exonware-xwsystem 0.1.0.1__py3-none-any.whl → 0.1.0.4__py3-none-any.whl

exonware/xwsystem/io/serialization/contracts.py

@@ -1,8 +1,9 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/serialization/contracts.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.4
 Generation Date: November 2, 2025
 
 Serialization contracts - ISerialization interface extending ICodec.
@@ -13,8 +14,7 @@ Following I→A→XW pattern:
 - XW: XW{Format}Serializer (concrete implementations)
 """
 
-from abc import ABC, abstractmethod
-from typing import Any, Union, Optional, BinaryIO, TextIO, AsyncIterator, Iterator
+from typing import Any, Optional, BinaryIO, TextIO, AsyncIterator, Iterator, Protocol, runtime_checkable
 # Root cause: Migrating to Python 3.12 built-in generic syntax for consistency
 # Priority #3: Maintainability - Modern type annotations improve code clarity
 from pathlib import Path
@@ -24,15 +24,16 @@ from ..contracts import EncodeOptions, DecodeOptions
 from ..defs import CodecCapability
 
 
-class ISerialization(ICodec[Any, Union[bytes, str]]):
+@runtime_checkable
+class ISerialization(ICodec[Any, bytes | str], Protocol):
     """
     Serialization interface extending ICodec.
     
     Provides serialization-specific functionality on top of the universal codec interface.
     
-    Type: ICodec[Any, Union[bytes, str]]
+    Type: ICodec[Any, bytes | str]
     - T (model type): Any (supports any Python object)
-    - R (representation): Union[bytes, str] (can be text or binary)
+    - R (representation): bytes | str (can be text or binary)
     
     This interface extends ICodec with:
     - File I/O methods (save_file, load_file)
@@ -49,63 +50,55 @@ class ISerialization(ICodec[Any, Union[bytes, str]]):
     # ========================================================================
     
     @property
-    @abstractmethod
     def format_name(self) -> str:
         """Get the serialization format name (e.g., 'JSON', 'YAML')."""
-        pass
+        ...
     
     @property
-    @abstractmethod
     def file_extensions(self) -> list[str]:
         """Get supported file extensions for this format."""
-        pass
+        ...
     
     @property
-    @abstractmethod
     def mime_type(self) -> str:
         """Get the MIME type for this serialization format."""
-        pass
+        ...
     
     @property
-    @abstractmethod
     def is_binary_format(self) -> bool:
         """Whether this is a binary or text-based format."""
-        pass
+        ...
     
     @property
-    @abstractmethod
     def supports_streaming(self) -> bool:
         """Whether this format supports streaming serialization."""
-        pass
+        ...
     
     # ========================================================================
     # CORE CODEC METHODS (from ICodec)
     # ========================================================================
     
-    @abstractmethod
-    def encode(self, value: Any, *, options: Optional[EncodeOptions] = None) -> Union[bytes, str]:
+    def encode(self, value: Any, *, options: Optional[EncodeOptions] = None) -> bytes | str:
         """
         Encode data to representation (bytes or str).
         
         Core codec method - all serializers must implement.
         """
-        pass
+        ...
     
-    @abstractmethod
-    def decode(self, repr: Union[bytes, str], *, options: Optional[DecodeOptions] = None) -> Any:
+    def decode(self, repr: bytes | str, *, options: Optional[DecodeOptions] = None) -> Any:
         """
         Decode representation (bytes or str) to data.
         
         Core codec method - all serializers must implement.
         """
-        pass
+        ...
     
     # ========================================================================
     # FILE I/O METHODS (Serialization-specific)
     # ========================================================================
     
-    @abstractmethod
-    def save_file(self, data: Any, file_path: Union[str, Path], **options) -> None:
+    def save_file(self, data: Any, file_path: str | Path, **options) -> None:
         """
         Save data to file with atomic operations.
         
@@ -117,10 +110,9 @@ class ISerialization(ICodec[Any, Union[bytes, str]]):
         Raises:
             SerializationError: If save fails
         """
-        pass
+        ...
     
-    @abstractmethod
-    def load_file(self, file_path: Union[str, Path], **options) -> Any:
+    def load_file(self, file_path: str | Path, **options) -> Any:
         """
         Load data from file.
         
@@ -134,13 +126,12 @@ class ISerialization(ICodec[Any, Union[bytes, str]]):
         Raises:
             SerializationError: If load fails
         """
