pypxml 1.0__py3-none-any.whl

cli/pypxml_cli.py

@@ -0,0 +1,15 @@
+import click
+
+
+@click.group()
+@click.help_option('--help')
+@click.version_option('1.0', '--version',
+                      prog_name='PyPXML',
+                      message='%(prog)s v%(version)s - Developed at Centre for Philology and Digitality (ZPD), '
+                              'University of Würzburg')
+def cli():
+    """
+    PyPXML command line interface entry point.
+    """
+    pass
+

pypxml/__init__.py

@@ -0,0 +1,9 @@
+# This file is licensed under the MIT License.
+# Copyright (c) 2024 Janik Haitz
+# See the LICENSE file in the root directory for more details.
+
+from .pxml import PageXML
+from .page import Page
+from .element import Element
+from .resources.xml_schema import XMLSchema
+from .resources.xml_types import XMLType

pypxml/element.py

@@ -0,0 +1,225 @@
+# This file is licensed under the MIT License.
+# Copyright (c) 2024 Janik Haitz
+# See the LICENSE file in the root directory for more details.
+
+from typing import Optional, Union, Self
+
+from lxml import etree
+
+from .resources.xml_types import XMLType
+
+
+class Element:
+    """ Represents an element inside a page. """
+    def __init__(self, _type: XMLType, attributes: Optional[dict[str, str]] = None):
+        self.__type: XMLType = _type
+        self.__attributes: dict[str, str] = attributes if attributes else {}
+        self.__elements: list[Element] = []
+        self.__text: Optional[str] = None
+
+    def __len__(self) -> int:
+        """ Returns the number of elements. """
+        return len(self.__elements)
+
+    def __iter__(self) -> Self:
+        """ Iterator: starting point for iterating over all elements. """
+        self.__n = 0
+        return self
+
+    def __next__(self) -> Self:
+        """ Iterator: yield next element. """
+        if self.__n < len(self.__elements):
+            self.__n += 1
+            return self.__elements[self.__n - 1]
+        else:
+            raise StopIteration
+
+    def __getitem__(self, key: Union[int, str]) -> Optional[Union[Self, str]]:
+        """
+        Get an Element object by its index or an attribute value by its key
+        :param key: Index (integer) of an Element object or a key (string) of an attribute.
+        :return: The Element of passed index (returns last object if the key is out of range) or the value of the
+            selected attribute. Returns None, if no match was found.
+        """
+        if isinstance(key, int) and len(self.__elements) > 0:
+            return self.__elements[min(key, len(self.__elements) - 1)]
+        elif isinstance(key, str) and key in self.__attributes:
+            return self.__attributes[key]
+        return None
+
+    def __setitem__(self, key: Union[int, str], value: Union[Self, str]) -> None:
+        """
+        Set an Element object or an attribute value.
+        :param key: Index (integer) for an Element object or a key (string) for an attribute.
+        :param value: Element object (if key is of type integer) or a string (if key is of type string).
+        """
+        if isinstance(key, int) and isinstance(value, Element) and len(self.__elements) > 0:
+            self.__elements[min(key, len(self.__elements) - 1)] = value
+        elif isinstance(key, str):
+            self.__attributes[key] = value
+        else:
+            raise ValueError('Invalid key or value')
+
+    def __contains__(self, key: Union[Self, str]) -> bool:
+        """
+        Checks if an Element object or an attribute exists.
+        :param key: Element object or attribute key.
+        :return: True, if either the passed Element object or the attribute exists. Else return False.
+        """
+        if isinstance(key, Element):
+            return key in self.__elements
+        elif isinstance(key, str):
+            return key in self.__attributes
+        return False
+
+    @property
+    def type(self) -> XMLType:
+        return self.__type
+
+    @type.setter
+    def type(self, value: XMLType) -> None:
+        self.__type = value
+
+    @property
+    def attributes(self) -> dict[str, str]:
+        return self.__attributes
+
+    @property
+    def elements(self) -> list[Self]:
+        return self.__elements
+
+    @property
+    def id(self) -> Optional[str]:
+        return self.__attributes.get('id', None)
+
+    @id.setter
+    def id(self, value: Optional[str]) -> None:
+        if value is None:
+            self.__attributes.pop('id', None)
+        else:
+            self.__attributes['id'] = value
+
+    @property
+    def text(self) -> Optional[str]:
+        return self.__text
+
+    @text.setter
+    def text(self, value: Optional[str]) -> None:
+        self.__text = None if value is None else str(value)
+
+    @classmethod
+    def new(cls, _type: XMLType, **attributes: str) -> Self:
+        """
+        Create a new Element object from scratch.
+        :param _type: The type of element to create.
+        :param attributes: Named arguments that will be stores as xml attributes.
+        :return: The newly created Element object.
+        """
+        attributes = {str(k): str(v) for k, v in attributes.items() if v is not None}
+        return cls(_type, attributes)
+
+    @classmethod
+    def from_etree(cls, tree: etree.Element) -> Self:
+        """
+        Create a new Element object from a lxml etree object.
+        :param tree: lxml etree object.
+        :return: Element object that represents the passed etree object.
+        """
+        element = cls(XMLType(tree.tag.split('}')[1]), dict(tree.items()))
+        element.text = tree.text
+        for child in tree:
+            element.add_element(Element.from_etree(child))
+        return element
+
+    def to_etree(self) -> etree.Element:
+        """
+        Convert the Element object to a lxml etree object.
+        :return: A lxml etree object that represents this Element object.
+        """
+        element = etree.Element(self.__type.value, **self.__attributes)
+        if self.__text is not None:
+            element.text = self.__text
+        for child in self.__elements:
+            element.append(child.to_etree())
+        return element
+
+    def is_region(self) -> bool:
+        """ Returns True, if the Element object is a region. """
+        return self.__type.value.endswith('Region')
+
+    def contains_text(self) -> bool:
+        """ Returns True, if the Element object contains text. """
+        return self.__text is not None
+
+    def set_attribute(self, key: str, value: Optional[str]) -> None:
+        """
+        Set an attribute.
+        :param key: Key of attribute. Creates a new one if the key does not exist.
+        :param value: Value for the attribute. Deletes the attribute of None is passed.
+        """
+        if value is None:
+            self.__attributes.pop(str(key), None)
+        else:
+            self.__attributes[str(key)] = str(value)
+
+    def delete_attribute(self, key: str) -> Optional[str]:
+        """
+        Delete an attribute.
+        :param key: The key to delete.
+        :return: Returns the deleted attribute value. If the key does not exist, None is returned.
+        """
+        return self.__attributes.pop(str(key), None)
+
+    def get_coords(self) -> Optional[Self]:
+        """ Return the first direct child Element object of type Coords. """
+        for element in self.__elements:
+            if element.type == XMLType.Coords:
+                return element
+        return None
+
+    def get_baseline(self) -> Optional[Self]:
+        """ Return the first direct child Element object of type Baseline. """
+        for element in self.__elements:
+            if element.type == XMLType.Baseline:
+                return element
+        return None
+
+    def add_element(self, element: Self, index: Optional[int] = None) -> None:
+        """
+        Add an existing Element object to the list elements.
+        :param element: The element to add.
+        :param index: If set, insert the element at this index. Else append to the list.
+        """
+        if index is None:
+            self.__elements.append(element)
+        else:
+            self.__elements.insert(min(index, len(self.__elements) - 1), element)
+
+    def create_element(self, _type: XMLType, index: int = None, **attributes: str) -> Self:
+        """
+        Create a new Element object and add it to the list of elements.
+        :param _type: XMLType of new element.
+        :param index: If set, insert the new element at this index. Else append to the list.
+        :param attributes: Named arguments that will be stores as xml attributes.
+        :return: The newly created Element object.
+        """
+        element = Element.new(_type, **attributes)
+        self.add_element(element, index)
+        return element
+
+    def remove_element(self, element: Union[Self, int]) -> Optional[Self]:
+        """
+        Remove an element from the list of elements.
+        :param element: The Element object or the index of the element to remove.
+        :return: The removed element, if it existed.
+        """
+        if isinstance(element, int) and element < len(self.__elements) - 1:
+            return self.__elements.pop(element)
+        elif isinstance(element, Element) and element in self.__elements:
+            self.__elements.remove(element)
+            return element
+        return None
+
+    def clear_elements(self) -> None:
+        """ Remove all Element objects from the list of elements. """
+        self.__elements.clear()

