pygexml 0.1.2__tar.gz

pygexml-0.1.2/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,89 @@
+# 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/pygexml/__init__.py

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

pygexml-0.1.2/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-0.1.2/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-0.1.2/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/pygexml.egg-info/PKG-INFO

@@ -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/pygexml.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+pygexml/__init__.py
+pygexml/geometry.py
+pygexml/page.py
+pygexml/py.typed
+pygexml/strategies.py
+pygexml.egg-info/PKG-INFO
+pygexml.egg-info/SOURCES.txt
+pygexml.egg-info/dependency_links.txt
+pygexml.egg-info/requires.txt
+pygexml.egg-info/top_level.txt
+test/test_geometry.py
+test/test_page.py

pygexml-0.1.2/pygexml.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pygexml-0.1.2/pygexml.egg-info/requires.txt

@@ -0,0 +1,17 @@
+lxml
+
+[dev]
+mypy
+pyright
+black
+lxml-stubs
+
+[docs]
+pdoc
+
+[strategies]
+hypothesis
+
+[test]
+pytest
+hypothesis

pygexml-0.1.2/pygexml.egg-info/top_level.txt

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

pygexml-0.1.2/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pygexml"
+version = "0.1.2"
+description = "A minimal Python wrapper around the PAGE-XML format for OCR output"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.12"
+authors = [
+    { name = "Mirko Westermeier", email = "mirko.westermeier@uni-muenster.de" },
+]
+dependencies = [
+    "lxml",
+]
+
+[project.urls]
+Homepage = "https://github.com/SCDH/pygexml"
+Repository = "https://github.com/SCDH/pygexml"
+Documentation = "https://scdh.github.io/pygexml"
+Issues = "https://github.com/SCDH/pygexml/issues"
+
+[tool.setuptools.package-data]
+pygexml = ["py.typed"]
+
+[project.optional-dependencies]
+strategies = ["hypothesis"]
+dev = ["mypy", "pyright", "black", "lxml-stubs"]
+test = ["pytest", "hypothesis"]
+docs = ["pdoc"]
+
+[tool.setuptools]
+packages = ["pygexml"]
+
+[tool.mypy]
+strict = true

pygexml-0.1.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pygexml-0.1.2/test/test_geometry.py

