ofdkit 0.1.0__py3-none-any.whl

ofdkit/invoice.py

@@ -0,0 +1,438 @@
+"""Invoice fields from Chinese e-invoices in OFD format.
+
+Three places in an OFD file can carry invoice data, read in this order of trust:
+
+1. An XML attachment with the invoice itself (``Attachs/original_invoice.xml`` in older
+   e-invoices), which holds the values directly.
+2. Custom tags (``Tags/CustomTags.xml``): each field points at the text objects on the
+   page that show its value. Both the 2016/2019 e-invoice schema (``fp:eInvoice``) and
+   the layout used by fully digitalised invoices (数电票, ``ofd:root``) are supported.
+3. ``CustomData`` entries in OFD.xml, which 数电票 use for a few key fields.
+
+ofdkit only reads these values. It never checks them against the tax authority, so a
+result says what the file contains, not that the invoice is genuine.
+"""
+
+from __future__ import annotations
+
+import re
+import xml.etree.ElementTree as ET
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from decimal import Decimal, InvalidOperation
+from typing import TYPE_CHECKING, Any
+
+from ._xml import child_text, children, grandchildren, local_name
+from .errors import OFDError
+
+if TYPE_CHECKING:
+    from .document import OFDDocument
+
+# Leaf element names of the e-invoice schemas, mapped to Invoice attributes.
+_FIELDS = {
+    "InvoiceNo": "invoice_number",
+    "InvoiceCode": "invoice_code",
+    "IssueDate": "issue_date",
+    "InvoiceCheckCode": "check_code",
+    "MachineNo": "machine_number",
+    "TaxExclusiveTotalAmount": "amount_without_tax",
+    "TaxTotalAmount": "tax_amount",
+    "TaxInclusiveTotalAmount": "total_amount",
+    "InvoiceClerk": "issuer",
+    "Payee": "payee",
+    "Checker": "reviewer",
+    "Note": "note",
+}
+_PARTY_FIELDS = {"Name": "name", "TaxID": "tax_id", "AddrTel": "address_phone", "FinancialAccount": "bank_account"}
+_ITEM_FIELDS = {
+    "Item": "name",
+    "Specification": "specification",
+    "MeasurementDimension": "unit",
+    "Quantity": "quantity",
+    "Price": "unit_price",
+    "Amount": "amount",
+    "TaxScheme": "tax_rate",
+    "TaxAmount": "tax_amount",
+}
+# CustomData names that e-invoices put in OFD.xml, mapped to schema leaf names.
+# Names are compared after removing spaces and punctuation (see _custom_data_key).
+_CUSTOM_DATA = {
+    "发票号码": "InvoiceNo",
+    "发票代码": "InvoiceCode",
+    "开票日期": "IssueDate",
+    "校验码": "InvoiceCheckCode",
+    "机器编号": "MachineNo",
+    "合计金额": "TaxExclusiveTotalAmount",
+    "合计税额": "TaxTotalAmount",
+    "价税合计": "TaxInclusiveTotalAmount",
+    "购买方名称": "BuyerName",
+    "购买方纳税人识别号": "BuyerTaxID",
+    "购买方地址电话": "BuyerAddrTel",
+    "购买方开户行及账号": "BuyerFinancialAccount",
+    "销售方名称": "SellerName",
+    "销售方纳税人识别号": "SellerTaxID",
+    "销售方地址电话": "SellerAddrTel",
+    "销售方开户行及账号": "SellerFinancialAccount",
+    "开票人": "InvoiceClerk",
+    "收款人": "Payee",
+    "复核人": "Checker",
+    "复核": "Checker",
+    "备注": "Note",
+}
+# A source counts as an invoice only if it has at least one of these.
+_KEY_FIELDS = ("InvoiceNo", "InvoiceCode", "TaxInclusiveTotalAmount", "TaxExclusiveTotalAmount")
+
+_AMOUNT = re.compile(r"^-?\d+(?:\.\d+)?$")
+_DATE = re.compile(r"^(\d{4})\s*[年/.-]?\s*(\d{1,2})\s*[月/.-]?\s*(\d{1,2})\s*日?(?:[\sT]+\d{1,2}:\d{2}(?::\d{2})?)?$")
+
+
+@dataclass
+class Party:
+    """Buyer (购买方) or seller (销售方)."""
+
+    name: str | None = None
+    tax_id: str | None = None
+    address_phone: str | None = None
+    bank_account: str | None = None
+
+    def to_dict(self) -> dict[str, str | None]:
+        return {
+            "name": self.name,
+            "tax_id": self.tax_id,
+            "address_phone": self.address_phone,
+            "bank_account": self.bank_account,
+        }
+
+
+@dataclass
+class LineItem:
+    """One line of goods or services. Numbers are kept as decimal strings."""
+
+    name: str | None = None
+    specification: str | None = None
+    unit: str | None = None
+    quantity: str | None = None
+    unit_price: str | None = None
+    amount: str | None = None
+    tax_rate: str | None = None
+    tax_amount: str | None = None
+
+    def to_dict(self) -> dict[str, str | None]:
+        return {
+            "name": self.name,
+            "specification": self.specification,
+            "unit": self.unit,
+            "quantity": self.quantity,
+            "unit_price": self.unit_price,
+            "amount": self.amount,
+            "tax_rate": self.tax_rate,
+            "tax_amount": self.tax_amount,
+        }
+
+
+@dataclass
+class Invoice:
+    """Invoice data found in an OFD file.
+
+    Amounts are decimal strings such as ``"4449.00"`` so that no precision is lost.
+    ``issue_date`` is ``YYYY-MM-DD`` when the file's date could be read.
+    """
+
+    invoice_number: str | None = None
+    invoice_code: str | None = None
+    issue_date: str | None = None
+    check_code: str | None = None
+    machine_number: str | None = None
+    buyer: Party = field(default_factory=Party)
+    seller: Party = field(default_factory=Party)
+    amount_without_tax: str | None = None
+    tax_amount: str | None = None
+    total_amount: str | None = None
+    issuer: str | None = None
+    payee: str | None = None
+    reviewer: str | None = None
+    note: str | None = None
+    items: list[LineItem] = field(default_factory=list)
+    #: Where the values came from: "attachment", "custom_tags" and/or "custom_data".
+    sources: list[str] = field(default_factory=list)
+    #: Problems noticed in the data, such as totals that do not add up.
+    warnings: list[str] = field(default_factory=list)
+    #: Every value found, by element path, for fields this class has no attribute for.
+    raw: dict[str, list[str]] = field(default_factory=dict)
+
+    def to_dict(self, include_raw: bool = False) -> dict[str, Any]:
+        data: dict[str, Any] = {
+            "invoice_number": self.invoice_number,
+            "invoice_code": self.invoice_code,
+            "issue_date": self.issue_date,
+            "check_code": self.check_code,
+            "machine_number": self.machine_number,
+            "buyer": self.buyer.to_dict(),
+            "seller": self.seller.to_dict(),
+            "amount_without_tax": self.amount_without_tax,
+            "tax_amount": self.tax_amount,
+            "total_amount": self.total_amount,
+            "issuer": self.issuer,
+            "payee": self.payee,
+            "reviewer": self.reviewer,
+            "note": self.note,
+            "items": [item.to_dict() for item in self.items],
+            "sources": list(self.sources),
+            "warnings": list(self.warnings),
+        }
+        if include_raw:
+            data["raw"] = {path: list(values) for path, values in self.raw.items()}
+        return data
+
+
+@dataclass
+class _Source:
+    """Values from one place in the file: leaf path -> values, plus grouped line items."""
+
+    name: str
+    values: dict[str, list[str]] = field(default_factory=dict)
+    items: list[dict[str, str]] = field(default_factory=list)
+
+    def leaf(self, leaf_name: str) -> list[str]:
+        """Values of every path ending in ``leaf_name``."""
+        found: list[str] = []
+        for path, values in self.values.items():
+            if path.rsplit("/", 1)[-1] == leaf_name:
+                found.extend(values)
+        return found
+
+    def is_invoice(self) -> bool:
+        return any(self.leaf(name) for name in _KEY_FIELDS)
+
+
+def read_invoice(document: OFDDocument) -> Invoice | None:
+    """Collect invoice data from an opened document, or None if it holds none."""
+    sources = [
+        source
+        for source in (*_attachment_sources(document), *_tag_sources(document), _custom_data_source(document))
+        if source.is_invoice()
+    ]
+    if not sources:
+        return None
+
+    def first(leaf_name: str) -> str | None:
+        for source in sources:
+            for value in source.leaf(leaf_name):
+                if value:
+                    return value
+        return None
+
+    invoice = Invoice()
+    for leaf_name, attribute in _FIELDS.items():
+        setattr(invoice, attribute, first(leaf_name))
+    for prefix, party in (("Buyer", invoice.buyer), ("Seller", invoice.seller)):
+        for suffix, attribute in _PARTY_FIELDS.items():
+            setattr(party, attribute, first(prefix + suffix))
+
+    for source in sources:
+        items = source.items or _flat_items(source)
+        if items:
+            invoice.items = [_line_item(item) for item in items]
+            break
+
+    for source in sources:
+        if source.name not in invoice.sources:
+            invoice.sources.append(source.name)
+        for path, values in source.values.items():
+            invoice.raw.setdefault(path, list(values))
+
+    _normalise(invoice)
+    return invoice
+
+
+def _attachment_sources(document: OFDDocument) -> list[_Source]:
+    sources = []
+    package = document._package
+    for body in document._bodies:
+        if body.attachments is None:
+            continue
+        try:
+            listing = package.read_xml(body.attachments)
+        except OFDError as exc:
+            document.warnings.append(f"attachments: {exc}")
+            continue
+        for attachment in children(listing, "Attachment"):
+            location = child_text(attachment, "FileLoc")
+            path = package.resolve(body.attachments, location)
+            if path is None or not path.lower().endswith(".xml"):
+                continue
+            try:
+                root = package.read_xml(path)
+            except OFDError:
+                continue
+            sources.append(_read_tree("attachment", root, resolve=None))
+    return sources
+
+
+def _tag_sources(document: OFDDocument) -> list[_Source]:
+    sources = []
+    package = document._package
+
+    def resolve(page_ref: str | None, object_id: str) -> str | None:
+        page = document.page_by_id(page_ref) if page_ref else None
+        for candidate in [page] if page is not None else document.pages:
+            try:
+                text = candidate.object_text(object_id)
+            except OFDError:
+                continue
+            if text is not None:
+                return text
+        return None
+
+    for body in document._bodies:
+        if body.custom_tags is None:
+            continue
+        try:
+            listing = package.read_xml(body.custom_tags)
+        except OFDError as exc:
+            document.warnings.append(f"custom tags: {exc}")
+            continue
+        for tag in children(listing, "CustomTag"):
+            path = package.resolve(body.custom_tags, child_text(tag, "FileLoc"))
+            if path is None:
+                continue
+            try:
+                root = package.read_xml(path)
+            except OFDError as exc:
+                document.warnings.append(f"custom tags: {exc}")
+                continue
+            sources.append(_read_tree("custom_tags", root, resolve=resolve))
+    return sources
+
+
+def _custom_data_source(document: OFDDocument) -> _Source:
+    source = _Source("custom_data")
+    for name, value in document.info.custom_data.items():
+        leaf_name = _CUSTOM_DATA.get(_custom_data_key(name))
+        if leaf_name and value.strip():
+            source.values.setdefault(leaf_name, []).append(value.strip())
+    return source
+
+
+def _custom_data_key(name: str) -> str:
+    """``销售方地址、 电话`` and ``销售方地址电话`` name the same field."""
+    return re.sub(r"[\s、，,:：]", "", name)
+
+
+def _read_tree(name: str, root: ET.Element, resolve: Callable[[str | None, str], str | None] | None) -> _Source:
+    """Collect leaf values of an invoice XML tree.
+
+    A leaf is an element whose only children are ObjectRef elements (custom tags) or
+    that has no children at all (attachments). GoodsInfo elements group line items.
+    """
+    source = _Source(name)
+
+    def value_of(element: ET.Element) -> str | None:
+        references = list(children(element, "ObjectRef"))
+        if references and resolve is not None:
+            parts = []
+            for reference in references:
+                object_id = (reference.text or "").strip()
+                if object_id:
+                    text = resolve(reference.get("PageRef"), object_id)
+                    if text:
+                        parts.append(text)
+            value = "".join(parts).strip()
+        else:
+            value = (element.text or "").strip()
+        return value or None
+
+    def visit(element: ET.Element, path: list[str], depth: int) -> None:
+        element_name = local_name(element.tag)
+        if not element_name or depth > 16:
+            return
+        if element_name == "GoodsInfo":
+            item: dict[str, str] = {}
+            for leaf in element:
+                value = value_of(leaf)
+                if value is not None:
+                    item.setdefault(local_name(leaf.tag), value)
+            if item:
+                source.items.append(item)
+            return
+        element_children = [c for c in element if local_name(c.tag) and local_name(c.tag) != "ObjectRef"]
+        if not element_children:
+            value = value_of(element)
+            if value is not None:
+                source.values.setdefault("/".join([*path, element_name]), []).append(value)
+            return
+        for element_child in element_children:
+            visit(element_child, [*path, element_name], depth + 1)
+
+    for element_child in root:
+        visit(element_child, [], 0)
+    return source
+
+
+def _flat_items(source: _Source) -> list[dict[str, str]]:
+    """Line items written as repeated top-level elements (数电票 custom tags)."""
+    columns = {leaf: source.values.get(leaf, []) for leaf in _ITEM_FIELDS}
+    count = max((len(values) for values in columns.values()), default=0)
+    return [
+        {leaf: values[index] for leaf, values in columns.items() if index < len(values)}
+        for index in range(count)
+    ]
+
+
+def _line_item(values: dict[str, str]) -> LineItem:
+    return LineItem(**{attribute: values.get(leaf) for leaf, attribute in _ITEM_FIELDS.items()})
+
+
+def _normalise(invoice: Invoice) -> None:
+    for attribute in ("amount_without_tax", "tax_amount", "total_amount"):
+        setattr(invoice, attribute, _amount(getattr(invoice, attribute)))
+    for item in invoice.items:
+        item.amount = _amount(item.amount)
+        item.tax_amount = _amount(item.tax_amount)
+        item.unit_price = _amount(item.unit_price)
+        item.quantity = _amount(item.quantity)
+    invoice.issue_date = _date(invoice.issue_date)
+    for party in (invoice.buyer, invoice.seller):
+        if party.tax_id:
+            party.tax_id = re.sub(r"\s+", "", party.tax_id).upper()
+    if invoice.invoice_number:
+        invoice.invoice_number = re.sub(r"\s+", "", invoice.invoice_number)
+
+    totals = [_decimal(invoice.amount_without_tax), _decimal(invoice.tax_amount), _decimal(invoice.total_amount)]
+    if all(value is not None for value in totals):
+        without_tax, tax, total = totals
+        assert without_tax is not None and tax is not None and total is not None
+        if without_tax + tax != total:
+            invoice.warnings.append(
+                f"amount_without_tax + tax_amount != total_amount ({without_tax} + {tax} != {total})"
+            )
+
+
+def _amount(value: str | None) -> str | None:
+    """Strip currency signs, thousands separators and spaces from a money value."""
+    if value is None:
+        return None
+    cleaned = re.sub(r"[¥￥,，\s元]", "", value)
+    return cleaned if _AMOUNT.match(cleaned) else value
+
+
+def _decimal(value: str | None) -> Decimal | None:
+    if value is None or not _AMOUNT.match(value):
+        return None
+    try:
+        return Decimal(value)
+    except InvalidOperation:
+        return None
+
+
+def _date(value: str | None) -> str | None:
+    """``2024年05月28日``, ``20240528`` or ``2024/5/28`` become ``2024-05-28``."""
+    if value is None:
+        return None
+    match = _DATE.match(value.strip())
+    if not match:
+        return value
+    year, month, day = (int(part) for part in match.groups())
+    if not (1 <= month <= 12 and 1 <= day <= 31):
+        return value
+    return f"{year:04d}-{month:02d}-{day:02d}"

