maxml 1.0.1__tar.gz → 1.0.3__tar.gz

{maxml-1.0.1 → maxml-1.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maxml
-Version: 1.0.1
+Version: 1.0.3
 Summary: A streamlined pure Python XML serializer.
 Author: Daniel Sissman
 License-Expression: MIT
@@ -18,7 +18,8 @@ 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.*
+Requires-Dist: classicist==1.0.*
+Requires-Dist: enumerific==1.0.*
 Provides-Extra: development
 Requires-Dist: black==24.10.*; extra == "development"
 Requires-Dist: pytest==8.3.*; extra == "development"
@@ -48,7 +49,7 @@ using `pip` via the `pip install` command by entering the following into your sh
 
 ### Example Usage
 
-To use the MaXML library, import the library's and begin creating your XML document:
+To use the MaXML library, import the library and begin creating your XML document:
 
 ```python
 import maxml

{maxml-1.0.1 → maxml-1.0.3}/README.md

@@ -18,7 +18,7 @@ using `pip` via the `pip install` command by entering the following into your sh
 
 ### Example Usage
 
-To use the MaXML library, import the library's and begin creating your XML document:
+To use the MaXML library, import the library and begin creating your XML document:
 
 ```python
 import maxml

{maxml-1.0.1 → maxml-1.0.3}/requirements.txt

@@ -1,2 +1,3 @@
 # MaXML Library: Runtime Dependencies
-hybridmethod==1.0.*
+classicist==1.0.*
+enumerific==1.0.*

maxml-1.0.3/source/maxml/__init__.py

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

{maxml-1.0.1 → maxml-1.0.3}/source/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 hybridmethod import hybridmethod
+from classicist import hybridmethod
 
+import re
 
 logger = logger.getChild(__name__)
 
@@ -71,15 +77,15 @@ class Element(object):
         for namespace in self._namespaces:
             if namespace.prefix == prefix:
                 if namespace.uri == uri:
-                    logger.warning(
+                    logger.info(
                         " >>> The '%s' namespace has already been registered..."
                         % (prefix)
                     )
                     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):
@@ -170,7 +176,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!"
                     )
 
@@ -557,6 +563,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 +572,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 +597,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:
@@ -624,6 +680,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)
@@ -656,7 +714,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 +727,7 @@ class Element(object):
                             depth=(depth + 1),
                             pretty=pretty,
                             indent=indent,
+                            escape=escape,
                             **kwargs,
                         )
 
@@ -684,6 +743,7 @@ class Element(object):
             depth=0,
             pretty=pretty,
             indent=indent,
+            escape=escape,
             **kwargs,
         )
 

maxml-1.0.3/source/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-1.0.3/source/maxml/exceptions/__init__.py

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

maxml-1.0.3/source/maxml/version.txt

@@ -0,0 +1 @@
+1.0.3

{maxml-1.0.1 → maxml-1.0.3}/source/maxml.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maxml
-Version: 1.0.1
+Version: 1.0.3
 Summary: A streamlined pure Python XML serializer.
 Author: Daniel Sissman
 License-Expression: MIT
@@ -18,7 +18,8 @@ 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.*
+Requires-Dist: classicist==1.0.*
+Requires-Dist: enumerific==1.0.*
 Provides-Extra: development
 Requires-Dist: black==24.10.*; extra == "development"
 Requires-Dist: pytest==8.3.*; extra == "development"
@@ -48,7 +49,7 @@ using `pip` via the `pip install` command by entering the following into your sh
 
 ### Example Usage
 
-To use the MaXML library, import the library's and begin creating your XML document:
+To use the MaXML library, import the library and begin creating your XML document:
 
 ```python
 import maxml

{maxml-1.0.1 → maxml-1.0.3}/source/maxml.egg-info/SOURCES.txt

@@ -12,6 +12,8 @@ source/maxml.egg-info/requires.txt
 source/maxml.egg-info/top_level.txt
 source/maxml.egg-info/zip-safe
 source/maxml/element/__init__.py
+source/maxml/enumerations/__init__.py
+source/maxml/exceptions/__init__.py
 source/maxml/logging/__init__.py
 source/maxml/namespace/__init__.py
 tests/test_element.py

{maxml-1.0.1 → maxml-1.0.3}/source/maxml.egg-info/requires.txt

@@ -1,4 +1,5 @@
-hybridmethod==1.0.*
+classicist==1.0.*
+enumerific==1.0.*
 
 [development]
 black==24.10.*

{maxml-1.0.1 → maxml-1.0.3}/tests/test_element.py

@@ -391,3 +391,73 @@ def test_maxml_fragment_tostring(element: maxml.Element, data: callable):
     assert isinstance(compare, str)
 
     assert string == compare
+
+
+def test_maxml_special_tostring(data: callable):
+    """Check serialization functionality works as expected with special characters"""
+
+    element = maxml.Element(name="my:test", namespace="http://namespace.example.org/my")
+
+    # Ensure that the element object's type is as expected
+    assert isinstance(element, maxml.Element)
+
+    sub = element.subelement("my:sub")
+
+    # Ensure that the subelement's type is as expected
+    assert isinstance(sub, maxml.Element)
+
+    # Ensure that the subelement's name prefix was parsed correctly
+    assert sub.prefix == "my"
+
+    # Ensure that the subelement's name was parsed correctly
+    assert sub.name == "sub"
+
+    # Ensure that the element's fullname was parsed correctly
+    assert sub.fullname == "my:sub"
+
+    # Ensure that the element's namespace prefix was registered correctly
+    assert sub.namespace.prefix == "my"
+
+    # Ensure that the element's namespace URI was registered correctly
+    assert sub.namespace.uri == "http://namespace.example.org/my"
+
+    # Ensure that the root has the expected depth
+    assert sub.depth == 1
+
+    sub.set("another", 'Test\'s all of the special characters "2 > 3 < 1" & more!')
+
+    values = [
+        "This & That",
+        "1 < 2",
+        "3 > 2",
+        "That's looking good!",
+        'Yes, I\'d agree, it is "looking good"!',
+        "This &gt; is already encoded &#129;!",
+    ]
+
+    sequence = sub.subelement("my:seq")
+
+    for index, value in enumerate(values, start=1):
+        item = sequence.subelement("my:li")
+        item.set("my:index", str(index))
+        item.text = value
+
+    string: str = element.tostring(pretty=True)
+
+    assert isinstance(string, str)
+
+    compare: str = data("examples/example03special-all.xml")
+
+    assert isinstance(compare, str)
+
+    assert string == compare
+
+    string: str = element.tostring(pretty=True, escape=maxml.Escape.Required)
+
+    assert isinstance(string, str)
+
+    compare: str = data("examples/example03special-required.xml")
+
+    assert isinstance(compare, str)
+
+    assert string == compare

maxml-1.0.1/source/maxml/__init__.py

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

maxml-1.0.1/source/maxml/version.txt

@@ -1 +0,0 @@
-1.0.1