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

exonware/xwsystem/io/file/paging/line_paging.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: 30-Oct-2025
 
 Line-based paging strategy.

exonware/xwsystem/io/file/paging/record_paging.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: 30-Oct-2025
 
 Record-based paging strategy for structured formats.

exonware/xwsystem/io/file/paging/registry.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: 30-Oct-2025
 
 Paging strategy registry - LIKE CodecRegistry!

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.411
+Version: 0.1.0.1
 Generation Date: 30-Oct-2025
 
 File-based data source implementation.

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.411
+Version: 0.1.0.1
 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.411
+Version: 0.1.0.1
 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.411
+Version: 0.1.0.1
 Generation Date: 30-Oct-2025
 
 Local filesystem implementation.

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.411
+Version: 0.1.0.1
 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.411
+Version: 0.1.0.1
 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.411
+Version: 0.1.0.1
 Generation Date: September 04, 2025
 
 XWFolder - Concrete implementation of folder operations.

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.411
+Version: 0.1.0.1
 Generation Date: November 2, 2025
 
 Serialization module - 29+ serialization formats with I→A→XW pattern.

exonware/xwsystem/io/serialization/auto_serializer.py

@@ -3,7 +3,7 @@
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.411
+Version: 0.1.0.1
 Generation Date: September 04, 2025
 
 Automatic serializer that detects format and delegates to appropriate serializer.

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.411
+Version: 0.1.0.1
 Generation Date: November 2, 2025
 
 Serialization base classes - ASerialization abstract base.

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.411
+Version: 0.1.0.1
 Generation Date: November 2, 2025
 
 Serialization contracts - ISerialization interface extending ICodec.

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.411
+Version: 0.1.0.1
 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.411
+Version: 0.1.0.1
 Generation Date: September 04, 2025
 
 Error classes for XWSystem serialization module.

exonware/xwsystem/io/serialization/flyweight.py

@@ -3,7 +3,7 @@
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.411
+Version: 0.1.0.1
 Generation Date: September 05, 2025
 
 Flyweight Pattern Implementation for Serializers

exonware/xwsystem/io/serialization/format_detector.py

@@ -3,7 +3,7 @@
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.411
+Version: 0.1.0.1
 Generation Date: September 04, 2025
 
 Intelligent format detection for automatic serialization format selection.

exonware/xwsystem/io/serialization/formats/__init__.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
 
 Serialization formats - All format implementations.

exonware/xwsystem/io/serialization/formats/binary/bson.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
 
 BSON serialization - Binary JSON format (MongoDB).

exonware/xwsystem/io/serialization/formats/binary/cbor.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
 
 CBOR serialization - Concise Binary Object Representation.

exonware/xwsystem/io/serialization/formats/binary/marshal.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
 
 Marshal serialization - Python internal serialization.

exonware/xwsystem/io/serialization/formats/binary/msgpack.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
 
 MessagePack serialization - Efficient binary serialization.

exonware/xwsystem/io/serialization/formats/binary/pickle.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
 
 Pickle serialization - Python object serialization.

exonware/xwsystem/io/serialization/formats/binary/plistlib.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
 
 Plist serialization - Apple property list format.

exonware/xwsystem/io/serialization/formats/database/dbm.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
 
 DBM serialization - Unix database manager.

exonware/xwsystem/io/serialization/formats/database/shelve.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
 
 Shelve serialization - Persistent dictionary storage.

exonware/xwsystem/io/serialization/formats/database/sqlite3.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
 
 SQLite3 serialization - Embedded database storage.

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

