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

exonware/xwsystem/io/serialization/formats/text/jsonlines.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: 02-Nov-2025
 
 JSON Lines (JSONL/NDJSON) Serialization - Newline-Delimited JSON
@@ -26,11 +26,12 @@ from typing import Any, Optional, Union
 from pathlib import Path
 import json
 
-from ...base import ASerialization
-from ...contracts import ISerialization
+from .json import JsonSerializer
+from ....errors import SerializationError
+from ....common.atomic import AtomicFileWriter
 
 
-class JsonLinesSerializer(ASerialization):
+class JsonLinesSerializer(JsonSerializer):
     """
     JSON Lines (JSONL/NDJSON) serializer for streaming data.
     
@@ -67,8 +68,36 @@ class JsonLinesSerializer(ASerialization):
     def codec_types(self) -> list[str]:
         """JSON Lines is a data exchange format."""
         return ["data", "serialization"]
-    
-    def encode(self, data: Any, options: Optional[dict[str, Any]] = None) -> str:
+
+    # -------------------------------------------------------------------------
+    # RECORD / STREAMING CAPABILITIES
+    # -------------------------------------------------------------------------
+
+    @property
+    def supports_record_streaming(self) -> bool:
+        """
+        JSONL is explicitly designed for record-level streaming.
+
+        This enables stream_read_record / stream_update_record to operate in a
+        true streaming fashion (line-by-line) without loading the entire file.
+        """
+        return True
+
+    @property
+    def supports_record_paging(self) -> bool:
+        """
+        JSONL supports efficient record-level paging.
+
+        Paging is implemented as a lightweight line counter that only parses
+        the requested slice of records.
+        """
+        return True
+
+    # -------------------------------------------------------------------------
+    # CORE ENCODE / DECODE
+    # -------------------------------------------------------------------------
+
+    def encode(self, data: Any, *, options: Optional[dict[str, Any]] = None) -> str:
         """
         Encode data to JSON Lines string.
         
@@ -82,14 +111,17 @@ class JsonLinesSerializer(ASerialization):
         if not isinstance(data, list):
             # Single object - wrap in list
             data = [data]
-        
-        lines = []
+
+        opts = options or {}
+        ensure_ascii = opts.get("ensure_ascii", False)
+
+        lines: list[str] = []
         for item in data:
-            lines.append(json.dumps(item, ensure_ascii=False))
-        
-        return '\n'.join(lines)
-    
-    def decode(self, data: Union[str, bytes], options: Optional[dict[str, Any]] = None) -> list[Any]:
+            lines.append(json.dumps(item, ensure_ascii=ensure_ascii))
+
+        return "\n".join(lines)
+
+    def decode(self, data: Union[str, bytes], *, options: Optional[dict[str, Any]] = None) -> list[Any]:
         """
         Decode JSON Lines string to list of Python objects.
         
@@ -101,16 +133,194 @@ class JsonLinesSerializer(ASerialization):
             List of decoded Python objects
         """
         if isinstance(data, bytes):
-            data = data.decode('utf-8')
-        
+            data = data.decode("utf-8")
+
         # Split by newlines and parse each line
-        lines = data.strip().split('\n')
-        results = []
-        
+        lines = data.strip().split("\n")
+        results: list[Any] = []
+
         for line in lines:
             line = line.strip()
             if line:  # Skip empty lines
                 results.append(json.loads(line))
