getafix 0.1.0__py3-none-any.whl

getafix/cli.py

@@ -0,0 +1,146 @@
+"""Command-line entry point for the ``getafix`` console script.
+
+Reads a Cross-Industry-Invoice XML file — or a Factur-X / ZUGFeRD PDF
+that has one embedded — parses it into a
+:class:`getafix.schema.Document`, runs the business-rule validators
+and prints both the invoice and the validation result as a rich
+console report.
+
+Requires the optional ``cli`` extra (pulls in ``lxml`` and ``rich``).
+PDF input additionally needs the ``pdf`` extra (pypdf)::
+
+    pip install 'getafix[cli,pdf]'
+
+Exit codes:
+
+* ``0`` — XML parsed cleanly and passed every validator.
+* ``1`` — XML parsed but at least one validation rule fired
+  (or the document tree could not be parsed as a CII invoice, or no
+  Factur-X XML was found in the supplied PDF).
+* ``2`` — usage / IO / missing dependency error.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import cast
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="getafix",
+        description=(
+            "Pretty-print a ZUGFeRD / Factur-X Cross-Industry-Invoice "
+            "XML file and report business-rule violations."
+        ),
+    )
+    _ = parser.add_argument(
+        "source",
+        type=Path,
+        help=(
+            "Path to a CII XML file (typically ``factur-x.xml``) or a "
+            "Factur-X / ZUGFeRD PDF with one embedded."
+        ),
+    )
+    _ = parser.add_argument(
+        "--no-validate",
+        action="store_true",
+        help="Skip running the BR-* business-rule validators.",
+    )
+    return parser
+
+
+def _looks_like_pdf(path: Path) -> bool:
+    """``True`` if ``path`` starts with the PDF magic header."""
+    try:
+        with path.open("rb") as fp:
+            return fp.read(5) == b"%PDF-"
+    except OSError:
+        return False
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    try:
+        import lxml.etree as etree
+        from rich.console import Console
+    except ImportError as exc:
+        _ = sys.stderr.write(
+            f"getafix CLI needs the optional 'cli' extra ({exc.name}): "
+            f"{exc.msg}.\nInstall with: pip install 'getafix[cli]'\n"
+        )
+        return 2
+
+    from getafix.report import render_invoice, render_validation_errors
+    from getafix.schema.document import Document
+
+    out = Console()
+    err = Console(stderr=True)
+
+    source = cast("Path", args.source)
+    no_validate = cast("bool", args.no_validate)
+    if not source.is_file():
+        err.print(f"[red]Could not read {source}: not a file[/red]")
+        return 2
+
+    if source.suffix.lower() == ".pdf" or _looks_like_pdf(source):
+        try:
+            from getafix.pdf import extract_xml
+        except ImportError:
+            err.print(
+                "[red]PDF input needs the optional 'pdf' dependency.[/red]\n"
+                "[red]Install with: pip install 'getafix[pdf]'[/red]"
+            )
+            return 2
+        try:
+            xml_payload = extract_xml(source)
+        except (OSError, ValueError) as exc:
+            err.print(f"[red]Could not read PDF {source}: {exc}[/red]")
+            return 1
+        if xml_payload is None:
+            err.print(
+                f"[red]No Factur-X / ZUGFeRD XML found in {source} "
+                "(looked for the standard attachment names).[/red]"
+            )
+            return 1
+        try:
+            tree = etree.ElementTree(etree.fromstring(xml_payload))
+        except etree.XMLSyntaxError as exc:
+            err.print(f"[red]Embedded XML in {source} is malformed: {exc}[/red]")
+            return 1
+    else:
+        try:
+            tree = etree.parse(str(source))
+        except OSError as exc:
+            err.print(f"[red]Could not read {source}: {exc}[/red]")
+            return 2
+        except etree.XMLSyntaxError as exc:
+            err.print(f"[red]XML syntax error in {source}: {exc}[/red]")
+            return 1
+
+    try:
+        doc = Document.from_xml(tree.getroot())
+    except (ValueError, TypeError, AssertionError) as exc:
+        err.print(
+            f"[red]Could not parse {source} as a CII invoice: "
+            f"{type(exc).__name__}: {exc}[/red]"
+        )
+        return 1
+
+    render_invoice(doc, console=out)
+
+    if no_validate:
+        return 0
+
+    profile = doc.context.guideline.id
+    errors = doc.validate_internal(profile)
+    render_validation_errors(errors, console=out)
+    return 1 if errors else 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

getafix/errors.py

@@ -0,0 +1,31 @@
+class ValidationError(ValueError):
+    """A single business-rule violation.
+
+    ``code`` is the rule identifier (``BR-CO-15`` etc.) and ``message``
+    a human-readable explanation. Subclassing ``ValueError`` keeps
+    backwards-compat with code that catches ``ValueError`` broadly, but
+    the public ``Document.validate`` entry point raises the plural
+    :class:`ValidationErrors` instead so callers can see every
+    violation in one pass.
+    """
+
+    def __init__(self, code: str, message: str):
+        super().__init__(f"{code}: {message}")
+        self.code: str = code
+        self.message: str = message
+
+
+class ValidationErrors(ValueError):
+    """Aggregate exception holding every ValidationError from a single
+    ``Document.validate`` pass.
+
+    ``errors`` is the list, in document order. Callers can check for a
+    specific rule with::
+
+        assert any(e.code == "BR-CO-15" for e in exc.errors)
+    """
+
+    def __init__(self, errors: list[ValidationError]):
+        joined = "; ".join(f"{e.code}: {e.message}" for e in errors)
+        super().__init__(joined)
+        self.errors: list[ValidationError] = errors

getafix/pdf.py

@@ -0,0 +1,119 @@
+"""Embed and extract Factur-X / ZUGFeRD XML in PDF documents.
+
+Importing this module requires the optional ``pypdf`` dependency::
+
+    pip install 'getafix[pdf]'
+
+Two operations:
+
+* :func:`attach_xml` — embed an XML file in a PDF under a configurable
+  attachment name. Defaults to ``factur-x.xml`` (the Factur-X 1.x /
+  ZUGFeRD 2.x convention); pass ``"zugferd-invoice.xml"`` for the
+  legacy ZUGFeRD 1.0 layout, ``"xrechnung.xml"`` for XRechnung, etc.
+* :func:`extract_xml` — return the bytes of the first embedded file
+  whose name matches one of the standard Factur-X / ZUGFeRD /
+  XRechnung / Order-X filenames.
+
+Caveat: :func:`attach_xml` produces a valid PDF with a generic embedded
+file, but does *not* upgrade the document to PDF/A-3 — the formal
+compliance requirement for Factur-X and ZUGFeRD invoices. Use a
+dedicated PDF/A-3 converter when full conformance is needed; this
+module only handles the file-attachment step.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from io import BytesIO
+from pathlib import Path
+
+from pypdf import PdfReader, PdfWriter
+
+STANDARD_LOCATIONS: tuple[str, ...] = (
+    "factur-x.xml",  # Factur-X 1.x / ZUGFeRD 2.x
+    "ZUGFeRD-invoice.xml",  # ZUGFeRD 1.0 (legacy)
+    "zugferd-invoice.xml",  # ZUGFeRD 1.0 alt casing
+    "xrechnung.xml",  # XRechnung
+    "order-x.xml",  # Order-X
+)
+"""Conventional filenames getafix will search for, in priority order."""
+
+DEFAULT_ATTACHMENT_NAME: str = STANDARD_LOCATIONS[0]
+"""Name used by :func:`attach_xml` when the caller doesn't override it."""
+
+
+def attach_xml(
+    pdf_in: Path | bytes,
+    xml: Path | bytes,
+    *,
+    pdf_out: Path | None = None,
+    attachment_name: str = DEFAULT_ATTACHMENT_NAME,
+    metadata: Mapping[str, str] | None = None,
+) -> Path | bytes:
+    """Embed ``xml`` in ``pdf_in`` as an embedded file and write the result.
+
+    ``pdf_in`` may be a :class:`~pathlib.Path` to read from, or the raw
+    bytes of a PDF. ``xml`` may likewise be a :class:`~pathlib.Path` to
+    read from, or raw bytes to embed verbatim.
+
+    ``pdf_out`` selects where the result goes. When given, the PDF is
+    written there and that :class:`~pathlib.Path` is returned. When
+    omitted, a :class:`~pathlib.Path` ``pdf_in`` is rewritten in place
+    (and returned); a bytes ``pdf_in`` causes the result to be returned
+    as bytes.
+
+    The attachment is stored under ``attachment_name`` in the PDF's
+    embedded-files name tree. The default matches the Factur-X 1.x /
+    ZUGFeRD 2.x convention; override for ZUGFeRD 1.0 or XRechnung.
+
+    ``metadata``, when given, extends the PDF's document information
+    dictionary (e.g. ``{"/Title": "Invoice 42"}``); existing entries are
+    kept unless a given key overrides them.
+
+    Returns the path the PDF was written to, or the result bytes when
+    ``pdf_in`` is bytes and no ``pdf_out`` is given.
+    """
+    xml_bytes = xml.read_bytes() if isinstance(xml, Path) else xml
+    clone_from = BytesIO(pdf_in) if isinstance(pdf_in, bytes) else str(pdf_in)
+    writer = PdfWriter(clone_from=clone_from)
+    _ = writer.add_attachment(attachment_name, xml_bytes)
+    if metadata:
+        writer.add_metadata(dict(metadata))
+    target = pdf_out if pdf_out is not None else pdf_in
+    if isinstance(target, bytes):
+        buffer = BytesIO()
+        _ = writer.write(buffer)
+        return buffer.getvalue()
+    with target.open("wb") as fp:
+        _ = writer.write(fp)
+    return target
+
+
+def extract_xml(
+    pdf: Path, *, candidates: Sequence[str] = STANDARD_LOCATIONS
+) -> bytes | None:
+    """Return the bytes of the first embedded file matching ``candidates``.
+
+    Names are compared case-insensitively, so e.g. ``factur-x.xml``,
+    ``Factur-X.xml`` and ``FACTUR-X.XML`` are all accepted. Search
+    order follows ``candidates``; the first hit wins.
+
+    Returns ``None`` when the PDF has no embedded files or none of
+    them matches a candidate.
+    """
+    reader = PdfReader(str(pdf))
+    attachments = reader.attachments
+    if not attachments:
+        return None
+    by_lowercase = {name.lower(): name for name in attachments}
+    for candidate in candidates:
+        original = by_lowercase.get(candidate.lower())
+        if original is None:
+            continue
+        # ``pypdf`` returns a list of byte payloads per attachment name
+        # (an attachment name can be re-used inside one PDF — rare in
+        # the Factur-X corpus but allowed). Return the first payload.
+        payload = attachments[original]
+        if payload:
+            return payload[0]
+    return None