ofdkit/layout.py

@@ -0,0 +1,84 @@
+"""Reading order: turn positioned text runs into lines of plain text."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Protocol
+
+
+class _Run(Protocol):
+    text: str
+    x: float
+    y: float
+    size: float
+    width: float
+
+
+# Runs whose baselines differ by less than this share of the font size are one line.
+_SAME_LINE = 0.5
+# A horizontal gap wider than this share of the font size gets a space ...
+_WORD_GAP = 0.25
+# ... and a gap wider than this one marks separate columns.
+_COLUMN_GAP = 1.5
+# A vertical step larger than this many font sizes starts a new paragraph.
+_PARAGRAPH_GAP = 2.2
+# Smallest size used for tolerances, so tiny or missing font sizes still work.
+_MIN_SIZE = 1.0
+
+
+def page_text(runs: Sequence[_Run]) -> str:
+    """Join runs into text, top to bottom and left to right."""
+    lines = _group_lines([run for run in _dedupe(runs) if run.text.strip()])
+    out: list[str] = []
+    previous_y: float | None = None
+    previous_size = _MIN_SIZE
+    for line in lines:
+        size = max(min(run.size for run in line), _MIN_SIZE)
+        y = line[0].y
+        if previous_y is not None and y - previous_y > _PARAGRAPH_GAP * max(size, previous_size):
+            out.append("")
+        out.append(_join_line(line))
+        previous_y, previous_size = y, size
+    return "\n".join(out).strip("\n")
+
+
+def _dedupe(runs: Sequence[_Run]) -> list[_Run]:
+    """Drop runs drawn twice at the same spot, a common way to fake bold text."""
+    seen: set[tuple[str, int, int]] = set()
+    unique = []
+    for run in runs:
+        key = (run.text, round(run.x * 4), round(run.y * 4))
+        if key not in seen:
+            seen.add(key)
+            unique.append(run)
+    return unique
+
+
+def _group_lines(runs: list[_Run]) -> list[list[_Run]]:
+    lines: list[list[_Run]] = []
+    for run in sorted(runs, key=lambda r: (r.y, r.x)):
+        if lines:
+            line = lines[-1]
+            anchor = line[0]
+            tolerance = _SAME_LINE * max(min(run.size, anchor.size), _MIN_SIZE)
+            if abs(run.y - anchor.y) <= tolerance:
+                line.append(run)
+                continue
+        lines.append([run])
+    for line in lines:
+        line.sort(key=lambda r: r.x)
+    return lines
+
+
+def _join_line(line: list[_Run]) -> str:
+    parts = [line[0].text]
+    for previous, run in zip(line, line[1:]):
+        size = max(min(previous.size, run.size), _MIN_SIZE)
+        gap = run.x - (previous.x + previous.width)
+        if gap > _COLUMN_GAP * size:
+            parts.append("   ")
+        elif gap > _WORD_GAP * size:
+            parts.append(" ")
+        parts.append(run.text)
+    # Leading spaces are layout, not content, and would start a code block in Markdown.
+    return "".join(parts).strip()

ofdkit/markdown.py

@@ -0,0 +1,100 @@
+"""Markdown output: the document's text, plus an invoice summary table for e-invoices."""
+
+from __future__ import annotations
+
+import re
+
+from .document import OFDDocument
+from .errors import OFDError
+from .invoice import Invoice
+
+_INVOICE_ROWS = [
+    ("发票号码", lambda i: i.invoice_number),
+    ("发票代码", lambda i: i.invoice_code),
+    ("开票日期", lambda i: i.issue_date),
+    ("校验码", lambda i: i.check_code),
+    ("购买方名称", lambda i: i.buyer.name),
+    ("购买方纳税人识别号", lambda i: i.buyer.tax_id),
+    ("购买方地址电话", lambda i: i.buyer.address_phone),
+    ("购买方开户行及账号", lambda i: i.buyer.bank_account),
+    ("销售方名称", lambda i: i.seller.name),
+    ("销售方纳税人识别号", lambda i: i.seller.tax_id),
+    ("销售方地址电话", lambda i: i.seller.address_phone),
+    ("销售方开户行及账号", lambda i: i.seller.bank_account),
+    ("合计金额", lambda i: i.amount_without_tax),
+    ("合计税额", lambda i: i.tax_amount),
+    ("价税合计", lambda i: i.total_amount),
+    ("开票人", lambda i: i.issuer),
+    ("收款人", lambda i: i.payee),
+    ("复核人", lambda i: i.reviewer),
+    ("备注", lambda i: i.note),
+]
+_ITEM_COLUMNS = [
+    ("项目名称", "name"),
+    ("规格型号", "specification"),
+    ("单位", "unit"),
+    ("数量", "quantity"),
+    ("单价", "unit_price"),
+    ("金额", "amount"),
+    ("税率", "tax_rate"),
+    ("税额", "tax_amount"),
+]
+_INLINE_SPECIAL = re.compile(r"([\\`*_])")
+_LINE_START_SPECIAL = re.compile(r"^(\s*)([#>])", re.MULTILINE)
+
+
+def document_markdown(document: OFDDocument) -> str:
+    """Markdown for a whole document.
+
+    E-invoices start with a table of their fields. Multi-page documents get a heading per
+    page. Characters that Markdown would treat as formatting are escaped, so that invoice
+    item names such as ``*信息技术服务*`` keep their asterisks.
+    """
+    sections: list[str] = []
+    invoice = document.invoice()
+    if invoice is not None:
+        sections.append(invoice_markdown(invoice))
+
+    pages = document.pages
+    use_headings = invoice is not None or len(pages) > 1
+    for page in pages:
+        try:
+            text = escape(page.text())
+        except OFDError as exc:
+            document.warnings.append(f"page {page.index + 1}: {exc}")
+            text = ""
+        if use_headings:
+            heading = f"## 第 {page.index + 1} 页" if len(pages) > 1 else "## 原文"
+            sections.append(f"{heading}\n\n{text}".rstrip())
+        elif text:
+            sections.append(text)
+    return "\n\n".join(sections).strip() + "\n"
+
+
+def invoice_markdown(invoice: Invoice) -> str:
+    """A Markdown table of the invoice's fields, followed by its line items."""
+    lines = ["## 发票信息", "", "| 项目 | 内容 |", "| --- | --- |"]
+    for label, get in _INVOICE_ROWS:
+        value = get(invoice)
+        if value:
+            lines.append(f"| {label} | {_cell(value)} |")
+    if invoice.items:
+        lines += ["", "### 明细", ""]
+        columns = [(label, attribute) for label, attribute in _ITEM_COLUMNS if any(getattr(item, attribute) for item in invoice.items)]
+        lines.append("| " + " | ".join(label for label, _ in columns) + " |")
+        lines.append("|" + " --- |" * len(columns))
+        for item in invoice.items:
+            lines.append("| " + " | ".join(_cell(getattr(item, attribute) or "") for _, attribute in columns) + " |")
+    if invoice.warnings:
+        lines += ["", *[f"> 注意：{escape(warning)}" for warning in invoice.warnings]]
+    return "\n".join(lines)
+
+
+def escape(text: str) -> str:
+    """Escape characters that would turn plain text into Markdown formatting."""
+    text = _INLINE_SPECIAL.sub(r"\\\1", text)
+    return _LINE_START_SPECIAL.sub(r"\1\\\2", text)
+
+
+def _cell(value: str) -> str:
+    return escape(value).replace("|", "\\|").replace("\r", " ").replace("\n", " ")

