xml2table 0.1.0__py3-none-any.whl

xml2table/__init__.py

@@ -0,0 +1,71 @@
+"""xml2table: convert XML and PDF documents to CSV, Excel, XML, and text.
+
+Quick start (XML -> CSV/Excel)::
+
+    from xml2table import xml_to_csv, xml_to_excel, FlattenOptions
+
+    xml_to_csv("orders.xml", "orders.csv")
+    xml_to_excel("orders.xml", "orders.xlsx", record_path="Order")
+
+    # Or, for repeated calls against the same document:
+    from xml2table import XMLConverter
+
+    converter = XMLConverter("orders.xml", options=FlattenOptions(record_path="Order"))
+    converter.to_csv("orders.csv")
+    converter.to_excel("orders.xlsx")
+    rows = converter.to_records()
+
+Quick start (PDF -> XML/text)::
+
+    from xml2table import pdf_to_xml, pdf_to_text
+
+    # paragraphs + tables, in reading order (pdfplumber; requires xml2table[pdf])
+    pdf_to_xml("invoice.pdf", "invoice.xml")
+
+    # fast reading-order plain text (pypdf; requires xml2table[pdf-text])
+    pdf_to_text("invoice.pdf", "invoice.txt")
+"""
+
+from .converter import (
+    XMLConverter,
+    xml_to_csv,
+    xml_to_dataframe,
+    xml_to_excel,
+    xml_to_records,
+)
+from .exceptions import (
+    MissingOptionalDependencyError,
+    PDFExtractionError,
+    RecordPathNotFoundError,
+    XMLConversionError,
+    XMLParseError,
+)
+from .options import FlattenOptions
+from .pdf_converter import PDFConverter, pdf_to_text, pdf_to_xml
+from .pdf_extract import Document, Page, Paragraph, Table
+from .pdf_options import PDFOptions
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "XMLConverter",
+    "FlattenOptions",
+    "xml_to_csv",
+    "xml_to_excel",
+    "xml_to_records",
+    "xml_to_dataframe",
+    "PDFConverter",
+    "PDFOptions",
+    "pdf_to_xml",
+    "pdf_to_text",
+    "Document",
+    "Page",
+    "Paragraph",
+    "Table",
+    "XMLConversionError",
+    "XMLParseError",
+    "RecordPathNotFoundError",
+    "MissingOptionalDependencyError",
+    "PDFExtractionError",
+    "__version__",
+]

xml2table/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

xml2table/cli.py