getafix/report/__init__.py

@@ -0,0 +1,104 @@
+"""Rich console report of a parsed Cross-Industry-Invoice :class:`Document`.
+
+Importing this package requires the optional ``rich`` dependency::
+
+    pip install 'getafix[cli]'
+
+The package mirrors :mod:`getafix.schema`: every schema module has a
+report counterpart that knows how to render the elements defined there
+(``document`` → Invoice panel, ``party`` → Seller / Buyer panels,
+``trade`` → line-items table, ``accounting`` → VAT breakdown / totals,
+``settlement`` → payment / prepayment sections, …). Shared primitives
+live in :mod:`getafix.report._types`; code-formatting helpers in
+:mod:`getafix.report.types`. (``schema/_numeric.py`` has no counterpart
+— it is a rounding helper, not a renderable element.)
+
+Two public entry points:
+
+* :func:`render_invoice` — pretty-print the document (header, parties,
+  lines, VAT breakdown, totals, payment block).
+* :func:`render_validation_errors` — pretty-print a list of
+  :class:`getafix.schema.element.ValidationError` from
+  ``Document.validate_internal``.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from rich.table import Table
+
+from getafix.report._types import SectionRenderer as SectionRenderer
+from getafix.report.accounting import allowance_charge_panel, tax_table, totals_panel
+from getafix.report.agreement import supporting_documents_panel
+from getafix.report.delivery import delivery_panel
+from getafix.report.document import header_panel
+from getafix.report.element import render_validation_errors as render_validation_errors
+from getafix.report.party import party_panel, tax_representative_panel
+from getafix.report.settlement import (
+    advance_payments_panel,
+    logistics_charges_panel,
+    payment_panel,
+)
+from getafix.report.trade import lines_table
+
+if TYPE_CHECKING:
+    from rich.console import Console
+
+    from getafix.schema.document import Document
+
+
+def render_invoice(doc: Document, console: Console | None = None) -> None:
+    """Print a structured, colourised report of ``doc`` to ``console``.
+
+    Sections are emitted top to bottom in reading order; each optional
+    section short-circuits to ``None`` when it has nothing to show, so a
+    bare MINIMUM invoice prints only the header, parties and totals.
+    """
+    from rich.console import Console
+
+    console = console or Console()
+    settlement = doc.trade.settlement
+    currency = settlement.currency_code
+
+    console.print(header_panel(doc))
+    # Force a true 50/50 split: a 2-column grid with ``ratio=1``
+    # columns gives each party panel exactly half the terminal width.
+    # ``Columns(equal=True)`` only equalises widths when content fits,
+    # which truncates a long Seller block against the Buyer side.
+    parties = Table.grid(expand=True, padding=(0, 1))
+    parties.add_column(ratio=1)
+    parties.add_column(ratio=1)
+    parties.add_row(
+        party_panel("Seller", doc.trade.agreement.seller),
+        party_panel("Buyer", doc.trade.agreement.buyer),
+    )
+    console.print(parties)
+    tax_representative = tax_representative_panel(
+        doc.trade.agreement.seller_tax_representative_party
+    )
+    if tax_representative is not None:
+        console.print(tax_representative)
+    delivery = delivery_panel(doc.trade.delivery)
+    if delivery is not None:
+        console.print(delivery)
+    supporting = supporting_documents_panel(doc.trade.agreement)
+    if supporting is not None:
+        console.print(supporting)
+    if doc.trade.items:
+        console.print(lines_table(doc.trade, currency))
+    if settlement.trade_taxes:
+        console.print(tax_table(settlement))
+    allowance_charges = allowance_charge_panel(settlement)
+    if allowance_charges is not None:
+        console.print(allowance_charges)
+    logistics_charges = logistics_charges_panel(settlement)
+    if logistics_charges is not None:
+        console.print(logistics_charges)
+    console.print(totals_panel(settlement))
+    advance_payments = advance_payments_panel(settlement)
+    if advance_payments is not None:
+        console.print(advance_payments)
+    payment = payment_panel(settlement)
+    if payment is not None:
+        console.print(payment)

getafix/report/_types.py

@@ -0,0 +1,80 @@
+"""Shared rendering primitives used across :mod:`getafix.report`.
+
+Mirrors :mod:`getafix.rules._types`: where the rules package defines a
+:data:`~getafix.rules.Validator` shape plus a couple of validator
+factories, the report package defines a :data:`SectionRenderer` shape
+plus the two helpers that give every section its consistent look —
+
+* :func:`described_panel` — wrap a panel body under a one-line, dim
+  description of *what the section means*;
+* :func:`describe_table` — fold the same kind of description into the
+  table's title block as a dim subtitle line.
+
+Keeping these in one place is what lets each ``report/<topic>.py``
+focus purely on turning its schema elements into rows / cells while the
+framing (titles, borders, descriptions) stays uniform.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from rich.console import Group, RenderableType
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from getafix.schema.element import Element
+
+type SectionRenderer[T: Element] = Callable[[T], RenderableType | None]
+"""Signature of a report-section renderer.
+
+``T`` is the concrete :class:`~getafix.schema.element.Element` the
+section is built from. The function returns a Rich renderable
+(:class:`~rich.panel.Panel` / :class:`~rich.table.Table`) or ``None``
+to signal "nothing to show" so the caller can skip an empty section
+rather than printing an empty box.
+
+Not every renderer fits the shape exactly — money-bearing sections also
+take the document currency, and :func:`getafix.report.party.party_panel`
+takes the party role — but the ``element -> renderable | None`` core is
+the common contract.
+"""
+
+# Per-section descriptions render in this style: muted, so the data
+# stays the focus while the one-liner explains what the box is.
+_DESCRIPTION_STYLE = "dim italic"
+
+
+def described_panel(
+    body: RenderableType, *, title: str, description: str, border_style: str
+) -> Panel:
+    """Frame ``body`` in a titled panel with a dim description on top.
+
+    The description is a short, human sentence explaining what the
+    section means (e.g. "The supplier issuing the invoice."). It is
+    placed above the body so a reader skimming the report can orient
+    themselves before reading the data.
+    """
+    content: RenderableType = (
+        Group(Text(description, style=_DESCRIPTION_STYLE), body)
+        if description
+        else body
+    )
+    return Panel(content, title=title, border_style=border_style)
+
+
+def describe_table(table: Table, description: str) -> Table:
+    """Fold ``description`` into the table title as a dim subtitle line.
+
+    The description sits directly under the title (above the header row),
+    so it reads as the table's own subtitle. A bottom caption was
+    avoided because, between two stacked sections, it reads like the
+    heading of the *next* table.
+    """
+    name = "" if table.title is None else str(table.title)
+    table.title = Text.assemble((name, "bold"), "\n", (description, _DESCRIPTION_STYLE))
+    # Styles now live on the Text spans; drop the base title style so it
+    # doesn't bleed bold onto the dim subtitle line.
+    table.title_style = None
+    return table