pypxml/page.py

@@ -0,0 +1,244 @@
+# This file is licensed under the MIT License.
+# Copyright (c) 2024 Janik Haitz
+# See the LICENSE file in the root directory for more details.
+
+from typing import Optional, Union, Self
+
+from lxml import etree
+
+from .element import Element
+from .resources.xml_types import XMLType
+
+
+class Page:
+    """ Represents a page of a PageXML file. """
+    def __init__(self, attributes: Optional[dict[str, str]] = None):
+        self.__attributes: dict[str, str] = attributes if attributes else {}
+        self.__reading_order: list[str] = []  # region id's
+        self.__elements: list[Element] = []
+
+    def __len__(self) -> int:
+        """ Returns the number of elements. """
+        return len(self.__elements)
+
+    def __iter__(self) -> Self:
+        """ Iterator: starting point for iterating over all elements that are regions. """
+        self.__n = 0
+        self.__regions = [element for element in self.__elements if element.is_region()]
+        return self
+
+    def __next__(self) -> Element:
+        """ Iterator: yield next element that is a region. """
+        if self.__n < len(self.__regions):
+            self.__n += 1
+            return self.__regions[self.__n - 1]
+        else:
+            raise StopIteration
+
+    def __getitem__(self, key: Union[int, str]) -> Optional[Union[Element, str]]:
+        """
+        Get an Element object by its index or an attribute value by its key
+        :param key: Index (integer) of an Element object or a key (string) of an attribute.
+        :return: The Element of passed index (returns last object if the key is out of range) or the value of the
+            selected attribute. Returns None, if no match was found.
+        """
+        if isinstance(key, int) and len(self.__elements) > 0:
+            return self.__elements[min(key, len(self.__elements) - 1)]
+        elif isinstance(key, str) and key in self.__attributes:
+            return self.__attributes[key]
+        return None
+
+    def __setitem__(self, key: Union[int, str], value: Union[Element, str]) -> None:
+        """
+        Set an Element object or an attribute value.
+        :param key: Index (integer) for an Element object or a key (string) for an attribute.
+        :param value: Element object (if key is of type integer) or a string (if key is of type string).
+        """
+        if isinstance(key, int) and isinstance(value, Element) and len(self.__elements) > 0:
+            self.__elements[min(key, len(self.__elements) - 1)] = value
+        elif isinstance(key, str):
+            self.__attributes[key] = value
+        else:
+            raise ValueError('Invalid key or value')
+
+    def __contains__(self, key: Union[Element, str]) -> bool:
+        """
+        Checks if an Element object or an attribute exists.
+        :param key: Element object or attribute key.
+        :return: True, if either the passed Element object or the attribute exists. Else return False.
+        """
+        if isinstance(key, Element):
+            return key in self.__elements
+        elif isinstance(key, str):
+            return key in self.__attributes
+        return False
+
+    @property
+    def attributes(self) -> dict[str, str]:
+        return self.__attributes
+
+    @property
+    def reading_order(self) -> list[str]:
+        return self.__reading_order
+
+    @property
+    def elements(self) -> list[Element]:
+        return self.__elements
+
+    @property
+    def regions(self) -> list[Element]:
+        return list([element for element in self.__regions if element.is_region()])
+
+    @property
+    def image_filename(self) -> Optional[str]:
+        return self.__attributes.get('imageFilename', None)
+
+    @image_filename.setter
+    def image_filename(self, filename: Optional[str]) -> None:
+        if filename is None:
+            self.__attributes.pop('imageFilename', None)
+        else:
+            self.__attributes['imageFilename'] = str(filename)
+
+    @property
+    def width(self) -> Optional[int]:
+        if (w := self.__attributes.get('imageWidth', None)) is not None:
+            return int(w)
+        return None
+
+    @property
+    def height(self) -> Optional[int]:
+        if (h := self.__attributes.get('imageHeight', None)) is not None:
+            return int(h)
+        return None
+
+    @classmethod
+    def new(cls, **attributes: str) -> Self:
+        """
+        Create a new Page object from scratch.
+        :param attributes: Named arguments that will be stored as attributes.
+        :return: The newly created Page object.
+        """
+        attributes = {str(k): str(v) for k, v in attributes.items() if v is not None}
+        return cls(attributes)
+
+    @classmethod
+    def from_etree(cls, tree: etree.Element) -> Self:
+        """
+        Create a new Page object from a lxml etree object.
+        :param tree: lxml etree object.
+        :return: Page object that represents the passed etree object.
+        """
+        page = cls(dict(tree.items()))
+        if (ro := tree.find('./{*}ReadingOrder')) is not None:
+            if (ro_elements := tree.findall('../{*}RegionRefIndexed')) is not None:
+                page._ro = list([i.get('regionRef') for i in sorted(list(ro_elements), key=lambda i: i.get('index'))])
+            tree.remove(ro)
+        for element in tree:
+            page.add_element(Element.from_etree(element), ro=False)
+        return page
+
+    def to_etree(self) -> etree.Element:
+        """
+        Convert the Page object to a lxml etree object.
+        :return: A lxml etree object that represents this Page object.
+        """
+        page = etree.Element('Page', **self.__attributes)
+        if len(self.__reading_order) > 0:
+            reading_order = etree.SubElement(page, 'ReadingOrder')
+            order_group = etree.SubElement(reading_order, 'OrderedGroup', id='g0')  # does id matter?
+            for i, rid in enumerate(self.__reading_order):
+                etree.SubElement(order_group, 'RegionRefIndexed', index=str(i), regionRef=rid)
+        for element in self.__elements:
+            page.append(element.to_etree())
+        return page
+
+    def set_attribute(self, key: str, value: Optional[str]) -> None:
+        """
+        Set or create an attribute.
+        :param key: Key of attribute. Creates a new one if the key does not exist.
+        :param value: Value for the attribute. Deletes the attribute of None is passed.
+        """
+        if value is None:
+            self.__attributes.pop(str(key), None)
+        else:
+            self.__attributes[str(key)] = str(value)
+
+    def delete_attribute(self, key: str) -> Optional[str]:
+        """
+        Delete an attribute.
+        :param key: The key to delete.
+        :return: Returns the deleted attribute value. If the key does not exist, None is returned.
+        """
+        return self.__attributes.pop(str(key), None)
+
+    def get_regions(self, region: Optional[XMLType] = None) -> list[Element]:
+        """
+        Return a list of all direct child elements that are regions.
+        :param region: Only select a specific region type.
+        :return: List of matching Element objects.
+        """
+        if region is None:
+            return list([e for e in self.__elements if e.is_region()])
+        return list([e for e in self.__elements if e.type == region])
+
+    def add_element(self, element: Element, index: Optional[int] = None, ro: bool = True) -> None:
+        """
+        Add an existing Element object to the list elements.
+        :param element: The element to add.
+        :param index: If set, insert the element at this index. Else append to the list.
+        :param ro: If set to true, add the element to the reading order at the specified index.
+            Only if the element is a region.
+        """
+        if index is None:
+            self.__elements.append(element)
+            if ro and element.is_region() and element.id:
+                self.__reading_order.append(element.id)
+        else:
+            self.__elements.insert(min(index, len(self.__elements) - 1), element)
+            if ro and element.is_region() and element.id:
+                self.__reading_order.insert(min(index, len(self.__elements) - 1), element.id)
+
+    def create_element(self, _type: XMLType, index: int = None, ro: bool = True, **attributes: str) -> Element:
+        """
+        Create a new Element object and add it to the list of elements.
+        :param _type: XMLType of new element.
+        :param index: If set, insert the new element at this index. Else append to the list.
+        :param ro: If set to true, add the element to the reading order at the specified index.
+            Only if the element is a region.
+        :param attributes: Named arguments that will be stores as xml attributes.
+        :return: The newly created Element object.
+        """
+        element = Element.new(_type, **attributes)
+        self.add_element(element, index, ro)
+        return element
+
+    def remove_element(self, element: Union[Element, int]) -> Optional[Element]:
+        """
+        Remove an element from the list of elements.
+        :param element: The Element object or the index of the element to remove.
+        :return: The removed element, if it existed.
+        """
+        if isinstance(element, int) and element < len(self.__elements) - 1:
+            return self.__elements.pop(element)
+        elif isinstance(element, Element) and element in self.__elements:
+            self.__elements.remove(element)
+            return element
+        return None
+
+    def clear_elements(self) -> None:
+        """ Remove all Element objects from the list of elements. """
+        self.__elements.clear()
+        self.clear_reading_order()
+
+    def clear_regions(self) -> None:
+        """ Remove all Element objects from the list of elements, that are regions. """
+        for element in self.__elements:
+            if element.is_region():
+                self.__elements.remove(element)
+                if element.id and element.id in self.__reading_order:
+                    self.__reading_order.remove(element.id)
+
+    def clear_reading_order(self) -> None:
+        """ Reset the reading order. """
+        self.__reading_order.clear()

