Merge pull request #4 from SCDH/file_reading

Author: memowe

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2026 Mirko Westermeier
+Copyright (c) 2026 Mirko Westermeier, Katharina Dietz
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

README.md

@@ -75,7 +75,7 @@ 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)
+Copyright (c) 2026 [Mirko Westermeier][gh-memowe], [Katharina Dietz][gh-kdietzm] (SCDH, University of Münster)
 
 Released under the [MIT License](LICENSE).
 
@@ -90,3 +90,4 @@ Released under the [MIT License](LICENSE).
 [gh-issues]: https://github.com/SCDH/pygexml/issues
 [gh-prs]: https://github.com/SCDH/pygexml/pulls
 [gh-memowe]: https://github.com/memowe
+[gh-kdietzm]: https://github.com/KDietzM

pygexml/page.py

@@ -1,3 +1,4 @@
+from pathlib import Path
 from re import Pattern, compile
 from warnings import warn
 from dataclasses import dataclass
@@ -179,6 +180,12 @@ def from_xml_string(cls, xml_str: str) -> "Page":
             raise PageXMLError("Page: no page element found")
         return cls.from_xml(page_element)
 
+    @classmethod
+    def from_xml_file(cls, file: Path | str, encoding: str = "utf-8") -> "Page":
+        path = Path(file)
+        xml_string = path.read_text(encoding=encoding)
+        return Page.from_xml_string(xml_string)
+
     def lookup_region(self, id: ID) -> TextRegion | None:
         return self.regions.get(id)
 

pyproject.toml

@@ -11,6 +11,7 @@ license = "MIT"
 requires-python = ">=3.12"
 authors = [
     { name = "Mirko Westermeier", email = "mirko.westermeier@uni-muenster.de" },
+    { name = "Katharina Dietz", email = "katharina.dietz@uni-muenster.de" },
 ]
 dependencies = [
     "lxml",

test/test_page.py

@@ -1,6 +1,9 @@
+from pathlib import Path
+
 import pytest
 from hypothesis import given, assume
 import hypothesis.strategies as st
+
 from lxml import etree
 
 from pygexml.strategies import *
@@ -349,6 +352,50 @@ def test_page_from_string() -> None:
     }
 
 
+def test_from_xml_file_example(tmp_path: Path) -> None:
+    content = """<?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>
+        """
+
+    xml_filepath = tmp_path / "test.xml"
+    xml_filepath.write_text(content, encoding="utf-8")
+
+    result = Page.from_xml_file(xml_filepath)
+    assert result.image_filename == "a.jpg"
+    assert result.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")},
+        )
+    }
+    assert result == Page.from_xml_string(content)
+
+
+def test_from_missing_xml_file(tmp_path: Path) -> None:
+    missing_file = tmp_path / "does_not_exist.xml"
+    assert not missing_file.exists()
+    with pytest.raises(FileNotFoundError):
+        Page.from_xml_file(missing_file)
+
+
 @given(st_text_regions, st_pages())
 def test_page_region_lookup(region: TextRegion, page: Page) -> None:
     assume(region.id not in page.regions)