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

exonware/xwsystem/io/data_operations.py

@@ -16,7 +16,7 @@ lazy, paged, and atomic access features without re-implementing I/O logic.
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.4
 Generation Date: 15-Dec-2025
 """
 
@@ -28,6 +28,8 @@ from typing import Any, Callable, Optional
 from abc import ABC, abstractmethod
 import json
 import os
+import platform
+import sys
 import tempfile
 import multiprocessing as mp
 from concurrent.futures import ProcessPoolExecutor, as_completed
@@ -55,11 +57,8 @@ def _process_chunk_worker(args: tuple[int, int, int, str, str, str | None, int |
     lines_processed = 0
     
     # Import parser in worker process (can't pickle serializer)
-    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()
     
     try:
         with open(file_path_str, "rb") as f:
@@ -99,7 +98,7 @@ def _process_chunk_worker(args: tuple[int, int, int, str, str, str | None, int |
                             id_val = str(obj[id_field_arg])
                             chunk_id_index[id_val] = line_idx
                     except Exception:
-                        # Skip invalid lines (best-effort indexing)
+                        # Skip invalid lines (fallback indexing)
                         pass
                 
                 lines_processed += 1
@@ -353,7 +352,7 @@ class NDJSONDataOperations(ADataOperations):
                 try:
                     tmp_path.unlink()
                 except OSError:
-                    # Best-effort cleanup; do not mask original error.
+                    # Cleanup attempt; do not mask original error.
                     logger.debug("Failed to cleanup temp file %s", tmp_path)
 
     # ------------------------------------------------------------------
@@ -433,11 +432,8 @@ class NDJSONDataOperations(ADataOperations):
         mtime = target.stat().st_mtime
 
         # Cache parser instance (matches example code pattern)
-        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()
 
         offset = 0
         with target.open("rb") as f:
@@ -461,7 +457,7 @@ class NDJSONDataOperations(ADataOperations):
                                 if max_id_index is None or len(id_index) < max_id_index:
                                     id_index[id_val] = line_no
                     except Exception:
-                        # Index should be best-effort and robust to bad lines.
+                        # Index is robust to bad lines.
                         # Skip invalid lines silently for performance
                         pass
 
@@ -492,9 +488,14 @@ class NDJSONDataOperations(ADataOperations):
             # ProcessPoolExecutor max_workers limit is 61 on Windows
             file_size_mb = file_path.stat().st_size / 1_048_576  # 1024 * 1024
             calculated_workers = int(file_size_mb / 10)  # 1 worker per 10MB
-            # Cap at 61 (ProcessPoolExecutor limit) or CPU count, whichever is higher
             cpu_count = mp.cpu_count()
-            num_workers = max(cpu_count, min(61, calculated_workers))
+            # Windows has a hard limit of 61 workers for ProcessPoolExecutor
+            # Unix/Linux systems have no such limit
+            # Use Python's native platform module for cross-platform detection
+            if platform.system() == 'Windows':
+                num_workers = max(cpu_count, min(61, calculated_workers))
+            else:
+                num_workers = max(cpu_count, calculated_workers)
         
         file_size = file_path.stat().st_size
         chunk_size_bytes = chunk_size_mb * 1_048_576  # 1024 * 1024
@@ -559,10 +560,10 @@ class NDJSONDataOperations(ADataOperations):
         
         # Merge results (process in order by chunk_id)
         if build_line_offsets:
-            # Optimize: Pre-calculate total size for better memory allocation
+            # Optimize: Pre-calculate total size for memory allocation
             total_offsets = sum(len(offsets) if offsets else 0 for offsets, _ in chunk_results_dict.values())
             if total_offsets > 0:
-                # Pre-allocate list for better performance
+                # Pre-allocate list for performance
                 line_offsets = [0] * total_offsets
                 current_idx = 0
             else:
@@ -742,5 +743,3 @@ __all__ = [
     "ADataOperations",
     "NDJSONDataOperations",
 ]
-
-

exonware/xwsystem/io/defs.py

@@ -1,8 +1,9 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/defs.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.4
 Generation Date: 30-Oct-2025
 
 IO module definitions - ALL enums and types in ONE place.
@@ -117,7 +118,7 @@ class PagingMode(Enum):
     LINE = "line"                # Page by line counts
     RECORD = "record"            # Page by record boundaries
     SMART = "smart"              # Adaptive paging
-    AUTO = "auto"                # Auto-detect best strategy
+    AUTO = "auto"                # Auto-detect strategy
 
 
 # From file
@@ -221,7 +222,7 @@ class CompressionLevel(Enum):
     """Compression level presets."""
     FAST = 1                # Fastest compression
     BALANCED = 6            # Balance speed/size
-    BEST = 9                # Best compression
+    BEST = 9                # Maximum compression
 
 
 

exonware/xwsystem/io/errors.py

@@ -1,8 +1,9 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/errors.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri  
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.4
 Generation Date: 30-Oct-2025
 
 IO module errors - ALL exceptions in ONE place.
@@ -10,7 +11,7 @@ IO module errors - ALL exceptions in ONE place.
 Consolidated from all submodules for maintainability.
 """
 
