PyCheval 0.1.0__tar.gz → 0.2.0__tar.gz

pycheval-0.2.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.3
+Name: PyCheval
+Version: 0.2.0
+Summary: Factur-X/ZUGFeRD parsing and generation library for Python
+License: Apache-2.0
+Keywords: factur-x,zugferd,invoice,billing
+Author: Sebastian Rittau
+Author-email: sebastian.rittau@zfutura.de
+Requires-Python: >= 3.11
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: File Formats
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Requires-Dist: pypdf (>=5.4.0,<6)
+Project-URL: GitHub, https://github.com/zfutura/pycheval
+Description-Content-Type: text/markdown
+
+# PyCheval – Factur-X/ZUGFeRD parsing and generation library for Python
+
+[![GitHub](https://img.shields.io/github/release/zfutura/pycheval/all.svg)](https://github.com/zfutura/pycheval/releases/)
+![Supported Python Versions](https://img.shields.io/pypi/pyversions/pycheval)
+[![Apache 2.0 License](https://img.shields.io/github/license/zfutura/pycheval)](https://github.com/zfutura/pycheval/blob/main/LICENSE)
+[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/zfutura/pycheval/test-and-lint.yml)](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.
+

pycheval-0.2.0/README.md

@@ -0,0 +1,105 @@
+# PyCheval – Factur-X/ZUGFeRD parsing and generation library for Python
+
+[![GitHub](https://img.shields.io/github/release/zfutura/pycheval/all.svg)](https://github.com/zfutura/pycheval/releases/)
+![Supported Python Versions](https://img.shields.io/pypi/pyversions/pycheval)
+[![Apache 2.0 License](https://img.shields.io/github/license/zfutura/pycheval)](https://github.com/zfutura/pycheval/blob/main/LICENSE)
+[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/zfutura/pycheval/test-and-lint.yml)](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.

pycheval-0.2.0/pyproject.toml

@@ -0,0 +1,77 @@
+[project]
+name = "PyCheval"
+version = "0.2.0"
+description = "Factur-X/ZUGFeRD parsing and generation library for Python"
+authors = [{ name = "Sebastian Rittau", email = "sebastian.rittau@zfutura.de" }]
+readme = "README.md"
+license = "Apache-2.0"
+keywords = ["factur-x", "zugferd", "invoice", "billing"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Topic :: File Formats",
+    "Topic :: Office/Business :: Financial :: Accounting",
+]
+requires-python = ">= 3.11"
+dependencies = [
+    "pypdf >= 5.4.0, < 6",
+]
+
+[project.urls]
+GitHub = "https://github.com/zfutura/pycheval"
+
+[tool.poetry]
+include = [{ path = "src/pycheval/locale/**/*.mo", format = ["sdist", "wheel"] }]
+exclude = ["src/pycheval/test_*"]
+
+[tool.poetry.group.dev.dependencies]
+babel = "~=2.17.0"
+mypy = "~=1.17.0"
+poethepoet = "^0.36.0"
+pytest = "^8.4.1"
+ruff = "^0.12.1"
+
+[tool.poe.tasks.lint]
+cmd = "ruff check src"
+help = "Lint the source code with ruff"
+
+[tool.poe.tasks.test]
+cmd = "pytest src"
+help = "Run unit and integration tests with pytest"
+
+[tool.poe.tasks.typecheck]
+cmd = "mypy src"
+help = "Type check the source code with mypy"
+
+[tool.poe.tasks.i18n-extract]
+cmd = "pybabel extract -o messages.pot src"
+help = "Extract messages for translation"
+
+[tool.poe.tasks.i18n-init]
+cmd = "pybabel init -D pycheval -i messages.pot -d src/pycheval/locale -l "
+help = "Initialize translation files for a new language"
+
+[tool.poe.tasks.i18n-update]
+cmd = "pybabel update -D pycheval -i messages.pot -d src/pycheval/locale"
+help = "Update translation files from the template"
+
+[tool.poe.tasks.i18n-compile]
+cmd = "pybabel compile -D pycheval -d src/pycheval/locale"
+help = "Compile translation files"
+
+[tool.ruff]
+target-version = "py312"
+line-length = 79
+
+[tool.ruff.lint]
+select = ["E", "F", "B", "I"]
+
+[tool.ruff.lint.isort]
+combine-as-imports = true
+
+[tool.mypy]
+strict = true
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

{pycheval-0.1.0 → pycheval-0.2.0}/src/pycheval/__init__.py

@@ -3,12 +3,17 @@ from typing import Final
 from .exc import *  # noqa: F403
 from .format import format_invoice_as_text as format_invoice_as_text
 from .generate import (
-    generate as generate,
     generate_et as generate_et,
+    generate_xml as generate_xml,
 )
 from .model import *  # noqa: F403
 from .money import Money as Money
 from .parse import parse_xml as parse_xml
+from .pdf_common import FileRelationship as FileRelationship
+from .pdf_embed import (
+    embed_facturx_file_in_pdf as embed_facturx_file_in_pdf,
+    embed_invoice_in_pdf as embed_invoice_in_pdf,
+)
 from .pdf_parse import parse_pdf as parse_pdf
 
 FACTURX_VERSION: Final = "1.0.07"

pycheval-0.2.0/src/pycheval/_test_data.py

@@ -0,0 +1,176 @@
+import datetime
+from decimal import Decimal
+from typing import Final
+
+from .model import (
+    EN16931Invoice,
+    EN16931LineItem,
+    IncludedNote,
+    LineAllowance,
+    LineCharge,
+    LineItem,
+    PaymentMeans,
+    PaymentTerms,
+    PostalAddress,
+    ProductCharacteristic,
+    ProductClassification,
+    ReferenceDocument,
+    Tax,
+    TradeContact,
+    TradeParty,
+)
+from .money import Money
+from .quantities import QuantityCode
+from .type_codes import (
+    AllowanceChargeCode,
+    DocumentTypeCode,
+    ItemTypeCode,
+    PaymentMeansCode,
+    ReferenceQualifierCode,
+    TaxCategoryCode,
+    TextSubjectCode,
+)
+
+TEST_PNG = b"\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x00\n\x00\x00\x00\n\x08\x02\x00\x00\x00\x02PX\xea\x00\x00\x00&IDAT\x18\xd3c\xfc\xff\xff?\x03n\xc0\xc4\xc0\xc0\xc0\xc0\xc8\x88E\x86\x91\x91\x81\x81\x81\x91\x08\xdd\x83X\x9al\x8f\x01\x00\xdf\x94\t\x11%\xfb\xb4\xe3\x00\x00\x00\x00IEND\xaeB`\x82"  # noqa: E501
+
+TEST_SELLER: Final = TradeParty(
+    "Seller GmbH",
+    PostalAddress(
+        "DE", None, "44331", "Test City", "Test Street 42", None, None
+    ),
+    "seller@example.com",
+    vat_id="DE123456789",
+    tax_number="123/456/789",
+    ids=["SELLER-123"],
+    global_ids=[("123456789", "0088")],
+    description="being formed",
+    legal_id=("DE123456789", "0088"),
+    trading_business_name="Great Business",
+    contact=TradeContact(
+        "Max Mustermann",
+        "Sales",
+        phone="+49 123 4567890",
+        email="foo@example.com",
+    ),
+)
+
+TEST_BUYER: Final = TradeParty(
+    "Buyer AG",
+    PostalAddress("DE"),
+)
+
+TEST_EN16931_INVOICE: Final = EN16931Invoice(
+    "INV-12345",
+    DocumentTypeCode.INVOICE,
+    datetime.date(2024, 8, 20),
+    TEST_SELLER,
+    TEST_BUYER,
+    "EUR",
+    tax_basis_total_amount=Money("10090.00", "EUR"),
+    tax_total_amounts=[Money("1917.10", "EUR")],
+    grand_total_amount=Money("12007.10", "EUR"),
+    due_payable_amount=Money("12007.10", "EUR"),
+    line_total_amount=Money("10090.00", "EUR"),
+    tax=[
+        Tax(
+            Money("1917.10", "EUR"),
+            Money("10090.00", "EUR"),
+            Decimal(19),
+            TaxCategoryCode.STANDARD_RATE,
+        ),
+    ],
+    delivery_date=datetime.date(2024, 8, 21),
+    notes=[
+        IncludedNote("This is a test invoice."),
+        IncludedNote(
+            "This is seller note.", TextSubjectCode.COMMENTS_BY_SELLER
+        ),
+    ],
+    line_items=[
+        LineItem(
+            "1",
+            "Fixed amount item\nWith multiple lines",
+            Money("10000.00", "EUR"),
+            (Decimal(1), QuantityCode.PIECE),
+            Money("10000.00", "EUR"),
+            Decimal("19"),
+        ),
+        EN16931LineItem(
+            "2",
+            "Hourly item",
+            Money("30.00", "EUR"),
+            (Decimal(3), QuantityCode.HOUR),
+            Money("90.00", "EUR"),
+            Decimal("19"),
+            global_id=("9781529044195", "0160"),
+            basis_quantity=(Decimal(1), QuantityCode.HOUR),
+            description="This is a line item description.",
+            note=IncludedNote("This is a line item note."),
+            seller_assigned_id="ISBN-44",
+            buyer_assigned_id="TT-123",
+            product_characteristics=[
+                ProductCharacteristic("color", "red"),
+            ],
+            product_classifications=[
+                ProductClassification("1234-5679", list_id=ItemTypeCode.ISSN),
+                ProductClassification(
+                    "9781529044195",
+                    list_id=ItemTypeCode.ISBN,
+                    list_version_id="99",
+                ),
+            ],
+            origin_country="DE",
+            buyer_order_line_id="BUY-DOC",
+            gross_unit_price=(
+                Money("40.00", "EUR"),
+                (Decimal(1), QuantityCode.HOUR),
+            ),
+            gross_allowance_or_charge=LineAllowance(
+                Money("10.00", "EUR"),
+                reason_code=AllowanceChargeCode.AHEAD_OF_SCHEDULE,
+            ),
+            charges=[
+                LineCharge(
+                    Money("0.05", "EUR"), reason="Complexity surcharge"
+                ),
+            ],
+            allowances=[
+                LineAllowance(
+                    Money("1.00", "EUR"),
+                    reason_code=AllowanceChargeCode.AHEAD_OF_SCHEDULE,
+                    reason="Ahead of schedule",
+                    basis_amount=Money("20.00", "EUR"),
+                    percent=Decimal("5"),
+                ),
+            ],
+            billing_period=(
+                datetime.date(2024, 8, 1),
+                datetime.date(2024, 8, 31),
+            ),
+            doc_ref=("REFDOC-1", None),
+        ),
+    ],
+    buyer_reference="BUYER-1234",
+    seller_order_id="SELL-DOC",
+    buyer_order_id="BUY-DOC",
+    contract_id="CONTRACT-123",
+    referenced_docs=[
+        ReferenceDocument("REFDOC-1", DocumentTypeCode.INVOICING_DATA_SHEET),
+        ReferenceDocument(
+            "REFDOC-2",
+            DocumentTypeCode.RELATED_DOCUMENT,
+            "Test ref doc",
+            "https://example.com/refdoc.txt",
+            attachment=(TEST_PNG, "image/png", "refdoc.png"),
+            reference_type_code=ReferenceQualifierCode.PRICE_LIST_VERSION,
+        ),
+    ],
+    procuring_project=("PROJ-123", "Project X"),
+    sepa_reference="ABC-dddd",
+    payment_means=[
+        PaymentMeans(PaymentMeansCode.BANK_PAYMENT),
+    ],
+    payment_terms=PaymentTerms(
+        due_date=datetime.date(2024, 9, 3),
+    ),
+)

{pycheval-0.1.0 → pycheval-0.2.0}/src/pycheval/const.py

@@ -16,3 +16,12 @@ URN_XRECHNUNG_PROFILE = "urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:sta
 NS_CII = "urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100"
 NS_RAM = "urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100"  # noqa: E501
 NS_UDT = "urn:un:unece:uncefact:data:standard:UnqualifiedDataType:100"
+
+ALLOWED_ATTACHMENT_MIME_TYPES = (
+    "application/pdf",
+    "image/png",
+    "image/jpeg",
+    "text/csv",
+    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    "application/vnd.oasis.opendocument.spreadsheet",
+)

{pycheval-0.1.0 → pycheval-0.2.0}/src/pycheval/exc.py

@@ -6,6 +6,10 @@ class PDFError(FacturXError):
     """Base class for PDF processing exceptions."""
 
 
+class InsufficientPDFError(PDFError):
+    """Raised when a PDF file is insufficient for Factur-X."""
+
+
 class PDFParseError(FacturXError):
     """Raise when a PDF file cannot be processed."""
 

{pycheval-0.1.0 → pycheval-0.2.0}/src/pycheval/format.py

@@ -473,8 +473,8 @@ def format_trade_party(trade_party: TradeParty) -> str:
         lines.append(_format_global_id(gid))
     if trade_party.legal_id:
         lines.append(_format_global_id(trade_party.legal_id))
-    for contact in trade_party.contacts:
-        lines.append(format_trade_contact(contact))
+    if trade_party.contact is not None:
+        lines.append(format_trade_contact(trade_party.contact))
 
     return "\n".join(lines)