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

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

@@ -1,3 +1,4 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/serialization/formats/text/append_only_log.py
 """Append-only log for fast atomic updates in JSONL files.
 
 This module provides an append-only log system that can be used by
@@ -12,11 +13,8 @@ import time
 from pathlib import Path
 from typing import Any, Callable
 
-try:
-    from exonware.xwsystem.io.serialization.parsers.registry import get_best_available_parser
-    _parser = get_best_available_parser()
-except ImportError:
-    import json as _parser
+from exonware.xwsystem.io.serialization.parsers.registry import get_best_available_parser
+_parser = get_best_available_parser()
 
 
 class AppendOnlyLog:
@@ -147,7 +145,7 @@ class AppendOnlyLog:
                 except Exception:
                     pass
         
-        # Not in log, return None (caller should read from main file)
+        # Not in log, return None (caller reads from main file)
         return None
     
     def _compact_background(self):
@@ -197,5 +195,5 @@ def atomic_update_with_append_log(
             # Fall through to full rewrite
             pass
     
-    # Fall back to full rewrite (caller should handle this)
+    # Fall back to full rewrite (caller handles this)
     return 0

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

@@ -1,8 +1,9 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/serialization/formats/text/configparser.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.3
 Generation Date: November 2, 2025
 
 ConfigParser serialization - INI file format.
@@ -15,7 +16,7 @@ Following I→A pattern:
 
 import configparser
 import io
-from typing import Any, Optional, Union
+from typing import Any, Optional
 from pathlib import Path
 
 from ...base import ASerialization
@@ -101,7 +102,7 @@ class ConfigParserSerializer(ASerialization):
     # CORE ENCODE/DECODE (Using configparser module)
     # ========================================================================
     
-    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 INI string.
         
@@ -147,7 +148,7 @@ class ConfigParserSerializer(ASerialization):
                 original_error=e
             )
     
-    def decode(self, repr: Union[bytes, str], *, options: Optional[DecodeOptions] = None) -> Any:
+    def decode(self, repr: bytes | str, *, options: Optional[DecodeOptions] = None) -> Any:
         """
         Decode INI string to data.
         
@@ -191,4 +192,3 @@ class ConfigParserSerializer(ASerialization):
                 format_name=self.format_name,
                 original_error=e
             )
-

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

@@ -1,8 +1,9 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/serialization/formats/text/csv.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.3
 Generation Date: November 2, 2025
 
 CSV serialization - Comma-separated values format.
@@ -15,7 +16,7 @@ Following I→A pattern:
 
 import csv
 import io
-from typing import Any, Optional, Union
+from typing import Any, Optional
 from pathlib import Path
 
 from ...base import ASerialization
@@ -102,7 +103,7 @@ class CsvSerializer(ASerialization):
     # CORE ENCODE/DECODE (Using csv module)
     # ========================================================================
     
-    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 CSV string.
         
@@ -163,7 +164,7 @@ class CsvSerializer(ASerialization):
                 original_error=e
             )
     
-    def decode(self, repr: Union[bytes, str], *, options: Optional[DecodeOptions] = None) -> Any:
+    def decode(self, repr: bytes | str, *, options: Optional[DecodeOptions] = None) -> Any:
         """
         Decode CSV string to data.
         
@@ -210,4 +211,5 @@ class CsvSerializer(ASerialization):
                 format_name=self.format_name,
                 original_error=e
             )
-
+    
+    # Note: File operations (save_file, load_file) are inherited from ASerialization base class

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

@@ -1,8 +1,9 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/serialization/formats/text/formdata.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.3
 Generation Date: November 2, 2025
 
 FormData serialization - URL-encoded form data.
@@ -14,7 +15,7 @@ Following I→A pattern:
 """
 
 from urllib.parse import urlencode, parse_qs
-from typing import Any, Optional, Union
+from typing import Any, Optional
 from pathlib import Path
 
 from ...base import ASerialization
@@ -89,7 +90,7 @@ class FormDataSerializer(ASerialization):
     # CORE ENCODE/DECODE (Using urllib.parse)
     # ========================================================================
     
-    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 form-data string.
         
@@ -129,7 +130,7 @@ class FormDataSerializer(ASerialization):
                 original_error=e
             )
     