ofdkit/markitdown_plugin.py

@@ -0,0 +1,55 @@
+"""MarkItDown plugin: convert OFD files to Markdown with ``markitdown --use-plugins``.
+
+Install with ``pip install "ofdkit[markitdown]"``. MarkItDown finds the plugin through the
+``markitdown.plugin`` entry point declared in ofdkit's package metadata.
+"""
+
+from __future__ import annotations
+
+import zipfile
+from typing import Any, BinaryIO
+
+from markitdown import DocumentConverter, DocumentConverterResult, StreamInfo
+
+from .document import OFDDocument
+from .markdown import document_markdown
+
+__plugin_interface_version__ = 1
+
+ACCEPTED_EXTENSIONS = (".ofd",)
+ACCEPTED_MIME_TYPES = ("application/ofd", "application/x-ofd")
+
+
+class OfdConverter(DocumentConverter):
+    """Converts OFD documents (GB/T 33190) to Markdown."""
+
+    def accepts(self, file_stream: BinaryIO, stream_info: StreamInfo, **kwargs: Any) -> bool:
+        if (stream_info.extension or "").lower() in ACCEPTED_EXTENSIONS:
+            return True
+        if (stream_info.mimetype or "").lower().split(";")[0].strip() in ACCEPTED_MIME_TYPES:
+            return True
+        return _looks_like_ofd(file_stream)
+
+    def convert(self, file_stream: BinaryIO, stream_info: StreamInfo, **kwargs: Any) -> DocumentConverterResult:
+        with OFDDocument(file_stream.read()) as document:
+            return DocumentConverterResult(markdown=document_markdown(document), title=document.info.title)
+
+
+def register_converters(markitdown: Any, **kwargs: Any) -> None:
+    """Called by MarkItDown when plugins are enabled."""
+    markitdown.register_converter(OfdConverter())
+
+
+def _looks_like_ofd(file_stream: BinaryIO) -> bool:
+    """A ZIP file whose root holds OFD.xml. The stream position is restored."""
+    position = file_stream.tell()
+    try:
+        if file_stream.read(4) != b"PK\x03\x04":
+            return False
+        file_stream.seek(position)
+        with zipfile.ZipFile(file_stream) as archive:
+            return any(name.lstrip("/").lower() == "ofd.xml" for name in archive.namelist())
+    except (zipfile.BadZipFile, OSError, ValueError, EOFError):
+        return False
+    finally:
+        file_stream.seek(position)