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

provide/foundation/hub/discovery.py

@@ -0,0 +1,62 @@
+"""
+Hub component discovery and dependency resolution utilities.
+
+Provides functions for discovering components and resolving their dependencies
+in the Hub registry system.
+"""
+
+from typing import Any
+
+from provide.foundation.hub.registry import Registry
+
+
+def _get_registry_and_lock():
+    """Get registry and lock from components module."""
+    from provide.foundation.hub.components import get_component_registry, _registry_lock
+    return get_component_registry(), _registry_lock
+
+
+def resolve_component_dependencies(name: str, dimension: str) -> dict[str, Any]:
+    """Resolve component dependencies recursively."""
+    registry, registry_lock = _get_registry_and_lock()
+    
+    with registry_lock:
+        entry = registry.get_entry(name, dimension)
+
+        if not entry:
+            return {}
+
+        dependencies = {}
+        dep_names = entry.metadata.get("dependencies", [])
+
+        for dep_name in dep_names:
+            # Try same dimension first
+            dep_component = registry.get(dep_name, dimension)
+            if dep_component is not None:
+                dependencies[dep_name] = dep_component
+            else:
+                # Search across dimensions
+                dep_component = registry.get(dep_name)
+                if dep_component is not None:
+                    dependencies[dep_name] = dep_component
+
+        return dependencies
+
+
+def discover_components(
+    group: str,
+    dimension: str = "component",
+    registry: Registry | None = None,
+) -> dict[str, type[Any]]:
+    """
+    Discover and register components from entry points.
+
+    This is a stub for the TDD implementation.
+    """
+    return {}
+
+
+__all__ = [
+    "resolve_component_dependencies",
+    "discover_components",
+]

provide/foundation/hub/handlers.py

@@ -0,0 +1,81 @@
+"""
+Hub error handler management utilities.
+
+Provides functions for discovering and executing error handlers from the registry.
+"""
+
+from typing import Any
+
+from provide.foundation.errors.decorators import with_error_handling
+from provide.foundation.hub.registry import RegistryEntry
+from provide.foundation.logger import get_logger
+
+log = get_logger(__name__)
+
+
+def _get_registry_and_lock():
+    """Get registry and lock from components module."""
+    from provide.foundation.hub.components import get_component_registry, _registry_lock, ComponentCategory
+    return get_component_registry(), _registry_lock, ComponentCategory
+
+
+def get_handlers_for_exception(exception: Exception) -> list[RegistryEntry]:
+    """Get error handlers that can handle the given exception type."""
+    registry, registry_lock, ComponentCategory = _get_registry_and_lock()
+    
+    with registry_lock:
+        # Get all error handlers
+        all_entries = list(registry)
+        handlers = [
+            entry
+            for entry in all_entries
+            if entry.dimension == ComponentCategory.ERROR_HANDLER.value
+        ]
+
+        # Filter by exception type
+        exception_type_name = type(exception).__name__
+        matching_handlers = []
+
+        for entry in handlers:
+            exception_types = entry.metadata.get("exception_types", [])
+            if any(
+                exc_type in exception_type_name or exception_type_name in exc_type
+                for exc_type in exception_types
+            ):
+                matching_handlers.append(entry)
+
+        # Sort by priority (highest first)
+        matching_handlers.sort(
+            key=lambda e: e.metadata.get("priority", 0), reverse=True
+        )
+        return matching_handlers
+
+
+@with_error_handling(
+    fallback=None,
+    context_provider=lambda: {"function": "execute_error_handlers", "module": "hub.handlers"}
+)
+def execute_error_handlers(
+    exception: Exception, context: dict[str, Any]
+) -> dict[str, Any] | None:
+    """Execute error handlers until one handles the exception."""
+    handlers = get_handlers_for_exception(exception)
+
+    for entry in handlers:
+        handler = entry.value
+        try:
+            result = handler(exception, context)
+            if result is not None:
+                return result
+        except Exception as handler_error:
+            log.error(
+                "Error handler failed", handler=entry.name, error=str(handler_error)
+            )
+
+    return None
+
+
+__all__ = [
+    "get_handlers_for_exception",
+    "execute_error_handlers",
+]

provide/foundation/hub/lifecycle.py

