provide-foundation 0.0.0.dev1__py3-none-any.whl → 0.0.0.dev3__py3-none-any.whl

provide/foundation/archive/zip.py

@@ -1,10 +1,11 @@
 """ZIP archive implementation."""
 
-import zipfile
 from pathlib import Path
+import zipfile
+
 from attrs import define, field
 
-from provide.foundation.archive.base import BaseArchive, ArchiveError
+from provide.foundation.archive.base import ArchiveError, BaseArchive
 from provide.foundation.file import ensure_parent_dir
 from provide.foundation.logger import get_logger
 
@@ -15,45 +16,46 @@ logger = get_logger(__name__)
 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):
+    def _validate_level(self, attribute: object, value: int) -> None:
         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', 
+                output,
+                "w",
                 compression=self.compression_type,
-                compresslevel=self.compression_level
+                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("*")):
@@ -63,141 +65,141 @@ class ZipArchive(BaseArchive):
                 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:
+
+            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:
+            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:
+            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:
+            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:
+            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:
+                    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
+            raise ArchiveError(f"Failed to extract file from ZIP: {e}") from e

provide/foundation/asynctools/__init__.py

@@ -0,0 +1,20 @@
+"""
+Async utilities for Foundation.
+
+Provides consistent async/await patterns, task management,
+and async context utilities for Foundation applications.
+"""
+
+from provide.foundation.asynctools.core import (
+    provide_gather,
+    provide_run,
+    provide_sleep_async,
+    provide_wait_for,
+)
+
+__all__ = [
+    "provide_gather",
+    "provide_run",
+    "provide_sleep_async",
+    "provide_wait_for",
+]

provide/foundation/asynctools/core.py

@@ -0,0 +1,126 @@
+"""Core async utilities for Foundation."""
+
+import asyncio
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from provide.foundation.errors import ValidationError
+
+
+async def provide_sleep_async(delay: float) -> None:
+    """
+    Async sleep with Foundation tracking and cancellation support.
+
+    Args:
+        delay: Number of seconds to sleep
+
+    Raises:
+        ValidationError: If delay is negative
+
+    Example:
+        >>> import asyncio
+        >>> async def main():
+        ...     await provide_sleep_async(0.1)
+        >>> asyncio.run(main())
+    """
+    if delay < 0:
+        raise ValidationError("Sleep delay must be non-negative")
+    await asyncio.sleep(delay)
+
+
+async def provide_gather(
+    *awaitables: Awaitable[Any], return_exceptions: bool = False
+) -> list[Any]:
+    """
+    Run awaitables concurrently with Foundation tracking.
+
+    Args:
+        *awaitables: Awaitable objects to run concurrently
+        return_exceptions: If True, exceptions are returned as results
+
+    Returns:
+        List of results in the same order as input awaitables
+
+    Raises:
+        ValidationError: If no awaitables provided
+
+    Example:
+        >>> import asyncio
+        >>> async def fetch_data(n):
+        ...     await provide_sleep_async(0.1)
+        ...     return n * 2
+        >>> async def main():
+        ...     results = await provide_gather(
+        ...         fetch_data(1), fetch_data(2), fetch_data(3)
+        ...     )
+        ...     return results
+        >>> asyncio.run(main())
+        [2, 4, 6]
+    """
+    if not awaitables:
+        raise ValidationError("At least one awaitable must be provided")
+
+    return await asyncio.gather(*awaitables, return_exceptions=return_exceptions)
+
+
+async def provide_wait_for(awaitable: Awaitable[Any], timeout: float | None) -> Any:
+    """
+    Wait for an awaitable with optional timeout.
+
+    Args:
+        awaitable: The awaitable to wait for
+        timeout: Timeout in seconds (None for no timeout)
+
+    Returns:
+        Result of the awaitable
+
+    Raises:
+        ValidationError: If timeout is negative
+        asyncio.TimeoutError: If timeout is exceeded
+
+    Example:
+        >>> import asyncio
+        >>> async def slow_task():
+        ...     await provide_sleep_async(0.2)
+        ...     return "done"
+        >>> async def main():
+        ...     try:
+        ...         result = await provide_wait_for(slow_task(), timeout=0.1)
+        ...     except asyncio.TimeoutError:
+        ...         result = "timed out"
+        ...     return result
+        >>> asyncio.run(main())
+        'timed out'
+    """
+    if timeout is not None and timeout < 0:
+        raise ValidationError("Timeout must be non-negative")
+
+    return await asyncio.wait_for(awaitable, timeout=timeout)
+
+
+def provide_run(main: Callable[[], Awaitable[Any]], *, debug: bool = False) -> Any:
+    """
+    Run async function with Foundation tracking.
+
+    Args:
+        main: Async function to run
+        debug: Whether to run in debug mode
+
+    Returns:
+        Result of the main function
+
+    Raises:
+        ValidationError: If main is not callable
+
+    Example:
+        >>> async def main():
+        ...     await provide_sleep_async(0.1)
+        ...     return "hello"
+        >>> result = provide_run(main)
+        >>> result
+        'hello'
+    """
+    if not callable(main):
+        raise ValidationError("Main must be callable")
+
+    return asyncio.run(main(), debug=debug)

