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

exonware/xwsystem/io/codec/contracts.py

@@ -2,27 +2,24 @@
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.409
+Version: 0.0.1.411
 Generation Date: September 04, 2025
 
 Codec module contracts - interfaces for codec operations.
 """
 
-from typing import Protocol, TypeVar, Optional, runtime_checkable
+from typing import Protocol, Optional, runtime_checkable
 from pathlib import Path
 
 from ..contracts import EncodeOptions, DecodeOptions, CodecCapability
 
-T = TypeVar('T')
-R = TypeVar('R')
-
 
 # ============================================================================
 # CODEC INTERFACES
 # ============================================================================
 
 @runtime_checkable
-class ICodec(Protocol[T, R]):
+class ICodec[T, R](Protocol):
     """
     Universal codec interface for bidirectional transformation.
     

exonware/xwsystem/io/codec/registry.py

@@ -2,13 +2,13 @@
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.409
+Version: 0.0.1.411
 Generation Date: November 04, 2025
 
 Universal Codec Registry - High-performance registry for all codec types.
 """
 
-from typing import Optional, Dict, Type, List, Union, Set, Any, Callable
+from typing import Optional, Union, Any, Callable
 from pathlib import Path
 from threading import RLock
 from functools import lru_cache
@@ -28,9 +28,9 @@ class CompoundExtensionTrie:
     
     def __init__(self):
         """Initialize the trie."""
-        self.root: Dict[str, Any] = {}
+        self.root: dict[str, Any] = {}
     
-    def insert(self, extensions: List[str], codec_id: str, priority: int = 0) -> None:
+    def insert(self, extensions: list[str], codec_id: str, priority: int = 0) -> None:
         """
         Insert a compound extension path.
         
@@ -52,7 +52,7 @@ class CompoundExtensionTrie:
         # Sort by priority (highest first)
         node['_codecs'].sort(key=lambda x: x[1], reverse=True)
     
-    def search(self, extensions: List[str]) -> List[str]:
+    def search(self, extensions: list[str]) -> list[str]:
         """
         Search for matching codec IDs.
         
@@ -104,36 +104,36 @@ class UniversalCodecRegistry:
     def __init__(self):
         """Initialize the universal codec registry."""
         # Core mappings (codec_id is always 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)]
-        self._by_alias: Dict[str, str] = {}  # alias -> codec_id (1:1 mapping)
-        self._by_type: Dict[str, Set[str]] = {}  # codec_type -> set of codec_ids
+        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)]
+        self._by_alias: dict[str, str] = {}  # alias -> codec_id (1:1 mapping)
+        self._by_type: dict[str, set[str]] = {}  # codec_type -> set of codec_ids
         
         # Magic bytes support (for content detection)
-        self._magic_bytes: Dict[bytes, List[tuple[str, int]]] = {}  # magic -> [(codec_id, priority)]
+        self._magic_bytes: dict[bytes, list[tuple[str, int]]] = {}  # magic -> [(codec_id, priority)]
         
         # Compound extension support
         self._compound_trie = CompoundExtensionTrie()
         
         # Instance cache
-        self._instances: Dict[str, ICodec] = {}
+        self._instances: dict[str, ICodec] = {}
         
         # Metadata cache
-        self._metadata: Dict[str, Dict[str, Any]] = {}
+        self._metadata: dict[str, dict[str, Any]] = {}
         
         # Priority tracking (codec_id -> priority)
-        self._priorities: Dict[str, int] = {}
+        self._priorities: dict[str, int] = {}
         
         # Thread safety
         self._lock = RLock()
     
     def register(
         self,
-        codec_class: Type[ICodec],
+        codec_class: type[ICodec],
         codec_instance: Optional[ICodec] = None,
         priority: int = 0,
-        magic_bytes: Optional[List[bytes]] = None
+        magic_bytes: Optional[list[bytes]] = None
     ) -> None:
         """
         Register a codec class or instance with optional priority and magic bytes.