-from typing import Any, Optional, Union
+from typing import Any, Optional
 from pathlib import Path
 
 

exonware/xwsystem/io/facade.py

@@ -1,8 +1,9 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/facade.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.4
 Generation Date: September 04, 2025
 
 XWIO - Main facade for all I/O operations (MANDATORY facade pattern).
@@ -10,12 +11,14 @@ XWIO - Main facade for all I/O operations (MANDATORY facade pattern).
 This is the primary entry point for the IO module, following GUIDELINES_DEV.md.
 """
 
+from __future__ import annotations
+
 import os
 import shutil
 import tempfile
 import time
 from pathlib import Path
-from typing import Any, Optional, Union, BinaryIO, TextIO
+from typing import Any, Optional, BinaryIO, TextIO
 
 from .base import AUnifiedIO
 from .contracts import FileMode, FileType, PathType, OperationResult, LockType, IUnifiedIO
@@ -54,7 +57,7 @@ class XWIO(AUnifiedIO):
     - Delegates to specialized components
     """
     
-    def __init__(self, file_path: Optional[Union[str, Path]] = None, **config):
+    def __init__(self, file_path: Optional[str | Path] = None, **config):
         """
         Initialize XWIO facade.
         
@@ -81,7 +84,7 @@ class XWIO(AUnifiedIO):
     # FILE OPERATIONS
     # ============================================================================
     
-    def open_file(self, file_path: Optional[Union[str, Path]] = None, mode: FileMode = FileMode.READ) -> None:
+    def open_file(self, file_path: Optional[str | Path] = None, mode: FileMode = FileMode.READ) -> None:
         """Open file with validation and monitoring."""
         target_path = Path(file_path) if file_path else self.file_path
         if not target_path:
@@ -100,7 +103,7 @@ class XWIO(AUnifiedIO):
             self.file_path = target_path
             logger.debug(f"File opened: {target_path} in mode {mode.value}")
     
-    def open_stream(self, stream: Union[BinaryIO, TextIO]) -> None:
+    def open_stream(self, stream: BinaryIO | TextIO) -> None:
         """Open stream for stream operations."""
         self._stream = stream
         self._position = 0
@@ -110,12 +113,12 @@ class XWIO(AUnifiedIO):
     # ABSTRACT METHOD IMPLEMENTATIONS (from AFile)
     # ============================================================================
     
-    # Keep open() for backward compatibility - delegate to file operations
+    # Delegate to file operations
     def open(self, mode: FileMode = FileMode.READ) -> None:
         """Open file with validation and monitoring (alias for open_file())."""
         self.open_file(mode=mode)
     
-    def read(self, size: Optional[int] = None) -> Union[str, bytes]:
+    def read(self, size: Optional[int] = None) -> str | bytes:
         """
         Read from file (implements AFile abstract method).
         
@@ -133,7 +136,7 @@ class XWIO(AUnifiedIO):
             # File operation  
             return self.read_file(size)
     
