# PyCheval – Factur-X/ZUGFeRD parsing and generation library for Python
[](https://github.com/zfutura/pycheval/releases/)
[](https://github.com/zfutura/pycheval/blob/main/LICENSE)
[](https://github.com/zfutura/pycheval/actions/workflows/test-and-lint)
Factur-X (also called ZUGFeRD in Germany) is a Franco-German standard for
electronic invoices. Structured XML data is embedded in PDF-A/3 files,
allowing invoices to be processed automatically while still being displayed in
standard PDF readers. Factur-X supports EN 16931, the European standard for
electronic invoicing.
See the [Factur-X website (French)](https://www.factur-x.org/) or
[FeRD website (German)](https://www.ferd-net.de/) for more information.
This library supports reading and writing PDF and XML files according to
Factur-X Version 1.07.3 (aka ZUGFeRD 2.3.3). The following Factur-X profiles
are currently supported:
- Minimum
- Basic WL
- Basic
- EN 16931 (Comfort)
Extended and XRechnung profiles are not yet supported.
**Warning**: This library is still in early development. The API may change
frequently, and not all features are implemented yet.
## Usage
### Installation
You can install PyCheval from PyPI:
```bash
pip install PyCheval
```
### Generating Factur-X
PyCheval supports several Factur-X profile levels, each with different levels of detail and complexity. First, you need to create an instance of the appropriate profile class. Then, you can pass that instance to one of the generation functions.
```python
from datetime import date
from pycheval import EN16931Invoice, Money, generate_xml
invoice = EN16931Invoice(
invoice_number="2021-123",
invoice_date=date(2021, 4, 13),
grand_total=Money("100.00", "EUR"),
... # See the class documentation for all required and optional fields.
)
xml_string = generate_xml(invoice)
```
To embed the generated XML into a PDF, you can use the `embed_invoice_in_pdf` function:
```python
from pathlib import Path
from pycheval import embed_invoice_in_pdf
invoice = ...
pdf_bytes = embed_invoice_in_pdf("invoice.pdf", invoice)
Path("invoice_with_facturx.pdf").write_bytes(pdf_bytes)
```
### Parsing Factur-X PDF files
PyCheval can parse Factur-X PDF files and extract the embedded invoice data. The parser will return an instance of the appropriate profile class.
```python
from pycheval import parse_pdf
invoice = parse_pdf("invoice.pdf") # Returns MinimumInvoice or a subclass
```
### Printing invoices
To display a formatted Factur-X invoice in the terminal, use the `format_invoice_as_text()` function:
```python
from pycheval import format_invoice_as_text
invoice = EN16931Invoice(...)
print(format_invoice_as_text(invoice))
```
### License and Warranty
**Copyright © ZFutura GmbH**
This project is licensed under the [Apache License 2.0](LICENSE).
**Disclaimer**: The software is provided "as is", without warranty of any kind.
The authors are not liable for any damages arising from the use of this
software. In particular, the authors do not guarantee that invoices generated
or parsed by this library will be valid or compliant with any standards, nor
that they are suitable for any specific purpose.
**Important**: It is the user's responsibility to ensure that generated
invoices meet all legal and regulatory requirements for their jurisdiction.
See the [LICENSE](LICENSE) file for the complete disclaimer and license terms.
Raw data
{
"_id": null,
"home_page": null,
"name": "PyCheval",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "factur-x, zugferd, invoice, billing",
"author": "Sebastian Rittau",
"author_email": "sebastian.rittau@zfutura.de",
"download_url": "https://files.pythonhosted.org/packages/51/75/588cb392ce9ceaab5a0585e3c3963ade3865627b198b5c2ad56ddf3fc76a/pycheval-0.2.0.tar.gz",
"platform": null,
"description": "# PyCheval \u2013 Factur-X/ZUGFeRD parsing and generation library for Python\n\n[](https://github.com/zfutura/pycheval/releases/)\n\n[](https://github.com/zfutura/pycheval/blob/main/LICENSE)\n[](https://github.com/zfutura/pycheval/actions/workflows/test-and-lint)\n\nFactur-X (also called ZUGFeRD in Germany) is a Franco-German standard for\nelectronic invoices. Structured XML data is embedded in PDF-A/3 files,\nallowing invoices to be processed automatically while still being displayed in\nstandard PDF readers. Factur-X supports EN 16931, the European standard for\nelectronic invoicing.\n\nSee the [Factur-X website (French)](https://www.factur-x.org/) or\n[FeRD website (German)](https://www.ferd-net.de/) for more information.\n\nThis library supports reading and writing PDF and XML files according to\nFactur-X Version 1.07.3 (aka ZUGFeRD 2.3.3). The following Factur-X profiles\nare currently supported:\n\n- Minimum\n- Basic WL\n- Basic\n- EN 16931 (Comfort)\n\nExtended and XRechnung profiles are not yet supported.\n\n**Warning**: This library is still in early development. The API may change\nfrequently, and not all features are implemented yet.\n\n## Usage\n\n### Installation\n\nYou can install PyCheval from PyPI:\n\n```bash\npip install PyCheval\n```\n\n### Generating Factur-X\n\nPyCheval supports several Factur-X profile levels, each with different levels of detail and complexity. First, you need to create an instance of the appropriate profile class. Then, you can pass that instance to one of the generation functions.\n\n```python\nfrom datetime import date\nfrom pycheval import EN16931Invoice, Money, generate_xml\n\ninvoice = EN16931Invoice(\n invoice_number=\"2021-123\",\n invoice_date=date(2021, 4, 13),\n grand_total=Money(\"100.00\", \"EUR\"),\n ... # See the class documentation for all required and optional fields.\n)\nxml_string = generate_xml(invoice)\n```\n\nTo embed the generated XML into a PDF, you can use the `embed_invoice_in_pdf` function:\n\n```python\nfrom pathlib import Path\nfrom pycheval import embed_invoice_in_pdf\n\ninvoice = ...\npdf_bytes = embed_invoice_in_pdf(\"invoice.pdf\", invoice)\nPath(\"invoice_with_facturx.pdf\").write_bytes(pdf_bytes)\n```\n\n### Parsing Factur-X PDF files\n\nPyCheval can parse Factur-X PDF files and extract the embedded invoice data. The parser will return an instance of the appropriate profile class.\n\n```python\nfrom pycheval import parse_pdf\n\ninvoice = parse_pdf(\"invoice.pdf\") # Returns MinimumInvoice or a subclass\n```\n\n### Printing invoices\n\nTo display a formatted Factur-X invoice in the terminal, use the `format_invoice_as_text()` function:\n\n```python\nfrom pycheval import format_invoice_as_text\n\ninvoice = EN16931Invoice(...)\nprint(format_invoice_as_text(invoice))\n```\n\n### License and Warranty\n\n**Copyright \u00a9 ZFutura GmbH**\n\nThis project is licensed under the [Apache License 2.0](LICENSE).\n\n**Disclaimer**: The software is provided \"as is\", without warranty of any kind. \nThe authors are not liable for any damages arising from the use of this\nsoftware. In particular, the authors do not guarantee that invoices generated\nor parsed by this library will be valid or compliant with any standards, nor\nthat they are suitable for any specific purpose. \n\n**Important**: It is the user's responsibility to ensure that generated\ninvoices meet all legal and regulatory requirements for their jurisdiction.\n\nSee the [LICENSE](LICENSE) file for the complete disclaimer and license terms.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Factur-X/ZUGFeRD parsing and generation library for Python",
"version": "0.2.0",
"project_urls": {
"GitHub": "https://github.com/zfutura/pycheval"
},
"split_keywords": [
"factur-x",
" zugferd",
" invoice",
" billing"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0c51174e521ef0d41511582906caa3f7ca7db79e0bde77576dbfa778ea801a88",
"md5": "6846212cd80a1a6893d700c58033625e",
"sha256": "0aacfa1cb6ca55c8f126e506546e6c3ff7f931d424152fe87970aee63f770f75"
},
"downloads": -1,
"filename": "pycheval-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6846212cd80a1a6893d700c58033625e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 52552,
"upload_time": "2025-07-26T17:31:26",
"upload_time_iso_8601": "2025-07-26T17:31:26.741733Z",
"url": "https://files.pythonhosted.org/packages/0c/51/174e521ef0d41511582906caa3f7ca7db79e0bde77576dbfa778ea801a88/pycheval-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5175588cb392ce9ceaab5a0585e3c3963ade3865627b198b5c2ad56ddf3fc76a",
"md5": "cbc89f6d456adff9fea4b17238ba82a2",
"sha256": "faff1e51620bbc4f7c0a69c76191f5f96150c72bb04cf6ef12f8f3991917bc75"
},
"downloads": -1,
"filename": "pycheval-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "cbc89f6d456adff9fea4b17238ba82a2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 46388,
"upload_time": "2025-07-26T17:31:27",
"upload_time_iso_8601": "2025-07-26T17:31:27.994260Z",
"url": "https://files.pythonhosted.org/packages/51/75/588cb392ce9ceaab5a0585e3c3963ade3865627b198b5c2ad56ddf3fc76a/pycheval-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-26 17:31:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "zfutura",
"github_project": "pycheval",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pycheval"
}
JSON
