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

exonware/xwsystem/io/codec/__init__.py

@@ -1,10 +1,11 @@
 #!/usr/bin/env python3
+#exonware/xwsystem/src/exonware/xwsystem/io/codec/__init__.py
 # exonware/xwsystem/io/codec/__init__.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.3
 Generation Date: October 30, 2025
 
 Universal Codec Abstraction for eXonware.
@@ -71,6 +72,7 @@ from ..contracts import (
     DecodeOptions,
     ICodecMetadata,
 )
+from .contracts import IFormatConfig
 from .base import (
     ACodec,
     MediaKey,
@@ -167,6 +169,7 @@ __all__ = [
     'EncodeOptions',
     'DecodeOptions',
     'ICodecMetadata',
+    'IFormatConfig',
     
     # Capabilities
     'CodecCapability',
@@ -193,4 +196,3 @@ __all__ = [
     'DecodeError',
     'CodecNotFoundError',
 ]
-

exonware/xwsystem/io/codec/base.py

@@ -1,17 +1,18 @@
 #!/usr/bin/env python3
+#exonware/xwsystem/src/exonware/xwsystem/io/codec/base.py
 # exonware/xwsystem/io/codec/base.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.3
 Generation Date: October 30, 2025
 
 Base classes, registry, adapters, and helper functions for codec system.
 """
 
 from __future__ import annotations
-from typing import Optional, Any, IO, Union
+from typing import Optional, Any, IO
 # Root cause: Migrating to Python 3.12 built-in generic syntax for consistency
 # Priority #3: Maintainability - Modern type annotations improve code clarity
 from pathlib import Path
@@ -415,7 +416,9 @@ class ACodec[T, R](ICodec[T, R], ICodecMetadata, ABC):
                         self._get_data_depth(v, cache, visited, current_depth + 1) - current_depth - 1
                         for v in data.values()
                     ]
-                    max_relative_depth = max(child_depths) if child_depths else 1
+                    # Get max relative depth from children (how deep from this dict)
+                    # Add 1 for the dict itself
+                    max_relative_depth = max(child_depths) + 1 if child_depths else 1
                 else:
                     max_relative_depth = 1  # Empty dict still counts as one level
             
@@ -425,7 +428,9 @@ class ACodec[T, R](ICodec[T, R], ICodecMetadata, ABC):
                         self._get_data_depth(item, cache, visited, current_depth + 1) - current_depth - 1
                         for item in data
                     ]
-                    max_relative_depth = max(child_depths) if child_depths else 1
+                    # Get max relative depth from children (how deep from this list)
+                    # Add 1 for the list itself
+                    max_relative_depth = max(child_depths) + 1 if child_depths else 1
                 else:
                     max_relative_depth = 1  # Empty list still counts as one level
             
@@ -435,7 +440,9 @@ class ACodec[T, R](ICodec[T, R], ICodecMetadata, ABC):
                     self._get_data_depth(v, cache, visited, current_depth + 1) - current_depth - 1
                     for v in vars(data).values()
                 ]
-                max_relative_depth = max(child_depths) if child_depths else 0
+                # Get max relative depth from children (how deep from this object)
+                # Add 1 for the object itself
+                max_relative_depth = max(child_depths) + 1 if child_depths else 1
             
             # Cache the result (maximum relative depth from this object)
             cache[obj_id] = max_relative_depth
@@ -507,7 +514,7 @@ class ACodec[T, R](ICodec[T, R], ICodecMetadata, ABC):
         self, 
         data: Any, 
         operation: str = "encode",
-        file_path: Optional[Union[str, Path]] = None,
+        file_path: Optional[str | Path] = None,
         skip_size_check: bool = False
     ) -> None:
         """
@@ -536,7 +543,7 @@ class ACodec[T, R](ICodec[T, R], ICodecMetadata, ABC):
         self._depth_cache.clear()
         self._size_cache.clear()
         
-        # ALWAYS check depth - this prevents infinite recursion which is the real security issue
+        # Check depth - prevents infinite recursion which is the security issue
         depth = self._get_data_depth(data)
         if depth > self._max_depth:
             raise SerializationError(
@@ -558,7 +565,7 @@ class ACodec[T, R](ICodec[T, R], ICodecMetadata, ABC):
                 if path_obj.exists():
                     file_size_mb = path_obj.stat().st_size / (1024 * 1024)
                     # If file is > 1GB, assume it's meant to be large and skip size validation
-                    # Large files should use lazy loading/streaming features
+                    # Large files use lazy loading/streaming features
                     if file_size_mb > 1024:  # 1GB threshold
                         return  # Skip size check for large files
             except (OSError, ValueError):
@@ -576,7 +583,7 @@ class ACodec[T, R](ICodec[T, R], ICodecMetadata, ABC):
             )
     
     # ========================================================================
-    # CORE METHODS (Must implement in subclasses)
+    # CORE METHODS (Implement in subclasses)
     # ========================================================================
     
     @abstractmethod
@@ -590,7 +597,7 @@ class ACodec[T, R](ICodec[T, R], ICodecMetadata, ABC):
         pass
     
     # ========================================================================
-    # METADATA PROPERTIES (Must implement in subclasses)
+    # METADATA PROPERTIES (Implement in subclasses)
     # ========================================================================
     
     @property
@@ -689,8 +696,8 @@ class ACodec[T, R](ICodec[T, R], ICodecMetadata, ABC):
             if isinstance(self._get_repr_type_hint(), str):
                 # Text codec, decode bytes to str
                 repr = repr.decode('utf-8')
-        except:
-            # Fall back to text
+        except (OSError, UnicodeDecodeError, FileNotFoundError, PermissionError):
+            # Fall back to text - catch specific exceptions only
             repr = path.read_text(encoding='utf-8')
         
         return self.decode(repr, options=opts or None)
@@ -879,4 +886,3 @@ class SerializerToFormatter[T]:
         """Decode from string via bytes."""
         data = repr.encode(self._encoding, errors=self._errors)
         return self._serializer.decode(data, options=options)
-

exonware/xwsystem/io/codec/contracts.py

@@ -1,14 +1,15 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/codec/contracts.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.3
 Generation Date: September 04, 2025
 
 Codec module contracts - interfaces for codec operations.
 """
 
-from typing import Protocol, Optional, runtime_checkable
+from typing import Protocol, Optional, runtime_checkable, Any
 from pathlib import Path
 
 from ..contracts import EncodeOptions, DecodeOptions, CodecCapability
@@ -211,3 +212,59 @@ class ICodecMetadata(Protocol):
         """
         ...
 
+
+@runtime_checkable
+class IFormatConfig(Protocol):
+    """
+    Interface for format configuration.
+    
+    This interface represents configuration for codec/format selection
+    and is used across xwsystem for format-aware operations. It provides
+    a standardized way to specify and validate codec/format configurations
+    with integration to the codec registry.
+    
+    Originally defined in xwstorage, moved to xwsystem.io.codec as it
+    is a general-purpose codec configuration abstraction.
+    """
+    
+    @property
+    def format_type(self) -> str:
+        """
+        Get the format type identifier (codec_id).
+        
+        Returns:
+            Format type identifier (e.g., "json", "yaml", "xml")
+        """
+        ...
+    
+    @property
+    def codec_id(self) -> str:
+        """
+        Get the codec identifier from xwsystem codec registry.
+        
+        This should match a codec_id in the UniversalCodecRegistry.
+        
+        Returns:
+            Codec identifier (typically same as format_type)
+        """
+        ...
+    
+    def to_dict(self) -> dict[str, Any]:
+        """
+        Convert configuration to dictionary.
+        
+        Returns:
+            Dictionary representation of the format configuration
+        """
+        ...
+    
+    def validate(self) -> bool:
+        """
+        Validate format configuration.
+        
+        Checks if the codec_id is available in the xwsystem codec registry.
+        
+        Returns:
+            True if format is valid and available in codec registry
+        """
+        ...

exonware/xwsystem/io/codec/registry.py

@@ -1,14 +1,15 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/codec/registry.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 04, 2025
 
 Universal Codec Registry - High-performance registry for all codec types.
 """
 
-from typing import Optional, Union, Any, Callable
+from typing import Optional, Any, Callable
 from pathlib import Path
 from threading import RLock
 from functools import lru_cache
@@ -103,7 +104,7 @@ class UniversalCodecRegistry:
     
     def __init__(self):
         """Initialize the universal codec registry."""
-        # Core mappings (codec_id is always lowercase)
+        # Core mappings (codec_id is lowercase)
         self._by_id: dict[str, type[ICodec]] = {}
         self._by_extension: dict[str, list[tuple[str, int]]] = {}  # ext -> [(codec_id, priority)]
         self._by_mime_type: dict[str, list[tuple[str, int]]] = {}  # mime -> [(codec_id, priority)]
@@ -324,7 +325,11 @@ class UniversalCodecRegistry:
     
     def get_by_id(self, codec_id: str) -> Optional[ICodec]:
         """
-        Get codec by ID (unique lookup).
+        Get codec by ID with O(1) caching (unique lookup).
+        
+        OPTIMIZED: Lockless fast path for cached instances.
+        First call: validates and instantiates (10-100μs)
+        Subsequent calls: cache lookup (< 1μs) ✅
         
         Args:
             codec_id: Codec identifier
@@ -332,10 +337,15 @@ class UniversalCodecRegistry:
         Returns:
             Codec instance or None
         """
+        codec_id_lower = codec_id.lower()
+        
+        # FAST PATH: Lockless cache check (O(1))
+        if codec_id_lower in self._instances:
+            return self._instances[codec_id_lower]  # O(1) cache hit! ✅
+        
+        # SLOW PATH: Need to instantiate (acquire lock)
         with self._lock:
-            codec_id_lower = codec_id.lower()
-            
-            # Check instance cache first
+            # Double-check cache after acquiring lock
             if codec_id_lower in self._instances:
                 return self._instances[codec_id_lower]
             
@@ -344,13 +354,19 @@ class UniversalCodecRegistry:
             if not codec_class:
                 return None
             
-            instance = codec_class()
-            self._instances[codec_id_lower] = instance
-            return instance
+            try:
+                instance = codec_class()
+                self._instances[codec_id_lower] = instance
+                return instance
+            except Exception:
+                # Failed to instantiate - don't cache the failure
+                return None
     
     def get_by_extension(self, ext: str) -> Optional[ICodec]:
         """
-        Get codec by extension (highest priority match).
+        Get codec by extension with O(1) caching (highest priority match).
+        
+        OPTIMIZED: Reduced lock contention by doing normalization outside lock.
         
         Args:
             ext: File extension (with or without dot)
@@ -358,18 +374,22 @@ class UniversalCodecRegistry:
         Returns:
             Highest priority codec instance or None
         """
+        # Normalize outside lock (no shared state access)
+        normalized_ext = ext.lower()
+        if not normalized_ext.startswith('.'):
+            normalized_ext = f'.{normalized_ext}'
+        
+        # Quick lookup with lock
         with self._lock:
-            normalized_ext = ext.lower()
-            if not normalized_ext.startswith('.'):
-                normalized_ext = f'.{normalized_ext}'
-            
             codec_list = self._by_extension.get(normalized_ext, [])
             if not codec_list:
                 return None
             
             # Return highest priority (first in sorted list)
             codec_id = codec_list[0][0]
-            return self.get_by_id(codec_id)
+        
+        # Get instance outside lock (uses lockless cache)
+        return self.get_by_id(codec_id)
     
     def get_by_mime_type(self, mime: str) -> Optional[ICodec]:
         """
@@ -407,7 +427,7 @@ class UniversalCodecRegistry:
             return self.get_by_id(codec_id)
     
     @lru_cache(maxsize=256)
-    def detect(self, path: Union[str, Path], codec_type: Optional[str] = None) -> Optional[ICodec]:
+    def detect(self, path: str | Path, codec_type: Optional[str] = None) -> Optional[ICodec]:
         """
         Auto-detect codec from file path (best match with optional type filter).
         
@@ -429,7 +449,7 @@ class UniversalCodecRegistry:
         with self._lock:
             return self._detect_internal(path, codec_type)
     
-    def _detect_internal(self, path: Union[str, Path], codec_type: Optional[str] = None) -> Optional[ICodec]:
+    def _detect_internal(self, path: str | Path, codec_type: Optional[str] = None) -> Optional[ICodec]:
         """Internal detection implementation (not cached)."""
         path_obj = Path(path)
         
@@ -574,7 +594,7 @@ class UniversalCodecRegistry:
                     results.append(codec)
             return results
     
-    def detect_all(self, path: Union[str, Path], codec_type: Optional[str] = None) -> list[ICodec]:
+    def detect_all(self, path: str | Path, codec_type: Optional[str] = None) -> list[ICodec]:
         """
         Detect all possible codecs for a file path.
         
@@ -732,10 +752,10 @@ class UniversalCodecRegistry:
     
     def get_statistics(self) -> dict[str, int]:
         """
-        Get registry statistics.
+        Get registry statistics including cache performance.
         
         Returns:
-            Dictionary with counts of registered items
+            Dictionary with counts of registered items and cache stats
         """
         with self._lock:
             return {
@@ -746,6 +766,32 @@ class UniversalCodecRegistry:
                 'types': len(self._by_type),
                 'magic_bytes': len(self._magic_bytes),
                 'cached_instances': len(self._instances),
+                'cache_hit_rate': len(self._instances) / max(1, len(self._by_id)),  # % of codecs cached
+                'detect_cache_info': self.detect.cache_info()._asdict(),  # LRU cache stats
+            }
+    
+    def get_cache_stats(self) -> dict:
+        """
+        Get detailed cache statistics for performance monitoring.
+        
+        Returns:
+            Dictionary with cache performance metrics
+        """
+        with self._lock:
+            detect_info = self.detect.cache_info()
+            return {
+                'instance_cache': {
+                    'size': len(self._instances),
+                    'max_codecs': len(self._by_id),
+                    'hit_rate': len(self._instances) / max(1, len(self._by_id)),
+                },
+                'detect_cache': {
+                    'hits': detect_info.hits,
+                    'misses': detect_info.misses,
+                    'size': detect_info.currsize,
+                    'max_size': detect_info.maxsize,
+                    'hit_rate': detect_info.hits / max(1, detect_info.hits + detect_info.misses),
+                }
             }
 
 

exonware/xwsystem/io/common/__init__.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: 30-Oct-2025
 
 Common utilities shared across IO operations.

exonware/xwsystem/io/common/atomic.py

@@ -1,15 +1,17 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/common/atomic.py
 """
 Atomic file operations to prevent data corruption during writes.
 """
 
 import logging
 import os
+import platform
 import shutil
 import tempfile
 import time
 from contextlib import contextmanager
 from pathlib import Path
-from typing import Any, BinaryIO, Optional, TextIO, Union
+from typing import Any, BinaryIO, Optional, TextIO
 
 logger = logging.getLogger(__name__)
 
@@ -31,11 +33,11 @@ class AtomicFileWriter:
 
     def __init__(
         self,
-        target_path: Union[str, Path],
+        target_path: str | Path,
         mode: str = "w",
         encoding: Optional[str] = "utf-8",
         backup: bool = False,
-        temp_dir: Optional[Union[str, Path]] = None,
+        temp_dir: Optional[str | Path] = None,
     ):
         """
         Initialize atomic file writer.
@@ -55,11 +57,11 @@ class AtomicFileWriter:
 
         self.temp_path: Optional[Path] = None
         self.backup_path: Optional[Path] = None
-        self.file_handle: Optional[Union[BinaryIO, TextIO]] = None
+        self.file_handle: Optional[BinaryIO | TextIO] = None
         self._committed = False
         self._started = False
 
-    def __enter__(self) -> Union[BinaryIO, TextIO]:
+    def __enter__(self) -> BinaryIO | TextIO:
         """Context manager entry - create temporary file."""
         return self.start()
 
@@ -73,7 +75,7 @@ class AtomicFileWriter:
             self.rollback()
         return False  # Don't suppress exceptions
 
-    def start(self) -> Union[BinaryIO, TextIO]:
+    def start(self) -> BinaryIO | TextIO:
         """
         Start the atomic write operation.
 
@@ -150,8 +152,8 @@ class AtomicFileWriter:
                 logger.warning(f"Temporary file is empty: {self.temp_path}")
 
             # Atomic move to target location
-            # On Windows, need to remove target first if it exists
-            if os.name == "nt" and self.target_path.exists():
+            # On Windows, need to remove target first if it exists (Windows filesystem limitation)
+            if platform.system() == 'Windows' and self.target_path.exists():
                 self.target_path.unlink()
 
             # Perform the atomic move
@@ -250,11 +252,11 @@ class AtomicFileWriter:
 
 @contextmanager
 def atomic_write(
-    target_path: Union[str, Path],
+    target_path: str | Path,
     mode: str = "w",
     encoding: Optional[str] = "utf-8",
     backup: bool = True,
-    temp_dir: Optional[Union[str, Path]] = None,
+    temp_dir: Optional[str | Path] = None,
 ):
     """
     Context manager for atomic file writing.
@@ -286,10 +288,11 @@ def atomic_write(
 
 
 def safe_write_text(
-    target_path: Union[str, Path],
+    target_path: str | Path,
     content: str,
     encoding: str = "utf-8",
     backup: bool = True,
+    append: bool = False,
 ) -> None:
     """
     Safely write text content to a file atomically.
@@ -300,12 +303,22 @@ def safe_write_text(
         encoding: Text encoding
         backup: Whether to create backup
     """
+    target_path = Path(target_path)
+    target_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # For append operations, atomic write semantics don't apply cleanly (we are not replacing the file).
+    # Tests and typical usage protect append with a lock (see FileLock usage in core tests).
+    if append:
+        with open(target_path, "a", encoding=encoding) as f:
+            f.write(content)
+        return
+
     with atomic_write(target_path, "w", encoding=encoding, backup=backup) as f:
         f.write(content)
 
 
 def safe_write_bytes(
-    target_path: Union[str, Path], content: bytes, backup: bool = True
+    target_path: str | Path, content: bytes, backup: bool = True
 ) -> None:
     """
     Safely write binary content to a file atomically.
@@ -320,7 +333,7 @@ def safe_write_bytes(
 
 
 def safe_read_text(
-    file_path: Union[str, Path], encoding: str = "utf-8", max_size_mb: float = 100.0
+    file_path: str | Path, encoding: str = "utf-8", max_size_mb: float = 100.0
 ) -> str:
     """
     Safely read text content from a file with size validation.
@@ -372,7 +385,7 @@ def safe_read_text(
         raise FileOperationError(f"IOError reading file '{file_path}': {e}") from e
 
 
-def safe_read_bytes(file_path: Union[str, Path], max_size_mb: float = 100.0) -> bytes:
+def safe_read_bytes(file_path: str | Path, max_size_mb: float = 100.0) -> bytes:
     """
     Safely read binary content from a file with size validation.
 
@@ -419,7 +432,7 @@ def safe_read_bytes(file_path: Union[str, Path], max_size_mb: float = 100.0) ->
 
 
 def safe_read_with_fallback(
-    file_path: Union[str, Path],
+    file_path: str | Path,
     preferred_encoding: str = "utf-8",
     fallback_encodings: Optional[list[str]] = None,
     max_size_mb: float = 100.0,
@@ -442,7 +455,7 @@ def safe_read_with_fallback(
     if fallback_encodings is None:
         fallback_encodings = ["latin1", "cp1252", "iso-8859-1"]
 
-    # Try preferred encoding first
+    # Try encoding first
     try:
         return safe_read_text(file_path, preferred_encoding, max_size_mb)
     except FileOperationError as e:

exonware/xwsystem/io/common/base.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: 30-Oct-2025
 
 Base classes and utilities for common IO operations.
@@ -21,8 +21,10 @@ Priority 4 (Performance): Efficient operations
 Priority 5 (Extensibility): Ready for new utilities
 """
 
+from __future__ import annotations
+
 from abc import ABC, abstractmethod
-from typing import Optional, Union, Callable
+from typing import Optional, Callable
 from pathlib import Path
 
 from ..contracts import IAtomicWriter, IPathValidator, IFileWatcher, IFileLock
@@ -43,7 +45,7 @@ class AAtomicWriter(IAtomicWriter, ABC):
     Provides skeletal implementation for atomic write operations.
     """
     
-    def __init__(self, path: Union[str, Path], mode: AtomicMode = AtomicMode.WRITE_BACKUP):
+    def __init__(self, path: str | Path, mode: AtomicMode = AtomicMode.WRITE_BACKUP):
         """Initialize atomic writer."""
         self.path = Path(path)
         self.mode = mode
@@ -55,7 +57,7 @@ class AAtomicWriter(IAtomicWriter, ABC):
         """Write data atomically."""
         pass
     
-    def __enter__(self) -> 'AAtomicWriter':
+    def __enter__(self) -> AAtomicWriter:
         """Enter context manager."""
         return self
     
@@ -77,18 +79,18 @@ class APathValidator(IPathValidator, ABC):
         self.security_level = security_level
     
     @abstractmethod
-    def validate_path(self, path: Union[str, Path]) -> bool:
+    def validate_path(self, path: str | Path) -> bool:
         """Validate path safety."""
         pass
     
-    def is_safe_path(self, path: Union[str, Path]) -> bool:
+    def is_safe_path(self, path: str | Path) -> bool:
         """Check if path is safe to use."""
         try:
             return self.validate_path(path)
         except Exception:
             return False
     
-    def normalize_path(self, path: Union[str, Path]) -> Path:
+    def normalize_path(self, path: str | Path) -> Path:
         """Normalize and resolve path."""
         return Path(path).resolve()
 
@@ -134,7 +136,7 @@ class AFileLock(IFileLock, ABC):
     Provides common locking logic.
     """
     
-    def __init__(self, path: Union[str, Path], mode: LockMode = LockMode.EXCLUSIVE):
+    def __init__(self, path: str | Path, mode: LockMode = LockMode.EXCLUSIVE):
         """Initialize lock."""
         self.path = Path(path)
         self.mode = mode
@@ -154,7 +156,7 @@ class AFileLock(IFileLock, ABC):
         """Check if locked."""
         return self._locked
     
-    def __enter__(self) -> 'AFileLock':
+    def __enter__(self) -> AFileLock:
         """Context manager entry."""
         self.acquire()
         return self
@@ -162,4 +164,3 @@ class AFileLock(IFileLock, ABC):
     def __exit__(self, exc_type, exc_val, exc_tb) -> None:
         """Context manager exit."""
         self.release()
-