maxml 1.0.0__py3-none-any.whl

maxml/__init__.py

@@ -0,0 +1,2 @@
+from maxml.element import Element
+from maxml.namespace import Namespace

maxml/element/__init__.py

@@ -0,0 +1,663 @@
+from __future__ import annotations
+
+from maxml.namespace import Namespace
+from maxml.logging import logger
+
+from hybridmethod import hybridmethod
+
+
+logger = logger.getChild(__name__)
+
+
+class Element(object):
+    """The Element class represents an XML element"""
+
+    _name: str = None
+    _prefix: str = None
+    _namespaces: set[Namespace] = set()
+    _attributes: dict[str, str] = None
+    _text: str = None
+    _parent: Element = None
+    _children: list[Element] = None
+    _mixed: bool = False
+
+    @hybridmethod
+    def register_namespace(self, prefix: str, uri: str):
+        """Supports registering namespaces globally for the module or per instance
+        depending on whether the method is called on the class directly or whether it is
+        called on a specific instance of the class.
+
+        If a namespace is registered globally for the module, the registered namespaces
+        become available for use by any instance of the class created within the program
+        after that point. This is especially useful for widely used XML namespaces which
+        obviates the need to re-register these widely used namespaces for each instance.
+
+        If there are namespaces which are specific to a document that is being created
+        and that won't be used elsewhere in the program, then those namespaces can be
+        registered on the specific class instance within which they will be used without
+        affecting the global list of registered namespaces.
+
+        Each namespace consists of a prefix which can be used to prefix element names
+        and the URI associated with that namespace prefix.
+
+        For example, the 'rdf' prefix is associated with the following canonical URI:
+            "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+
+        This would be registered globally by calling:
+
+            Element.register_namespace(
+                prefix="rdf",
+                uri="http://www.w3.org/1999/02/22-rdf-syntax-ns#",
+            )
+
+        Or this would be registered on a specific instance of the class by calling:
+
+            instance.register_namespace(
+                prefix="rdf",
+                uri="http://www.w3.org/1999/02/22-rdf-syntax-ns#",
+            )
+
+        Where 'instance' was the variable referencing the desired instance of the class.
+        """
+
+        logger.debug("%s.register_namespace(prefix: %s, uri: %s)", self, prefix, uri)
+
+        if not isinstance(prefix, str):
+            raise TypeError("The 'prefix' argument must have a string value!")
+
+        if not isinstance(uri, str):
+            raise TypeError("The 'uri' argument must have a string value!")
+
+        for namespace in self._namespaces:
+            if namespace.prefix == prefix:
+                if namespace.uri == uri:
+                    logger.warning(
+                        " >>> The '%s' namespace has already been registered..."
+                        % (prefix)
+                    )
+                    break
+                else:
+                    raise ValueError(
+                        "The '%s' namespace has already been registered with a different URI!"
+                        % (prefix)
+                    )
+        else:
+            if namespace := Namespace(prefix=prefix, uri=uri):
+                self._namespaces.add(namespace)
+
+    def __init__(
+        self,
+        name: str,
+        text: str = None,
+        namespace: Namespace | str = None,
+        mixed: bool = True,
+        parent: Element = None,
+        **attributes,
+    ):
+        """Support initializing a new XML element with a required element name, optional
+        text content, an optional parent element reference (which must be set for child
+        nodes) and an optional namespace definition provided either as a Namespace class
+        instance containing the matching prefix and associated namespace URI or as a URI
+        given as a string which corresponds to the prefix used in the element's name."""
+
+        if not isinstance(name, str):
+            raise TypeError("The 'name' argument must have a string value!")
+        elif len(name := name.strip()) == 0:
+            raise ValueError("The 'name' argument must have a non-empty string value!")
+
+        if not ":" in name:
+            raise ValueError(
+                "The 'name' argument must contain a ':' separator character between the namespace and tag name!"
+            )
+
+        prefix: str = None
+
+        if ":" in name:
+            (prefix, basename) = name.split(":", maxsplit=1)
+
+        self._prefix: str = prefix
+
+        self._name: str = basename
+
+        if parent is None:
+            pass
+        elif isinstance(parent, Element):
+            self._parent: Element = parent
+        else:
+            raise TypeError(
+                "The 'parent' argument must reference an Element class instance!"
+            )
+
+        if text is None:
+            pass
+        elif isinstance(text, str):
+            self._text: str = text
+        else:
+            raise TypeError(
+                "The 'text' argument, if specified, must have a string value!"
+            )
+
+        self._namespaces: set[Namespace] = set()
+
+        if namespace is None:
+            for namespace in self.__class__._namespaces:
+                if namespace.prefix == prefix:
+                    break
+            else:
+                raise ValueError(
+                    f"No namespace has been registered for the '{prefix}' prefix associated with the '{name}' element!"
+                )
+
+            self._namespaces.add(namespace.copy().promote())
+        elif isinstance(uri := namespace, str):
+            for namespace in self.__class__._namespaces:
+                if namespace.uri == uri:
+                    break
+            else:
+                namespace = Namespace(prefix=prefix, uri=uri)
+
+            self.__class__._namespaces.add(namespace)
+
+            self._namespaces.add(namespace.copy().promote())
+        elif isinstance(namespace, Namespace):
+            self.__class__._namespaces.add(namespace)
+
+            self._namespaces.add(namespace.copy().promote())
+        else:
+            raise TypeError(
+                "The 'namespace' argument does not contain a valid namespace!"
+            )
+
+        self._attributes: dict[str, str] = attributes or {}
+
+        self._children: list[Element] = []
+
+        if isinstance(mixed, bool):
+            self._mixed = mixed
+        else:
+            raise TypeError("The 'mixed' argument must have a boolean value!")
+
+        logger.debug(
+            "%s.__init__(name: %s, text: %s, parent: %s, namespace: %s, kwargs: %s) => depth %d",
+            self.__class__.__name__,
+            name,
+            text,
+            parent,
+            namespace,
+            attributes,
+            self.depth,
+        )
+
+    @property
+    def depth(self) -> int:
+        """Return the depth of the current Element where the root Element has a depth of
+        zero (0) and all nested Elements have a depth that increases by one (1) for each
+        level of nesting between the root node and the current Element node."""
+
+        depth: int = 0
+
+        if self.parent:
+            depth = 1 + self.parent.depth
+        else:
+            depth = 0
+
+        return depth
+
+    @property
+    def prefix(self) -> str | None:
+        """Return the current Element node's namespace prefix."""
+
+        return self._prefix
+
+    @property
+    def name(self) -> str:
+        """Return the current Element node's name without its namespace prefix."""
+
+        return self._name
+
+    @property
+    def fullname(self) -> str:
+        """Return the current Element node's full name, combining the elements namespace
+        prefix and name."""
+
+        if self._prefix:
+            return f"{self._prefix}:{self._name}"
+        else:
+            return self._name
+
+    @property
+    def namespace(self) -> Namespace | None:
+        """Return the current Element node's namespace, if the Element has a prefix and
+        if a matching namespace has been registered prior to or at the time the Element
+        was created. If no matching namespace can be found, None will be returned."""
+
+        namespace: Namespace = None
+
+        if self._prefix:
+            for namespace in self.__class__._namespaces:
+                if namespace.prefix == self._prefix:
+                    break
+            else:
+                namespace = None
+
+        logger.debug(
+            "%s.namespace(%s) => %s",
+            self.__class__.__name__,
+            self.fullname,
+            namespace.prefix if namespace else "?",
+        )
+
+        return namespace
+
+    @property
+    def namespaces(self) -> set[Namespace]:
+        """Return the namespaces associated with the current Element and its parent"""
+
+        namespaces: set[Namespace] = set(self._namespaces)
+
+        logger.debug(
+            "%s.namespaces(%s) => %s",
+            self.__class__.__name__,
+            self.fullname,
+            [n.prefix for n in namespaces],
+        )
+
+        if self.parent:
+            for namespace in self.parent.namespaces:
+                namespaces.add(namespace)
+
+        if namespace := self.namespace:
+            namespaces.add(namespace)
+
+        logger.debug(
+            "%s.namespaces(%s) => %s",
+            self.__class__.__name__,
+            self.fullname,
+            [n.prefix for n in namespaces],
+        )
+
+        return namespaces
+
+    @property
+    def namespaced(self) -> set[Namespace]:
+        """Return the namespaces associated with the current Element and its children"""
+
+        namespaces: list[Namespace] = set()
+
+        inherited: set[Namespace] = self.parent.namespaces if self.parent else set()
+
+        # logger.debug("%s.namespaced(%s) => inherited => %s", self.__class__.__name__, self.fullname, [n.prefix for n in inherited])
+
+        if namespace := self.namespace:
+            if self.parent is None:
+                namespaces.add(namespace)
+            elif not namespace in inherited:
+                namespaces.add(namespace)
+
+        if self.depth > 0:
+            for child in self.children:
+                if namespace := child.namespace:
+                    if self.parent is None or not namespace in inherited:
+                        namespaces.add(namespace)
+
+        # logger.debug("%s.namespaced(%s) => current => %s", self.__class__.__name__, self.fullname, [n.prefix for n in namespaces])
+
+        return namespaces
+
+    @property
+    def parent(self) -> Element | None:
+        """Return current Element node's parent Element or None if its the root node."""
+
+        return self._parent
+
+    @property
+    def root(self) -> Element:
+        """Return the root Element of the tree, callable from any other Element node."""
+
+        if self.parent is None:
+            return self
+
+        return self.parent.root
+
+    @property
+    def children(self) -> list[Element]:
+        """Return a copy of the list of children associated with the current Element."""
+
+        return list(self._children)
+
+    @property
+    def empty(self) -> bool:
+        """Determine if the current Element is considered empty or not, as determined by
+        the absence of any children, returning True for Elements without children."""
+
+        return len(self._children) == 0
+
+    @property
+    def attributes(self) -> dict[str, str]:
+        """Return a copy of the dictionary of attributes held by the current Element."""
+
+        return dict(self._attributes)
+
+    def set(self, name: str, value: object) -> Element:
+        """Supports setting a named attribute value on the current Element; if the named
+        attribute already exists, its value will be overwritten."""
+
+        if not isinstance(name, str):
+            raise TypeError("The 'name' argument must have a string value!")
+
+        if not (isinstance(value, object) and hasattr(value, "__str__")):
+            raise TypeError(
+                "The 'value' argument must have a value that can be cast to a string!"
+            )
+
+        self._attributes[name] = value
+
+        return self
+
+    def get(self, name: str, default: object = None) -> object | None:
+        """Supports getting the value of a named attribute on the Element if the named
+        attribute exists, returning the optional default value if the named attributes
+        does not exist or returning None otherwise."""
+
+        if not isinstance(name, str):
+            raise TypeError("The 'name' argument must have a string value!")
+
+        if name in self._attributes:
+            return self._attributes[name]
+
+        return default
+
+    def unset(self, name: str) -> Element:
+        """Supports unsetting a named attribute on the Element."""
+
+        if not isinstance(name, str):
+            raise TypeError("The 'name' argument must have a string value!")
+
+        if name in self._attributes:
+            del self._attributes[name]
+
+        return self
+
+    def subelement(self, name: str, **kwargs) -> Element:
+        """Create a child Element under the current Element."""
+
+        if not isinstance(name, str):
+            raise TypeError("The 'name' argument must have a string value!")
+
+        element = Element(name=name, parent=self, **kwargs)
+
+        self._children.append(element)
+
+        if self.parent:
+            if namespace := element.namespace:
+                self._namespaces.add(namespace)
+
+        return element
+
+    @property
+    def text(self) -> str | None:
+        """Return the text value of the current Element if present or None otherwise."""
+
+        return self._text
+
+    @text.setter
+    def text(self, text: str):
+        """Supports setting the text property of the current Element by assigning a
+        string value, or nullifying the text value if needed by assinging None."""
+
+        if text is None:
+            self._text = None
+        elif isinstance(text, str):
+            self._text = text
+        else:
+            raise TypeError(
+                "The 'text' property must be assigned to a string value or None!"
+            )
+
+    @property
+    def mixed(self) -> bool:
+        """Return whether mixed content mode is enabled or not; by default it is."""
+
+        return self._mixed
+
+    def _parse_path(self, path: str) -> list[str]:
+        """Supports parsing the search path into its consistuent parts"""
+
+        if not isinstance(path, str):
+            raise TypeError("The 'path' argument must have a string value!")
+
+        # The root node can be referenced via '$', '.' or '//' and to allow removal of
+        # a potentially trailing '/' we first need to replace '//' with '.'
+        if path == "//":
+            path = "."
+
+        # Remove any potentially trailing '/' from the search path so that it doesn't
+        # result in an additional empty search path component when splitting below
+        path = path.rstrip("/")
+
+        # The '//' prefix can also be used to indicate the root node
+        if path.startswith("//"):
+            path = "." + path[2:]
+
+        # The '$' prefix can also be used to indicate the root node
+        elif path.startswith("$"):
+            path = "." + path[1:]
+
+        return path.split("/")
+
+    def find(self, path: str) -> Element | None:
+        """Supports finding the matching element nested within the current Element as
+        specified by the path which consists of one or more prefixed names and optional
+        wildcard characters."""
+
+        if not isinstance(path, str):
+            raise TypeError("The 'path' argument must have a string value!")
+
+        current: Element = self
+
+        if (count := len(parts := self._parse_path(path))) > 0:
+            root: Element = self.root
+
+            found: bool = False
+
+            for index, part in enumerate(parts, start=1):
+                # print(index, part)
+
+                if part == ".":
+                    # print(f" >>> matched root ({part}) => {root.fullname}")
+                    current = root
+
+                    if count == index:
+                        found = True
+                        break
+                else:
+                    # print(f" >>> checking children for ({part})")
+
+                    for child in current.children:
+                        # print(f" >>> checking child ({child.fullname})")
+
+                        if part == "*" or child.fullname == part:
+                            # print(f" >>> matched child ({part})")
+
+                            current = child
+
+                            if count == index:
+                                found = True
+                                break
+
+            if found is False:
+                current = None
+
+        return current
+
+    def findall(self, path: str) -> list[Element]:
+        """Supports finding the matching elements nested within the current Element as
+        specified by the path which consists of one or more prefixed names and optional
+        wildcard characters."""
+
+        if not isinstance(path, str):
+            raise TypeError("The 'path' argument must have a string value!")
+
+        found: list[Element] = []
+
+        current: Element = self
+
+        if (count := len(parts := self._parse_path(path))) > 0:
+            root: Element = self.root
+
+            for index, part in enumerate(parts, start=1):
+                # print(index, part)
+
+                if part == ".":
+                    current = root
+
+                    if index == count:
+                        found.append(child)
+                else:
+                    for child in current.children:
+                        if part == "*" or child.fullname == part:
+                            current = child
+
+                            if index == count:
+                                found.append(child)
+
+        return found
+
+    def tostring(
+        self,
+        pretty: bool = False,
+        indent: str | int = None,
+        encoding: str = None,
+        **kwargs,
+    ) -> str | bytes:
+        """Supports serializing the current Element tree to a string or to a bytes array
+        if a string encoding, such as 'UTF-8', is specified."""
+
+        if not isinstance(pretty, bool):
+            raise TypeError("The 'pretty' argument must have a boolean value!")
+
+        if indent is None:
+            indent = 2
+
+        if isinstance(indent, (int, str)):
+            if isinstance(indent, int) and indent > 0:
+                indent = " " * indent
+            elif isinstance(indent, str) and len(indent) > 0:
+                pass
+            else:
+                indent = ""
+        else:
+            raise TypeError(
+                "The 'indent' argument, if specified, must have an integer or string value!"
+            )
+
+        if encoding is None:
+            pass
+        elif not isinstance(encoding, str):
+            raise TypeError("The 'encoding' argument must have a string value!")
+
+        def stringify(
+            element: Element,
+            depth: int,
+            pretty: bool = False,
+            indent: str = None,
+            **kwargs,
+        ) -> str:
+            """Convert the current XML element to a serialized XML string, recursively
+            iterating downward through the tree and all of its children."""
+
+            if indent is None:
+                indent = ""
+
+            newline: bool = False
+
+            # Begin the element tag
+            string: str = f"<{element.fullname}"
+
+            # Add any promoted namespaces (those which should proceed any attributes)
+            count = len(element.namespaced)
+            for index, namespace in enumerate(element.namespaced, start=1):
+                if not namespace.promoted:
+                    continue
+
+                if pretty and count > 1 and (newline or (index > 1 and index <= count)):
+                    string += f"\n{indent * (depth + 2)}"
+
+                string += f' xmlns:{namespace.prefix}="{namespace.uri}"'
+
+            # Add any attributes
+            count = len(element.attributes)
+            for index, (key, value) in enumerate(element.attributes.items(), start=1):
+                if pretty and count > 1 and index >= 1 and index <= count:
+                    string += f"\n{indent * (depth + 2)}"
+                    newline = True
+
+                string += f' {key}="{value}"'
+
+            # Add any non-promoted namespaces (those which can follow any attributes)
+            count = len(element.namespaced)
+
+            if count > 2:
+                newline = True
+
+            for index, namespace in enumerate(element.namespaced, start=1):
+                if namespace.promoted:
+                    continue
+
+                if pretty and count > 1 and (newline or (index > 1 and index <= count)):
+                    string += f"\n{indent * (depth + 2)}"
+
+                string += f' xmlns:{namespace.prefix}="{namespace.uri}"'
+
+            # Close an empty element tag if the element lacks text content and children
+            if element.text is None and element.empty is True:
+                string += f"/>"
+
+            # Otherwise include the element's optional text and children
+            else:
+                string += f">"
+
+                if not element.mixed and (element.text and element.children):
+                    raise ValueError(
+                        "The current XML element cannot be serialized as mixed content mode is not enabled, but both node text and children have been specified; please either enable mixed mode or adjust the element's node contents."
+                    )
+
+                # Include the element's text content, if any
+                if element.text and (element.mixed or not element.children):
+                    string += element.text
+
+                # Include the element's children, if any
+                if element.children and (element.mixed or not element.text):
+                    for child in element.children:
+                        if pretty:
+                            string += f"\n{indent * (depth + 1)}"
+
+                        string += stringify(
+                            element=child,
+                            depth=(depth + 1),
+                            pretty=pretty,
+                            indent=indent,
+                            **kwargs,
+                        )
+
+                    if pretty:
+                        string += f"\n{indent * (depth)}"
+
+                string += f"</{element.fullname}>"
+
+            return string
+
+        string = stringify(
+            element=self,
+            depth=0,
+            pretty=pretty,
+            indent=indent,
+            **kwargs,
+        )
+
+        string = string.strip()
+
+        if encoding:
+            string = string.encode(encoding)
+
+        return string

