pygexml 0.1.2__py3-none-any.whl

pygexml/__init__.py

@@ -0,0 +1,3 @@
+from .page import Page
+
+__all__ = ["Page"]

pygexml/geometry.py

@@ -0,0 +1,57 @@
+from dataclasses import dataclass
+
+
+class GeometryError(Exception):
+    pass
+
+
+@dataclass
+class Point:
+    x: int
+    y: int
+
+    def __str__(self) -> str:
+        return f"{self.x},{self.y}"
+
+
+@dataclass
+class Box:
+    top_left: Point
+    bottom_right: Point
+
+    def __post_init__(self) -> None:
+        if (
+            self.top_left.x > self.bottom_right.x
+            or self.top_left.y > self.bottom_right.y
+        ):
+            raise GeometryError("Box: top left is not top left")
+
+    def width(self) -> int:
+        return self.bottom_right.x - self.top_left.x
+
+    def height(self) -> int:
+        return self.bottom_right.y - self.top_left.y
+
+    def contains(self, point: Point) -> bool:
+        return (
+            self.top_left.x <= point.x <= self.bottom_right.x
+            and self.top_left.y <= point.y <= self.bottom_right.y
+        )
+
+
+@dataclass
+class Polygon:
+    points: list[Point]
+
+    def __post_init__(self) -> None:
+        if len(self.points) < 1:
+            raise GeometryError("Polygon: points must not be empty")
+
+    def bounding_box(self) -> Box:
+        min_x = min(point.x for point in self.points)
+        max_x = max(point.x for point in self.points)
+        min_y = min(point.y for point in self.points)
+        max_y = max(point.y for point in self.points)
+        return Box(
+            top_left=Point(x=min_x, y=min_y), bottom_right=Point(x=max_x, y=max_y)
+        )

pygexml/page.py

