provide-foundation 0.0.0.dev2__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

@@ -21,8 +21,6 @@ from provide.foundation.cli.testing import (
     isolated_cli_runner,
     temp_config_file,
 )
-from provide.foundation.testing.cli import MockContext
-from provide.foundation.testing.logger import mock_logger
 from provide.foundation.cli.utils import (
     CliTestRunner,
     assert_cli_error,
@@ -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,12 +8,12 @@ except ImportError:
     click = None
     _HAS_CLICK = False
 
-from provide.foundation.utils.deps import check_optional_deps, has_dependency
 from provide.foundation.console.output import pout
-from provide.foundation.process import exit_success, exit_error
+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(
@@ -68,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,7 +21,7 @@ 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)
@@ -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:
@@ -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:

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:
@@ -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:

provide/foundation/cli/testing.py

@@ -6,7 +6,6 @@ import os
 from pathlib import Path
 import tempfile
 from typing import Any
-from unittest.mock import MagicMock
 
 import click
 from click.testing import CliRunner
@@ -17,8 +16,6 @@ from provide.foundation.logger import get_logger
 log = get_logger(__name__)
 
 
-
-
 @contextmanager
 def isolated_cli_runner(
     env: dict[str, str] | None = None,
@@ -140,8 +137,6 @@ def create_test_cli(
     return cli
 
 
-
-
 class CliTestCase:
     """Base class for CLI test cases with common utilities."""
 

provide/foundation/cli/utils.py

@@ -1,12 +1,11 @@
 """Common CLI utilities for output, logging, and testing."""
 
-import json
 from typing import Any
 
 import click
 from click.testing import CliRunner, Result
 
-from provide.foundation.console.output import pout, perr
+from provide.foundation.console.output import perr, pout
 from provide.foundation.context import CLIContext
 from provide.foundation.logger import (
     LoggingConfig,

provide/foundation/config/__init__.py

@@ -9,6 +9,25 @@ from provide.foundation.config.base import (
     BaseConfig,
     field,
 )
+from provide.foundation.config.converters import (
+    parse_bool_extended,
+    parse_comma_list,
+    parse_console_formatter,
+    parse_float_with_validation,
+    parse_headers,
+    parse_json_dict,
+    parse_json_list,
+    parse_log_level,
+    parse_module_levels,
+    parse_rate_limits,
+    parse_sample_rate,
+    validate_log_level,
+    validate_non_negative,
+    validate_overflow_policy,
+    validate_port,
+    validate_positive,
+    validate_sample_rate,
+)
 from provide.foundation.config.env import (
     RuntimeConfig,
     env_field,
@@ -45,25 +64,6 @@ from provide.foundation.config.types import (
     ConfigSource,
     ConfigValue,
 )
-from provide.foundation.config.converters import (
-    parse_bool_extended,
-    parse_comma_list,
-    parse_console_formatter,
-    parse_float_with_validation,
-    parse_headers,
-    parse_json_dict,
-    parse_json_list,
-    parse_log_level,
-    parse_module_levels,
-    parse_rate_limits,
-    parse_sample_rate,
-    validate_log_level,
-    validate_non_negative,
-    validate_overflow_policy,
-    validate_port,
-    validate_positive,
-    validate_sample_rate,
-)
 from provide.foundation.config.validators import (
     validate_choice,
     validate_range,

provide/foundation/config/base.py

@@ -87,7 +87,7 @@ class BaseConfig:
     _source_map: dict[str, ConfigSource] = attrs_field(init=False, factory=lambda: {})
     _original_values: dict[str, Any] = attrs_field(init=False, factory=lambda: {})
 
-    def __attrs_post_init__(self):
+    def __attrs_post_init__(self) -> None:
         """Post-initialization hook for subclasses."""
         # The _source_map and _original_values are now handled by attrs with factory
         # Note: validate() is now async, so we can't call it here
@@ -175,7 +175,7 @@ class BaseConfig:
             Configuration instance
         """
         # Filter data to only include fields defined in the class, excluding private fields
-        field_names = {f.name for f in fields(cls) if not f.name.startswith('_')}
+        field_names = {f.name for f in fields(cls) if not f.name.startswith("_")}
         filtered_data = {k: v for k, v in data.items() if k in field_names}
 
         # Create instance