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

exonware/xwsystem/io/archive/facade.py

@@ -0,0 +1,263 @@
+#exonware/xwsystem/src/exonware/xwsystem/io/archive/facade.py
+"""
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.1.0.3
+Generation Date: January 2026
+
+XWArchive - Unified Archiving Facade
+
+Simplified API for all archive formats:
+- ZIP, TAR, TAR.GZ, TAR.BZ2, TAR.XZ, 7Z, RAR, etc.
+- Auto-detect format from file path
+- Compression support
+"""
+
+from pathlib import Path
+from typing import Any, Optional, Union, List
+
+from .archive import Archive
+from .archivers import ZipArchiver, TarArchiver
+from .formats import get_archiver_for_file, get_archiver_by_id
+from .archive_files import ZipFile, TarFile
+from ..defs import ArchiveFormat, CompressionAlgorithm, CompressionLevel
+from ...config.logging_setup import get_logger
+
+logger = get_logger(__name__)
+
+
+class XWArchive:
+    """
+    Unified archiving facade - simple API for all archive formats.
+    
+    Examples:
+        >>> # Format-specific
+        >>> archive = XWArchive("zip")  # or format="zip"
+        >>> archive = XWArchive("tar.gz")
+        >>> archive = XWArchive("7z")
+        
+        >>> # Auto-detect from path
+        >>> archive = XWArchive("backup.zip")  # Detects ZIP
+        
+        >>> # With compression
+        >>> archive = XWArchive("tar.gz", compression="gzip", level="best")
+        
+        >>> # Quick operations
+        >>> XWArchive.create("files.zip", ["file1.txt", "file2.txt"])
+        >>> XWArchive.extract("archive.zip", "output_dir")
+        
+        >>> # File operations
+        >>> with XWArchive("backup.zip") as arch:
+        ...     arch.add("file.txt")
+        ...     arch.extract("file.txt", "output/")
+    """
+    
+    def __init__(
+        self,
+        format_or_path: Union[str, Path],
+        *,
+        format: Optional[str] = None,
+        compression: Optional[str] = None,
+        level: Union[str, int] = "balanced",
+        **kwargs
+    ):
+        """
+        Initialize unified archive.
+        
+        Args:
+            format_or_path: Format name ("zip", "tar.gz") or file path ("backup.zip")
+            format: Explicit format name (overrides auto-detection)
+            compression: Compression algorithm ("gzip", "bzip2", "lzma", "zstd", etc.)
+            level: Compression level ("fast", "balanced", "best") or int (0-9)
+            **kwargs: Additional archive options
+        """
+        self.format_or_path = format_or_path
+        self.format = format
+        self.compression = compression
+        self.level = level
+        self.kwargs = kwargs
+        
+        # Auto-detect format from path if it looks like a file path
+        if isinstance(format_or_path, (str, Path)):
+            path = Path(format_or_path)
+            # Check if it's a file path (has extension or path separators)
+            is_file_path = path.suffix or "/" in str(format_or_path) or "\\" in str(format_or_path)
+            
+            if is_file_path and not format:
+                # Looks like a file path - try to detect format from extension
+                try:
+                    detected = get_archiver_for_file(str(path))
+                    if detected:
+                        self.format = detected.codec_id
+                        self.file_path = path
+                    else:
+                        # Fallback: extract format from extension
+                        ext = path.suffix.lstrip('.').lower()
+                        if ext in ('zip', 'tar', 'gz', 'bz2', 'xz', '7z', 'rar'):
+                            self.format = ext
+                            self.file_path = path
+                        else:
+                            self.format = "zip"  # Default
+                            self.file_path = path
+                except Exception:
+                    # Fallback: extract format from extension
+                    ext = path.suffix.lstrip('.').lower()
+                    self.format = ext if ext else "zip"
+                    self.file_path = path
+            else:
+                # Use as format name
+                self.format = format or str(format_or_path)
+        
+        # Determine compression level
+        if isinstance(level, str):
+            level_map = {
+                "fast": CompressionLevel.FAST,
+                "balanced": CompressionLevel.BALANCED,
+                "best": CompressionLevel.BEST,
+            }
+            self.compression_level = level_map.get(level.lower(), CompressionLevel.BALANCED)
+        else:
+            self.compression_level = level
+        
+        # Create archiver instance
+        self._archiver = self._create_archiver()
+        self._archive_file = None
+    
+    def _create_archiver(self):
+        """Create archiver instance based on format."""
+        if self.format:
+            try:
+                archiver = get_archiver_by_id(self.format.lower())
+                if archiver:
+                    return archiver()
+            except Exception:
+                pass
+        
+        # Fallback to common formats
+        format_lower = (self.format or "").lower()
+        
+        if format_lower in ("zip", ".zip"):
+            return ZipArchiver()
+        elif format_lower in ("tar", ".tar"):
+            return TarArchiver()
+        elif format_lower in ("tar.gz", ".tar.gz", "targz"):
+            return TarArchiver()  # TarArchiver handles compression
+        elif format_lower in ("tar.bz2", ".tar.bz2", "tarbz2"):
+            return TarArchiver()
+        elif format_lower in ("tar.xz", ".tar.xz", "tarxz"):
+            return TarArchiver()
+        else:
+            # Try to get from registry
+            try:
+                return get_archiver_by_id(format_lower)()
+            except Exception:
+                raise ValueError(f"Unknown archive format: {self.format}")
+    
+    def create(self, archive_path: Union[str, Path], files: List[Union[str, Path]], **options) -> Path:
+        """
+        Create archive from files.
+        
+        Args:
+            archive_path: Path to create archive at
+            files: List of files/directories to archive
+            **options: Additional archive options
+            
+        Returns:
+            Path to created archive
+        """
+        archive_path = Path(archive_path)
+        files = [Path(f) for f in files]
+        
+        # Use Archive facade for file operations
+        archive = Archive()
+        archive.create(files, archive_path, format=self.format or None, **options)
+        
+        return archive_path
+    
+    def extract(self, archive_path: Union[str, Path], output_dir: Union[str, Path], **options) -> Path:
+        """
+        Extract archive to directory.
+        
+        Args:
+            archive_path: Path to archive
+            output_dir: Directory to extract to
+            **options: Additional extraction options
+            
+        Returns:
+            Output directory path
+        """
+        archive_path = Path(archive_path)
+        output_dir = Path(output_dir)
+        
+        # Use Archive facade
+        archive = Archive()
+        archive.extract(archive_path, output_dir, **options)
+        
+        return output_dir
+    
+    def add(self, file_path: Union[str, Path], **options) -> None:
+        """Add file to archive (when used as context manager)."""
+        if not hasattr(self, 'file_path') or not self.file_path:
+            raise ValueError("No archive file path specified. Initialize with file path for context manager usage.")
+        
+        # Use Archive facade to add file
+        archive = Archive()
+        archive.add_file(self.file_path, Path(file_path), **options)
+    
+    def list_contents(self) -> List[str]:
+        """List files in archive."""
+        if not self._archive_file:
+            raise ValueError("Archive not opened")
+        return self._archive_file.list_contents()
+    
+    def __enter__(self):
+        """Context manager entry."""
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit."""
+        if self._archive_file:
+            # Archive files handle their own cleanup
+            pass
+    
+    @classmethod
+    def create_archive(
+        cls,
+        archive_path: Union[str, Path],
+        files: List[Union[str, Path]],
+        format: Optional[str] = None,
+        **options
+    ) -> Path:
+        """
+        Static method to create archive.
+        
+        Examples:
+            >>> XWArchive.create_archive("files.zip", ["file1.txt", "file2.txt"])
+        """
+        # Auto-detect format from path
+        archive_path = Path(archive_path)
+        if not format:
+            format = archive_path.suffix.lstrip('.') or "zip"
+        
+        archive = cls(format, **options)
+        return archive.create(archive_path, files, **options)
+    
+    @classmethod
+    def extract_archive(
+        cls,
+        archive_path: Union[str, Path],
+        output_dir: Union[str, Path],
+        **options
+    ) -> Path:
+        """
+        Static method to extract archive.
+        
+        Examples:
+            >>> XWArchive.extract_archive("archive.zip", "output_dir")
+        """
+        archive_path = Path(archive_path)
+        format = archive_path.suffix.lstrip('.') or "zip"
+        
+        archive = cls(format, **options)
+        return archive.extract(archive_path, output_dir, **options)

exonware/xwsystem/io/archive/formats/__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: November 1, 2025
 
 Archive format implementations - COMPREHENSIVE 2025 SUPPORT.
@@ -33,7 +33,7 @@ Priority 4 (Performance): Efficient format handling
 Priority 5 (Extensibility): Easy to add more formats
 """
 
