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

exonware/xwsystem/io/file/source.py

@@ -4,7 +4,7 @@
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.410
+Version: 0.0.1.411
 Generation Date: 30-Oct-2025
 
 File-based data source implementation.
@@ -66,12 +66,14 @@ class FileDataSource(IDataSource[Union[bytes, str]]):
         self._validate_path = validate_path
         
         if validate_path:
-            # Use PathManager for validation if available
+            # Use PathValidator for validation if available
             try:
-                from ..common.path_manager import PathManager
-                pm = PathManager()
-                if not pm.is_safe_path(self._path):
-                    raise ValueError(f"Unsafe path: {self._path}")
+                from ...security.path_validator import PathValidator
+                # Don't check existence during initialization - file may be created later
+                pv = PathValidator(check_existence=False)
+                # For write modes, allow creating the file (path doesn't exist yet)
+                for_writing = mode and ('w' in mode or 'a' in mode or '+' in mode)
+                pv.validate_path(str(self._path), for_writing=for_writing, create_dirs=True)
             except ImportError:
                 pass
     
@@ -131,10 +133,19 @@ class FileDataSource(IDataSource[Union[bytes, str]]):
             if atomic:
                 # Use AtomicFileWriter from common
                 from ..common.atomic import AtomicFileWriter
-                with AtomicFileWriter(self._path, backup=backup) as writer:
+                # Determine mode based on data type and stored mode
+                if isinstance(data, bytes):
+                    # Binary mode
+                    atomic_mode = 'wb'
+                    encoding = None
+                else:
+                    # Text mode
+                    atomic_mode = 'w'
+                    encoding = options.get('encoding', self._encoding or 'utf-8')
+                
+                with AtomicFileWriter(self._path, mode=atomic_mode, encoding=encoding, backup=backup) as writer:
                     if isinstance(data, str):
-                        encoding = options.get('encoding', self._encoding or 'utf-8')
-                        writer.write(data.encode(encoding))
+                        writer.write(data)
                     else:
                         writer.write(data)
             else:

exonware/xwsystem/io/filesystem/__init__.py

@@ -4,7 +4,7 @@
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.410
+Version: 0.0.1.411
 Generation Date: 30-Oct-2025
 
 Virtual filesystem abstractions.

exonware/xwsystem/io/filesystem/base.py

@@ -4,7 +4,7 @@
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.410
+Version: 0.0.1.411
 Generation Date: 30-Oct-2025
 
 Base classes for virtual filesystem.

exonware/xwsystem/io/filesystem/local.py

@@ -4,7 +4,7 @@
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.410
+Version: 0.0.1.411
 Generation Date: 30-Oct-2025
 
 Local filesystem implementation.
@@ -144,4 +144,12 @@ class LocalFileSystem(IFileSystem):
         p = self._resolve_path(path)
         p.parent.mkdir(parents=True, exist_ok=True)
         p.write_bytes(content)
+    
+    def read(self, path: str) -> bytes:
+        """Read file contents."""
+        return self.read_bytes(path)
+    
+    def write(self, path: str, content: bytes) -> None:
+        """Write file contents."""
+        self.write_bytes(path, content)
 

exonware/xwsystem/io/folder/__init__.py

@@ -4,7 +4,7 @@
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.410
+Version: 0.0.1.411
 Generation Date: 30-Oct-2025
 
 Folder-specific implementations.

exonware/xwsystem/io/folder/base.py

@@ -4,7 +4,7 @@
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.410
+Version: 0.0.1.411
 Generation Date: 30-Oct-2025
 
 Base classes for folder operations.

exonware/xwsystem/io/folder/folder.py

@@ -2,7 +2,7 @@
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.410
+Version: 0.0.1.411
 Generation Date: September 04, 2025
 
 XWFolder - Concrete implementation of folder operations.
@@ -65,7 +65,7 @@ class XWFolder(AFolder):
     def create(self, parents: bool = True, exist_ok: bool = True) -> bool:
         """Create directory with validation."""
         if self.validate_paths:
-            self._path_validator.validate_path(self.dir_path)
+            self._path_validator.validate_path(self.dir_path, for_writing=True, create_dirs=parents)
         
         with performance_monitor("directory_create"):
             try:

exonware/xwsystem/io/serialization/__init__.py

