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

provide/foundation/cli/main.py

@@ -0,0 +1,65 @@
+"""
+Main CLI entry point for Foundation.
+"""
+
+try:
+    import click
+
+    _HAS_CLICK = True
+except ImportError:
+    click = None
+    _HAS_CLICK = False
+
+
+def _require_click():
+    """Ensure click is available for CLI."""
+    if not _HAS_CLICK:
+        raise ImportError(
+            "CLI requires optional dependencies. "
+            "Install with: pip install 'provide-foundation[cli]'"
+        )
+
+
+if _HAS_CLICK:
+
+    @click.group()
+    @click.version_option()
+    def cli():
+        """Foundation CLI - Telemetry and observability tools."""
+        pass
+
+    # Register commands from commands module
+    try:
+        from provide.foundation.cli.commands.deps import deps_command
+
+        cli.add_command(deps_command)
+    except ImportError:
+        pass
+
+    # Register logs commands
+    try:
+        from provide.foundation.cli.commands.logs import logs_group
+
+        cli.add_command(logs_group)
+    except ImportError:
+        pass
+
+    # Register OpenObserve commands if available
+    try:
+        from provide.foundation.observability.openobserve.commands import (
+            openobserve_group,
+        )
+
+        cli.add_command(openobserve_group)
+    except ImportError:
+        pass
+
+else:
+
+    def cli():
+        """CLI stub when click is not available."""
+        _require_click()
+
+
+if __name__ == "__main__":
+    cli()

provide/foundation/cli/testing.py

