maxml 1.0.2__py3-none-any.whl → 1.0.4__py3-none-any.whl

maxml/__init__.py

@@ -1,2 +1,4 @@
 from maxml.element import Element
 from maxml.namespace import Namespace
+from maxml.enumerations import Escape
+from maxml.exceptions import MaXMLError

maxml/element/__init__.py

@@ -2,9 +2,15 @@ from __future__ import annotations
 
 from maxml.namespace import Namespace
 from maxml.logging import logger
+from maxml.enumerations import (
+    Context,
+    Escape,
+)
+from maxml.exceptions import MaXMLError
 
 from classicist import hybridmethod
 
+import re
 
 logger = logger.getChild(__name__)
 
@@ -22,7 +28,7 @@ class Element(object):
     _mixed: bool = False
 
     @hybridmethod
-    def register_namespace(self, prefix: str, uri: str):
+    def register_namespace(self, prefix: str, uri: str, promoted: bool = False):
         """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.
@@ -68,6 +74,9 @@ class Element(object):
         if not isinstance(uri, str):
             raise TypeError("The 'uri' argument must have a string value!")
 
+        if not isinstance(promoted, bool):
+            raise TypeError("The 'promoted' argument must have a boolean value!")
+
         for namespace in self._namespaces:
             if namespace.prefix == prefix:
                 if namespace.uri == uri:
@@ -77,12 +86,12 @@ class Element(object):
                     )
                     break
                 else:
-                    raise ValueError(
-                        "The '%s' namespace has already been registered with a different URI!"
-                        % (prefix)
+                    raise MaXMLError(
+                        "The '%s' namespace, %s, has already been registered with a different URI: %s!"
+                        % (prefix, uri, namespace.uri)
                     )
         else:
-            if namespace := Namespace(prefix=prefix, uri=uri):
+            if namespace := Namespace(prefix=prefix, uri=uri, promoted=promoted):
                 self._namespaces.add(namespace)
 
     def __init__(
@@ -170,7 +179,7 @@ class Element(object):
 
                         break
                 else:
-                    raise ValueError(
+                    raise MaXMLError(
                         f"No namespace has been registered for the '{prefix}' prefix associated with the '{name}' element!"
                     )
 
@@ -180,7 +189,7 @@ class Element(object):
                 if namespace.uri == uri:
                     break
             else:
-                namespace = Namespace(prefix=prefix, uri=uri)
+                namespace = Namespace(prefix=prefix, uri=uri, promoted=False)
 
             self.__class__._namespaces.add(namespace)
 
@@ -557,6 +566,7 @@ class Element(object):
         pretty: bool = False,
         indent: str | int = None,
         encoding: str = None,
+        escape: Escape = Escape.All,
         **kwargs,
     ) -> str | bytes:
         """Supports serializing the current Element tree to a string or to a bytes array
@@ -565,6 +575,11 @@ class Element(object):
         if not isinstance(pretty, bool):
             raise TypeError("The 'pretty' argument must have a boolean value!")
 
+        if not isinstance(escape, Escape):
+            raise TypeError(
+                "The 'escape' argument must reference an Escape enumeration option!"
+            )
+
         if indent is None:
             indent = 2
 
@@ -585,10 +600,54 @@ class Element(object):
         elif not isinstance(encoding, str):
             raise TypeError("The 'encoding' argument must have a string value!")
 
+        def escaper(value: str, context: Context, escape: Escape) -> str:
+            """Helper method to escape special characters in XML attributes and text."""
+
+            if isinstance(value, str):
+                pass
+            elif hasattr(value, "__str__"):
+                value = str(value)
+            else:
+                raise TypeError(
+                    "The 'value' argument must have a string value or a value that can be cast to a string!"
+                )
+
+            replacements: dict[str, str] = {
+                "&": "&",
+                "<": "&lt;",
+                ">": "&gt;",
+                '"': "&quot;",
+                "'": "&apos;",
+            }
+
+            if context is Context.Attribute:
+                # Required replacements for element attribute values
+                required: list[str] = ["&", "<", '"']
+            elif context is Context.Text:
+                # Required replacements for element text
+                required: list[str] = ["&", "<"]
+            else:
+                # Require all replacements for other contexts
+                required: list[str] = [key for key in replacements]
+
+            for search, replacement in replacements.items():
+                if (escape is Escape.All) or (search in required):
+                    if search == "&":
+                        # Ensure only standalone "&" characters are replaced, ignoring
+                        # any that are part of an XML special character escape sequence
+                        value = re.sub(
+                            r"&(?!(([a-z]+|#x?[0-9a-fA-F]+);))", replacement, value
+                        )
+                    else:
+                        value = value.replace(search, replacement)
+
+            return value
+
         def stringify(
             element: Element,
             depth: int,
             pretty: bool = False,
+            escape: Escape = Escape.All,
             indent: str = None,
             **kwargs,
         ) -> str:
