pint-ae-toolkit 0.1.0__py3-none-any.whl

pint_ae/__init__.py

@@ -0,0 +1 @@
+

pint_ae/cli.py

@@ -0,0 +1,74 @@
+"""Command-line interface for the pint-ae toolkit."""
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from pint_ae.parser import parse
+from pint_ae.rules import validate
+
+app = typer.Typer(
+    name="pint-ae",
+    help="PINT AE toolkit - validate UAE e-invoices against Peppol rules.",
+    no_args_is_help=True,
+)
+console = Console()
+
+
+@app.callback()
+def main() -> None:
+    """PINT AE toolkit - validate UAE e-invoices against Peppol rules."""
+    pass
+
+
+@app.command()
+def diagnose(
+    files: list[Path] = typer.Argument(..., help="Invoice XML files to validate"),
+    verbose: bool = typer.Option(
+        False, "--verbose", "-v", help="Show clean invoices too, not just violations"
+    ),
+) -> None:
+    """Validate PINT AE invoices against business rules and print a report."""
+    parse_errors = 0
+    invoices_with_violations = 0
+    invoices_clean = 0
+
+    for file in files:
+        try:
+            inv = parse(file.read_bytes())
+        except Exception as exc:
+            parse_errors += 1
+            console.print(f"[red]x[/red] {file.name} -- parse error: {exc}")
+            continue
+
+        violations = validate(inv)
+        if not violations:
+            invoices_clean += 1
+            if verbose:
+                console.print(f"[green]OK[/green] {file.name} ({inv.invoice_id}) -- clean")
+            continue
+
+        invoices_with_violations += 1
+        console.print(
+            f"[red]x[/red] {file.name} ({inv.invoice_id}) -- {len(violations)} violation(s)"
+        )
+        for v in violations:
+            console.print(f"    [{v.severity}] {v.rule_id}: {v.message}")
+            console.print(f"    Citation: {v.citation}")
+
+    total = parse_errors + invoices_with_violations + invoices_clean
+    console.print(
+        f"\nSummary: {invoices_clean}/{total} clean, "
+        f"{invoices_with_violations} with violations, {parse_errors} parse error(s)"
+    )
+
+    if parse_errors:
+        raise typer.Exit(code=2)
+    if invoices_with_violations:
+        raise typer.Exit(code=1)
+    raise typer.Exit(code=0)
+
+
+if __name__ == "__main__":
+    app()

pint_ae/parser.py