-        pass
+        ...
     
     # ========================================================================
     # VALIDATION METHODS
     # ========================================================================
     
-    @abstractmethod
     def validate_data(self, data: Any) -> bool:
         """
         Validate data for serialization compatibility.
@@ -154,14 +145,13 @@ class ISerialization(ICodec[Any, Union[bytes, str]]):
         Raises:
             SerializationError: If validation fails
         """
-        pass
+        ...
     
     # ========================================================================
     # STREAMING METHODS
     # ========================================================================
     
-    @abstractmethod
-    def iter_serialize(self, data: Any, chunk_size: int = 8192) -> Iterator[Union[str, bytes]]:
+    def iter_serialize(self, data: Any, chunk_size: int = 8192) -> Iterator[str | bytes]:
         """
         Stream serialize data in chunks.
         
@@ -172,10 +162,9 @@ class ISerialization(ICodec[Any, Union[bytes, str]]):
         Yields:
             Serialized chunks
         """
-        pass
+        ...
     
-    @abstractmethod
-    def iter_deserialize(self, src: Union[TextIO, BinaryIO, Iterator[Union[str, bytes]]]) -> Any:
+    def iter_deserialize(self, src: TextIO | BinaryIO | Iterator[str | bytes]) -> Any:
         """
         Stream deserialize data from chunks.
         
@@ -185,14 +174,13 @@ class ISerialization(ICodec[Any, Union[bytes, str]]):
         Returns:
             Deserialized data
         """
-        pass
+        ...
     
     # ========================================================================
     # ASYNC METHODS
     # ========================================================================
     
-    @abstractmethod
-    async def save_file_async(self, data: Any, file_path: Union[str, Path], **options) -> None:
+    async def save_file_async(self, data: Any, file_path: str | Path, **options) -> None:
         """
         Async save data to file.
         
@@ -201,10 +189,9 @@ class ISerialization(ICodec[Any, Union[bytes, str]]):
             file_path: Path to save file
             **options: Format-specific options
         """
-        pass
+        ...
     
-    @abstractmethod
-    async def load_file_async(self, file_path: Union[str, Path], **options) -> Any:
+    async def load_file_async(self, file_path: str | Path, **options) -> Any:
         """
         Async load data from file.
         
@@ -215,10 +202,9 @@ class ISerialization(ICodec[Any, Union[bytes, str]]):
         Returns:
             Deserialized data
         """
-        pass
+        ...
     
-    @abstractmethod
-    async def stream_serialize(self, data: Any, chunk_size: int = 8192) -> AsyncIterator[Union[str, bytes]]:
+    async def stream_serialize(self, data: Any, chunk_size: int = 8192) -> AsyncIterator[str | bytes]:
         """
         Async stream serialize data in chunks.
         
@@ -229,10 +215,9 @@ class ISerialization(ICodec[Any, Union[bytes, str]]):
         Yields:
             Serialized chunks
         """
-        pass
+        ...
     
-    @abstractmethod
-    async def stream_deserialize(self, data_stream: AsyncIterator[Union[str, bytes]]) -> Any:
+    async def stream_deserialize(self, data_stream: AsyncIterator[str | bytes]) -> Any:
         """
         Async stream deserialize data from chunks.
         
@@ -242,16 +227,15 @@ class ISerialization(ICodec[Any, Union[bytes, str]]):
         Returns:
             Deserialized data
         """
-        pass
+        ...
     
     # ========================================================================
     # ADVANCED FEATURES (Optional - format-specific implementations)
     # ========================================================================
     
