exonware-xwsystem 0.0.1.411__py3-none-any.whl → 0.1.0.1__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.411
+Version: 0.1.0.1
 Generation Date: 02-Nov-2025
 
 JSON Lines (JSONL/NDJSON) Serialization - Newline-Delimited JSON
@@ -27,8 +27,14 @@ from pathlib import Path
 import json
 
 from .json import JsonSerializer
+from ...parsers.registry import get_parser
+from ...parsers.base import IJsonParser
 from ....errors import SerializationError
 from ....common.atomic import AtomicFileWriter
+from exonware.xwsystem.config.logging_setup import get_logger
+from exonware.xwsystem.config.performance import get_performance_config
+
+logger = get_logger(__name__)
 
 
 class JsonLinesSerializer(JsonSerializer):
@@ -40,9 +46,16 @@ class JsonLinesSerializer(JsonSerializer):
     Concrete: JsonLinesSerializer
     """
     
-    def __init__(self):
-        """Initialize JSON Lines serializer."""
-        super().__init__()
+    def __init__(self, parser_name: Optional[str] = None):
+        """
+        Initialize JSON Lines serializer with optional parser selection.
+        
+        Args:
+            parser_name: Parser name ("standard", "orjson", or None for auto-detect)
+        """
+        super().__init__(parser_name=parser_name)
+        # Get parser instance for direct use in line-by-line operations
+        self._parser: IJsonParser = get_parser(parser_name)
     
     @property
     def codec_id(self) -> str:
@@ -117,7 +130,12 @@ class JsonLinesSerializer(JsonSerializer):
 
         lines: list[str] = []
         for item in data:
-            lines.append(json.dumps(item, ensure_ascii=ensure_ascii))
+            # Use pluggable parser
+            result = self._parser.dumps(item, ensure_ascii=ensure_ascii)
+            # Convert bytes to str if needed
+            if isinstance(result, bytes):
+                result = result.decode("utf-8")
+            lines.append(result)
 
         return "\n".join(lines)
 
@@ -142,7 +160,8 @@ class JsonLinesSerializer(JsonSerializer):
         for line in lines:
             line = line.strip()
             if line:  # Skip empty lines
-                results.append(json.loads(line))
+                # Use pluggable parser
+                results.append(self._parser.loads(line))
 
         return results
 
@@ -174,7 +193,8 @@ class JsonLinesSerializer(JsonSerializer):
                 line = line.strip()
                 if not line:
                     continue
-                record = json.loads(line)
+                # Use pluggable parser
+                record = self._parser.loads(line)
                 if match(record):
                     return self._apply_projection(record, projection)
 
@@ -195,11 +215,63 @@ class JsonLinesSerializer(JsonSerializer):
         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.
+        
+        Supports append-only log optimization for large files (use_append_log=True).
         """
         path = Path(file_path)
         if not path.exists():
             raise FileNotFoundError(f"File not found: {path}")
 
+        # Check if append-only log should be used
+        perf_config = get_performance_config()
+        use_append_log = options.get("use_append_log", None)
+        if use_append_log is None:
+            if not perf_config.enable_append_log:
+                use_append_log = False
+            else:
+                # Auto-detect: use for files above threshold
+                file_size_mb = path.stat().st_size / (1024 * 1024)
+                use_append_log = file_size_mb > perf_config.append_log_threshold_mb
+
+        # Try append-only log if enabled
+        if use_append_log:
+            try:
+                from .append_only_log import AppendOnlyLog
+                log = AppendOnlyLog(path)
+                
+                # For append-only log, we need to find matching records first
+                # and apply updates, then append to log
+                # This is a simplified version - full implementation would
+                # integrate with index for O(1) lookups
+                updated = 0
+                with path.open("r", encoding="utf-8") as src:
+                    for line in src:
+                        raw = line.rstrip("\n")
+                        if not raw.strip():
+                            continue
+                        
+                        try:
+                            record = self._parser.loads(raw)
+                            if match(record):
+                                # Apply updater
+                                updated_record = updater(record)
+                                
+                                # Extract type and id for log entry
+                                type_name = record.get("@type") or record.get("type") or "Record"
+                                id_value = str(record.get("id", ""))
+                                
+                                # Append to log
+                                log.update_record(type_name, id_value, lambda x: updated_record)
+                                updated += 1
+                        except Exception:
+                            continue
+                
+                return updated
+            except Exception as e:
+                # Fall back to full rewrite if append-only log fails
+                logger.debug(f"Append-only log failed, falling back to full rewrite: {e}")
+
+        # Original full-rewrite implementation
         updated = 0
         backup = options.get("backup", True)
         ensure_ascii = options.get("ensure_ascii", False)