@@ -0,0 +1,127 @@
+"""Parser for PINT AE invoices (UBL 2.1 XML).
+
+Exposes: parse(xml: str | bytes) -> PintAeInvoice
+"""
+
+from datetime import date
+from decimal import Decimal
+
+from lxml import etree
+
+from pint_ae.types import LineItem, Party, PintAeInvoice, TaxCategory
+
+NSMAP = {
+    "inv": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2",
+    "cac": "urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2",
+    "cbc": "urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2",
+}
+
+
+def _text(el: etree._Element, xpath: str) -> str:
+    found = el.find(xpath, namespaces=NSMAP)
+    if found is None or found.text is None:
+        raise ValueError(f"Missing required element: {xpath}")
+    return str(found.text).strip()
+
+
+def _opt_text(el: etree._Element, xpath: str) -> str | None:
+    found = el.find(xpath, namespaces=NSMAP)
+    if found is None or found.text is None:
+        return None
+    return str(found.text).strip()
+
+
+def _decimal(el: etree._Element, xpath: str) -> Decimal:
+    return Decimal(_text(el, xpath))
+
+
+def _parse_party(el: etree._Element, base: str) -> Party:
+    name = _text(el, f"{base}/cac:Party/cac:PartyName/cbc:Name")
+    trn = _text(el, f"{base}/cac:Party/cac:PartyTaxScheme/cbc:CompanyID")
+    id_el = el.find(f"{base}/cac:Party/cac:PartyIdentification/cbc:ID", namespaces=NSMAP)
+    peppol_id: str | None = None
+    if id_el is not None and id_el.text is not None:
+        scheme = id_el.get("schemeID")
+        peppol_id = f"{scheme}:{id_el.text.strip()}" if scheme else id_el.text.strip()
+    country = _opt_text(
+        el, f"{base}/cac:Party/cac:PostalAddress/cac:Country/cbc:IdentificationCode"
+    )
+    return Party(name=name, trn=trn, peppol_id=peppol_id, country_code=country)
+
+
+def _parse_tax_category(cat_el: etree._Element) -> TaxCategory:
+    code = cat_el.findtext("cbc:ID", namespaces=NSMAP)
+    pct = cat_el.findtext("cbc:Percent", namespaces=NSMAP)
+    if code is None or pct is None:
+        raise ValueError("TaxCategory missing cbc:ID or cbc:Percent")
+    return TaxCategory(code=code.strip(), percent=Decimal(pct.strip()))
+
+
+def _parse_line(line_el: etree._Element) -> LineItem:
+    line_id = _text(line_el, "cbc:ID")
+    desc = _text(line_el, "cac:Item/cbc:Name")
+    qty_el = line_el.find("cbc:InvoicedQuantity", namespaces=NSMAP)
+    if qty_el is None or qty_el.text is None:
+        raise ValueError("InvoiceLine missing cbc:InvoicedQuantity")
+    qty = Decimal(qty_el.text.strip())
+    unit = qty_el.get("unitCode", "EA")
+    price = _decimal(line_el, "cac:Price/cbc:PriceAmount")
+    total = _decimal(line_el, "cbc:LineExtensionAmount")
+    cat_el = line_el.find("cac:Item/cac:ClassifiedTaxCategory", namespaces=NSMAP)
+    if cat_el is None:
+        raise ValueError("InvoiceLine missing cac:ClassifiedTaxCategory")
+    return LineItem(
+        line_id=line_id,
+        description=desc,
+        quantity=qty,
+        unit_code=unit,
+        unit_price=price,
+        line_total=total,
+        tax_category=_parse_tax_category(cat_el),
+    )
+
+
+def parse(xml: str | bytes) -> PintAeInvoice:
+    """Parse a PINT AE UBL 2.1 XML invoice into a PintAeInvoice."""
+    if isinstance(xml, str):
+        xml = xml.encode("utf-8")
+    root = etree.fromstring(xml)
+
+    supplier = _parse_party(root, "cac:AccountingSupplierParty")
+    customer = _parse_party(root, "cac:AccountingCustomerParty")
+
+    tax_cats: list[TaxCategory] = []
+    for sub in root.findall("cac:TaxTotal/cac:TaxSubtotal", namespaces=NSMAP):
+        cat_el = sub.find("cac:TaxCategory", namespaces=NSMAP)
+        if cat_el is None:
+            raise ValueError("TaxSubtotal missing cac:TaxCategory")
+        base = _parse_tax_category(cat_el)
+        taxable = sub.findtext("cbc:TaxableAmount", namespaces=NSMAP)
+        tax_amt = sub.findtext("cbc:TaxAmount", namespaces=NSMAP)
+        tax_cats.append(
+            TaxCategory(
+                code=base.code,
+                percent=base.percent,
+                taxable_amount=Decimal(taxable.strip()) if taxable else None,
+                tax_amount=Decimal(tax_amt.strip()) if tax_amt else None,
+            )
+        )
+
+    line_items = [_parse_line(line) for line in root.findall("cac:InvoiceLine", namespaces=NSMAP)]
+
+    return PintAeInvoice(
+        customization_id=_text(root, "cbc:CustomizationID"),
+        profile_id=_text(root, "cbc:ProfileID"),
+        invoice_id=_text(root, "cbc:ID"),
+        issue_date=date.fromisoformat(_text(root, "cbc:IssueDate")),
+        invoice_type_code=_text(root, "cbc:InvoiceTypeCode"),
+        document_currency_code=_text(root, "cbc:DocumentCurrencyCode"),
+        supplier=supplier,
+        customer=customer,
+        tax_categories=tax_cats,
+        line_items=line_items,
+        line_extension_amount=_decimal(root, "cac:LegalMonetaryTotal/cbc:LineExtensionAmount"),
+        tax_exclusive_amount=_decimal(root, "cac:LegalMonetaryTotal/cbc:TaxExclusiveAmount"),
+        tax_inclusive_amount=_decimal(root, "cac:LegalMonetaryTotal/cbc:TaxInclusiveAmount"),
+        payable_amount=_decimal(root, "cac:LegalMonetaryTotal/cbc:PayableAmount"),
+    )

pint_ae/rules.py

