ofdkit 0.1.0__py3-none-any.whl

ofdkit/__init__.py

@@ -0,0 +1,54 @@
+"""ofdkit: read OFD documents (GB/T 33190) and Chinese e-invoices.
+
+>>> import ofdkit
+>>> with ofdkit.open("invoice.ofd") as doc:  # doctest: +SKIP
+...     print(doc.text())
+...     print(doc.invoice())
+"""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _version
+
+from .document import DocInfo, OFDDocument, Page, TextRun
+from .errors import OFDError, OFDFormatError, OFDLimitError
+from .invoice import Invoice, LineItem, Party
+from .package import Source
+
+try:
+    __version__ = _version("ofdkit")
+except PackageNotFoundError:  # running from a source checkout that is not installed
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "DocInfo",
+    "Invoice",
+    "LineItem",
+    "OFDDocument",
+    "OFDError",
+    "OFDFormatError",
+    "OFDLimitError",
+    "Page",
+    "Party",
+    "TextRun",
+    "__version__",
+    "extract_invoice",
+    "extract_text",
+    "open",
+]
+
+
+def open(source: Source) -> OFDDocument:  # noqa: A001 - mirrors builtins.open on purpose
+    """Open an OFD file from a path, bytes, or a binary file object."""
+    return OFDDocument(source)
+
+
+def extract_text(source: Source, page_separator: str = "\n\n") -> str:
+    """Return all text of an OFD file in reading order."""
+    with OFDDocument(source) as document:
+        return document.text(page_separator)
+
+
+def extract_invoice(source: Source) -> Invoice | None:
+    """Return the invoice data of an OFD e-invoice, or None if the file holds none."""
+    with OFDDocument(source) as document:
+        return document.invoice()

ofdkit/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

ofdkit/_xml.py

@@ -0,0 +1,120 @@
+"""XML helpers: safe parsing, recovery from common producer bugs, namespace-free lookups.
+
+OFD files in the wild use several namespace URIs (``http://www.ofdspec.org/2016``,
+``http://www.ofdspec.org``, the e-invoice schemas, or none at all), and some producers
+write malformed XML such as ``<:eInvoice xmlns:="">`` or undeclared prefixes. All lookups
+here therefore match on local names only, and parsing falls back to a repaired copy of
+the text when strict parsing fails.
+"""
+
+from __future__ import annotations
+
+import codecs
+import re
+import xml.etree.ElementTree as ET
+from collections.abc import Iterator
+
+from .errors import OFDFormatError, OFDLimitError
+
+# OFD never needs a DTD; refusing them rules out entity-expansion attacks.
+_FORBIDDEN = re.compile(r"<!DOCTYPE|<!ENTITY", re.IGNORECASE)
+_DECLARED_ENCODING = re.compile(rb"""^\s*<\?xml[^>]*?encoding\s*=\s*["']([A-Za-z0-9._-]+)["']""")
+_XML_DECLARATION = re.compile(r"^\s*<\?xml[^>]*\?>")
+_TAG = re.compile(r"<[^<>]*>")
+_ELEMENT_PREFIX = re.compile(r"^<(/?)[^\s<>/=\"':]*:")
+_XMLNS_ATTRIBUTE = re.compile(r"""\s+xmlns(?::[^\s=]*)?\s*=\s*(?:"[^"]*"|'[^']*')""")
+_ATTRIBUTE_PREFIX = re.compile(r"""(\s)[^\s<>/="':]+:(?=[^\s<>/="':]+\s*=)""")
+
+# Chinese producers often declare GB2312 or GBK; GB18030 is a superset of both.
+_ENCODING_ALIASES = {"gb2312": "gb18030", "gbk": "gb18030", "cp936": "gb18030"}
+
+
+def local_name(tag: object) -> str:
+    """Return the tag name without its namespace (comments and PIs give '')."""
+    if not isinstance(tag, str):
+        return ""
+    return tag.rsplit("}", 1)[-1]
+
+
+def children(element: ET.Element, name: str) -> Iterator[ET.Element]:
+    """Direct children with the given local name."""
+    for child_element in element:
+        if local_name(child_element.tag) == name:
+            yield child_element
+
+
+def grandchildren(element: ET.Element | None, container: str, name: str) -> Iterator[ET.Element]:
+    """Children named ``name`` of the first child named ``container``, if any."""
+    holder = child(element, container)
+    if holder is not None:
+        yield from children(holder, name)
+
+
+def child(element: ET.Element | None, name: str) -> ET.Element | None:
+    """First direct child with the given local name, or None."""
+    if element is None:
+        return None
+    return next(children(element, name), None)
+
+
+def child_text(element: ET.Element | None, name: str) -> str | None:
+    """Stripped text of the first direct child with the given local name, or None."""
+    found = child(element, name)
+    if found is None or found.text is None:
+        return None
+    text = found.text.strip()
+    return text or None
+
+
+def parse_xml(data: bytes, name: str = "XML") -> ET.Element:
+    """Parse an XML part strictly, falling back to a repaired copy for broken files."""
+    try:
+        text = _decode(data)
+    except UnicodeError as exc:
+        raise OFDFormatError(f"{name}: cannot decode XML: {exc}") from exc
+    if _FORBIDDEN.search(text):
+        raise OFDLimitError(f"{name}: DTDs and entity declarations are not allowed")
+    text = _XML_DECLARATION.sub("", text, count=1)
+    try:
+        return ET.fromstring(text)
+    except ET.ParseError as first_error:
+        try:
+            return ET.fromstring(_repair(text))
+        except ET.ParseError:
+            raise OFDFormatError(f"{name}: invalid XML: {first_error}") from first_error
+
+
+def _decode(data: bytes) -> str:
+    if data.startswith(codecs.BOM_UTF8):
+        return data[len(codecs.BOM_UTF8):].decode("utf-8", errors="replace")
+    if data.startswith((codecs.BOM_UTF16_LE, codecs.BOM_UTF16_BE)):
+        return data.decode("utf-16")
+    declared = _DECLARED_ENCODING.match(data)
+    if declared:
+        encoding = declared.group(1).decode("ascii").lower()
+        encoding = _ENCODING_ALIASES.get(encoding, encoding)
+        try:
+            codec_name = codecs.lookup(encoding).name
+        except LookupError:  # unknown declaration: fall through to detection
+            codec_name = "utf-8"
+        if codec_name != "utf-8":
+            return data.decode(codec_name, errors="replace")
+    try:
+        return data.decode("utf-8")
+    except UnicodeDecodeError:
+        # Undeclared non-UTF-8 text from Chinese producers is almost always GBK.
+        return data.decode("gb18030", errors="replace")
+
+
+def _repair(text: str) -> str:
+    """Drop namespace declarations and prefixes so that unbound or empty prefixes parse."""
+    return _TAG.sub(_repair_tag, text)
+
+
+def _repair_tag(match: re.Match[str]) -> str:
+    tag = match.group(0)
+    if tag.startswith(("<?", "<!")):
+        return tag
+    tag = _ELEMENT_PREFIX.sub(r"<\1", tag, count=1)
+    tag = _XMLNS_ATTRIBUTE.sub("", tag)
+    return _ATTRIBUTE_PREFIX.sub(r"\1", tag)