-# Standard formats (always available)
+# Standard formats (stdlib)
 from .zip import ZipArchiver
 from .tar import TarArchiver
 
@@ -132,4 +132,3 @@ __all__ = [
     "get_archiver_by_id",
     "register_archive_format",
 ]
-

exonware/xwsystem/io/archive/formats/brotli_format.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: November 1, 2025
 
 Brotli (.br) compression format - RANK #6 WEB COMPRESSION.
@@ -18,6 +18,7 @@ Priority 4 (Performance): Optimized for web
 Priority 5 (Extensibility): Lazy installation of brotli
 """
 
+import sys
 import tarfile
 from pathlib import Path
 from typing import Optional
@@ -25,10 +26,17 @@ from typing import Optional
 from ...contracts import IArchiveFormat
 from ...errors import ArchiveError
 
-# Lazy import for brotli - optional dependency
+# Optional dependency: brotli
+import importlib.util
 try:
-    import brotli
-except ImportError:
+    _brotli_spec = importlib.util.find_spec('brotli')
+    if _brotli_spec is not None and _brotli_spec.loader is not None:
+        import brotli
+    else:
+        brotli = None  # type: ignore
+except (ValueError, AttributeError, ImportError):
+    # Handle case where find_spec raises ValueError (e.g., module.__spec__ is None)
+    # or other import-related errors
     brotli = None  # type: ignore
 
 
@@ -119,12 +127,18 @@ class BrotliArchiver(IArchiveFormat):
             
             extracted = []
             with tarfile.open(fileobj=tar_buffer, mode='r') as tar:
+                # Use data filter for Python 3.12+ compatibility (prevents deprecation warning)
+                # For older Python versions, filter parameter is not available
+                extract_kwargs = {}
+                if sys.version_info >= (3, 12):
+                    extract_kwargs['filter'] = 'data'
+                
                 if members:
                     for member in members:
-                        tar.extract(member, output_dir)
+                        tar.extract(member, output_dir, **extract_kwargs)
                         extracted.append(output_dir / member)
                 else:
-                    tar.extractall(output_dir)
+                    tar.extractall(output_dir, **extract_kwargs)
                     extracted = [output_dir / m.name for m in tar.getmembers()]
             
             return extracted
@@ -148,4 +162,3 @@ class BrotliArchiver(IArchiveFormat):
     def add_file(self, archive: Path, file: Path, arcname: Optional[str] = None) -> None:
         """Not supported - recreate archive instead."""
         raise ArchiveError("Brotli doesn't support append mode. Recreate the archive.")
-

exonware/xwsystem/io/archive/formats/lz4_format.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: November 1, 2025
 
 LZ4 compression format - RANK #7 FASTEST COMPRESSION.
@@ -18,6 +18,7 @@ Priority 4 (Performance): Best speed (slower ratio)
 Priority 5 (Extensibility): Lazy installation of lz4
 """
 
