exonware-xwsystem 0.0.1.411__py3-none-any.whl → 0.1.0.3__py3-none-any.whl

exonware/xwsystem/io/serialization/parsers/hybrid_parser.py

@@ -0,0 +1,62 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/serialization/parsers/hybrid_parser.py
+"""Hybrid parser: msgspec for reading, orjson for writing (direct, no try/catch)."""
+
+from typing import Any
+import msgspec  # Direct import for reading
+import orjson  # Direct import for writing
+
+from .base import AJsonParser
+
+
+class HybridParser(AJsonParser):
+    """
+    Hybrid parser - fastest combination:
+    - msgspec for reading (1.36x faster than orjson)
+    - orjson for writing (2.27x faster than msgspec)
+    
+    Direct imports (no try/catch) - assumes both are available.
+    """
+    
+    @property
+    def parser_name(self) -> str:
+        return "hybrid"
+    
+    @property
+    def tier(self) -> int:
+        return 1
+    
+    @property
+    def is_available(self) -> bool:
+        return True  # Assumes both msgspec and orjson are available
+    
+    def loads(self, s: str | bytes) -> Any:
+        """Parse JSON using msgspec.json.decode() - fastest for reading."""
+        if isinstance(s, str):
+            s = s.encode("utf-8")
+        # msgspec.json.decode accepts bytes directly
+        return msgspec.json.decode(s)
+    
+    def dumps(self, obj: Any, **kwargs) -> str | bytes:
+        """Serialize JSON using orjson.dumps() - fastest for writing."""
+        option = 0
+        
+        # orjson options
+        if not kwargs.get("ensure_ascii", True):
+            # orjson outputs UTF-8, so ensure_ascii=False is default
+            pass
+        
+        # Handle indent (orjson doesn't support indent directly)
+        indent = kwargs.get("indent", None)
+        if indent:
+            # For pretty printing, use orjson.OPT_INDENT_2
+            option |= orjson.OPT_INDENT_2
+        
+        # Sort keys
+        if kwargs.get("sort_keys", False):
+            option |= orjson.OPT_SORT_KEYS
+        
+        result = orjson.dumps(obj, option=option)
+        
+        # Return as bytes (orjson returns bytes)
+        # Caller can decode if string is needed
+        return result

exonware/xwsystem/io/serialization/parsers/msgspec_parser.py

@@ -0,0 +1,48 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/serialization/parsers/msgspec_parser.py
+"""msgspec parser - Tier 1 (Rust-based, very fast)."""
+
+from typing import Any
+import importlib.util
+
+_msgspec_spec = importlib.util.find_spec('msgspec')
+if _msgspec_spec is not None:
+    import msgspec
+    MSGSPEC_AVAILABLE = True
+else:
+    MSGSPEC_AVAILABLE = False
+    msgspec = None
+
+from .base import AJsonParser
+
+
+class MsgspecParser(AJsonParser):
+    """msgspec parser - Tier 1 (Rust-based, very fast, close to orjson)."""
+    
+    @property
+    def parser_name(self) -> str:
+        return "msgspec"
+    
+    @property
+    def tier(self) -> int:
+        return 1
+    
+    @property
+    def is_available(self) -> bool:
+        return MSGSPEC_AVAILABLE
+    
+    def loads(self, s: str | bytes) -> Any:
+        """Parse JSON using msgspec.json.decode()."""
+        if isinstance(s, str):
+            s = s.encode("utf-8")
+        # msgspec.json.decode accepts bytes directly
+        return msgspec.json.decode(s)
+    
+    def dumps(self, obj: Any, **kwargs) -> str | bytes:
+        """Serialize JSON using msgspec.json.encode()."""
+        result = msgspec.json.encode(obj)
+        
+        # msgspec returns bytes, decode if string needed
+        if isinstance(result, bytes) and kwargs.get("return_str", False):
+            return result.decode("utf-8")
+        
+        return result

exonware/xwsystem/io/serialization/parsers/orjson_direct_parser.py