@@ -0,0 +1,114 @@
+import pytest
+from hypothesis import given, strategies as st
+
+from pygexml.strategies import *
+from pygexml.geometry import *
+
+############## Tests for Point #####################
+
+
+@given(st.integers(min_value=0), st.integers(min_value=0))
+def test_point_construction(x: int, y: int) -> None:
+    point = Point(x=x, y=y)
+    assert point.x == x
+    assert point.y == y
+
+
+@given(st.integers(min_value=0), st.integers(min_value=0))
+def test_point_stringification(x: int, y: int) -> None:
+    point = Point(x=x, y=y)
+    assert str(point) == f"{x},{y}"
+
+
+############## Tests for Box ####################
+
+
+def test_box_simple_example() -> None:
+    p17 = Point(17, 17)
+    p42 = Point(42, 42)
+    box = Box(top_left=p17, bottom_right=p42)
+    assert box.top_left == p17
+    assert box.bottom_right == p42
+    assert box.width() == 25
+    assert box.height() == 25
+
+
+@given(st_box_points())
+def test_box_construction(pp: tuple[Point, Point]) -> None:
+    tl, br = pp
+    box = Box(top_left=tl, bottom_right=br)
+    assert box.top_left == tl
+    assert box.bottom_right == br
+
+
+@given(st_box_points())
+def test_box_construction_exception(pp: tuple[Point, Point]) -> None:
+    tl, br = pp
+    with pytest.raises(Exception, match="top left is not top left"):
+        Box(top_left=br, bottom_right=tl)  # flipped points!
+
+
+@given(st_boxes)
+def test_box_width(box: Box) -> None:
+    assert box.width() == abs(box.bottom_right.x - box.top_left.x)
+
+
+@given(st_boxes)
+def test_box_height(box: Box) -> None:
+    assert box.height() == abs(box.bottom_right.y - box.top_left.y)
+
+
+def test_box_simple_contains() -> None:
+    box = Box(Point(17, 17), Point(42, 42))
+    assert box.contains(Point(23, 37))
+    assert not box.contains(Point(23, 666))
+
+
+@given(st_points, st_boxes)
+def test_box_containment(point: Point, box: Box) -> None:
+    assert box.contains(point) == (
+        box.top_left.x <= point.x <= box.bottom_right.x
+        and box.top_left.y <= point.y <= box.bottom_right.y
+    )
+
+
+############## Tests for Polygon ####################
+
+
+def test_polygon_simple_example() -> None:
+    p17 = Point(17, 17)
+    p42 = Point(42, 42)
+    polygon = Polygon(points=[p17, p42])
+    assert polygon.points == [p17, p42]
+    assert polygon.bounding_box().top_left == p17
+    assert polygon.bounding_box().bottom_right == p42
+
+
+@given(st.lists(st_points, min_size=1))
+def test_polygon_construction(points: list[Point]) -> None:
+    polygon = Polygon(points=points)
+    assert polygon.points == points
+
+
+def test_polygon_construction_without_points() -> None:
+    with pytest.raises(GeometryError, match="Polygon: points must not be empty"):
+        Polygon(points=[])
+
+
+@given(st_polygons)
+def test_polygon_bounding_box_corners(polygon: Polygon) -> None:
+    points = polygon.points
+    min_x = min(point.x for point in points)
+    max_x = max(point.x for point in points)
+    min_y = min(point.y for point in points)
+    max_y = max(point.y for point in points)
+    bounding_box = polygon.bounding_box()
+    assert bounding_box.top_left == Point(x=min_x, y=min_y)
+    assert bounding_box.bottom_right == Point(x=max_x, y=max_y)
+
+
+@given(st_polygons)
+def test_polygon_bounding_box_contains(polygon: Polygon) -> None:
+    bounding_box = polygon.bounding_box()
+    for point in polygon.points:
+        assert bounding_box.contains(point)

pygexml-0.1.2/test/test_page.py