@@ -0,0 +1,188 @@
+from re import Pattern, compile
+from warnings import warn
+from dataclasses import dataclass
+from typing import ClassVar
+from collections.abc import Iterable
+from lxml import etree
+from lxml.etree import _Element as Element, QName
+
+from .geometry import Point, Polygon, GeometryError
+
+
+def find_child(element: Element, name: str) -> Element | None:
+    for child in element:
+        if QName(child).localname == name:
+            return child
+    return None
+
+
+def find_children(element: Element, name: str) -> Iterable[Element]:
+    return (child for child in element if QName(child).localname == name)
+
+
+class PageXMLError(Exception):
+    pass
+
+
+@dataclass
+class Coords:
+    polygon: Polygon
+
+    # Loose regex that allows for negative values that can be handled by
+    # our code. Context: PeroOCR sometimes produces PageXML with negative
+    # coordinate values.
+    # https://github.com/DCGM/pero-ocr/issues/84#issuecomment-3745059403
+    LOOSE_PATTERN: ClassVar[Pattern[str]] = compile(
+        r"^(-?[0-9]+,-?[0-9]+ )+(-?[0-9]+,-?[0-9]+)$"
+    )
+
+    # Regex from official Page-XML spec
+    STRICT_PATTERN: ClassVar[Pattern[str]] = compile(
+        r"^([0-9]+,[0-9]+ )+([0-9]+,[0-9]+)$"
+    )
+
+    _NOT_ENOUGH_POINTS: ClassVar[str] = "Coords: at least 2 Points are required"
+
+    def __post_init__(self) -> None:
+        if len(self.polygon.points) < 2:
+            raise PageXMLError(Coords._NOT_ENOUGH_POINTS)
+
+    def __str__(self) -> str:
+        return " ".join(str(p) for p in self.polygon.points)
+
+    @classmethod
+    def parse(cls, points_str: str) -> "Coords":
+
+        if not cls.LOOSE_PATTERN.match(points_str):
+            raise PageXMLError("Invalid Coords XML string")
+
+        if not cls.STRICT_PATTERN.match(points_str):
+            warn(
+                "Warning: Coords XML string does not match the PAGE XMl spec: "
+                + points_str
+            )
+
+        points: list[Point] = []
+        for pair_str in points_str.split(" "):
+            [x, y] = pair_str.split(",")
+            points.append(Point(x=int(x), y=int(y)))
+
+        try:
+            polygon = Polygon(points=points)
+        except GeometryError:
+            raise PageXMLError(cls._NOT_ENOUGH_POINTS)
+
+        return Coords(polygon=polygon)
+
+
+type ID = str
+
+
+@dataclass
+class TextLine:
+    id: ID
+    coords: Coords
+    text: str
+
+    def words(self) -> Iterable[str]:
+        return self.text.split()
+
+    @classmethod
+    def from_xml(cls, element: Element) -> "TextLine":
+        if QName(element).localname != "TextLine":
+            raise PageXMLError("TextLine: wrong element given")
+        if "id" not in element.attrib:
+            raise PageXMLError("TextLine: no id found")
+        coords_element = find_child(element, "Coords")
+        if coords_element is None:
+            raise PageXMLError("TextLine: no Coords found")
+        if "points" not in coords_element.attrib:
+            raise PageXMLError("TextLine: Coords has no points attribute")
+        text_equiv = find_child(element, "TextEquiv")
+        text_element = (
+            find_child(text_equiv, "Unicode") if text_equiv is not None else None
+        )
+        if text_element is None:
+            raise PageXMLError("TextLine: no text found")
+        return TextLine(
+            id=str(element.attrib["id"]),
+            coords=Coords.parse(str(coords_element.attrib["points"])),
+            text=text_element.text if text_element.text is not None else "",
+        )
+
+
+@dataclass
+class TextRegion:
+    id: ID
+    coords: Coords
+    textlines: dict[ID, TextLine]
+
+    @classmethod
+    def from_xml(cls, element: Element) -> "TextRegion":
+        if QName(element).localname != "TextRegion":
+            raise PageXMLError("TextRegion: wrong element given")
+        if "id" not in element.attrib:
+            raise PageXMLError("TextRegion: no id found")
+        coords_element = find_child(element, "Coords")
+        if coords_element is None:
+            raise PageXMLError("TextRegion: no Coords element found")
+        if "points" not in coords_element.attrib:
+            raise PageXMLError("TextRegion: Coords has no points attribute")
+        text_lines = find_children(element, "TextLine")
+
+        return TextRegion(
+            id=str(element.attrib["id"]),
+            coords=Coords.parse(str(coords_element.attrib["points"])),
+            textlines={
+                tl.id: tl for tl in (TextLine.from_xml(tl) for tl in text_lines)
+            },
+        )
+
+    def lookup_textline(self, id: ID) -> TextLine | None:
+        return self.textlines.get(id)
+
+    def all_text(self) -> Iterable[str]:
+        return (tl.text for tl in self.textlines.values())
+
+    def all_words(self) -> Iterable[str]:
+        return (w for tl in self.textlines.values() for w in tl.words())
+
+
+@dataclass
+class Page:
+    image_filename: str
+    regions: dict[ID, TextRegion]
+
+    @classmethod
+    def from_xml(cls, element: Element) -> "Page":
+        if QName(element).localname != "Page":
+            raise PageXMLError("Page: wrong element given")
+
+        if "imageFilename" not in element.attrib:
+            raise PageXMLError("Page: no filename found")
+
+        regions = find_children(element, "TextRegion")
+
+        return Page(
+            image_filename=str(element.attrib["imageFilename"]),
+            regions={
+                tr.id: tr for tr in (TextRegion.from_xml(region) for region in regions)
+            },
+        )
+
+    @classmethod
+    def from_xml_string(cls, xml_str: str) -> "Page":
+        root = etree.fromstring(xml_str.encode("utf-8"))
+        page_element = find_child(root, "Page")
+        if page_element is None:
+            raise PageXMLError("Page: no page element found")
+        return cls.from_xml(page_element)
+
+    def lookup_region(self, id: ID) -> TextRegion | None:
+        return self.regions.get(id)
+
+    def all_text(self) -> Iterable[str]:
+        return (line for region in self.regions.values() for line in region.all_text())
+
+    def all_words(self) -> Iterable[str]:
+        return (word for region in self.regions.values() for word in region.all_words())