-    @abstractmethod
     def atomic_update_path(
         self, 
-        file_path: Union[str, Path], 
+        file_path: str | Path, 
         path: str, 
         value: Any, 
         **options
@@ -277,12 +261,11 @@ class ISerialization(ICodec[Any, Union[bytes, str]]):
         Example:
             >>> serializer.atomic_update_path("config.json", "/database/host", "localhost")
         """
-        pass
+        ...
     
-    @abstractmethod
     def atomic_read_path(
         self, 
-        file_path: Union[str, Path], 
+        file_path: str | Path, 
         path: str, 
         **options
     ) -> Any:
@@ -310,9 +293,8 @@ class ISerialization(ICodec[Any, Union[bytes, str]]):
         Example:
             >>> host = serializer.atomic_read_path("config.json", "/database/host")
         """
-        pass
+        ...
     
-    @abstractmethod
     def validate_with_schema(
         self, 
         data: Any, 
@@ -334,13 +316,12 @@ class ISerialization(ICodec[Any, Union[bytes, str]]):
             NotImplementedError: If this format doesn't support schema validation
             SerializationError: If validation fails
         """
-        pass
+        ...
     
-    @abstractmethod
     def incremental_save(
         self, 
         items: Iterator[Any], 
-        file_path: Union[str, Path], 
+        file_path: str | Path, 
         **options
     ) -> None:
         """
@@ -358,12 +339,11 @@ class ISerialization(ICodec[Any, Union[bytes, str]]):
             NotImplementedError: If this format doesn't support incremental streaming
             SerializationError: If save operation fails
         """
-        pass
+        ...
     
-    @abstractmethod
     def incremental_load(
         self, 
-        file_path: Union[str, Path], 
+        file_path: str | Path, 
         **options
     ) -> Iterator[Any]:
         """
@@ -383,12 +363,11 @@ class ISerialization(ICodec[Any, Union[bytes, str]]):
             NotImplementedError: If this format doesn't support incremental streaming
             SerializationError: If load operation fails
         """
-        pass
+        ...
     
-    @abstractmethod
     def query(
         self, 
-        file_path: Union[str, Path], 
+        file_path: str | Path, 
         query_expr: str, 
         **options
     ) -> Any:
@@ -410,12 +389,11 @@ class ISerialization(ICodec[Any, Union[bytes, str]]):
             SerializationError: If query operation fails
             ValueError: If query expression is invalid
         """
-        pass
+        ...
     
-    @abstractmethod
     def merge(
         self, 
-        file_path: Union[str, Path], 
+        file_path: str | Path, 
         updates: dict[str, Any], 
         **options
     ) -> None:
@@ -433,7 +411,7 @@ class ISerialization(ICodec[Any, Union[bytes, str]]):
             NotImplementedError: If this format doesn't support merge operations
             SerializationError: If merge operation fails
         """
-        pass
+        ...
 
     # ========================================================================
     # RECORD-LEVEL OPERATIONS (Optional, generic defaults in ASerialization)
@@ -441,7 +419,7 @@ class ISerialization(ICodec[Any, Union[bytes, str]]):
 
     def stream_read_record(
         self,
-        file_path: Union[str, Path],
+        file_path: str | Path,
         match: callable,
         projection: Optional[list[Any]] = None,
         **options: Any,
@@ -463,7 +441,7 @@ class ISerialization(ICodec[Any, Union[bytes, str]]):
 
     def stream_update_record(
         self,
-        file_path: Union[str, Path],
+        file_path: str | Path,
         match: callable,
         updater: callable,
         *,
@@ -486,7 +464,7 @@ class ISerialization(ICodec[Any, Union[bytes, str]]):
 
     def get_record_page(
         self,
-        file_path: Union[str, Path],
+        file_path: str | Path,
         page_number: int,
         page_size: int,
         **options: Any,
@@ -507,7 +485,7 @@ class ISerialization(ICodec[Any, Union[bytes, str]]):
 
     def get_record_by_id(
         self,
-        file_path: Union[str, Path],
+        file_path: str | Path,
         id_value: Any,
         *,
         id_field: str = "id",
@@ -521,4 +499,3 @@ class ISerialization(ICodec[Any, Union[bytes, str]]):
         linear scan over a top-level list.
         """
         raise NotImplementedError
-

exonware/xwsystem/io/serialization/defs.py

@@ -1,10 +1,11 @@
 #!/usr/bin/env python3
+#exonware/xwsystem/src/exonware/xwsystem/io/serialization/defs.py
 #exonware/xwsystem/serialization/types.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.4
 Generation Date: 07-Sep-2025
 
 Serialization types and enums for XWSystem.

exonware/xwsystem/io/serialization/errors.py

@@ -1,9 +1,10 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/serialization/errors.py
 #exonware/xwsystem/serialization/errors.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.4
 Generation Date: September 04, 2025
 
 Error classes for XWSystem serialization module.

exonware/xwsystem/io/serialization/flyweight.py

@@ -1,9 +1,10 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/serialization/flyweight.py
 #exonware\xwsystem\serialization\flyweight.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.4
 Generation Date: September 05, 2025
 
 Flyweight Pattern Implementation for Serializers
@@ -14,7 +15,7 @@ configuration, which is especially important for high-throughput applications.
 """
 
 import threading
-from typing import Any, Hashable, Optional, Union
+from typing import Any, Hashable, Optional
 # Root cause: Migrating to Python 3.12 built-in generic syntax for consistency
 # Priority #3: Maintainability - Modern type annotations improve code clarity
 from weakref import WeakValueDictionary
@@ -172,7 +173,10 @@ class SerializerFlyweight:
 _serializer_flyweight = SerializerFlyweight()
 
 
-def get_serializer[T: ISerialization](serializer_class: type[T], **config: Any) -> T:
+def get_serializer[T: ISerialization](
+    serializer_class_or_name: type[T] | str, 
+    **config: Any
+) -> T:
     """
     Get a serializer instance using the flyweight pattern.
     
@@ -180,22 +184,165 @@ def get_serializer[T: ISerialization](serializer_class: type[T], **config: Any)
     automatic memory optimization through instance sharing.
     
     Args:
-        serializer_class: The serializer class to instantiate
+        serializer_class_or_name: The serializer class to instantiate, or a string
+                                  format name (e.g., "json", "yaml", "toml")
         **config: Configuration parameters for the serializer
         
     Returns:
         Shared serializer instance
-        
+    
     Example:
         >>> from xwsystem.serialization import JsonSerializer
         >>> # These will return the same instance
         >>> json1 = get_serializer(JsonSerializer, validate_input=True)
         >>> json2 = get_serializer(JsonSerializer, validate_input=True)
         >>> assert json1 is json2  # Same instance
+        >>> 
+        >>> # Can also use string format name
+        >>> json3 = get_serializer("json")
+        >>> json4 = get_serializer("json")
+        >>> assert json3 is json4  # Same instance
+        >>> assert json1 is json3  # Same instance (if config matches)
     """
+    # If string format name is provided, resolve to serializer class
+    if isinstance(serializer_class_or_name, str):
+        serializer_class = _get_serializer_class_from_name(serializer_class_or_name)
+    else:
+        serializer_class = serializer_class_or_name
+    
     return _serializer_flyweight.get_serializer(serializer_class, **config)
 
 
+def _get_serializer_class_from_name(format_name: str) -> type[ISerialization]:
+    """
+    Get serializer class from format name string.
+    
+    Args:
+        format_name: Format name (e.g., "json", "yaml", "toml")
+        
+    Returns:
+        Serializer class
+        
+    Raises:
+        ValueError: If format is not supported
+    """
+    # Import here to avoid circular imports
+    # Import from formats.text, formats.binary, formats.database packages
+    from .formats.text import (
+        JsonSerializer, YamlSerializer, TomlSerializer, XmlSerializer,
+        CsvSerializer, ConfigParserSerializer, FormDataSerializer, 
+        MultipartSerializer, Json5Serializer, JsonLinesSerializer
+    )
+    from .formats.binary import (
+        PickleSerializer, MarshalSerializer, BsonSerializer, 
+        MsgPackSerializer, CborSerializer, PlistSerializer
+    )
+    from .formats.database import (
+        DbmSerializer, ShelveSerializer, Sqlite3Serializer
+    )
+    
+    # Core formats (17+ formats)
+    format_map = {
+        'json': JsonSerializer,
+        'yaml': YamlSerializer, 
+        'toml': TomlSerializer,
+        'xml': XmlSerializer,
+        'csv': CsvSerializer,
+        'ini': ConfigParserSerializer,
+        'configparser': ConfigParserSerializer,
+        'pickle': PickleSerializer,
+        'marshal': MarshalSerializer,
+        'bson': BsonSerializer,
+        'msgpack': MsgPackSerializer,
+        'cbor': CborSerializer,
+        'dbm': DbmSerializer,
+        'shelve': ShelveSerializer,
+        'plist': PlistSerializer,
+        'formdata': FormDataSerializer,
+        'multipart': MultipartSerializer,
+        'json5': Json5Serializer,
+        'jsonl': JsonLinesSerializer,
+        'jsonlines': JsonLinesSerializer,
+        'ndjson': JsonLinesSerializer,
+        'sqlite3': Sqlite3Serializer,
+        'sqlite': Sqlite3Serializer,
+    }
+    
+    # Check for enterprise formats (available in xwformats)
+    enterprise_formats = {
+        'avro', 'protobuf', 'thrift', 'parquet', 'orc', 'capnproto', 'flatbuffers',
+        'hdf5', 'feather', 'zarr', 'netcdf', 'mat',
+        'lmdb', 'graphdb', 'leveldb', 'ubjson'
+    }
+    
+    format_lower = format_name.lower()
+    
+    if format_lower in enterprise_formats:
+        # Try to get from xwformats registry
+        from ..codec.registry import get_registry
+        registry = get_registry()
+        codec = (registry.get_by_id(format_lower) or 
+                registry.get_by_id(format_name.lower()) or 
+                registry.get_by_id(format_name.upper()) or
+                registry.get_by_alias(format_lower) or
+                registry.get_by_alias(format_name.lower()) or
+                registry.get_by_alias(format_name.upper()))
+        
+        if codec:
+            # Check if codec implements ISerialization (has dumps/loads)
+            if hasattr(codec, 'dumps') and hasattr(codec, 'loads'):
+                return type(codec)
+            else:
+                raise ValueError(
+                    f"Format '{format_name}' found in registry but doesn't implement ISerialization. "
+                    f"Use the codec directly or ensure it's a full serializer implementation."
+                )
+        else:
+            raise ValueError(
+                f"Enterprise format '{format_name}' requires exonware-xwformats.\n"
+                f"Install with: pip install exonware-xwformats\n"
+                f"Or use lazy install: pip install exonware-xwsystem[lazy]\n"
+                f"Then import: from exonware.xwformats import {format_name.capitalize()}Serializer"
+            )
+    
+    serializer_class = format_map.get(format_lower)
+    if not serializer_class:
+        # Check UniversalCodecRegistry for auto-registered formats (like XWJSON)
+        # XWJSON and other formats auto-register themselves when their modules are imported
+        try:
+            from ..codec.registry import get_registry
+            registry = get_registry()
+            # Try format name as-is, then lowercase, then uppercase, then aliases
+            codec = (registry.get_by_id(format_lower) or 
+                    registry.get_by_id(format_name.lower()) or 
+                    registry.get_by_id(format_name.upper()) or
+                    registry.get_by_alias(format_lower) or
+                    registry.get_by_alias(format_name.lower()) or
+                    registry.get_by_alias(format_name.upper()))
+            
+            if codec:
+                # Check if codec implements ISerialization (has dumps/loads or load_file/save_file)
+                if hasattr(codec, 'load_file') and hasattr(codec, 'save_file'):
+                    # This is a full ISerialization implementation (like XWJSONSerializer)
+                    return type(codec)
+                elif hasattr(codec, 'dumps') and hasattr(codec, 'loads'):
+                    # This is a full ISerialization implementation
+                    return type(codec)
+        except Exception:
+            # Registry not available or format not found, continue to error
+            pass
+        
+        available_formats = list(format_map.keys())
+        raise ValueError(
+            f"Unsupported format: {format_name}. "
+            f"Available core formats: {', '.join(sorted(available_formats))}\n"
+            f"Enterprise formats available in exonware-xwformats: {', '.join(sorted(enterprise_formats))}\n"
+            f"Auto-registered formats (XWJSON, etc.) should be available via UniversalCodecRegistry"
+        )
+    
+    return serializer_class
+
+
 def get_flyweight_stats() -> dict[str, Any]:
     """
     Get flyweight usage statistics.
@@ -334,7 +481,7 @@ def create_serializer(format_name: str, **config: Any) -> ISerialization:
         ValueError: If format is not supported
     """
     # Import here to avoid circular imports
-    # Core formats (always available)
+    # Core formats (stdlib)
     from . import (
         JsonSerializer, YamlSerializer, TomlSerializer, XmlSerializer,
         CsvSerializer, ConfigParserSerializer, PickleSerializer, MarshalSerializer,
@@ -344,7 +491,7 @@ def create_serializer(format_name: str, **config: Any) -> ISerialization:
     )
     
     # NOTE: Enterprise formats moved to exonware-xwformats per DEV_GUIDELINES.md
-    # Users should explicitly import from xwformats:
+    # Users explicitly import from xwformats:
     # from exonware.xwformats import AvroSerializer, ProtobufSerializer, ...
     # Then use them directly or via registry