@@ -2,7 +2,7 @@
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.410
+Version: 0.0.1.411
 Generation Date: November 2, 2025
 
 Serialization module - 29+ serialization formats with I→A→XW pattern.

exonware/xwsystem/io/serialization/auto_serializer.py

@@ -3,14 +3,14 @@
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.410
+Version: 0.0.1.411
 Generation Date: September 04, 2025
 
 Automatic serializer that detects format and delegates to appropriate serializer.
 """
 
 from pathlib import Path
-from typing import Any, Optional, Type, Union
+from typing import Any, Optional, Union
 
 from .format_detector import FormatDetector, detect_format
 from .contracts import ISerialization
@@ -39,7 +39,7 @@ class AutoSerializer:
         self._serializer_cache: dict[str, ISerialization] = {}
         self._default_format = default_format
     
-    def _get_serializer_class(self, format_name: str) -> Type[ISerialization]:
+    def _get_serializer_class(self, format_name: str) -> type[ISerialization]:
         """
         Get serializer class for format name.
         
@@ -52,36 +52,45 @@ class AutoSerializer:
         Raises:
             ImportError: If format not available
         """
-        # Dynamic import to avoid circular dependencies
+        # Dynamic import to avoid circular dependencies.
+        # Root cause fix: import concrete serializers from the canonical
+        # xwsystem.io.serialization.formats packages instead of a parallel
+        # exonware.xwsystem.serialization namespace (which should not exist).
         module_map = {
-            'JSON': ('json', 'JsonSerializer'),
-            'YAML': ('yaml', 'YamlSerializer'),
-            'TOML': ('toml', 'TomlSerializer'),
-            'XML': ('xml', 'XmlSerializer'),
-            'CSV': ('csv', 'CsvSerializer'),
-            'ConfigParser': ('configparser', 'ConfigParserSerializer'),
-            'FormData': ('formdata', 'FormDataSerializer'),
-            'Multipart': ('multipart', 'MultipartSerializer'),
-            
-            # Binary formats
-            'BSON': ('bson', 'BsonSerializer'),
-            'MessagePack': ('msgpack', 'MsgPackSerializer'),
-            'CBOR': ('cbor', 'CborSerializer'),
-            'Pickle': ('pickle', 'PickleSerializer'),
-            'Marshal': ('marshal', 'MarshalSerializer'),
-            'SQLite3': ('sqlite3', 'Sqlite3Serializer'),
-            'DBM': ('dbm', 'DbmSerializer'),
-            'Shelve': ('shelve', 'ShelveSerializer'),
-            'Plistlib': ('plistlib', 'PlistSerializer'),
-            
-            # Schema-based formats
-            'Avro': ('avro', 'AvroSerializer'),
-            'Protobuf': ('protobuf', 'ProtobufSerializer'),
-            'Thrift': ('thrift', 'ThriftSerializer'),
-            'Parquet': ('parquet', 'ParquetSerializer'),
-            'ORC': ('orc', 'OrcSerializer'),
-            'CapnProto': ('capnproto', 'CapnProtoSerializer'),
-            'FlatBuffers': ('flatbuffers', 'FlatBuffersSerializer'),
+            # Text formats
+            'JSON': ('io.serialization.formats.text.json', 'JsonSerializer'),
+            'JSONL': ('io.serialization.formats.text.jsonlines', 'JsonLinesSerializer'),
+            'NDJSON': ('io.serialization.formats.text.jsonlines', 'JsonLinesSerializer'),
+            'YAML': ('io.serialization.formats.text.yaml', 'YamlSerializer'),
+            'TOML': ('io.serialization.formats.text.toml', 'TomlSerializer'),
+            'XML': ('io.serialization.formats.text.xml', 'XmlSerializer'),
+            'CSV': ('io.serialization.formats.text.csv', 'CsvSerializer'),
+            'ConfigParser': ('io.serialization.formats.text.configparser', 'ConfigParserSerializer'),
+            'FormData': ('io.serialization.formats.text.formdata', 'FormDataSerializer'),
+            'Multipart': ('io.serialization.formats.text.multipart', 'MultipartSerializer'),
+
+            # Binary / database formats
+            'BSON': ('io.serialization.formats.binary.bson', 'BsonSerializer'),
+            'MessagePack': ('io.serialization.formats.binary.msgpack', 'MsgPackSerializer'),
+            'CBOR': ('io.serialization.formats.binary.cbor', 'CborSerializer'),
+            'Pickle': ('io.serialization.formats.binary.pickle', 'PickleSerializer'),
+            'Marshal': ('io.serialization.formats.binary.marshal', 'MarshalSerializer'),
+            'SQLite3': ('io.serialization.formats.database.sqlite3', 'Sqlite3Serializer'),
+            'DBM': ('io.serialization.formats.database.dbm', 'DbmSerializer'),
+            'Shelve': ('io.serialization.formats.database.shelve', 'ShelveSerializer'),
+            'Plistlib': ('io.serialization.formats.binary.plistlib', 'PlistSerializer'),
+
+            # Schema-based / advanced formats (placeholders for future modules)
+            # These entries intentionally point to non-existent modules today.
+            # The lazy installation system will handle installing/adding them
+            # when the corresponding format implementations are introduced.
+            'Avro': ('io.serialization.formats.schema.avro', 'AvroSerializer'),
+            'Protobuf': ('io.serialization.formats.schema.protobuf', 'ProtobufSerializer'),
+            'Thrift': ('io.serialization.formats.schema.thrift', 'ThriftSerializer'),
+            'Parquet': ('io.serialization.formats.scientific.parquet', 'ParquetSerializer'),
+            'ORC': ('io.serialization.formats.scientific.orc', 'OrcSerializer'),
+            'CapnProto': ('io.serialization.formats.schema.capnproto', 'CapnProtoSerializer'),
+            'FlatBuffers': ('io.serialization.formats.schema.flatbuffers', 'FlatBuffersSerializer'),
         }
         
         if format_name not in module_map:
@@ -90,9 +99,9 @@ class AutoSerializer:
         module_name, class_name = module_map[format_name]
         
         try:
-            # Import from current package
-            module = __import__(f'exonware.xwsystem.serialization.{module_name}', 
-                              fromlist=[class_name])
+            # Import from canonical xwsystem.io serialization path
+            module = __import__(f'exonware.xwsystem.{module_name}',
+                                fromlist=[class_name])
             return getattr(module, class_name)
         except (ImportError, AttributeError) as e:
             # Lazy installation system will handle missing dependencies
@@ -119,7 +128,8 @@ class AutoSerializer:
         self, 
         data: Any, 
         file_path: Optional[Union[str, Path]] = None,
-        format_hint: Optional[str] = None
+        format_hint: Optional[str] = None,
+        **opts
     ) -> Union[str, bytes]:
         """
         Auto-detect format and serialize data.