@@ -510,7 +510,7 @@ class UniversalCodecRegistry:
     # MULTIPLE RESULT METHODS (All matches)
     # ========================================================================
     
-    def get_all_by_extension(self, ext: str) -> List[ICodec]:
+    def get_all_by_extension(self, ext: str) -> list[ICodec]:
         """
         Get all codecs matching an extension (sorted by priority).
         
@@ -528,7 +528,7 @@ class UniversalCodecRegistry:
             codec_list = self._by_extension.get(normalized_ext, [])
             return [self.get_by_id(codec_id) for codec_id, _ in codec_list if self.get_by_id(codec_id)]
     
-    def get_all_by_mime_type(self, mime: str) -> List[ICodec]:
+    def get_all_by_mime_type(self, mime: str) -> list[ICodec]:
         """
         Get all codecs matching a MIME type (sorted by priority).
         
@@ -542,7 +542,7 @@ class UniversalCodecRegistry:
             codec_list = self._by_mime_type.get(mime.lower(), [])
             return [self.get_by_id(codec_id) for codec_id, _ in codec_list if self.get_by_id(codec_id)]
     
-    def get_all_by_type(self, codec_type: str) -> List[ICodec]:
+    def get_all_by_type(self, codec_type: str) -> list[ICodec]:
         """
         Get all codecs of a specific type.
         
@@ -556,7 +556,7 @@ class UniversalCodecRegistry:
             codec_ids = self._by_type.get(codec_type.lower(), set())
             return [self.get_by_id(codec_id) for codec_id in codec_ids if self.get_by_id(codec_id)]
     
-    def filter_by_capability(self, cap: CodecCapability) -> List[ICodec]:
+    def filter_by_capability(self, cap: CodecCapability) -> list[ICodec]:
         """
         Get all codecs with a specific capability.
         
@@ -574,7 +574,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: Union[str, Path], codec_type: Optional[str] = None) -> list[ICodec]:
         """
         Detect all possible codecs for a file path.
         
@@ -624,7 +624,7 @@ class UniversalCodecRegistry:
     # METADATA & MANAGEMENT METHODS
     # ========================================================================
     
-    def get_metadata(self, codec_id: str) -> Optional[Dict[str, Any]]:
+    def get_metadata(self, codec_id: str) -> Optional[dict[str, Any]]:
         """
         Get full metadata for a codec.
         
@@ -637,7 +637,7 @@ class UniversalCodecRegistry:
         with self._lock:
             return self._metadata.get(codec_id.lower())
     
-    def list_types(self) -> List[str]:
+    def list_types(self) -> list[str]:
         """
         List all registered codec types.
         
@@ -647,7 +647,7 @@ class UniversalCodecRegistry:
         with self._lock:
             return list(self._by_type.keys())
     
-    def list_codecs(self, codec_type: Optional[str] = None) -> List[str]:
+    def list_codecs(self, codec_type: Optional[str] = None) -> list[str]:
         """
         List all codec IDs, optionally filtered by type.
         
@@ -663,17 +663,17 @@ class UniversalCodecRegistry:
             else:
                 return list(self._by_id.keys())
     
-    def list_extensions(self) -> List[str]:
+    def list_extensions(self) -> list[str]:
         """List all registered file extensions."""
         with self._lock:
             return list(self._by_extension.keys())
     
-    def list_mime_types(self) -> List[str]:
+    def list_mime_types(self) -> list[str]:
         """List all registered MIME types."""
         with self._lock:
             return list(self._by_mime_type.keys())
     
-    def list_aliases(self) -> List[str]:
+    def list_aliases(self) -> list[str]:
         """List all registered aliases."""
         with self._lock:
             return list(self._by_alias.keys())
@@ -702,7 +702,7 @@ class UniversalCodecRegistry:
     # BULK OPERATIONS
     # ========================================================================
     
