haiway 0.19.5__py3-none-any.whl → 0.20.0__py3-none-any.whl

haiway/context/observability.py

@@ -8,6 +8,7 @@ from logging import WARNING as WARNING_LOGGING
 from logging import Logger, getLogger
 from types import TracebackType
 from typing import Any, Protocol, Self, final, runtime_checkable
+from uuid import UUID, uuid4
 
 from haiway.context.identifier import ScopeIdentifier
 from haiway.state import State
@@ -25,10 +26,18 @@ __all__ = (
     "ObservabilityMetricRecording",
     "ObservabilityScopeEntering",
     "ObservabilityScopeExiting",
+    "ObservabilityTraceIdentifying",
 )
 
 
 class ObservabilityLevel(IntEnum):
+    """
+    Defines the severity levels for observability recordings.
+
+    These levels correspond to standard logging levels, allowing consistent
+    severity indication across different types of observability records.
+    """
+
     # values from logging package
     ERROR = ERROR_LOGGING
     WARNING = WARNING_LOGGING
@@ -48,10 +57,36 @@ type ObservabilityAttribute = (
     | None
     | Missing
 )
+"""
+A type representing values that can be recorded as observability attributes.
+
+Includes scalar types (strings, numbers, booleans), sequences of these types,
+None, or Missing marker.
+"""
+
+
+@runtime_checkable
+class ObservabilityTraceIdentifying(Protocol):
+    """
+    Protocol for accessing trace identifier in an observability system.
+    """
+
+    def __call__(
+        self,
+        scope: ScopeIdentifier,
+        /,
+    ) -> UUID: ...
 
 
 @runtime_checkable
 class ObservabilityLogRecording(Protocol):
