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

provide/foundation/testing/hub.py

@@ -0,0 +1,23 @@
+"""
+Hub Testing Fixtures for Foundation.
+
+Provides pytest fixtures for testing hub and component functionality,
+including container directories and component registration scenarios.
+"""
+
+from pathlib import Path
+import tempfile
+
+import pytest
+
+
+@pytest.fixture(scope="session")
+def default_container_directory():
+    """
+    Provides a default directory for container operations in tests.
+
+    This fixture is used by tests that need a temporary directory
+    for container-related operations.
+    """
+    with tempfile.TemporaryDirectory() as tmp_dir:
+        yield Path(tmp_dir)

provide/foundation/testing/logger.py

@@ -0,0 +1,106 @@
+#
+# logger.py
+#
+"""
+Logger Testing Utilities for Foundation.
+
+Provides utilities for resetting logger state, managing configurations,
+and ensuring test isolation for the Foundation logging system.
+"""
+
+import structlog
+
+from provide.foundation.logger.core import (
+    _LAZY_SETUP_STATE,
+    logger as foundation_logger,
+)
+from provide.foundation.streams.file import reset_streams
+
+
+def _reset_opentelemetry_providers() -> None:
+    """
+    Reset OpenTelemetry providers to uninitialized state.
+
+    This prevents "Overriding of current TracerProvider/MeterProvider" warnings
+    and stream closure issues by properly resetting the global providers.
+    """
+    try:
+        # Reset tracing provider by resetting the Once flag
+        import opentelemetry.trace as otel_trace
+
+        if hasattr(otel_trace, "_TRACER_PROVIDER_SET_ONCE"):
+            once_obj = otel_trace._TRACER_PROVIDER_SET_ONCE
+            if hasattr(once_obj, "_done"):
+                once_obj._done = False
+        # Reset to NoOpTracerProvider
+        from opentelemetry.trace import NoOpTracerProvider
+
+        otel_trace._TRACER_PROVIDER = NoOpTracerProvider()
+    except ImportError:
+        # OpenTelemetry tracing not available
+        pass
+    except Exception:
+        # Ignore errors during reset
+        pass
+
+    try:
+        # Reset metrics provider by resetting the Once flag
+        import opentelemetry.metrics._internal as otel_metrics_internal
+
+        if hasattr(otel_metrics_internal, "_METER_PROVIDER_SET_ONCE"):
+            once_obj = otel_metrics_internal._METER_PROVIDER_SET_ONCE
+            if hasattr(once_obj, "_done"):
+                once_obj._done = False
+        # Reset to NoOpMeterProvider
+        from opentelemetry.metrics import NoOpMeterProvider
+
+        otel_metrics_internal._METER_PROVIDER = NoOpMeterProvider()
+    except ImportError:
+        # OpenTelemetry metrics not available
+        pass
+    except Exception:
+        # Ignore errors during reset
+        pass
+
+
+def reset_foundation_state() -> None:
+    """
+    Internal function to reset structlog and Foundation's state.
+
+    This resets:
+    - structlog configuration to defaults
+    - Foundation logger state and configuration
+    - Stream state back to defaults
+    - Lazy setup state tracking
+    - OpenTelemetry provider state (if available)
+    """
+    # Reset structlog to its default unconfigured state
+    structlog.reset_defaults()
+
+    # Reset stream state
+    reset_streams()
+
+    # Reset OpenTelemetry providers to avoid "Overriding" warnings and stream closure
+    _reset_opentelemetry_providers()
+
+    # Reset foundation logger state
+    foundation_logger._is_configured_by_setup = False
+    foundation_logger._active_config = None
+    foundation_logger._active_resolved_emoji_config = None
+    _LAZY_SETUP_STATE.update({"done": False, "error": None, "in_progress": False})
+
+
+def reset_foundation_setup_for_testing() -> None:
+    """
+    Public test utility to reset Foundation's internal state.
+
+    This function ensures clean test isolation by resetting all
+    Foundation logging state between test runs.
+    """
+    reset_foundation_state()
+
+
+__all__ = [
+    "reset_foundation_setup_for_testing",
+    "reset_foundation_state",
+]

provide/foundation/testing/streams.py