@@ -0,0 +1,194 @@
+"""
+Hub component lifecycle management utilities.
+
+Provides functions for initializing, managing, and cleaning up components
+registered in the Hub registry system.
+"""
+
+import asyncio
+import inspect
+from typing import Any
+
+from provide.foundation.logger import get_logger
+
+log = get_logger(__name__)
+
+
+def _get_registry_and_globals():
+    """Get registry, lock, and initialized components from components module."""
+    from provide.foundation.hub.components import (
+        get_component_registry, 
+        _registry_lock, 
+        _initialized_components
+    )
+    return get_component_registry(), _registry_lock, _initialized_components
+
+
+def get_or_initialize_component(name: str, dimension: str) -> Any:
+    """Get component, initializing lazily if needed."""
+    registry, registry_lock, initialized_components = _get_registry_and_globals()
+    
+    with registry_lock:
+        key = (name, dimension)
+
+        # Return already initialized component
+        if key in initialized_components:
+            return initialized_components[key]
+
+        entry = registry.get_entry(name, dimension)
+
+        if not entry:
+            return None
+
+        # If already initialized, return it
+        if entry.value is not None:
+            initialized_components[key] = entry.value
+            return entry.value
+
+        # Initialize lazily
+        if entry.metadata.get("lazy", False):
+            factory = entry.metadata.get("factory")
+            if factory:
+                try:
+                    component = factory()
+                    # Update registry with initialized component
+                    registry.register(
+                        name=name,
+                        value=component,
+                        dimension=dimension,
+                        metadata=entry.metadata,
+                        replace=True,
+                    )
+                    initialized_components[key] = component
+                    return component
+                except Exception as e:
+                    log.error(
+                        "Component initialization failed",
+                        component=name,
+                        dimension=dimension,
+                        error=str(e),
+                    )
+
+        return entry.value
+
+
+async def initialize_async_component(name: str, dimension: str) -> Any:
+    """Initialize component asynchronously."""
+    registry, registry_lock, initialized_components = _get_registry_and_globals()
+    
+    with registry_lock:
+        key = (name, dimension)
+
+        # Return already initialized component
+        if key in initialized_components:
+            return initialized_components[key]
+
+        entry = registry.get_entry(name, dimension)
+
+        if not entry:
+            return None
+
+        # Initialize with async factory
+        if entry.metadata.get("async", False):
+            factory = entry.metadata.get("factory")
+            if factory:
+                try:
+                    if inspect.iscoroutinefunction(factory):
+                        component = await factory()
+                    else:
+                        component = factory()
+
+                    # Update registry
+                    registry.register(
+                        name=name,
+                        value=component,
+                        dimension=dimension,
+                        metadata=entry.metadata,
+                        replace=True,
+                    )
+                    initialized_components[key] = component
+                    return component
+                except Exception as e:
+                    log.error(
+                        "Async component initialization failed",
+                        component=name,
+                        dimension=dimension,
+                        error=str(e),
+                    )
+
+        return entry.value
+
+
+def cleanup_all_components(dimension: str | None = None) -> None:
+    """Clean up all components in dimension."""
+    registry, registry_lock, _ = _get_registry_and_globals()
+    
+    with registry_lock:
+        if dimension:
+            entries = [entry for entry in registry if entry.dimension == dimension]
+        else:
+            entries = list(registry)
+
+        for entry in entries:
+            if entry.metadata.get("supports_cleanup", False):
+                component = entry.value
+                if hasattr(component, "cleanup"):
+                    try:
+                        cleanup_func = component.cleanup
+                        if inspect.iscoroutinefunction(cleanup_func):
+                            # Run async cleanup
+                            loop = None
+                            try:
+                                loop = asyncio.get_event_loop()
+                                if loop.is_running():
+                                    # Create task if loop is running
+                                    loop.create_task(cleanup_func())
+                                else:
+                                    loop.run_until_complete(cleanup_func())
+                            except RuntimeError:
+                                # Create new loop if none exists
+                                loop = asyncio.new_event_loop()
+                                loop.run_until_complete(cleanup_func())
+                                loop.close()
+                        else:
+                            cleanup_func()
+                    except Exception as e:
+                        log.error(
+                            "Component cleanup failed",
+                            component=entry.name,
+                            dimension=entry.dimension,
+                            error=str(e),
+                        )
+
+
+async def initialize_all_async_components() -> None:
+    """Initialize all async components in dependency order."""
+    registry, _, _ = _get_registry_and_globals()
+
+    # Get all async components
+    async_components = [
+        entry for entry in registry if entry.metadata.get("async", False)
+    ]
+
+    # Sort by priority for initialization order
+    async_components.sort(key=lambda e: e.metadata.get("priority", 0), reverse=True)
+
+    # Initialize each component
+    for entry in async_components:
+        try:
+            await initialize_async_component(entry.name, entry.dimension)
+        except Exception as e:
+            log.error(
+                "Failed to initialize async component",
+                component=entry.name,
+                dimension=entry.dimension,
+                error=str(e),
+            )
+
+
+__all__ = [
+    "get_or_initialize_component",
+    "initialize_async_component", 
+    "cleanup_all_components",
+    "initialize_all_async_components",
+]

