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

exonware/xwsystem/http_client/facade.py

@@ -0,0 +1,156 @@
+#exonware/xwsystem/src/exonware/xwsystem/http_client/facade.py
+"""
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.1.0.4
+Generation Date: January 2026
+
+XWHTTP - Unified HTTP Client Facade
+
+Simplified API for HTTP operations:
+- Simple requests (GET, POST, PUT, DELETE, etc.)
+- Client instances with configuration
+- Async support
+- Retry logic
+"""
+
+from typing import Any, Optional, Dict
+from pathlib import Path
+
+from .client import HttpClient, AsyncHttpClient, HttpError, RetryConfig
+from .advanced_client import AdvancedHttpClient, AdvancedHttpConfig
+from ..config.logging_setup import get_logger
+
+logger = get_logger(__name__)
+
+
+class XWHTTP:
+    """
+    Unified HTTP client facade - simple API for HTTP operations.
+    
+    Examples:
+        >>> # Simple requests
+        >>> response = XWHTTP.get("https://api.example.com/data")
+        >>> response = XWHTTP.post("https://api.example.com/users", json={"name": "John"})
+        
+        >>> # Client instance
+        >>> client = XWHTTP(base_url="https://api.example.com", timeout=30)
+        >>> response = client.get("/users")
+        >>> response = client.post("/users", json=data)
+        
+        >>> # Async
+        >>> async def fetch():
+        ...     async with XWHTTP() as client:
+        ...         response = await client.get("https://api.example.com")
+    """
+    
+    def __init__(
+        self,
+        base_url: Optional[str] = None,
+        timeout: int = 30,
+        retries: int = 3,
+        async_mode: bool = False,
+        **kwargs
+    ):
+        """
+        Initialize HTTP client.
+        
+        Args:
+            base_url: Base URL for all requests
+            timeout: Request timeout in seconds
+            retries: Number of retry attempts
+            async_mode: Use async client
+            **kwargs: Additional client configuration
+        """
+        self.base_url = base_url
+        self.timeout = timeout
+        self.retries = retries
+        self.async_mode = async_mode
+        self.kwargs = kwargs
+        
+        # Create client instance
+        if async_mode:
+            self._client = AsyncHttpClient(
+                base_url=base_url,
+                timeout=timeout,
+                retry_config=RetryConfig(max_retries=retries),
+                **kwargs
+            )
+        else:
+            self._client = HttpClient(
+                base_url=base_url,
+                timeout=timeout,
+                retry_config=RetryConfig(max_retries=retries),
+                **kwargs
+            )
+    
+    def get(self, url: str, **kwargs) -> Any:
+        """GET request."""
+        full_url = self._build_url(url)
+        return self._client.get(full_url, **kwargs)
+    
+    def post(self, url: str, **kwargs) -> Any:
+        """POST request."""
+        full_url = self._build_url(url)
+        return self._client.post(full_url, **kwargs)
+    
+    def put(self, url: str, **kwargs) -> Any:
+        """PUT request."""
+        full_url = self._build_url(url)
+        return self._client.put(full_url, **kwargs)
+    
+    def delete(self, url: str, **kwargs) -> Any:
+        """DELETE request."""
+        full_url = self._build_url(url)
+        return self._client.delete(full_url, **kwargs)
+    
+    def patch(self, url: str, **kwargs) -> Any:
+        """PATCH request."""
+        full_url = self._build_url(url)
+        return self._client.patch(full_url, **kwargs)
+    
+    def _build_url(self, url: str) -> str:
+        """Build full URL from base_url and relative URL."""
+        if self.base_url and not url.startswith(("http://", "https://")):
+            return f"{self.base_url.rstrip('/')}/{url.lstrip('/')}"
+        return url
+    
+    def __enter__(self):
+        """Context manager entry."""
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit."""
+        # Clients handle their own cleanup
+        pass
+    
+    @staticmethod
+    def get(url: str, **kwargs) -> Any:
+        """Static GET request."""
+        client = HttpClient()
+        return client.get(url, **kwargs)
+    
+    @staticmethod
+    def post(url: str, **kwargs) -> Any:
+        """Static POST request."""
+        client = HttpClient()
+        return client.post(url, **kwargs)
+    
+    @staticmethod
+    def put(url: str, **kwargs) -> Any:
+        """Static PUT request."""
+        client = HttpClient()
+        return client.put(url, **kwargs)
+    
+    @staticmethod
+    def delete(url: str, **kwargs) -> Any:
+        """Static DELETE request."""
+        client = HttpClient()
+        return client.delete(url, **kwargs)
+    
+    @staticmethod
+    def patch(url: str, **kwargs) -> Any:
+        """Static PATCH request."""
+        client = HttpClient()
+        return client.patch(url, **kwargs)

exonware/xwsystem/io/__init__.py

@@ -1,8 +1,9 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/__init__.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
 
 I/O utilities for safe file operations, path management, and codec integration.
@@ -94,6 +95,18 @@ from .file import (
 
 from .folder import XWFolder
 
+# ═══════════════════════════════════════════════════════════════════════
+# SOURCE READER - Load from path or URL (local + internet)
+# ═══════════════════════════════════════════════════════════════════════
+
+from .source_reader import (
+    SourceLoadConfig,
+    is_http_url,
+    get_scheme,
+    is_external_scheme,
+    read_source_text,
+)
+
 # ═══════════════════════════════════════════════════════════════════════
 # STREAM - Stream + Codec Integration
 # ═══════════════════════════════════════════════════════════════════════
@@ -113,7 +126,7 @@ from .filesystem import LocalFileSystem
 # ═══════════════════════════════════════════════════════════════════════
 
 from .archive import (
-    # Legacy Archive
+    # Archive
     Archive, Compression,
     # Archivers (Codecs - In-memory)
     ZipArchiver, TarArchiver,
@@ -138,7 +151,6 @@ from .codec.contracts import ICodec, ICodecMetadata
 from .codec.base import ACodec
 from .codec.registry import UniversalCodecRegistry, get_registry
 
-# Type aliases for backward compatibility
 from .contracts import EncodeOptions, DecodeOptions, Serializer, Formatter
 
 # ═══════════════════════════════════════════════════════════════════════
@@ -192,6 +204,13 @@ __all__ = [
     # Folder operations
     "XWFolder",
     
+    # Source reader (path or URI; config-driven, multi-scheme)
+    "SourceLoadConfig",
+    "is_http_url",
+    "get_scheme",
+    "is_external_scheme",
+    "read_source_text",
+    
     # Stream operations
     "CodecIO", "PagedCodecIO", "AsyncAtomicFileWriter",
     

exonware/xwsystem/io/archive/__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
 
 Archive and compression with REGISTRY PATTERN!
@@ -118,4 +118,10 @@ __all__ = [
     # Facades
     "Archive",
     "Compression",
-]
+    
+    # Unified Facade
+    "XWArchive",
+]
+
+# Import unified facade
+from .facade import XWArchive

exonware/xwsystem/io/archive/archive.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
 
 Archive facade using registry pattern.

exonware/xwsystem/io/archive/archive_files.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
 
 Archive FILES - File persistence for archives.
@@ -26,7 +26,7 @@ Priority 5 (Extensibility): Easy to add new formats
 import zipfile
 import tarfile
 from pathlib import Path
-from typing import Any, Optional, Union
+from typing import Any, Optional
 
 from ..archive.base import AArchiveFile
 from ..contracts import IArchiveFile, IArchiver
@@ -63,7 +63,7 @@ class ZipFile(AArchiveFile):
         >>> files = zip_file.list_contents()
     """
     