@@ -213,16 +285,21 @@ class JsonLinesSerializer(JsonSerializer):
                             raw = line.rstrip("\n")
                             if not raw.strip():
                                 # Preserve structural empty lines
-                                writer.write(b"\n")
+                                writer.write("\n")
                                 continue
 
-                            record = json.loads(raw)
+                            # Use pluggable parser
+                            record = self._parser.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"))
+                            # Use pluggable parser for serialization
+                            result = self._parser.dumps(record, ensure_ascii=ensure_ascii)
+                            if isinstance(result, bytes):
+                                result = result.decode("utf-8")
+                            out_line = result + "\n"
+                            writer.write(out_line)
             else:
                 # Non-atomic fallback: read + rewrite line-by-line
                 new_lines: list[str] = []
@@ -233,12 +310,17 @@ class JsonLinesSerializer(JsonSerializer):
                             new_lines.append("\n")
                             continue
 
-                        record = json.loads(raw)
+                        # Use pluggable parser
+                        record = self._parser.loads(raw)
                         if match(record):
                             record = updater(record)
                             updated += 1
 
-                        new_lines.append(json.dumps(record, ensure_ascii=ensure_ascii) + "\n")
+                        # Use pluggable parser for serialization
+                        result = self._parser.dumps(record, ensure_ascii=ensure_ascii)
+                        if isinstance(result, bytes):
+                            result = result.decode("utf-8")
+                        new_lines.append(result + "\n")
 
                 path.parent.mkdir(parents=True, exist_ok=True)
                 path.write_text("".join(new_lines), encoding="utf-8")
@@ -288,7 +370,8 @@ class JsonLinesSerializer(JsonSerializer):
                     break
 
                 if current_index >= start_index:
-                    results.append(json.loads(line))
+                    # Use pluggable parser
+                    results.append(self._parser.loads(line))
 
                 current_index += 1
 
@@ -318,7 +401,8 @@ class JsonLinesSerializer(JsonSerializer):
                 if not line:
                     continue
 
-                record = json.loads(line)
+                # Use pluggable parser
+                record = self._parser.loads(line)
                 if isinstance(record, dict) and record.get(id_field) == id_value:
                     return record
 

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.411
+Version: 0.1.0.1
 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.411
+Version: 0.1.0.1
 Generation Date: November 2, 2025
 
 TOML serialization - Configuration file format.

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.411
+Version: 0.1.0.1
 Generation Date: November 2, 2025
 
 XML serialization - Extensible Markup Language.

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.411
+Version: 0.1.0.1
 Generation Date: November 2, 2025
 
 YAML serialization - Human-readable data serialization format.

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

@@ -0,0 +1,15 @@
+"""JSON Parser abstraction layer for pluggable performance optimizations.
+
+This module provides a pluggable parser system that allows switching between
+different JSON parsing implementations (stdlib, orjson, etc.) for performance.
+"""
+
+from .base import IJsonParser
+from .registry import get_parser, get_best_available_parser, register_parser
+
+__all__ = [
+    'IJsonParser',
+    'get_parser',
+    'get_best_available_parser',
+    'register_parser',
+]

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