pypxml/pxml.py

@@ -0,0 +1,223 @@
+# This file is licensed under the MIT License.
+# Copyright (c) 2024 Janik Haitz
+# See the LICENSE file in the root directory for more details.
+
+from typing import Optional, Union, Self
+from datetime import datetime
+from pathlib import Path
+import json
+
+from lxml import etree
+
+from .page import Page
+from .resources.xml_schema import XMLSchema
+
+
+class PageXML:
+    """ Represents a PageXML file. """
+    def __init__(self, creator: str, created: str, changed: str) -> None:
+        self.__creator: str = creator
+        self.__created: str = created
+        self.__changed: str = changed
+        self.__pages: list[Page] = []
+
+    def __len__(self) -> int:
+        """ Returns the number of pages. """
+        return len(self.__pages)
+
+    def __iter__(self) -> Self:
+        """ Iterator: starting point for iterating over all pages. """
+        self.__n = 0
+        return self
+
+    def __next__(self) -> Page:
+        """ Iterator: yield next page. """
+        if self.__n < len(self.__pages):
+            self.__n += 1
+            return self.__pages[self.__n - 1]
+        else:
+            raise StopIteration
+
+    def __getitem__(self, key: int) -> Optional[Page]:
+        """
+        Get the Page object of a given index.
+        :param key: The index value of the Page object.
+        :return: Page object if pages are available. Returns last page if index is out of range.
+        """
+        if len(self.__pages) > 0:
+            return self.__pages[min(key, len(self.__pages) - 1)]
+        return None
+
+    def __setitem__(self, key: int, value: Page) -> None:
+        """
+        Set a Page object for a given index.
+        :param key: The target index for the Page object.
+        :param value: The new Page object.
+        """
+        if len(self.__pages) > 0:
+            self.__pages[min(key, len(self.__pages) - 1)] = value
+
+    def __contains__(self, key: Page) -> bool:
+        """
+        Checks if a Page objects exists.
+        :param key: The Page object.
+        :return: True, if the Page object exists. Else return False.
+        """
+        if isinstance(key, Page):
+            return key in self.__pages
+        return False
+
+    @property
+    def creator(self) -> Optional[str]:
+        return self.__creator
+
+    @creator.setter
+    def creator(self, creator: str) -> None:
+        self.__creator = str(creator)
+
+    @property
+    def created(self) -> Optional[str]:
+        return self.__created
+
+    @created.setter
+    def created(self, created: Union[datetime, str]) -> None:
+        if isinstance(created, datetime):
+            self.__created = created.isoformat()
+        else:
+            self.__created = str(created)
+
+    @property
+    def changed(self) -> Optional[str]:
+        return self.__changed
+
+    @changed.setter
+    def changed(self, changed: Union[datetime, str]) -> None:
+        if isinstance(changed, datetime):
+            self.__changed = changed.isoformat()
+        else:
+            self.__changed = str(changed)
+
+    @property
+    def pages(self) -> list[Page]:
+        return self.__pages
+
+    @classmethod
+    def new(cls, creator: str = 'PyPXML') -> Self:
+        """
+        Create a new PageXML object from scratch.
+        :param creator: Specify creator tag in PageXMLs metadata.
+        :return: Newly created PageXML object.
+        """
+        return cls(creator, datetime.now().isoformat(), datetime.now().isoformat())
+
+    @classmethod
+    def from_etree(cls, tree: etree.Element) -> Self:
+        """
+        Create a new PageXML object from a lxml etree object.
+        :param tree: lxml etree object.
+        :return: PageXML object that represents the passed etree object.
+        """
+        if (md_tree := tree.find('./{*}Metadata')) is not None:
+            if (creator := md_tree.find('./{*}Creator')) is not None:
+                creator = creator.text
+            if (created := md_tree.find('./{*}Created')) is not None:
+                created = created.text
+            if (last_change := md_tree.find('./{*}LastChange')) is not None:
+                last_change = last_change.text
+            pxml = cls(creator, created, last_change)
+        else:
+            pxml = cls.new()
+        if (pages := tree.findall('./{*}Page')) is not None:
+            for page_tree in pages:
+                pxml.add_page(Page.from_etree(page_tree))
+        return pxml
+
+    def to_etree(self, version: str = '2019', schema_file: Optional[Path] = None) -> etree.Element:
+        """
+        Convert a PageXML object to a lxml etree element.
+        :param version: PageXML Version to use. Currently supported: `2019`.
+        :param schema_file: Custom schema in json format.
+        :return: A lxml etree object that represents this PageXML object.
+        """
+        self.changed = datetime.now().isoformat()
+        if schema_file is not None:
+            with open(schema_file) as stream:
+                schema = XMLSchema.custom('pagexml', version, json.load(stream))
+        else:
+            schema = XMLSchema.pagexml(version)
+        xsi_qname = etree.QName("http://www.w3.org/2001/XMLSchema-instance", 'schemaLocation')
+        nsmap = { None: schema['xmlns'], 'xsi': schema['xmlns_xsi'] }
+        root = etree.Element('PcGts', { xsi_qname: schema['xsi_schema_location'] }, nsmap=nsmap)
+        metadata = etree.SubElement(root, 'Metadata')
+        etree.SubElement(metadata, 'Creator').text = self.__creator
+        etree.SubElement(metadata, 'Created').text = self.__created
+        etree.SubElement(metadata, 'LastChange').text = self.__changed
+        for page in self.__pages:
+            root.append(page.to_etree())
+        return root
+
+    @classmethod
+    def from_xml(cls, fp: Union[Path, str], encoding: Optional[str] = None) -> Self:
+        """
+        Create a new PageXML object from a PageXML file.
+        :param fp: Path of PageXML file.
+        :param encoding: Set custom encoding.
+        :return: PageXML object.
+        """
+        parser = etree.XMLParser(remove_blank_text=True, encoding=encoding)
+        tree = etree.parse(fp, parser).getroot()
+        return cls.from_etree(tree)
+
+    def to_xml(self, fp: Union[Path, str], version: str = '2019-07-15', schema_file: Optional[Path] = None,
+               encoding: str = 'utf-8') -> None:
+        """
+        Create a PageXML file from a PageXML file.
+        :param fp: Path to new PageXML file.
+        :param version: The PageXML version to use. Currently supported: `2019`.
+        :param schema_file: Custom schema in json format.
+        :param encoding: Set custom encoding.
+        """
+        with open(fp, 'wb') as f:
+            tree = etree.tostring(self.to_etree(version, schema_file),
+                                  pretty_print=True,
+                                  encoding=encoding,
+                                  xml_declaration=True)
+            f.write(tree)
+
+    def add_page(self, page: Page, index: Optional[int] = None) -> None:
+        """
+        Add a Page object to the list of pages.
+        :param page: The Page object to add.
+        :param index: If set, insert the Page object at this index.
+        """
+        if index is None or index >= len(self.__pages) - 1:
+            self.__pages.append(page)
+        else:
+            self.__pages.insert(index, page)
+
+    def create_page(self, index: Optional[int] = None, **attributes: str) -> Page:
+        """
+        Create a new Page object and add it to the list of pages.
+        :param index: If set, insert the Page object at this index.
+        :param attributes: Named arguments that will be stores as xml attributes.
+        :return: The newly created Page object.
+        """
+        page = Page.new(**attributes)
+        self.add_page(page, index)
+        return page
+
+    def remove_page(self, page: Union[Page, int]) -> Optional[Page]:
+        """
+        Remove a Page object from the list of pages.
+        :param page: The index of the Page object to remove or the Page object itself.
+        :return: The Page object that was removed if it existed.
+        """
+        if isinstance(page, Page) and page in self.__pages:
+            self.__pages.remove(page)
+            return page
+        elif isinstance(page, int) and page < len(self.__pages):
+            return self.__pages.pop(page)
+
+    def clear_pages(self) -> None:
+        """ Remove all Page objects from the list of pages. """
+        self.__pages.clear()