@@ -0,0 +1,142 @@
+"""PINT AE business rules validator.
+
+Each rule is a pure function: PintAeInvoice -> list[RuleViolation].
+Rules are registered in _RULES; validate() runs all of them.
+
+Every rule cites a BR-* number from Peppol BIS Billing 3.0. PINT AE
+inherits these rules unchanged unless noted in the PINT AE BIS.
+"""
+
+from dataclasses import dataclass
+from decimal import Decimal
+
+from pint_ae.types import PintAeInvoice
+
+
+@dataclass
+class RuleViolation:
+    """A single rule violation on an invoice."""
+
+    rule_id: str
+    citation: str
+    field: str
+    message: str
+    severity: str = "error"
+
+
+def rule_line_sum(inv: PintAeInvoice) -> list[RuleViolation]:
+    """R-001 / BT-106 / BR-CO-10: line_extension_amount == sum of line totals."""
+    expected = sum((item.line_total for item in inv.line_items), start=Decimal("0"))
+    if inv.line_extension_amount != expected:
+        return [
+            RuleViolation(
+                rule_id="R-001",
+                citation="Peppol BIS Billing 3.0 BR-CO-10 (BT-106)",
+                field="line_extension_amount",
+                message=(
+                    f"line_extension_amount {inv.line_extension_amount} does not equal "
+                    f"sum of line totals {expected}"
+                ),
+            )
+        ]
+    return []
+
+
+def rule_tax_exclusive_sum(inv: PintAeInvoice) -> list[RuleViolation]:
+    """R-002 / BT-109 / BR-CO-13: tax_exclusive_amount == sum of taxable amounts."""
+    expected = sum(
+        (cat.taxable_amount or Decimal("0") for cat in inv.tax_categories),
+        start=Decimal("0"),
+    )
+    if inv.tax_exclusive_amount != expected:
+        return [
+            RuleViolation(
+                rule_id="R-002",
+                citation="Peppol BIS Billing 3.0 BR-CO-13 (BT-109)",
+                field="tax_exclusive_amount",
+                message=(
+                    f"tax_exclusive_amount {inv.tax_exclusive_amount} does not equal "
+                    f"sum of taxable amounts {expected}"
+                ),
+            )
+        ]
+    return []
+
+
+def rule_payable_amount(inv: PintAeInvoice) -> list[RuleViolation]:
+    """R-003 / BT-115 / BR-CO-15: payable_amount == tax_inclusive_amount."""
+    if inv.payable_amount != inv.tax_inclusive_amount:
+        return [
+            RuleViolation(
+                rule_id="R-003",
+                citation="Peppol BIS Billing 3.0 BR-CO-15 (BT-115)",
+                field="payable_amount",
+                message=(
+                    f"payable_amount {inv.payable_amount} does not equal "
+                    f"tax_inclusive_amount {inv.tax_inclusive_amount}"
+                ),
+            )
+        ]
+    return []
+
+
+def rule_total_tax(inv: PintAeInvoice) -> list[RuleViolation]:
+    """R-004 / BT-110 / BR-CO-14: sum of tax amounts == payable - tax_exclusive."""
+    total_tax = sum(
+        (cat.tax_amount or Decimal("0") for cat in inv.tax_categories),
+        start=Decimal("0"),
+    )
+    expected = inv.payable_amount - inv.tax_exclusive_amount
+    if total_tax != expected:
+        return [
+            RuleViolation(
+                rule_id="R-004",
+                citation="Peppol BIS Billing 3.0 BR-CO-14 (BT-110)",
+                field="tax_categories",
+                message=(
+                    f"sum of tax_amounts {total_tax} does not equal "
+                    f"payable - tax_exclusive {expected}"
+                ),
+            )
+        ]
+    return []
+
+
+def rule_vat_rate_consistency(inv: PintAeInvoice) -> list[RuleViolation]:
+    """R-005 / BT-152 / BR-S-05: standard rate must be 5.00%, zero rate 0.00%."""
+    expected_rates = {
+        "S": Decimal("5.00"),
+        "Z": Decimal("0.00"),
+    }
+    violations: list[RuleViolation] = []
+    for cat in inv.tax_categories:
+        if cat.code in expected_rates and cat.percent != expected_rates[cat.code]:
+            violations.append(
+                RuleViolation(
+                    rule_id="R-005",
+                    citation="Peppol BIS Billing 3.0 BR-S-05 (BT-152)",
+                    field=f"tax_category[{cat.code}].percent",
+                    message=(
+                        f"VAT category {cat.code} requires percent "
+                        f"{expected_rates[cat.code]}, found {cat.percent}"
+                    ),
+                )
+            )
+    return violations
+
+
+_RULES = [
+    rule_line_sum,
+    rule_tax_exclusive_sum,
+    rule_payable_amount,
+    rule_total_tax,
+    rule_vat_rate_consistency,
+]
+
+
+def validate(inv: PintAeInvoice) -> list[RuleViolation]:
+    """Run all registered rules against an invoice; return all violations."""
+    violations: list[RuleViolation] = []
+    for rule in _RULES:
+        violations.extend(rule(inv))
+    return violations

pint_ae/types.py