-    def register_bulk(self, codec_classes: List[Type[ICodec]], priorities: Optional[List[int]] = None) -> int:
+    def register_bulk(self, codec_classes: list[type[ICodec]], priorities: Optional[list[int]] = None) -> int:
         """
         Register multiple codecs efficiently.
         
@@ -730,7 +730,7 @@ class UniversalCodecRegistry:
     # STATISTICS & INTROSPECTION
     # ========================================================================
     
-    def get_statistics(self) -> Dict[str, int]:
+    def get_statistics(self) -> dict[str, int]:
         """
         Get registry statistics.
         

exonware/xwsystem/io/common/__init__.py

@@ -4,7 +4,7 @@
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.409
+Version: 0.0.1.411
 Generation Date: 30-Oct-2025
 
 Common utilities shared across IO operations.

exonware/xwsystem/io/common/atomic.py

@@ -9,7 +9,7 @@ import tempfile
 import time
 from contextlib import contextmanager
 from pathlib import Path
-from typing import Any, BinaryIO, List, Optional, TextIO, Union
+from typing import Any, BinaryIO, Optional, TextIO, Union
 
 logger = logging.getLogger(__name__)
 
@@ -421,7 +421,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],
     preferred_encoding: str = "utf-8",
-    fallback_encodings: Optional[List[str]] = None,
+    fallback_encodings: Optional[list[str]] = None,
     max_size_mb: float = 100.0,
 ) -> str:
     """

exonware/xwsystem/io/common/base.py

@@ -4,7 +4,7 @@
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.409
+Version: 0.0.1.411
 Generation Date: 30-Oct-2025
 
 Base classes and utilities for common IO operations.

exonware/xwsystem/io/common/lock.py

@@ -4,7 +4,7 @@
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.409
+Version: 0.0.1.411
 Generation Date: 30-Oct-2025
 
 File locking implementation for concurrent access control.

exonware/xwsystem/io/common/watcher.py

@@ -4,7 +4,7 @@
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.409
+Version: 0.0.1.411
 Generation Date: 30-Oct-2025
 
 File watching implementation for change monitoring.
@@ -19,7 +19,7 @@ Priority 5 (Extensibility): Easy to add new event types
 import time
 import threading
 from pathlib import Path
-from typing import Dict, Any, Optional, Callable
+from typing import Any, Optional, Callable
 
 from ..contracts import IFileWatcher
 
@@ -56,8 +56,8 @@ class FileWatcher(IFileWatcher):
             poll_interval: Polling interval in seconds
         """
         self._poll_interval = poll_interval
-        self._watched: Dict[Path, Callable] = {}
-        self._file_states: Dict[Path, Dict[str, Any]] = {}
+        self._watched: dict[Path, Callable] = {}
+        self._file_states: dict[Path, dict[str, Any]] = {}
         self._running = False
         self._thread: Optional[threading.Thread] = None
     

exonware/xwsystem/io/contracts.py