-    def decode(self, repr: Union[bytes, str], *, options: Optional[DecodeOptions] = None) -> Any:
+    def decode(self, repr: bytes | str, *, options: Optional[DecodeOptions] = None) -> Any:
         """
         Decode form-data string to data.
         
@@ -172,4 +173,3 @@ class FormDataSerializer(ASerialization):
                 format_name=self.format_name,
                 original_error=e
             )
-

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

@@ -1,8 +1,9 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/serialization/formats/text/json.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.3
 Generation Date: November 2, 2025
 
 JSON serialization - Universal, human-readable data interchange format.
@@ -14,12 +15,12 @@ Following I→A pattern:
 """
 
 import json
-from typing import Any, Optional, Union
+from typing import Any, Optional
 from pathlib import Path
 
 from ...base import ASerialization
 from ...parsers.registry import get_parser
-from ...parsers.base import IJsonParser
+from ...parsers.base import AJsonParser
 from ....contracts import EncodeOptions, DecodeOptions
 from ....defs import CodecCapability
 from ....errors import SerializationError
@@ -54,15 +55,22 @@ class JsonSerializer(ASerialization):
         >>> user = serializer.load_file("user.json")
     """
     
-    def __init__(self, parser_name: Optional[str] = None):
+    def __init__(
+        self,
+        parser_name: Optional[str] = None,
+        max_depth: Optional[int] = None,
+        max_size_mb: Optional[float] = None,
+    ):
         """
         Initialize JSON serializer with optional parser selection.
         
         Args:
             parser_name: Parser name ("standard", "orjson", or None for auto-detect)
+            max_depth: Maximum nesting depth allowed (passed to ASerialization / ACodec)
+            max_size_mb: Maximum estimated data size in MB (passed to ASerialization / ACodec)
         """
-        super().__init__()
-        self._parser: IJsonParser = get_parser(parser_name)
+        super().__init__(max_depth=max_depth, max_size_mb=max_size_mb)
+        self._parser: AJsonParser = get_parser(parser_name)
     
     # ========================================================================
     # CODEC METADATA
@@ -137,7 +145,7 @@ class JsonSerializer(ASerialization):
     # CORE ENCODE/DECODE (Using official json library)
     # ========================================================================
     
-    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 JSON string.
         
@@ -188,7 +196,7 @@ class JsonSerializer(ASerialization):
                 original_error=e
             )
     
-    def decode(self, repr: Union[bytes, str], *, options: Optional[DecodeOptions] = None) -> Any:
+    def decode(self, repr: bytes | str, *, options: Optional[DecodeOptions] = None) -> Any:
         """
         Decode JSON string to data.
         
@@ -241,7 +249,7 @@ class JsonSerializer(ASerialization):
     
     def atomic_update_path(
         self, 
-        file_path: Union[str, Path], 
+        file_path: str | Path, 
         path: str, 
         value: Any, 
         **options
@@ -282,7 +290,7 @@ class JsonSerializer(ASerialization):
             
             # Load entire file
             # For large files (10GB+), skip size validation to allow atomic operations
-            # Root cause: Large files should use atomic path operations without full validation
+            # Root cause: Large files use atomic path operations without full validation
             # Solution: Skip size check for atomic operations (depth check still performed)
             large_file_options = {**options, 'skip_size_check': True}
             data = self.load_file(file_path, **large_file_options)
@@ -297,12 +305,14 @@ class JsonSerializer(ASerialization):
             path_obj.parent.mkdir(parents=True, exist_ok=True)
             
             backup = options.get('backup', True)
-            with AtomicFileWriter(path_obj, backup=backup) as writer:
+            encoding = options.get('encoding', 'utf-8')
+            # JSON encode returns str, not bytes - write as text
+            with AtomicFileWriter(path_obj, mode='w', encoding=encoding, backup=backup) as writer:
                 if isinstance(repr_data, bytes):
-                    writer.write(repr_data)
+                    # If somehow we got bytes, decode first
+                    writer.write(repr_data.decode(encoding))
                 else:
-                    encoding = options.get('encoding', 'utf-8')
-                    writer.write(repr_data.encode(encoding))
+                    writer.write(repr_data)
                     
         except (FileNotFoundError, ValueError, KeyError, jsonpointer.JsonPointerException) as e:
             raise
@@ -315,7 +325,7 @@ class JsonSerializer(ASerialization):
     
     def atomic_read_path(
         self, 
-        file_path: Union[str, Path], 
+        file_path: str | Path, 
         path: str, 
         **options
     ) -> Any:
@@ -356,7 +366,7 @@ class JsonSerializer(ASerialization):
             
             # Load entire file
             # For large files (10GB+), skip size validation to allow atomic operations
-            # Root cause: Large files should use atomic path operations without full validation
+            # Root cause: Large files use atomic path operations without full validation
             # Solution: Skip size check for atomic operations (depth check still performed)
             large_file_options = {**options, 'skip_size_check': True}
             data = self.load_file(file_path, **large_file_options)
@@ -377,7 +387,7 @@ class JsonSerializer(ASerialization):
     
     def query(
         self, 
-        file_path: Union[str, Path], 
+        file_path: str | Path, 
         query_expr: str, 
         **options
     ) -> Any:
@@ -429,4 +439,3 @@ class JsonSerializer(ASerialization):
                 format_name=self.format_name,
                 original_error=e
             ) from e