ofdkit/batch.py

@@ -0,0 +1,111 @@
+"""Many files at once: find OFD files and summarise their invoices as rows."""
+
+from __future__ import annotations
+
+from collections import Counter
+from collections.abc import Iterable, Sequence
+from decimal import Decimal, InvalidOperation
+from pathlib import Path
+from typing import Any
+
+from .document import OFDDocument
+from .errors import OFDError
+from .invoice import Invoice
+
+COLUMNS = [
+    "file",
+    "invoice_number",
+    "invoice_code",
+    "issue_date",
+    "buyer_name",
+    "buyer_tax_id",
+    "seller_name",
+    "seller_tax_id",
+    "amount_without_tax",
+    "tax_amount",
+    "total_amount",
+    "items",
+    "warnings",
+    "error",
+]
+
+NO_INVOICE = "no invoice data"
+
+
+def find_ofd_files(paths: Iterable[str | Path], recursive: bool = False) -> tuple[list[Path], list[str]]:
+    """OFD files in ``paths`` (files are kept, folders are searched), plus paths that do not exist."""
+    found: list[Path] = []
+    missing: list[str] = []
+    for raw in paths:
+        path = Path(raw)
+        if path.is_dir():
+            candidates = path.rglob("*") if recursive else path.glob("*")
+            found.extend(sorted(p for p in candidates if p.is_file() and p.suffix.lower() == ".ofd"))
+        elif path.exists():
+            found.append(path)
+        else:
+            missing.append(str(raw))
+    return found, missing
+
+
+def invoice_rows(files: Sequence[Path]) -> list[dict[str, Any]]:
+    """One row per file, with duplicate invoice numbers flagged in ``warnings``."""
+    rows = [invoice_row(path) for path in files]
+    numbers = Counter(row["invoice_number"] for row in rows if row["invoice_number"])
+    for row in rows:
+        if numbers.get(row["invoice_number"], 0) > 1:
+            row["warnings"] = "; ".join(filter(None, [row["warnings"], "duplicate invoice number"]))
+    return rows
+
+
+def invoice_row(path: Path) -> dict[str, Any]:
+    row: dict[str, Any] = dict.fromkeys(COLUMNS, "")
+    row["file"] = str(path)
+    try:
+        with OFDDocument(path) as document:
+            invoice = document.invoice()
+    except (OFDError, OSError) as exc:
+        row["error"] = str(exc)
+        return row
+    if invoice is None:
+        row["error"] = NO_INVOICE
+        return row
+    row.update(_invoice_columns(invoice))
+    return row
+
+
+def summary(rows: Sequence[dict[str, Any]]) -> dict[str, Any]:
+    """Counts and the sum of ``total_amount`` over rows that are invoices."""
+    invoices = [row for row in rows if not row["error"]]
+    total = sum((_decimal(row["total_amount"]) for row in invoices), Decimal(0))
+    return {
+        "files": len(rows),
+        "invoices": len(invoices),
+        "without_invoice_data": sum(1 for row in rows if row["error"] == NO_INVOICE),
+        "errors": sum(1 for row in rows if row["error"] and row["error"] != NO_INVOICE),
+        "total_amount_sum": str(total),
+    }
+
+
+def _invoice_columns(invoice: Invoice) -> dict[str, Any]:
+    return {
+        "invoice_number": invoice.invoice_number or "",
+        "invoice_code": invoice.invoice_code or "",
+        "issue_date": invoice.issue_date or "",
+        "buyer_name": invoice.buyer.name or "",
+        "buyer_tax_id": invoice.buyer.tax_id or "",
+        "seller_name": invoice.seller.name or "",
+        "seller_tax_id": invoice.seller.tax_id or "",
+        "amount_without_tax": invoice.amount_without_tax or "",
+        "tax_amount": invoice.tax_amount or "",
+        "total_amount": invoice.total_amount or "",
+        "items": len(invoice.items),
+        "warnings": "; ".join(invoice.warnings),
+    }
+
+
+def _decimal(value: str) -> Decimal:
+    try:
+        return Decimal(value)
+    except (InvalidOperation, TypeError):
+        return Decimal(0)