-        
+
+        return results
+
+    # -------------------------------------------------------------------------
+    # RECORD-LEVEL OPERATIONS (True streaming, line-by-line)
+    # -------------------------------------------------------------------------
+
+    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 JSONL file.
+
+        Reads the file line-by-line, parsing each JSON object and returning the
+        first record that satisfies match(record). Optional projection is
+        applied using the base helper to avoid duplicating logic.
+        """
+        path = Path(file_path)
+        if not path.exists():
+            raise FileNotFoundError(f"File not found: {path}")
+
+        # Line-by-line scan – no full-file load
+        with path.open("r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                record = json.loads(line)
+                if match(record):
+                    return self._apply_projection(record, 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:
+        """
+        Stream-style update of logical records in a JSONL file.
+
+        Implementation uses a temp file + AtomicFileWriter pattern to ensure
+        atomicity when atomic=True. Records are processed line-by-line and only
+        the matching records are materialized and updated.
+        """
+        path = Path(file_path)
+        if not path.exists():
+            raise FileNotFoundError(f"File not found: {path}")
+
+        updated = 0
+        backup = options.get("backup", True)
+        ensure_ascii = options.get("ensure_ascii", False)
+
+        try:
+            if atomic:
+                # Atomic path: use AtomicFileWriter for temp+replace semantics
+                with AtomicFileWriter(path, backup=backup) as writer:
+                    with path.open("r", encoding="utf-8") as src:
+                        for line in src:
+                            raw = line.rstrip("\n")
+                            if not raw.strip():
+                                # Preserve structural empty lines
+                                writer.write(b"\n")
+                                continue
+
+                            record = json.loads(raw)
+                            if match(record):
+                                record = updater(record)
+                                updated += 1
+
+                            out_line = json.dumps(record, ensure_ascii=ensure_ascii) + "\n"
+                            writer.write(out_line.encode("utf-8"))
+            else:
+                # Non-atomic fallback: read + rewrite line-by-line
+                new_lines: list[str] = []
+                with path.open("r", encoding="utf-8") as src:
+                    for line in src:
+                        raw = line.rstrip("\n")
+                        if not raw.strip():
+                            new_lines.append("\n")
+                            continue
+
+                        record = json.loads(raw)
+                        if match(record):
+                            record = updater(record)
+                            updated += 1
+
+                        new_lines.append(json.dumps(record, ensure_ascii=ensure_ascii) + "\n")
+
+                path.parent.mkdir(parents=True, exist_ok=True)
+                path.write_text("".join(new_lines), encoding="utf-8")
+
+            return updated
+        except Exception as e:
+            raise SerializationError(
+                f"Failed to stream-update JSONL records in {path}: {e}",
+                format_name=self.format_name,
+                original_error=e,
+            ) from e
+
+    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 JSONL file.
+
+        Pages are computed by counting logical records (non-empty lines). Only
+        the requested slice is parsed and returned, keeping memory usage
+        proportional to page_size rather than file size.
+        """
+        if page_number < 1 or page_size <= 0:
+            raise ValueError("Invalid page_number or page_size")
+
+        path = Path(file_path)
+        if not path.exists():
+            raise FileNotFoundError(f"File not found: {path}")
+
+        start_index = (page_number - 1) * page_size
+        end_index = start_index + page_size
+
+        results: list[Any] = []
+        current_index = 0
+
+        with path.open("r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+
+                if current_index >= end_index:
+                    break
+
+                if current_index >= start_index:
+                    results.append(json.loads(line))
+
+                current_index += 1
+
         return results
 
+    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 from a JSONL file.
+
+        Performs a streaming linear scan over records, returning the first
+        record where record[id_field] == id_value.
+        """
+        path = Path(file_path)
+        if not path.exists():
+            raise FileNotFoundError(f"File not found: {path}")
+
+        with path.open("r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+
+                record = json.loads(line)
+                if isinstance(record, dict) and record.get(id_field) == id_value:
+                    return record
+
+        raise KeyError(f"Record with {id_field}={id_value!r} not found")
+

exonware/xwsystem/io/serialization/formats/text/multipart.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
 
 Multipart serialization - Multipart form data format.

exonware/xwsystem/io/serialization/formats/text/toml.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
 
 TOML serialization - Configuration file format.
@@ -180,8 +180,17 @@ class TomlSerializer(ASerialization):
         """
         try:
             if not isinstance(value, dict):
-                raise TypeError("TOML can only serialize dictionaries")
-            
+                # TOML requires a table (dict) at the top level. For data-oriented
+                # use cases (e.g. record lists), transparently wrap common patterns
+                # so that higher-level APIs (record paging, etc.) can still work
+                # uniformly across formats.
+                if isinstance(value, list):
+                    # Auto-wrap top-level list into "items" table.
+                    value = {"items": value}
+                else:
+                    # Fallback: wrap primitive/other types into a single "value" key.
+                    value = {"value": value}
+
             opts = options or {}
             
             # Root cause fixed: Remove None values before encoding (TOML doesn't support None).
@@ -227,6 +236,13 @@ class TomlSerializer(ASerialization):
             
             # Decode from TOML string
             data = tomllib.loads(repr)
+
+            # If this looks like an auto-wrapped list payload (see encode),
+            # unwrap it for callers so that higher-level APIs (including the
+            # generic record-level operations in ASerialization) see the
+            # natural Python structure (a list of records).
+            if isinstance(data, dict) and set(data.keys()) == {"items"} and isinstance(data["items"], list):
+                return data["items"]
             
             return data
             

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.410
+Version: 0.0.1.411
 Generation Date: November 2, 2025
 
 XML serialization - Extensible Markup Language.
@@ -427,6 +427,13 @@ class XmlSerializer(ASerialization):
         if isinstance(repr, bytes):
             repr = repr.decode('utf-8')
         
+        # Trim leading BOM/whitespace before XML declaration.
+        # Root cause: Some producers emit a blank line or BOM before '<?xml ...?>',
+        # which causes ExpatError: "XML or text declaration not at start of entity".
+        # Priority #2 (Usability): Be forgiving on harmless leading whitespace/BOM
+        # while keeping strict parsing for the actual XML content.
+        repr = repr.lstrip("\ufeff\r\n\t ")
+        
         opts = options or {}
         root_name = opts.get('root', 'root')
         preserve_types = opts.get('preserve_types', False)

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.410
+Version: 0.0.1.411
 Generation Date: November 2, 2025
 
 YAML serialization - Human-readable data serialization format.
@@ -13,7 +13,7 @@ Following I→A pattern:
 - Concrete: YamlSerializer
 """
 
-from typing import Any, Optional, Union
+from typing import Any, Optional, Union, Iterator
 from pathlib import Path
 
 from ...base import ASerialization
@@ -88,6 +88,10 @@ class YamlSerializer(ASerialization):
     def supports_streaming(self) -> bool:
         return True  # YAML supports multiple documents
     
+    @property
+    def supports_incremental_streaming(self) -> bool:
+        return True  # YAML supports multi-document streaming
+    
     @property
     def capabilities(self) -> CodecCapability:
         return CodecCapability.BIDIRECTIONAL
@@ -178,4 +182,50 @@ class YamlSerializer(ASerialization):
                 format_name=self.format_name,
                 original_error=e
             )
+    
+    # ========================================================================
+    # INCREMENTAL STREAMING
+    # ========================================================================
+    
+    def incremental_load(
+        self,
+        file_path: Union[str, Path],
+        **options: Any,
+    ) -> Iterator[Any]:
+        """
+        Stream YAML documents one at a time (supports multi-document YAML).
+        
+        Uses PyYAML's safe_load_all() for true streaming without loading
+        entire file into memory.
+        
+        Args:
+            file_path: Path to the YAML file
+            **options: YAML options (Loader, etc.)
+            
+        Yields:
+            Each document from the YAML file one at a time
+            
+        Raises:
+            FileNotFoundError: If file doesn't exist
+            SerializationError: If parsing fails
+        """
+        path = Path(file_path)
+        if not path.exists():
+            raise FileNotFoundError(f"File not found: {path}")
+        
+        opts = options or {}
+        loader = opts.get('Loader', yaml.SafeLoader)
+        
+        try:
+            with path.open("r", encoding="utf-8") as f:
+                # Use safe_load_all for multi-document streaming
+                for document in yaml.safe_load_all(f):
+                    if document is not None:  # Skip empty documents
+                        yield document
+        except (yaml.YAMLError, UnicodeDecodeError) as e:
+            raise SerializationError(
+                f"Failed to incrementally load YAML: {e}",
+                format_name=self.format_name,
+                original_error=e
+            ) from e
 

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.410
+Version: 0.0.1.411
 Generation Date: November 2, 2025
 
 Serialization Registry - Delegates to UniversalCodecRegistry.

exonware/xwsystem/io/serialization/serializer.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
 
 XWSerializer - Unified intelligent serializer with I/O integration and auto-serialization.
@@ -11,7 +11,7 @@ XWSerializer - Unified intelligent serializer with I/O integration and auto-seri
 import os
 import time
 from pathlib import Path
-from typing import Any, Optional, Union, Callable, Type
+from typing import Any, Optional, Union, Callable
 
 from .base import ASerialization
 from .contracts import ISerialization
@@ -97,7 +97,7 @@ class XWSerializer(ASerialization):
     # FORMAT DETECTION AND TRANSFORMATION (from XWSerialization)
     # ============================================================================
     
-    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."""
         module_map = {
             'JSON': ('json', 'JsonSerializer'),
@@ -775,6 +775,178 @@ class XWSerializer(ASerialization):
             except Exception as e:
                 logger.error(f"Merge failed for {target_path}: {e}")
                 raise SerializationError(f"Merge failed: {e}") from e
+
+    # ============================================================================
+    # RECORD-LEVEL OPERATIONS (delegated to specialized serializers)
+    # ============================================================================
+
+    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.
+
+        Delegates to the specialized serializer when available (e.g. JSONL /
+        NDJSON), falling back to the generic ASerialization implementation
+        which may load the entire file and scan in memory.
+        """
+        target_path = Path(file_path)
+
+        if self.validate_paths:
+            self._path_validator.validate_path(target_path)
+
+        format_hint = self._detect_format_from_path(target_path)
+        specialized = self._ensure_specialized(
+            file_path=target_path,
+            format_hint=format_hint,
+        )
+
+        try:
+            return specialized.stream_read_record(
+                target_path,
+                match,
+                projection=projection,
+                **options,
+            )
+        except NotImplementedError:
+            # Fallback to generic full-load behavior from ASerialization
+            return super().stream_read_record(
+                target_path,
+                match,
+                projection=projection,
+                **options,
+            )
+
+    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.
+
+        Delegates to the specialized serializer when it provides a streaming
+        implementation (e.g. JSONL). Falls back to the generic
+        ASerialization implementation that may load the full file, but still
+        honours atomic save semantics.
+        """
+        target_path = Path(file_path)
+
+        if self.validate_paths:
+            self._path_validator.validate_path(target_path)
+
+        format_hint = self._detect_format_from_path(target_path)
+        specialized = self._ensure_specialized(
+            file_path=target_path,
+            format_hint=format_hint,
+        )
+
+        try:
+            return specialized.stream_update_record(
+                target_path,
+                match,
+                updater,
+                atomic=atomic,
+                **options,
+            )
+        except NotImplementedError:
+            return super().stream_update_record(
+                target_path,
+                match,
+                updater,
+                atomic=atomic,
+                **options,
+            )
+
+    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.
+
+        Delegates to the specialized serializer when supported (for example,
+        JSONL can implement true streaming paging). Falls back to the generic
+        ASerialization implementation, which may load the entire file and
+        slice a top-level list.
+        """
+        target_path = Path(file_path)
+
+        if self.validate_paths:
+            self._path_validator.validate_path(target_path)
+
+        format_hint = self._detect_format_from_path(target_path)
+        specialized = self._ensure_specialized(
+            file_path=target_path,
+            format_hint=format_hint,
+        )
+
+        try:
+            return specialized.get_record_page(
+                target_path,
+                page_number,
+                page_size,
+                **options,
+            )
+        except NotImplementedError:
+            return super().get_record_page(
+                target_path,
+                page_number,
+                page_size,
+                **options,
+            )
+
+    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.
+
+        Delegates to the specialized serializer where possible; falls back to
+        the generic ASerialization implementation which performs a linear scan
+        over a top-level list.
+        """
+        target_path = Path(file_path)
+
+        if self.validate_paths:
+            self._path_validator.validate_path(target_path)
+
+        format_hint = self._detect_format_from_path(target_path)
+        specialized = self._ensure_specialized(
+            file_path=target_path,
+            format_hint=format_hint,
+        )
+
+        try:
+            return specialized.get_record_by_id(
+                target_path,
+                id_value,
+                id_field=id_field,
+                **options,
+            )
+        except NotImplementedError:
+            return super().get_record_by_id(
+                target_path,
+                id_value,
+                id_field=id_field,
+                **options,
+            )
     
     # ============================================================================
     # BATCH OPERATIONS

exonware/xwsystem/io/serialization/utils/__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: November 9, 2025
 
 Serialization utilities module.

exonware/xwsystem/io/serialization/utils/path_ops.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: November 9, 2025
 
 Path operations utilities for serialization formats.

exonware/xwsystem/io/stream/__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
 
 Stream operations and codec-integrated I/O.