maxml/logging/__init__.py

@@ -0,0 +1,3 @@
+import logging
+
+logger = logging.getLogger("maxml")

maxml/namespace/__init__.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+import zlib
+
+from maxml.logging import logger
+
+logger = logger.getChild(__name__)
+
+
+class Namespace(object):
+    """The Namespace class represents an XML namespace"""
+
+    _prefix: str = None
+    _uri: str = None
+    _promoted: bool = False
+
+    def __init__(self, prefix: str, uri: str):
+        """Initialize the Namespace class"""
+
+        if not isinstance(prefix, str):
+            raise TypeError("The 'prefix' argument must have a string value!")
+
+        self._prefix = prefix
+
+        if not isinstance(uri, str):
+            raise TypeError("The 'uri' argument must have a string value!")
+
+        self._uri = uri
+
+    def __str__(self) -> str:
+        """Return a string representation of the class for debugging purposes."""
+
+        return f"<{self.__class__.__name__}({self._prefix}:{self._uri})>"
+
+    def __repr__(self) -> str:
+        """Return a more detailed representation of the class for debugging purposes."""
+
+        return f"<{__name__}.{self.__class__.__name__}({self._prefix}:{self._uri}) object at 0x{hex(id(self))}>"
+
+    @staticmethod
+    def stableid(value: str):
+        """Generate a stable id for a given string value; this is used with __hash__."""
+
+        if not isinstance(value, str):
+            raise TypeError("The 'value' argument must have a string value!")
+
+        return zlib.crc32(value.encode()) & 0xFFFFFFFF
+
+    def __hash__(self) -> int:
+        """Generate a stable hash value for a Namespace with a given prefix and URI."""
+
+        return self.stableid(self._prefix) + self.stableid(self._uri)
+
+    def __eq__(self, other: Namespace) -> bool:
+        """Support comparing Namespace instances by determining if the prefix and URI
+        match, allowing copies of Namespace instances to compare as equal even if they
+        are distinctly different copies in memory."""
+
+        logger.debug(
+            "%s.__eq__(self: %s, other: %s)",
+            self.__class__.__name__,
+            self,
+            other,
+        )
+
+        if not isinstance(other, Namespace):
+            return False
+
+        if self.prefix != other.prefix:
+            return False
+
+        if self.uri != other.uri:
+            return False
+
+        return True
+
+    @property
+    def prefix(self) -> str:
+        """Return the prefix held by the Namespace."""
+
+        return self._prefix
+
+    @property
+    def uri(self) -> str:
+        """Return the URI held by the Namespace."""
+
+        return self._uri
+
+    def copy(self) -> Namespace:
+        """Create an independent copy of the current Namespace instance."""
+
+        return Namespace(prefix=self.prefix, uri=self.uri)
+
+    @property
+    def promoted(self) -> bool:
+        """Return the promoted status of the Namespace instance as set or unset through
+        the 'promote' and 'unpromote' helper methods."""
+
+        return self._promoted
+
+    @promoted.setter
+    def promoted(self, promoted: bool):
+        """Support setting the promoted value via the property accessor."""
+
+        if not isinstance(promoted, bool):
+            raise TypeError("The 'promoted' argument must have a boolean value!")
+
+        self._promoted = promoted
+
+    def promote(self) -> Namespace:
+        """Mark the current Namespace instance as having been 'promoted' which allows
+        it to be listed before any attributes on the Element it is associated with; as
+        this method returns a reference to 'self' it may be chained with other calls."""
+
+        self._promoted = True
+
+        return self
+
+    def unpromote(self) -> Namespace:
+        """Mark the current Namespace instance as having been 'unpromoted' preventing it
+        from being listed before any attributes on the Element it is associated with; as
+        this method returns a reference to 'self' it may be chained with other calls."""
+
+        self._promoted = False
+
+        return self