-    def write(self, data: Union[str, bytes]) -> int:
+    def write(self, data: str | bytes) -> int:
         """
         Write to file (implements AFile abstract method).
         
@@ -151,26 +154,7 @@ class XWIO(AUnifiedIO):
             # File operation
             return self.write_file(data)
     
-    def save_as(self, path: Union[str, Path], data: Any, **kwargs) -> bool:
-        """
-        Save data to specific path (implements AFile abstract method).
-        
-        Args:
-            path: Target file path
-            data: Data to save
-            **kwargs: Additional options
-            
-        Returns:
-            True if successful, False otherwise
-        """
-        try:
-            self.save(data, file_path=path, **kwargs)
-            return True
-        except Exception as e:
-            logger.error(f"Failed to save data to {path}: {e}")
-            return False
-    
-    def to_file(self, path: Union[str, Path], **kwargs) -> bool:
+    def to_file(self, path: str | Path, **kwargs) -> bool:
         """
         Write current data to file (implements AFile abstract method).
         
@@ -198,7 +182,7 @@ class XWIO(AUnifiedIO):
         logger.warning("No data to write to file")
         return False
     
-    def from_file(self, path: Union[str, Path], **kwargs) -> 'XWIO':
+    def from_file(self, path: str | Path, **kwargs) -> XWIO:
         """
         Load data from file and return new XWIO instance (implements AFile abstract method).
         
@@ -212,8 +196,17 @@ class XWIO(AUnifiedIO):
         new_instance = XWIO(file_path=path, **self.__dict__.get('_config', {}))
         new_instance._current_data = new_instance.load(file_path=path, **kwargs)
         return new_instance
+
+    def load_from(self, path: str | Path, **kwargs) -> Any:
+        """
+        Load data from a specific path (convenience alias).
+
+        This matches the facade-style API used in core tests:
+        - `load_from(path)` delegates to `load(file_path=...)`.
+        """
+        return self.load(file_path=path, **kwargs)
     
-    def read_file(self, size: Optional[int] = None) -> Union[str, bytes]:
+    def read_file(self, size: Optional[int] = None) -> str | bytes:
         """Read from file with validation."""
         if not self.is_open():
             raise ValueError("File not open")
@@ -226,7 +219,7 @@ class XWIO(AUnifiedIO):
             
             return data
     
-    def write_file(self, data: Union[str, bytes]) -> int:
+    def write_file(self, data: str | bytes) -> int:
         """Write to file with validation."""
         if not self.is_open():
             raise ValueError("File not open")
@@ -238,14 +231,20 @@ class XWIO(AUnifiedIO):
             return self._handle.write(data)
     
     
-    def save(self, data: Any, file_path: Optional[Union[str, Path]] = None) -> None:
-        """Save data to file with atomic operations."""
+    def save(self, data: Any, file_path: Optional[str | Path] = None) -> bool:
+        """
+        Save data to file with atomic operations.
+
+        Returns:
+            True if successful.
+        """
         target_path = Path(file_path) if file_path else self.file_path
         if not target_path:
             raise ValueError("No file path specified")
         
         if self.validate_paths:
-            self._path_validator.validate_path(target_path)
+            # Saving is a write operation; allow creating new files in valid directories.
+            self._path_validator.validate_path(target_path, for_writing=True, create_dirs=True)
         
         if self.validate_data:
             self._data_validator.validate_data(data)
@@ -253,18 +252,21 @@ class XWIO(AUnifiedIO):
         with performance_monitor("file_save"):
             if self.use_atomic_operations:
                 # Use atomic file writer
-                with AtomicFileWriter(target_path, backup=self.auto_backup) as writer:
-                    if isinstance(data, str):
-                        writer.write(data.encode('utf-8'))
-                    else:
+                if isinstance(data, bytes):
+                    with AtomicFileWriter(target_path, mode="wb", backup=self.auto_backup) as writer:
+                        writer.write(data)
+                else:
+                    # Treat as text (most common path for XWIO facade)
+                    with AtomicFileWriter(target_path, mode="w", encoding="utf-8", backup=self.auto_backup) as writer:
                         writer.write(data)
             else:
                 # Direct write
                 target_path.parent.mkdir(parents=True, exist_ok=True)
                 with open(target_path, 'wb' if isinstance(data, bytes) else 'w') as f:
                     f.write(data)
+        return True
     
-    def load(self, file_path: Optional[Union[str, Path]] = None) -> Any:
+    def load(self, file_path: Optional[str | Path] = None) -> Any:
         """Load data from file with validation."""
         target_path = Path(file_path) if file_path else self.file_path
         if not target_path:
@@ -342,7 +344,7 @@ class XWIO(AUnifiedIO):
     # ATOMIC OPERATIONS
     # ============================================================================
     
-    def atomic_write(self, file_path: Union[str, Path], data: Union[str, bytes], 
+    def atomic_write(self, file_path: str | Path, data: str | bytes, 
                     backup: bool = True) -> OperationResult:
         """Atomically write data to file."""
         target_path = Path(file_path)
@@ -365,7 +367,7 @@ class XWIO(AUnifiedIO):
                 logger.error(f"Atomic write failed for {target_path}: {e}")
                 return OperationResult.FAILED
     
-    def atomic_copy(self, source: Union[str, Path], destination: Union[str, Path]) -> OperationResult:
+    def atomic_copy(self, source: str | Path, destination: str | Path) -> OperationResult:
         """Atomically copy file."""
         source_path = Path(source)
         dest_path = Path(destination)
@@ -385,7 +387,7 @@ class XWIO(AUnifiedIO):
                 logger.error(f"Atomic copy failed from {source_path} to {dest_path}: {e}")
                 return OperationResult.FAILED
     
-    def atomic_move(self, source: Union[str, Path], destination: Union[str, Path]) -> OperationResult:
+    def atomic_move(self, source: str | Path, destination: str | Path) -> OperationResult:
         """Atomically move file."""
         source_path = Path(source)
         dest_path = Path(destination)
@@ -411,7 +413,7 @@ class XWIO(AUnifiedIO):
                 logger.error(f"Atomic move failed from {source_path} to {dest_path}: {e}")
                 return OperationResult.FAILED
     
-    def atomic_delete(self, file_path: Union[str, Path], backup: bool = True) -> OperationResult:
+    def atomic_delete(self, file_path: str | Path, backup: bool = True) -> OperationResult:
         """Atomically delete file."""
         target_path = Path(file_path)
         
@@ -431,7 +433,7 @@ class XWIO(AUnifiedIO):
                 logger.error(f"Atomic delete failed for {target_path}: {e}")
                 return OperationResult.FAILED
     
-    def atomic_rename(self, old_path: Union[str, Path], new_path: Union[str, Path]) -> OperationResult:
+    def atomic_rename(self, old_path: str | Path, new_path: str | Path) -> OperationResult:
         """Atomically rename file."""
         old_file = Path(old_path)
         new_file = Path(new_path)
@@ -455,7 +457,7 @@ class XWIO(AUnifiedIO):
     # BACKUP OPERATIONS
     # ============================================================================
     
-    def create_backup(self, source: Union[str, Path], backup_dir: Union[str, Path]) -> Optional[Path]:
+    def create_backup(self, source: str | Path, backup_dir: str | Path) -> Optional[Path]:
         """Create backup of file or directory."""
         source_path = Path(source)
         backup_path = Path(backup_dir)
@@ -484,7 +486,7 @@ class XWIO(AUnifiedIO):
                 logger.error(f"Backup creation failed for {source_path}: {e}")
                 return None
     
-    def restore_backup(self, backup_path: Union[str, Path], target: Union[str, Path]) -> OperationResult:
+    def restore_backup(self, backup_path: str | Path, target: str | Path) -> OperationResult:
         """Restore from backup."""
         backup = Path(backup_path)
         target_path = Path(target)
@@ -553,7 +555,7 @@ class XWIO(AUnifiedIO):
     # ASYNC OPERATIONS
     # ============================================================================
     
-    async def aread(self, size: Optional[int] = None) -> Union[str, bytes]:
+    async def aread(self, size: Optional[int] = None) -> str | bytes:
         """Async read operation."""
         if not self._async_stream:
             raise ValueError("Async stream not initialized")
@@ -561,7 +563,7 @@ class XWIO(AUnifiedIO):
         with performance_monitor("async_read"):
             return await self._async_stream.read(size)
     
-    async def awrite(self, data: Union[str, bytes]) -> int:
+    async def awrite(self, data: str | bytes) -> int:
         """Async write operation."""
         if not self._async_stream:
             raise ValueError("Async stream not initialized")
@@ -640,7 +642,7 @@ class XWIO(AUnifiedIO):
     # CODEC INTEGRATION (UniversalCodecRegistry)
     # ============================================================================
     
-    def serialize(self, data: Any, format_id: str, **options) -> Union[bytes, str]:
+    def serialize(self, data: Any, format_id: str, **options) -> bytes | str:
         """
         Serialize data using specified format.
         