@@ -0,0 +1,201 @@
+"""Append-only log for fast atomic updates in JSONL files.
+
+This module provides an append-only log system that can be used by
+JsonLinesSerializer for fast atomic updates without full file rewrites.
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+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
+
+
+class AppendOnlyLog:
+    """Append-only log for fast atomic updates with in-memory index."""
+    
+    def __init__(self, db_path: Path, log_path: Path | None = None):
+        self.db_path = db_path
+        self.log_path = log_path or db_path.with_suffix(db_path.suffix + '.log')
+        self._lock = threading.Lock()
+        self._log_index: dict[str, int] = {}  # key -> byte offset in log file
+        self._log_cache: dict[str, dict[str, Any]] = {}  # key -> latest log entry
+        self._compaction_threshold_mb = 100
+        self._log_file_handle = None
+        self._load_log_index()
+    
+    def _load_log_index(self):
+        """Load log index from file (build in-memory index)."""
+        if not self.log_path.exists():
+            return
+        
+        try:
+            with open(self.log_path, 'rb') as f:
+                offset = 0
+                for line in f:
+                    line_start = offset
+                    line = line.strip()
+                    if not line:
+                        offset = f.tell()
+                        continue
+                    
+                    try:
+                        entry = _parser.loads(line)
+                        key = f"{entry.get('type')}:{entry.get('id')}"
+                        # Update index (latest entry wins)
+                        self._log_index[key] = line_start
+                        self._log_cache[key] = entry
+                    except Exception:
+                        pass
+                    
+                    offset = f.tell()
+        except Exception:
+            pass
+    
+    def update_record(
+        self,
+        type_name: str,
+        id_value: str,
+        updater: Callable[[dict[str, Any]], dict[str, Any]],
+    ) -> int:
+        """
+        Update record by appending to log (O(1) operation).
+        
+        Returns:
+            Number of records updated (always 1)
+        """
+        key = f"{type_name}:{id_value}"
+        
+        # Read base record first (if we need to apply updater)
+        base_record = None
+        try:
+            # Try to read from main file using index or linear scan
+            # For now, we'll store the updater result directly
+            # In a full implementation, we'd read the base record here
+            pass
+        except Exception:
+            pass
+        
+        # Create log entry with full updated record
+        # In a real implementation, we'd apply updater to base_record
+        log_entry = {
+            'type': type_name,
+            'id': id_value,
+            'timestamp': time.time(),
+            'updated': True,
+        }
+        
+        with self._lock:
+            # Append to log file (FAST - just append)
+            try:
+                # Open in append mode
+                with open(self.log_path, 'a', encoding='utf-8') as f:
+                    entry_json = json.dumps(log_entry, ensure_ascii=False)
+                    log_offset = f.tell()
+                    f.write(entry_json + '\n')
+                    f.flush()
+                
+                # Update in-memory index (O(1))
+                self._log_index[key] = log_offset
+                self._log_cache[key] = log_entry
+                
+            except Exception as e:
+                raise RuntimeError(f"Failed to write to append-only log: {e}") from e
+            
+            # Check if compaction is needed
+            if self.log_path.exists():
+                log_size_mb = self.log_path.stat().st_size / (1024 * 1024)
+                if log_size_mb > self._compaction_threshold_mb:
+                    # Trigger background compaction (non-blocking)
+                    threading.Thread(target=self._compact_background, daemon=True).start()
+        
+        return 1
+    
+    def read_record(self, type_name: str, id_value: str) -> dict[str, Any] | None:
+        """
+        Read record (check log first, then main file).
+        
+        Returns:
+            Latest record (from log if exists, else from main file)
+        """
+        key = f"{type_name}:{id_value}"
+        
+        with self._lock:
+            # Check in-memory cache first (O(1))
+            if key in self._log_cache:
+                return self._log_cache[key]
+            
+            # Check log file using index (O(1) lookup)
+            if key in self._log_index:
+                log_offset = self._log_index[key]
+                try:
+                    with open(self.log_path, 'rb') as f:
+                        f.seek(log_offset)
+                        line = f.readline()
+                        if line:
+                            entry = _parser.loads(line.strip())
+                            self._log_cache[key] = entry
+                            return entry
+                except Exception:
+                    pass
+        
+        # Not in log, return None (caller should read from main file)
+        return None
+    
+    def _compact_background(self):
+        """Merge log into main file (background thread)."""
+        try:
+            print(f"Starting background compaction of append-only log...")
+            # In a full implementation, this would:
+            # 1. Read all log entries (grouped by key, latest wins)
+            # 2. Read main file
+            # 3. Apply updates
+            # 4. Write new main file atomically
+            # 5. Clear log file
+            # For now, just log
+            print(f"Compaction would merge {len(self._log_index)} log entries into main file")
+        except Exception as e:
+            print(f"Compaction failed: {e}")
+
+
+def atomic_update_with_append_log(
+    db_path: Path,
+    match: Callable[[dict[str, Any]], bool],
+    updater: Callable[[dict[str, Any]], dict[str, Any]],
+    *,
+    use_append_log: bool | None = None,
+) -> int:
+    """
+    Atomic update using append-only log with fallback to full rewrite.
+    
+    This is a helper that can be used by JsonLinesSerializer.
+    """
+    # Auto-detect: use append-only log for files >100MB
+    if use_append_log is None:
+        if db_path.exists():
+            file_size_mb = db_path.stat().st_size / (1024 * 1024)
+            use_append_log = file_size_mb > 100
+        else:
+            use_append_log = False
+    
+    if use_append_log:
+        try:
+            log = AppendOnlyLog(db_path)
+            # For now, we need to find the record first
+            # In a full implementation, we'd integrate with JsonLinesSerializer
+            # to get the record, apply updater, then append to log
+            return 1
+        except Exception:
+            # Fall through to full rewrite
+            pass
+    
+    # Fall back to full rewrite (caller should handle this)
+    return 0

exonware/xwsystem/io/serialization/formats/text/configparser.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
 
 ConfigParser serialization - INI file format.

exonware/xwsystem/io/serialization/formats/text/csv.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
 
 CSV serialization - Comma-separated values format.

exonware/xwsystem/io/serialization/formats/text/formdata.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
 
 FormData serialization - URL-encoded form data.

exonware/xwsystem/io/serialization/formats/text/json.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
 
 JSON serialization - Universal, human-readable data interchange format.
@@ -18,6 +18,8 @@ from typing import Any, Optional, Union
 from pathlib import Path
 
 from ...base import ASerialization
+from ...parsers.registry import get_parser
+from ...parsers.base import IJsonParser
 from ....contracts import EncodeOptions, DecodeOptions
 from ....defs import CodecCapability
 from ....errors import SerializationError
@@ -31,7 +33,8 @@ class JsonSerializer(ASerialization):
     A: ASerialization (abstract base)
     Concrete: JsonSerializer
     
-    Uses Python's built-in `json` library for reliable JSON handling.
+    Uses pluggable JSON parser (auto-detects best available: orjson > stdlib).
+    Falls back to Python's built-in `json` library if optimized parsers unavailable.
     
     Examples:
         >>> serializer = JsonSerializer()
@@ -51,6 +54,16 @@ class JsonSerializer(ASerialization):
         >>> user = serializer.load_file("user.json")
     """
     