maxml/version.txt

@@ -0,0 +1 @@
+1.0.0

maxml-1.0.0.dist-info/METADATA

@@ -0,0 +1,330 @@
+Metadata-Version: 2.4
+Name: maxml
+Version: 1.0.0
+Summary: A streamlined pure Python XML serializer.
+Author: Daniel Sissman
+License-Expression: MIT
+Project-URL: documentation, https://github.com/bluebinary/maxml/blob/main/README.md
+Project-URL: changelog, https://github.com/bluebinary/maxml/blob/main/CHANGELOG.md
+Project-URL: repository, https://github.com/bluebinary/maxml
+Project-URL: issues, https://github.com/bluebinary/maxml/issues
+Project-URL: homepage, https://github.com/bluebinary/maxml
+Keywords: xml,serialization,xml serialization,xml writer
+Platform: any
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: hybridmethod==1.0.*
+Provides-Extra: development
+Requires-Dist: black==24.10.*; extra == "development"
+Requires-Dist: pytest==8.3.*; extra == "development"
+Requires-Dist: pytest-codeblocks==0.17.0; extra == "development"
+Provides-Extra: distribution
+Requires-Dist: build; extra == "distribution"
+Requires-Dist: twine; extra == "distribution"
+Requires-Dist: wheel; extra == "distribution"
+
+# MaXML: A Pure Python XML Serializer
+
+The MaXML library provides a streamlined pure Python XML serializer.
+
+### Requirements
+
+The MaXML library has been tested with Python 3.10, 3.11, 3.12 and 3.13. The library is
+not compatible with Python 3.9 or earlier.
+
+### Installation
+
+The MaXML library is available from PyPI, so may be added to a project's dependencies
+via its `requirements.txt` file or similar by referencing the MaXML library's name,
+`maxml`, or the library may be installed directly into your local runtime environment
+using `pip` via the `pip install` command by entering the following into your shell:
+
+	$ pip install maxml
+
+### Example Usage
+
+To use the MaXML library, import the library's and begin creating your XML document:
+
+```python
+import maxml
+
+root = maxml.Element(name="my:node", namespace="http://namespace.example.org/my")
+
+child = root.subelement(name="my:child-node")
+
+child.set("my-attribute", "my-attribute-value")
+
+child.text = "testing"
+
+root.tostring(pretty=True)
+```
+
+The above example will result in the following XML:
+
+```xml
+<my:node xmlns:my="http://namespace.example.org/my">
+  <my:child-node my-attribute="my-attribute-value">testing</my:child-node>
+</my:node>
+```
+
+### Methods & Properties
+
+The MaXML library provides two main classes for use in creating and serializing XML, the
+`Elements` class that is used to represent nodes in the XML document tree along with any
+attributes those nodes have, their associated namespaces, any text content and children,
+and the `Namespace` class for holding information about namespaces.
+
+The classes and their methods and properties are listed below:
+
+#### Element Class
+
+The `Element` class constructor `Element(...)` takes the following arguments:
+
+ * `name` (`str`) – The required `name` argument sets the prefixed name of the element.
+
+ * `text` (`str`) – The optional `text` argument can be used to specify the text content
+	of the element; alternatively it can be set later via the `text` property.
+
+ * `namespace` (`Namespace` | `str`) – The optional `namespace` argument can be used to
+	specify the namespace for the element while it is being created; the namespace can
+	either be specified as the URI that corresponds with the prefix specified as part of
+	the element's name, or can be a reference to a `Namespace` class instance that holds
+	the corresponding `prefix` and matching `URI`. If the matching namespace has already
+	been registered before the element is created via the class' `register_element()`
+	method, then it is not necessary to specify a `namespace` argument when an element
+	that references that namespace (via its `name` prefix) is created.
+
+ * `mixed` (`bool`) – The optional `mixed` argument can be used to override the default
+	mixed-content mode of the element; by default each element allows mixed-content
+	which means that the element can contain both text content and children; if an
+	element should only be allowed to contain text content or children, then
+	`mixed` can be set to `False` during the construction of the element, which will
+	then prevent both content types from being serialized and will instead result in an
+	error being raised.
+
+ * `parent` (`Element`) – The optional `parent` property is used internally by the
+	library when sub-elements are created to set the appropriate parent reference; this
+	property should not be set manually unless one is conformable with the possible
+	side-effects that may occur.
+
+The `Element` class provides the following methods:
+
+ * `register_namespace(prefix: str, uri: str)` – The `register_namespace()`  method
+	supports registering namespaces globally for the module or per instance depending
+	on whether the method is called on the class directly or whether it is called on a
+	specific instance of the class.
+
+	If a namespace is registered globally for the module, the registered namespaces
+	become available for use by any instance of the class created within the program
+	after that point. This is especially useful for widely used XML namespaces which
+	obviates the need to re-register these widely used namespaces for each instance.
+
+	If there are namespaces which are specific to a document that is being created
+	and that won't be used elsewhere in the program, then those namespaces can be
+	registered on the specific class instance within which they will be used without
+	affecting the global list of registered namespaces.
+
+	Each namespace consists of a prefix which can be used to prefix element names
+	and the URI associated with that namespace prefix.
+
+	For example, the 'rdf' prefix is associated with the following canonical URI:
+		"http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+
+	This would be registered globally by calling:
+
+	```python
+	from maxml import Element
+	
+	Element.register_namespace(
+	  prefix="rdf",
+	  uri="http://www.w3.org/1999/02/22-rdf-syntax-ns#",
+	)
+	```
+
+	Or this would be registered locally on an instance of the class before its use by a
+	sub-element by calling:
+
+	```python
+	from maxml import Element
+	
+	element = Element(name="my:test", namespace="http://namespace.example.org/my")
+	
+	element.register_namespace(
+	  prefix="rdf",
+	  uri="http://www.w3.org/1999/02/22-rdf-syntax-ns#",
+	)
+	```
+
+	Where `instance` was the variable referencing the desired instance of the class.
+
+ * `set(name: str, value: object)` (`Element`) – The `set()` supports setting a named
+	attribute value on the current element; if the named attribute already exists, its
+	value is overwritten. The `set()` method returns a reference to `self` so it may be
+	chained with other calls on the element.
+
+ * `get(name: str, default: object = None)` (`object` | `None`) – The `get()` supports
+	getting the value of a named attribute on the Element if the named attribute exists,
+	returning the optional `default` value if the named attributes does not exist or if
+	the `default` value has not been specified, returning `None` otherwise.
+
+ * `unset(name: str)` (`Element`) – The `set()` supports unsetting a named attribute on
+	the element. The `unset()` method returns a reference to `self` so it may be chained
+	with other calls on the element.
+
+ * `subelement(name: str, **kwargs)` (`Element`) – The `subelement()` method creates a
+	child element nested under the current element. It requires a `name` and optionally
+	accepts all of the other arguments that the `Element` class constructor accepts as
+	documented above. When a child element is created, its parent is automatically set
+	to the element it is nested under. The `subelement()` method returns a reference to
+	the newly created element, thus other calls on that element may be chained.
+
+ * `find(path: str)` (`Element` | `None`) – The `find()` method can be used to find the
+	matching element nested within the current element as specified by the element path
+	which consists of one or more prefixed names and optional wildcard characters.
+	
+	The path to the element we wish to find can be specified from the root node of the
+	tree by starting the path with the "//" marker which indicates the root node, or the
+	path can be specified as a relative path by omitting this, which will result in the
+	search starting at the current element node. The path should be specified with the
+	name of the element at each level of the nesting that should be matched against to
+	reach the desired node; each element node name should be separated by a single "/"
+	character, and if any node name could be matched as part of the search the wildcard
+	character "*" can be used in place of an element node name.
+
+ * `findall(path: str)` (`list[Element]`) – The `findall()` method can be used to find
+	the matching elements nested within the current element as specified by the element
+	path which consists of one or more prefixed names and optional wildcard characters.
+	
+	The `findall()` method uses the same search path format as the `find()` method
+	described above, the only difference being that if multiple elements are found at
+	the end of the search, all matching elements will be returned instead of the first
+	match found as is the case with the `find` method.
+
+ * `tostring(pretty: bool = False, indent: str | int = None, encoding: str = None)` –
+	The `tostring()` method supports serializing the current element tree to a string,
+	or to a bytes array if a string encoding, such as 'UTF-8' is specified.
+	
+	To create a 'pretty' printed string, set the `pretty` argument to `True` and set an
+	optional indent, which by default is set to two spaces per level of indentation. To
+	set the indent level to 1 or more spaces, set `indent` to a positive integer value
+	of the number of spaces that should be used for the indentation per level of nesting
+	or to use a different whitespace character, such as a tab, set the `indent` value to
+	a tab character using the escape sequence for a tab, `"\t"`.
+	
+	To have the method return an encoded `bytes` sequence instead of a unicode string,
+	set the optional `encoding` argument to a valid string encoding, such as `"UTF-8"`.
+
+The `Element` class provides the following properties:
+
+ * `prefix` (`str`) – The `prefix` property returns the prefix portion of the element's
+	tag full name, for example `my` from `my:test`.
+
+ * `name` (`str`) – The `name` property getter returns the name portion of the element's
+	tag full name, for example `test` from `my:test`.
+
+ * `fullname` (`str`) – The `fullname` property returns the full name of the element's
+	tag, for example `my:test`.
+
+ * `namespace` (`Namespace`) – The `namespace` property returns the namespace associated
+	with the element, as either registered before the element was created, or created by
+	the process of creating the element if the optional `namespace` property was used.
+
+ * `depth` (`int`) – The `depth` property returns depth of the element in the tree.
+
+ * `parent` (`Element` | `None`) – The `parent` property returns the parent, if any, of
+	the element; the root node of the tree will not have a parent, while all other
+	elements will have an assigned parent, set automatically when a sub-element is made.
+
+ * `children` (`list[Element]`) – The `children` property returns the list of children
+	elements associated with the element, if any have been assigned.
+
+ * `attributes` (`dict[str, str]`) – The `attributes` property returns a dictionary of
+	the attributes associated with the element, if any have been assigned, where the key
+	of each entry is the name of the attribute and the value is its value.
+
+ * `text` (`str` | `None`) – The `text` property returns the text of the element if any
+	has been assigned or `None` otherwise.
+
+ * `mixed` (`bool`) – The `mixed` property returns the mixed-content status of the
+	element which determines whether the element can have both text content and children
+	or if at most it can only have one or the other. By default each element allows both
+	content types, but by setting the `mixed` argument on the `Element` constructor to
+	`False`, mixed-content mode will be turned-off.
+
+ * `root` (`Element`) – The `root` property returns the root element of the tree from
+	anywhere else within the tree.
+
+ * `namespaces` (`set[Namespace]`) – The `namespaces` property returns the full `set` of
+	namespaces associated with the element including any inherited from its parents; the
+	set can be used to inspect the associated namespaces, but its primary use is to help
+	facilitate the serialization of the document.
+
+ * `namespaced` (`set[Namespace]`) – The `namespaced` property returns the unique `set`
+	of namespaces associated with the element that have not already been referenced by
+	a parent node, thus ensuring only the newly referenced namespaces are introduced in
+	the serialized document rather than potentially repeated references to namespaces
+	which have already been referenced previously; the set can be used to inspect the
+	associated namespaces, but its primary use is to help facilitate the serialization.
+
+#### Namespace Class
+
+The `Namespace` class constructor `Namespace(...)` takes the following arguments:
+
+ * `prefix` (`str`) – The required `prefix` argument sets the namespace prefix.
+ * `uri` (`str`) – The required `uri` argument sets the namespace URI.
+
+The `Namespace` class provides the following methods:
+
+ * `copy()` (`Namespace`) – The `copy()` method creates an independent copy of the
+	current Namespace instance and returns it.
+
+ * `promote()` (`Namespace`) – The `promote()` marks the current Namespace instance as
+	having been 'promoted' which allows it to be listed before any attributes on the
+	Element it is associated with; as this method returns a reference to `self` it may
+	be chained with other calls.
+
+ * `unpromote()` (`Namespace`) – The `unpromote()` marks the current Namespace instance
+	as having been 'un-promoted' preventing it from being listed before any attributes
+	on the Element it is associated with; as this method returns a reference to `self`
+	it may be chained with other calls.
+
+The `Namespace` class provides the following properties:
+
+ * `prefix` (`str`) – The `prefix` property returns the prefix held by the namespace.
+ * `uri` (`str`) – The `uri` property returns the URI held by the namespace.
+ * `promoted` (`bool`) – The `promoted` property getter returns the promoted state of the
+	Namespace instance as set or unset through the `promote()` and `unpromote()` helper
+	methods or via the `promoted` property setter.
+ * `promoted` (`bool`) – The `promoted` property setter supports setting the `promoted`
+	property value via the property accessor.
+
+
+### Unit Tests
+
+The MaXML library includes a suite of comprehensive unit tests which ensure that the
+library functionality operates as expected. The unit tests were developed with and are
+run via `pytest`.
+
+To ensure that the unit tests are run within a predictable runtime environment where all of the necessary dependencies are available, a [Docker](https://www.docker.com) image is created within which the tests are run. To run the unit tests, ensure Docker and Docker Compose is [installed](https://docs.docker.com/engine/install/), and perform the following commands, which will build the Docker image via `docker compose build` and then run the tests via `docker compose run` – the output of running the tests will be displayed:
+
+```shell
+$ docker compose build
+$ docker compose run tests
+```
+
+To run the unit tests with optional command line arguments being passed to `pytest`, append the relevant arguments to the `docker compose run tests` command, as follows, for example passing `-vv` to enable verbose output:
+
+```shell
+$ docker compose run tests -vv
+```
+
+See the documentation for [PyTest](https://docs.pytest.org/en/latest/) regarding available optional command line arguments.
+
+### Copyright & License Information
+
+Copyright © 2025 Daniel Sissman; licensed under the MIT License.

maxml-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+maxml/__init__.py,sha256=QuUB-oFrPKRZ4XzPuk4Mt8r35EMx652PALyAeWvQXIo,72
+maxml/version.txt,sha256=klIfw8vZZL3J9YSpkbif3apXVO0cyW1tQkRTOGacEwU,5
+maxml/element/__init__.py,sha256=jCrnThqnN6hACfmbsFZcY8MMV4czBCmoYOOpVpRjzDQ,22673
+maxml/logging/__init__.py,sha256=AMpvZEQH9GIBe8609sMwb2T64rovpkRRCc9rs2kHy8g,52
+maxml/namespace/__init__.py,sha256=iZqHWuGi09KtMTr7wHiyTQLXB2TFljUir8wZGLi2b60,3882
+maxml-1.0.0.dist-info/METADATA,sha256=LW_yxkgZyiuT3fOmtnkiWKoEra0hHpvY7M-igpXXt6g,16164
+maxml-1.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+maxml-1.0.0.dist-info/top_level.txt,sha256=ZFK3SmCc04Dzhl9QkO_hVBAEiHwCNrwn8X_PINWE9C4,6
+maxml-1.0.0.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+maxml-1.0.0.dist-info/RECORD,,

maxml-1.0.0.dist-info/WHEEL

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

maxml-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+maxml

maxml-1.0.0.dist-info/zip-safe

@@ -0,0 +1 @@
+