euinvoice 0.1.0__py3-none-any.whl

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}")

euinvoice/__main__.py

@@ -0,0 +1,305 @@
+"""Command-line interface: ``python -m euinvoice`` (plan §8, M8.3).
+
+Subcommands (each registers its handler with ``set_defaults(run=...)``):
+
+* ``validate FILE [--profile ID] [--json]``: :func:`euinvoice.validate` on a UBL / CII document or the invoice
+  of a Factur-X / ZUGFeRD PDF; one line per finding, then a verdict line.
+* ``convert FILE --to ubl|cii [--profile ID] [-o OUT]``: :func:`euinvoice.parse_detailed`, then
+  :func:`euinvoice.to_xml`; the XML goes to ``OUT`` or stdout. Input that has no business term in the model is
+  not converted, and each such XPath is reported on stderr (readers never drop input silently, plan §1).
+* ``info FILE [--json]``: the detected syntax, root, BT-24 and profile, the Factur-X / ZUGFeRD container of a
+  PDF, the invoice's BT-1, BT-2, BT-3, BT-5 and document totals (BG-22), and what was not mapped.
+* ``artifacts fetch [--only NAME]``: download and verify the pinned official artifacts.
+
+``FILE`` ``-`` reads stdin. ``--profile`` takes a :attr:`euinvoice.profiles.Profile.id`; without it the profile
+comes from BT-24 (``validate`` falls back to EN 16931 core as :func:`euinvoice.validate` documents).
+
+Exit codes:
+
+* ``0``: success; ``validate`` found nothing ``fatal`` / ``error`` (warnings allowed).
+* ``1``: the document was rejected: ``validate`` found a ``fatal`` / ``error`` finding (``validate --profile ID``
+  on a document whose syntax the profile does not support included), ``convert`` was refused by the pre-flight /
+  calculation checks (the findings go to stderr), the input is not a readable invoice (malformed XML, unsupported
+  root or profile, a PDF without one embedded invoice), or an artifact fails its integrity check
+  (``ArtifactIntegrityError``: sha256 mismatch, unsafe archive member).
+* ``2``: no verdict, fix the command or the setup: a usage error (argparse, an unknown ``--profile``, ``convert
+  --profile ID --to SYNTAX`` with a syntax the profile does not support), ``FILE`` cannot be read or ``OUT``
+  written, an artifact download fails (network / HTTP), the artifacts are missing (the message names
+  ``artifacts fetch``) or the profile's Schematron is not pinned, or an extra (``[pdf]``) is not installed.
+
+Text that the terminal's encoding cannot represent (e.g. German rule messages on an ASCII stdout) is written
+with backslash escapes instead of failing.
+
+JSON output (``--json``), one object on stdout:
+
+* ``validate``: ``{"ok": bool, "findings": [{"rule_id", "severity", "location", "message", "source"}]}``, the
+  fields of :class:`euinvoice.report.Finding` (``location`` may be ``null``).
+* ``info``: ``{"syntax", "root", "specification_identifier", "profile", "pdf", "invoice", "unmapped"}``.
+  ``profile`` is a profile id or ``null``; ``pdf`` is ``null`` for XML, else ``{"container",
+  "conformance_level", "filename"}``; ``invoice`` maps the BT ids above to strings (dates ISO 8601, amounts as
+  plain decimals) or ``null`` when absent; ``unmapped`` lists XPaths.
+
+Errors are a single ``error: ...`` line on stderr in either mode.
+"""
+
+import argparse
+import dataclasses
+import datetime
+import io
+import json
+import logging
+import sys
+import typing as t
+from decimal import Decimal
+from pathlib import Path
+
+from euinvoice import profiles
+from euinvoice._api import parse_detailed, to_xml
+from euinvoice.detection import detect, is_pdf
+from euinvoice.errors import ArtifactsNotAvailableError, EuInvoiceError, PreflightError
+from euinvoice.model.bt_index import path_of
+from euinvoice.model.invoice import Invoice
+from euinvoice.report import Finding, Severity, ValidationReport
+from euinvoice.syntax import Syntax
+from euinvoice.validation import artifacts, validate
+
+if t.TYPE_CHECKING:
+    from euinvoice.facturx import Extracted
+
+PROFILES: t.Final[t.Mapping[str, profiles.Profile]] = {
+    profile.id: profile for name in profiles.__all__ if isinstance(profile := getattr(profiles, name), profiles.Profile)
+}
+"""Every profile ``--profile`` accepts, by :attr:`~euinvoice.profiles.Profile.id`."""
+
+# The terms ``info`` shows (EN 16931-1 §6.4; ids resolved to model paths by euinvoice.model.bt_index): invoice number,
+# issue date, type code, currency, and the document totals BG-22 (BT-106 … BT-115).
+_SUMMARY_TERMS: t.Final = ("BT-1", "BT-2", "BT-3", "BT-5", *(f"BT-{n}" for n in range(106, 116)))
+
+
+def _read(file: str) -> bytes:
+    """The bytes of ``file``, or of stdin for ``-``."""
+    return sys.stdin.buffer.read() if file == "-" else Path(file).read_bytes()
+
+
+def _xml_of(data: bytes) -> tuple[bytes, "Extracted | None"]:
+    """The invoice XML of ``data`` and, for a Factur-X / ZUGFeRD PDF, what :func:`euinvoice.facturx.extract` found."""
+    if not is_pdf(data):
+        return data, None
+    # Imported here so that XML input never needs pypdf (the ``[pdf]`` extra).
+    from euinvoice import facturx
+
+    found = facturx.extract(data)
+    return found.xml, found
+
+
+def _finding_line(finding: Finding) -> str:
+    at = f" at {finding.location}" if finding.location else ""
+    return f"{finding.severity} {finding.rule_id} [{finding.source}]{at}: {finding.message}\n"
+
+
+def _validate(args: argparse.Namespace) -> int:
+    xml, found = _xml_of(_read(args.file))
+    # For a PDF, the Factur-X level in the XMP selects the profile (a level shares its BT-24 with EN 16931 core or
+    # XRechnung), as in ``info``. A level whose Factur-X Schematron is not pinned (MINIMUM, BASIC WL, BASIC,
+    # EXTENDED; issue #42) then makes validate() raise ArtifactsNotAvailableError (exit 2) instead of a verdict. A
+    # ZUGFeRD 2.0 PDF selects no profile; validate() refuses its MINIMUM, BASIC and EXTENDED BT-24s the same way (#98).
+    profile = args.profile if args.profile is not None or found is None else found.profile
+    try:
+        report: ValidationReport = validate(xml, profile)
+    except ArtifactsNotAvailableError as exc:  # the unpinned Factur-X Schematron (#42) names the Python spelling
+        raise ArtifactsNotAvailableError(
+            str(exc).replace("pass profile=euinvoice.profiles.EN16931", "pass --profile en16931")
+        ) from exc
+    if args.json:
+        payload = {"ok": report.ok, "findings": [dataclasses.asdict(f) for f in report.findings]}
+        sys.stdout.write(json.dumps(payload, indent=2) + "\n")
+    else:
+        blocking = sum(f.severity in (Severity.FATAL, Severity.ERROR) for f in report.findings)
+        for finding in report.findings:
+            sys.stdout.write(_finding_line(finding))
+        verdict = "ok" if report.ok else "invalid"
+        sys.stdout.write(f"{verdict}: {blocking} fatal/error, {len(report.findings) - blocking} warning/information\n")
+    return 0 if report.ok else 1
+
+
+def _convert(args: argparse.Namespace) -> int:
+    if args.profile is not None and Syntax(args.to) not in args.profile.syntaxes:
+        supported = ", ".join(sorted(args.profile.syntaxes))
+        sys.stderr.write(
+            f"error: profile {args.profile.id!r} does not support --to {args.to}; it supports {supported}\n"
+        )
+        return 2
+    result = parse_detailed(_read(args.file))
+    for path in result.unmapped:
+        sys.stderr.write(f"warning: not converted, no business term: {path}\n")
+    try:
+        xml = to_xml(result.invoice, profile=args.profile, syntax=args.to)
+    except PreflightError as exc:
+        sys.stderr.write(
+            f"error: invoice fails the {exc.profile_id} pre-flight and calculation checks for {exc.syntax}\n"
+        )
+        for finding in exc.findings:
+            sys.stderr.write(_finding_line(finding))
+        return 1
+    if args.output is None:
+        sys.stdout.buffer.write(xml)
+        sys.stdout.buffer.flush()
+    else:
+        # Written only after to_xml succeeded, so a refusal never touches OUT.
+        # ponytail: a write error midway (e.g. disk full) can leave OUT truncated; the upgrade path is a temp file in
+        # the same directory + os.replace that keeps OUT's mode and does not replace a symlink.
+        Path(args.output).write_bytes(xml)
+    return 0
+
+
+def _plain(value: object) -> str | None:
+    """A business term's value as JSON-safe text: amounts via ``format(v, "f")`` (never exponent notation)."""
+    if value is None:
+        return None
+    if isinstance(value, Decimal):
+        return format(value, "f")
+    if isinstance(value, datetime.date):
+        return value.isoformat()
+    return str(value)
+
+
+def _summary(invoice: Invoice) -> dict[str, str | None]:
+    summary: dict[str, str | None] = {}
+    for ident in _SUMMARY_TERMS:
+        value: object = invoice
+        for name in path_of(ident).split("."):
+            value = getattr(value, name)
+        summary[ident] = _plain(value)
+    return summary
+
+
+def _info(args: argparse.Namespace) -> int:
+    xml, found = _xml_of(_read(args.file))
+    detection = detect(xml)
+    result = parse_detailed(xml)
+    # For a PDF, extract() picks the profile: a Factur-X level shares its BT-24 with EN 16931 core or XRechnung.
+    profile = detection.profile if found is None else found.profile
+    container = (
+        None
+        if found is None
+        else {"container": found.container, "conformance_level": found.conformance_level, "filename": found.filename}
+    )
+    summary = _summary(result.invoice)
+    head = {
+        "syntax": str(detection.syntax),
+        "root": detection.root,
+        "specification_identifier": detection.specification_identifier,
+        "profile": profile.id if profile is not None else None,
+    }
+    if args.json:
+        payload = {**head, "pdf": container, "invoice": summary, "unmapped": list(result.unmapped)}
+        sys.stdout.write(json.dumps(payload, indent=2) + "\n")
+        return 0
+    lines = [
+        *(f"{key}: {value}" for key, value in head.items()),
+        *(f"pdf {key}: {value}" for key, value in (container or {}).items()),
+        *(f"{ident}: {term}" for ident, term in summary.items() if term is not None),
+        *(f"unmapped: {path}" for path in result.unmapped),
+    ]
+    sys.stdout.write("".join(f"{line}\n" for line in lines))
+    return 0
+
+
+def _artifacts_fetch(args: argparse.Namespace) -> int:
+    names = t.cast(list[artifacts.SourceName] | None, args.only)
+    for name, path in artifacts.fetch(names).items():
+        sys.stdout.write(f"{name}: {path}\n")
+    return 0
+
+
+def _profile_arg(value: str) -> profiles.Profile:
+    try:
+        return PROFILES[value]
+    except KeyError:
+        raise argparse.ArgumentTypeError(f"unknown profile {value!r}; choose from {', '.join(PROFILES)}") from None
+
+
+_EPILOG: t.Final = "exit codes: 0 ok, 1 document rejected (findings, refused, unreadable invoice), 2 usage or setup"
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="python -m euinvoice",
+        description="EN 16931 e-invoicing toolkit (euinvoice).",
+        epilog=_EPILOG,
+    )
+    commands = parser.add_subparsers(dest="command", required=True)
+    profile_help = f"profile id (default: from BT-24): {', '.join(PROFILES)}"
+
+    check = commands.add_parser(
+        "validate", help="validate a UBL / CII invoice or Factur-X / ZUGFeRD PDF", epilog=_EPILOG
+    )
+    check.add_argument("file", metavar="FILE", help="the invoice; - reads stdin")
+    check.add_argument("--profile", type=_profile_arg, metavar="ID", help=profile_help)
+    check.add_argument("--json", action="store_true", help="print the report as JSON")
+    check.set_defaults(run=_validate)
+
+    convert = commands.add_parser("convert", help="convert an invoice to UBL or CII", epilog=_EPILOG)
+    convert.add_argument("file", metavar="FILE", help="the invoice (XML or Factur-X / ZUGFeRD PDF); - reads stdin")
+    convert.add_argument("--to", required=True, choices=[str(s) for s in Syntax], help="target syntax")
+    convert.add_argument("--profile", type=_profile_arg, metavar="ID", help=profile_help)
+    convert.add_argument("-o", "--output", metavar="OUT", help="write here instead of stdout")
+    convert.set_defaults(run=_convert)
+
+    info = commands.add_parser("info", help="show what an invoice is: syntax, profile, number, totals", epilog=_EPILOG)
+    info.add_argument("file", metavar="FILE", help="the invoice (XML or Factur-X / ZUGFeRD PDF); - reads stdin")
+    info.add_argument("--json", action="store_true", help="print as JSON")
+    info.set_defaults(run=_info)
+
+    group = commands.add_parser("artifacts", help="manage the official validation artifacts")
+    actions = group.add_subparsers(dest="action", required=True)
+    fetch = actions.add_parser(
+        "fetch",
+        help=f"download and verify the pinned artifacts into ${artifacts.ENV_VAR} "
+        f"(default {artifacts.DEFAULT_CACHE_DIR})",
+    )
+    fetch.add_argument(
+        "--only",
+        action="append",
+        metavar="NAME",
+        choices=t.get_args(artifacts.SourceName),
+        help="fetch only this source (repeatable); choices: %(choices)s",
+    )
+    fetch.set_defaults(run=_artifacts_fetch)
+    return parser
+
+
+def main(argv: t.Sequence[str] | None = None) -> int:
+    """Run the CLI.
+
+    Args:
+        argv: Arguments without the program name; defaults to ``sys.argv[1:]``.
+
+    Returns:
+        The process exit code (see the module docstring). Usage errors found by argparse exit with 2 through
+        ``SystemExit``.
+    """
+    for stream in (sys.stdout, sys.stderr):
+        if isinstance(stream, io.TextIOWrapper):
+            stream.reconfigure(errors="backslashreplace")
+    args = _parser().parse_args(argv)
+    run = t.cast(t.Callable[[argparse.Namespace], int], args.run)
+    # pypdf logs recoverable damage (e.g. "EOF marker not found") as warnings; the CLI reports a PdfError as one
+    # ``error:`` line instead, so the pypdf logger is quieted for the run and restored afterwards.
+    pypdf_logger = logging.getLogger("pypdf")
+    level = pypdf_logger.level
+    pypdf_logger.setLevel(logging.ERROR)
+    try:
+        return run(args)
+    except (ArtifactsNotAvailableError, OSError, ImportError) as exc:
+        sys.stderr.write(f"error: {exc}\n")
+        return 2
+    except EuInvoiceError as exc:
+        sys.stderr.write(f"error: {exc}\n")
+        return 1
+    finally:
+        pypdf_logger.setLevel(level)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