provide/foundation/hub/manager.py

@@ -19,7 +19,7 @@ except ImportError:
     click = None
     _HAS_CLICK = False
 
-from provide.foundation.context import Context
+from provide.foundation.context import CLIContext
 from provide.foundation.errors.config import ValidationError
 from provide.foundation.errors.decorators import with_error_handling
 from provide.foundation.errors.resources import AlreadyExistsError
@@ -60,7 +60,7 @@ class Hub:
 
     def __init__(
         self,
-        context: Context | None = None,
+        context: CLIContext | None = None,
         component_registry: Registry | None = None,
         command_registry: Registry | None = None,
     ) -> None:
@@ -68,11 +68,11 @@ class Hub:
         Initialize the hub.
 
         Args:
-            context: Foundation context for configuration
+            context: Foundation CLIContext for configuration
             component_registry: Custom component registry
             command_registry: Custom command registry
         """
-        self.context = context or Context()
+        self.context = context or CLIContext()
         self._component_registry = component_registry or get_component_registry()
         self._command_registry = command_registry or get_command_registry()
         self._cli_group: click.Group | None = None

provide/foundation/hub/processors.py

@@ -0,0 +1,44 @@
+"""
+Hub processor pipeline management utilities.
+
+Provides functions for managing log processors and processing stages
+in the Hub registry system.
+"""
+
+from provide.foundation.hub.registry import RegistryEntry
+
+
+def _get_registry_and_lock():
+    """Get registry and lock from components module."""
+    from provide.foundation.hub.components import get_component_registry, _registry_lock, ComponentCategory
+    return get_component_registry(), _registry_lock, ComponentCategory
+
+
+def get_processor_pipeline() -> list[RegistryEntry]:
+    """Get log processors ordered by priority."""
+    registry, registry_lock, ComponentCategory = _get_registry_and_lock()
+    
+    with registry_lock:
+        # Get all processors
+        all_entries = list(registry)
+        processors = [
+            entry
+            for entry in all_entries
+            if entry.dimension == ComponentCategory.PROCESSOR.value
+        ]
+
+        # Sort by priority (highest first)
+        processors.sort(key=lambda e: e.metadata.get("priority", 0), reverse=True)
+        return processors
+
+
+def get_processors_for_stage(stage: str) -> list[RegistryEntry]:
+    """Get processors for a specific processing stage."""
+    pipeline = get_processor_pipeline()
+    return [entry for entry in pipeline if entry.metadata.get("stage") == stage]
+
+
+__all__ = [
+    "get_processor_pipeline",
+    "get_processors_for_stage",
+]

provide/foundation/integrations/__init__.py

@@ -0,0 +1,11 @@
+"""
+Optional integrations for Foundation.
+
+This module contains integrations with external services and tools
+that are not part of the core foundation library.
+"""
+
+__all__ = [
+    # Available integrations (import on demand)
+    # "openobserve",
+]

provide/foundation/{observability → integrations}/openobserve/__init__.py

@@ -1,11 +1,12 @@
 """
 OpenObserve integration for Foundation.
 