getafix/report/accounting.py

@@ -0,0 +1,171 @@
+"""Rendering for the financial spine (:mod:`getafix.schema.accounting`).
+
+Three sections, all driven off the header settlement:
+
+* :func:`tax_table` — the VAT breakdown (BG-23), one row per category /
+  rate;
+* :func:`allowance_charge_panel` — document-level allowances (BG-20) and
+  charges (BG-21);
+* :func:`totals_panel` — the monetary summation (BG-22) down to the
+  amount due.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from rich.panel import Panel
+from rich.table import Table
+
+from getafix.report._types import describe_table, described_panel
+from getafix.report.types import dim_paren, format_amount, format_vat
+
+if TYPE_CHECKING:
+    from decimal import Decimal
+
+    from getafix.schema.accounting import ApplicableTradeTax
+    from getafix.schema.settlement import TradeSettlement
+
+
+def tax_table(settlement: TradeSettlement) -> Table:
+    """VAT breakdown (BG-23): taxable base and tax per category and rate."""
+    currency = settlement.currency_code
+    taxes = settlement.trade_taxes or []
+    # The tax-point column (BT-7 date / BT-8 code) is rare — only add it
+    # when at least one row carries it, so the common invoice stays narrow.
+    has_tax_point = any(
+        tax.tax_point_date is not None or tax.due_date_code is not None for tax in taxes
+    )
+    table = Table(
+        title="VAT breakdown (BG-23)",
+        title_style="bold",
+        header_style="bold",
+        border_style="blue",
+        expand=True,
+    )
+    table.add_column("Cat", no_wrap=True)
+    table.add_column("Rate", justify="right")
+    table.add_column(f"Basis [{currency}]", justify="right")
+    table.add_column(f"Tax [{currency}]", justify="right")
+    table.add_column("Exemption reason")
+    if has_tax_point:
+        table.add_column("Tax point (BT-7/8)", no_wrap=True)
+    for tax in taxes:
+        rate = tax.rate_applicable_percent
+        reason = tax.exemption_reason or ""
+        if tax.exemption_reason_code:
+            reason = f"{dim_paren(tax.exemption_reason_code)} {reason}".strip()
+        cells = [
+            tax.category_code.value,
+            f"{rate}%" if rate is not None else "-",
+            f"{tax.basis_amount}" if tax.basis_amount is not None else "-",
+            f"{tax.calculated_amount}" if tax.calculated_amount is not None else "-",
+            reason,
+        ]
+        if has_tax_point:
+            cells.append(_tax_point_cell(tax))
+        table.add_row(*cells)
+    return describe_table(
+        table, "Taxable base and tax amount per VAT category and rate."
+    )
+
+
+def _tax_point_cell(tax: ApplicableTradeTax) -> str:
+    """Tax point date (BT-7) or, failing that, the due-date code (BT-8)."""
+    if tax.tax_point_date is not None:
+        return tax.tax_point_date.isoformat()
+    if tax.due_date_code is not None:
+        return f"code {tax.due_date_code.value}"
+    return "-"
+
+
+def allowance_charge_panel(settlement: TradeSettlement) -> Table | None:
+    """Document-level allowances (BG-20) and charges (BG-21).
+
+    Each row shows the indicator label, reason, amount, optional VAT
+    category + rate, and an optional ``% * basis`` derivation. Returns
+    ``None`` if no header-level allowance/charge is present.
+    """
+    items = settlement.allowance_charge or []
+    if not items:
+        return None
+    currency = settlement.currency_code
+    table = Table(
+        title="Document-level allowances & charges (BG-20 / BG-21)",
+        title_style="bold",
+        header_style="bold",
+        border_style="blue",
+        expand=True,
+    )
+    table.add_column("Kind", no_wrap=True)
+    table.add_column("Reason")
+    table.add_column(f"Amount [{currency}]", justify="right")
+    table.add_column("Calc.", justify="right")
+    table.add_column("VAT", justify="right", no_wrap=True)
+    for ac in items:
+        kind = "[red]Charge[/red]" if ac.indicator else "[green]Allowance[/green]"
+        reason_bits = [ac.reason or ""]
+        if ac.reason_code:
+            reason_bits.append(dim_paren(ac.reason_code))
+        if ac.calculation_percent is not None and ac.basis_amount is not None:
+            calc = f"{ac.calculation_percent}% of {ac.basis_amount}"
+        elif ac.calculation_percent is not None:
+            calc = f"{ac.calculation_percent}%"
+        elif ac.basis_amount is not None:
+            calc = f"basis {ac.basis_amount}"
+        else:
+            calc = "-"
+        ctt = ac.category_trade_tax
+        vat = format_vat(ctt.category_code, ctt.rate_applicable_percent) if ctt else "-"
+        table.add_row(
+            kind,
+            " ".join(b for b in reason_bits if b),
+            f"{ac.actual_amount}",
+            calc,
+            vat,
+        )
+    return describe_table(
+        table, "Discounts and surcharges applied to the whole invoice."
+    )
+
+
+def totals_panel(settlement: TradeSettlement) -> Panel:
+    """Monetary summation (BG-22): line, tax and grand totals to amount due."""
+    summ = settlement.monetary_summation
+    currency = settlement.currency_code
+    grid = Table.grid(padding=(0, 2))
+    grid.add_column(style="bold")
+    grid.add_column(justify="right")
+    rows: list[tuple[str, Decimal | None]] = [
+        ("Line total (BT-106)", summ.line_total),
+        ("Allowances (BT-107)", summ.allowance_total),
+        ("Charges (BT-108)", summ.charge_total),
+        ("Tax basis (BT-109)", summ.tax_basis_total),
+    ]
+    for label, value in rows:
+        if value is None:
+            continue
+        grid.add_row(label, format_amount(value, currency))
+    for tax in summ.tax_total or []:
+        grid.add_row(
+            f"Tax total ({tax.currency_id})", format_amount(tax.amount, tax.currency_id)
+        )
+    tail: list[tuple[str, Decimal | None]] = [
+        ("Rounding (BT-114)", summ.rounding_amount),
+        ("Grand total (BT-112)", summ.grand_total),
+        ("Prepaid (BT-113)", summ.prepaid_total),
+    ]
+    for label, value in tail:
+        if value is None:
+            continue
+        grid.add_row(label, format_amount(value, currency))
+    grid.add_row(
+        "[bold yellow]Amount due (BT-115)[/bold yellow]",
+        f"[bold yellow]{format_amount(summ.due_amount, currency)}[/bold yellow]",
+    )
+    return described_panel(
+        grid,
+        title="[bold]Totals[/bold]",
+        description="Net, tax and gross totals down to the amount due.",
+        border_style="yellow",
+    )