@@ -0,0 +1,400 @@
+import pytest
+from hypothesis import given, assume
+import hypothesis.strategies as st
+from lxml import etree
+
+from pygexml.strategies import *
+from pygexml.geometry import Point, Polygon
+from pygexml.page import Coords, ID, TextLine, TextRegion, Page
+
+############## Tests for Coords ####################
+
+
+def test_coords_example() -> None:
+    polygon = Polygon(points=[Point(1, 2), Point(3, 4)])
+    coords = Coords(polygon=polygon)
+    assert coords.polygon == polygon
+
+
+def test_coords_with_not_enough_points() -> None:
+    with pytest.raises(Exception, match="at least 2 Points"):
+        Coords(polygon=Polygon(points=[Point(17, 42)]))
+
+
+def test_coords_stringification() -> None:
+    coords = Coords(polygon=Polygon(points=[Point(1, 2), Point(17, 42)]))
+    assert str(coords) == "1,2 17,42"
+
+
+def test_coords_parse_example() -> None:
+    coords = Coords.parse("1,2 17,42")
+    assert coords.polygon.points == [Point(1, 2), Point(17, 42)]
+
+
+def test_coords_parse_invalid_inputs() -> None:
+    with pytest.raises(Exception, match="Invalid Coords XML string"):
+        Coords.parse("17,42 666,42 SCDH, yay!")
+    with pytest.raises(Exception, match="Invalid Coords XML string"):
+        Coords.parse("")
+    with pytest.raises(Exception, match="Invalid Coords XML string"):
+        Coords.parse("17,42")
+
+
+def test_coords_allow_for_simple_negative_coordinates() -> None:
+    with pytest.warns(
+        UserWarning, match=r".*does not match the PAGE XMl spec: 1,-2 -3,4"
+    ):
+        coords = Coords.parse("1,-2 -3,4")
+        assert coords.polygon.points == [Point(1, -2), Point(-3, 4)]
+
+
+@given(st_coords)
+def test_coords_parse_arbitrary(coords: Coords) -> None:
+    assert Coords.parse(str(coords)) == coords
+
+
+@given(st_coords_strings)
+def test_coords_stringify_arbitrary(coords_str: str) -> None:
+    coords_object = Coords.parse(coords_str)
+    assert str(coords_object) == coords_str
+
+
+############## Tests for TextLines ####################
+
+
+def test_textline_simple_parsing_example() -> None:
+    tl = TextLine.from_xml(etree.fromstring("""
+        <TextLine id="tl-id">
+            <Coords points="17,42 1,2"/>
+            <TextEquiv>
+                <Unicode>tl-text</Unicode>
+            </TextEquiv>
+        </TextLine>
+    """))
+    assert tl.id == "tl-id"
+    assert tl.coords == Coords.parse("17,42 1,2")
+    assert tl.text == "tl-text"
+
+
+def test_textline_wrong_element() -> None:
+    with pytest.raises(Exception, match="wrong element given"):
+        TextLine.from_xml(etree.fromstring("<WRONG>!!!</WRONG>"))
+
+
+def test_textline_no_id() -> None:
+    xml = etree.fromstring("<TextLine></TextLine>")
+    with pytest.raises(Exception, match="no id found"):
+        TextLine.from_xml(xml)
+
+
+def test_textline_no_coords() -> None:
+    xml = etree.fromstring("""
+        <TextLine id="tl-id">
+            <TextEquiv>
+                <Unicode>tl-text</Unicode>
+            </TextEquiv>
+        </TextLine>
+    """)
+    with pytest.raises(Exception, match="no Coords found"):
+        TextLine.from_xml(xml)
+
+
+def test_textline_no_text() -> None:
+    xml = etree.fromstring("""
+        <TextLine id="tl-id">
+            <Coords points="0,0 10,0 10,10 0,10"/>
+            <TextEquiv>
+            </TextEquiv>
+        </TextLine>
+    """)
+    with pytest.raises(Exception, match="no text found"):
+        TextLine.from_xml(xml)
+
+
+def test_textline_empty_text() -> None:
+    xml = etree.fromstring("""
+        <TextLine id="tl-id">
+            <Coords points="1,2 3,4"/>
+            <TextEquiv>
+                <Unicode/>
+            </TextEquiv>
+        </TextLine>
+    """)
+    assert TextLine.from_xml(xml).text == ""
+
+
+def test_textline_simple_words() -> None:
+    tl = TextLine("", Coords.parse("1,2 3,4"), "foo  bar baz ")
+    assert tl.words() == ["foo", "bar", "baz"]
+
+
+@given(st_text_lines)
+def test_textline_words(tl: TextLine) -> None:
+    assert tl.words() == tl.text.split()
+
+
+####### Tests for TextRegion ###############
+
+
+def test_textregion_simple_parsing_example() -> None:
+    tr = TextRegion.from_xml(etree.fromstring("""
+        <TextRegion id="tr-id">
+            <Coords points="1,2 8,9"/>
+            <TextLine id="tl-1">
+                <Coords points="17,42 1,2"/>
+                <TextEquiv>
+                    <Unicode>bla</Unicode>
+                </TextEquiv>
+            </TextLine>
+
+            <TextLine id="tl-2">
+                <Coords points="20,38 2,2"/>
+                <TextEquiv>
+                    <Unicode>blub</Unicode>
+                </TextEquiv>
+            </TextLine>
+        </TextRegion>
+        """))
+    assert tr.id == "tr-id"
+    assert tr.coords == Coords.parse("1,2 8,9")
+    assert tr.textlines == {
+        "tl-1": TextLine(
+            id="tl-1",
+            coords=Coords.parse("17,42 1,2"),
+            text="bla",
+        ),
+        "tl-2": TextLine(
+            id="tl-2",
+            coords=Coords.parse("20,38 2,2"),
+            text="blub",
+        ),
+    }
+
+
+def test_textregion_wrong_element() -> None:
+    with pytest.raises(Exception, match="wrong element given"):
+        TextRegion.from_xml(etree.fromstring("<WRONG>!!!</WRONG>"))
+
+
+def test_textregion_no_id() -> None:
+    xml = etree.fromstring("<TextRegion></TextRegion>")
+    with pytest.raises(Exception, match="no id found"):
+        TextRegion.from_xml(xml)
+
+
+def test_textregion_no_coords() -> None:
+    xml = etree.fromstring("""
+        <TextRegion id="tr-id">
+            <TextLine id="tl-1">
+                <TextEquiv>
+                    <Unicode>bla</Unicode>
+                </TextEquiv>
+            </TextLine>
+        </TextRegion>
+    """)
+    with pytest.raises(Exception, match="no Coords element found"):
+        TextRegion.from_xml(xml)
+
+
+@given(st_text_lines, st_text_regions)
+def test_textregion_line_lookup(line: TextLine, region: TextRegion) -> None:
+    assume(not line.id in region.textlines)
+    region.textlines[line.id] = line
+    assert region.lookup_textline(line.id) == line
+
+
+@given(st.text(), st_text_regions)
+def test_textregion_line_lookup_not_found(id: ID, region: TextRegion) -> None:
+    assume(not id in region.textlines)
+    assert region.lookup_textline(id) is None
+
+
+def test_textregion_all_text_and_words() -> None:
+    tr = TextRegion(
+        id="a",
+        coords=Coords.parse("1,2 3,4"),
+        textlines={
+            "b": TextLine(id="b", coords=Coords.parse("2,3 4,5"), text="foo"),
+            "c": TextLine(id="c", coords=Coords.parse("2,3 4,5"), text="bar  baz "),
+        },
+    )
+    assert list(tr.all_text()) == ["foo", "bar  baz "]
+    assert list(tr.all_words()) == ["foo", "bar", "baz"]
+
+
+@given(st_text_regions)
+def test_textregion_all_arbitrary_text_and_words(region: TextRegion) -> None:
+    assert list(region.all_text()) == [tl.text for tl in region.textlines.values()]
+    assert list(region.all_words()) == [
+        w for tl in region.textlines.values() for w in tl.words()
+    ]
+
+
+############### Tests for Page ####################
+
+
+def test_create_page_from_element() -> None:
+    pa = Page.from_xml(etree.fromstring("""
+        <Page imageFilename="7895328.jpg" imageWidth="4279" imageHeight="5315">
+            <TextRegion id="tr-1">
+                <Coords points="1,2 8,9"/>
+                <TextLine id="tl-1">
+                    <Coords points="17,42 1,2"/>
+                    <TextEquiv>
+                        <Unicode>bla</Unicode>
+                    </TextEquiv>
+                </TextLine>
+                <TextLine id="tl-2">
+                    <Coords points="20,38 2,2"/>
+                    <TextEquiv>
+                        <Unicode>blub</Unicode>
+                    </TextEquiv>
+                </TextLine>
+            </TextRegion>
+
+            <TextRegion id="tr-2">
+                <Coords points="1,2 8,9"/>
+                <TextLine id="tl-1">
+                    <Coords points="17,42 1,2"/>
+                    <TextEquiv>
+                        <Unicode>bla</Unicode>
+                    </TextEquiv>
+                </TextLine>
+                <TextLine id="tl-2">
+                    <Coords points="20,38 2,2"/>
+                    <TextEquiv>
+                        <Unicode>blub</Unicode>
+                    </TextEquiv>
+                </TextLine>
+            </TextRegion>
+        </Page>
+    """))
+
+    assert pa.image_filename == "7895328.jpg"
+    assert pa.regions == {
+        "tr-1": TextRegion(
+            id="tr-1",
+            coords=Coords.parse("1,2 8,9"),
+            textlines={
+                "tl-1": TextLine(
+                    id="tl-1",
+                    coords=Coords.parse("17,42 1,2"),
+                    text="bla",
+                ),
+                "tl-2": TextLine(
+                    id="tl-2",
+                    coords=Coords.parse("20,38 2,2"),
+                    text="blub",
+                ),
+            },
+        ),
+        "tr-2": TextRegion(
+            id="tr-2",
+            coords=Coords.parse("1,2 8,9"),
+            textlines={
+                "tl-1": TextLine(
+                    id="tl-1",
+                    coords=Coords.parse("17,42 1,2"),
+                    text="bla",
+                ),
+                "tl-2": TextLine(
+                    id="tl-2",
+                    coords=Coords.parse("20,38 2,2"),
+                    text="blub",
+                ),
+            },
+        ),
+    }
+
+
+def test_page_wrong_element() -> None:
+    with pytest.raises(Exception, match="wrong element given"):
+        Page.from_xml(etree.fromstring("<WRONG>!!!</WRONG>"))
+
+
+def test_page_no_filename() -> None:
+    xml = "<Page></Page>"
+    with pytest.raises(Exception, match="no filename found"):
+        Page.from_xml(etree.fromstring(xml))
+
+
+def test_page_from_string() -> None:
+    pa = Page.from_xml_string("""<?xml version='1.0' encoding='utf-8'?>
+        <PcGts xmlns="http://schema.primaresearch.org/PAGE/gts/pagecontent/2019-07-15" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://schema.primaresearch.org/PAGE/gts/pagecontent/2019-07-15/pagecontent.xsd">
+            <Metadata>
+                <Creator>God</Creator>
+                <Created>Sonntag</Created>
+            </Metadata>
+            <Page imageFilename="a.jpg" imageWidth="4217" imageHeight="1742">
+                <TextRegion id="b">
+                    <Coords points="1,2 3,4"/>
+                    <TextLine id="c" index="0" custom="heights_v2:[91.0,32.1]">
+                        <Coords points="5,6 7,8"/>
+                        <Baseline points="2008,360 2208,352"/>
+                        <TextEquiv conf="0.932">
+                        <Unicode>d</Unicode>
+                        </TextEquiv>
+                    </TextLine>
+                </TextRegion>
+            </Page>
+        </PcGts>
+    """)  # use default PageXML namespace
+    assert pa.image_filename == "a.jpg"
+    assert pa.regions == {
+        "b": TextRegion(
+            id="b",
+            coords=Coords.parse("1,2 3,4"),
+            textlines={"c": TextLine(id="c", coords=Coords.parse("5,6 7,8"), text="d")},
+        )
+    }
+
+
+@given(st_text_regions, st_pages())
+def test_page_region_lookup(region: TextRegion, page: Page) -> None:
+    assume(region.id not in page.regions)
+    page.regions[region.id] = region
+    assert page.lookup_region(region.id) == region
+
+
+@given(st.text(), st_pages())
+def test_page_region_lookup_not_found(id: str, page: Page) -> None:
+    assume(id not in page.regions)
+    assert page.lookup_region(id) is None
+
+
+def test_page_all_text_and_words() -> None:
+    pa = Page(
+        image_filename="a",
+        regions={
+            "a": TextRegion(
+                id="a",
+                coords=Coords.parse("1,2 3,4"),
+                textlines={
+                    "b": TextLine(id="b", coords=Coords.parse("2,3 4,5"), text="foo"),
+                    "c": TextLine(id="c", coords=Coords.parse("2,3 4,5"), text="bar"),
+                },
+            ),
+            "c": TextRegion(
+                id="c",
+                coords=Coords.parse("1,2 3,4"),
+                textlines={
+                    "b": TextLine(id="b", coords=Coords.parse("2,3 4,5"), text="bla"),
+                    "c": TextLine(
+                        id="c", coords=Coords.parse("2,3 4,5"), text="blub 42"
+                    ),
+                },
+            ),
+        },
+    )
+    assert list(pa.all_text()) == ["foo", "bar", "bla", "blub 42"]
+    assert list(pa.all_words()) == ["foo", "bar", "bla", "blub", "42"]
+
+
+@given(st_pages())
+def test_page_all_arbitrary_text_and_words(page: Page) -> None:
+    assert list(page.all_text()) == [
+        t for r in page.regions.values() for t in r.all_text()
+    ]
+    assert list(page.all_words()) == [
+        w for r in page.regions.values() for w in r.all_words()
+    ]