@@ -0,0 +1,54 @@
+#
+# streams.py
+#
+"""
+Stream Testing Utilities for Foundation.
+
+Provides utilities for redirecting and managing streams during testing,
+allowing tests to capture and control Foundation's output streams.
+"""
+
+from typing import TextIO
+
+# Import the actual stream management variables
+from provide.foundation.streams.core import get_log_stream
+
+
+def set_log_stream_for_testing(stream: TextIO | None) -> None:
+    """
+    Set the log stream for testing purposes.
+
+    This allows tests to redirect Foundation's log output to a custom stream
+    (like StringIO) for capturing and verifying log messages.
+
+    Args:
+        stream: Stream to redirect to, or None to reset to stderr
+    """
+    # Import the actual implementation from streams.core
+    from provide.foundation.streams.core import (
+        set_log_stream_for_testing as _set_stream,
+    )
+
+    _set_stream(stream)
+
+
+def get_current_log_stream() -> TextIO:
+    """
+    Get the currently active log stream.
+
+    Returns:
+        The current log stream being used by Foundation
+    """
+    return get_log_stream()
+
+
+def reset_log_stream() -> None:
+    """Reset log stream back to stderr."""
+    set_log_stream_for_testing(None)
+
+
+__all__ = [
+    "get_current_log_stream",
+    "reset_log_stream",
+    "set_log_stream_for_testing",
+]

provide/foundation/tracer/__init__.py

@@ -0,0 +1,49 @@
+#
+# __init__.py
+#
+"""
+Foundation Tracer Module.
+
+Provides distributed tracing functionality with optional OpenTelemetry integration.
+Falls back to simple, lightweight tracing when OpenTelemetry is not available.
+"""
+
+# OpenTelemetry feature detection
+try:
+    from opentelemetry import trace as otel_trace
+    from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
+        OTLPSpanExporter as OTLPGrpcSpanExporter,
+    )
+    from opentelemetry.exporter.otlp.proto.http.trace_exporter import (
+        OTLPSpanExporter as OTLPHttpSpanExporter,
+    )
+    from opentelemetry.sdk.trace import TracerProvider
+    from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+    _HAS_OTEL = True
+except ImportError:
+    otel_trace = None
+    TracerProvider = None
+    BatchSpanProcessor = None
+    OTLPGrpcSpanExporter = None
+    OTLPHttpSpanExporter = None
+    _HAS_OTEL = False
+
+from provide.foundation.tracer.context import (
+    get_current_span,
+    get_current_trace_id,
+    get_trace_context,
+    set_current_span,
+    with_span,
+)
+from provide.foundation.tracer.spans import Span
+
+__all__ = [
+    "_HAS_OTEL",  # For internal use
+    "Span",
+    "get_current_span",
+    "get_current_trace_id",
+    "get_trace_context",
+    "set_current_span",
+    "with_span",
+]

provide/foundation/tracer/context.py