@@ -0,0 +1,54 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/serialization/parsers/orjson_direct_parser.py
+"""orjson parser - DIRECT (no try/catch, assumes orjson is available)."""
+
+from typing import Any
+import orjson  # Direct import, no try/catch
+
+from .base import AJsonParser
+
+
+class OrjsonDirectParser(AJsonParser):
+    """orjson parser - DIRECT (no try/catch, assumes orjson is available)."""
+    
+    @property
+    def parser_name(self) -> str:
+        return "orjson_direct"
+    
+    @property
+    def tier(self) -> int:
+        return 1
+    
+    @property
+    def is_available(self) -> bool:
+        return True  # Assumes orjson is available
+    
+    def loads(self, s: str | bytes) -> Any:
+        """Parse JSON using orjson.loads()."""
+        if isinstance(s, str):
+            s = s.encode("utf-8")
+        return orjson.loads(s)
+    
+    def dumps(self, obj: Any, **kwargs) -> str | bytes:
+        """Serialize JSON using orjson.dumps()."""
+        option = 0
+        
+        # orjson options
+        if not kwargs.get("ensure_ascii", True):
+            # orjson outputs UTF-8, so ensure_ascii=False is default
+            pass
+        
+        # Handle indent (orjson doesn't support indent directly)
+        indent = kwargs.get("indent", None)
+        if indent:
+            # For pretty printing, use orjson.OPT_INDENT_2
+            option |= orjson.OPT_INDENT_2
+        
+        # Sort keys
+        if kwargs.get("sort_keys", False):
+            option |= orjson.OPT_SORT_KEYS
+        
+        result = orjson.dumps(obj, option=option)
+        
+        # Return as bytes (orjson returns bytes)
+        # Caller can decode if string is needed
+        return result

exonware/xwsystem/io/serialization/parsers/orjson_parser.py

@@ -0,0 +1,62 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/serialization/parsers/orjson_parser.py
+"""orjson parser - Tier 1 (3-4x faster than stdlib)."""
+
+from typing import Any
+import importlib.util
+
+_orjson_spec = importlib.util.find_spec('orjson')
+if _orjson_spec is not None:
+    import orjson
+    ORJSON_AVAILABLE = True
+else:
+    ORJSON_AVAILABLE = False
+    orjson = None
+
+from .base import AJsonParser
+
+
+class OrjsonParser(AJsonParser):
+    """orjson parser - Tier 1 (3-4x faster than stdlib)."""
+    
+    @property
+    def parser_name(self) -> str:
+        return "orjson"
+    
+    @property
+    def tier(self) -> int:
+        return 1
+    
+    @property
+    def is_available(self) -> bool:
+        return ORJSON_AVAILABLE
+    
+    def loads(self, s: str | bytes) -> Any:
+        """Parse JSON using orjson.loads()."""
+        if isinstance(s, str):
+            s = s.encode("utf-8")
+        return orjson.loads(s)
+    
+    def dumps(self, obj: Any, **kwargs) -> str | bytes:
+        """Serialize JSON using orjson.dumps()."""
+        option = 0
+        
+        # orjson options
+        if not kwargs.get("ensure_ascii", True):
+            # orjson outputs UTF-8, so ensure_ascii=False is default
+            pass
+        
+        # Handle indent (orjson doesn't support indent directly)
+        indent = kwargs.get("indent", None)
+        if indent:
+            # For pretty printing, use orjson.OPT_INDENT_2
+            option |= orjson.OPT_INDENT_2
+        
+        # Sort keys
+        if kwargs.get("sort_keys", False):
+            option |= orjson.OPT_SORT_KEYS
+        
+        result = orjson.dumps(obj, option=option)
+        
+        # Return as bytes (orjson returns bytes)
+        # Caller can decode if string is needed
+        return result

exonware/xwsystem/io/serialization/parsers/pysimdjson_parser.py

@@ -0,0 +1,55 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/serialization/parsers/pysimdjson_parser.py
+"""pysimdjson parser - Tier 1 (C++ simdjson, excellent for partial parsing)."""
+
+from typing import Any
+import importlib.util
+
+_simdjson_spec = importlib.util.find_spec('simdjson')
+if _simdjson_spec is not None:
+    import simdjson
+    PYSIMDJSON_AVAILABLE = True
+else:
+    PYSIMDJSON_AVAILABLE = False
+    simdjson = None
+
+from .base import AJsonParser
+
+
+class PysimdjsonParser(AJsonParser):
+    """pysimdjson parser - Tier 1 (C++ simdjson, excellent for partial parsing)."""
+    
+    @property
+    def parser_name(self) -> str:
+        return "pysimdjson"
+    
+    @property
+    def tier(self) -> int:
+        return 1
+    
+    @property
+    def is_available(self) -> bool:
+        return PYSIMDJSON_AVAILABLE
+    
+    def loads(self, s: str | bytes) -> Any:
+        """Parse JSON using simdjson.loads()."""
+        if isinstance(s, str):
+            s = s.encode("utf-8")
+        return simdjson.loads(s)
+    
+    def dumps(self, obj: Any, **kwargs) -> str | bytes:
+        """Serialize JSON using pysimdjson.dumps()."""
+        # pysimdjson doesn't have dumps, fallback to orjson or stdlib
+        # For now, use orjson if available, else stdlib
+        _orjson_spec = importlib.util.find_spec('orjson')
+        if _orjson_spec is not None:
+            import orjson
+            result = orjson.dumps(obj)
+            if isinstance(result, bytes) and kwargs.get("return_str", False):
+                return result.decode("utf-8")
+            return result
+        else:
+            import json
+            result = json.dumps(obj, **kwargs)
+            if isinstance(result, str) and kwargs.get("return_bytes", False):
+                return result.encode("utf-8")
+            return result

