provide-foundation 0.0.0.dev0__py3-none-any.whl → 0.0.0.dev2__py3-none-any.whl

provide/foundation/archive/operations.py

@@ -0,0 +1,334 @@
+"""Archive operation chains and helpers."""
+
+import tempfile
+from pathlib import Path
+from typing import Callable
+
+from attrs import define, field
+
+from provide.foundation.archive.base import ArchiveError
+from provide.foundation.archive.tar import TarArchive
+from provide.foundation.archive.gzip import GzipCompressor
+from provide.foundation.archive.bzip2 import Bzip2Compressor
+from provide.foundation.archive.zip import ZipArchive
+from provide.foundation.file import ensure_parent_dir
+from provide.foundation.file.safe import safe_delete
+from provide.foundation.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+@define(slots=True)
+class OperationChain:
+    """
+    Chain multiple archive operations together.
+    
+    Enables complex operations like tar.gz, tar.bz2, etc.
+    Operations are executed in order for creation, reversed for extraction.
+    """
+    
+    operations: list[str] = field(factory=list)
+    
+    def execute(self, source: Path, output: Path) -> Path:
+        """
+        Execute operation chain on source.
+        
+        Args:
+            source: Source file or directory
+            output: Final output path
+            
+        Returns:
+            Path to final output
+            
+        Raises:
+            ArchiveError: If any operation fails
+        """
+        current = source
+        temp_files = []
+        
+        try:
+            for i, op in enumerate(self.operations):
+                # Determine output for this operation
+                if i == len(self.operations) - 1:
+                    # Last operation, use final output
+                    next_output = output
+                else:
+                    # Intermediate operation, use temp file
+                    suffix = self._get_suffix_for_operation(op)
+                    temp = tempfile.NamedTemporaryFile(suffix=suffix, delete=False)
+                    temp.close()
+                    next_output = Path(temp.name)
+                    temp_files.append(next_output)
+                
+                # Execute operation
+                current = self._execute_operation(op, current, next_output)
+                logger.debug(f"Executed operation '{op}': {current}")
+            
+            return current
+            
+        except Exception as e:
+            raise ArchiveError(f"Operation chain failed: {e}") from e
+        finally:
+            # Clean up temp files using Foundation's safe file operations
+            for temp in temp_files:
+                safe_delete(temp, missing_ok=True)
+    
+    def reverse(self, source: Path, output: Path) -> Path:
+        """
+        Reverse operation chain (extract/decompress).
+        
+        Args:
+            source: Source archive
+            output: Final output path
+            
+        Returns:
+            Path to final output
+            
+        Raises:
+            ArchiveError: If any operation fails
+        """
+        # Reverse the operations and invert them
+        reverse_map = {
+            'tar': 'untar',
+            'untar': 'tar',
+            'gzip': 'gunzip', 
+            'gunzip': 'gzip',
+            'bzip2': 'bunzip2',
+            'bunzip2': 'bzip2',
+            'zip': 'unzip',
+            'unzip': 'zip',
+        }
+        
+        reversed_ops = []
+        for op in reversed(self.operations):
+            reversed_op = reverse_map.get(op.lower(), op)
+            reversed_ops.append(reversed_op)
+        
+        reversed_chain = OperationChain(operations=reversed_ops)
+        return reversed_chain.execute(source, output)
+    
+    def _execute_operation(self, operation: str, source: Path, output: Path) -> Path:
+        """Execute a single operation."""
+        match operation.lower():
+            case "tar":
+                tar = TarArchive()
+                return tar.create(source, output)
+            case "untar":
+                tar = TarArchive()
+                return tar.extract(source, output)
+            case "gzip":
+                gzip = GzipCompressor()
+                return gzip.compress_file(source, output)
+            case "gunzip":
+                gzip = GzipCompressor()
+                return gzip.decompress_file(source, output)
+            case "bzip2":
+                bz2 = Bzip2Compressor()
+                return bz2.compress_file(source, output)
+            case "bunzip2":
+                bz2 = Bzip2Compressor()
+                return bz2.decompress_file(source, output)
+            case "zip":
+                zip_archive = ZipArchive()
+                return zip_archive.create(source, output)
+            case "unzip":
+                zip_archive = ZipArchive()
+                return zip_archive.extract(source, output)
+            case _:
+                raise ArchiveError(f"Unknown operation: {operation}")
+    
+    def _get_suffix_for_operation(self, operation: str) -> str:
+        """Get file suffix for operation."""
+        suffixes = {
+            "tar": ".tar",
+            "gzip": ".gz",
+            "bzip2": ".bz2",
+            "zip": ".zip",
+        }
+        return suffixes.get(operation.lower(), ".tmp")
+
+
+class ArchiveOperations:
+    """
+    Helper class for common archive operation patterns.
+    
+    Provides convenient methods for common archive formats.
+    """
+    
+    @staticmethod
+    def create_tar_gz(source: Path, output: Path, deterministic: bool = True) -> Path:
+        """
+        Create .tar.gz archive in one step.
+        
+        Args:
+            source: Source file or directory
+            output: Output path (should end with .tar.gz)
+            deterministic: Create reproducible archive
+            
+        Returns:
+            Path to created archive
+            
+        Raises:
+            ArchiveError: If creation fails
+        """
+        ensure_parent_dir(output)
+        
+        # Create temp tar file
+        temp_tar = output.with_suffix('.tar')
+        try:
+            tar = TarArchive(deterministic=deterministic)
+            tar.create(source, temp_tar)
+            
+            # Compress to final output
+            gzip = GzipCompressor()
+            return gzip.compress_file(temp_tar, output)
+        finally:
+            # Clean up temp file
+            if temp_tar.exists():
+                temp_tar.unlink()
+    
+    @staticmethod
+    def extract_tar_gz(archive: Path, output: Path) -> Path:
+        """
+        Extract .tar.gz archive in one step.
+        
+        Args:
+            archive: Archive path
+            output: Output directory
+            
+        Returns:
+            Path to extraction directory
+            
+        Raises:
+            ArchiveError: If extraction fails
+        """
+        output.mkdir(parents=True, exist_ok=True)
+        
+        # Decompress to temp file
+        with tempfile.NamedTemporaryFile(suffix='.tar', delete=False) as temp:
+            temp_tar = Path(temp.name)
+        
+        try:
+            gzip = GzipCompressor()
+            gzip.decompress_file(archive, temp_tar)
+            
+            # Extract tar
+            tar = TarArchive()
+            return tar.extract(temp_tar, output)
+        finally:
+            # Clean up temp file
+            if temp_tar.exists():
+                temp_tar.unlink()
+    
+    @staticmethod
+    def create_tar_bz2(source: Path, output: Path, deterministic: bool = True) -> Path:
+        """
+        Create .tar.bz2 archive in one step.
+        
+        Args:
+            source: Source file or directory
+            output: Output path (should end with .tar.bz2)
+            deterministic: Create reproducible archive
+            
+        Returns:
+            Path to created archive
+            
+        Raises:
+            ArchiveError: If creation fails
+        """
+        ensure_parent_dir(output)
+        
+        # Create temp tar file
+        temp_tar = output.with_suffix('.tar')
+        try:
+            tar = TarArchive(deterministic=deterministic)
+            tar.create(source, temp_tar)
+            
+            # Compress to final output
+            bz2 = Bzip2Compressor()
+            return bz2.compress_file(temp_tar, output)
+        finally:
+            # Clean up temp file
+            if temp_tar.exists():
+                temp_tar.unlink()
+    
+    @staticmethod
+    def extract_tar_bz2(archive: Path, output: Path) -> Path:
+        """
+        Extract .tar.bz2 archive in one step.
+        
+        Args:
+            archive: Archive path
+            output: Output directory
+            
+        Returns:
+            Path to extraction directory
+            
+        Raises:
+            ArchiveError: If extraction fails
+        """
+        output.mkdir(parents=True, exist_ok=True)
+        
+        # Decompress to temp file
+        with tempfile.NamedTemporaryFile(suffix='.tar', delete=False) as temp:
+            temp_tar = Path(temp.name)
+        
+        try:
+            bz2 = Bzip2Compressor()
+            bz2.decompress_file(archive, temp_tar)
+            
+            # Extract tar
+            tar = TarArchive()
+            return tar.extract(temp_tar, output)
+        finally:
+            # Clean up temp file
+            if temp_tar.exists():
+                temp_tar.unlink()
+    
+    @staticmethod
+    def detect_format(file: Path) -> list[str]:
+        """
+        Detect archive format and return operation chain.
+        
+        Args:
+            file: File path to analyze
+            
+        Returns:
+            List of operations needed to extract
+            
+        Raises:
+            ArchiveError: If format cannot be detected
+        """
+        name = file.name.lower()
+        
+        # Check by extension
+        if name.endswith('.tar.gz') or name.endswith('.tgz'):
+            return ['gunzip', 'untar']
+        elif name.endswith('.tar.bz2') or name.endswith('.tbz2'):
+            return ['bunzip2', 'untar']
+        elif name.endswith('.tar'):
+            return ['untar']
+        elif name.endswith('.gz'):
+            return ['gunzip']
+        elif name.endswith('.bz2'):
+            return ['bunzip2']
+        elif name.endswith('.zip'):
+            return ['unzip']
+        
+        # Check by magic numbers
+        try:
+            with open(file, 'rb') as f:
+                magic = f.read(4)
+                
+            if magic[:2] == b'\x1f\x8b':  # gzip
+                return ['gunzip']
+            elif magic[:3] == b'BZh':  # bzip2
+                return ['bunzip2']
+            elif magic[:4] == b'PK\x03\x04':  # zip
+                return ['unzip']
+            elif magic[:3] == b'ustar':  # tar (at offset 257)
+                return ['untar']
+        except Exception:
+            pass
+        
+        raise ArchiveError(f"Cannot detect format of {file}")