+import sys
 import tarfile
 from pathlib import Path
 from typing import Optional
@@ -25,10 +26,17 @@ from typing import Optional
 from ...contracts import IArchiveFormat
 from ...errors import ArchiveError
 
-# Lazy import for lz4 - optional dependency
+# Optional dependency: lz4
+import importlib.util
 try:
-    import lz4.frame as lz4
-except ImportError:
+    _lz4_spec = importlib.util.find_spec('lz4')
+    if _lz4_spec is not None and _lz4_spec.loader is not None:
+        import lz4.frame as lz4
+    else:
+        lz4 = None  # type: ignore
+except (ValueError, AttributeError, ImportError):
+    # Handle case where find_spec raises ValueError (e.g., module.__spec__ is None)
+    # or other import-related errors
     lz4 = None  # type: ignore
 
 
@@ -118,12 +126,18 @@ class Lz4Archiver(IArchiveFormat):
             
             extracted = []
             with tarfile.open(fileobj=tar_buffer, mode='r') as tar:
+                # Use data filter for Python 3.12+ compatibility (prevents deprecation warning)
+                # For older Python versions, filter parameter is not available
+                extract_kwargs = {}
+                if sys.version_info >= (3, 12):
+                    extract_kwargs['filter'] = 'data'
+                
                 if members:
                     for member in members:
-                        tar.extract(member, output_dir)
+                        tar.extract(member, output_dir, **extract_kwargs)
                         extracted.append(output_dir / member)
                 else:
-                    tar.extractall(output_dir)
+                    tar.extractall(output_dir, **extract_kwargs)
                     extracted = [output_dir / m.name for m in tar.getmembers()]
             
             return extracted