@@ -0,0 +1,59 @@
+"""Base JSON parser interface."""
+
+from abc import ABC, abstractmethod
+from typing import Any, Union
+
+
+class IJsonParser(ABC):
+    """Abstract JSON parser interface for pluggable implementations."""
+    
+    @abstractmethod
+    def loads(self, s: Union[str, bytes]) -> Any:
+        """
+        Parse JSON string/bytes to Python object.
+        
+        Args:
+            s: JSON string or bytes
+            
+        Returns:
+            Parsed Python object
+        """
+        pass
+    
+    @abstractmethod
+    def dumps(self, obj: Any, **kwargs) -> Union[str, bytes]:
+        """
+        Serialize Python object to JSON.
+        
+        Args:
+            obj: Python object to serialize
+            **kwargs: Serialization options (ensure_ascii, indent, etc.)
+            
+        Returns:
+            JSON string or bytes
+        """
+        pass
+    
+    @property
+    @abstractmethod
+    def parser_name(self) -> str:
+        """Parser identifier (e.g., 'standard', 'orjson')."""
+        pass
+    
+    @property
+    @abstractmethod
+    def tier(self) -> int:
+        """
+        Performance tier:
+        0 = stdlib (baseline)
+        1 = orjson (3-4x faster)
+        2 = Rust extension (5-7x faster, future)
+        3 = Pure Rust core (6-8x faster, future)
+        """
+        pass
+    
+    @property
+    @abstractmethod
+    def is_available(self) -> bool:
+        """Check if parser is available (dependencies installed)."""
+        pass

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

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

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

@@ -0,0 +1,45 @@
+"""msgspec parser - Tier 1 (Rust-based, very fast)."""
+
+from typing import Any, Union
+
+try:
+    import msgspec
+    MSGSPEC_AVAILABLE = True
+except ImportError:
+    MSGSPEC_AVAILABLE = False
+    msgspec = None
+
+from .base import IJsonParser
+
+
+class MsgspecParser(IJsonParser):
+    """msgspec parser - Tier 1 (Rust-based, very fast, close to orjson)."""
+    
+    @property
+    def parser_name(self) -> str:
+        return "msgspec"
+    
+    @property
+    def tier(self) -> int:
+        return 1
+    
+    @property
+    def is_available(self) -> bool:
+        return MSGSPEC_AVAILABLE
+    
+    def loads(self, s: Union[str, bytes]) -> Any:
+        """Parse JSON using msgspec.json.decode()."""
+        if isinstance(s, str):
+            s = s.encode("utf-8")
+        # msgspec.json.decode accepts bytes directly
+        return msgspec.json.decode(s)
+    
+    def dumps(self, obj: Any, **kwargs) -> Union[str, bytes]:
+        """Serialize JSON using msgspec.json.encode()."""
+        result = msgspec.json.encode(obj)
+        
+        # msgspec returns bytes, decode if string needed
+        if isinstance(result, bytes) and kwargs.get("return_str", False):
+            return result.decode("utf-8")
+        
+        return result

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

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

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

@@ -0,0 +1,59 @@
+"""orjson parser - Tier 1 (3-4x faster than stdlib)."""
+
+from typing import Any, Union
+
+try:
+    import orjson
+    ORJSON_AVAILABLE = True
+except ImportError:
+    ORJSON_AVAILABLE = False
+    orjson = None
+
+from .base import IJsonParser
+
+
+class OrjsonParser(IJsonParser):
+    """orjson parser - Tier 1 (3-4x faster than stdlib)."""
+    
+    @property
+    def parser_name(self) -> str:
+        return "orjson"
+    
+    @property
+    def tier(self) -> int:
+        return 1
+    
+    @property
+    def is_available(self) -> bool:
+        return ORJSON_AVAILABLE
+    
+    def loads(self, s: Union[str, bytes]) -> Any:
+        """Parse JSON using orjson.loads()."""
+        if isinstance(s, str):
+            s = s.encode("utf-8")
+        return orjson.loads(s)
+    
+    def dumps(self, obj: Any, **kwargs) -> Union[str, bytes]:
+        """Serialize JSON using orjson.dumps()."""
+        option = 0
+        
+        # orjson options
+        if not kwargs.get("ensure_ascii", True):
+            # orjson always outputs UTF-8, so ensure_ascii=False is default
+            pass
+        
+        # Handle indent (orjson doesn't support indent directly)
+        indent = kwargs.get("indent", None)
+        if indent:
+            # For pretty printing, use orjson.OPT_INDENT_2
+            option |= orjson.OPT_INDENT_2
+        
+        # Sort keys
+        if kwargs.get("sort_keys", False):
+            option |= orjson.OPT_SORT_KEYS
+        
+        result = orjson.dumps(obj, option=option)
+        
+        # Return as bytes (orjson returns bytes)
+        # Caller can decode if string is needed
+        return result

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