-    def __init__(self, path: Union[str, Path]):
+    def __init__(self, path: str | Path):
         """Initialize zip archive file."""
         super().__init__(path, archiver=ZipArchiver())
         self._archiver = ZipArchiver()  # Composition!
@@ -150,7 +150,7 @@ class TarFile(AArchiveFile):
     Supports compression: gzip, bz2, xz
     """
     
-    def __init__(self, path: Union[str, Path], compression: str = ''):
+    def __init__(self, path: str | Path, compression: str = ''):
         """
         Initialize tar archive file.
         
@@ -215,6 +215,3 @@ class TarFile(AArchiveFile):
     def get_archiver(self) -> IArchiver:
         """Get the underlying archiver codec."""
         return self._archiver
-
-
-

exonware/xwsystem/io/archive/archivers.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
 
 Archive codecs - In-memory archive processors.
@@ -22,11 +22,12 @@ Priority 4 (Performance): Efficient in-memory operations
 Priority 5 (Extensibility): Easy to add new formats (7z, RAR, etc.)
 """
 
+import sys
 import zipfile
 import tarfile
 import io
 from pathlib import Path
-from typing import Any, Optional, Union
+from typing import Any, Optional
 
 from ..archive.base import AArchiver
 from ..contracts import IArchiver, EncodeOptions, DecodeOptions
@@ -96,6 +97,44 @@ class ZipArchiver(AArchiver):
     def supports_capability(self, capability: CodecCapability) -> bool:
         """Check capability support."""
         return capability in (CodecCapability.BIDIRECTIONAL, CodecCapability.COMPRESSION)
+
+    # ----------------------------------------------------------------------
+    # File-based convenience API (used by archive facade + tests)
+    # ----------------------------------------------------------------------
+
+    @property
+    def format_id(self) -> str:
+        """Format identifier alias (compat with archive facade/tests)."""
+        return self.codec_id
+
+    def create(self, files: list[Path], archive_path: Path, compression: int = zipfile.ZIP_DEFLATED) -> Path:
+        """
+        Create a ZIP archive on disk from a list of files.
+        """
+        try:
+            archive_path.parent.mkdir(parents=True, exist_ok=True)
+            with zipfile.ZipFile(archive_path, "w", compression=compression) as zf:
+                for file_path in files:
+                    zf.write(file_path, arcname=file_path.name)
+            return archive_path
+        except Exception as e:
+            raise ArchiveError(f"Failed to create zip archive '{archive_path}': {e}")
+
+    def list_contents(self, archive_path: Path) -> list[str]:
+        """List contents of a ZIP archive on disk."""
+        try:
+            with zipfile.ZipFile(archive_path, "r") as zf:
+                return zf.namelist()
+        except Exception as e:
+            raise ArchiveError(f"Failed to list zip contents for '{archive_path}': {e}")
+
+    def add_file(self, archive_path: Path, file_path: Path, compression: int = zipfile.ZIP_DEFLATED) -> None:
+        """Add a file to an existing ZIP archive."""
+        try:
+            with zipfile.ZipFile(archive_path, "a", compression=compression) as zf:
+                zf.write(file_path, arcname=file_path.name)
+        except Exception as e:
+            raise ArchiveError(f"Failed to add file to zip '{archive_path}': {e}")
     
     def encode(self, value: Any, *, options: Optional[EncodeOptions] = None) -> bytes:
         """