@@ -669,7 +671,7 @@ class XWIO(AUnifiedIO):
         
         return codec.encode(data, options=options or None)
     
-    def deserialize(self, data: Union[bytes, str], format_id: str, **options) -> Any:
+    def deserialize(self, data: bytes | str, format_id: str, **options) -> Any:
         """
         Deserialize data using specified format.
         
@@ -698,7 +700,7 @@ class XWIO(AUnifiedIO):
         
         return codec.decode(data, options=options or None)
     
-    def save_serialized(self, data: Any, file_path: Union[str, Path], format_id: Optional[str] = None, **options) -> None:
+    def save_serialized(self, data: Any, file_path: str | Path, format_id: Optional[str] = None, **options) -> None:
         """
         Serialize and save data to file.
         
@@ -742,7 +744,7 @@ class XWIO(AUnifiedIO):
             else:
                 path.write_text(repr_data, encoding='utf-8')
     
-    def load_serialized(self, file_path: Union[str, Path], format_id: Optional[str] = None, **options) -> Any:
+    def load_serialized(self, file_path: str | Path, format_id: Optional[str] = None, **options) -> Any:
         """
         Load and deserialize data from file.
         
@@ -789,7 +791,7 @@ class XWIO(AUnifiedIO):
     # CONVENIENCE ALIASES (User-friendly API)
     # ============================================================================
     
-    def load_as(self, file_path: Union[str, Path], format_id: str, **options) -> Any:
+    def load_as(self, file_path: str | Path, format_id: str, **options) -> Any:
         """
         Load data from file using specified format (convenience alias).
         
