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

provide/foundation/__init__.py

@@ -9,12 +9,12 @@ Primary public interface for the library, re-exporting common components.
 # Export config module for easy access
 # New foundation components
 # Make the errors module available for detailed imports
-from provide.foundation import config, errors, platform, process
+from provide.foundation import config, errors, platform, process, resilience
 from provide.foundation._version import __version__
 
 # Console I/O functions (always available - handles click dependency internally)
 from provide.foundation.console import perr, pin, pout
-from provide.foundation.context import Context
+from provide.foundation.context import CLIContext, Context
 
 # Error handling exports - only the essentials
 from provide.foundation.errors import (
@@ -27,6 +27,19 @@ from provide.foundation.errors import (
     with_error_handling,
 )
 
+# Resilience exports
+from provide.foundation.resilience import (
+    retry,
+    circuit_breaker,
+    fallback,
+    RetryPolicy,
+    RetryExecutor,
+    BackoffStrategy,
+    CircuitBreaker,
+    CircuitState,
+    FallbackChain,
+)
+
 # Hub and Registry exports (public API)
 from provide.foundation.hub.components import ComponentCategory, get_component_registry
 from provide.foundation.hub.manager import Hub, clear_hub, get_hub
@@ -39,17 +52,12 @@ from provide.foundation.logger import (
     setup_logging,  # Setup function (backward compatibility)
 )
 
-# Emoji exports
-from provide.foundation.logger.emoji.matrix import (
-    PRIMARY_EMOJI,
-    SECONDARY_EMOJI,
-    TERTIARY_EMOJI,
-    show_emoji_matrix,
-)
-from provide.foundation.logger.emoji.types import (
-    EmojiSet,
-    EmojiSetConfig,
-    FieldToEmojiMapping,
+# Event set exports
+from provide.foundation.eventsets.display import show_event_matrix
+from provide.foundation.eventsets.types import (
+    EventMapping,
+    EventSet,
+    FieldMapping,
 )
 from provide.foundation.setup import (
     setup_telemetry,
@@ -93,15 +101,16 @@ def __getattr__(name: str):
 
 
 __all__ = [
-    # Core Emoji Dictionaries (available for direct use or reference)
-    "PRIMARY_EMOJI",
-    "SECONDARY_EMOJI",
-    "TERTIARY_EMOJI",
+    # Event enrichment utilities
+    "show_event_matrix",
     "ConsoleFormatterStr",
     # New foundation modules
-    "Context",
-    # Emoji Mapping classes
-    "EmojiSet",
+    "CLIContext",
+    "Context",  # Backward compatibility
+    # Event set types
+    "EventMapping",
+    "EventSet",
+    "FieldMapping",
     # Error handling essentials
     "FoundationError",
     # Type aliases
@@ -115,8 +124,6 @@ __all__ = [
     "get_component_registry",
     "get_hub",
     "clear_hub",
-    "FieldToEmojiMapping",
-    "EmojiSetConfig",
     # Configuration classes
     "TelemetryConfig",
     # Version
@@ -136,12 +143,23 @@ __all__ = [
     "pout",
     "platform",
     "process",
+    # Resilience patterns
+    "retry",
+    "circuit_breaker", 
+    "fallback",
+    "RetryPolicy",
+    "RetryExecutor",
+    "BackoffStrategy",
+    "CircuitBreaker",
+    "CircuitState", 
+    "FallbackChain",
+    # Backward compatibility (deprecated)
     "retry_on_error",
+    "resilience",  # The resilience module for detailed imports
     "setup_logging",  # Backward compatibility
     "setup_logger",  # Consistent naming
     "setup_telemetry",
     # Utilities
-    "show_emoji_matrix",
     "shutdown_foundation_telemetry",
     "timed_block",
     # Rate limiting utilities

provide/foundation/archive/__init__.py

@@ -0,0 +1,23 @@
+"""Archive operations for provide-foundation.
+
+This module provides clean, composable archive operations without complex abstractions.
+Tools for creating, extracting, and manipulating archives in various formats.
+"""
+
+from provide.foundation.archive.base import ArchiveError, BaseArchive
+from provide.foundation.archive.bzip2 import Bzip2Compressor
+from provide.foundation.archive.gzip import GzipCompressor
+from provide.foundation.archive.operations import ArchiveOperations, OperationChain
+from provide.foundation.archive.tar import TarArchive
+from provide.foundation.archive.zip import ZipArchive
+
+__all__ = [
+    "ArchiveError",
+    "ArchiveOperations",
+    "BaseArchive",
+    "Bzip2Compressor",
+    "GzipCompressor",
+    "OperationChain",
+    "TarArchive",
+    "ZipArchive",
+]

provide/foundation/archive/base.py

@@ -0,0 +1,70 @@
+"""Base classes and interfaces for archive operations."""
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+from provide.foundation.errors import FoundationError
+
+
+class ArchiveError(FoundationError):
+    """Base exception for archive-related errors."""
+    pass
+
+
+class BaseArchive(ABC):
+    """
+    Abstract base class for all archive implementations.
+    
+    This defines the common interface that all archive implementations
+    must follow, ensuring consistency across different archive formats.
+    """
+    
+    @abstractmethod
+    def create(self, source: Path, output: Path) -> Path:
+        """
+        Create an archive from source path.
+        
+        Args:
+            source: Source file or directory to archive
+            output: Output archive file path
+            
+        Returns:
+            Path to the created archive file
+            
+        Raises:
+            ArchiveError: If archive creation fails
+        """
+        pass
+    
+    @abstractmethod
+    def extract(self, archive: Path, output: Path) -> Path:
+        """
+        Extract an archive to output path.
+        
+        Args:
+            archive: Archive file to extract
+            output: Output directory for extracted contents
+            
+        Returns:
+            Path to the extraction directory
+            
+        Raises:
+            ArchiveError: If extraction fails
+        """
+        pass
+    
+    @abstractmethod
+    def validate(self, archive: Path) -> bool:
+        """
+        Validate that an archive is properly formed.
+        
+        Args:
+            archive: Archive file to validate
+            
+        Returns:
+            True if archive is valid, False otherwise
+            
+        Raises:
+            ArchiveError: If validation cannot be performed
+        """
+        pass

provide/foundation/archive/bzip2.py

@@ -0,0 +1,157 @@
+"""BZIP2 compression implementation."""
+
+import bz2
+import shutil
+from pathlib import Path
+from typing import BinaryIO
+
+from attrs import define, field
+
+from provide.foundation.archive.base import ArchiveError
+from provide.foundation.file import ensure_parent_dir
+from provide.foundation.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+@define(slots=True)
+class Bzip2Compressor:
+    """
+    BZIP2 compression implementation.
+    
+    Provides BZIP2 compression and decompression for single files.
+    Does not handle bundling - use with TarArchive for .tar.bz2 files.
+    """
+    
+    level: int = field(default=9)  # Compression level 1-9 (1=fast, 9=best)
+    
+    @level.validator
+    def _validate_level(self, attribute, value):
+        if not 1 <= value <= 9:
+            raise ValueError(f"Compression level must be 1-9, got {value}")
+    
+    def compress(self, input_stream: BinaryIO, output_stream: BinaryIO) -> None:
+        """
+        Compress data from input stream to output stream.
+        
+        Args:
+            input_stream: Input binary stream
+            output_stream: Output binary stream
+            
+        Raises:
+            ArchiveError: If compression fails
+        """
+        try:
+            with bz2.BZ2File(output_stream, 'wb', compresslevel=self.level) as bz:
+                shutil.copyfileobj(input_stream, bz)
+            logger.debug(f"Compressed data with BZIP2 level {self.level}")
+        except Exception as e:
+            raise ArchiveError(f"Failed to compress with BZIP2: {e}") from e
+    
+    def decompress(self, input_stream: BinaryIO, output_stream: BinaryIO) -> None:
+        """
+        Decompress data from input stream to output stream.
+        
+        Args:
+            input_stream: Input binary stream (bzip2 compressed)
+            output_stream: Output binary stream
+            
+        Raises:
+            ArchiveError: If decompression fails
+        """
+        try:
+            with bz2.BZ2File(input_stream, 'rb') as bz:
+                shutil.copyfileobj(bz, output_stream)
+            logger.debug("Decompressed BZIP2 data")
+        except Exception as e:
+            raise ArchiveError(f"Failed to decompress BZIP2: {e}") from e
+    
+    def compress_file(self, input_path: Path, output_path: Path) -> Path:
+        """
+        Compress a file.
+        
+        Args:
+            input_path: Input file path
+            output_path: Output file path (should end with .bz2)
+            
+        Returns:
+            Path to compressed file
+            
+        Raises:
+            ArchiveError: If compression fails
+        """
+        try:
+            ensure_parent_dir(output_path)
+            
+            with open(input_path, 'rb') as f_in:
+                with bz2.open(output_path, 'wb', compresslevel=self.level) as f_out:
+                    shutil.copyfileobj(f_in, f_out)
+            
+            logger.debug(f"Compressed {input_path} to {output_path}")
+            return output_path
+            
+        except Exception as e:
+            raise ArchiveError(f"Failed to compress file: {e}") from e
+    
+    def decompress_file(self, input_path: Path, output_path: Path) -> Path:
+        """
+        Decompress a file.
+        
+        Args:
+            input_path: Input file path (bzip2 compressed)
+            output_path: Output file path
+            
+        Returns:
+            Path to decompressed file
+            
+        Raises:
+            ArchiveError: If decompression fails
+        """
+        try:
+            ensure_parent_dir(output_path)
+            
+            with bz2.open(input_path, 'rb') as f_in:
+                with open(output_path, 'wb') as f_out:
+                    shutil.copyfileobj(f_in, f_out)
+            
+            logger.debug(f"Decompressed {input_path} to {output_path}")
+            return output_path
+            
+        except Exception as e:
+            raise ArchiveError(f"Failed to decompress file: {e}") from e
+    
+    def compress_bytes(self, data: bytes) -> bytes:
+        """
+        Compress bytes data.
+        
+        Args:
+            data: Input bytes
+            
+        Returns:
+            Compressed bytes
+            
+        Raises:
+            ArchiveError: If compression fails
+        """
+        try:
+            return bz2.compress(data, compresslevel=self.level)
+        except Exception as e:
+            raise ArchiveError(f"Failed to compress bytes: {e}") from e
+    
+    def decompress_bytes(self, data: bytes) -> bytes:
+        """
+        Decompress bytes data.
+        
+        Args:
+            data: Compressed bytes
+            
+        Returns:
+            Decompressed bytes
+            
+        Raises:
+            ArchiveError: If decompression fails
+        """
+        try:
+            return bz2.decompress(data)
+        except Exception as e:
+            raise ArchiveError(f"Failed to decompress bytes: {e}") from e

provide/foundation/archive/gzip.py

@@ -0,0 +1,159 @@
+"""GZIP compression implementation."""
+
+import gzip
+import shutil
+from io import BytesIO
+from pathlib import Path
+from typing import BinaryIO
+
+from attrs import define, field
+
+from provide.foundation.archive.base import ArchiveError
+from provide.foundation.file import ensure_parent_dir
+from provide.foundation.file.utils import get_size
+from provide.foundation.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+@define(slots=True)
+class GzipCompressor:
+    """
+    GZIP compression implementation.
+    
+    Provides GZIP compression and decompression for single files.
+    Does not handle bundling - use with TarArchive for .tar.gz files.
+    """
+    
+    level: int = field(default=6)  # Compression level 1-9 (1=fast, 9=best)
+    
+    @level.validator
+    def _validate_level(self, attribute, value):
+        if not 1 <= value <= 9:
+            raise ValueError(f"Compression level must be 1-9, got {value}")
+    
+    def compress(self, input_stream: BinaryIO, output_stream: BinaryIO) -> None:
+        """
+        Compress data from input stream to output stream.
+        
+        Args:
+            input_stream: Input binary stream
+            output_stream: Output binary stream
+            
+        Raises:
+            ArchiveError: If compression fails
+        """
+        try:
+            with gzip.GzipFile(fileobj=output_stream, mode='wb', compresslevel=self.level) as gz:
+                shutil.copyfileobj(input_stream, gz)
+            logger.debug(f"Compressed data with GZIP level {self.level}")
+        except Exception as e:
+            raise ArchiveError(f"Failed to compress with GZIP: {e}") from e
+    
+    def decompress(self, input_stream: BinaryIO, output_stream: BinaryIO) -> None:
+        """
+        Decompress data from input stream to output stream.
+        
+        Args:
+            input_stream: Input binary stream (gzipped)
+            output_stream: Output binary stream
+            
+        Raises:
+            ArchiveError: If decompression fails
+        """
+        try:
+            with gzip.GzipFile(fileobj=input_stream, mode='rb') as gz:
+                shutil.copyfileobj(gz, output_stream)
+            logger.debug("Decompressed GZIP data")
+        except Exception as e:
+            raise ArchiveError(f"Failed to decompress GZIP: {e}") from e
+    
+    def compress_file(self, input_path: Path, output_path: Path) -> Path:
+        """
+        Compress a file.
+        
+        Args:
+            input_path: Input file path
+            output_path: Output file path (should end with .gz)
+            
+        Returns:
+            Path to compressed file
+            
+        Raises:
+            ArchiveError: If compression fails
+        """
+        try:
+            ensure_parent_dir(output_path)
+            
+            with open(input_path, 'rb') as f_in:
+                with gzip.open(output_path, 'wb', compresslevel=self.level) as f_out:
+                    shutil.copyfileobj(f_in, f_out)
+            
+            logger.debug(f"Compressed {input_path} to {output_path}")
+            return output_path
+            
+        except Exception as e:
+            raise ArchiveError(f"Failed to compress file: {e}") from e
+    
+    def decompress_file(self, input_path: Path, output_path: Path) -> Path:
+        """
+        Decompress a file.
+        
+        Args:
+            input_path: Input file path (gzipped)
+            output_path: Output file path
+            
+        Returns:
+            Path to decompressed file
+            
+        Raises:
+            ArchiveError: If decompression fails
+        """
+        try:
+            ensure_parent_dir(output_path)
+            
+            with gzip.open(input_path, 'rb') as f_in:
+                with open(output_path, 'wb') as f_out:
+                    shutil.copyfileobj(f_in, f_out)
+            
+            logger.debug(f"Decompressed {input_path} to {output_path}")
+            return output_path
+            
+        except Exception as e:
+            raise ArchiveError(f"Failed to decompress file: {e}") from e
+    
+    def compress_bytes(self, data: bytes) -> bytes:
+        """
+        Compress bytes data.
+        
+        Args:
+            data: Input bytes
+            
+        Returns:
+            Compressed bytes
+            
+        Raises:
+            ArchiveError: If compression fails
+        """
+        try:
+            return gzip.compress(data, compresslevel=self.level)
+        except Exception as e:
+            raise ArchiveError(f"Failed to compress bytes: {e}") from e
+    
+    def decompress_bytes(self, data: bytes) -> bytes:
+        """
+        Decompress bytes data.
+        
+        Args:
+            data: Compressed bytes
+            
+        Returns:
+            Decompressed bytes
+            
+        Raises:
+            ArchiveError: If decompression fails
+        """
+        try:
+            return gzip.decompress(data)
+        except Exception as e:
+            raise ArchiveError(f"Failed to decompress bytes: {e}") from e