-

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

@@ -4,7 +4,7 @@
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.3
 Generation Date: 02-Nov-2025
 
 JSON5 Serialization - Extended JSON with Comments and Trailing Commas
@@ -23,7 +23,7 @@ Priority 4 (Performance): Efficient parsing via json5 library
 Priority 5 (Extensibility): Compatible with standard JSON
 """
 
-from typing import Any, Optional, Union
+from typing import Any, Optional
 from pathlib import Path
 
 # Lazy import for json5 - the lazy hook will automatically handle ImportError
@@ -85,6 +85,11 @@ class Json5Serializer(JsonSerializer):
         """Alternative names."""
         return ["json5", "JSON5"]
     
+    @property
+    def format_name(self) -> str:
+        """Format name."""
+        return "JSON5"
+    
     @property
     def codec_types(self) -> list[str]:
         """JSON5 is a serialization and config format (supports comments)."""
@@ -133,7 +138,7 @@ class Json5Serializer(JsonSerializer):
                 original_error=e
             )
     
-    def decode(self, data: Union[str, bytes], options: Optional[dict[str, Any]] = None) -> Any:
+    def decode(self, data: str | bytes, options: Optional[dict[str, Any]] = None) -> Any:
         """
         Decode JSON5 string to Python data.
         
@@ -191,4 +196,3 @@ class Json5Serializer(JsonSerializer):
                 format_name=self.format_name,
                 original_error=e
             )
-

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.1.0.1
+Version: 0.1.0.3
 Generation Date: 02-Nov-2025
 
 JSON Lines (JSONL/NDJSON) Serialization - Newline-Delimited JSON
@@ -22,13 +22,13 @@ Priority 4 (Performance): Memory-efficient streaming
 Priority 5 (Extensibility): Compatible with standard JSON
 """
 
-from typing import Any, Optional, Union
+from typing import Any, Optional
 from pathlib import Path
 import json
 
 from .json import JsonSerializer
 from ...parsers.registry import get_parser
-from ...parsers.base import IJsonParser
+from ...parsers.base import AJsonParser
 from ....errors import SerializationError
 from ....common.atomic import AtomicFileWriter
 from exonware.xwsystem.config.logging_setup import get_logger
@@ -55,12 +55,17 @@ class JsonLinesSerializer(JsonSerializer):
         """
         super().__init__(parser_name=parser_name)
         # Get parser instance for direct use in line-by-line operations
-        self._parser: IJsonParser = get_parser(parser_name)
+        self._parser: AJsonParser = get_parser(parser_name)
     
     @property
     def codec_id(self) -> str:
         """Codec identifier."""
-        return "jsonl"
+        return "jsonl"  # Primary ID, but "ndjson" also works via aliases
+    
+    @property
+    def format_name(self) -> str:
+        """Format display name."""
+        return "JSONL/NDJSON"  # Both names prominently displayed
     
     @property
     def media_types(self) -> list[str]:
@@ -74,8 +79,8 @@ class JsonLinesSerializer(JsonSerializer):
     
     @property
     def aliases(self) -> list[str]:
-        """Alternative names."""
-        return ["jsonl", "JSONL", "ndjson", "NDJSON", "jsonlines"]
+        """Alternative names - NDJSON is a first-class alias."""
+        return ["jsonl", "JSONL", "ndjson", "NDJSON", "jsonlines", "JSONLines"]
     
     @property
     def codec_types(self) -> list[str]:
@@ -139,7 +144,7 @@ class JsonLinesSerializer(JsonSerializer):
 
         return "\n".join(lines)
 