@@ -810,16 +812,30 @@ class XWIO(AUnifiedIO):
         """
         return self.load_serialized(file_path, format_id=format_id, **options)
     
-    def save_as(self, file_path: Union[str, Path], data: Any, format_id: str, **options) -> None:
+    def save_as(
+        self,
+        file_path: str | Path,
+        data: Any,
+        format_id: Optional[str] = None,
+        **options,
+    ) -> bool:
         """
-        Save data to file using specified format (convenience alias).
+        Save data to a specific path.
+
+        This method intentionally supports **two** usage patterns:
+
+        1) **File-like save** (AFile-style):
+           - `save_as(path, data)` → writes raw text/bytes to the target path
+
+        2) **Serialization save** (format-aware):
+           - `save_as(path, data, format_id="json", ...)` → serializes and writes via codec registry
         
-        Alias for save_serialized() with explicit format.
+        If you want a more explicit serialization name, prefer `write_as(...)`.
         
         Args:
             file_path: Path to save to
             data: Data to serialize
-            format_id: Format identifier (e.g., 'json', 'yaml', 'xml')
+            format_id: Optional format identifier (e.g., 'json', 'yaml', 'xml')
             **options: Format-specific options
         
         Examples:
@@ -827,9 +843,19 @@ class XWIO(AUnifiedIO):
             >>> io.save_as("config.yml", config_dict, "yaml", indent=2)
             >>> io.save_as("users.xml", users_list, "xml", pretty=True)
         """
-        self.save_serialized(data, file_path, format_id=format_id, **options)
+        try:
+            if format_id is None:
+                # Raw save (string/bytes) with path validation + atomic ops
+                return bool(self.save(data, file_path=file_path))
+
+            # Format-aware save via codec registry
+            self.save_serialized(data, file_path, format_id=format_id, **options)
+            return True
+        except Exception as e:
+            logger.error(f"Failed to save data to {file_path}: {e}")
+            return False
     
-    def read_as(self, file_path: Union[str, Path], format_id: Optional[str] = None, **options) -> Any:
+    def read_as(self, file_path: str | Path, format_id: Optional[str] = None, **options) -> Any:
         """
         Read and deserialize file (auto-detect or explicit format).
         