exonware/xwsystem/io/serialization/parsers/rapidjson_parser.py

@@ -0,0 +1,53 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/serialization/parsers/rapidjson_parser.py
+"""python-rapidjson parser - Tier 1 (C++ rapidjson)."""
+
+from typing import Any
+import importlib.util
+
+_rapidjson_spec = importlib.util.find_spec('rapidjson')
+if _rapidjson_spec is not None:
+    import rapidjson
+    RAPIDJSON_AVAILABLE = True
+else:
+    RAPIDJSON_AVAILABLE = False
+    rapidjson = None
+
+from .base import AJsonParser
+
+
+class RapidjsonParser(AJsonParser):
+    """python-rapidjson parser - Tier 1 (C++ rapidjson)."""
+    
+    @property
+    def parser_name(self) -> str:
+        return "rapidjson"
+    
+    @property
+    def tier(self) -> int:
+        return 1
+    
+    @property
+    def is_available(self) -> bool:
+        return RAPIDJSON_AVAILABLE
+    
+    def loads(self, s: str | bytes) -> Any:
+        """Parse JSON using rapidjson.loads()."""
+        if isinstance(s, bytes):
+            s = s.decode("utf-8")
+        return rapidjson.loads(s)
+    
+    def dumps(self, obj: Any, **kwargs) -> str | bytes:
+        """Serialize JSON using rapidjson.dumps()."""
+        # rapidjson supports most stdlib kwargs
+        result = rapidjson.dumps(
+            obj,
+            ensure_ascii=kwargs.get("ensure_ascii", True),
+            indent=kwargs.get("indent", None),
+            sort_keys=kwargs.get("sort_keys", False),
+        )
+        
+        # rapidjson returns str, encode if bytes needed
+        if isinstance(result, str) and kwargs.get("return_bytes", False):
+            return result.encode("utf-8")
+        
+        return result

exonware/xwsystem/io/serialization/parsers/registry.py

@@ -0,0 +1,91 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/serialization/parsers/registry.py
+"""Parser registry for JSON parser selection and auto-detection."""
+
+from typing import Optional, Type
+
+from .base import AJsonParser
+from .standard import StandardJsonParser
+
+# Import hybrid parser (direct, no try/catch - assumes msgspec and orjson available)
+from .hybrid_parser import HybridParser
+
+# Registry of available parsers
+_PARSERS: dict[str, Type[AJsonParser]] = {
+    "hybrid": HybridParser,  # Default: msgspec for reading, orjson for writing
+    "standard": StandardJsonParser,  # Fallback only
+}
+
+# Cache of parser instances
+_PARSER_INSTANCES: dict[str, AJsonParser] = {}
+
+
+def get_best_available_parser() -> AJsonParser:
+    """
+    Auto-detect and return the best available parser.
+    
+    Default: hybrid (msgspec for reading, orjson for writing)
+    - Fastest combination: msgspec reads 1.36x faster, orjson writes 2.27x faster
+    - Direct imports (no try/catch) - assumes both are available
+    
+    Fallback: standard (stdlib json)
+    
+    Returns:
+        Best available parser instance
+    """
+    # Try hybrid first (default)
+    parser_class = _PARSERS.get("hybrid")
+    if parser_class:
+        parser = parser_class()
+        if parser.is_available:
+            return parser
+    
+    # Fallback to standard (stdlib)
+    return StandardJsonParser()
+
+
+def get_parser(name: Optional[str] = None) -> AJsonParser:
+    """
+    Get parser by name or auto-detect best available.
+    
+    Args:
+        name: Parser name ("standard", "orjson", or None for auto-detect)
+    
+    Returns:
+        Parser instance (falls back to best available if requested parser unavailable)
+    """
+    if name is None:
+        return get_best_available_parser()
+    
+    # Check cache first
+    if name in _PARSER_INSTANCES:
+        parser = _PARSER_INSTANCES[name]
+        if parser.is_available:
+            return parser
+    
+    # Create new instance
+    parser_class = _PARSERS.get(name, StandardJsonParser)
+    parser = parser_class()
+    
+    # Cache if available
+    if parser.is_available:
+        _PARSER_INSTANCES[name] = parser
+    else:
+        # Fallback to available parser if requested parser unavailable
+        if name != "standard":
+            return get_best_available_parser()
+    
+    return parser
+
+
+def register_parser(name: str, parser_class: Type[AJsonParser]):
+    """
+    Register a new parser implementation.
+    
+    Args:
+        name: Parser identifier
+        parser_class: Parser class implementing AJsonParser
+    """
+    _PARSERS[name] = parser_class
+    # Clear cache to allow new parser to be used
+    if name in _PARSER_INSTANCES:
+        del _PARSER_INSTANCES[name]