pygexml/strategies.py

@@ -0,0 +1,69 @@
+# mypy: disallow_untyped_defs=False
+# mypy: disallow_untyped_calls=False
+
+import string
+
+import hypothesis.strategies as st
+
+from pygexml.geometry import Point, Box, Polygon
+from pygexml.page import Coords, Page, TextLine, TextRegion
+
+st_points = st.builds(Point, x=st.integers(min_value=0), y=st.integers(min_value=0))
+
+
+@st.composite
+def st_box_points(draw):
+    tl = draw(st_points)
+    br_x = draw(st.integers(min_value=tl.x + 1))
+    br_y = draw(st.integers(min_value=tl.y + 1))
+    br = Point(x=br_x, y=br_y)
+    return tl, br
+
+
+st_boxes = st.builds(
+    lambda pp: Box(top_left=pp[0], bottom_right=pp[1]), st_box_points()
+)
+
+st_polygons = st.builds(Polygon, st.lists(st_points, min_size=1))
+st_polygons2 = st.builds(Polygon, st.lists(st_points, min_size=2))
+
+st_coords = st.builds(Coords, polygon=st_polygons2)
+
+st_coords_strings = st.builds(str, st_coords)
+
+
+def st_xml_text(**kwargs):
+    xml_chars = (
+        st.characters(min_codepoint=0x20, max_codepoint=0xD7FF)
+        | st.characters(min_codepoint=0xE000, max_codepoint=0xFFFD)
+        | st.characters(min_codepoint=0x10000, max_codepoint=0x10FFFF)
+        | st.sampled_from(["\t", "\n"])
+    )
+    return st.text(alphabet=xml_chars, **kwargs)
+
+
+def st_simple_text(**kwargs):
+    simple = string.ascii_letters + string.digits + " _-"
+    return st.text(alphabet=simple, max_size=20, **kwargs)
+
+
+st_text_lines = st.builds(
+    TextLine, id=st_simple_text(), coords=st_coords, text=st_xml_text()
+)
+
+st_text_regions = st.builds(
+    TextRegion,
+    id=st_simple_text(),
+    coords=st_coords,
+    textlines=st.builds(
+        lambda lines: {l.id: l for l in lines}, st.lists(st_text_lines)
+    ),
+)
+
+
+@st.composite
+def st_pages(draw):
+    image_filename = draw(st_simple_text())
+    regions = {tr.id: tr for tr in draw(st.lists(st_text_regions))}
+    page = Page(image_filename=image_filename, regions=regions)
+    return page