@@ -174,13 +213,26 @@ class ZipArchiver(AArchiver):
         """
         return self.encode(data, options=options)
     
-    def extract(self, archive_bytes: bytes, **options) -> Any:
+    def extract(self, source: bytes | Path, extract_dir: Optional[Path] = None, **options) -> Any:
         """
-        User-friendly: Extract zip bytes to data.
-        
-        Delegates to decode().
+        Extract ZIP from either in-memory bytes or a file path.
+
+        - If source is bytes: returns dict[str, bytes] via decode()
+        - If source is Path: extracts to extract_dir and returns list[Path]
         """
-        return self.decode(archive_bytes, options=options)
+        if isinstance(source, (bytes, bytearray)):
+            return self.decode(bytes(source), options=options)
+
+        if extract_dir is None:
+            raise ArchiveError("extract_dir is required when extracting from a file path")
+
+        try:
+            extract_dir.mkdir(parents=True, exist_ok=True)
+            with zipfile.ZipFile(source, "r") as zf:
+                zf.extractall(extract_dir)
+                return [extract_dir / name for name in zf.namelist()]
+        except Exception as e:
+            raise ArchiveError(f"Failed to extract zip archive '{source}': {e}")
 
 
 class TarArchiver(AArchiver):
@@ -226,6 +278,42 @@ class TarArchiver(AArchiver):
     def supports_capability(self, capability: CodecCapability) -> bool:
         """Check capability support."""
         return capability in (CodecCapability.BIDIRECTIONAL, CodecCapability.COMPRESSION)
+
+    # ----------------------------------------------------------------------
+    # File-based convenience API (used by archive facade + tests)
+    # ----------------------------------------------------------------------
+
+    @property
+    def format_id(self) -> str:
+        """Format identifier alias (compat with archive facade/tests)."""
+        return self.codec_id
+
+    def create(self, files: list[Path], archive_path: Path, mode: str = "w") -> Path:
+        """Create a TAR archive on disk from a list of files."""
+        try:
+            archive_path.parent.mkdir(parents=True, exist_ok=True)
+            with tarfile.open(archive_path, mode) as tf:
+                for file_path in files:
+                    tf.add(file_path, arcname=file_path.name)
+            return archive_path
+        except Exception as e:
+            raise ArchiveError(f"Failed to create tar archive '{archive_path}': {e}")
+
+    def list_contents(self, archive_path: Path) -> list[str]:
+        """List contents of a TAR archive on disk."""
+        try:
+            with tarfile.open(archive_path, "r:*") as tf:
+                return [m.name for m in tf.getmembers() if m.name]
+        except Exception as e:
+            raise ArchiveError(f"Failed to list tar contents for '{archive_path}': {e}")
+
+    def add_file(self, archive_path: Path, file_path: Path) -> None:
+        """Add a file to an existing TAR archive (append mode)."""
+        try:
+            with tarfile.open(archive_path, "a") as tf:
+                tf.add(file_path, arcname=file_path.name)
+        except Exception as e:
+            raise ArchiveError(f"Failed to add file to tar '{archive_path}': {e}")
     
     def encode(self, value: Any, *, options: Optional[EncodeOptions] = None) -> bytes:
         """Encode data to tar bytes (in RAM)."""
@@ -286,7 +374,29 @@ class TarArchiver(AArchiver):
         """User-friendly: Compress data to tar bytes."""
         return self.encode(data, options=options)
     
-    def extract(self, archive_bytes: bytes, **options) -> Any:
-        """User-friendly: Extract tar bytes to data."""
-        return self.decode(archive_bytes, options=options)
+    def extract(self, source: bytes | Path, extract_dir: Optional[Path] = None, **options) -> Any:
+        """
+        Extract TAR from either in-memory bytes or a file path.
 