@@ -0,0 +1,220 @@
+"""Testing utilities specifically for CLI applications."""
+
+from contextlib import contextmanager
+import json
+import os
+from pathlib import Path
+import tempfile
+from typing import Any
+from unittest.mock import MagicMock
+
+import click
+from click.testing import CliRunner
+
+from provide.foundation.context import Context
+from provide.foundation.logger import get_logger
+
+log = get_logger(__name__)
+
+
+class MockContext(Context):
+    """Mock context for testing that tracks method calls."""
+
+    def __init__(self, **kwargs) -> None:
+        """Initialize mock context with tracking."""
+        super().__init__(**kwargs)
+        self.calls = []
+        self.saved_configs = []
+        self.loaded_configs = []
+
+    def save_config(self, path: str | Path) -> None:
+        """Track save_config calls."""
+        self.saved_configs.append(path)
+        super().save_config(path)
+
+    def load_config(self, path: str | Path) -> None:
+        """Track load_config calls."""
+        self.loaded_configs.append(path)
+        super().load_config(path)
+
+
+@contextmanager
+def isolated_cli_runner(
+    env: dict[str, str] | None = None,
+):
+    """
+    Create an isolated test environment for CLI testing.
+
+    Args:
+        env: Environment variables to set
+
+    Yields:
+        CliRunner instance in isolated filesystem
+    """
+    runner = CliRunner()
+
+    with runner.isolated_filesystem():
+        # Set up environment
+        old_env = {}
+        if env:
+            for key, value in env.items():
+                old_env[key] = os.environ.get(key)
+                os.environ[key] = value
+
+        try:
+            yield runner
+        finally:
+            # Restore environment
+            for key, old_value in old_env.items():
+                if old_value is None:
+                    os.environ.pop(key, None)
+                else:
+                    os.environ[key] = old_value
+
+
+@contextmanager
+def temp_config_file(
+    content: dict[str, Any] | str,
+    format: str = "json",
+) -> Path:
+    """
+    Create a temporary configuration file for testing.
+
+    Args:
+        content: Configuration content (dict or string)
+        format: File format (json, toml, yaml)
+
+    Yields:
+        Path to temporary config file
+    """
+    suffix = f".{format}"
+
+    with tempfile.NamedTemporaryFile(
+        mode="w",
+        suffix=suffix,
+        delete=False,
+    ) as f:
+        if isinstance(content, dict):
+            if format == "json":
+                json.dump(content, f, indent=2)
+            elif format == "toml":
+                try:
+                    import tomli_w
+
+                    tomli_w.dump(content, f)
+                except ImportError:
+                    # Fall back to manual formatting
+                    for key, value in content.items():
+                        if isinstance(value, str):
+                            f.write(f'{key} = "{value}"\n')
+                        else:
+                            f.write(f"{key} = {value}\n")
+            elif format == "yaml":
+                try:
+                    import yaml
+
+                    yaml.safe_dump(content, f)
+                except ImportError:
+                    raise ImportError("PyYAML required for YAML testing")
+        else:
+            f.write(content)
+
+        config_path = Path(f.name)
+
+    try:
+        yield config_path
+    finally:
+        config_path.unlink(missing_ok=True)
+
+
+def create_test_cli(
+    name: str = "test-cli",
+    version: str = "1.0.0",
+    commands: list[click.Command] | None = None,
+) -> click.Group:
+    """
+    Create a test CLI group with standard options.
+
+    Args:
+        name: CLI name
+        version: CLI version
+        commands: Optional list of commands to add
+
+    Returns:
+        Click Group configured for testing
+    """
+    from provide.foundation.cli.decorators import standard_options
+
+    @click.group(name=name)
+    @standard_options
+    @click.pass_context
+    def cli(ctx, **kwargs) -> None:
+        """Test CLI for testing."""
+        ctx.obj = Context(**{k: v for k, v in kwargs.items() if v is not None})
+
+    if commands:
+        for cmd in commands:
+            cli.add_command(cmd)
+
+    return cli
+
+
+def mock_logger():
+    """
+    Create a mock logger for testing.
+
+    Returns:
+        MagicMock with common logger methods
+    """
+    mock = MagicMock()
+    mock.debug = MagicMock()
+    mock.info = MagicMock()
+    mock.warning = MagicMock()
+    mock.error = MagicMock()
+    mock.critical = MagicMock()
+    return mock
+
+
+class CliTestCase:
+    """Base class for CLI test cases with common utilities."""
+
+    def setup_method(self) -> None:
+        """Set up test case."""
+        self.runner = CliRunner()
+        self.temp_files = []
+
+    def teardown_method(self) -> None:
+        """Clean up test case."""
+        for path in self.temp_files:
+            if path.exists():
+                path.unlink()
+
+    def invoke(self, *args, **kwargs):
+        """Invoke CLI command."""
+        return self.runner.invoke(*args, **kwargs)
+
+    def create_temp_file(self, content: str = "", suffix: str = "") -> Path:
+        """Create a temporary file that will be cleaned up."""
+        with tempfile.NamedTemporaryFile(
+            mode="w",
+            suffix=suffix,
+            delete=False,
+        ) as f:
+            f.write(content)
+            path = Path(f.name)
+
+        self.temp_files.append(path)
+        return path
+
+    def assert_json_output(self, result, expected: dict[str, Any]) -> None:
+        """Assert that output is valid JSON matching expected."""
+        try:
+            output = json.loads(result.output)
+        except json.JSONDecodeError as e:
+            raise AssertionError(f"Output is not valid JSON: {e}\n{result.output}")
+
+        for key, value in expected.items():
+            assert key in output, f"Key '{key}' not in output"
+            assert output[key] == value, (
+                f"Value mismatch for '{key}': {output[key]} != {value}"
+            )

provide/foundation/cli/utils.py