ofdkit/cli.py

@@ -0,0 +1,189 @@
+"""Command-line interface for ofdkit."""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any
+
+from . import __version__
+from .batch import COLUMNS, find_ofd_files, invoice_rows, summary
+from .document import OFDDocument
+from .errors import OFDError
+from .markdown import document_markdown
+
+EXIT_OK = 0
+EXIT_NO_INVOICE = 1
+EXIT_ERROR = 2
+
+# Kept for backward compatibility with code that imported it from here.
+CSV_COLUMNS = COLUMNS
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="ofdkit",
+        description="Read OFD documents (GB/T 33190) and Chinese e-invoices.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    commands = parser.add_subparsers(dest="command", metavar="COMMAND")
+
+    info = commands.add_parser("info", help="show pages, metadata and whether the file is an invoice")
+    info.add_argument("file", help="OFD file")
+    info.add_argument("--json", action="store_true", help="print JSON")
+
+    text = commands.add_parser("text", help="print the text in reading order")
+    text.add_argument("file", help="OFD file")
+    text.add_argument("-o", "--output", help="write to this file (UTF-8) instead of the screen")
+    text.add_argument("--markdown", action="store_true", help="print Markdown, with an invoice table for e-invoices")
+
+    invoice = commands.add_parser("invoice", help="print invoice fields as JSON")
+    invoice.add_argument("file", help="OFD file")
+    invoice.add_argument("--raw", action="store_true", help="also print every value found, by element path")
+
+    batch = commands.add_parser("batch", help="list the invoices in files and folders as CSV")
+    batch.add_argument("paths", nargs="+", metavar="PATH", help="OFD files or folders")
+    batch.add_argument("-o", "--output", help="CSV file to write (UTF-8 with BOM, so Excel shows Chinese correctly)")
+    batch.add_argument("-r", "--recursive", action="store_true", help="also look in subfolders")
+
+    mcp = commands.add_parser("mcp", help='run an MCP server over stdio for AI tools (needs "ofdkit[mcp]")')
+    mcp.add_argument("--root", help="only allow reading files inside this folder")
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    _replace_unencodable_output()
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.command is None:
+        parser.print_help()
+        return EXIT_OK
+    commands = {"info": _info, "text": _text, "invoice": _invoice, "batch": _batch, "mcp": _mcp}
+    try:
+        return commands[args.command](args)
+    except (OFDError, OSError) as exc:
+        print(f"ofdkit: error: {exc}", file=sys.stderr)
+        return EXIT_ERROR
+
+
+def _info(args: argparse.Namespace) -> int:
+    with OFDDocument(args.file) as document:
+        data = file_info(document, args.file)
+    if args.json:
+        print(json.dumps(data, ensure_ascii=False, indent=2))
+        return EXIT_OK
+
+    info = data["info"]
+    sizes = sorted({(page["width_mm"], page["height_mm"]) for page in data["pages"]})
+    size_text = ", ".join(f"{w:g} x {h:g} mm" for w, h in sizes)
+    lines = [("File", args.file), ("Pages", f"{len(data['pages'])} ({size_text})" if sizes else "0")]
+    for label, key in (("Title", "title"), ("Author", "author"), ("Created", "creation_date"), ("Modified", "mod_date")):
+        if info[key]:
+            lines.append((label, info[key]))
+    if info["creator"]:
+        creator = info["creator"] + (f" {info['creator_version']}" if info["creator_version"] else "")
+        lines.append(("Creator", creator))
+    lines.append(("Invoice", "yes" if data["is_invoice"] else "no"))
+    lines.extend(("Warning", warning) for warning in data["warnings"])
+    width = max(len(label) for label, _ in lines) + 1
+    for label, value in lines:
+        print(f"{label + ':':<{width}} {value}")
+    return EXIT_OK
+
+
+def file_info(document: OFDDocument, name: str) -> dict[str, Any]:
+    """Pages, metadata and whether the document is an invoice, as plain data."""
+    invoice = document.invoice()
+    return {
+        "file": name,
+        "pages": [
+            {"number": page.index + 1, "id": page.id, "width_mm": page.width, "height_mm": page.height}
+            for page in document.pages
+        ],
+        "info": document.info.to_dict(),
+        "is_invoice": invoice is not None,
+        "warnings": list(document.warnings),
+    }
+
+
+def _text(args: argparse.Namespace) -> int:
+    with OFDDocument(args.file) as document:
+        text = document_markdown(document).rstrip("\n") if args.markdown else document.text()
+        warnings = list(document.warnings)
+    if args.output:
+        Path(args.output).write_text(text + "\n", encoding="utf-8")
+    else:
+        print(text)
+    for warning in warnings:
+        print(f"ofdkit: warning: {warning}", file=sys.stderr)
+    return EXIT_OK
+
+
+def _invoice(args: argparse.Namespace) -> int:
+    with OFDDocument(args.file) as document:
+        invoice = document.invoice()
+    if invoice is None:
+        print(f"ofdkit: no invoice data found in {args.file}", file=sys.stderr)
+        return EXIT_NO_INVOICE
+    print(json.dumps(invoice.to_dict(include_raw=args.raw), ensure_ascii=False, indent=2))
+    return EXIT_OK
+
+
+def _batch(args: argparse.Namespace) -> int:
+    files, missing = find_ofd_files(args.paths, args.recursive)
+    for path in missing:
+        print(f"ofdkit: warning: {path} does not exist", file=sys.stderr)
+    if not files:
+        print("ofdkit: error: no .ofd files found", file=sys.stderr)
+        return EXIT_ERROR
+
+    rows = invoice_rows(files)
+    if args.output:
+        with open(args.output, "w", newline="", encoding="utf-8-sig") as stream:
+            _write_csv(stream, rows)
+    else:
+        _write_csv(sys.stdout, rows)
+
+    totals = summary(rows)
+    print(
+        f"ofdkit: {totals['files']} files, {totals['invoices']} invoices, "
+        f"{totals['files'] - totals['invoices']} without invoice data; "
+        f"total_amount sum {totals['total_amount_sum']}",
+        file=sys.stderr,
+    )
+    return EXIT_OK
+
+
+def _mcp(args: argparse.Namespace) -> int:
+    try:
+        from .mcp_server import create_server
+    except ImportError as exc:
+        print(f'ofdkit: error: MCP support needs the "mcp" extra: pip install "ofdkit[mcp]" ({exc})', file=sys.stderr)
+        return EXIT_ERROR
+    create_server(root=args.root).run("stdio")
+    return EXIT_OK
+
+
+def _write_csv(stream: Any, rows: list[dict[str, Any]]) -> None:
+    writer = csv.DictWriter(stream, fieldnames=COLUMNS)
+    writer.writeheader()
+    writer.writerows(rows)
+
+
+def _replace_unencodable_output() -> None:
+    """Never crash on a character the console cannot show (old Windows code pages)."""
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is not None:
+            try:
+                reconfigure(errors="replace")
+            except (ValueError, OSError):
+                pass
+
+
+if __name__ == "__main__":
+    sys.exit(main())