@@ -0,0 +1,186 @@
+"""Command-line interface for xml2table.
+
+Examples:
+    xml2table csv orders.xml orders.csv --record-path Order
+    xml2table excel orders.xml orders.xlsx --array-mode explode
+    xml2table excel orders.xml orders.xlsx --sheet orders=Order --sheet items=".//Item"
+    xml2table pdf invoice.pdf invoice.xml --to xml
+    xml2table pdf invoice.pdf invoice.txt --to text
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Dict, Optional, Sequence
+
+from .converter import xml_to_csv, xml_to_excel
+from .exceptions import XMLConversionError
+from .options import FlattenOptions
+from .pdf_converter import pdf_to_text, pdf_to_xml
+from .pdf_options import PDFOptions
+
+
+def _add_common_flags(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("input", help="Path to the input XML file")
+    parser.add_argument("output", help="Path to the output file")
+    parser.add_argument(
+        "--record-path",
+        default=None,
+        help="ElementTree-style path to the repeated record element, e.g. 'Order' or './/Item'",
+    )
+    parser.add_argument(
+        "--array-mode",
+        choices=["join", "explode", "index"],
+        default="join",
+        help="How repeated sibling elements are represented (default: join)",
+    )
+    parser.add_argument("--join-separator", default="; ", help="Separator used when --array-mode=join")
+    parser.add_argument("--separator", default=".", help="Separator used for nested key paths (default: '.')")
+    parser.add_argument("--attribute-prefix", default="@", help="Prefix for columns derived from XML attributes")
+    parser.add_argument("--no-attributes", action="store_true", help="Exclude XML attributes from the output")
+    parser.add_argument("--keep-namespaces", action="store_true", help="Keep XML namespace URIs in tag names")
+    parser.add_argument("--encoding", default="utf-8", help="Encoding for input/output text (default: utf-8)")
+
+
+def _options_from_args(args: argparse.Namespace) -> FlattenOptions:
+    return FlattenOptions(
+        record_path=args.record_path,
+        attribute_prefix=args.attribute_prefix,
+        separator=args.separator,
+        array_mode=args.array_mode,
+        join_separator=args.join_separator,
+        include_attributes=not args.no_attributes,
+        strip_namespaces=not args.keep_namespaces,
+        encoding=args.encoding,
+    )
+
+
+def _parse_sheet_spec(spec: str) -> tuple:
+    if "=" not in spec:
+        raise argparse.ArgumentTypeError(
+            f"invalid --sheet value {spec!r}; expected NAME=RECORD_PATH"
+        )
+    name, path = spec.split("=", 1)
+    if not name or not path:
+        raise argparse.ArgumentTypeError(
+            f"invalid --sheet value {spec!r}; expected NAME=RECORD_PATH"
+        )
+    return name, path
+
+
+def _add_pdf_flags(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("input", help="Path to the input PDF file")
+    parser.add_argument("output", help="Path to the output file")
+    parser.add_argument(
+        "--to",
+        choices=["xml", "text"],
+        required=True,
+        help="Output format: 'xml' (paragraphs + tables, via pdfplumber) or "
+        "'text' (fast reading-order plain text, via pypdf)",
+    )
+    parser.add_argument(
+        "--line-tolerance",
+        type=float,
+        default=3.0,
+        help="XML only. Max vertical gap (points) for words to be treated as the same line (default: 3.0)",
+    )
+    parser.add_argument(
+        "--paragraph-gap",
+        type=float,
+        default=6.0,
+        help="XML only. Min vertical gap (points) between lines to start a new paragraph (default: 6.0)",
+    )
+    parser.add_argument(
+        "--cell-na", default="", help="XML only. String used for empty table cells (default: '')"
+    )
+    parser.add_argument(
+        "--page-separator",
+        default="\n----- Page {page} -----\n",
+        help="Text only. Inserted between pages; '{page}' is replaced with the page number",
+    )
+    parser.add_argument(
+        "--no-layout",
+        action="store_true",
+        help="Text only. Use plain, whitespace-normalized text instead of "
+        "preserving the PDF's visual layout",
+    )
+
+
+def _pdf_options_from_args(args: argparse.Namespace) -> PDFOptions:
+    return PDFOptions(
+        line_tolerance=args.line_tolerance,
+        paragraph_gap=args.paragraph_gap,
+        cell_na=args.cell_na,
+        page_separator=args.page_separator,
+        keep_layout=not args.no_layout,
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="xml2table", description="Convert XML to CSV/Excel, or PDF to XML/text."
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    csv_parser = subparsers.add_parser("csv", help="Convert XML to CSV")
+    _add_common_flags(csv_parser)
+    csv_parser.add_argument("--delimiter", default=",", help="Field delimiter (default: ',')")
+
+    excel_parser = subparsers.add_parser("excel", help="Convert XML to Excel (.xlsx)")
+    _add_common_flags(excel_parser)
+    excel_parser.add_argument("--sheet-name", default="Sheet1", help="Sheet name for single-sheet output")
+    excel_parser.add_argument(
+        "--sheet",
+        action="append",
+        dest="sheets",
+        default=None,
+        metavar="NAME=RECORD_PATH",
+        type=_parse_sheet_spec,
+        help="Add a named sheet built from its own record path; repeatable. "
+        "When given, produces a multi-sheet workbook and ignores --record-path/--sheet-name.",
+    )
+
+    pdf_parser = subparsers.add_parser(
+        "pdf", help="Convert PDF to XML or text, preserving paragraphs and tables"
+    )
+    _add_pdf_flags(pdf_parser)
+
+    return parser
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    try:
+        if args.command == "csv":
+            options = _options_from_args(args)
+            path = xml_to_csv(args.input, args.output, options=options, delimiter=args.delimiter)
+        elif args.command == "excel":
+            options = _options_from_args(args)
+            sheets: Optional[Dict[str, str]] = dict(args.sheets) if args.sheets else None
+            path = xml_to_excel(
+                args.input,
+                args.output,
+                options=options,
+                sheet_name=args.sheet_name,
+                sheets=sheets,
+            )
+        elif args.command == "pdf":
+            pdf_options = _pdf_options_from_args(args)
+            convert = pdf_to_xml if args.to == "xml" else pdf_to_text
+            path = convert(args.input, args.output, options=pdf_options)
+        else:  # pragma: no cover - argparse enforces valid choices
+            parser.error(f"unknown command: {args.command}")
+            return 2
+    except XMLConversionError as exc:
+        print(f"xml2table: error: {exc}", file=sys.stderr)
+        return 1
+
+    print(f"Wrote {path}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

xml2table/converter.py

@@ -0,0 +1,168 @@
+"""High-level, user-facing conversion API."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, List, Mapping, Optional, Union
+
+from .exceptions import MissingOptionalDependencyError
+from .options import FlattenOptions
+from .parser import XmlSource, parse_to_records, union_columns
+from .writers import write_csv, write_excel, write_workbook
+
+
+class XMLConverter:
+    """Convert one XML document into rows, CSV, Excel, or a DataFrame.
+
+    Parsing happens once, lazily, on first access and is cached; call
+    :meth:`to_records` (or any of the write methods) as many times as you
+    like without re-parsing.
+
+    Example:
+        >>> converter = XMLConverter("orders.xml", options=FlattenOptions(record_path="Order"))
+        >>> converter.to_csv("orders.csv")
+        >>> converter.to_excel("orders.xlsx")
+    """
+
+    def __init__(self, source: XmlSource, options: Optional[FlattenOptions] = None) -> None:
+        self._source = source
+        self.options = options or FlattenOptions()
+        self._records: Optional[List[Dict[str, Any]]] = None
+
+    @classmethod
+    def from_string(cls, xml_string: Union[str, bytes], options: Optional[FlattenOptions] = None) -> "XMLConverter":
+        """Build a converter from an in-memory XML string or bytes."""
+        return cls(xml_string, options=options)
+
+    @classmethod
+    def from_file(cls, path: Union[str, Path], options: Optional[FlattenOptions] = None) -> "XMLConverter":
+        """Build a converter from a file path."""
+        return cls(Path(path), options=options)
+
+    def to_records(self) -> List[Dict[str, Any]]:
+        """Return the flattened rows as a list of plain ``dict`` objects."""
+        if self._records is None:
+            self._records = parse_to_records(self._source, self.options)
+        return self._records
+
+    @property
+    def columns(self) -> List[str]:
+        """Column names, in first-seen order across all rows."""
+        return union_columns(self.to_records())
+
+    def to_dataframe(self):
+        """Return the flattened rows as a :class:`pandas.DataFrame`.
+
+        Requires the optional ``pandas`` dependency
+        (``pip install xml2table[pandas]``).
+        """
+        try:
+            import pandas as pd
+        except ImportError as exc:  # pragma: no cover - exercised only without pandas
+            raise MissingOptionalDependencyError(
+                "pandas is required for to_dataframe(); install it with "
+                "'pip install xml2table[pandas]'"
+            ) from exc
+        return pd.DataFrame(self.to_records(), columns=self.columns)
+
+    def to_csv(
+        self,
+        destination: Union[str, Path],
+        *,
+        columns: Optional[List[str]] = None,
+        delimiter: str = ",",
+        encoding: Optional[str] = None,
+    ) -> Path:
+        """Write the flattened rows to a CSV file and return its path."""
+        return write_csv(
+            self.to_records(),
+            destination,
+            columns=columns,
+            delimiter=delimiter,
+            encoding=encoding or self.options.encoding,
+        )
+
+    def to_excel(
+        self,
+        destination: Union[str, Path],
+        *,
+        sheet_name: str = "Sheet1",
+        columns: Optional[List[str]] = None,
+    ) -> Path:
+        """Write the flattened rows to a single-sheet ``.xlsx`` file and return its path."""
+        return write_excel(self.to_records(), destination, sheet_name=sheet_name, columns=columns)
+
+    def __len__(self) -> int:
+        return len(self.to_records())
+
+    def __repr__(self) -> str:  # pragma: no cover - cosmetic
+        return f"XMLConverter(options={self.options!r})"
+
+
+def xml_to_records(source: XmlSource, *, options: Optional[FlattenOptions] = None, record_path: Optional[str] = None) -> List[Dict[str, Any]]:
+    """Parse XML into a list of flat row dicts. See :class:`FlattenOptions` for tuning."""
+    opts = _resolve_options(options, record_path)
+    return XMLConverter(source, options=opts).to_records()
+
+
+def xml_to_dataframe(source: XmlSource, *, options: Optional[FlattenOptions] = None, record_path: Optional[str] = None):
+    """Parse XML directly into a :class:`pandas.DataFrame` (requires ``pandas``)."""
+    opts = _resolve_options(options, record_path)
+    return XMLConverter(source, options=opts).to_dataframe()
+
+
+def xml_to_csv(
+    source: XmlSource,
+    destination: Union[str, Path],
+    *,
+    options: Optional[FlattenOptions] = None,
+    record_path: Optional[str] = None,
+    columns: Optional[List[str]] = None,
+    delimiter: str = ",",
+) -> Path:
+    """Convert an XML document straight to a CSV file.
+
+    ``record_path`` is a convenience shortcut for ``options.record_path``
+    when you don't need to customize anything else.
+    """
+    opts = _resolve_options(options, record_path)
+    return XMLConverter(source, options=opts).to_csv(destination, columns=columns, delimiter=delimiter)
+
+
+def xml_to_excel(
+    source: XmlSource,
+    destination: Union[str, Path],
+    *,
+    options: Optional[FlattenOptions] = None,
+    record_path: Optional[str] = None,
+    sheet_name: str = "Sheet1",
+    columns: Optional[List[str]] = None,
+    sheets: Optional[Mapping[str, str]] = None,
+) -> Path:
+    """Convert an XML document straight to an ``.xlsx`` file.
+
+    Pass ``sheets`` (a mapping of sheet name -> record path) to produce a
+    multi-sheet workbook from several independent record paths within the
+    *same* document, e.g.::
+
+        xml_to_excel(
+            "orders.xml", "orders.xlsx",
+            sheets={"orders": "Order", "items": ".//Order/Items/Item"},
+        )
+    """
+    if sheets:
+        base_options = options or FlattenOptions()
+        sheet_rows = {
+            name: parse_to_records(source, base_options.with_record_path(path))
+            for name, path in sheets.items()
+        }
+        return write_workbook(sheet_rows, destination)
+
+    opts = _resolve_options(options, record_path)
+    return XMLConverter(source, options=opts).to_excel(destination, sheet_name=sheet_name, columns=columns)
+
+
+def _resolve_options(options: Optional[FlattenOptions], record_path: Optional[str]) -> FlattenOptions:
+    if record_path is None:
+        return options or FlattenOptions()
+    return (options or FlattenOptions()).with_record_path(record_path)