provide/foundation/cli/__init__.py

@@ -17,10 +17,8 @@ from provide.foundation.cli.decorators import (
 )
 from provide.foundation.cli.testing import (
     CliTestCase,
-    MockContext,
     create_test_cli,
     isolated_cli_runner,
-    mock_logger,
     temp_config_file,
 )
 from provide.foundation.cli.utils import (
@@ -35,6 +33,8 @@ from provide.foundation.cli.utils import (
     echo_warning,
     setup_cli_logging,
 )
+from provide.foundation.testing.cli import MockContext
+from provide.foundation.testing.logger import mock_logger
 
 __all__ = [
     "CliTestCase",

provide/foundation/cli/commands/deps.py

@@ -8,10 +8,12 @@ except ImportError:
     click = None
     _HAS_CLICK = False
 
-from provide.foundation.utils.deps import check_optional_deps
+from provide.foundation.console.output import pout
+from provide.foundation.process import exit_error, exit_success
+from provide.foundation.utils.deps import check_optional_deps, has_dependency
 
 
-def _require_click():
+def _require_click() -> None:
     """Ensure click is available for CLI commands."""
     if not _HAS_CLICK:
         raise ImportError(
@@ -23,21 +25,25 @@ def _require_click():
 def _deps_command_impl(quiet: bool, check: str | None) -> None:
     """Implementation of deps command logic."""
     if check:
-        from provide.foundation.utils.deps import has_dependency
-
         available = has_dependency(check)
         if not quiet:
             status = "✅" if available else "❌"
-            print(f"{status} {check}: {'Available' if available else 'Missing'}")
+            pout(f"{status} {check}: {'Available' if available else 'Missing'}")
             if not available:
-                print(f"Install with: pip install 'provide-foundation[{check}]'")
-        exit(0 if available else 1)
+                pout(f"Install with: pip install 'provide-foundation[{check}]'")
+        if available:
+            exit_success()
+        else:
+            exit_error("Dependency check failed")
     else:
         # Check all dependencies
         deps = check_optional_deps(quiet=quiet, return_status=True)
         available_count = sum(1 for dep in deps if dep.available)
         total_count = len(deps)
-        exit(0 if available_count == total_count else 1)
+        if available_count == total_count:
+            exit_success()
+        else:
+            exit_error(f"Missing {total_count - available_count} dependencies")
 
 
 if _HAS_CLICK:
@@ -62,7 +68,7 @@ if _HAS_CLICK:
         _deps_command_impl(quiet, check)
 else:
     # Stub for when click is not available
-    def deps_command(*args, **kwargs):
+    def deps_command(*args: object, **kwargs: object) -> None:
         """Deps command stub when click is not available."""
         _require_click()
 

provide/foundation/cli/commands/logs/__init__.py

@@ -21,14 +21,14 @@ if _HAS_CLICK:
 
     @click.group("logs", help="Send and query logs with OpenTelemetry integration")
     @click.pass_context
-    def logs_group(ctx):
+    def logs_group(ctx: click.Context) -> None:
         """Logs management commands with OTEL correlation."""
         # Store shared context
         ctx.ensure_object(dict)
 
         # Try to get OpenObserve client if available
         try:
-            from provide.foundation.observability.openobserve import OpenObserveClient
+            from provide.foundation.integrations.openobserve import OpenObserveClient
 
             ctx.obj["client"] = OpenObserveClient.from_config()
         except Exception as e:
@@ -53,7 +53,7 @@ if _HAS_CLICK:
 
 else:
     # Stub when click is not available
-    def logs_group(*args, **kwargs):
+    def logs_group(*args: object, **kwargs: object) -> None:
         """Logs command stub when click is not available."""
         raise ImportError(
             "CLI commands require optional dependencies. "

provide/foundation/cli/commands/logs/generate.py

@@ -205,7 +205,7 @@ def generate_logs_command(
     error_rate: float,
     enable_rate_limit: bool,
     rate_limit: float,
-):
+) -> None:
     """Generate logs to test OpenObserve integration with Foundation's rate limiting."""
 
     click.echo("🚀 Starting log generation...")
@@ -351,7 +351,7 @@ def generate_logs_command(
 
 if not _HAS_CLICK:
 
-    def generate_logs_command(*args, **kwargs):
+    def generate_logs_command(*args: object, **kwargs: object) -> None:
         raise ImportError(
             "Click is required for CLI commands. Install with: pip install click"
         )

provide/foundation/cli/commands/logs/query.py

@@ -66,8 +66,8 @@ if _HAS_CLICK:
     )
     @click.pass_context
     def query_command(
-        ctx, sql, current_trace, trace_id, level, service, last, stream, size, format
-    ):
+        ctx: click.Context, sql: str | None, current_trace: bool, trace_id: str | None, level: str | None, service: str | None, last: str, stream: str, size: int, format: str
+    ) -> int | None:
         """Query logs from OpenObserve.
 
         Examples:
@@ -89,7 +89,7 @@ if _HAS_CLICK:
             # Custom SQL query
             foundation logs query --sql "SELECT * FROM default WHERE duration_ms > 1000"
         """
-        from provide.foundation.observability.openobserve import (
+        from provide.foundation.integrations.openobserve import (
             format_output,
             search_logs,
         )
@@ -166,7 +166,7 @@ if _HAS_CLICK:
 
 else:
 
-    def query_command(*args, **kwargs):
+    def query_command(*args: object, **kwargs: object) -> None:
         """Query command stub when click is not available."""
         raise ImportError(
             "CLI commands require optional dependencies. "

provide/foundation/cli/commands/logs/send.py

@@ -66,8 +66,8 @@ if _HAS_CLICK:
     )
     @click.pass_context
     def send_command(
-        ctx, message, level, service, json_attrs, attr, trace_id, span_id, use_otlp
-    ):
+        ctx: click.Context, message: str | None, level: str, service: str | None, json_attrs: str | None, attr: tuple[str, ...], trace_id: str | None, span_id: str | None, use_otlp: bool
+    ) -> int | None:
         """Send a log entry to OpenObserve.
 
         Examples:
@@ -83,7 +83,7 @@ if _HAS_CLICK:
             # Send with JSON attributes
             foundation logs send -m "Error occurred" -j '{"error_code": 500, "path": "/api/users"}'
         """
-        from provide.foundation.observability.openobserve.otlp import send_log
+        from provide.foundation.integrations.openobserve.otlp import send_log
 
         # Get message from stdin if not provided
         if not message:

provide/foundation/cli/commands/logs/tail.py

@@ -50,7 +50,7 @@ if _HAS_CLICK:
         help="Output format",
     )
     @click.pass_context
-    def tail_command(ctx, stream, filter_sql, lines, follow, format):
+    def tail_command(ctx: click.Context, stream: str, filter_sql: str | None, lines: int, follow: bool, format: str) -> int | None:
         """Tail logs in real-time (like 'tail -f').
 
         Examples:
@@ -69,7 +69,7 @@ if _HAS_CLICK:
             # Tail with JSON output
             foundation logs tail --format json
         """
-        from provide.foundation.observability.openobserve import (
+        from provide.foundation.integrations.openobserve import (
             format_output,
             tail_logs,
         )
@@ -104,7 +104,7 @@ if _HAS_CLICK:
 
 else:
 
-    def tail_command(*args, **kwargs):
+    def tail_command(*args: object, **kwargs: object) -> None:
         """Tail command stub when click is not available."""
         raise ImportError(
             "CLI commands require optional dependencies. "

provide/foundation/cli/decorators.py

@@ -3,7 +3,6 @@
 from collections.abc import Callable
 import functools
 from pathlib import Path
-import sys
 from typing import Any, TypeVar
 
 try:
@@ -11,7 +10,8 @@ try:
 except ImportError:
     click = None
 
-from provide.foundation.context import Context
+from provide.foundation.context import CLIContext
+from provide.foundation.process import exit_error, exit_interrupted
 
 F = TypeVar("F", bound=Callable[..., Any])
 
@@ -162,7 +162,7 @@ def error_handler(f: F) -> F:
         except KeyboardInterrupt:
             if not json_output:
                 click.secho("\nInterrupted by user", fg="yellow", err=True)
-            sys.exit(130)  # Standard exit code for SIGINT
+            exit_interrupted()
         except Exception as e:
             if debug:
                 # In debug mode, show full traceback
@@ -179,16 +179,16 @@ def error_handler(f: F) -> F:
             else:
                 click.secho(f"Error: {e}", fg="red", err=True)
 
-            sys.exit(1)
+            exit_error(f"Command failed: {str(e)}")
 
     return wrapper
 
 
 def pass_context(f: F) -> F:
     """
-    Decorator to pass the foundation Context to a command.
+    Decorator to pass the foundation CLIContext to a command.
 
-    Creates or retrieves a Context from Click's context object
+    Creates or retrieves a CLIContext from Click's context object
     and passes it as the first argument to the decorated function.
     """
 
@@ -197,15 +197,15 @@ def pass_context(f: F) -> F:
     def wrapper(ctx: click.Context, *args, **kwargs):
         # Get or create foundation context
         if not hasattr(ctx, "obj") or ctx.obj is None:
-            ctx.obj = Context()
-        elif not isinstance(ctx.obj, Context):
+            ctx.obj = CLIContext()
+        elif not isinstance(ctx.obj, CLIContext):
             # If obj exists but isn't a Context, wrap it
             if isinstance(ctx.obj, dict):
-                ctx.obj = Context.from_dict(ctx.obj)
+                ctx.obj = CLIContext.from_dict(ctx.obj)
             else:
-                # Store existing obj and create new Context
+                # Store existing obj and create new CLIContext
                 old_obj = ctx.obj
-                ctx.obj = Context()
+                ctx.obj = CLIContext()
                 ctx.obj._cli_data = old_obj
 
         # Update context from command options

provide/foundation/cli/main.py

@@ -46,7 +46,7 @@ if _HAS_CLICK:
 
     # Register OpenObserve commands if available
     try:
-        from provide.foundation.observability.openobserve.commands import (
+        from provide.foundation.integrations.openobserve.commands import (
             openobserve_group,
         )