exonware/xwsystem/io/serialization/parsers/standard.py

@@ -0,0 +1,44 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/serialization/parsers/standard.py
+"""Standard library JSON parser (baseline implementation)."""
+
+import json
+from typing import Any
+
+from .base import AJsonParser
+
+
+class StandardJsonParser(AJsonParser):
+    """Standard library JSON parser - Tier 0 (baseline)."""
+    
+    @property
+    def parser_name(self) -> str:
+        return "standard"
+    
+    @property
+    def tier(self) -> int:
+        return 0
+    
+    @property
+    def is_available(self) -> bool:
+        return True  # Available (stdlib)
+    
+    def loads(self, s: str | bytes) -> Any:
+        """Parse JSON using stdlib json.loads()."""
+        if isinstance(s, bytes):
+            s = s.decode("utf-8")
+        return json.loads(s)
+    
+    def dumps(self, obj: Any, **kwargs) -> str | bytes:
+        """Serialize JSON using stdlib json.dumps()."""
+        ensure_ascii = kwargs.get("ensure_ascii", False)
+        indent = kwargs.get("indent", None)
+        sort_keys = kwargs.get("sort_keys", False)
+        
+        return json.dumps(
+            obj,
+            ensure_ascii=ensure_ascii,
+            indent=indent,
+            sort_keys=sort_keys,
+            default=kwargs.get("default", None),
+            cls=kwargs.get("cls", None),
+        )

exonware/xwsystem/io/serialization/parsers/ujson_parser.py

@@ -0,0 +1,53 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/serialization/parsers/ujson_parser.py
+"""ujson parser - Tier 1 (C-based, fast)."""
+
+from typing import Any
+import importlib.util
+
+_ujson_spec = importlib.util.find_spec('ujson')
+if _ujson_spec is not None:
+    import ujson
+    UJSON_AVAILABLE = True
+else:
+    UJSON_AVAILABLE = False
+    ujson = None
+
+from .base import AJsonParser
+
+
+class UjsonParser(AJsonParser):
+    """ujson parser - Tier 1 (C-based, fast)."""
+    
+    @property
+    def parser_name(self) -> str:
+        return "ujson"
+    
+    @property
+    def tier(self) -> int:
+        return 1
+    
+    @property
+    def is_available(self) -> bool:
+        return UJSON_AVAILABLE
+    
+    def loads(self, s: str | bytes) -> Any:
+        """Parse JSON using ujson.loads()."""
+        if isinstance(s, bytes):
+            s = s.decode("utf-8")
+        return ujson.loads(s)
+    
+    def dumps(self, obj: Any, **kwargs) -> str | bytes:
+        """Serialize JSON using ujson.dumps()."""
+        # ujson supports most stdlib kwargs
+        result = ujson.dumps(
+            obj,
+            ensure_ascii=kwargs.get("ensure_ascii", True),
+            indent=kwargs.get("indent", None),
+            sort_keys=kwargs.get("sort_keys", False),
+        )
+        
+        # ujson returns str, encode if bytes needed
+        if isinstance(result, str) and kwargs.get("return_bytes", False):
+            return result.encode("utf-8")
+        
+        return result

exonware/xwsystem/io/serialization/registry.py

@@ -1,8 +1,9 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/serialization/registry.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.411
+Version: 0.1.0.3
 Generation Date: November 2, 2025
 
 Serialization Registry - Delegates to UniversalCodecRegistry.
@@ -10,7 +11,7 @@ Serialization Registry - Delegates to UniversalCodecRegistry.
 Provides serialization-specific convenience methods for format discovery.
 """
 
-from typing import Optional, Union
+from typing import Optional
 from pathlib import Path
 
 from ..codec.registry import UniversalCodecRegistry, get_registry
@@ -68,7 +69,7 @@ class SerializationRegistry:
         """
         return self._codec_registry.get_by_id(format_id)
     
-    def detect_from_file(self, file_path: Union[str, Path]) -> Optional[ISerialization]:
+    def detect_from_file(self, file_path: str | Path) -> Optional[ISerialization]:
         """
         Auto-detect serializer from file path.
         
@@ -184,4 +185,3 @@ def get_serialization_registry() -> SerializationRegistry:
     if _global_serialization_registry is None:
         _global_serialization_registry = SerializationRegistry()
     return _global_serialization_registry
-