euinvoice/_api.py

@@ -0,0 +1,154 @@
+"""The top-level API: :func:`to_xml`, :func:`parse` and :func:`parse_detailed` (plan §4 "Public API", "Data flow").
+
+Writing: ``profile.prepare(invoice)`` → ``profile.preflight(prepared, syntax)`` and
+``calc.check(prepared, syntax=syntax)`` → the syntax writer. Reading:
+(a Factur-X / ZUGFeRD PDF goes through :func:`euinvoice.facturx.extract` first) → :func:`euinvoice._xml.parse`
+(D10) → :func:`euinvoice.detection.detect_root` → the syntax reader. This module sits above every other package;
+nothing below imports it.
+"""
+
+import typing as t
+
+from euinvoice import _xml, calc, profiles
+from euinvoice.detection import detect_root, is_pdf
+from euinvoice.errors import PreflightError, UnsupportedDocumentError
+from euinvoice.model import Invoice
+from euinvoice.profiles._base import FACTURX_RULE_SET
+from euinvoice.report import ValidationReport
+from euinvoice.syntax import Syntax, cii, ubl
+from euinvoice.syntax.result import ParseResult
+
+__all__ = ["parse", "parse_detailed", "to_xml"]
+
+
+def to_xml(
+    invoice: Invoice,
+    *,
+    profile: profiles.Profile | None = None,
+    syntax: Syntax | t.Literal["ubl", "cii"] | None = None,
+) -> bytes:
+    """Write an invoice as UBL 2.1 or CII D16B XML under a profile, after its pre-flight and calculation checks.
+
+    The invoice is first set up for the profile with :meth:`~euinvoice.profiles.Profile.prepare` (BT-24 becomes
+    the profile's, BT-23 gets its default; see there), so the written document reads back as
+    ``profile.prepare(invoice)``, not as ``invoice``. Then two checks run on the prepared invoice:
+    :attr:`~euinvoice.profiles.Profile.preflight` (the profile's rules) and :func:`euinvoice.calc.check` with the
+    target syntax (the CEN calculation, VAT category and period rules, each ``fatal`` exactly when that syntax's
+    official CEN binding rejects it; ``tests/conformance/test_calc_oracle.py``). Any ``fatal`` or ``error``
+    finding refuses the write with :class:`PreflightError`, because the official rules would reject the document.
+    Warnings do not block and are not returned; call ``profile.preflight(prepared, syntax)`` and
+    ``calc.check(prepared, syntax=syntax)`` to see them. Both checks are early, model-level messages; the official
+    Schematron stays the oracle (D8), so run :func:`euinvoice.validate` on the result for the verdict.
+
+    Args:
+        invoice: The invoice, e.g. from :func:`euinvoice.calc.complete`.
+        profile: The profile to write under. ``None`` uses the profile registered for the invoice's own BT-24
+            (:func:`euinvoice.profiles.get`); a Factur-X level shares its BT-24 with another profile, so pass it
+            explicitly (and see :func:`euinvoice.facturx.embed` for the PDF).
+        syntax: ``Syntax.UBL`` / ``"ubl"`` or ``Syntax.CII`` / ``"cii"``. ``None`` is allowed only when the
+            profile supports a single syntax, which is then used (e.g. ``FACTURX_EN16931`` /
+            ``FACTURX_XRECHNUNG``: CII).
+
+    Returns:
+        The serialized XML document.
+
+    Raises:
+        PreflightError: The pre-flight or calculation checks report a ``fatal`` or ``error`` finding; ``findings``
+            holds every finding of both.
+        UnsupportedDocumentError: ``profile`` is ``None`` and no profile is registered for the invoice's BT-24;
+            the profile does not support ``syntax``; or it is a Factur-X level that is not generated (MINIMUM,
+            BASIC WL, BASIC, EXTENDED, plan §1), whose official Schematron is not pinned (issue #42), so nothing
+            could tell whether its rules accept the document.
+        ValueError: ``syntax`` is not a syntax, or is ``None`` for a profile that supports more than one.
+    """
+    if profile is None:
+        profile = profiles.get(invoice.process_control.specification_identifier)
+    if FACTURX_RULE_SET in profile.rule_sets:
+        raise UnsupportedDocumentError(
+            f"profile {profile.id!r} is not generated (plan §1): its Factur-X / ZUGFeRD Schematron is not pinned "
+            "(https://github.com/letsrevel/euinvoice/issues/42)"
+        )
+    target = _target_syntax(profile, syntax)
+    prepared = profile.prepare(invoice)
+    findings = (*profile.preflight(prepared, target), *calc.check(prepared, syntax=target))
+    if not ValidationReport(findings).ok:
+        raise PreflightError(profile.id, target, findings)
+    return ubl.write(prepared) if target is Syntax.UBL else cii.write(prepared)
+
+
+def parse(data: bytes) -> Invoice:
+    """Read a UBL or CII invoice, or the invoice of a Factur-X / ZUGFeRD PDF, into the semantic model.
+
+    This is :func:`parse_detailed` without its ``unmapped`` list: input that has no business term in the model
+    is **discarded** here. Use :func:`parse_detailed` to see it.
+
+    Args:
+        data: UBL 2.1 ``Invoice`` / ``CreditNote`` or CII D16B ``CrossIndustryInvoice`` XML, or a PDF with an
+            embedded Factur-X / ZUGFeRD invoice.
+
+    Returns:
+        The invoice.
+
+    Raises:
+        TypeError: ``data`` is not ``bytes``.
+        ParseError: See :func:`parse_detailed`.
+        UnsupportedDocumentError: See :func:`parse_detailed`.
+        PdfError: See :func:`parse_detailed`.
+        ImportError: ``data`` is a PDF and the ``[pdf]`` extra (pypdf) is not installed.
+    """
+    return parse_detailed(data).invoice
+
+
+def parse_detailed(data: bytes) -> ParseResult:
+    """Read a UBL or CII invoice, or the invoice of a Factur-X / ZUGFeRD PDF, and list what was not mapped.
+
+    The syntax comes from the root element (:func:`euinvoice.detection.detect_root`); the BT-24 profile plays no part
+    in reading. A PDF (``%PDF-`` header, see :func:`euinvoice.detection.is_pdf`) is read with
+    :func:`euinvoice.facturx.extract`, which needs the ``[pdf]`` extra, and its embedded XML is parsed like any
+    other.
+
+    Args:
+        data: UBL 2.1 ``Invoice`` / ``CreditNote`` or CII D16B ``CrossIndustryInvoice`` XML, or a PDF with an
+            embedded Factur-X / ZUGFeRD invoice.
+
+    Returns:
+        The invoice plus the XPath of every element or attribute that has no business term in the model
+        (:attr:`~euinvoice.syntax.result.ParseResult.unmapped`).
+
+    Raises:
+        TypeError: ``data`` is not ``bytes``.
+        ParseError: The XML is malformed, has a DOCTYPE or exceeds the parser limits (D10), or its content does not
+            form a valid invoice (the message names the BT/BG id). Factur-X MINIMUM and BASIC WL documents raise it,
+            as they lack terms EN 16931 requires (issue #69).
+        UnsupportedDocumentError: The root element is not a UBL 2.1 Invoice / CreditNote or a CII D16B
+            CrossIndustryInvoice.
+        PdfError: ``data`` is a PDF that does not name exactly one embedded invoice (see
+            :func:`euinvoice.facturx.extract`).
+        ImportError: ``data`` is a PDF and the ``[pdf]`` extra (pypdf) is not installed.
+    """
+    if is_pdf(data):
+        # Imported here so that ``import euinvoice`` and XML parsing never need pypdf (the ``[pdf]`` extra);
+        # without it, importing ``euinvoice.facturx`` raises an ImportError naming the extra.
+        from euinvoice import facturx
+
+        data = facturx.extract(data).xml
+    root = _xml.parse(data)
+    return ubl.read(root) if detect_root(root).syntax is Syntax.UBL else cii.read(root)
+
+
+def _target_syntax(profile: profiles.Profile, syntax: Syntax | str | None) -> Syntax:
+    """The syntax to write: ``syntax`` if the profile supports it, else the profile's only one."""
+    if syntax is None:
+        if len(profile.syntaxes) != 1:
+            raise ValueError(
+                f"profile {profile.id!r} supports {', '.join(sorted(profile.syntaxes))}; pass syntax= to choose one"
+            )
+        (only,) = profile.syntaxes
+        return only
+    target = Syntax(syntax)
+    if target not in profile.syntaxes:
+        raise UnsupportedDocumentError(
+            f"profile {profile.id!r} does not support {target.upper()}; it supports "
+            f"{', '.join(sorted(profile.syntaxes))}"
+        )
+    return target

euinvoice/_syntax.py

@@ -0,0 +1,16 @@
+"""The :class:`Syntax` enum, a leaf module so ``calc`` can name a syntax without importing ``syntax``.
+
+The dependency direction is ``model`` ← ``calc`` ← ``syntax`` (CLAUDE.md); the public path is
+:class:`euinvoice.syntax.Syntax`.
+"""
+
+import enum
+
+__all__ = ["Syntax"]
+
+
+class Syntax(enum.StrEnum):
+    """An XML syntax for EN 16931 invoices."""
+
+    UBL = "ubl"
+    CII = "cii"