@@ -2,23 +2,22 @@
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.409
+Version: 0.0.1.411
 Generation Date: September 04, 2025
 
 IO module contracts - interfaces and enums for input/output operations.
 """
 
 from abc import ABC, abstractmethod
-from typing import Any, Dict, List, Optional, Union, AsyncGenerator, BinaryIO, TextIO, Generic, TypeVar, Protocol, runtime_checkable, Callable, Iterator
+from typing import Any, Optional, Union, AsyncGenerator, BinaryIO, TextIO, Protocol, runtime_checkable, Callable, Iterator
 from typing_extensions import TypeAlias
 from pathlib import Path
 
-T = TypeVar('T')
-R = TypeVar('R')
-
 # Type aliases for codec options
-EncodeOptions: TypeAlias = Dict[str, Any]
-DecodeOptions: TypeAlias = Dict[str, Any]
+# Root cause: Migrating to Python 3.12 built-in generic syntax for consistency
+# Priority #3: Maintainability - Modern type annotations improve code clarity
+EncodeOptions: TypeAlias = dict[str, Any]
+DecodeOptions: TypeAlias = dict[str, Any]
 Serializer: TypeAlias = 'ICodec[Any, bytes]'
 Formatter: TypeAlias = 'ICodec[Any, str]'
 
@@ -305,17 +304,17 @@ class IFolder(ABC):
         pass
     
     @abstractmethod
-    def list_files(self, pattern: Optional[str] = None, recursive: bool = False) -> List[Path]:
+    def list_files(self, pattern: Optional[str] = None, recursive: bool = False) -> list[Path]:
         """List files in directory."""
         pass
     
     @abstractmethod
-    def list_directories(self, recursive: bool = False) -> List[Path]:
+    def list_directories(self, recursive: bool = False) -> list[Path]:
         """List subdirectories."""
         pass
     
     @abstractmethod
-    def walk(self) -> List[tuple[Path, List[str], List[str]]]:
+    def walk(self) -> list[tuple[Path, list[str], list[str]]]:
         """Walk directory tree."""
         pass
     
@@ -363,19 +362,19 @@ class IFolder(ABC):
     
     @staticmethod
     @abstractmethod
-    def list_files_static(path: Union[str, Path], pattern: Optional[str] = None, recursive: bool = False) -> List[Path]:
+    def list_files_static(path: Union[str, Path], pattern: Optional[str] = None, recursive: bool = False) -> list[Path]:
         """List files in directory."""
         pass
     
     @staticmethod
     @abstractmethod
-    def list_directories_static(path: Union[str, Path], recursive: bool = False) -> List[Path]:
+    def list_directories_static(path: Union[str, Path], recursive: bool = False) -> list[Path]:
         """List subdirectories."""
         pass
     
     @staticmethod
     @abstractmethod
-    def walk_static(path: Union[str, Path]) -> List[tuple[Path, List[str], List[str]]]:
+    def walk_static(path: Union[str, Path]) -> list[tuple[Path, list[str], list[str]]]:
         """Walk directory tree."""
         pass
     
@@ -818,7 +817,7 @@ class IBackupOperations(ABC):
         pass
     
     @abstractmethod
-    def list_backups(self, backup_dir: Union[str, Path]) -> List[Path]:
+    def list_backups(self, backup_dir: Union[str, Path]) -> list[Path]:
         """List available backups."""
         pass
     
@@ -850,7 +849,7 @@ class IBackupOperations(ABC):
     
     @staticmethod
     @abstractmethod
-    def list_backups_static(backup_dir: Union[str, Path]) -> List[Path]:
+    def list_backups_static(backup_dir: Union[str, Path]) -> list[Path]:
         """List available backups."""
         pass
     
@@ -1002,7 +1001,7 @@ class IFileManager(IFile, IFolder, IPath, IAtomicOperations, IBackupOperations,
 # DATA SOURCE INTERFACES (Used by file/, stream/)
 # ============================================================================
 
-class IDataSource(ABC, Generic[T]):
+class IDataSource[T](ABC):
     """Universal data source interface for various data sources."""
     
     @abstractmethod
@@ -1016,11 +1015,11 @@ class IDataSource(ABC, Generic[T]):
         pass
 
 
-class IPagedDataSource(ABC, Generic[T]):
+class IPagedDataSource[T](ABC):
     """Paged data source interface for large data sets."""
     
     @abstractmethod
-    def read_page(self, page_number: int) -> List[T]:
+    def read_page(self, page_number: int) -> list[T]:
         """Read a specific page of data."""
         pass
     
@@ -1034,7 +1033,7 @@ class IPagedDataSource(ABC, Generic[T]):
 # CODEC-INTEGRATED IO INTERFACES (Used by stream/)
 # ============================================================================
 
-class ICodecIO(ABC, Generic[T, R]):
+class ICodecIO[T, R](ABC):
     """Codec-integrated IO interface with source type T and result type R."""
     
     @abstractmethod
@@ -1048,7 +1047,7 @@ class ICodecIO(ABC, Generic[T, R]):
         pass
 
 
-class IPagedCodecIO(ABC, Generic[T, R]):
+class IPagedCodecIO[T, R](ABC):
     """Paged codec-integrated IO interface with source type T and result type R."""
     
     @abstractmethod
@@ -1134,24 +1133,24 @@ class IArchiveFormat(Protocol):
         ...
     
     @property
-    def file_extensions(self) -> List[str]:
+    def file_extensions(self) -> list[str]:
         """Supported file extensions."""
         ...
     
     @property
-    def mime_types(self) -> List[str]:
+    def mime_types(self) -> list[str]:
         """Supported MIME types."""
         ...
     
-    def create(self, files: List[Path], output: Path, **opts) -> None:
+    def create(self, files: list[Path], output: Path, **opts) -> None:
         """Create archive from files."""
         ...
     
-    def extract(self, archive: Path, output_dir: Path, members: Optional[List[str]] = None, **opts) -> List[Path]:
+    def extract(self, archive: Path, output_dir: Path, members: Optional[list[str]] = None, **opts) -> list[Path]:
         """Extract archive."""
         ...
     
-    def list_contents(self, archive: Path) -> List[str]:
+    def list_contents(self, archive: Path) -> list[str]:
         """List archive contents."""
         ...
     
@@ -1173,7 +1172,7 @@ class ICompressor(Protocol):
         ...
     
     @property
-    def file_extensions(self) -> List[str]:
+    def file_extensions(self) -> list[str]:
         """Supported file extensions."""
         ...
     
@@ -1203,12 +1202,12 @@ class IArchiveMetadata(Protocol):
         ...
     
     @property
-    def file_extensions(self) -> List[str]:
+    def file_extensions(self) -> list[str]:
         """Supported extensions."""
         ...
     
     @property
-    def mime_types(self) -> List[str]:
+    def mime_types(self) -> list[str]:
         """MIME types."""
         ...
     
@@ -1221,7 +1220,7 @@ class IArchiveMetadata(Protocol):
 # From codec/
 
 @runtime_checkable
-class ICodec(Protocol[T, R]):
+class ICodec[T, R](Protocol):
     """
     Universal codec interface for bidirectional transformation.
     