-Provides log querying and streaming capabilities when OpenTelemetry is available.
+Provides log querying and streaming capabilities as an optional integration.
 """
 
-from provide.foundation.observability.openobserve.client import OpenObserveClient
-from provide.foundation.observability.openobserve.exceptions import (
+from provide.foundation.integrations.openobserve.client import OpenObserveClient
+from provide.foundation.integrations.openobserve.config import OpenObserveConfig
+from provide.foundation.integrations.openobserve.exceptions import (
     OpenObserveAuthenticationError,
     OpenObserveConfigError,
     OpenObserveConnectionError,
@@ -13,7 +14,7 @@ from provide.foundation.observability.openobserve.exceptions import (
     OpenObserveQueryError,
     OpenObserveStreamingError,
 )
-from provide.foundation.observability.openobserve.formatters import (
+from provide.foundation.integrations.openobserve.formatters import (
     format_csv,
     format_json,
     format_log_line,
@@ -21,13 +22,13 @@ from provide.foundation.observability.openobserve.formatters import (
     format_summary,
     format_table,
 )
-from provide.foundation.observability.openobserve.models import (
+from provide.foundation.integrations.openobserve.models import (
     SearchQuery,
     SearchResponse,
     StreamInfo,
     parse_relative_time,
 )
-from provide.foundation.observability.openobserve.search import (
+from provide.foundation.integrations.openobserve.search import (
     aggregate_by_level,
     get_current_trace_logs,
     search_by_level,
@@ -36,13 +37,15 @@ from provide.foundation.observability.openobserve.search import (
     search_errors,
     search_logs,
 )
-from provide.foundation.observability.openobserve.streaming import (
+from provide.foundation.integrations.openobserve.streaming import (
     stream_logs,
     stream_search_http2,
     tail_logs,
 )
 
 __all__ = [
+    # Configuration
+    "OpenObserveConfig",
     # Client
     "OpenObserveClient",
     # Search functions

provide/foundation/{observability → integrations}/openobserve/auth.py

@@ -4,7 +4,7 @@ Authentication handling for OpenObserve.
 
 import base64
 
-from provide.foundation.observability.openobserve.exceptions import (
+from provide.foundation.integrations.openobserve.exceptions import (
     OpenObserveAuthenticationError,
 )
 

provide/foundation/{observability → integrations}/openobserve/client.py

@@ -12,16 +12,16 @@ from requests.adapters import HTTPAdapter
 from urllib3.util.retry import Retry
 
 from provide.foundation.logger import get_logger
-from provide.foundation.observability.openobserve.auth import (
+from provide.foundation.integrations.openobserve.auth import (
     get_auth_headers,
     validate_credentials,
 )
-from provide.foundation.observability.openobserve.exceptions import (
+from provide.foundation.integrations.openobserve.exceptions import (
     OpenObserveConfigError,
     OpenObserveConnectionError,
     OpenObserveQueryError,
 )
-from provide.foundation.observability.openobserve.models import (
+from provide.foundation.integrations.openobserve.models import (
     SearchQuery,
     SearchResponse,
     StreamInfo,
@@ -74,7 +74,7 @@ class OpenObserveClient:
 
     @classmethod
     def from_config(cls) -> "OpenObserveClient":
-        """Create client from TelemetryConfig.
+        """Create client from OpenObserveConfig.
 
         Returns:
             Configured OpenObserveClient instance
@@ -82,26 +82,26 @@ class OpenObserveClient:
         Raises:
             OpenObserveConfigError: If configuration is missing
         """
-        from provide.foundation.logger.config import TelemetryConfig
+        from provide.foundation.integrations.openobserve.config import OpenObserveConfig
 
-        config = TelemetryConfig.from_env()
+        config = OpenObserveConfig.from_env()
 
-        if not config.openobserve_url:
+        if not config.url:
             raise OpenObserveConfigError(
                 "OpenObserve URL not configured. Set OPENOBSERVE_URL environment variable."
             )
 