@@ -128,6 +138,7 @@ class AutoSerializer:
             data: Data to serialize
             file_path: Optional file path for format detection
             format_hint: Optional format hint to use
+            **opts: Additional serializer-specific options (pretty, indent, etc.)
             
         Returns:
             Serialized data
@@ -145,7 +156,7 @@ class AutoSerializer:
                 logger.debug(f"Using default format: {format_name}")
         
         serializer = self._get_serializer(format_name)
-        return serializer.dumps(data)
+        return serializer.dumps(data, **opts)
     
     def detect_and_deserialize(
         self, 
@@ -362,7 +373,8 @@ _global_auto_serializer = AutoSerializer()
 def auto_serialize(
     data: Any, 
     file_path: Optional[Union[str, Path]] = None,
-    format_hint: Optional[str] = None
+    format_hint: Optional[str] = None,
+    **opts
 ) -> Union[str, bytes]:
     """
     Convenience function for auto-serialization.
@@ -371,11 +383,12 @@ def auto_serialize(
         data: Data to serialize
         file_path: Optional file path for format detection
         format_hint: Optional format hint
+        **opts: Additional serializer options
         
     Returns:
         Serialized data
     """
-    return _global_auto_serializer.detect_and_serialize(data, file_path, format_hint)
+    return _global_auto_serializer.detect_and_serialize(data, file_path, format_hint, **opts)
 
 def auto_deserialize(
     data: Union[str, bytes], 

exonware/xwsystem/io/serialization/base.py

@@ -2,7 +2,7 @@
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.410
+Version: 0.0.1.411
 Generation Date: November 2, 2025
 
 Serialization base classes - ASerialization abstract base.
@@ -275,6 +275,27 @@ class ASerialization(ACodec[Any, Union[bytes, str]], ISerialization):
             True if lazy loading is supported
         """
         return False
+
+    @property
+    def supports_record_streaming(self) -> bool:
+        """
+        Whether this serializer exposes record-level streaming operations
+        (stream_read_record / stream_update_record).
+
+        Default: False. Override in subclasses that provide efficient record
+        streaming on top of their underlying format.
+        """
+        return False
+
+    @property
+    def supports_record_paging(self) -> bool:
+        """
+        Whether this serializer supports efficient record-level paging.
+
+        Default: False. Override in subclasses that can page records without
+        loading the entire dataset.
+        """
+        return False
     
     # ========================================================================
     # FILE I/O METHODS (Default implementations using encode/decode)
@@ -373,6 +394,149 @@ class ASerialization(ACodec[Any, Union[bytes, str]], ISerialization):
                 format_name=self.format_name,
                 original_error=e
             )
+
+    # ========================================================================
+    # RECORD-LEVEL OPERATIONS (Generic defaults – can be overridden)
+    # ========================================================================
+
+    def stream_read_record(
+        self,
+        file_path: Union[str, Path],
+        match: callable,
+        projection: Optional[list[Any]] = None,
+        **options: Any,
+    ) -> Any:
+        """
+        Default record-level read:
+        - Load the entire file via load_file().
+        - If top-level is a list, scan until match(record) is True.
+        - Apply optional projection and return the first matching record.
+
+        This is format-agnostic but may be expensive for huge files. Formats
+        that support true streaming should override this method.
+        """
+        data = self.load_file(file_path, **options)
+
+        if isinstance(data, list):
+            for record in data:
+                if match(record):
+                    return self._apply_projection(record, projection)
+
+        # Fallback: treat entire object as a single "record"
+        if match(data):
+            return self._apply_projection(data, projection)
+
+        raise KeyError("No matching record found")
+
+    def stream_update_record(
+        self,
+        file_path: Union[str, Path],
+        match: callable,
+        updater: callable,
+        *,
+        atomic: bool = True,
+        **options: Any,
+    ) -> int:
+        """
+        Default record-level update:
+        - Load entire file via load_file().
+        - If top-level is a list, apply updater() to matching records.
+        - Save the modified data back via save_file().
+
+        This is generic and honours the serializer's existing atomic/write
+        behavior, but may be expensive for huge files. Formats that support
+        streaming/partial updates should override this method.
+        """
+        data = self.load_file(file_path, **options)
+        updated = 0
+
+        if isinstance(data, list):
+            new_records: list[Any] = []
+            for record in data:
+                if match(record):
+                    record = updater(record)
+                    updated += 1
+                new_records.append(record)
+            data = new_records
+        else:
+            if match(data):
+                data = updater(data)
+                updated = 1
+
+        # Delegate to existing save_file() which may already be atomic.
+        self.save_file(data, file_path, **options)
+        return updated
+
+    def get_record_page(
+        self,
+        file_path: Union[str, Path],
+        page_number: int,
+        page_size: int,
+        **options: Any,
+    ) -> list[Any]:
+        """
+        Default record-level paging:
+        - Load entire file via load_file().
+        - If top-level is a list, return a slice corresponding to the requested page.
+
+        Formats that support indexed or streaming paging should override this
+        method for better performance on very large datasets.
+        """
+        if page_number < 1 or page_size <= 0:
+            raise ValueError("Invalid page_number or page_size")
+
+        data = self.load_file(file_path, **options)
+
+        if isinstance(data, list):
+            start = (page_number - 1) * page_size
+            end = start + page_size
+            return data[start:end]
+
+        # Non-list data: treat as a single record page
+        if page_number == 1 and page_size > 0:
+            return [data]
+
+        return []
+
+    def get_record_by_id(
+        self,
+        file_path: Union[str, Path],
+        id_value: Any,
+        *,
+        id_field: str = "id",
+        **options: Any,
+    ) -> Any:
+        """
+        Default record lookup by id:
+        - Load entire file via load_file().
+        - If top-level is a list of dict-like records, scan for record[id_field].
+        """
+        data = self.load_file(file_path, **options)
+
+        if isinstance(data, list):
+            for record in data:
+                if isinstance(record, dict) and record.get(id_field) == id_value:
+                    return record
+
+        # Single-record fallback
+        if isinstance(data, dict) and data.get(id_field) == id_value:
+            return data
+
+        raise KeyError(f"Record with {id_field}={id_value!r} not found")
+
+    # Small helper for projection handling
+    def _apply_projection(self, record: Any, projection: Optional[list[Any]]) -> Any:
+        if not projection:
+            return record
+        current = record
+        for key in projection:
+            if isinstance(current, dict) and isinstance(key, str):
+                current = current[key]
+            elif isinstance(current, list) and isinstance(key, int):
+                current = current[key]
+            else:
+                raise KeyError(key)
+        return current
     
     # ========================================================================
     # VALIDATION METHODS (Default implementations)

exonware/xwsystem/io/serialization/contracts.py

@@ -2,7 +2,7 @@
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.410
+Version: 0.0.1.411
 Generation Date: November 2, 2025
 
 Serialization contracts - ISerialization interface extending ICodec.
@@ -435,3 +435,90 @@ class ISerialization(ICodec[Any, Union[bytes, str]]):
         """
         pass
 
+    # ========================================================================
+    # RECORD-LEVEL OPERATIONS (Optional, generic defaults in ASerialization)
+    # ========================================================================
+
+    def stream_read_record(
+        self,
+        file_path: Union[str, Path],
+        match: callable,
+        projection: Optional[list[Any]] = None,
+        **options: Any,
+    ) -> Any:
+        """
+        Stream-style read of a single logical record from a file.
+
+        Semantics:
+        - Treat the underlying representation as a sequence of logical records
+          (e.g., list elements, table rows, NDJSON records).
+        - Return the first record that satisfies `match(record)`.
+        - If `projection` is provided, return only that sub-structure.
+
+        Concrete serializers may override this for efficient, true streaming
+        (e.g., NDJSON line-by-line). The default implementation in ASerialization
+        is allowed to load the full file and scan in memory.
+        """
+        raise NotImplementedError
+
+    def stream_update_record(
+        self,
+        file_path: Union[str, Path],
+        match: callable,
+        updater: callable,
+        *,
+        atomic: bool = True,
+        **options: Any,
+    ) -> int:
+        """
+        Stream-style update of logical records in a file.
+
+        Semantics:
+        - Apply `updater(record)` to each record for which `match(record)` is True.
+        - When `atomic=True`, must preserve atomicity guarantees (temp file +
+          replace, or equivalent) provided by the underlying serializer/I/O.
+        - Returns the number of updated records.
+
+        Concrete serializers may override this to avoid loading the full file.
+        The default implementation in ASerialization may be full-load.
+        """
+        raise NotImplementedError
+
+    def get_record_page(
+        self,
+        file_path: Union[str, Path],
+        page_number: int,
+        page_size: int,
+        **options: Any,
+    ) -> list[Any]:
+        """
+        Retrieve a logical page of records from a file.
+
+        Semantics:
+        - page_number is 1-based.
+        - page_size is the number of records.
+        - Returns a list of native records.
+
+        Concrete serializers may override this to use indexes or streaming.
+        The default implementation in ASerialization may load the entire file
+        and slice a top-level list.
+        """
+        raise NotImplementedError
+
+    def get_record_by_id(
+        self,
+        file_path: Union[str, Path],
+        id_value: Any,
+        *,
+        id_field: str = "id",
+        **options: Any,
+    ) -> Any:
+        """
+        Retrieve a logical record by identifier (e.g., record[id_field] == id_value).
+
+        Concrete serializers may override this to use an index or format-specific
+        mechanisms. The default implementation in ASerialization may perform a
+        linear scan over a top-level list.
+        """
+        raise NotImplementedError
+

exonware/xwsystem/io/serialization/defs.py

@@ -4,7 +4,7 @@
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.410
+Version: 0.0.1.411
 Generation Date: 07-Sep-2025
 
 Serialization types and enums for XWSystem.

exonware/xwsystem/io/serialization/errors.py

@@ -3,7 +3,7 @@
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.410
+Version: 0.0.1.411
 Generation Date: September 04, 2025
 
 Error classes for XWSystem serialization module.