xml2table/exceptions.py

@@ -0,0 +1,28 @@
+"""Exception hierarchy for xml2table."""
+
+from __future__ import annotations
+
+
+class XMLConversionError(Exception):
+    """Base class for all errors raised by xml2table."""
+
+
+class XMLParseError(XMLConversionError):
+    """The input could not be parsed as XML."""
+
+
+class RecordPathNotFoundError(XMLConversionError):
+    """No unambiguous set of record elements could be found.
+
+    Raised when ``record_path`` is not supplied and the document's structure
+    is ambiguous (e.g. more than one repeated child element at the root),
+    or when a supplied ``record_path`` matches nothing.
+    """
+
+
+class MissingOptionalDependencyError(XMLConversionError):
+    """An optional dependency (e.g. pandas) is required but not installed."""
+
+
+class PDFExtractionError(XMLConversionError):
+    """A PDF document could not be opened or parsed."""

xml2table/options.py

@@ -0,0 +1,66 @@
+"""Configuration for how XML is flattened into rows."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from typing import Optional
+
+_VALID_ARRAY_MODES = ("join", "explode", "index")
+
+
+@dataclass(frozen=True)
+class FlattenOptions:
+    """Controls how nested/repeated XML structure becomes flat rows.
+
+    Attributes:
+        record_path: An :mod:`xml.etree.ElementTree`-style path (e.g.
+            ``"Order"``, ``"Orders/Order"``, ``".//Item"``) identifying the
+            elements that become one row each. If ``None``, xml2table tries
+            to infer the repeated element automatically and raises
+            :class:`~xml2table.exceptions.RecordPathNotFoundError` if the
+            structure is ambiguous.
+        attribute_prefix: Prefix used for keys derived from XML attributes.
+        text_key: Key used for an element's own text when the element also
+            has attributes or children (so the text isn't ambiguous with a
+            child field).
+        separator: Separator used when joining nested key paths, e.g.
+            ``"address.city"``.
+        array_mode: How repeated sibling elements are represented:
+
+            * ``"join"`` (default) - collapse repeated values into a single
+              cell, joined by ``join_separator``. Cheapest, one row per
+              record, lossy for structured children.
+            * ``"index"`` - keep every repeated value but disambiguate keys
+              with a numeric index, e.g. ``item.0.name``, ``item.1.name``.
+              One row per record, no data loss, wide output.
+            * ``"explode"`` - cartesian-expand repeated children into extra
+              rows (similar to a SQL join). No data loss, tall output.
+        join_separator: Separator used to join values when ``array_mode`` is
+            ``"join"``.
+        include_attributes: Whether XML attributes are included as columns.
+        strip_namespaces: Whether XML namespace URIs (``{uri}tag``) are
+            stripped from tag and attribute names.
+        encoding: Text encoding used when reading/writing files.
+    """
+
+    record_path: Optional[str] = None
+    attribute_prefix: str = "@"
+    text_key: str = "#text"
+    separator: str = "."
+    array_mode: str = "join"
+    join_separator: str = "; "
+    include_attributes: bool = True
+    strip_namespaces: bool = True
+    encoding: str = "utf-8"
+
+    def __post_init__(self) -> None:
+        if self.array_mode not in _VALID_ARRAY_MODES:
+            raise ValueError(
+                f"array_mode must be one of {_VALID_ARRAY_MODES!r}, got {self.array_mode!r}"
+            )
+        if not self.separator:
+            raise ValueError("separator must be a non-empty string")
+
+    def with_record_path(self, record_path: Optional[str]) -> "FlattenOptions":
+        """Return a copy of these options with ``record_path`` overridden."""
+        return replace(self, record_path=record_path)