@@ -0,0 +1,51 @@
+"""pysimdjson parser - Tier 1 (C++ simdjson, excellent for partial parsing)."""
+
+from typing import Any, Union
+
+try:
+    import simdjson
+    PYSIMDJSON_AVAILABLE = True
+except ImportError:
+    PYSIMDJSON_AVAILABLE = False
+    simdjson = None
+
+from .base import IJsonParser
+
+
+class PysimdjsonParser(IJsonParser):
+    """pysimdjson parser - Tier 1 (C++ simdjson, excellent for partial parsing)."""
+    
+    @property
+    def parser_name(self) -> str:
+        return "pysimdjson"
+    
+    @property
+    def tier(self) -> int:
+        return 1
+    
+    @property
+    def is_available(self) -> bool:
+        return PYSIMDJSON_AVAILABLE
+    
+    def loads(self, s: Union[str, bytes]) -> Any:
+        """Parse JSON using simdjson.loads()."""
+        if isinstance(s, str):
+            s = s.encode("utf-8")
+        return simdjson.loads(s)
+    
+    def dumps(self, obj: Any, **kwargs) -> Union[str, bytes]:
+        """Serialize JSON using pysimdjson.dumps()."""
+        # pysimdjson doesn't have dumps, fallback to orjson or stdlib
+        # For now, use orjson if available, else stdlib
+        try:
+            import orjson
+            result = orjson.dumps(obj)
+            if isinstance(result, bytes) and kwargs.get("return_str", False):
+                return result.decode("utf-8")
+            return result
+        except ImportError:
+            import json
+            result = json.dumps(obj, **kwargs)
+            if isinstance(result, str) and kwargs.get("return_bytes", False):
+                return result.encode("utf-8")
+            return result

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

@@ -0,0 +1,50 @@
+"""python-rapidjson parser - Tier 1 (C++ rapidjson)."""
+
+from typing import Any, Union
+
+try:
+    import rapidjson
+    RAPIDJSON_AVAILABLE = True
+except ImportError:
+    RAPIDJSON_AVAILABLE = False
+    rapidjson = None
+
+from .base import IJsonParser
+
+
+class RapidjsonParser(IJsonParser):
+    """python-rapidjson parser - Tier 1 (C++ rapidjson)."""
+    
+    @property
+    def parser_name(self) -> str:
+        return "rapidjson"
+    
+    @property
+    def tier(self) -> int:
+        return 1
+    
+    @property
+    def is_available(self) -> bool:
+        return RAPIDJSON_AVAILABLE
+    
+    def loads(self, s: Union[str, bytes]) -> Any:
+        """Parse JSON using rapidjson.loads()."""
+        if isinstance(s, bytes):
+            s = s.decode("utf-8")
+        return rapidjson.loads(s)
+    
+    def dumps(self, obj: Any, **kwargs) -> Union[str, bytes]:
+        """Serialize JSON using rapidjson.dumps()."""
+        # rapidjson supports most stdlib kwargs
+        result = rapidjson.dumps(
+            obj,
+            ensure_ascii=kwargs.get("ensure_ascii", True),
+            indent=kwargs.get("indent", None),
+            sort_keys=kwargs.get("sort_keys", False),
+        )
+        
+        # rapidjson returns str, encode if bytes needed
+        if isinstance(result, str) and kwargs.get("return_bytes", False):
+            return result.encode("utf-8")
+        
+        return result