@@ -0,0 +1,115 @@
+#
+# context.py
+#
+"""
+Trace context management for Foundation tracer.
+Manages trace context and span hierarchy.
+"""
+
+import contextvars
+from typing import Any
+
+from provide.foundation.tracer.spans import Span
+
+# Context variable to track the current span
+_current_span: contextvars.ContextVar[Span | None] = contextvars.ContextVar(
+    "current_span", default=None
+)
+
+# Context variable to track the current trace ID
+_current_trace_id: contextvars.ContextVar[str | None] = contextvars.ContextVar(
+    "current_trace_id", default=None
+)
+
+
+def get_current_span() -> Span | None:
+    """Get the currently active span."""
+    return _current_span.get()
+
+
+def get_current_trace_id() -> str | None:
+    """Get the current trace ID."""
+    return _current_trace_id.get()
+
+
+def set_current_span(span: Span | None) -> None:
+    """Set the current active span."""
+    _current_span.set(span)
+    if span:
+        _current_trace_id.set(span.trace_id)
+
+
+def create_child_span(name: str, parent: Span | None = None) -> Span:
+    """
+    Create a child span.
+
+    Args:
+        name: Name of the span
+        parent: Parent span, defaults to current span
+
+    Returns:
+        New child span
+    """
+    if parent is None:
+        parent = get_current_span()
+
+    if parent:
+        return Span(name=name, parent_id=parent.span_id, trace_id=parent.trace_id)
+    else:
+        return Span(name=name)
+
+
+class SpanContext:
+    """
+    Context manager for managing span lifecycle.
+
+    Automatically sets and clears the current span.
+    """
+
+    def __init__(self, span: Span):
+        self.span = span
+        self.previous_span: Span | None = None
+
+    def __enter__(self) -> Span:
+        """Enter the span context."""
+        self.previous_span = get_current_span()
+        set_current_span(self.span)
+        return self.span
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Exit the span context."""
+        if exc_type is not None:
+            self.span.set_error(f"{exc_type.__name__}: {exc_val}")
+        self.span.finish()
+        set_current_span(self.previous_span)
+
+
+def with_span(name: str) -> SpanContext:
+    """
+    Create a new span context.
+
+    Args:
+        name: Name of the span
+
+    Returns:
+        SpanContext that can be used as a context manager
+    """
+    span = create_child_span(name)
+    return SpanContext(span)
+
+
+def get_trace_context() -> dict[str, Any]:
+    """
+    Get the current trace context information.
+
+    Returns:
+        Dictionary with trace context information
+    """
+    current_span = get_current_span()
+    trace_id = get_current_trace_id()
+
+    return {
+        "trace_id": trace_id,
+        "span_id": current_span.span_id if current_span else None,
+        "span_name": current_span.name if current_span else None,
+    }

provide/foundation/tracer/otel.py

@@ -0,0 +1,135 @@
+"""OpenTelemetry integration for Foundation tracer."""
+
+from provide.foundation.logger import get_logger
+from provide.foundation.logger.config.telemetry import TelemetryConfig
+
+log = get_logger(__name__)
+
+# Feature detection
+try:
+    from opentelemetry import trace as otel_trace
+    from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
+        OTLPSpanExporter as OTLPGrpcSpanExporter,
+    )
+    from opentelemetry.exporter.otlp.proto.http.trace_exporter import (
+        OTLPSpanExporter as OTLPHttpSpanExporter,
+    )
+    from opentelemetry.sdk.resources import Resource
+    from opentelemetry.sdk.trace import TracerProvider
+    from opentelemetry.sdk.trace.export import BatchSpanProcessor
+    from opentelemetry.sdk.trace.sampling import TraceIdRatioBased
+
+    _HAS_OTEL = True
+except ImportError:
+    _HAS_OTEL = False
+    # Stub everything for type hints
+    otel_trace = None
+    TracerProvider = None
+    BatchSpanProcessor = None
+    Resource = None
+    OTLPGrpcSpanExporter = None
+    OTLPHttpSpanExporter = None
+    TraceIdRatioBased = None
+
+
+def _require_otel() -> None:
+    """Ensure OpenTelemetry is available."""
+    if not _HAS_OTEL:
+        raise ImportError(
+            "OpenTelemetry features require optional dependencies. "
+            "Install with: pip install 'provide-foundation[opentelemetry]'"
+        )
+
+
+def setup_opentelemetry_tracing(config: TelemetryConfig) -> None:
+    """Setup OpenTelemetry tracing with configuration.
+
+    Args:
+        config: Telemetry configuration
+    """
+    # Check if tracing is disabled first, before checking dependencies
+    if not config.tracing_enabled or config.globally_disabled:
+        log.debug("🔍 OpenTelemetry tracing disabled")
+        return
+
+    # Check if OpenTelemetry is available
+    if not _HAS_OTEL:
+        log.debug("🔍 OpenTelemetry tracing not available (dependencies not installed)")
+        return
+
+    log.debug("🔍🚀 Setting up OpenTelemetry tracing")
+
+    # Create resource with service information
+    resource_attrs = {}
+    if config.service_name:
+        resource_attrs["service.name"] = config.service_name
+    if config.service_version:
+        resource_attrs["service.version"] = config.service_version
+
+    resource = Resource.create(resource_attrs)
+
+    # Create tracer provider with sampling
+    sampler = TraceIdRatioBased(config.trace_sample_rate)
+    tracer_provider = TracerProvider(resource=resource, sampler=sampler)
+
+    # Setup OTLP exporter if endpoint is configured
+    if config.otlp_endpoint or config.otlp_traces_endpoint:
+        endpoint = config.otlp_traces_endpoint or config.otlp_endpoint
+        headers = config.get_otlp_headers_dict()
+
+        log.debug(f"🔍📤 Configuring OTLP exporter: {endpoint}")
+
+        # Choose exporter based on protocol
+        if config.otlp_protocol == "grpc":
+            exporter = OTLPGrpcSpanExporter(
+                endpoint=endpoint,
+                headers=headers,
+            )
+        else:  # http/protobuf
+            exporter = OTLPHttpSpanExporter(
+                endpoint=endpoint,
+                headers=headers,
+            )
+
+        # Add batch processor
+        processor = BatchSpanProcessor(exporter)
+        tracer_provider.add_span_processor(processor)
+
+        log.debug(f"✅ OTLP span exporter configured: {config.otlp_protocol}")
+
+    # Set the global tracer provider
+    otel_trace.set_tracer_provider(tracer_provider)
+
+    log.info("🔍✅ OpenTelemetry tracing setup complete")
+
+
+def get_otel_tracer(name: str) -> "otel_trace.Tracer | None":
+    """Get OpenTelemetry tracer if available.
+
+    Args:
+        name: Name for the tracer
+
+    Returns:
+        OpenTelemetry tracer or None if not available
+    """
+    if not _HAS_OTEL:
+        return None
+
+    try:
+        return otel_trace.get_tracer(name)
+    except Exception:
+        return None
+
+
+def shutdown_opentelemetry() -> None:
+    """Shutdown OpenTelemetry tracing."""
+    if not _HAS_OTEL:
+        return
+
+    try:
+        tracer_provider = otel_trace.get_tracer_provider()
+        if hasattr(tracer_provider, "shutdown"):
+            tracer_provider.shutdown()
+            log.debug("🔍🛑 OpenTelemetry tracer provider shutdown")
+    except Exception as e:
+        log.warning(f"⚠️ Error shutting down OpenTelemetry: {e}")

provide/foundation/tracer/spans.py

@@ -0,0 +1,174 @@
+#
+# spans.py
+#
+"""
+Enhanced span implementation for Foundation tracer.
+Provides OpenTelemetry integration when available, falls back to simple tracing.
+"""
+
+from dataclasses import dataclass, field
+import time
+from typing import Any, Optional
+import uuid
+
+from provide.foundation.logger import get_logger
+
+log = get_logger(__name__)
+
+# OpenTelemetry feature detection
+try:
+    from opentelemetry import trace as otel_trace
+    from opentelemetry.trace import Status, StatusCode
+
+    _HAS_OTEL = True
+except ImportError:
+    otel_trace = None
+    Status = None
+    StatusCode = None
+    _HAS_OTEL = False
+
+
+@dataclass
+class Span:
+    """
+    Enhanced span implementation with optional OpenTelemetry integration.
+
+    Maintains simple API while providing distributed tracing when OpenTelemetry is available.
+    """
+
+    name: str
+    span_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    parent_id: str | None = None
+    trace_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    start_time: float = field(default_factory=time.time)
+    end_time: float | None = None
+    tags: dict[str, Any] = field(default_factory=dict)
+    status: str = "ok"
+    error: str | None = None
+
+    # Internal OpenTelemetry span (when available)
+    _otel_span: Optional["otel_trace.Span"] = field(
+        default=None, init=False, repr=False
+    )
+    _active: bool = field(default=True, init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        """Initialize span after creation."""
+        # Try to create OpenTelemetry span if available
+        if _HAS_OTEL:
+            try:
+                tracer = otel_trace.get_tracer(__name__)
+                self._otel_span = tracer.start_span(self.name)
+
+                log.debug(f"🔍✨ Created OpenTelemetry span: {self.name}")
+            except Exception as e:
+                log.debug(f"🔍⚠️ Failed to create OpenTelemetry span: {e}")
+                self._otel_span = None
+
+    def set_tag(self, key: str, value: Any) -> None:
+        """Set a tag on the span."""
+        self.tags[key] = value
+
+        # Also set on OpenTelemetry span if available
+        if self._otel_span and hasattr(self._otel_span, "set_attribute"):
+            try:
+                self._otel_span.set_attribute(key, value)
+            except Exception as e:
+                log.debug(f"🔍⚠️ Failed to set OpenTelemetry attribute: {e}")
+
+    def set_error(self, error: str | Exception) -> None:
+        """Mark the span as having an error."""
+        self.status = "error"
+        self.error = str(error)
+
+        # Also set on OpenTelemetry span if available
+        if self._otel_span and Status and StatusCode:
+            try:
+                self._otel_span.set_status(Status(StatusCode.ERROR, str(error)))
+                self._otel_span.record_exception(
+                    error if isinstance(error, Exception) else Exception(error)
+                )
+            except Exception as e:
+                log.debug(f"🔍⚠️ Failed to set OpenTelemetry error: {e}")
+
+    def finish(self) -> None:
+        """Finish the span and record end time."""
+        if self._active:
+            self.end_time = time.time()
+            self._active = False
+
+            # Also finish OpenTelemetry span if available
+            if self._otel_span:
+                try:
+                    self._otel_span.end()
+                    log.debug(f"🔍✅ Finished OpenTelemetry span: {self.name}")
+                except Exception as e:
+                    log.debug(f"🔍⚠️ Failed to finish OpenTelemetry span: {e}")
+
+    def __enter__(self) -> "Span":
+        """Context manager entry."""
+        # Set this span as current in OpenTelemetry context if available
+        if self._otel_span and _HAS_OTEL:
+            try:
+                # OpenTelemetry spans are automatically set as current when started
+                pass
+            except Exception as e:
+                log.debug(f"🔍⚠️ Failed to set OpenTelemetry span context: {e}")
+
+        # Also set in Foundation tracer context
+        try:
+            from provide.foundation.tracer.context import set_current_span
+
+            set_current_span(self)
+        except Exception as e:
+            log.debug(f"🔍⚠️ Failed to set Foundation span context: {e}")
+
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Context manager exit."""
+        # Handle exceptions
+        if exc_type is not None:
+            self.set_error(exc_val if exc_val else exc_type.__name__)
+
+        # Finish the span
+        self.finish()
+
+        # Clear from Foundation tracer context
+        try:
+            from provide.foundation.tracer.context import set_current_span
+
+            set_current_span(None)
+        except Exception as e:
+            log.debug(f"🔍⚠️ Failed to clear Foundation span context: {e}")
+
+    def duration_ms(self) -> float:
+        """Get the duration of the span in milliseconds."""
+        if self.end_time is None:
+            return (time.time() - self.start_time) * 1000
+        return (self.end_time - self.start_time) * 1000
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert span to dictionary representation."""
+        return {
+            "name": self.name,
+            "span_id": self.span_id,
+            "parent_id": self.parent_id,
+            "trace_id": self.trace_id,
+            "start_time": self.start_time,
+            "end_time": self.end_time,
+            "duration_ms": self.duration_ms(),
+            "tags": self.tags,
+            "status": self.status,
+            "error": self.error,
+        }
+
+    def __enter__(self):
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit."""
+        if exc_type is not None:
+            self.set_error(f"{exc_type.__name__}: {exc_val}")
+        self.finish()

provide/foundation/types.py

@@ -0,0 +1,32 @@
+"""
+Core type definitions and constants for Foundation.
+"""
+
+from typing import Literal
+
+from provide.foundation.logger.trace import TRACE_LEVEL_NAME, TRACE_LEVEL_NUM
+
+LogLevelStr = Literal[
+    "CRITICAL", "ERROR", "WARNING", "INFO", "DEBUG", "TRACE", "NOTSET"
+]
+
+_VALID_LOG_LEVEL_TUPLE: tuple[LogLevelStr, ...] = (
+    "CRITICAL",
+    "ERROR",
+    "WARNING",
+    "INFO",
+    "DEBUG",
+    "TRACE",
+    "NOTSET",
+)
+
+ConsoleFormatterStr = Literal["key_value", "json"]
+
+_VALID_FORMATTER_TUPLE: tuple[ConsoleFormatterStr, ...] = ("key_value", "json")
+
+__all__ = [
+    "TRACE_LEVEL_NAME",
+    "TRACE_LEVEL_NUM",
+    "ConsoleFormatterStr",
+    "LogLevelStr",
+]