pypxml/resources/__init__.py

@@ -0,0 +1,4 @@
+# This file is licensed under the MIT License.
+# Copyright (c) 2024 Janik Haitz
+# See the LICENSE file in the root directory for more details.
+

pypxml/resources/xml_schema.py

@@ -0,0 +1,43 @@
+# This file is licensed under the MIT License.
+# Copyright (c) 2024 Janik Haitz
+# See the LICENSE file in the root directory for more details.
+
+from typing import Literal
+
+
+DEFAULT_SCHEMA = {
+    'pagexml': {
+        '2019': {
+            'xmlns': 'http://schema.primaresearch.org/PAGE/gts/pagecontent/2017-07-15',
+            'xmlns_xsi': 'http://www.w3.org/2001/XMLSchema-instance',
+            'xsi_schema_location': 'http://schema.primaresearch.org/PAGE/gts/pagecontent/2017-07-15 http://schema.primaresearch.org/PAGE/gts/pagecontent/2017-07-15/pagecontent.xsd'
+        },
+        '2017': {
+            'xmlns': 'http://schema.primaresearch.org/PAGE/gts/pagecontent/2019-07-15',
+            'xmlns_xsi': 'http://www.w3.org/2001/XMLSchema-instance',
+            'xsi_schema_location': 'http://schema.primaresearch.org/PAGE/gts/pagecontent/2019-07-15 http://schema.primaresearch.org/PAGE/gts/pagecontent/2019-07-15/pagecontent.xsd'
+        }
+    }
+}
+
+
+class XMLSchema:
+    @staticmethod
+    def pagexml(version: Literal['2019', '2017'] = '2019') -> dict[str, str]:
+        """
+        Returns the xml schema values of a specified PageXML version.
+        :param version: The PageXML version to use.
+        :return: A dictionary containing all header attributes: `xmlns`, `xmlns_xsi`, `xsi_schema_location`
+        """
+        return DEFAULT_SCHEMA['pagexml'][version]
+
+    @staticmethod
+    def custom(schema: str, version: str, custom: dict) -> dict[str, str]:
+        """
+        Returns the custom xml schema values of a specified version.
+        :param schema: The schema to use.
+        :param version: The version to use.
+        :param custom: A dictionary containing custom xml schema values. See DEFAULT_SCHEMA as example.
+        :return: A dictionary containing all header attributes provided by the custom schema.
+        """
+        return custom[schema][version]

