euinvoice 0.1.0__tar.gz

euinvoice-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Biagio Distefano
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

euinvoice-0.1.0/PKG-INFO

@@ -0,0 +1,212 @@
+Metadata-Version: 2.4
+Name: euinvoice
+Version: 0.1.0
+Summary: EN 16931 e-invoicing for Python: build, serialize (UBL/CII), validate, parse and embed (Factur-X) European e-invoices.
+Keywords: e-invoicing,en16931,peppol,xrechnung,factur-x,zugferd,ubl,cii,einvoice
+Author: Biagio Distefano
+Author-email: Biagio Distefano <biagio@biagiodistefano.io>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Classifier: Topic :: Text Processing :: Markup :: XML
+Classifier: Typing :: Typed
+Requires-Dist: lxml>=5.3
+Requires-Dist: pydantic>=2.11
+Requires-Dist: pypdf>=6.1 ; extra == 'pdf'
+Requires-Dist: saxonche>=12.9,!=13.0.0 ; extra == 'validate'
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/letsrevel/euinvoice
+Project-URL: Issues, https://github.com/letsrevel/euinvoice/issues
+Project-URL: Changelog, https://github.com/letsrevel/euinvoice/blob/main/CHANGELOG.md
+Provides-Extra: pdf
+Provides-Extra: validate
+Description-Content-Type: text/markdown
+
+# euinvoice
+
+**EN 16931 e-invoicing for Python.** You can build European e-invoices as typed models, serialize them
+to **UBL** or **CII**, validate them against the **official** rule sets, parse them back, and embed them
+in **Factur-X / ZUGFeRD** PDFs.
+
+> **Status: 0.1.0, not yet released.** The API can still change before the release; see
+> [`CHANGELOG.md`](CHANGELOG.md) and the [known limitations](#known-limitations).
+
+## Why
+
+EU e-invoicing mandates are arriving country by country, and the reference tooling is mostly Java. euinvoice
+is a small, typed, MIT-licensed Python library with three principles:
+
+- **One semantic model.** The EN 16931 business terms form a frozen, `Decimal`-only Pydantic model. UBL and CII
+  are just two ways of writing it down.
+- **The official rules are the judge.** Validation runs the pinned official XSD and Schematron artifacts (CEN,
+  Peppol, KoSIT XRechnung) on SaxonC-HE, not a reimplementation that drifts after the next rule release.
+- **Framework-free and side-effect-free.** Bytes go in and bytes come out, with no Django, no network and no
+  file system in the core.
+
+## What 0.1.0 supports
+
+| Profile | Syntax | Generate | Parse | Validate |
+|---|---|---|---|---|
+| EN 16931 core | UBL 2.1, CII D16B | ✅ | ✅ | ✅ XSD + CEN |
+| Peppol BIS Billing 3.0 | UBL 2.1, CII D16B | ✅ | ✅ | ✅ XSD + CEN + Peppol |
+| XRechnung 3.0 (CIUS) | UBL 2.1, CII D16B | ✅ | ✅ | ✅ XSD + CEN + XRechnung |
+| XRechnung 3.0 Extension | UBL 2.1, CII D16B | ✅ EN 16931 content only | ✅ extension content listed as unmapped; content outside the CEN code lists (e.g. ICD `XR03`, testsuite `04.05a` CII) raises `ParseError` | ⚠️ raw flags ([#49](https://github.com/letsrevel/euinvoice/issues/49)) |
+| XRechnung 3.0 CVD | UBL 2.1, CII D16B | ❌ | ❌ conforming documents (BR-CL-13) | ⚠️ raw flags, see below |
+| Factur-X 1.0 / ZUGFeRD 2.1+ EN 16931, XRECHNUNG | CII in PDF/A-3 | ✅ | ✅ | ⚠️ EN 16931 / XRechnung rules only |
+| Factur-X 1.0 / ZUGFeRD 2.1+ BASIC, EXTENDED | CII in PDF/A-3 | ❌ | ✅ EXTENDED-only content listed as unmapped | ❌ |
+| Factur-X 1.0 / ZUGFeRD 2.1+ MINIMUM, BASIC WL | CII in PDF/A-3 | ❌ | ❌ detected and extracted only | ❌ |
+| ZUGFeRD 2.0 MINIMUM, BASIC, EXTENDED | CII in PDF/A-3 | ❌ | ✅ BASIC, EXTENDED (EXTENDED-only content listed as unmapped; corpus EXTENDED samples with codes outside the CEN lists, ABK BR-CL-19 and 9958 BR-CL-25, raise `ParseError` like their 2.1 twins, [#69](https://github.com/letsrevel/euinvoice/issues/69)); ❌ MINIMUM | ❌ |
+
+- **Parse** means read into the EN 16931 model. Readers never drop input silently: every element or attribute
+  without a business term is listed in `parse_detailed(...).unmapped`.
+- **Validate** reports the raw severities of the official rule sets. KoSIT's per-scenario severity overrides are
+  not applied ([#49](https://github.com/letsrevel/euinvoice/issues/49)): for example, 2 of the 6 official XRechnung Extension instances get fatal findings
+  that KoSIT downgrades.
+- **XRechnung CVD:** BR-DE-CVD-03 (fatal, `XRechnung-UBL-validation.sch` lines 560-562) needs an item
+  classification with list id `CVD`, which BR-CL-13 (fatal, CEN `EN16931-UBL-codes.sch` lines 67-68) and
+  therefore the model refuse. No *conforming* CVD invoice can be built or read. `validate()` rejects every CVD
+  document: BR-CL-13 when it carries the `CVD` item classification, BR-DE-CVD-03 (fatal) when it does not
+  (KoSIT downgrades BR-CL-13, [#49](https://github.com/letsrevel/euinvoice/issues/49)).
+- **Factur-X:** the rows above cover the Factur-X 1.0 / ZUGFeRD 2.1+ BT-24s. `facturx.embed` / `facturx.extract`
+  write and read the PDF container (the `[pdf]` extra). The
+  Factur-X XSD and Schematron are not pinned yet ([#42](https://github.com/letsrevel/euinvoice/issues/42)), so
+  `validate()` checks the embedded XML of the EN 16931 and XRECHNUNG levels against the EN 16931 / XRechnung
+  rules only, and raises `ArtifactsNotAvailableError` for MINIMUM, BASIC WL, BASIC and EXTENDED. MINIMUM and
+  BASIC WL carry no invoice lines, so they cannot become an `Invoice`: `parse()` raises `ParseError`
+  ([#69](https://github.com/letsrevel/euinvoice/issues/69)). The library does not check PDF/A-3 conformance
+  (the test suite runs veraPDF on `embed()` output). ZUGFeRD 2.0 PDFs are extract-only (not generated). Their
+  MINIMUM, BASIC and EXTENDED BT-24s (`urn:zugferd.de:2p0:*`) and the colon spellings of BASIC and EXTENDED
+  (`urn:cen.eu:en16931:2017:compliant:factur-x.eu:1p0:*`) are not registered as profiles, but `validate()` raises
+  `ArtifactsNotAvailableError` for them as for the levels above (CLI exit 2;
+  [#98](https://github.com/letsrevel/euinvoice/issues/98)). A ZUGFeRD 2.0 EN 16931 invoice carries the core BT-24
+  and is validated as EN 16931 core.
+  ZUGFeRD 1.0 PDFs are extract-only (`parse()` raises `UnsupportedDocumentError`).
+
+Planned later: ebInterface, more national CIUSes (RO, HR, FR, DK, …), FatturaPA, KSeF, Facturae, and
+clearance/transport integrations.
+
+## Install
+
+```bash
+uv add euinvoice                    # model + UBL/CII serialize/parse
+uv add 'euinvoice[validate]'        # + official Schematron validation (SaxonC-HE)
+uv add 'euinvoice[pdf]'             # + Factur-X / ZUGFeRD PDF embedding
+```
+
+Until 0.1.0 is on PyPI: `uv add 'euinvoice @ git+https://github.com/letsrevel/euinvoice'`.
+
+The official validation artifacts are **downloaded, not bundled**, because of their licences. Fetch them
+once (pinned and sha256-verified):
+
+```bash
+python -m euinvoice artifacts fetch   # cache: $EUINVOICE_ARTIFACTS_DIR or ~/.cache/euinvoice
+```
+
+## Usage
+
+`draft` is an `euinvoice.InvoiceDraft`: the invoice without its derived totals. These examples run as tests
+(`tests/_readme.py` builds the synthetic XRechnung draft they use); see the [quickstart](docs/quickstart.md) for
+building a draft.
+
+```python
+>>> from euinvoice import calc, detect, parse, parse_detailed, profiles, to_xml, validate
+>>> invoice = calc.complete(draft)  # derive line totals, document totals and the VAT breakdown (EN 16931)
+>>> xml = to_xml(invoice, profile=profiles.XRECHNUNG, syntax="cii")  # raises PreflightError on blocking findings
+>>> parse(xml) == profiles.XRECHNUNG.prepare(invoice)  # lossless; to_xml wrote the profile's BT-24 (prepare)
+True
+>>> parse_detailed(xml).unmapped  # XPaths of input with no business term; parse() discards them
+()
+>>> found = detect(xml)  # syntax and profile from the root element and BT-24
+>>> found.syntax, found.profile.id
+(<Syntax.CII: 'cii'>, 'xrechnung')
+```
+
+Validation needs the `[validate]` extra and the fetched artifacts. `validate()` takes XML; for a PDF, pass
+`facturx.extract(pdf).xml` or use the CLI.
+
+<!-- readme-doctest: needs-artifacts -->
+```python
+>>> report = validate(xml)  # profile auto-detected from BT-24
+>>> report.ok
+True
+>>> for finding in report.findings:
+...     print(finding.rule_id, finding.severity, finding.message)
+```
+
+Factur-X / ZUGFeRD needs the `[pdf]` extra:
+
+```python
+>>> from euinvoice import facturx
+>>> # your renderer produces the human-readable PDF/A-3 (e.g. WeasyPrint pdf_variant="pdf/a-3b")
+>>> hybrid_pdf = facturx.embed(rendered_pdf, invoice, profile=profiles.FACTURX_EN16931)
+>>> found = facturx.extract(hybrid_pdf)
+>>> found.filename, found.conformance_level, found.profile.id
+('factur-x.xml', 'EN 16931', 'facturx-en16931')
+>>> parse(hybrid_pdf) == profiles.FACTURX_EN16931.prepare(invoice)  # parse() reads PDFs too
+True
+```
+
+## Command line
+
+`python -m euinvoice` wraps the same functions. `FILE` is UBL, CII or a Factur-X / ZUGFeRD PDF (`-` reads
+stdin), and `--profile` takes a profile id such as `xrechnung` or `peppol`.
+
+```bash
+python -m euinvoice validate invoice.xml [--profile ID] [--json]   # one line per finding, then the verdict
+python -m euinvoice convert invoice.xml --to ubl|cii [--profile ID] [-o OUT]
+python -m euinvoice info invoice.pdf [--json]                      # syntax, BT-24, profile, container, totals
+python -m euinvoice artifacts fetch [--only NAME]
+```
+
+Exit codes: `0` success (warnings allowed); `1` the document was rejected (a `fatal` or `error` finding, a
+refused conversion, an unreadable invoice) or an artifact failed its integrity check; `2` no verdict (usage
+error, unknown profile, unreadable file, failed download, missing artifacts or extras, a Factur-X level whose
+rules are not pinned). `--help` on each subcommand lists them.
+
+## Documentation
+
+The [`docs/`](docs/index.md) folder holds the guide: [quickstart](docs/quickstart.md),
+[concepts](docs/concepts.md), [validation](docs/validation.md), [Factur-X](docs/facturx.md), a
+[mapping guide](docs/mapping/index.md) with synthetic freelancer and ticketing examples, and the
+[BT mapping](docs/reference/bt-mapping.md). It builds with `make docs` (mkdocs-material). The GitHub Pages site goes live
+once the maintainer enables Pages for the repository and sets the repository variable `DOCS_DEPLOY=true`.
+
+## Known limitations
+
+Open questions waiting for a maintainer decision (`needs-human`):
+
+- [#42](https://github.com/letsrevel/euinvoice/issues/42): the Factur-X / ZUGFeRD XSD and Schematron have no
+  pinnable official download, so Factur-X levels are not validated against Factur-X rules (see above).
+- [#69](https://github.com/letsrevel/euinvoice/issues/69): Factur-X MINIMUM and BASIC WL cannot be read into the
+  model.
+- [#49](https://github.com/letsrevel/euinvoice/issues/49): KoSIT's XRechnung severity overrides are not applied,
+  so the verdict can differ from the KoSIT validator in both directions (e.g. BR-CL-21/23, XRechnung Extension
+  and CVD).
+- [#67](https://github.com/letsrevel/euinvoice/issues/67): the XRechnung profiles set no default BT-23; the caller
+  must provide it (the pre-flight reports PEPPOL-EN16931-R001 otherwise).
+- [#40](https://github.com/letsrevel/euinvoice/issues/40): the hardened parser rejects a single text node over
+  10,000,000 bytes, i.e. a BT-125 attachment over about 7.5 MB.
+
+## Development
+
+```bash
+make setup        # uv sync --all-extras --group dev
+make check        # ruff + mypy --strict + file length
+make test         # unit tests, ≥95% branch coverage
+make artifacts    # fetch official artifacts + corpora
+make conformance  # run them
+```
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md). Security reports: [`SECURITY.md`](SECURITY.md).
+
+## Licence
+
+MIT. Official validation artifacts are third-party works under their own licences (EUPL-1.2,
+Apache-2.0 and others). They are fetched at runtime and never redistributed by this package.

euinvoice-0.1.0/README.md

@@ -0,0 +1,181 @@
+# euinvoice
+
+**EN 16931 e-invoicing for Python.** You can build European e-invoices as typed models, serialize them
+to **UBL** or **CII**, validate them against the **official** rule sets, parse them back, and embed them
+in **Factur-X / ZUGFeRD** PDFs.
+
+> **Status: 0.1.0, not yet released.** The API can still change before the release; see
+> [`CHANGELOG.md`](CHANGELOG.md) and the [known limitations](#known-limitations).
+
+## Why
+
+EU e-invoicing mandates are arriving country by country, and the reference tooling is mostly Java. euinvoice
+is a small, typed, MIT-licensed Python library with three principles:
+
+- **One semantic model.** The EN 16931 business terms form a frozen, `Decimal`-only Pydantic model. UBL and CII
+  are just two ways of writing it down.
+- **The official rules are the judge.** Validation runs the pinned official XSD and Schematron artifacts (CEN,
+  Peppol, KoSIT XRechnung) on SaxonC-HE, not a reimplementation that drifts after the next rule release.
+- **Framework-free and side-effect-free.** Bytes go in and bytes come out, with no Django, no network and no
+  file system in the core.
+
+## What 0.1.0 supports
+
+| Profile | Syntax | Generate | Parse | Validate |
+|---|---|---|---|---|
+| EN 16931 core | UBL 2.1, CII D16B | ✅ | ✅ | ✅ XSD + CEN |
+| Peppol BIS Billing 3.0 | UBL 2.1, CII D16B | ✅ | ✅ | ✅ XSD + CEN + Peppol |
+| XRechnung 3.0 (CIUS) | UBL 2.1, CII D16B | ✅ | ✅ | ✅ XSD + CEN + XRechnung |
+| XRechnung 3.0 Extension | UBL 2.1, CII D16B | ✅ EN 16931 content only | ✅ extension content listed as unmapped; content outside the CEN code lists (e.g. ICD `XR03`, testsuite `04.05a` CII) raises `ParseError` | ⚠️ raw flags ([#49](https://github.com/letsrevel/euinvoice/issues/49)) |
+| XRechnung 3.0 CVD | UBL 2.1, CII D16B | ❌ | ❌ conforming documents (BR-CL-13) | ⚠️ raw flags, see below |
+| Factur-X 1.0 / ZUGFeRD 2.1+ EN 16931, XRECHNUNG | CII in PDF/A-3 | ✅ | ✅ | ⚠️ EN 16931 / XRechnung rules only |
+| Factur-X 1.0 / ZUGFeRD 2.1+ BASIC, EXTENDED | CII in PDF/A-3 | ❌ | ✅ EXTENDED-only content listed as unmapped | ❌ |
+| Factur-X 1.0 / ZUGFeRD 2.1+ MINIMUM, BASIC WL | CII in PDF/A-3 | ❌ | ❌ detected and extracted only | ❌ |
+| ZUGFeRD 2.0 MINIMUM, BASIC, EXTENDED | CII in PDF/A-3 | ❌ | ✅ BASIC, EXTENDED (EXTENDED-only content listed as unmapped; corpus EXTENDED samples with codes outside the CEN lists, ABK BR-CL-19 and 9958 BR-CL-25, raise `ParseError` like their 2.1 twins, [#69](https://github.com/letsrevel/euinvoice/issues/69)); ❌ MINIMUM | ❌ |
+
+- **Parse** means read into the EN 16931 model. Readers never drop input silently: every element or attribute
+  without a business term is listed in `parse_detailed(...).unmapped`.
+- **Validate** reports the raw severities of the official rule sets. KoSIT's per-scenario severity overrides are
+  not applied ([#49](https://github.com/letsrevel/euinvoice/issues/49)): for example, 2 of the 6 official XRechnung Extension instances get fatal findings
+  that KoSIT downgrades.
+- **XRechnung CVD:** BR-DE-CVD-03 (fatal, `XRechnung-UBL-validation.sch` lines 560-562) needs an item
+  classification with list id `CVD`, which BR-CL-13 (fatal, CEN `EN16931-UBL-codes.sch` lines 67-68) and
+  therefore the model refuse. No *conforming* CVD invoice can be built or read. `validate()` rejects every CVD
+  document: BR-CL-13 when it carries the `CVD` item classification, BR-DE-CVD-03 (fatal) when it does not
+  (KoSIT downgrades BR-CL-13, [#49](https://github.com/letsrevel/euinvoice/issues/49)).
+- **Factur-X:** the rows above cover the Factur-X 1.0 / ZUGFeRD 2.1+ BT-24s. `facturx.embed` / `facturx.extract`
+  write and read the PDF container (the `[pdf]` extra). The
+  Factur-X XSD and Schematron are not pinned yet ([#42](https://github.com/letsrevel/euinvoice/issues/42)), so
+  `validate()` checks the embedded XML of the EN 16931 and XRECHNUNG levels against the EN 16931 / XRechnung
+  rules only, and raises `ArtifactsNotAvailableError` for MINIMUM, BASIC WL, BASIC and EXTENDED. MINIMUM and
+  BASIC WL carry no invoice lines, so they cannot become an `Invoice`: `parse()` raises `ParseError`
+  ([#69](https://github.com/letsrevel/euinvoice/issues/69)). The library does not check PDF/A-3 conformance
+  (the test suite runs veraPDF on `embed()` output). ZUGFeRD 2.0 PDFs are extract-only (not generated). Their
+  MINIMUM, BASIC and EXTENDED BT-24s (`urn:zugferd.de:2p0:*`) and the colon spellings of BASIC and EXTENDED
+  (`urn:cen.eu:en16931:2017:compliant:factur-x.eu:1p0:*`) are not registered as profiles, but `validate()` raises
+  `ArtifactsNotAvailableError` for them as for the levels above (CLI exit 2;
+  [#98](https://github.com/letsrevel/euinvoice/issues/98)). A ZUGFeRD 2.0 EN 16931 invoice carries the core BT-24
+  and is validated as EN 16931 core.
+  ZUGFeRD 1.0 PDFs are extract-only (`parse()` raises `UnsupportedDocumentError`).
+
+Planned later: ebInterface, more national CIUSes (RO, HR, FR, DK, …), FatturaPA, KSeF, Facturae, and
+clearance/transport integrations.
+
+## Install
+
+```bash
+uv add euinvoice                    # model + UBL/CII serialize/parse
+uv add 'euinvoice[validate]'        # + official Schematron validation (SaxonC-HE)
+uv add 'euinvoice[pdf]'             # + Factur-X / ZUGFeRD PDF embedding
+```
+
+Until 0.1.0 is on PyPI: `uv add 'euinvoice @ git+https://github.com/letsrevel/euinvoice'`.
+
+The official validation artifacts are **downloaded, not bundled**, because of their licences. Fetch them
+once (pinned and sha256-verified):
+
+```bash
+python -m euinvoice artifacts fetch   # cache: $EUINVOICE_ARTIFACTS_DIR or ~/.cache/euinvoice
+```
+
+## Usage
+
+`draft` is an `euinvoice.InvoiceDraft`: the invoice without its derived totals. These examples run as tests
+(`tests/_readme.py` builds the synthetic XRechnung draft they use); see the [quickstart](docs/quickstart.md) for
+building a draft.
+
+```python
+>>> from euinvoice import calc, detect, parse, parse_detailed, profiles, to_xml, validate
+>>> invoice = calc.complete(draft)  # derive line totals, document totals and the VAT breakdown (EN 16931)
+>>> xml = to_xml(invoice, profile=profiles.XRECHNUNG, syntax="cii")  # raises PreflightError on blocking findings
+>>> parse(xml) == profiles.XRECHNUNG.prepare(invoice)  # lossless; to_xml wrote the profile's BT-24 (prepare)
+True
+>>> parse_detailed(xml).unmapped  # XPaths of input with no business term; parse() discards them
+()
+>>> found = detect(xml)  # syntax and profile from the root element and BT-24
+>>> found.syntax, found.profile.id
+(<Syntax.CII: 'cii'>, 'xrechnung')
+```
+
+Validation needs the `[validate]` extra and the fetched artifacts. `validate()` takes XML; for a PDF, pass
+`facturx.extract(pdf).xml` or use the CLI.
+
+<!-- readme-doctest: needs-artifacts -->
+```python
+>>> report = validate(xml)  # profile auto-detected from BT-24
+>>> report.ok
+True
+>>> for finding in report.findings:
+...     print(finding.rule_id, finding.severity, finding.message)
+```
+
+Factur-X / ZUGFeRD needs the `[pdf]` extra:
+
+```python
+>>> from euinvoice import facturx
+>>> # your renderer produces the human-readable PDF/A-3 (e.g. WeasyPrint pdf_variant="pdf/a-3b")
+>>> hybrid_pdf = facturx.embed(rendered_pdf, invoice, profile=profiles.FACTURX_EN16931)
+>>> found = facturx.extract(hybrid_pdf)
+>>> found.filename, found.conformance_level, found.profile.id
+('factur-x.xml', 'EN 16931', 'facturx-en16931')
+>>> parse(hybrid_pdf) == profiles.FACTURX_EN16931.prepare(invoice)  # parse() reads PDFs too
+True
+```
+
+## Command line
+
+`python -m euinvoice` wraps the same functions. `FILE` is UBL, CII or a Factur-X / ZUGFeRD PDF (`-` reads
+stdin), and `--profile` takes a profile id such as `xrechnung` or `peppol`.
+
+```bash
+python -m euinvoice validate invoice.xml [--profile ID] [--json]   # one line per finding, then the verdict
+python -m euinvoice convert invoice.xml --to ubl|cii [--profile ID] [-o OUT]
+python -m euinvoice info invoice.pdf [--json]                      # syntax, BT-24, profile, container, totals
+python -m euinvoice artifacts fetch [--only NAME]
+```
+
+Exit codes: `0` success (warnings allowed); `1` the document was rejected (a `fatal` or `error` finding, a
+refused conversion, an unreadable invoice) or an artifact failed its integrity check; `2` no verdict (usage
+error, unknown profile, unreadable file, failed download, missing artifacts or extras, a Factur-X level whose
+rules are not pinned). `--help` on each subcommand lists them.
+
+## Documentation
+
+The [`docs/`](docs/index.md) folder holds the guide: [quickstart](docs/quickstart.md),
+[concepts](docs/concepts.md), [validation](docs/validation.md), [Factur-X](docs/facturx.md), a
+[mapping guide](docs/mapping/index.md) with synthetic freelancer and ticketing examples, and the
+[BT mapping](docs/reference/bt-mapping.md). It builds with `make docs` (mkdocs-material). The GitHub Pages site goes live
+once the maintainer enables Pages for the repository and sets the repository variable `DOCS_DEPLOY=true`.
+
+## Known limitations
+
+Open questions waiting for a maintainer decision (`needs-human`):
+
+- [#42](https://github.com/letsrevel/euinvoice/issues/42): the Factur-X / ZUGFeRD XSD and Schematron have no
+  pinnable official download, so Factur-X levels are not validated against Factur-X rules (see above).
+- [#69](https://github.com/letsrevel/euinvoice/issues/69): Factur-X MINIMUM and BASIC WL cannot be read into the
+  model.
+- [#49](https://github.com/letsrevel/euinvoice/issues/49): KoSIT's XRechnung severity overrides are not applied,
+  so the verdict can differ from the KoSIT validator in both directions (e.g. BR-CL-21/23, XRechnung Extension
+  and CVD).
+- [#67](https://github.com/letsrevel/euinvoice/issues/67): the XRechnung profiles set no default BT-23; the caller
+  must provide it (the pre-flight reports PEPPOL-EN16931-R001 otherwise).
+- [#40](https://github.com/letsrevel/euinvoice/issues/40): the hardened parser rejects a single text node over
+  10,000,000 bytes, i.e. a BT-125 attachment over about 7.5 MB.
+
+## Development
+
+```bash
+make setup        # uv sync --all-extras --group dev
+make check        # ruff + mypy --strict + file length
+make test         # unit tests, ≥95% branch coverage
+make artifacts    # fetch official artifacts + corpora
+make conformance  # run them
+```
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md). Security reports: [`SECURITY.md`](SECURITY.md).
+
+## Licence
+
+MIT. Official validation artifacts are third-party works under their own licences (EUPL-1.2,
+Apache-2.0 and others). They are fetched at runtime and never redistributed by this package.

euinvoice-0.1.0/pyproject.toml

@@ -0,0 +1,138 @@
+[project]
+name = "euinvoice"
+version = "0.1.0"
+description = "EN 16931 e-invoicing for Python: build, serialize (UBL/CII), validate, parse and embed (Factur-X) European e-invoices."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Biagio Distefano", email = "biagio@biagiodistefano.io" }
+]
+keywords = ["e-invoicing", "en16931", "peppol", "xrechnung", "factur-x", "zugferd", "ubl", "cii", "einvoice"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Office/Business :: Financial :: Accounting",
+    "Topic :: Text Processing :: Markup :: XML",
+    "Typing :: Typed",
+]
+requires-python = ">=3.12"
+dependencies = [
+    "lxml>=5.3",
+    "pydantic>=2.11",
+]
+
+[project.optional-dependencies]
+# Official Schematron validation (XSLT 3.0). SaxonC-HE is MPL-2.0.
+validate = [
+    "saxonche>=12.9,!=13.0.0",
+]
+# Factur-X / ZUGFeRD PDF/A-3 embedding and extraction.
+pdf = [
+    "pypdf>=6.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/letsrevel/euinvoice"
+Issues = "https://github.com/letsrevel/euinvoice/issues"
+Changelog = "https://github.com/letsrevel/euinvoice/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["uv_build>=0.11.8,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "hypothesis>=6.168.4",
+    "licensecheck>=2026.0.8",
+    "lxml-stubs>=0.5.1",
+    "mkdocs-material>=9.7.7",
+    "mkdocstrings[python]>=1.0.6",
+    "mypy>=2.4.0",
+    "pip-audit>=2.10.1",
+    "pytest>=9.1.1",
+    "pytest-cov>=7.1.0",
+    "pytest-xdist>=3.8.0",
+    "ruff>=0.16.10",
+]
+
+[tool.ruff]
+line-length = 120
+target-version = "py312"
+src = ["src", "tests", "scripts"]
+
+[tool.ruff.lint]
+preview = true
+# Compared to revel-backend: adds bugbear (B), comprehensions (C4), naming (N), pytest style (PT),
+# pyupgrade (UP), simplify (SIM), ruff-specific (RUF), and flake8-bandit (S), which replaces the
+# separate bandit run. Security rules that matter most here (hardened XML parsing) are enforced
+# by tests, see CLAUDE.md.
+select = ["B", "C4", "C90", "D", "E", "F", "I", "N", "import-private-name", "too-many-nested-blocks", "PT", "RUF", "S", "SIM", "T20", "UP", "W"]
+ignore = ["undocumented-public-module", "undocumented-public-package", "undocumented-magic-method", "undocumented-public-init"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["D", "assert", "import-private-name"]
+"scripts/**" = ["print"]
+# The Syntax enum lives in the package root (IMPLEMENTATION_PLAN.md §4: "Syntax enum {UBL, CII}").
+"src/euinvoice/syntax/__init__.py" = ["non-empty-init-module"]
+# The lazy ``facturx`` __getattr__ sits under ``if not TYPE_CHECKING`` so mypy users still get attribute errors (#27).
+"src/euinvoice/__init__.py" = ["non-empty-init-module"]
+# One row per business term (keyed by BT id for the coverage gate #32): long XPaths, kept one row per line.
+"tests/syntax/test_*_write_bts.py" = ["line-too-long"]
+
+[tool.ruff.lint.mccabe]
+max-complexity = 10
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.pylint]
+max-nested-blocks = 4
+
+[tool.mypy]
+strict = true
+extra_checks = true
+warn_unreachable = true
+warn_unused_ignores = true
+plugins = ["pydantic.mypy"]
+files = ["src", "tests", "scripts"]
+
+[[tool.mypy.overrides]]
+# saxonche ships no type information.
+module = "saxonche.*"
+ignore_missing_imports = true
+
+[tool.pydantic-mypy]
+init_typed = true
+init_forbid_extra = true
+warn_required_dynamic_aliases = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# Dev scripts in scripts/ are importable from tests (tests/scripts/test_<name>.py).
+pythonpath = ["scripts", "tests"]
+addopts = "-ra --strict-markers --strict-config -m 'not conformance'"
+xfail_strict = true
+markers = [
+    "conformance: runs the official validation artifacts and upstream example corpora (needs `make artifacts`); run with `make conformance`",
+]
+filterwarnings = ["error"]
+
+[tool.coverage.run]
+branch = true
+source = ["euinvoice"]
+
+[tool.coverage.report]
+fail_under = 95
+show_missing = true
+skip_covered = true
+exclude_also = [
+    "if t.TYPE_CHECKING:",
+    "raise NotImplementedError",
+    "@t.overload",
+]

euinvoice-0.1.0/src/euinvoice/__init__.py

@@ -0,0 +1,64 @@
+"""EN 16931 e-invoicing: build, serialize (UBL/CII), validate, parse and embed (Factur-X) European e-invoices.
+
+The public API (plan §4): :func:`to_xml`, :func:`parse`, :func:`parse_detailed`, :func:`validate` and
+:func:`detect`, the :class:`Invoice` / :class:`InvoiceDraft` models and the ``calc``, ``profiles`` and
+``facturx`` subpackages. ``facturx`` needs the ``[pdf]`` extra and is imported on first access
+(``euinvoice.facturx`` or ``from euinvoice import facturx``); it is not in ``__all__``, so ``from euinvoice import *``
+works without pypdf. ``import euinvoice`` loads neither pypdf nor saxonche (the ``[validate]`` extra, loaded when
+validating).
+
+The functions :func:`detect` and :func:`validate` live in the modules ``euinvoice.detection`` and
+``euinvoice.validation`` (renamed in #93 so the functions shadow no module).
+"""
+
+import importlib
+import typing as t
+from importlib.metadata import version
+
+from euinvoice import calc, profiles
+from euinvoice._api import parse, parse_detailed, to_xml
+from euinvoice.detection import detect
+from euinvoice.model import Invoice, InvoiceDraft
+from euinvoice.report import ValidationReport
+from euinvoice.syntax import Syntax
+from euinvoice.syntax.result import ParseResult
+from euinvoice.validation import validate
+
+if t.TYPE_CHECKING:
+    # The redundant alias marks an explicit re-export, so ruff does not add ``facturx`` to ``__all__`` (which would
+    # make ``from euinvoice import *`` need pypdf).
+    from euinvoice import facturx as facturx
+
+__version__ = version("euinvoice")
+
+__all__ = [
+    "Invoice",
+    "InvoiceDraft",
+    "ParseResult",
+    "Syntax",
+    "ValidationReport",
+    "__version__",
+    "calc",
+    "detect",
+    "parse",
+    "parse_detailed",
+    "profiles",
+    "to_xml",
+    "validate",
+]
+
+
+# Hidden from type checkers so that a typo such as ``euinvoice.facturxx`` is a mypy error, not ``Any``; the
+# ``TYPE_CHECKING`` import above gives them ``facturx``.
+if not t.TYPE_CHECKING:
+
+    def __getattr__(name: str) -> t.Any:
+        """Import ``euinvoice.facturx`` on first access (it needs the ``[pdf]`` extra).
+
+        Raises:
+            AttributeError: ``name`` is not a lazily imported subpackage.
+            ImportError: ``name`` is ``"facturx"`` and pypdf is not installed; the message names the extra.
+        """
+        if name == "facturx":
+            return importlib.import_module("euinvoice.facturx")
+        raise AttributeError(f"module 'euinvoice' has no attribute {name!r}")