@@ -147,4 +161,3 @@ class Lz4Archiver(IArchiveFormat):
     def add_file(self, archive: Path, file: Path, arcname: Optional[str] = None) -> None:
         """Not supported - recreate archive instead."""
         raise ArchiveError("LZ4 doesn't support append mode. Recreate the archive.")
-

exonware/xwsystem/io/archive/formats/rar.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: November 1, 2025
 
 RAR5 archive format implementation - RANK #3 PROPRIETARY COMPRESSION.
@@ -24,10 +24,17 @@ from typing import Optional
 from ...contracts import IArchiveFormat
 from ...errors import ArchiveError
 
-# Lazy import for rarfile - optional dependency
+# Optional dependency: rarfile
+import importlib.util
 try:
-    import rarfile
-except ImportError:
+    _rarfile_spec = importlib.util.find_spec('rarfile')
+    if _rarfile_spec is not None and _rarfile_spec.loader is not None:
+        import rarfile
+    else:
+        rarfile = None  # type: ignore
+except (ValueError, AttributeError, ImportError):
+    # Handle case where find_spec raises ValueError (e.g., module.__spec__ is None)
+    # or other import-related errors
     rarfile = None  # type: ignore
 
 
@@ -123,4 +130,3 @@ class RarArchiver(IArchiveFormat):
     def add_file(self, archive: Path, file: Path, arcname: Optional[str] = None) -> None:
         """RAR append not supported (requires WinRAR binary)."""
         raise ArchiveError("RAR append requires WinRAR/RAR binary (proprietary).")
-

exonware/xwsystem/io/archive/formats/sevenzip.py

@@ -4,10 +4,10 @@
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.3
 Generation Date: November 1, 2025
 
-7z archive format implementation - RANK #1 BEST COMPRESSION.
+7z archive format implementation - High compression ratio.
 
 **Best overall ratio + AES-256 encryption + solid archiving**
 
@@ -24,10 +24,17 @@ from typing import Optional
 from ...contracts import IArchiveFormat
 from ...errors import ArchiveError
 
-# Lazy import for py7zr - optional dependency
+# Optional dependency: py7zr
+import importlib.util
 try:
-    import py7zr
-except ImportError:
+    _py7zr_spec = importlib.util.find_spec('py7zr')
+    if _py7zr_spec is not None and _py7zr_spec.loader is not None:
+        import py7zr
+    else:
+        py7zr = None  # type: ignore
+except (ValueError, AttributeError, ImportError):
+    # Handle case where find_spec raises ValueError (e.g., module.__spec__ is None)
+    # or other import-related errors
     py7zr = None  # type: ignore
 
 
@@ -133,4 +140,3 @@ class SevenZipArchiver(IArchiveFormat):
                 zf.write(file, arcname=arcname)
         except Exception as e:
             raise ArchiveError(f"Failed to add file to 7z: {e}")
-

exonware/xwsystem/io/archive/formats/squashfs_format.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: November 1, 2025
 
 SquashFS filesystem format - RANK #10 EMBEDDED SYSTEMS.
@@ -152,4 +152,3 @@ class SquashfsArchiver(IArchiveFormat):
     def add_file(self, archive: Path, file: Path, arcname: Optional[str] = None) -> None:
         """SquashFS doesn't support append (read-only FS)."""
         raise ArchiveError("SquashFS is read-only. Recreate the filesystem to add files.")
-

exonware/xwsystem/io/archive/formats/tar.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
 
 TAR archive format implementation.