@@ -1407,7 +1406,7 @@ class IAtomicWriter(Protocol):
 # ARCHIVE INTERFACES (Dual Architecture: Codec + File)
 # ============================================================================
 
-class IArchiver(ICodec[T, bytes]):
+class IArchiver[T](ICodec[T, bytes]):
     """
     Archive codec interface - operates in MEMORY on ANY data.
     
@@ -1457,17 +1456,17 @@ class IArchiveFile(IFile):
     """
     
     @abstractmethod
-    def add_files(self, files: List[Path], **options) -> None:
+    def add_files(self, files: list[Path], **options) -> None:
         """Add files to archive (uses archiver.compress internally)."""
         pass
     
     @abstractmethod
-    def extract_to(self, dest: Path, **options) -> List[Path]:
+    def extract_to(self, dest: Path, **options) -> list[Path]:
         """Extract archive to destination (uses archiver.extract internally)."""
         pass
     
     @abstractmethod
-    def list_contents(self) -> List[str]:
+    def list_contents(self) -> list[str]:
         """List files in archive."""
         pass
     
@@ -1671,7 +1670,7 @@ class IFolderSource(Protocol):
         """Delete directory."""
         ...
     
-    def list_files(self, pattern: Optional[str] = None, recursive: bool = False) -> List[Path]:
+    def list_files(self, pattern: Optional[str] = None, recursive: bool = False) -> list[Path]:
         """List files in directory."""
         ...
 
@@ -1694,13 +1693,9 @@ class IIOManager(Protocol):
 # From stream/
 
 
-class IPagedCodecIO(ICodecIO[T, R]):
+class IPagedCodecIO[T, R](ICodecIO[T, R]):
     """
     Interface for paged codec I/O.
-    
-    Root cause fixed: Removed Protocol from class that inherits from ABC.
-    Python 3.12 doesn't allow mixing Protocol with ABC inheritance.
-    ICodecIO is already an ABC, so this class inherits ABC behavior.
     """
     
     @abstractmethod