provide/foundation/archive/tar.py

@@ -0,0 +1,164 @@
+"""TAR archive implementation."""
+
+import tarfile
+from pathlib import Path
+
+from attrs import define, field
+
+from provide.foundation.archive.base import BaseArchive, ArchiveError
+from provide.foundation.file import ensure_parent_dir
+from provide.foundation.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+@define(slots=True)
+class TarArchive(BaseArchive):
+    """
+    TAR archive implementation.
+    
+    Creates and extracts TAR archives with optional metadata preservation
+    and deterministic output for reproducible builds.
+    """
+    
+    deterministic: bool = field(default=True)
+    preserve_metadata: bool = field(default=True)
+    preserve_permissions: bool = field(default=True)
+    
+    def create(self, source: Path, output: Path) -> Path:
+        """
+        Create TAR archive from source.
+        
+        Args:
+            source: Source file or directory to archive
+            output: Output TAR file path
+            
+        Returns:
+            Path to created archive
+            
+        Raises:
+            ArchiveError: If archive creation fails
+        """
+        try:
+            ensure_parent_dir(output)
+            
+            with tarfile.open(output, "w") as tar:
+                if source.is_dir():
+                    # Add all files in directory
+                    for item in sorted(source.rglob("*")):
+                        if item.is_file():
+                            arcname = item.relative_to(source.parent)
+                            self._add_file(tar, item, arcname)
+                else:
+                    # Add single file
+                    self._add_file(tar, source, source.name)
+            
+            logger.debug(f"Created TAR archive: {output}")
+            return output
+            
+        except Exception as e:
+            raise ArchiveError(f"Failed to create TAR archive: {e}") from e
+
+    def extract(self, archive: Path, output: Path) -> Path:
+        """
+        Extract TAR archive to output directory.
+        
+        Args:
+            archive: TAR archive file path
+            output: Output directory path
+            
+        Returns:
+            Path to extraction directory
+            
+        Raises:
+            ArchiveError: If extraction fails
+        """
+        try:
+            output.mkdir(parents=True, exist_ok=True)
+            
+            with tarfile.open(archive, "r") as tar:
+                # Security check - prevent path traversal
+                for member in tar.getmembers():
+                    if member.name.startswith("/") or ".." in member.name:
+                        raise ArchiveError(f"Unsafe path in archive: {member.name}")
+                
+                # Extract all
+                tar.extractall(output)
+            
+            logger.debug(f"Extracted TAR archive to: {output}")
+            return output
+            
+        except Exception as e:
+            raise ArchiveError(f"Failed to extract TAR archive: {e}") from e
+
+    def validate(self, archive: Path) -> bool:
+        """
+        Validate TAR archive integrity.
+        
+        Args:
+            archive: TAR archive file path
+            
+        Returns:
+            True if archive is valid, False otherwise
+        """
+        try:
+            with tarfile.open(archive, "r") as tar:
+                # Try to read all members
+                for member in tar.getmembers():
+                    # Just checking we can read the metadata
+                    pass
+            return True
+        except Exception:
+            return False
+    
+    def list_contents(self, archive: Path) -> list[str]:
+        """
+        List contents of TAR archive.
+        
+        Args:
+            archive: TAR archive file path
+            
+        Returns:
+            List of file paths in archive
+            
+        Raises:
+            ArchiveError: If listing fails
+        """
+        try:
+            contents = []
+            with tarfile.open(archive, "r") as tar:
+                for member in tar.getmembers():
+                    if member.isfile():
+                        contents.append(member.name)
+            return sorted(contents)
+        except Exception as e:
+            raise ArchiveError(f"Failed to list TAR contents: {e}") from e
+    
+    def _add_file(self, tar: tarfile.TarFile, file_path: Path, arcname: str | Path) -> None:
+        """
+        Add single file to TAR archive.
+        
+        Args:
+            tar: Open TarFile object
+            file_path: Path to file to add
+            arcname: Name in archive
+        """
+        tarinfo = tar.gettarinfo(str(file_path), str(arcname))
+        
+        if self.deterministic:
+            # Set consistent metadata for reproducible archives
+            tarinfo.uid = 0
+            tarinfo.gid = 0
+            tarinfo.uname = ""
+            tarinfo.gname = ""
+            tarinfo.mtime = 0
+        
+        if not self.preserve_permissions:
+            # Normalize permissions
+            if tarinfo.isfile():
+                tarinfo.mode = 0o644
+            elif tarinfo.isdir():
+                tarinfo.mode = 0o755
+        
+        with open(file_path, "rb") as f:
+            tar.addfile(tarinfo, f)