@@ -0,0 +1,62 @@
+"""Pydantic models for PINT AE invoices (UBL 2.1 subset).
+
+Field names follow the PINT AE BIS 1.0.4 business terms in snake_case.
+All monetary and quantity values use Decimal for tax-grade precision.
+
+See: docs/learning/03_pydantic_for_tax_data.md
+Spec: PINT AE Billing 1.0.4 - https://docs.peppol.eu/poac/ae/upcoming/pint-ae/bis/
+"""
+
+from datetime import date
+from decimal import Decimal
+
+from pydantic import BaseModel, Field
+
+
+class Party(BaseModel):
+    """A supplier or customer in a PINT AE invoice."""
+
+    name: str = Field(..., min_length=1, max_length=200)
+    trn: str = Field(..., min_length=15, max_length=15, pattern=r"^\d{15}$")
+    peppol_id: str | None = Field(default=None)
+    country_code: str | None = Field(default=None, min_length=2, max_length=2)
+
+
+class TaxCategory(BaseModel):
+    """A VAT tax category (S, Z, E, O, or AE)."""
+
+    code: str = Field(..., min_length=1, max_length=2, pattern=r"^(S|Z|E|O|AE)$")
+    percent: Decimal = Field(..., ge=0, le=100)
+    taxable_amount: Decimal | None = Field(default=None, ge=0)
+    tax_amount: Decimal | None = Field(default=None, ge=0)
+
+
+class LineItem(BaseModel):
+    """A single invoice line item."""
+
+    line_id: str = Field(..., min_length=1)
+    description: str = Field(..., min_length=1, max_length=500)
+    quantity: Decimal = Field(..., gt=0)
+    unit_code: str = Field(default="EA", min_length=1, max_length=3)
+    unit_price: Decimal = Field(..., ge=0)
+    line_total: Decimal = Field(..., ge=0)
+    tax_category: TaxCategory
+
+
+class PintAeInvoice(BaseModel):
+    """A PINT AE invoice (subset of the 51 mandatory fields)."""
+
+    customization_id: str = Field(..., pattern=r"^urn:peppol:pint:billing-1@ae-1$")
+    profile_id: str = Field(default="urn:peppol:bis:billing")
+    invoice_id: str = Field(..., min_length=1, max_length=50)
+    issue_date: date
+    invoice_type_code: str = Field(..., pattern=r"^\d{3}$")
+    document_currency_code: str = Field(..., min_length=3, max_length=3)
+    supplier: Party
+    customer: Party
+    tax_categories: list[TaxCategory] = Field(..., min_length=1)
+    line_items: list[LineItem] = Field(..., min_length=1)
+    line_extension_amount: Decimal = Field(..., ge=0)
+    tax_exclusive_amount: Decimal = Field(..., ge=0)
+    tax_inclusive_amount: Decimal = Field(..., ge=0)
+    payable_amount: Decimal = Field(..., ge=0)

pint_ae_toolkit-0.1.0.dist-info/METADATA

@@ -0,0 +1,19 @@
+Metadata-Version: 2.5
+Name: pint-ae-toolkit
+Version: 0.1.0
+Summary: PINT AE toolkit - parsing, validation, and diagnostics for UAE e-invoicing
+Requires-Python: >=3.11
+Requires-Dist: lxml>=5.0
+Requires-Dist: pydantic>=2.5
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: ipykernel>=6.20; extra == 'dev'
+Requires-Dist: jupyterlab>=4.0; extra == 'dev'
+Requires-Dist: lxml-stubs; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: nbformat>=5.7; extra == 'dev'
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'

pint_ae_toolkit-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+pint_ae/__init__.py,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
+pint_ae/cli.py,sha256=8CtmT9Ll82Z9zI_Hx08v2O-EYuZRgxzoSsAAurd1a-0,2111
+pint_ae/parser.py,sha256=lpw9IIUgwnhkVgNaxzEOjp5SeJE9M_FE48HwwpvBIlE,5091
+pint_ae/rules.py,sha256=0knGcMt6c4BfpmcOqet8kkng3ZEo_simq8-TVYweAbI,4705
+pint_ae/types.py,sha256=SNmrqTbvjqci44HLDuTSLBsEmMghKOvPhB6mh_3wB4A,2341
+pint_ae_toolkit-0.1.0.dist-info/METADATA,sha256=R8PuXIKcmJo0lKNoj1L4jTZBEbfo-umrNh8EViLsiCc,672
+pint_ae_toolkit-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+pint_ae_toolkit-0.1.0.dist-info/entry_points.txt,sha256=l66GNbxaGkpla7naFnLOW892PnxJjXBG4SPTaNhbhLA,44
+pint_ae_toolkit-0.1.0.dist-info/RECORD,,

pint_ae_toolkit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pint_ae_toolkit-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pint-ae = pint_ae.cli:app