pypxml/resources/xml_types.py

@@ -0,0 +1,59 @@
+# This file is licensed under the MIT License.
+# Copyright (c) 2024 Janik Haitz
+# See the LICENSE file in the root directory for more details.
+
+from enum import Enum
+
+
+class XMLType(Enum):
+    """
+    https://ocr-d.de/de/gt-guidelines/pagexml/pagecontent_xsd_Complex_Type_pc_PcGtsType.html#PcGtsType_Page
+    """
+
+    # ReadingOrder
+    ReadingOrder = "ReadingOrder"
+    OrderedGroup = "OrderedGroup"
+    RegionRefIndexed = "RegionRefIndexed"
+
+    # Regions
+    AdvertRegion = "AdvertRegion"
+    ChartRegion = "ChartRegion"
+    ChemRegion = "ChemRegion"
+    CustomRegion = "CustomRegion"
+    GraphicRegion = "GraphicRegion"
+    ImageRegion = "ImageRegion"
+    LineDrawingRegion = "LineDrawingRegion"
+    MapRegion = "MapRegion"
+    MathsRegion = "MathsRegion"
+    MusicRegion = "MusicRegion"
+    NoiseRegion = "NoiseRegion"
+    SeparatorRegion = "SeparatorRegion"
+    TableRegion = "TableRegion"
+    TextRegion = "TextRegion"
+    UnknownRegion = "UnknownRegion"
+
+    # Elements
+    AlternativeImage = "AlternativeImage"
+    Baseline = "Baseline"
+    Border = "Border"
+    Coords = "Coords"
+    Glyph = "Glyph"
+    GraphemeGroup = "GraphemeGroup"
+    Graphemes = "Graphemes"
+    Grid = "Grid"
+    Label = "Label"
+    Labels = "Labels"
+    Layers = "Layers"
+    Metadata = "Metadata"
+    NonPrintingChar = "NonPrintingChar"
+    PlainText = "PlainText"
+    PrintSpace = "PrintSpace"
+    Relations = "Relations"
+    Roles = "Roles"
+    TextEquiv = "TextEquiv"
+    TextLine = "TextLine"
+    TextStyle = "TextStyle"
+    Unicode = "Unicode"
+    UserAttribute = "UserAttribute"
+    UserDefined = "UserDefined"
+    Word = "Word"

