exonware-xwsystem 0.0.1.408__py3-none-any.whl → 0.0.1.410__py3-none-any.whl

exonware/xwsystem/io/serialization/formats/text/xml.py

@@ -2,7 +2,7 @@
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.408
+Version: 0.0.1.410
 Generation Date: November 2, 2025
 
 XML serialization - Extensible Markup Language.
@@ -11,6 +11,12 @@ Following I→A pattern:
 - I: ISerialization (interface)
 - A: ASerialization (abstract base)
 - Concrete: XmlSerializer
+
+Improved implementation:
+- Uses xmltodict for both encoding and decoding (better round-trip compatibility)
+- Requires xmltodict >= 0.13.0 for security features
+- Preserves types using XML attributes
+- Minimal try/catch blocks with proper error handling
 """
 
 from typing import Any, Optional, Union
@@ -21,20 +27,18 @@ from ....contracts import EncodeOptions, DecodeOptions
 from ....defs import CodecCapability
 from ....errors import SerializationError
 
-# Use defusedxml for security
-# Try defusedxml first (more secure), fallback to standard library if not available
-# The lazy hook will handle defusedxml installation if missing
+# Primary: xmltodict for both encoding and decoding (better round-trip)
+# xmltodict has built-in security features (disable_entities=True by default)
+# No need for defusedxml - xmltodict handles XML security internally
+import xmltodict
+
+# Optional: dicttoxml as fallback (not recommended for round-trip)
 try:
-    import defusedxml.ElementTree as ET
-    from defusedxml import defuse_stdlib
-    defuse_stdlib()
+    import dicttoxml
+    DICTTOXML_AVAILABLE = True
 except ImportError:
-    # Fallback to standard library (always available)
-    import xml.etree.ElementTree as ET
-
-# Lazy import for dicttoxml and xmltodict - the lazy hook will automatically handle ImportError
-import dicttoxml
-import xmltodict
+    DICTTOXML_AVAILABLE = False
+    dicttoxml = None
 
 
 class XmlSerializer(ASerialization):
@@ -45,7 +49,8 @@ class XmlSerializer(ASerialization):
     A: ASerialization (abstract base)
     Concrete: XmlSerializer
     
-    Uses defusedxml, dicttoxml, and xmltodict for secure XML handling.
+    Uses xmltodict for both encoding and decoding to ensure perfect round-trip compatibility.
+    Requires xmltodict >= 0.13.0 for security features.
     
     Examples:
         >>> serializer = XmlSerializer()
@@ -53,8 +58,9 @@ class XmlSerializer(ASerialization):
         >>> # Encode data
         >>> xml_str = serializer.encode({"user": {"name": "John", "age": 30}})
         >>> 
-        >>> # Decode data
-        >>> data = serializer.decode("<user><name>John</name></user>")
+        >>> # Decode data (perfect round-trip)
+        >>> data = serializer.decode(xml_str)
+        >>> assert data == {"user": {"name": "John", "age": 30}}
         >>> 
         >>> # Save to file
         >>> serializer.save_file({"config": {"debug": True}}, "config.xml")
@@ -66,10 +72,25 @@ class XmlSerializer(ASerialization):
     def __init__(self):
         """Initialize XML serializer."""
         super().__init__()
-        if dicttoxml is None or xmltodict is None:
+        if xmltodict is None:
+            raise ImportError(
+                "xmltodict >= 0.13.0 is required for XML serialization. "
+                "Install with: pip install xmltodict>=0.13.0"
+            )
+        
+        # Verify security features are available
+        # Root cause fixed: Check for security features at initialization.
+        # Priority #1: Security - Use available security features, recommend upgrade for full security.
+        import inspect
+        parse_sig = inspect.signature(xmltodict.parse)
+        self._has_disable_entities = 'disable_entities' in parse_sig.parameters
+        self._has_forbid_dtd = 'forbid_dtd' in parse_sig.parameters
+        self._has_forbid_entities = 'forbid_entities' in parse_sig.parameters
+        
+        if not self._has_disable_entities:
             raise ImportError(
-                "dicttoxml and xmltodict are required for XML serialization. "
-                "Install with: pip install dicttoxml xmltodict defusedxml"
+                "xmltodict with disable_entities support is required for XML serialization. "
+                "Install with: pip install 'xmltodict>=0.12.0'"
             )
     
     # ========================================================================
@@ -118,18 +139,212 @@ class XmlSerializer(ASerialization):
         return ["serialization", "markup"]
     
     # ========================================================================
-    # CORE ENCODE/DECODE (Using dicttoxml + xmltodict)
+    # XML SANITIZATION HELPERS
+    # ========================================================================
+    
+    def _sanitize_xml_name(self, name: str) -> str:
+        """
+        Sanitize a string to be a valid XML element/attribute name.
+        
+        XML 1.0 element name rules:
+        - Must start with letter, underscore, or colon (colon for namespaces)
+        - Can contain letters, digits, hyphens, underscores, periods, colons
+        - Cannot start with "xml" (case-insensitive)
+        - Cannot contain spaces or other special characters
+        
+        Root cause fixed: Dictionary keys used as XML element names must be valid XML names.
+        Solution: Prefix invalid names with underscore, replace invalid chars with underscore.
+        Priority #2: Usability - Ensure all data can be serialized to XML.
+        
+        Args:
+            name: String to sanitize as XML name
+            
+        Returns:
+            Valid XML element/attribute name
+        """
+        import re
+        
+        # Convert to string if not already
+        name_str = str(name)
+        
+        # Replace invalid characters with underscore
+        # Valid chars: letters, digits, hyphens, underscores, periods, colons
+        sanitized = re.sub(r'[^a-zA-Z0-9_\-.:]', '_', name_str)
+        
+        # If starts with digit, hyphen, period, or colon, prefix with underscore
+        if sanitized and sanitized[0] in '0123456789-.:':
+            sanitized = '_' + sanitized
+        
+        # If starts with "xml" (case-insensitive), prefix with underscore
+        if sanitized.lower().startswith('xml'):
+            sanitized = '_' + sanitized
+        
+        # If empty after sanitization, use default name
+        if not sanitized:
+            sanitized = '_item'
+        
+        return sanitized
+    
+    def _sanitize_for_xml(self, data: Any, preserve_keys: bool = True) -> Any:
+        """
+        Sanitize data for XML encoding by removing/replacing invalid XML characters.
+        
+        XML 1.0 doesn't allow certain control characters (0x00-0x1F except 0x09, 0x0A, 0x0D).
+        Also sanitizes dictionary keys to be valid XML element names.
+        
+        Root cause fixed: Dictionary keys must be valid XML element names (can't start with digits).
+        Solution: Sanitize keys and store original keys as XML attributes for round-trip preservation.
+        Priority #2: Usability - Ensure all data structures can be serialized to XML with key preservation.
+        
+        Args:
+            data: Python data structure
+            preserve_keys: If True, store original keys as @_original_key attributes
+            
+        Returns:
+            Sanitized data structure safe for XML encoding
+        """
+        if isinstance(data, dict):
+            # Root cause fixed: Dictionary keys must be valid XML element names.
+            # Keys that start with digits (like UUIDs) are invalid XML element names.
+            # Solution: Sanitize keys and preserve originals as attributes for round-trip.
+            sanitized_dict = {}
+            for key, value in data.items():
+                # Sanitize key to be valid XML element name
+                sanitized_key = self._sanitize_xml_name(key)
+                # Handle key collisions (if sanitization produces duplicate keys)
+                original_key = sanitized_key
+                counter = 1
+                while sanitized_key in sanitized_dict:
+                    sanitized_key = f"{original_key}_{counter}"
+                    counter += 1
+                
+                # Sanitize value recursively
+                sanitized_value = self._sanitize_for_xml(value, preserve_keys=preserve_keys)
+                
+                # If key was changed and we want to preserve it, store original as attribute
+                if preserve_keys and sanitized_key != str(key):
+                    # Wrap value in dict with original key as attribute
+                    # xmltodict uses @ prefix for attributes
+                    if isinstance(sanitized_value, dict):
+                        # Add original key as attribute to existing dict
+                        sanitized_value['@_original_key'] = str(key)
+                        sanitized_dict[sanitized_key] = sanitized_value
+                    else:
+                        # Wrap non-dict value to add attribute
+                        sanitized_dict[sanitized_key] = {
+                            '@_original_key': str(key),
+                            '#text': sanitized_value
+                        }
+                else:
+                    sanitized_dict[sanitized_key] = sanitized_value
+            return sanitized_dict
+        elif isinstance(data, list):
+            return [self._sanitize_for_xml(item, preserve_keys=preserve_keys) for item in data]
+        elif isinstance(data, str):
+            # Remove invalid XML 1.0 control characters (except tab, newline, carriage return)
+            # XML 1.0 allows: #x9 (tab), #xA (newline), #xD (carriage return)
+            # All other control chars (0x00-0x1F) are invalid
+            import re
+            # Remove control characters except tab, newline, carriage return
+            sanitized = re.sub(r'[\x00-\x08\x0B\x0C\x0E-\x1F]', '', data)
+            return sanitized
+        elif isinstance(data, (int, float, bool, type(None))):
+            return data
+        else:
+            # Convert other types to string and sanitize
+            return self._sanitize_for_xml(str(data))
+    
+    # ========================================================================
+    # TYPE PRESERVATION HELPERS
+    # ========================================================================
+    
+    def _preserve_types(self, data: Any) -> Any:
+        """
+        Preserve Python types in XML structure using type hints.
+        
+        Adds '@type' attributes to preserve type information for round-trip.
+        This allows us to restore int, float, bool, None from string representations.
+        
+        Args:
+            data: Python data structure
+            
+        Returns:
+            Data structure with type hints embedded
+        """
+        if isinstance(data, dict):
+            result = {}
+            for key, value in data.items():
+                if isinstance(value, (int, float, bool, type(None))):
+                    # Store type information
+                    result[key] = {
+                        '@type': type(value).__name__,
+                        '#text': str(value) if value is not None else ''
+                    }
+                elif isinstance(value, dict):
+                    result[key] = self._preserve_types(value)
+                elif isinstance(value, list):
+                    result[key] = [self._preserve_types(item) for item in value]
+                else:
+                    result[key] = value
+            return result
+        elif isinstance(data, list):
+            return [self._preserve_types(item) for item in data]
+        else:
+            return data
+    
+    def _restore_types(self, data: Any) -> Any:
+        """
+        Restore Python types from XML structure with type hints.
+        
+        Converts '@type' attributes back to proper Python types.
+        
+        Args:
+            data: XML data structure with type hints
+            
+        Returns:
+            Data structure with restored types
+        """
+        if isinstance(data, dict):
+            # Check if this is a type-hinted value
+            if '@type' in data and '#text' in data and len(data) == 2:
+                type_name = data['@type']
+                text_value = data['#text']
+                
+                if type_name == 'int':
+                    return int(text_value) if text_value else 0
+                elif type_name == 'float':
+                    return float(text_value) if text_value else 0.0
+                elif type_name == 'bool':
+                    return text_value.lower() in ('true', '1', 'yes')
+                elif type_name == 'NoneType':
+                    return None
+                else:
+                    return text_value
+            
+            # Recursively process dict
+            result = {}
+            for key, value in data.items():
+                if key not in ('@type', '#text'):
+                    result[key] = self._restore_types(value)
+            return result
+        elif isinstance(data, list):
+            return [self._restore_types(item) for item in data]
+        else:
+            return data
+    
+    # ========================================================================
+    # CORE ENCODE/DECODE (Using xmltodict for both - perfect round-trip)
     # ========================================================================
     
     def encode(self, value: Any, *, options: Optional[EncodeOptions] = None) -> Union[bytes, str]:
         """
         Encode data to XML string.
         
-        Uses dicttoxml.dicttoxml().
+        Uses xmltodict.unparse() for encoding (better round-trip compatibility than dicttoxml).
         
         Args:
             value: Data to serialize
-            options: XML options (root, attr_type, etc.)
+            options: XML options (root, pretty, preserve_types, etc.)
         
         Returns:
             XML string
@@ -137,44 +352,70 @@ class XmlSerializer(ASerialization):
         Raises:
             SerializationError: If encoding fails
         """
+        opts = options or {}
+        
+        # Determine root element name
+        root_name = opts.get('root', 'root')
+        
+        # Root cause fixed: Sanitize data to remove invalid XML characters.
+        # Priority #1: Security - Prevent XML injection and malformed XML.
+        # Priority #2: Usability - Ensure data can be encoded without errors.
+        value = self._sanitize_for_xml(value)
+        
+        # Root cause fixed: Type preservation disabled by default - XML is text-based.
+        # Priority #2: Usability - Focus on structure preservation first, types are secondary.
+        # Note: Numbers will be strings in XML (this is expected XML behavior).
+        preserve_types = opts.get('preserve_types', False)
+        if preserve_types:
+            value = self._preserve_types(value)
+        
+        # Wrap in root element if needed (xmltodict requires single root)
+        # Root cause fixed: Always wrap in root element for xmltodict compatibility.
+        if not isinstance(value, dict):
+            # Non-dict value - wrap it
+            wrapped_value = {root_name: value}
+        elif len(value) != 1:
+            # Multiple keys - wrap in root
+            wrapped_value = {root_name: value}
+        else:
+            # Single key dict - check if we should use it as root or wrap it
+            single_key = list(value.keys())[0]
+            if single_key == root_name:
+                # Already has correct root name
+                wrapped_value = value
+            else:
+                # Different root name - wrap it
+                wrapped_value = {root_name: value}
+        
+        # Encode to XML string using xmltodict.unparse()
+        # Root cause fixed: Use xmltodict for both encode and decode for perfect round-trip.
+        # Priority #2: Usability - Round-trip serialization should preserve data structure.
         try:
-            opts = options or {}
-            
-            # Encode to XML bytes
-            xml_bytes = dicttoxml.dicttoxml(
-                value,
-                custom_root=opts.get('root', 'root'),
-                attr_type=opts.get('attr_type', False),
-                item_func=opts.get('item_func', lambda x: 'item')
+            xml_str = xmltodict.unparse(
+                wrapped_value,
+                pretty=opts.get('pretty', False),
+                indent=opts.get('indent', '  '),
+                full_document=opts.get('full_document', True)
             )
-            
-            # Convert to string
-            xml_str = xml_bytes.decode('utf-8')
-            
-            # Pretty print if requested
-            if opts.get('pretty', False):
-                import xml.dom.minidom
-                dom = xml.dom.minidom.parseString(xml_bytes)
-                xml_str = dom.toprettyxml(indent=opts.get('indent', '  '))
-            
-            return xml_str
-            
-        except Exception as e:
+        except (ValueError, TypeError) as e:
             raise SerializationError(
-                f"Failed to encode XML: {e}",
+                f"Failed to encode XML: {e}. "
+                f"Data may contain invalid XML characters or unsupported types.",
                 format_name=self.format_name,
                 original_error=e
-            )
+            ) from e
+        
+        return xml_str
     
     def decode(self, repr: Union[bytes, str], *, options: Optional[DecodeOptions] = None) -> Any:
         """
         Decode XML string to data.
         
-        Uses xmltodict.parse().
+        Uses xmltodict.parse() with security features enabled.
         
         Args:
             repr: XML string (bytes or str)
-            options: XML options (process_namespaces, etc.)
+            options: XML options (process_namespaces, root, preserve_types, etc.)
         
         Returns:
             Decoded Python dict
@@ -182,29 +423,163 @@ class XmlSerializer(ASerialization):
         Raises:
             SerializationError: If decoding fails
         """
+        # Convert bytes to str if needed
+        if isinstance(repr, bytes):
+            repr = repr.decode('utf-8')
+        
+        opts = options or {}
+        root_name = opts.get('root', 'root')
+        preserve_types = opts.get('preserve_types', False)
+        
+        # Decode from XML string with security features enabled
+        # Root cause fixed: Use available security features based on xmltodict version.
+        # Priority #1: Security - Use all available security features.
+        parse_kwargs = {
+            'process_namespaces': opts.get('process_namespaces', False),
+            'namespace_separator': opts.get('namespace_separator', ':'),
+            'disable_entities': True,  # Security: disable external entities (available in >=0.12.0)
+        }
+        
+        # Add additional security features if available (>=0.13.0)
+        if self._has_forbid_dtd:
+            parse_kwargs['forbid_dtd'] = True  # Security: forbid DTD
+        if self._has_forbid_entities:
+            parse_kwargs['forbid_entities'] = True  # Security: forbid entities
+        
         try:
-            # Convert bytes to str if needed
-            if isinstance(repr, bytes):
-                repr = repr.decode('utf-8')
-            
-            opts = options or {}
+            data = xmltodict.parse(repr, **parse_kwargs)
+        except Exception as e:
+            # Provide better error context for XML parsing failures
+            error_msg = str(e)
+            if "not well-formed" in error_msg or "ExpatError" in str(type(e).__name__):
+                # Try to find the problematic character position
+                raise SerializationError(
+                    f"Failed to decode XML: {error_msg}. "
+                    f"The XML may contain invalid characters or be malformed.",
+                    format_name=self.format_name,
+                    original_error=e
+                ) from e
+            else:
+                raise SerializationError(
+                    f"Failed to decode XML: {error_msg}",
+                    format_name=self.format_name,
+                    original_error=e
+                ) from e
+        
+        # Unwrap root element if it matches expected root name
+        # Root cause fixed: Proper root element handling - check if root matches expected name.
+        # Priority #2: Usability - Round-trip serialization should preserve data structure.
+        if isinstance(data, dict) and len(data) == 1:
+            # Check if the single key matches root_name or if it's a generic 'root'
+            keys = list(data.keys())
+            if keys[0] == root_name or (root_name == 'root' and keys[0] == 'root'):
+                data = data[keys[0]]
+            # If root doesn't match, keep wrapped (might be intentional)
+        
+        # Restore original keys if they were preserved
+        # Root cause fixed: Dictionary keys were sanitized during encoding.
+        # Solution: Restore original keys from @_original_key attributes.
+        # Priority #2: Usability - Round-trip serialization must preserve key names.
+        data = self._restore_original_keys(data)
+        
+        # Restore types if they were preserved
+        if preserve_types:
+            data = self._restore_types(data)
+        
+        return data
+    
+    def _infer_type(self, value: str) -> Any:
+        """
+        Infer Python type from XML string value.
+        
+        Root cause fixed: XML is text-based and converts all values to strings.
+        Solution: Attempt to infer and restore original types (int, float, bool, None).
+        Priority #2: Usability - Round-trip serialization should preserve types when possible.
+        
+        Args:
+            value: String value from XML
             
-            # Decode from XML string
-            data = xmltodict.parse(
-                repr,
-                process_namespaces=opts.get('process_namespaces', False),
-                namespace_separator=opts.get('namespace_separator', ':'),
-                disable_entities=True,  # Security: disable external entities
-                forbid_dtd=True,  # Security: forbid DTD
-                forbid_entities=True  # Security: forbid entities
-            )
+        Returns:
+            Value with inferred type (int, float, bool, None, or original string)
+        """
+        if not isinstance(value, str):
+            return value
+        
+        value = value.strip()
+        
+        # Check for None/empty
+        if not value or value.lower() in ('none', 'null', ''):
+            return None
+        
+        # Check for boolean
+        if value.lower() in ('true', 'false'):
+            return value.lower() == 'true'
+        
+        # Check for integer
+        try:
+            # Try int first (more common)
+            if value.isdigit() or (value.startswith('-') and value[1:].isdigit()):
+                return int(value)
+        except (ValueError, OverflowError):
+            pass
+        
+        # Check for float
+        try:
+            return float(value)
+        except (ValueError, OverflowError):
+            pass
+        
+        # Return original string if no type matches
+        return value
+    
+    def _restore_original_keys(self, data: Any) -> Any:
+        """
+        Restore original dictionary keys from @_original_key attributes.
+        
+        Root cause fixed: Keys were sanitized during encoding (e.g., UUIDs starting with digits).
+        Solution: Check for @_original_key attributes and restore original key names.
+        Priority #2: Usability - Round-trip serialization must preserve key names.
+        
+        Args:
+            data: Decoded XML data structure
             
+        Returns:
+            Data structure with original keys restored and types inferred
+        """
+        if isinstance(data, dict):
+            result = {}
+            for key, value in data.items():
+                # Skip xmltodict internal attributes
+                if key.startswith('@') and key != '@_original_key':
+                    continue
+                
+                # Check if this value has an original key attribute
+                if isinstance(value, dict) and '@_original_key' in value:
+                    original_key = value['@_original_key']
+                    # Remove the attribute from value
+                    clean_value = {k: v for k, v in value.items() if k != '@_original_key'}
+                    
+                    # If clean_value has only #text, unwrap it
+                    if len(clean_value) == 1 and '#text' in clean_value:
+                        clean_value = clean_value['#text']
+                        # Infer type for unwrapped text value
+                        clean_value = self._infer_type(clean_value)
+                    
+                    # Recursively restore keys in the value
+                    clean_value = self._restore_original_keys(clean_value)
+                    result[original_key] = clean_value
+                else:
+                    # Recursively restore keys in the value
+                    restored_value = self._restore_original_keys(value)
+                    # Infer type for leaf string values
+                    if isinstance(restored_value, str):
+                        restored_value = self._infer_type(restored_value)
+                    result[key] = restored_value
+            return result
+        elif isinstance(data, list):
+            return [self._restore_original_keys(item) for item in data]
+        else:
+            # Infer type for leaf string values
+            if isinstance(data, str):
+                return self._infer_type(data)
             return data
-            
-        except (Exception, UnicodeDecodeError) as e:
-            raise SerializationError(
-                f"Failed to decode XML: {e}",
-                format_name=self.format_name,
-                original_error=e
-            )
-

exonware/xwsystem/io/serialization/formats/text/yaml.py

@@ -2,7 +2,7 @@
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.408
+Version: 0.0.1.410
 Generation Date: November 2, 2025
 
 YAML serialization - Human-readable data serialization format.

exonware/xwsystem/io/serialization/registry.py

@@ -2,7 +2,7 @@
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.408
+Version: 0.0.1.410
 Generation Date: November 2, 2025
 
 Serialization Registry - Delegates to UniversalCodecRegistry.
@@ -10,7 +10,7 @@ Serialization Registry - Delegates to UniversalCodecRegistry.
 Provides serialization-specific convenience methods for format discovery.
 """
 
-from typing import Optional, List, Union
+from typing import Optional, Union
 from pathlib import Path
 
 from ..codec.registry import UniversalCodecRegistry, get_registry
@@ -117,7 +117,7 @@ class SerializationRegistry:
         """
         return self._codec_registry.get_by_mime_type(mime_type)
     
-    def list_formats(self) -> List[str]:
+    def list_formats(self) -> list[str]:
         """
         List all registered format IDs.
         
@@ -130,7 +130,7 @@ class SerializationRegistry:
         """
         return self._codec_registry.list_codecs()
     
-    def list_extensions(self) -> List[str]:
+    def list_extensions(self) -> list[str]:
         """
         List all registered file extensions.
         
@@ -143,7 +143,7 @@ class SerializationRegistry:
         """
         return self._codec_registry.list_extensions()
     
-    def list_mime_types(self) -> List[str]:
+    def list_mime_types(self) -> list[str]:
         """
         List all registered MIME types.