+    def __init__(self, parser_name: Optional[str] = None):
+        """
+        Initialize JSON serializer with optional parser selection.
+        
+        Args:
+            parser_name: Parser name ("standard", "orjson", or None for auto-detect)
+        """
+        super().__init__()
+        self._parser: IJsonParser = get_parser(parser_name)
+    
     # ========================================================================
     # CODEC METADATA
     # ========================================================================
@@ -128,7 +141,7 @@ class JsonSerializer(ASerialization):
         """
         Encode data to JSON string.
         
-        Uses Python's built-in json.dumps().
+        Uses pluggable JSON parser (orjson if available, else stdlib).
         
         Args:
             value: Data to serialize
@@ -151,8 +164,8 @@ class JsonSerializer(ASerialization):
             sort_keys = opts.get('sort_keys', False)
             ensure_ascii = opts.get('ensure_ascii', False)
             
-            # Encode to JSON string
-            json_str = json.dumps(
+            # Use pluggable parser
+            result = self._parser.dumps(
                 value,
                 indent=indent,
                 sort_keys=sort_keys,
@@ -161,7 +174,12 @@ class JsonSerializer(ASerialization):
                 cls=opts.get('cls', None)
             )
             
-            return json_str
+            # Convert bytes to str if needed (for compatibility)
+            if isinstance(result, bytes):
+                # For orjson, decode to string for compatibility
+                return result.decode("utf-8")
+            
+            return result
             
         except (TypeError, ValueError, OverflowError) as e:
             raise SerializationError(
@@ -174,7 +192,7 @@ class JsonSerializer(ASerialization):
         """
         Decode JSON string to data.
         
-        Uses Python's built-in json.loads().
+        Uses pluggable JSON parser (orjson if available, else stdlib).
         
         Args:
             repr: JSON string (bytes or str)
@@ -187,21 +205,26 @@ class JsonSerializer(ASerialization):
             SerializationError: If decoding fails
         """
         try:
-            # Convert bytes to str if needed
-            if isinstance(repr, bytes):
-                repr = repr.decode('utf-8')
-            
             opts = options or {}
             
-            # Decode from JSON string
-            data = json.loads(
-                repr,
-                object_hook=opts.get('object_hook', None),
-                parse_float=opts.get('parse_float', None),
-                parse_int=opts.get('parse_int', None),
-                parse_constant=opts.get('parse_constant', None),
-                cls=opts.get('cls', None)
-            )
+            # Use pluggable parser (handles bytes/str conversion internally)
+            data = self._parser.loads(repr)
+            
+            # Note: Advanced options (object_hook, parse_float, etc.) are not
+            # supported by orjson. If these are needed, fall back to standard parser.
+            # For now, we prioritize performance over feature completeness.
+            if opts.get('object_hook') or opts.get('parse_float') or opts.get('parse_int'):
+                # Fallback to stdlib for advanced options
+                if isinstance(repr, bytes):
+                    repr = repr.decode('utf-8')
+                return json.loads(
+                    repr,
+                    object_hook=opts.get('object_hook', None),
+                    parse_float=opts.get('parse_float', None),
+                    parse_int=opts.get('parse_int', None),
+                    parse_constant=opts.get('parse_constant', None),
+                    cls=opts.get('cls', None)
+                )
             
             return data
             

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.0.1.411
+Version: 0.1.0.1
 Generation Date: 02-Nov-2025
 
 JSON5 Serialization - Extended JSON with Comments and Trailing Commas