@@ -606,7 +665,7 @@ class Element(object):
             # 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:
+                if namespace.promoted is False:
                     continue
 
                 if pretty and count > 1 and (newline or (index > 1 and index <= count)):
@@ -624,6 +683,8 @@ class Element(object):
                     string += f"\n{indent * (depth + 2)}"
                     newline = True
 
+                value = escaper(value, context=Context.Attribute, escape=escape)
+
                 string += f' {key}="{value}"'
 
             # Add any non-promoted namespaces (those which can follow any attributes)
@@ -633,7 +694,7 @@ class Element(object):
                 newline = True
 
             for index, namespace in enumerate(element.namespaced, start=1):
-                if namespace.promoted:
+                if namespace.promoted is True:
                     continue
 
                 if pretty and count > 1 and (newline or (index > 1 and index <= count)):
@@ -656,7 +717,7 @@ class Element(object):
 
                 # Include the element's text content, if any
                 if element.text and (element.mixed or not element.children):
-                    string += element.text
+                    string += escaper(element.text, context=Context.Text, escape=escape)
 
                 # Include the element's children, if any
                 if element.children and (element.mixed or not element.text):
@@ -669,6 +730,7 @@ class Element(object):
                             depth=(depth + 1),
                             pretty=pretty,
                             indent=indent,
+                            escape=escape,
                             **kwargs,
                         )
 
@@ -684,6 +746,7 @@ class Element(object):
             depth=0,
             pretty=pretty,
             indent=indent,
+            escape=escape,
             **kwargs,
         )
 

maxml/enumerations/__init__.py

@@ -0,0 +1,25 @@
+from enumerific import Enumeration, auto
+
+
+class Context(Enumeration):
+    """List of XML contexts, to denote the XML context currently being processed."""
+
+    Unknown = auto()
+    Root = auto(description="Document root node")
+    Prolog = auto(description="Document declaration (prolog)")
+    Instruction = auto(description="Document processing instruction")
+    DocType = auto(description="Document type")
+    Element = auto(description="Element comprising opening/closing or self-closing tag")
+    TagOpen = auto(description="Opening tag of an element (maybe self-closing)")
+    TagClose = auto(description="Closing tag of an element")
+    Attribute = auto(description="Attribute held by an element's tag")
+    Text = auto(description="Text held between an element's opening and closing tags")
+    Data = auto(description="Data held in a CDATA section")
+    Comment = auto(description="Comment held in a comment section")
+
+
+class Escape(Enumeration):
+    """List of XML special character escape modes."""
+
+    All = auto(description="Escape all XML special characters")
+    Required = auto(description="Escpae only required XML special characters")

maxml/exceptions/__init__.py

@@ -0,0 +1,2 @@
+class MaXMLError(Exception):
+    pass

maxml/namespace/__init__.py

@@ -14,7 +14,7 @@ class Namespace(object):
     _uri: str = None
     _promoted: bool = False
 
-    def __init__(self, prefix: str, uri: str):
+    def __init__(self, prefix: str, uri: str, promoted: bool = False):
         """Initialize the Namespace class"""
 
         if not isinstance(prefix, str):
@@ -27,6 +27,11 @@ class Namespace(object):
 
         self._uri = uri
 
+        if not isinstance(promoted, bool):
+            raise TypeError("The 'promoted' argument must have a boolean value!")
+
+        self._promoted = promoted
+
     def __str__(self) -> str:
         """Return a string representation of the class for debugging purposes."""
 

