xml2table

A small, predictable Python SDK for converting XML and PDF documents to CSV, Excel, XML, and plain text.

• XML → CSV / Excel. One core recursive flattening function turns nested XML into flat rows; CSV and Excel are thin writers on top of it. No data loss by default: repeated elements can be joined into one cell, exploded into extra rows, or spread across indexed columns — you choose.
• PDF → XML. A structure-preserving extractor (pdfplumber-backed) groups a PDF's words into paragraphs and detects tables, keeping both in their original top-to-bottom reading order — no data lost, no tables flattened into loose words.
• PDF → text. A fast, lightweight raw-text extractor (pypdf-backed) that doesn't need table detection at all — just the PDF's text, in reading order, with its visual whitespace layout preserved by default.
• Small dependency footprint. Only openpyxl is required for the XML-to-table side. pandas (DataFrames), pypdf (PDF text), and pdfplumber (PDF XML/tables) are all optional extras — importing xml2table never requires any of them.
• Three ways in, for each conversion: one-line functions, a reusable converter object, or the xml2table CLI.

Install

pip install -e .             # from a checkout: XML -> CSV/Excel only
pip install -e ".[pandas]"   # + optional DataFrame support
pip install -e ".[pdf-text]" # + PDF -> text (pypdf only, lightweight)
pip install -e ".[pdf]"      # + PDF -> XML and text (pdfplumber + pypdf)

Quick start

from xml2table import xml_to_csv, xml_to_excel

xml_to_csv("orders.xml", "orders.csv")
xml_to_excel("orders.xml", "orders.xlsx")

Given:

<orders>
  <order id="1">
    <customer><name>Jane Doe</name></customer>
    <total>99.99</total>
  </order>
</orders>

you get one row per <order>:

Nested elements are flattened with .-separated keys, attributes get an @ prefix, and the record element (order here) is auto-detected as "the repeated child of the root". When detection is ambiguous, pass record_path explicitly.

Reusable converter

Parse once, write many times:

from xml2table import XMLConverter, FlattenOptions

converter = XMLConverter("orders.xml", options=FlattenOptions(record_path="Order"))
converter.to_csv("orders.csv")
converter.to_excel("orders.xlsx", sheet_name="Orders")
rows = converter.to_records()      # list[dict]
df = converter.to_dataframe()      # requires pandas

Handling repeated elements (array_mode)

Given an order with two line items, FlattenOptions.array_mode controls the shape of the output:

from xml2table import FlattenOptions, xml_to_records

xml_to_records("orders.xml", options=FlattenOptions(array_mode="explode"))

Multi-sheet Excel from one document

Turn different parts of the same XML document into separate, related sheets (e.g. an "orders" table and an "items" table):

from xml2table import xml_to_excel

xml_to_excel(
    "orders.xml", "orders.xlsx",
    sheets={"orders": "Order", "items": ".//Order/Items/Item"},
)

Record paths

record_path uses the same syntax as Element.findall (a subset of XPath): "Order", "Orders/Order", ".//Item", "Order[@status='shipped']", etc.

CLI (XML)

xml2table csv orders.xml orders.csv --record-path Order --array-mode explode
xml2table excel orders.xml orders.xlsx --sheet-name Orders
xml2table excel orders.xml orders.xlsx --sheet orders=Order --sheet items=".//Item"

Run xml2table csv --help or xml2table excel --help for all flags (--separator, --attribute-prefix, --no-attributes, --keep-namespaces, --delimiter, --encoding, ...).

PDF → XML / text

pdf_to_xml and pdf_to_text are two independent, purpose-built backends behind one options object and one CLI command:

• pdf_to_xml (pdfplumber) groups the PDF's words into paragraphs (by line, then by vertical gap) and detects tables separately via ruling lines or text alignment, then places both back in the order they appear on the page. Nothing is dropped, and table text never bleeds into surrounding paragraphs.
• pdf_to_text (pypdf) is a much lighter path: it just extracts each page's text in reading order, preserving the PDF's visual whitespace layout by default (so simple tables and columns still read naturally) without doing any table detection.

from xml2table import pdf_to_xml, pdf_to_text

pdf_to_xml("invoice.pdf", "invoice.xml")    # paragraphs + tables (needs xml2table[pdf])
pdf_to_text("invoice.pdf", "invoice.txt")   # fast raw text (needs xml2table[pdf-text])

invoice.xml looks like:

<document source="invoice.pdf" pages="1">
  <page number="1" width="595.28" height="841.89">
    <paragraph bbox="42.83,43.13,159.90,61.13">Invoice #1024</paragraph>
    <table bbox="40.00,220.00,540.00,316.00" rows="4" cols="3">
      <row><cell>Item</cell><cell>Qty</cell><cell>Price</cell></row>
      <row><cell>Widget</cell><cell>2</cell><cell>$10.00</cell></row>
      ...
    </table>
  </page>
</document>

invoice.txt is pypdf's layout-preserving text, e.g.:

Invoice #1024

Bill To: Jane Doe
123 Example Street
Springfield, USA

Thank you for your business. Payment is due within thirty days...

Item                                                          Qty        Price
Widget                                                        2          $10.00
...

Reuse one PDFConverter for both (it lazily parses with pdfplumber only if you call to_xml()/pages, and always uses pypdf for to_text()):

from xml2table import PDFConverter

converter = PDFConverter("invoice.pdf")
converter.to_xml("invoice.xml")
converter.to_text("invoice.txt")
for page in converter.pages:
    print(page.number, len(page.paragraphs), len(page.tables))

PDFOptions reference

CLI (PDF)

xml2table pdf invoice.pdf invoice.xml --to xml
xml2table pdf invoice.pdf invoice.txt --to text

Run xml2table pdf --help for all flags (--line-tolerance, --paragraph-gap, --cell-na, --page-separator, --no-layout).

Validation: tested on 1,200 financial-report PDFs

pdf_to_xml and pdf_to_text were benchmarked against 1,200 generated financial-report PDFs (balance sheets, income statements, cash-flow statements, MD&A-style narrative text, footnotes — real financial formatting: $1,234,567, (123,456) negatives, N/A blanks, multi-page, ruled and borderless tables) with exact ground truth for every paragraph and table cell, so the numbers below are measured, not estimated. Full methodology, the generator, and raw per-document results are in benchmarks/RESULTS.md.

The one real limitation, quantified: pdfplumber's default table finder needs ruling lines, so it doesn't detect borderless (text-only-aligned) tables — but nothing is lost when it doesn't: the un-detected table's text still comes through as ordinary paragraph text (pdf_to_text recall stays at 100%). We also tested the obvious "fix" — pdfplumber's table_settings override for borderless tables — across all 1,200 documents, and it made things worse: because the override applies to the whole page, it started misreading ordinary paragraph sentences as table cells, corrupting paragraph output in 97.9% of documents (paragraph fidelity dropped from 100% to 13.9%). We did not ship that as a recommended workaround; see PDFOptions.table_settings's docstring and benchmarks/RESULTS.md for the full numbers and why.

We could not download real financial filings for this test — this sandboxed session's network policy blocks direct access to sites like sec.gov — so the corpus is synthetic but built to real financial-statement conventions specifically so every value has a known-correct answer to grade against. benchmarks/RESULTS.md explains this in more detail and gives the exact commands to reproduce or extend the benchmark (e.g. against real filings, on a machine with broader network access).

FlattenOptions reference

Errors

All exceptions inherit from xml2table.XMLConversionError:

• XMLParseError — malformed XML input
• RecordPathNotFoundError — record_path matched nothing, or automatic record detection was ambiguous (the error message tells you what to pass)
• PDFExtractionError — a PDF file could not be opened or parsed
• MissingOptionalDependencyError — e.g. calling to_dataframe() without pandas, pdf_to_xml() without pdfplumber, or pdf_to_text() without pypdf, installed

Development

pip install -e ".[dev]"   # includes pandas, pdfplumber, pypdf, and fpdf2 (for regenerating PDF fixtures)
pytest
python examples/quickstart.py

Project layout:

src/xml2table/
  parser.py          # XML -> list[dict] flattening engine
  options.py         # FlattenOptions
  converter.py       # XMLConverter + module-level convenience functions
  writers/           # CSV and Excel output
  pdf_extract.py     # pdfplumber: PDF -> Document(pages of Paragraph/Table), in reading order
  pdf_xml_writer.py  # Document -> XML
  pdf_text_extract.py # pypdf: PDF -> plain text, independent of pdf_extract.py
  pdf_options.py     # PDFOptions
  pdf_converter.py   # PDFConverter + pdf_to_xml/pdf_to_text
  cli.py             # `xml2table` command-line tool
tests/
  fixtures/          # sample XML documents and PDF fixtures (fixtures/pdf/)
  test_*.py
examples/
  quickstart.py