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

provide/__init__.py

@@ -0,0 +1,15 @@
+"""
+Provide Namespace Package.
+
+Provides easy access to common foundation components:
+- logger: Foundation logging system
+- config: Foundation configuration system
+"""
+
+# Core imports for convenience
+from provide.foundation import config, logger
+
+__all__ = [
+    "config",
+    "logger",
+]

provide/foundation/__init__.py

@@ -0,0 +1,155 @@
+#
+# __init__.py
+#
+"""
+Foundation Telemetry Library (structlog-based).
+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._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
+
+# Error handling exports - only the essentials
+from provide.foundation.errors import (
+    # Base exception only
+    FoundationError,
+    # Most commonly used handlers
+    error_boundary,
+    retry_on_error,
+    # Most commonly used decorators
+    with_error_handling,
+)
+
+# 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
+from provide.foundation.hub.registry import Registry, RegistryEntry
+from provide.foundation.logger import (
+    LoggingConfig,
+    TelemetryConfig,
+    get_logger,  # Factory function for creating loggers
+    setup_logger,  # Setup function (consistent naming)
+    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,
+)
+from provide.foundation.setup import (
+    setup_telemetry,
+    shutdown_foundation_telemetry,
+)
+
+# New type exports for emoji mapping
+from provide.foundation.types import (
+    ConsoleFormatterStr,
+    LogLevelStr,
+)
+
+# New utility exports
+from provide.foundation.utils import (
+    TokenBucketRateLimiter,
+    check_optional_deps,
+    timed_block,
+)
+
+
+# Lazy loading support for optional modules
+def __getattr__(name: str):
+    """Support lazy loading of optional modules."""
+    if name == "cli":
+        try:
+            import provide.foundation.cli as cli
+
+            return cli
+        except ImportError as e:
+            if "click" in str(e):
+                raise ImportError(
+                    "CLI features require optional dependencies. Install with: "
+                    "pip install 'provide-foundation[cli]'"
+                ) from e
+            raise
+    elif name == "metrics":
+        import provide.foundation.metrics as metrics
+
+        return metrics
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
+
+
+__all__ = [
+    # Core Emoji Dictionaries (available for direct use or reference)
+    "PRIMARY_EMOJI",
+    "SECONDARY_EMOJI",
+    "TERTIARY_EMOJI",
+    "ConsoleFormatterStr",
+    # New foundation modules
+    "Context",
+    # Emoji Mapping classes
+    "EmojiSet",
+    # Error handling essentials
+    "FoundationError",
+    # Type aliases
+    "LogLevelStr",
+    "LoggingConfig",
+    # Hub and Registry (public API)
+    "Registry",
+    "RegistryEntry",
+    "Hub",
+    "ComponentCategory",
+    "get_component_registry",
+    "get_hub",
+    "clear_hub",
+    "FieldToEmojiMapping",
+    "EmojiSetConfig",
+    # Configuration classes
+    "TelemetryConfig",
+    # Version
+    "__version__",
+    # Dependency checking utility
+    "check_optional_deps",
+    # Config module
+    "config",
+    "error_boundary",
+    "errors",  # The errors module for detailed imports
+    "get_logger",
+    # Core setup and logger
+    "logger",
+    # Console functions (work with or without click)
+    "perr",
+    "pin",
+    "pout",
+    "platform",
+    "process",
+    "retry_on_error",
+    "setup_logging",  # Backward compatibility
+    "setup_logger",  # Consistent naming
+    "setup_telemetry",
+    # Utilities
+    "show_emoji_matrix",
+    "shutdown_foundation_telemetry",
+    "timed_block",
+    # Rate limiting utilities
+    "TokenBucketRateLimiter",
+    "with_error_handling",
+]
+
+# Import the logger instance after all other imports to avoid module shadowing
+from provide.foundation.logger import logger
+
+# 🐍📝

provide/foundation/_version.py

@@ -0,0 +1,58 @@
+#
+# version.py
+#
+"""
+Version handling for provide-foundation.
+Integrates VERSION logic from flavorpack with robust fallback mechanisms.
+"""
+
+from pathlib import Path
+
+
+def _find_project_root() -> Path | None:
+    """Find the project root directory by looking for VERSION file."""
+    current = Path(__file__).parent
+
+    # Walk up the directory tree looking for VERSION file
+    while current != current.parent:  # Stop at filesystem root
+        version_file = current / "VERSION"
+        if version_file.exists():
+            return current
+        current = current.parent
+
+    return None
+
+
+def get_version() -> str:
+    """Get the current provide-foundation version.
+
+    Reads from VERSION file if it exists, otherwise falls back to package metadata,
+    then to default development version.
+
+    Returns:
+        str: The current version string
+    """
+    # Try VERSION file first (single source of truth)
+    project_root = _find_project_root()
+    if project_root:
+        version_file = project_root / "VERSION"
+        if version_file.exists():
+            try:
+                return version_file.read_text().strip()
+            except OSError:
+                # Fall back to metadata if VERSION file can't be read
+                pass
+
+    # Fallback to package metadata
+    try:
+        from importlib.metadata import PackageNotFoundError, version
+
+        return version("provide-foundation")
+    except PackageNotFoundError:
+        pass
+
+    # Final fallback
+    return "0.0.0-dev"
+
+
+__version__ = get_version()

provide/foundation/cli/__init__.py

@@ -0,0 +1,67 @@
+"""
+Foundation CLI utilities for consistent command-line interfaces.
+
+Provides standard decorators, utilities, and patterns for building
+CLI tools in the provide-io ecosystem.
+"""
+
+from provide.foundation.cli.decorators import (
+    config_options,
+    error_handler,
+    flexible_options,
+    logging_options,
+    output_options,
+    pass_context,
+    standard_options,
+    version_option,
+)
+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 (
+    CliTestRunner,
+    assert_cli_error,
+    assert_cli_success,
+    create_cli_context,
+    echo_error,
+    echo_info,
+    echo_json,
+    echo_success,
+    echo_warning,
+    setup_cli_logging,
+)
+
+__all__ = [
+    "CliTestCase",
+    # Testing
+    "CliTestRunner",
+    "MockContext",
+    "assert_cli_error",
+    "assert_cli_success",
+    "config_options",
+    "create_cli_context",
+    "create_test_cli",
+    "echo_error",
+    "echo_info",
+    # Utilities
+    "echo_json",
+    "echo_success",
+    "echo_warning",
+    "error_handler",
+    "flexible_options",
+    "isolated_cli_runner",
+    # Decorators
+    "logging_options",
+    "mock_logger",
+    "output_options",
+    "pass_context",
+    "setup_cli_logging",
+    "standard_options",
+    "temp_config_file",
+    "version_option",
+]

provide/foundation/cli/commands/__init__.py

@@ -0,0 +1,3 @@
+"""Foundation CLI commands."""
+
+# This module provides CLI commands for foundation utilities

provide/foundation/cli/commands/deps.py

@@ -0,0 +1,71 @@
+"""CLI command for checking optional dependencies."""
+
+try:
+    import click
+
+    _HAS_CLICK = True
+except ImportError:
+    click = None
+    _HAS_CLICK = False
+
+from provide.foundation.utils.deps import check_optional_deps
+
+
+def _require_click():
+    """Ensure click is available for CLI commands."""
+    if not _HAS_CLICK:
+        raise ImportError(
+            "CLI commands require optional dependencies. "
+            "Install with: pip install 'provide-foundation[cli]'"
+        )
+
+
+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'}")
+            if not available:
+                print(f"Install with: pip install 'provide-foundation[{check}]'")
+        exit(0 if available else 1)
+    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 _HAS_CLICK:
+
+    @click.command("deps")
+    @click.option(
+        "--quiet", "-q", is_flag=True, help="Suppress output, just return exit code"
+    )
+    @click.option(
+        "--check", metavar="DEPENDENCY", help="Check specific dependency only"
+    )
+    def deps_command(quiet: bool, check: str | None) -> None:
+        """Check optional dependency status.
+
+        Shows which optional dependencies are available and provides
+        installation instructions for missing ones.
+
+        Exit codes:
+        - 0: All dependencies available (or specific one if --check used)
+        - 1: Some dependencies missing (or specific one missing if --check used)
+        """
+        _deps_command_impl(quiet, check)
+else:
+    # Stub for when click is not available
+    def deps_command(*args, **kwargs):
+        """Deps command stub when click is not available."""
+        _require_click()
+
+
+# Export the command
+__all__ = ["deps_command"]

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

@@ -0,0 +1,63 @@
+"""
+Logs command group for Foundation CLI.
+
+Provides commands for sending and querying logs with OpenTelemetry integration.
+"""
+
+try:
+    import click
+
+    _HAS_CLICK = True
+except ImportError:
+    click = None
+    _HAS_CLICK = False
+
+from provide.foundation.logger import get_logger
+
+log = get_logger(__name__)
+
+
+if _HAS_CLICK:
+
+    @click.group("logs", help="Send and query logs with OpenTelemetry integration")
+    @click.pass_context
+    def logs_group(ctx):
+        """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
+
+            ctx.obj["client"] = OpenObserveClient.from_config()
+        except Exception as e:
+            log.debug(f"OpenObserve client not available: {e}")
+            ctx.obj["client"] = None
+
+    # Import subcommands
+    from provide.foundation.cli.commands.logs.generate import (
+        generate_logs_command as generate_command,
+    )
+    from provide.foundation.cli.commands.logs.query import query_command
+    from provide.foundation.cli.commands.logs.send import send_command
+    from provide.foundation.cli.commands.logs.tail import tail_command
+
+    # Register subcommands
+    logs_group.add_command(send_command)
+    logs_group.add_command(query_command)
+    logs_group.add_command(tail_command)
+    logs_group.add_command(generate_command)
+
+    __all__ = ["logs_group"]
+
+else:
+    # Stub when click is not available
+    def logs_group(*args, **kwargs):
+        """Logs command stub when click is not available."""
+        raise ImportError(
+            "CLI commands require optional dependencies. "
+            "Install with: pip install 'provide-foundation[cli]'"
+        )
+
+    __all__ = []