+        - If source is bytes: returns dict[str, bytes] via decode()
+        - If source is Path: extracts to extract_dir and returns list[Path]
+        """
+        if isinstance(source, (bytes, bytearray)):
+            return self.decode(bytes(source), options=options)
+
+        if extract_dir is None:
+            raise ArchiveError("extract_dir is required when extracting from a file path")
+
+        try:
+            extract_dir.mkdir(parents=True, exist_ok=True)
+            with tarfile.open(source, "r:*") as tf:
+                # Use data filter for Python 3.12+ compatibility (prevents deprecation warning)
+                # data_filter allows all files but validates paths for security
+                # For older Python versions, filter parameter is not available
+                extract_kwargs = {}
+                if sys.version_info >= (3, 12):
+                    extract_kwargs['filter'] = 'data'
+                tf.extractall(extract_dir, **extract_kwargs)
+                return [extract_dir / m.name for m in tf.getmembers() if m.name]
+        except Exception as e:
+            raise ArchiveError(f"Failed to extract tar archive '{source}': {e}")

exonware/xwsystem/io/archive/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 and registries for archive system.
@@ -19,7 +19,7 @@ Priority 5 (Extensibility): Easy to add 7z, RAR, etc.
 """
 
 from abc import ABC, abstractmethod
-from typing import Optional, Union, Any
+from typing import Optional, Any
 from pathlib import Path
 
 from ..contracts import IArchiveFormat, ICompressor, IArchiveMetadata, IArchiver, IArchiveFile, EncodeOptions, DecodeOptions
@@ -193,7 +193,7 @@ class AArchiveFile(AFile, IArchiveFile, ABC):
     This is for file-based archive operations - works on archive files on disk.
     """
     
-    def __init__(self, file_path: Union[str, Path], archiver: Optional[IArchiver] = None):
+    def __init__(self, file_path: str | Path, archiver: Optional[IArchiver] = None):
         """
         Initialize archive file.
         
@@ -282,7 +282,7 @@ class ArchiveFormatRegistry:
         """Get archiver by format ID."""
         return self._instances.get(format_id)
     
-    def get_by_extension(self, path: Union[str, Path]) -> Optional[IArchiveFormat]:
+    def get_by_extension(self, path: str | Path) -> Optional[IArchiveFormat]:
         """
         Get archiver by file extension (AUTO-DETECTION!).
         
@@ -374,4 +374,3 @@ def get_global_compression_registry() -> CompressionRegistry:
         _global_compression_registry = CompressionRegistry()
         # Auto-register built-in compressors (will be done in compression/__init__.py)
     return _global_compression_registry
-

exonware/xwsystem/io/archive/codec_integration.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
 
 Archive-Codec Integration - Register archivers with CodecRegistry.
@@ -55,4 +55,3 @@ def register_archivers_as_codecs():
 
 # Auto-register on import
 register_archivers_as_codecs()
-

exonware/xwsystem/io/archive/compression.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
 
 Compression operations for gzip, bz2, and lzma.
@@ -184,4 +184,3 @@ class Compression(ICompression):
         output.write_bytes(decompressed)
         
         return output
-