-        if not config.openobserve_user or not config.openobserve_password:
+        if not config.user or not config.password:
             raise OpenObserveConfigError(
                 "OpenObserve credentials not configured. "
                 "Set OPENOBSERVE_USER and OPENOBSERVE_PASSWORD environment variables."
             )
 
         return cls(
-            url=config.openobserve_url,
-            username=config.openobserve_user,
-            password=config.openobserve_password,
-            organization=config.openobserve_org,
+            url=config.url,
+            username=config.user,
+            password=config.password,
+            organization=config.org or "default",
         )
 
     def _make_request(

provide/foundation/{observability → integrations}/openobserve/commands.py

@@ -18,7 +18,7 @@ log = get_logger(__name__)
 
 
 if _HAS_CLICK:
-    from provide.foundation.observability.openobserve import (
+    from provide.foundation.integrations.openobserve import (
         OpenObserveClient,
         format_output,
         search_logs,
@@ -198,7 +198,7 @@ if _HAS_CLICK:
             return 1
 
         try:
-            from provide.foundation.observability.openobserve import search_errors
+            from provide.foundation.integrations.openobserve import search_errors
 
             response = search_errors(
                 stream=stream,
@@ -240,7 +240,7 @@ if _HAS_CLICK:
             return 1
 
         try:
-            from provide.foundation.observability.openobserve import search_by_trace_id
+            from provide.foundation.integrations.openobserve import search_by_trace_id
 
             response = search_by_trace_id(
                 trace_id=trace_id,

provide/foundation/integrations/openobserve/config.py

@@ -0,0 +1,37 @@
+"""OpenObserve integration configuration."""
+
+from attrs import define
+
+from provide.foundation.config.env import RuntimeConfig
+from provide.foundation.config.base import field
+
+
+@define(slots=True, repr=False)
+class OpenObserveConfig(RuntimeConfig):
+    """Configuration for OpenObserve integration."""
+
+    url: str | None = field(
+        default=None,
+        env_var="OPENOBSERVE_URL",
+        description="OpenObserve URL endpoint",
+    )
+    org: str | None = field(
+        default=None,
+        env_var="OPENOBSERVE_ORG",
+        description="OpenObserve organization",
+    )
+    user: str | None = field(
+        default=None,
+        env_var="OPENOBSERVE_USER",
+        description="OpenObserve username",
+    )
+    password: str | None = field(
+        default=None,
+        env_var="OPENOBSERVE_PASSWORD",
+        description="OpenObserve password",
+    )
+    stream: str | None = field(
+        default=None,
+        env_var="OPENOBSERVE_STREAM",
+        description="OpenObserve stream name",
+    )

provide/foundation/{observability → integrations}/openobserve/formatters.py

@@ -8,7 +8,7 @@ import io
 import json
 from typing import Any
 
-from provide.foundation.observability.openobserve.models import SearchResponse
+from provide.foundation.integrations.openobserve.models import SearchResponse
 
 
 def format_json(response: SearchResponse | dict[str, Any], pretty: bool = True) -> str:

provide/foundation/{observability → integrations}/openobserve/otlp.py

@@ -7,7 +7,7 @@ import json
 from typing import Any
 
 from provide.foundation.logger import get_logger
-from provide.foundation.observability.openobserve.client import OpenObserveClient
+from provide.foundation.integrations.openobserve.client import OpenObserveClient
 
 log = get_logger(__name__)
 

provide/foundation/{observability → integrations}/openobserve/search.py

@@ -4,8 +4,8 @@ Search operations for OpenObserve.
 
 
 from provide.foundation.logger import get_logger
-from provide.foundation.observability.openobserve.client import OpenObserveClient
-from provide.foundation.observability.openobserve.models import SearchResponse
+from provide.foundation.integrations.openobserve.client import OpenObserveClient
+from provide.foundation.integrations.openobserve.models import SearchResponse
 
 log = get_logger(__name__)
 

provide/foundation/{observability → integrations}/openobserve/streaming.py

@@ -10,12 +10,12 @@ from typing import Any
 import requests
 
 from provide.foundation.logger import get_logger
-from provide.foundation.observability.openobserve.auth import get_auth_headers
-from provide.foundation.observability.openobserve.client import OpenObserveClient
-from provide.foundation.observability.openobserve.exceptions import (
+from provide.foundation.integrations.openobserve.auth import get_auth_headers
+from provide.foundation.integrations.openobserve.client import OpenObserveClient
+from provide.foundation.integrations.openobserve.exceptions import (
     OpenObserveStreamingError,
 )
-from provide.foundation.observability.openobserve.models import parse_relative_time
+from provide.foundation.integrations.openobserve.models import parse_relative_time
 
 log = get_logger(__name__)