@@ -0,0 +1,210 @@
+"""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.context import Context
+from provide.foundation.logger import (
+    LoggingConfig,
+    TelemetryConfig,
+    get_logger,
+)
+from provide.foundation.setup import setup_telemetry
+
+log = get_logger(__name__)
+
+
+def echo_json(data: Any, err: bool = False) -> None:
+    """
+    Output data as JSON.
+
+    Args:
+        data: Data to output as JSON
+        err: Whether to output to stderr
+    """
+    click.echo(json.dumps(data, indent=2, default=str), err=err)
+
+
+def echo_error(message: str, json_output: bool = False) -> None:
+    """
+    Output an error message.
+
+    Args:
+        message: Error message to output
+        json_output: Whether to output as JSON
+    """
+    if json_output:
+        echo_json({"error": message}, err=True)
+    else:
+        click.secho(f"✗ {message}", fg="red", err=True)
+
+
+def echo_success(message: str, json_output: bool = False) -> None:
+    """
+    Output a success message.
+
+    Args:
+        message: Success message to output
+        json_output: Whether to output as JSON
+    """
+    if json_output:
+        echo_json({"success": message})
+    else:
+        click.secho(f"✓ {message}", fg="green")
+
+
+def echo_warning(message: str, json_output: bool = False) -> None:
+    """
+    Output a warning message.
+
+    Args:
+        message: Warning message to output
+        json_output: Whether to output as JSON
+    """
+    if json_output:
+        echo_json({"warning": message}, err=True)
+    else:
+        click.secho(f"⚠ {message}", fg="yellow", err=True)
+
+
+def echo_info(message: str, json_output: bool = False) -> None:
+    """
+    Output an informational message.
+
+    Args:
+        message: Info message to output
+        json_output: Whether to output as JSON
+    """
+    if json_output:
+        echo_json({"info": message})
+    else:
+        click.echo(f"ℹ {message}")
+
+
+def setup_cli_logging(
+    ctx: Context,
+) -> None:
+    """
+    Setup logging for CLI applications using a Context object.
+
+    This function is the designated way to configure logging within a CLI
+    application built with foundation. It uses the provided context object
+    to construct a full TelemetryConfig and initializes the system.
+
+    Args:
+        ctx: The foundation Context, populated by CLI decorators.
+    """
+    console_formatter = "json" if ctx.json_output else ctx.log_format
+
+    logging_config = LoggingConfig(
+        default_level=ctx.log_level,
+        console_formatter=console_formatter,
+        omit_timestamp=False,
+        logger_name_emoji_prefix_enabled=not ctx.no_emoji,
+        das_emoji_prefix_enabled=not ctx.no_emoji,
+        log_file=ctx.log_file,
+    )
+
+    telemetry_config = TelemetryConfig(
+        service_name=ctx.profile,
+        logging=logging_config,
+    )
+
+    setup_telemetry(config=telemetry_config)
+
+
+def create_cli_context(**kwargs) -> Context:
+    """
+    Create a Context for CLI usage.
+
+    Loads from environment, then overlays any provided kwargs.
+
+    Args:
+        **kwargs: Override values for the context
+
+    Returns:
+        Configured Context instance
+    """
+    ctx = Context.from_env()
+    for key, value in kwargs.items():
+        if value is not None and hasattr(ctx, key):
+            setattr(ctx, key, value)
+    return ctx
+
+
+class CliTestRunner:
+    """Test runner for CLI commands using Click's testing facilities."""
+
+    def __init__(self) -> None:
+        self.runner = CliRunner()
+
+    def invoke(
+        self,
+        cli: click.Command | click.Group,
+        args: list[str] | None = None,
+        input: str | None = None,
+        env: dict[str, str] | None = None,
+        catch_exceptions: bool = True,
+        **kwargs,
+    ) -> Result:
+        """Invoke a CLI command for testing."""
+        return self.runner.invoke(
+            cli,
+            args=args,
+            input=input,
+            env=env,
+            catch_exceptions=catch_exceptions,
+            **kwargs,
+        )
+
+    def isolated_filesystem(self):
+        """
+        Context manager for isolated filesystem.
+        """
+        return self.runner.isolated_filesystem()
+
+
+def assert_cli_success(result: Result, expected_output: str | None = None) -> None:
+    """
+    Assert that a CLI command succeeded.
+    """
+    if result.exit_code != 0:
+        raise AssertionError(
+            f"Command failed with exit code {result.exit_code}\n"
+            f"Output: {result.output}\n"
+            f"Exception: {result.exception}"
+        )
+
+    if expected_output and expected_output not in result.output:
+        raise AssertionError(
+            f"Expected output not found.\n"
+            f"Expected: {expected_output}\n"
+            f"Actual: {result.output}"
+        )
+
+
+def assert_cli_error(
+    result: Result,
+    expected_error: str | None = None,
+    exit_code: int | None = None,
+) -> None:
+    """
+    Assert that a CLI command failed.
+    """
+    if result.exit_code == 0:
+        raise AssertionError(f"Command succeeded unexpectedly\nOutput: {result.output}")
+
+    if exit_code is not None and result.exit_code != exit_code:
+        raise AssertionError(
+            f"Wrong exit code.\nExpected: {exit_code}\nActual: {result.exit_code}"
+        )
+
+    if expected_error and expected_error not in result.output:
+        raise AssertionError(
+            f"Expected error not found.\n"
+            f"Expected: {expected_error}\n"
+            f"Actual: {result.output}"
+        )