provide/foundation/archive/zip.py

@@ -0,0 +1,203 @@
+"""ZIP archive implementation."""
+
+import zipfile
+from pathlib import Path
+from attrs import define, field
+
+from provide.foundation.archive.base import BaseArchive, ArchiveError
+from provide.foundation.file import ensure_parent_dir
+from provide.foundation.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+@define(slots=True)
+class ZipArchive(BaseArchive):
+    """
+    ZIP archive implementation.
+    
+    Creates and extracts ZIP archives with optional compression and encryption.
+    Supports adding files to existing archives.
+    """
+    
+    compression_level: int = field(default=6)  # Compression level 0-9 (0=store, 9=best)
+    compression_type: int = field(default=zipfile.ZIP_DEFLATED)
+    password: bytes | None = field(default=None)
+    
+    @compression_level.validator
+    def _validate_level(self, attribute, value):
+        if not 0 <= value <= 9:
+            raise ValueError(f"Compression level must be 0-9, got {value}")
+    
+    def create(self, source: Path, output: Path) -> Path:
+        """
+        Create ZIP archive from source.
+        
+        Args:
+            source: Source file or directory to archive
+            output: Output ZIP file path
+            
+        Returns:
+            Path to created archive
+            
+        Raises:
+            ArchiveError: If archive creation fails
+        """
+        try:
+            ensure_parent_dir(output)
+            
+            with zipfile.ZipFile(
+                output, 'w', 
+                compression=self.compression_type,
+                compresslevel=self.compression_level
+            ) as zf:
+                if self.password:
+                    zf.setpassword(self.password)
+                
+                if source.is_dir():
+                    # Add all files in directory
+                    for item in sorted(source.rglob("*")):
+                        if item.is_file():
+                            arcname = item.relative_to(source)
+                            zf.write(item, arcname)
+                else:
+                    # Add single file
+                    zf.write(source, source.name)
+            
+            logger.debug(f"Created ZIP archive: {output}")
+            return output
+            
+        except Exception as e:
+            raise ArchiveError(f"Failed to create ZIP archive: {e}") from e
+
+    def extract(self, archive: Path, output: Path) -> Path:
+        """
+        Extract ZIP archive to output directory.
+        
+        Args:
+            archive: ZIP archive file path
+            output: Output directory path
+            
+        Returns:
+            Path to extraction directory
+            
+        Raises:
+            ArchiveError: If extraction fails
+        """
+        try:
+            output.mkdir(parents=True, exist_ok=True)
+            
+            with zipfile.ZipFile(archive, 'r') as zf:
+                if self.password:
+                    zf.setpassword(self.password)
+                
+                # Security check - prevent path traversal
+                for member in zf.namelist():
+                    if member.startswith("/") or ".." in member:
+                        raise ArchiveError(f"Unsafe path in archive: {member}")
+                
+                # Extract all
+                zf.extractall(output)
+            
+            logger.debug(f"Extracted ZIP archive to: {output}")
+            return output
+            
+        except Exception as e:
+            raise ArchiveError(f"Failed to extract ZIP archive: {e}") from e
+
+    def validate(self, archive: Path) -> bool:
+        """
+        Validate ZIP archive integrity.
+        
+        Args:
+            archive: ZIP archive file path
+            
+        Returns:
+            True if archive is valid, False otherwise
+        """
+        try:
+            with zipfile.ZipFile(archive, 'r') as zf:
+                # Test the archive
+                result = zf.testzip()
+                return result is None  # None means no bad files
+        except Exception:
+            return False
+    
+    def list_contents(self, archive: Path) -> list[str]:
+        """
+        List contents of ZIP archive.
+        
+        Args:
+            archive: ZIP archive file path
+            
+        Returns:
+            List of file paths in archive
+            
+        Raises:
+            ArchiveError: If listing fails
+        """
+        try:
+            with zipfile.ZipFile(archive, 'r') as zf:
+                return sorted(zf.namelist())
+        except Exception as e:
+            raise ArchiveError(f"Failed to list ZIP contents: {e}") from e
+    
+    def add_file(self, archive: Path, file: Path, arcname: str | None = None) -> None:
+        """
+        Add file to existing ZIP archive.
+        
+        Args:
+            archive: ZIP archive file path
+            file: File to add
+            arcname: Name in archive (defaults to file name)
+            
+        Raises:
+            ArchiveError: If adding file fails
+        """
+        try:
+            with zipfile.ZipFile(archive, 'a', compression=self.compression_type) as zf:
+                if self.password:
+                    zf.setpassword(self.password)
+                
+                zf.write(file, arcname or file.name)
+            
+            logger.debug(f"Added {file} to ZIP archive {archive}")
+            
+        except Exception as e:
+            raise ArchiveError(f"Failed to add file to ZIP: {e}") from e
+    
+    def extract_file(self, archive: Path, member: str, output: Path) -> Path:
+        """
+        Extract single file from ZIP archive.
+        
+        Args:
+            archive: ZIP archive file path
+            member: Name of file in archive
+            output: Output directory or file path
+            
+        Returns:
+            Path to extracted file
+            
+        Raises:
+            ArchiveError: If extraction fails
+        """
+        try:
+            with zipfile.ZipFile(archive, 'r') as zf:
+                if self.password:
+                    zf.setpassword(self.password)
+                
+                # Security check
+                if member.startswith("/") or ".." in member:
+                    raise ArchiveError(f"Unsafe path: {member}")
+                
+                if output.is_dir():
+                    zf.extract(member, output)
+                    return output / member
+                else:
+                    ensure_parent_dir(output)
+                    with zf.open(member) as source, open(output, 'wb') as target:
+                        target.write(source.read())
+                    return output
+                    
+        except Exception as e:
+            raise ArchiveError(f"Failed to extract file from ZIP: {e}") from e