pygexml-0.1.2.dist-info/METADATA

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: pygexml
+Version: 0.1.2
+Summary: A minimal Python wrapper around the PAGE-XML format for OCR output
+Author-email: Mirko Westermeier <mirko.westermeier@uni-muenster.de>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/SCDH/pygexml
+Project-URL: Repository, https://github.com/SCDH/pygexml
+Project-URL: Documentation, https://scdh.github.io/pygexml
+Project-URL: Issues, https://github.com/SCDH/pygexml/issues
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: lxml
+Provides-Extra: strategies
+Requires-Dist: hypothesis; extra == "strategies"
+Provides-Extra: dev
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pyright; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: lxml-stubs; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: hypothesis; extra == "test"
+Provides-Extra: docs
+Requires-Dist: pdoc; extra == "docs"
+Dynamic: license-file
+
+# pygexml
+
+A minimal Python wrapper around the [PAGE-XML][page-xml] format for OCR output.
+
+[![pygexml checks, tests and docs][workflows-badge]][workflows] [![API docs online][api-docs-badge]][api-docs]
+
+## Installation
+
+```
+pip install pygexml
+```
+
+Requires Python 3.12+.
+
+## Usage
+
+```python
+from pygexml import Page
+
+page = Page.from_xml_string(xml_string)
+
+for line in page.all_text():
+    print(line)
+```
+
+### Data model
+
+| Class | Import from |
+|---|---|
+| `Page` | `pygexml` |
+| `Page`, `TextRegion`, `TextLine`, `Coords` | `pygexml.page` |
+| `Point`, `Box`, `Polygon` | `pygexml.geometry` |
+
+`Page`, `TextRegion` and `TextLine` each expose `all_text()` and `all_words()` iterators.
+Lookups by ID are available via `lookup_region()` and `lookup_textline()`.
+
+Refer to the [online API docs][api-docs] for details.
+
+### Hypothesis strategies
+
+The `pygexml.strategies` module provides [Hypothesis][hypothesis] strategies for all pygexml types, ready to use in property-based tests - including downstream projects:
+
+```python
+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][api-docs-strategies] for details.
+
+## Development
+
+```bash
+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][api-docs] is published to GitHub Pages on every push to `main`.
+
+## Contributing
+
+[Bug reports, feature requests][gh-issues] and [pull requests][gh-prs] 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](CODE_OF_CONDUCT.md).
+
+## Copyright and License
+
+Copyright (c) 2026 [Mirko Westermeier][gh-memowe] (SCDH, University of Münster)
+
+Released under the [MIT License](LICENSE).
+
+[page-xml]: https://github.com/PRImA-Research-Lab/PAGE-XML
+[workflows]: https://github.com/SCDH/pygexml/actions/workflows/checks_tests_docs.yml
+[workflows-badge]: https://github.com/SCDH/pygexml/actions/workflows/checks_tests_docs.yml/badge.svg
+[hypothesis]: https://hypothesis.readthedocs.io
+[api-docs]: https://scdh.github.io/pygexml
+[api-docs-strategies]: https://scdh.github.io/pygexml/pygexml/strategies.html
+[api-docs-badge]: https://img.shields.io/badge/API%20docs-online-blue?logo=gitbook&logoColor=lightgrey
+[gh-issues]: https://github.com/SCDH/pygexml/issues
+[gh-prs]: https://github.com/SCDH/pygexml/pulls
+[gh-memowe]: https://github.com/memowe

pygexml-0.1.2.dist-info/RECORD

@@ -0,0 +1,10 @@
+pygexml/__init__.py,sha256=fCNsaocAimKd454bOvuxmABVYzJ1SlZJ5BmY9gztXdo,43
+pygexml/geometry.py,sha256=yr_hsKH52nsrPsFcki1e_I3pnu2wKNSjvoWDn13ciLs,1414
+pygexml/page.py,sha256=Ivd3PjC2d2wBQcH-ijxNg0NYXen7n9fh2cMQwNffic0,6081
+pygexml/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pygexml/strategies.py,sha256=JthqvLN6o3xEHZTLe8YprHMGwAeMOrbCFDBZIKjUjCs,1889
+pygexml-0.1.2.dist-info/licenses/LICENSE,sha256=-tfmDDwot09J3YfFKWMK3CRhPs_qZ9qMfTfXKk8jlE8,1061
+pygexml-0.1.2.dist-info/METADATA,sha256=W6e8DRdKxMJ2RgdaNhISPkC6sTv2nkMTRSVUed1I_ew,3714
+pygexml-0.1.2.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+pygexml-0.1.2.dist-info/top_level.txt,sha256=GwUE9XI9ezJT0rf_Kp-VBOJmRgo-fVWOXt0nCwxplIk,8
+pygexml-0.1.2.dist-info/RECORD,,

pygexml-0.1.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pygexml-0.1.2.dist-info/licenses/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2026 Mirko Westermeier
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

pygexml-0.1.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+pygexml