pypxml-1.0.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Janik Haitz
+
+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.

pypxml-1.0.dist-info/METADATA

@@ -0,0 +1,156 @@
+Metadata-Version: 2.1
+Name: pypxml
+Version: 1.0
+Summary: A python library for parsing, converting and modifying PageXML files. 
+Author-email: Janik Haitz <jahtz.dev@proton.me>
+License: MIT License
+        
+        Copyright (c) 2024 Janik Haitz
+        
+        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.
+        
+Project-URL: repository, https://github.com/jahtz/pypxml
+Keywords: PageXML,XML,OCR,optical character recognition
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: lxml ~=5.3.0
+Requires-Dist: click ~=8.1.7
+
+from src.pypxml import XMLSchema
+
+# PyPXML
+A python library for parsing, converting and modifying PageXML files.
+
+## Setup
+```shell
+pip install pypxml
+```
+
+### Install from source
+1. Clone repository: `git clone https://github.com/jahtz/pypxml`
+2. Install package: `cd pypxml && pip install .`
+3. Test with `pypxml --version`
+
+## CLI
+```
+pypxml [OPTIONS] COMMAND [ARGS]...
+```
+Coming in version 2.x
+
+## API
+PyXML provides a feature rich Python API for working with PageXML files.
+
+### Basics
+```python
+from pypxml import PageXML, Page, Element, XMLType
+
+pxml = PageXML.from_xml('path_to_pagexml.xml')
+page1 = pxml.create_page(imageFilename='0001.png', 
+                         imageWidth=1000, 
+                         imageHeight=2500)
+page1.create_element(XMLType.TextRegion, id='ir01')
+pxml.to_xml('path_to_output.xml')
+```
+
+### PageXML class
+```python
+from pypxml import PageXML
+
+# open file
+pxml = PageXML.from_xml('path_to.xml')
+# or create new PageXML
+pxml = PageXML.new()
+
+# edit metadata
+pxml.creator = 'yourname'
+...
+
+# create a page
+page = pxml.create_page(imageFilename='0001.png',
+                        imageWidth=1000,
+                        imageHeight='2500')
+# or add existing page
+pxml.add_page(page)  # see below
+
+# iterate over pages
+for page in pxml:
+    ...
+
+# delete or modify pages
+pxml[0] = ...
+pxml.remove_page(pxml[1])
+
+# save object to file
+pxml.to_xml('output.xml')
+...
+```
+
+### Page class
+```python
+from pypxml import Page, XMLType
+
+# create a page
+page = Page.new(imageFilename='0001.png',
+                imageWidth=1000,
+                imageHeight=2500)
+
+# modify attributes
+page['imageFilename'] = '0002.png'
+# or get element by index
+element = page[3]
+
+# add elements (automatically added to reading order if it is a region)
+text_region = page.create_element(XMLType.TextRegion, id='tr1')
+# or add existing element
+page.add_element(element)
+
+# iterate over regions
+for region in page:
+    ...
+...
+```
+
+### Element class
+```python
+from pypxml import Element, XMLType
+
+# create an element
+coords = Element.new(XMLType.Coords, 
+                     points='1,2 3,4 5,6 7,8')
+# modify attributes
+coords['points'] = 'some other coords'
+# or get element by index
+baseline = text_region[2]
+
+# check if element is a region
+if text_region.is_region():
+    ...
+
+# get coords and baseline, if they exist
+coords = text_line.get_coords()
+baseline = text_line.get_baseline()
+...
+```
+
+## ZPD
+Developed at Centre for [Philology and Digitality](https://www.uni-wuerzburg.de/en/zpd/) (ZPD), [University of Würzburg](https://www.uni-wuerzburg.de/en/).

pypxml-1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cli/pypxml_cli.py,sha256=Ui5FqdPaYk43686AytkKB6L66mDmbxGdE2s9f8PC_eU,397
+pypxml/__init__.py,sha256=gGyTUwm-H6Z_iESkAKUhjEVMUldRkZs7wqOKjpfHmKc,307
+pypxml/element.py,sha256=ivvkS-ktcQzU7pxbJb1uZut7ShF0a3s7WXzFSebFTq8,8530
+pypxml/page.py,sha256=6mqyGS9VsM2NMX87h6AzhagudjkSWuqnpiWH-x3Zuao,10131
+pypxml/pxml.py,sha256=LHPiHI4gaKxzacqPTVEch2Zx1LnjZSA7yXMqJ_LLpdk,8385
+pypxml/resources/__init__.py,sha256=5LWKUrEyh94LutFHtwZxjieOnSeS-o0afz6qZMmRydU,144
+pypxml/resources/xml_schema.py,sha256=FDOX_tK-ctN3oxxXiL9-ocuPSV8vChmvom27cJ1fleA,1881
+pypxml/resources/xml_types.py,sha256=UBHWVznBwSTzYXdp0hpbbeChXsYozkNeL1qvHxQgwwY,1620
+pypxml-1.0.dist-info/LICENSE,sha256=YtURTiiG41gsIDU4gyMNba_R6Db-J_GvXZvtXGVUyZo,1068
+pypxml-1.0.dist-info/METADATA,sha256=2har3hD2fOqyaq3Ac4AaIZwEYg2ODyoDwFaJSLsXP2o,4400
+pypxml-1.0.dist-info/WHEEL,sha256=GV9aMThwP_4oNCtvEC2ec3qUYutgWeAzklro_0m4WJQ,91
+pypxml-1.0.dist-info/entry_points.txt,sha256=zkGOJGSpAat6xMZrzonPstt_BiHgTBkH0aEYb9SpX1w,46
+pypxml-1.0.dist-info/top_level.txt,sha256=wz-ismkaMeQqzKDV6hKEH3gMDZT9mVbLSqnha04iUZE,11
+pypxml-1.0.dist-info/RECORD,,

pypxml-1.0.dist-info/WHEEL

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

pypxml-1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pypxml = cli.pypxml_cli:cli

pypxml-1.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+cli
+pypxml