provide/foundation/config/__init__.py

@@ -0,0 +1,106 @@
+"""
+Foundation Configuration System.
+
+A comprehensive, extensible configuration framework for the provide.io ecosystem.
+Supports multiple configuration sources with precedence, validation, and type safety.
+"""
+
+from provide.foundation.config.base import (
+    BaseConfig,
+    field,
+)
+from provide.foundation.config.env import (
+    RuntimeConfig,
+    env_field,
+    get_env,
+    get_env_async,
+)
+from provide.foundation.config.loader import (
+    ConfigLoader,
+    DictConfigLoader,
+    FileConfigLoader,
+    MultiSourceLoader,
+)
+from provide.foundation.config.manager import (
+    ConfigManager,
+    get_config,
+    set_config,
+)
+from provide.foundation.config.schema import (
+    ConfigSchema,
+    SchemaField,
+    validate_schema,
+)
+
+# Import sync wrappers for convenience
+from provide.foundation.config.sync import (
+    SyncConfigManager,
+    load_config,
+    load_config_from_env,
+    load_config_from_file,
+    validate_config,
+)
+from provide.foundation.config.types import (
+    ConfigDict,
+    ConfigSource,
+    ConfigValue,
+)
+from provide.foundation.config.validators import (
+    validate_choice,
+    validate_non_negative,
+    validate_positive,
+    validate_range,
+)
+from provide.foundation.errors.config import (
+    ConfigurationError as ConfigError,
+    ValidationError as ConfigValidationError,
+)
+from provide.foundation.utils.parsing import (
+    parse_bool,
+    parse_dict,
+    parse_list,
+)
+
+__all__ = [
+    # Base
+    "BaseConfig",
+    # Types
+    "ConfigDict",
+    "ConfigError",
+    # Loader
+    "ConfigLoader",
+    # Manager
+    "ConfigManager",
+    # Schema
+    "ConfigSchema",
+    "ConfigSource",
+    "ConfigValidationError",
+    "ConfigValue",
+    "DictConfigLoader",
+    # Environment
+    "RuntimeConfig",
+    "FileConfigLoader",
+    "MultiSourceLoader",
+    "SchemaField",
+    "SyncConfigManager",
+    "env_field",
+    "field",
+    "get_config",
+    "get_env",
+    "get_env_async",
+    # Sync wrappers
+    "load_config",
+    "load_config_from_env",
+    "load_config_from_file",
+    "parse_bool",
+    "parse_dict",
+    "parse_list",
+    "set_config",
+    # Validators
+    "validate_choice",
+    "validate_config",
+    "validate_non_negative",
+    "validate_positive",
+    "validate_range",
+    "validate_schema",
+]