-    def decode(self, data: Union[str, bytes], *, options: Optional[dict[str, Any]] = None) -> list[Any]:
+    def decode(self, data: str | bytes, *, options: Optional[dict[str, Any]] = None) -> list[Any]:
         """
         Decode JSON Lines string to list of Python objects.
         
@@ -171,7 +176,7 @@ class JsonLinesSerializer(JsonSerializer):
 
     def stream_read_record(
         self,
-        file_path: Union[str, Path],
+        file_path: str | Path,
         match: callable,
         projection: Optional[list[Any]] = None,
         **options: Any,
@@ -202,7 +207,7 @@ class JsonLinesSerializer(JsonSerializer):
 
     def stream_update_record(
         self,
-        file_path: Union[str, Path],
+        file_path: str | Path,
         match: callable,
         updater: callable,
         *,
@@ -222,7 +227,7 @@ class JsonLinesSerializer(JsonSerializer):
         if not path.exists():
             raise FileNotFoundError(f"File not found: {path}")
 
-        # Check if append-only log should be used
+        # Check if append-only log is used
         perf_config = get_performance_config()
         use_append_log = options.get("use_append_log", None)
         if use_append_log is None:
@@ -335,7 +340,7 @@ class JsonLinesSerializer(JsonSerializer):
 
     def get_record_page(
         self,
-        file_path: Union[str, Path],
+        file_path: str | Path,
         page_number: int,
         page_size: int,
         **options: Any,
@@ -379,7 +384,7 @@ class JsonLinesSerializer(JsonSerializer):
 
     def get_record_by_id(
         self,
-        file_path: Union[str, Path],
+        file_path: str | Path,
         id_value: Any,
         *,
         id_field: str = "id",
@@ -407,4 +412,3 @@ class JsonLinesSerializer(JsonSerializer):
                     return record
 
         raise KeyError(f"Record with {id_field}={id_value!r} not found")
-

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

@@ -1,8 +1,9 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/serialization/formats/text/multipart.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.3
 Generation Date: November 2, 2025
 
 Multipart serialization - Multipart form data format.
@@ -20,7 +21,7 @@ from email import encoders
 from email.parser import BytesParser
 from email.policy import default
 import io
-from typing import Any, Optional, Union
+from typing import Any, Optional
 from pathlib import Path
 
 from ...base import ASerialization
@@ -97,7 +98,7 @@ class MultipartSerializer(ASerialization):
     # CORE ENCODE/DECODE (Using email.mime modules)
     # ========================================================================
     
-    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 multipart format.
         
@@ -150,7 +151,7 @@ class MultipartSerializer(ASerialization):
                 original_error=e
             )
     
-    def decode(self, repr: Union[bytes, str], *, options: Optional[DecodeOptions] = None) -> Any:
+    def decode(self, repr: bytes | str, *, options: Optional[DecodeOptions] = None) -> Any:
         """
         Decode multipart data.
         
@@ -209,4 +210,3 @@ class MultipartSerializer(ASerialization):
                 format_name=self.format_name,
                 original_error=e
             )
-

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

@@ -1,8 +1,9 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/serialization/formats/text/toml.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.3
 Generation Date: November 2, 2025
 
 TOML serialization - Configuration file format.
@@ -14,7 +15,7 @@ Following I→A pattern:
 """
 
 import sys
-from typing import Any, Optional, Union
+from typing import Any, Optional
 from pathlib import Path
 
 from ...base import ASerialization
@@ -158,7 +159,7 @@ class TomlSerializer(ASerialization):
             # Primitive values - return as-is (None will be filtered out by caller)
             return data
     
-    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 TOML string.
         
@@ -195,7 +196,7 @@ class TomlSerializer(ASerialization):
             
             # Root cause fixed: Remove None values before encoding (TOML doesn't support None).
             # Solution: Recursively remove None values to ensure TOML compatibility.
-            # Priority #2: Usability - All data structures should be serializable.
+            # Priority #2: Usability - All data structures are serializable.
             cleaned_value = self._remove_none_values(value)
             
             # Encode to TOML string
@@ -213,7 +214,7 @@ class TomlSerializer(ASerialization):
                 original_error=e
             )
     
-    def decode(self, repr: Union[bytes, str], *, options: Optional[DecodeOptions] = None) -> Any:
+    def decode(self, repr: bytes | str, *, options: Optional[DecodeOptions] = None) -> Any:
         """
         Decode TOML string to data.
         
@@ -252,4 +253,5 @@ class TomlSerializer(ASerialization):
                 format_name=self.format_name,
                 original_error=e
             )
-
+    
+    # Note: File operations (save_file, load_file) are inherited from ASerialization base class