pygexml

A minimal Python wrapper around the PAGE-XML format for OCR output. Can also import ALTO-XML.

Installation

pip install pygexml

Requires Python 3.12+.

Usage

from pygexml import Page

page = Page.from_xml_file("docs/xml_file.xml")

for line in page.all_text():
    print(line)

All dataclasses are serializable with to_dict/from_dict and to_json/from_json via dataclasses-json.

Data model

Class	Import from
Page	pygexml
Page, TextRegion, TextLine, Coords, Label	pygexml.page
Point, Box, Polygon	pygexml.geometry

• Page, TextRegion and TextLine each expose all_text() and all_words() iterators.
• On Page, these respect the PAGE-XML reading order if present.
• Lookups by ID are available via lookup_region() and lookup_textline().
• The reading order is also accessible directly via regions_ordered().
• TextLine.confidence is read from PAGE-XML TextEquiv/@conf. ALTO confidence is not mapped because its String/@WC values are defined per word, below the granularity of this model.
• Page.labels and TextRegion.labels contain semantic PAGE-XML labels as set[Label]. Each Label has a required value and optional type and comments.

Refer to the online API docs for details.

Hypothesis strategies

The pygexml.strategies module provides Hypothesis strategies for all pygexml types, ready to use in property-based tests - including downstream projects:

from hypothesis import given
from pygexml.strategies import st_pages

@given(st_pages())
def test_my_page_processing(page):
    assert process(page) is not None

Refer to the pygexml.strategies API docs for details.

Development

pip install ".[dev,test,docs]"

black pygexml test          # format
mypy pygexml test           # type check
pyright pygexml test        # type check
pytest -v                   # tests
pdoc -o .api_docs ./pygexml # API docs

CI runs on Python 3.12, 3.13 and 3.14. API documentation is published to GitHub Pages on every push to main.

Contributing

Bug reports, feature requests and pull requests are welcome. Feel free to open draft pull requests early to invite discussion and collaboration.

Please note that this project has a Code of Conduct.

Copyright and License

Copyright (c) 2026 Mirko Westermeier, Katharina Dietz (SCDH, University of Münster)

Released under the MIT License.