@@ -16,6 +16,7 @@ Priority 4 (Performance): Efficient TAR operations
 Priority 5 (Extensibility): Registered via registry
 """
 
+import sys
 import tarfile
 from pathlib import Path
 from typing import Optional
@@ -80,10 +81,12 @@ class TarArchiver(IArchiveFormat):
         with tarfile.open(archive, 'r:*') as tf:
             if members:
                 for member in members:
-                    tf.extract(member, output_dir)
+                    tf.extract(member, output_dir, filter='data')
                     extracted.append(output_dir / member)
             else:
-                tf.extractall(output_dir)
+                # Use data filter for Python 3.14+ compatibility (prevents deprecation warning)
+                # data_filter allows all files but validates paths for security
+                tf.extractall(output_dir, filter='data')
                 extracted = [output_dir / member.name for member in tf.getmembers()]
         
         return extracted
@@ -94,13 +97,55 @@ class TarArchiver(IArchiveFormat):
             return [member.name for member in tf.getmembers()]
     
     def add_file(self, archive: Path, file: Path, arcname: Optional[str] = None) -> None:
-        """Add file to TAR archive."""
+        """Add file to TAR archive (supports compressed archives)."""
         arcname = arcname or file.name
         
-        # Only support append to uncompressed TAR
+        # Uncompressed TAR - direct append
         if archive.suffix == '.tar':
             with tarfile.open(archive, 'a') as tf:
                 tf.add(file, arcname=arcname)
         else:
-            raise NotImplementedError("Adding to compressed TAR archives not supported")
-
+            # Compressed TAR - decompress, append, recompress
+            import tempfile
+            import shutil
+            
+            # Determine compression type
+            suffix = "".join(archive.suffixes).lower()
+            compression = None
+            if '.gz' in suffix or '.tgz' in suffix:
+                compression = 'gz'
+            elif '.bz2' in suffix or '.tbz' in suffix:
+                compression = 'bz2'
+            elif '.xz' in suffix or '.txz' in suffix:
+                compression = 'xz'
+            
+            if compression is None:
+                raise ValueError(f"Unsupported compression format: {suffix}")
+            
+            # Create temporary uncompressed TAR
+            with tempfile.NamedTemporaryFile(suffix='.tar', delete=False) as tmp_tar:
+                tmp_tar_path = Path(tmp_tar.name)
+            
+            try:
+                # Extract existing archive to temporary TAR
+                if archive.exists():
+                    with tarfile.open(archive, 'r:*') as source_tf:
+                        with tarfile.open(tmp_tar_path, 'w') as tmp_tf:
+                            for member in source_tf.getmembers():
+                                tmp_tf.addfile(member, source_tf.extractfile(member))
+                
+                # Add new file to temporary TAR
+                with tarfile.open(tmp_tar_path, 'a') as tmp_tf:
+                    tmp_tf.add(file, arcname=arcname)
+                
+                # Recompress to original archive
+                mode_map = {'gz': 'w:gz', 'bz2': 'w:bz2', 'xz': 'w:xz'}
+                with tarfile.open(tmp_tar_path, 'r') as tmp_tf:
+                    with tarfile.open(archive, mode_map[compression]) as compressed_tf:
+                        for member in tmp_tf.getmembers():
+                            compressed_tf.addfile(member, tmp_tf.extractfile(member))
+            
+            finally:
+                # Clean up temporary file
+                if tmp_tar_path.exists():
+                    tmp_tar_path.unlink()

exonware/xwsystem/io/archive/formats/wim_format.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: November 1, 2025
 
 WIM (Windows Imaging) format - RANK #9 SYSTEM IMAGES.
@@ -24,10 +24,17 @@ from typing import Optional
 from ...contracts import IArchiveFormat
 from ...errors import ArchiveError
 
-# Lazy import for wimlib - optional dependency
+# Optional dependency: wimlib
+import importlib.util
 try:
-    import wimlib
-except ImportError:
+    _wimlib_spec = importlib.util.find_spec('wimlib')
+    if _wimlib_spec is not None and _wimlib_spec.loader is not None:
+        import wimlib
+    else:
+        wimlib = None  # type: ignore
+except (ValueError, AttributeError, ImportError):
+    # Handle case where find_spec raises ValueError (e.g., module.__spec__ is None)
+    # or other import-related errors
     wimlib = None  # type: ignore
 
 
@@ -132,4 +139,3 @@ class WimArchiver(IArchiveFormat):
             wim.write()
         except Exception as e:
             raise ArchiveError(f"Failed to add image to WIM: {e}")
-

exonware/xwsystem/io/archive/formats/zip.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
 
 ZIP archive format implementation.
@@ -86,4 +86,3 @@ class ZipArchiver(IArchiveFormat):
         arcname = arcname or file.name
         with zipfile.ZipFile(archive, 'a') as zf:
             zf.write(file, arcname=arcname)
-

exonware/xwsystem/io/archive/formats/zpaq_format.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: November 1, 2025
 
 ZPAQ journaled compression format - RANK #8 EXTREME COMPRESSION.
@@ -150,4 +150,3 @@ class ZpaqArchiver(IArchiveFormat):
             raise ArchiveError(f"ZPAQ add failed: {e.stderr}")
         except Exception as e:
             raise ArchiveError(f"Failed to add file to zpaq: {e}")
-