@@ -850,7 +876,7 @@ class XWIO(AUnifiedIO):
         """
         return self.load_serialized(file_path, format_id=format_id, **options)
     
-    def write_as(self, file_path: Union[str, Path], data: Any, format_id: Optional[str] = None, **options) -> None:
+    def write_as(self, file_path: str | Path, data: Any, format_id: Optional[str] = None, **options) -> None:
         """
         Serialize and write to file (auto-detect or explicit format).
         
@@ -902,7 +928,7 @@ class XWIO(AUnifiedIO):
         
         # Close async stream
         if self._async_stream:
-            # Note: This should be called in async context
+            # Note: Called in async context
             logger.warning("Async stream still open - call aclose() in async context")
         
         # Cleanup temporary resources

exonware/xwsystem/io/file/__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.4
 Generation Date: 30-Oct-2025
 
 File-specific implementations and utilities.

exonware/xwsystem/io/file/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.4
 Generation Date: 30-Oct-2025
 
 Base classes for file operations.
@@ -20,7 +20,7 @@ Priority 5 (Extensibility): Ready for new file types
 
 from abc import ABC, abstractmethod
 from pathlib import Path
-from typing import Union, Optional, Any
+from typing import Optional, Any
 
 from ..contracts import IFileSource, IPagedSource, IPagingStrategy
 from ..defs import PagingMode
@@ -38,7 +38,7 @@ class AFileSource(IFileSource, ABC):
     Provides common file source functionality.
     """
     
-    def __init__(self, path: Union[str, Path], mode: str = 'rb', encoding: Optional[str] = None):
+    def __init__(self, path: str | Path, mode: str = 'rb', encoding: Optional[str] = None):
         """Initialize file source."""
         self._path = Path(path)
         self._mode = mode
@@ -64,12 +64,12 @@ class AFileSource(IFileSource, ABC):
             self._path.unlink()
     
     @abstractmethod
-    def read(self, **options) -> Union[bytes, str]:
+    def read(self, **options) -> bytes | str:
         """Read entire file content."""
         pass
     
     @abstractmethod
-    def write(self, data: Union[bytes, str], **options) -> None:
+    def write(self, data: bytes | str, **options) -> None:
         """Write entire content to file."""
         pass
 
@@ -84,7 +84,7 @@ class APagedSource(IPagedSource, ABC):
     
     def __init__(
         self,
-        path: Union[str, Path],
+        path: str | Path,
         mode: str = 'rb',
         encoding: Optional[str] = None,
         paging_strategy: Optional[IPagingStrategy] = None
@@ -116,7 +116,7 @@ class APagedSource(IPagedSource, ABC):
             return -1
         return self._path.stat().st_size
     
-    def read_page(self, page: int, page_size: int, **options) -> Union[bytes, str]:
+    def read_page(self, page: int, page_size: int, **options) -> bytes | str:
         """Read specific page using strategy."""
         return self._paging_strategy.read_page(
             self._path,
@@ -138,7 +138,7 @@ class APagedSource(IPagedSource, ABC):
         )
     
     @abstractmethod
-    def read_chunk(self, offset: int, size: int, **options) -> Union[bytes, str]:
+    def read_chunk(self, offset: int, size: int, **options) -> bytes | str:
         """Read chunk by byte offset."""
         pass
     
@@ -146,4 +146,3 @@ class APagedSource(IPagedSource, ABC):
     def iter_chunks(self, chunk_size: int, **options):
         """Iterate over chunks."""
         pass
-

exonware/xwsystem/io/file/conversion.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.4
 Generation Date: November 1, 2025
 
 File Format Conversion - Convert between compatible formats.
@@ -22,7 +22,7 @@ Priority 5 (Extensibility): Works with any registered codec
 """
 
 from pathlib import Path
-from typing import Any, Optional, Union
+from typing import Any, Optional
 
 from ..codec.base import get_global_registry
 from ..contracts import ICodec
@@ -241,4 +241,3 @@ def convert_file(
         >>> convert_file(Path("data.json"), Path("data.yaml"))
     """
     _converter.convert_file(source_path, target_path, source_format, target_format, **options)
-