maxml/version.txt

@@ -1 +1 @@
-1.0.2
+1.0.4

{maxml-1.0.2.dist-info → maxml-1.0.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maxml
-Version: 1.0.2
+Version: 1.0.4
 Summary: A streamlined pure Python XML serializer.
 Author: Daniel Sissman
 License-Expression: MIT
@@ -115,10 +115,10 @@ The `Element` class constructor `Element(...)` takes the following arguments:
 
 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.
+ * `register_namespace(prefix: str, uri: str, promoted: bool = False)` –
+	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
@@ -132,6 +132,12 @@ The `Element` class provides the following methods:
 
 	Each namespace consists of a prefix which can be used to prefix element names
 	and the URI associated with that namespace prefix.
+	
+	Optionally, a namespace can be marked as promoted during registration, which will
+	result in the namespace being serialized into the XML before any attributes on the
+	element. Namespaces that are not marked as promoted will appear after attributes.
+	Namespace promotion can be enabled for a given namespace during registration by
+	passing the optional `promoted` keyword argument with the value of `True`.
 
 	For example, the 'rdf' prefix is associated with the following canonical URI:
 		"http://www.w3.org/1999/02/22-rdf-syntax-ns#"

maxml-1.0.4.dist-info/RECORD

@@ -0,0 +1,12 @@
+maxml/__init__.py,sha256=9wLSTIlZTXinpBr9ABp_PUWhfxubtNM89Iac2VCNet8,150
+maxml/version.txt,sha256=rqWtvvV0eFJzxPOcG3aHz4AZk-DLa_Z4GkFonk7bsgw,5
+maxml/element/__init__.py,sha256=TDHieGdGX6ypTWq885ilJgO-sRUt4AT8twa3w9MElOM,26396
+maxml/enumerations/__init__.py,sha256=N15XKtEZp2cFwqq_1GXyODqoOE--z9WukZGt_rFur2E,1153
+maxml/exceptions/__init__.py,sha256=qMI3bIXJe6zDXzRnxdW3v6wbxSYfd1oK-9lnxvZzzjQ,38
+maxml/logging/__init__.py,sha256=AMpvZEQH9GIBe8609sMwb2T64rovpkRRCc9rs2kHy8g,52
+maxml/namespace/__init__.py,sha256=1TT9vo6iWQyxEOLPzvHd_cf4i5_w3F-tdOm_k-VABQM,4067
+maxml-1.0.4.dist-info/METADATA,sha256=UTM15oNsmwGV5YFujZhMYBXKGIF8U8D_BQ34OVENOj4,16626
+maxml-1.0.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+maxml-1.0.4.dist-info/top_level.txt,sha256=ZFK3SmCc04Dzhl9QkO_hVBAEiHwCNrwn8X_PINWE9C4,6
+maxml-1.0.4.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+maxml-1.0.4.dist-info/RECORD,,

maxml-1.0.2.dist-info/RECORD

@@ -1,10 +0,0 @@
-maxml/__init__.py,sha256=QuUB-oFrPKRZ4XzPuk4Mt8r35EMx652PALyAeWvQXIo,72
-maxml/version.txt,sha256=v-wuNFg62n5q8stzmT-3Wj9xR6bJQ-X_X1xClPxXe5A,5
-maxml/element/__init__.py,sha256=8N6ePtw7nOX6VVQ0eG5mmDJkBXo8S1qwVF3k9X2OmLo,23843
-maxml/logging/__init__.py,sha256=AMpvZEQH9GIBe8609sMwb2T64rovpkRRCc9rs2kHy8g,52
-maxml/namespace/__init__.py,sha256=iZqHWuGi09KtMTr7wHiyTQLXB2TFljUir8wZGLi2b60,3882
-maxml-1.0.2.dist-info/METADATA,sha256=J9F0r0aKB7prWv2tALoHhPRtFYCUXm096UOdoRQW5Fc,16193
-maxml-1.0.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-maxml-1.0.2.dist-info/top_level.txt,sha256=ZFK3SmCc04Dzhl9QkO_hVBAEiHwCNrwn8X_PINWE9C4,6
-maxml-1.0.2.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-maxml-1.0.2.dist-info/RECORD,,