+    """
+    Protocol for recording log messages in an observability system.
+
+    Implementations should handle formatting and storing log messages
+    with appropriate contextual information from the scope.
+    """
+
     def __call__(
         self,
         scope: ScopeIdentifier,
@@ -65,6 +100,13 @@ class ObservabilityLogRecording(Protocol):
 
 @runtime_checkable
 class ObservabilityEventRecording(Protocol):
+    """
+    Protocol for recording events in an observability system.
+
+    Implementations should handle recording named events with
+    associated attributes and appropriate contextual information.
+    """
+
     def __call__(
         self,
         scope: ScopeIdentifier,
@@ -78,6 +120,13 @@ class ObservabilityEventRecording(Protocol):
 
 @runtime_checkable
 class ObservabilityMetricRecording(Protocol):
+    """
+    Protocol for recording metrics in an observability system.
+
+    Implementations should handle recording numeric measurements with
+    optional units and associated attributes.
+    """
+
     def __call__(
         self,
         scope: ScopeIdentifier,
@@ -93,6 +142,13 @@ class ObservabilityMetricRecording(Protocol):
 
 @runtime_checkable
 class ObservabilityAttributesRecording(Protocol):
+    """
+    Protocol for recording standalone attributes in an observability system.
+
+    Implementations should handle recording contextual attributes
+    that are not directly associated with logs, events, or metrics.
+    """
+
     def __call__(
         self,
         scope: ScopeIdentifier,
@@ -104,6 +160,12 @@ class ObservabilityAttributesRecording(Protocol):
 
 @runtime_checkable
 class ObservabilityScopeEntering(Protocol):
+    """
+    Protocol for handling scope entry in an observability system.
+
+    Implementations should record when execution enters a new scope.
+    """
+
     def __call__[Metric: State](
         self,
         scope: ScopeIdentifier,
@@ -113,6 +175,13 @@ class ObservabilityScopeEntering(Protocol):
 
 @runtime_checkable
 class ObservabilityScopeExiting(Protocol):
+    """
+    Protocol for handling scope exit in an observability system.
+
+    Implementations should record when execution exits a scope,
+    including any exceptions that caused the exit.
+    """
+
     def __call__[Metric: State](
         self,
         scope: ScopeIdentifier,
@@ -123,6 +192,16 @@ class ObservabilityScopeExiting(Protocol):
 
 
 class Observability:  # avoiding State inheritance to prevent propagation as scope state
+    """
+    Container for observability recording functions.
+
+    Provides a unified interface for recording various types of observability
+    data including logs, events, metrics, and attributes. Also handles recording
+    when scopes are entered and exited.
+
+    This class is immutable after initialization.
+    """
+
     __slots__ = (
         "attributes_recording",
         "event_recording",
@@ -130,10 +209,12 @@ class Observability:  # avoiding State inheritance to prevent propagation as sco
         "metric_recording",
         "scope_entering",
         "scope_exiting",
+        "trace_identifying",
     )
 
     def __init__(
         self,
+        trace_identifying: ObservabilityTraceIdentifying,
         log_recording: ObservabilityLogRecording,
         metric_recording: ObservabilityMetricRecording,
         event_recording: ObservabilityEventRecording,
@@ -141,6 +222,32 @@ class Observability:  # avoiding State inheritance to prevent propagation as sco
         scope_entering: ObservabilityScopeEntering,
         scope_exiting: ObservabilityScopeExiting,
     ) -> None:
+        """
+        Initialize an Observability container with recording functions.
+
+        Parameters
+        ----------
+        trace_identifying: ObservabilityTraceIdentifying
+            Function for identifying traces
+        log_recording: ObservabilityLogRecording
+            Function for recording log messages
+        metric_recording: ObservabilityMetricRecording
+            Function for recording metrics
+        event_recording: ObservabilityEventRecording
+            Function for recording events
+        attributes_recording: ObservabilityAttributesRecording
+            Function for recording attributes
+        scope_entering: ObservabilityScopeEntering
+            Function called when a scope is entered
+        scope_exiting: ObservabilityScopeExiting
+            Function called when a scope is exited
+        """
+        self.trace_identifying: ObservabilityTraceIdentifying
+        object.__setattr__(
+            self,
+            "trace_identifying",
+            trace_identifying,
+        )
         self.log_recording: ObservabilityLogRecording
         object.__setattr__(
             self,
@@ -165,7 +272,6 @@ class Observability:  # avoiding State inheritance to prevent propagation as sco
             "attributes_recording",
             attributes_recording,
         )
-
         self.scope_entering: ObservabilityScopeEntering
         object.__setattr__(
             self,
@@ -203,6 +309,32 @@ def _logger_observability(
     logger: Logger,
     /,
 ) -> Observability:
+    """
+    Create an Observability instance that uses a Logger for recording.
+
+    Adapts a standard Python logger to the Observability interface,
+    mapping observability concepts to log messages.
+
+    Parameters
+    ----------
+    logger: Logger
+        The logger to use for recording observability data
+
+    Returns
+    -------
+    Observability
+        An Observability instance that uses the logger
+    """
+
+    trace_id: UUID = uuid4()
+    trace_id_hex: str = trace_id.hex
+
+    def trace_identifying(
+        scope: ScopeIdentifier,
+        /,
+    ) -> UUID:
+        return trace_id
+
     def log_recording(
         scope: ScopeIdentifier,
         /,
@@ -213,7 +345,7 @@ def _logger_observability(
     ) -> None:
         logger.log(
             level,
-            f"{scope.unique_name} {message}",
+            f"[{trace_id_hex}] {scope.unique_name} {message}",
             *args,
             exc_info=exception,
         )
@@ -228,7 +360,8 @@ def _logger_observability(
     ) -> None:
         logger.log(
             level,
-            f"{scope.unique_name} Recorded event: {event} {format_str(attributes)}",
+            f"[{trace_id_hex}] {scope.unique_name} Recorded event:"
+            f" {event} {format_str(attributes)}",
         )
 
     def metric_recording(
@@ -244,14 +377,16 @@ def _logger_observability(
         if attributes:
             logger.log(
                 level,
-                f"{scope.unique_name} Recorded metric: {metric} = {value}{unit or ''}"
+                f"[{trace_id_hex}] {scope.unique_name} Recorded metric:"
+                f" {metric} = {value} {unit or ''}"
                 f"\n{format_str(attributes)}",
             )
 
         else:
             logger.log(
                 level,
-                f"{scope.unique_name} Recorded metric: {metric} = {value}{unit or ''}",
+                f"[{trace_id_hex}] {scope.unique_name} Recorded metric:"
+                f" {metric} = {value} {unit or ''}",
             )
 
     def attributes_recording(
@@ -265,7 +400,7 @@ def _logger_observability(
 
         logger.log(
             level,
-            f"{scope.unique_name} Recorded attributes: {format_str(attributes)}",
+            f"[{trace_id_hex}] {scope.unique_name} Recorded attributes: {format_str(attributes)}",
         )
 
     def scope_entering[Metric: State](
@@ -274,7 +409,7 @@ def _logger_observability(
     ) -> None:
         logger.log(
             ObservabilityLevel.DEBUG,
-            f"{scope.unique_name} Entering scope: {scope.label}",
+            f"[{trace_id_hex}] {scope.unique_name} Entering scope: {scope.label}",
         )
 
     def scope_exiting[Metric: State](
@@ -290,6 +425,7 @@ def _logger_observability(
         )
 
     return Observability(
+        trace_identifying=trace_identifying,
         log_recording=log_recording,
         event_recording=event_recording,
         metric_recording=metric_recording,
@@ -301,6 +437,16 @@ def _logger_observability(
 
 @final
 class ObservabilityContext:
+    """
+    Context manager for observability within a scope.
+
+    Manages observability recording within a context, propagating the
+    appropriate observability handler and scope information. Records
+    scope entry and exit events automatically.
+
+    This class is immutable after initialization.
+    """
+
     _context = ContextVar[Self]("ObservabilityContext")
 
     @classmethod
@@ -311,6 +457,25 @@ class ObservabilityContext:
         *,
         observability: Observability | Logger | None,
     ) -> Self:
+        """
+        Create an observability context for a scope.
+
+        If called within an existing context, inherits the observability
+        handler unless a new one is specified. If called outside any context,
+        creates a new root context with the specified or default observability.
+
+        Parameters
+        ----------
+        scope: ScopeIdentifier
+            The scope identifier this context is associated with
+        observability: Observability | Logger | None
+            The observability handler to use, or None to inherit or create default
+
+        Returns
+        -------
+        Self
+            A new observability context
+        """
         current: Self
         try:  # check for current scope
             current = cls._context.get()
@@ -350,6 +515,45 @@ class ObservabilityContext:
             observability=resolved_observability,
         )
 
+    @classmethod
+    def trace_id(
+        cls,
+        scope_identifier: ScopeIdentifier | None = None,
+    ) -> str:
+        """
+        Get the hexadecimal trace identifier for the specified scope or current scope.
+
+        This class method retrieves the trace identifier from the current observability context,
+        which can be used to correlate logs, events, and metrics across different components.
+
+        Parameters
+        ----------
+        scope_identifier: ScopeIdentifier | None, default=None
+            The scope identifier to get the trace ID for. If None, the current scope's
+            trace ID is returned.
+
+        Returns
+        -------
+        str
+            The hexadecimal representation of the trace ID
+
+        Raises
+        ------
+        RuntimeError
+            If called outside of any scope context
+        """
+        try:
+            return (
+                cls._context.get()
+                .observability.trace_identifying(
+                    scope_identifier if scope_identifier is not None else ScopeIdentifier.current()
+                )
+                .hex
+            )
+
+        except LookupError as exc:
+            raise RuntimeError("Attempting to access scope identifier outside of scope") from exc
+
     @classmethod
     def record_log(
         cls,
@@ -359,6 +563,22 @@ class ObservabilityContext:
         *args: Any,
         exception: BaseException | None,
     ) -> None:
+        """
+        Record a log message in the current observability context.
+
+        If no context is active, falls back to the root logger.
+
+        Parameters
+        ----------
+        level: ObservabilityLevel
+            The severity level for this log message
+        message: str
+            The log message text, may contain format placeholders
+        *args: Any
+            Format arguments for the message
+        exception: BaseException | None
+            Optional exception to associate with the log
+        """
         try:  # catch exceptions - we don't wan't to blow up on observability
             context: Self = cls._context.get()
 
@@ -388,6 +608,21 @@ class ObservabilityContext:
         *,
         attributes: Mapping[str, ObservabilityAttribute],
     ) -> None:
+        """
+        Record an event in the current observability context.
+
+        Records a named event with associated attributes. Falls back to logging
+        an error if recording fails.
+
+        Parameters
+        ----------
+        level: ObservabilityLevel
+            The severity level for this event
+        event: str
+            The name of the event
+        attributes: Mapping[str, ObservabilityAttribute]
+            Key-value attributes associated with the event
+        """
         try:  # catch exceptions - we don't wan't to blow up on observability
             context: Self = cls._context.get()
 
@@ -417,6 +652,25 @@ class ObservabilityContext:
         unit: str | None,
         attributes: Mapping[str, ObservabilityAttribute],
     ) -> None:
+        """
+        Record a metric in the current observability context.
+
+        Records a numeric measurement with an optional unit and associated attributes.
+        Falls back to logging an error if recording fails.
+
+        Parameters
+        ----------
+        level: ObservabilityLevel
+            The severity level for this metric
+        metric: str
+            The name of the metric
+        value: float | int
+            The numeric value of the metric
+        unit: str | None
+            Optional unit for the metric (e.g., "ms", "bytes")
+        attributes: Mapping[str, ObservabilityAttribute]
+            Key-value attributes associated with the metric
+        """
         try:  # catch exceptions - we don't wan't to blow up on observability
             context: Self = cls._context.get()
 
@@ -445,6 +699,19 @@ class ObservabilityContext:
         *,
         attributes: Mapping[str, ObservabilityAttribute],
     ) -> None:
+        """
+        Record standalone attributes in the current observability context.
+
+        Records key-value attributes not directly associated with a specific log,
+        event, or metric. Falls back to logging an error if recording fails.
+
+        Parameters
+        ----------
+        level: ObservabilityLevel
+            The severity level for these attributes
+        attributes: Mapping[str, ObservabilityAttribute]
+            Key-value attributes to record
+        """
         try:  # catch exceptions - we don't wan't to blow up on observability
             context: Self = cls._context.get()
 
@@ -512,6 +779,16 @@ class ObservabilityContext:
         )
 
     def __enter__(self) -> None:
+        """
+        Enter this observability context.
+
+        Sets this context as the current one and records scope entry.
+
+        Raises
+        ------
+        AssertionError
+            If attempting to re-enter an already active context
+        """
         assert self._token is None, "Context reentrance is not allowed"  # nosec: B101
         object.__setattr__(
             self,
@@ -526,6 +803,25 @@ class ObservabilityContext:
         exc_val: BaseException | None,
         exc_tb: TracebackType | None,
     ) -> None:
+        """
+        Exit this observability context.
+
+        Restores the previous context and records scope exit.
+
+        Parameters
+        ----------
+        exc_type: type[BaseException] | None
+            Type of exception that caused the exit
+        exc_val: BaseException | None
+            Exception instance that caused the exit
+        exc_tb: TracebackType | None
+            Traceback for the exception
+
+        Raises
+        ------
+        AssertionError
+            If the context is not active
+        """
         assert self._token is not None, "Unbalanced context enter/exit"  # nosec: B101
         ObservabilityContext._context.reset(self._token)
         object.__setattr__(

haiway/context/state.py

@@ -16,6 +16,14 @@ __all__ = (
 
 @final
 class ScopeState:
+    """
+    Container for state objects within a scope.
+
+    Stores state objects by their type, allowing retrieval by type.
+    Only one state of a given type can be stored at a time.
+    This class is immutable after initialization.
+    """
+
     __slots__ = ("_state",)
 
     def __init__(
@@ -54,6 +62,30 @@ class ScopeState:
         /,
         default: StateType | None = None,
     ) -> StateType:
+        """
+        Get a state object by its type.
+
+        If the state type is not found, attempts to use a provided default
+        or instantiate a new instance of the type. Raises MissingState
+        if neither is possible.
+
+        Parameters
+        ----------
+        state: type[StateType]
+            The type of state to retrieve
+        default: StateType | None
+            Optional default value to use if state not found
+
+        Returns
+        -------
+        StateType
+            The requested state object
+
+        Raises
+        ------
+        MissingState
+            If state not found and default not provided or instantiation fails
+        """
         if state in self._state:
             return cast(StateType, self._state[state])
 
@@ -77,6 +109,22 @@ class ScopeState:
         self,
         state: Iterable[State],
     ) -> Self:
+        """
+        Create a new ScopeState with updated state objects.
+
+        Combines the current state with new state objects, with new state
+        objects overriding existing ones of the same type.
+
+        Parameters
+        ----------
+        state: Iterable[State]
+            New state objects to add or replace
+
+        Returns
+        -------
+        Self
+            A new ScopeState with the combined state
+        """
         if state:
             return self.__class__(
                 [
@@ -91,6 +139,14 @@ class ScopeState:
 
 @final
 class StateContext:
+    """
+    Context manager for state within a scope.
+
+    Manages state propagation and access within a context. Provides
+    methods to retrieve state by type and create updated state contexts.
+    This class is immutable after initialization.
+    """
+
     _context = ContextVar[ScopeState]("StateContext")
 
     @classmethod
@@ -100,6 +156,31 @@ class StateContext:
         /,
         default: StateType | None = None,
     ) -> StateType:
+        """
+        Get a state object by type from the current context.
+
+        Retrieves a state object of the specified type from the current context.
+        If not found, uses the provided default or attempts to create a new instance.
+
+        Parameters
+        ----------
+        state: type[StateType]
+            The type of state to retrieve
+        default: StateType | None
+            Optional default value to use if state not found
+
+        Returns
+        -------
+        StateType
+            The requested state object
+
+        Raises
+        ------
+        MissingContext
+            If called outside of a state context
+        MissingState
+            If state not found and default not provided or instantiation fails
+        """
         try:
             return cls._context.get().state(state, default=default)
 
@@ -112,6 +193,22 @@ class StateContext:
         state: Iterable[State],
         /,
     ) -> Self:
+        """
+        Create a new StateContext with updated state.
+
+        If called within an existing context, inherits and updates that context's state.
+        If called outside any context, creates a new root context.
+
+        Parameters
+        ----------
+        state: Iterable[State]
+            New state objects to add or replace
+
+        Returns
+        -------
+        Self
+            A new StateContext with the combined state
+        """
         try:
             # update current scope context
             return cls(state=cls._context.get().updated(state=state))
@@ -161,6 +258,16 @@ class StateContext:
         )
 
     def __enter__(self) -> None:
+        """
+        Enter this state context.
+
+        Sets this context's state as the current state in the context.
+
+        Raises
+        ------
+        AssertionError
+            If attempting to re-enter an already active context
+        """
         assert self._token is None, "Context reentrance is not allowed"  # nosec: B101
         object.__setattr__(
             self,
@@ -174,6 +281,25 @@ class StateContext:
         exc_val: BaseException | None,
         exc_tb: TracebackType | None,
     ) -> None:
+        """
+        Exit this state context.
+
+        Restores the previous state context.
+
+        Parameters
+        ----------
+        exc_type: type[BaseException] | None
+            Type of exception that caused the exit
+        exc_val: BaseException | None
+            Exception instance that caused the exit
+        exc_tb: TracebackType | None
+            Traceback for the exception
+
+        Raises
+        ------
+        AssertionError
+            If the context is not active
+        """
         assert self._token is not None, "Unbalanced context enter/exit"  # nosec: B101
         StateContext._context.reset(self._token)
         object.__setattr__(