haiway 0.18.1__py3-none-any.whl → 0.19.0__py3-none-any.whl

haiway/__init__.py

@@ -20,7 +20,6 @@ from haiway.context import (
 )
 from haiway.helpers import (
     LoggerObservability,
-    ResultTrace,
     asynchronous,
     cache,
     retry,
@@ -87,7 +86,6 @@ __all__ = (
     "ObservabilityMetricRecording",
     "ObservabilityScopeEntering",
     "ObservabilityScopeExiting",
-    "ResultTrace",
     "ScopeContext",
     "ScopeIdentifier",
     "State",

haiway/context/access.py

@@ -11,6 +11,7 @@ from collections.abc import (
     Callable,
     Coroutine,
     Iterable,
+    Mapping,
 )
 from logging import Logger
 from types import TracebackType
@@ -597,81 +598,69 @@ class ctx:
             ObservabilityLevel.DEBUG, message, *args, exception=exception, **extra
         )
 
+    @overload
     @staticmethod
-    def event(
-        event: State,
+    def record(
+        level: ObservabilityLevel = ObservabilityLevel.DEBUG,
         /,
         *,
-        level: ObservabilityLevel = ObservabilityLevel.INFO,
-        **extra: Any,
-    ) -> None:
-        """
-        Record event within current scope context.
-
-        Parameters
-        ----------
-        event: State
-            contents of event to be recorded.
+        attributes: Mapping[str, ObservabilityAttribute],
+    ) -> None: ...
 
-        Returns
-        -------
-        None
-        """
-
-        ObservabilityContext.record_event(
-            event,
-            level=level,
-            **extra,
-        )
+    @overload
+    @staticmethod
+    def record(
+        level: ObservabilityLevel = ObservabilityLevel.DEBUG,
+        /,
+        *,
+        event: str,
+        attributes: Mapping[str, ObservabilityAttribute] | None = None,
+    ) -> None: ...
 
+    @overload
     @staticmethod
-    def metric(
-        metric: str,
+    def record(
+        level: ObservabilityLevel = ObservabilityLevel.DEBUG,
         /,
         *,
+        metric: str,
         value: float | int,
         unit: str | None = None,
-        **extra: Any,
-    ) -> None:
-        """
-        Record metric within current scope context.
-
-        Parameters
-        ----------
-        metric: State
-            name of metric to be recorded.
-        value: float | int
-            value of metric to be recorded.
-        unit: str | None = None
-            unit of metric to be recorded.
-
-        Returns
-        -------
-        None
-        """
-
-        ObservabilityContext.record_metric(
-            metric,
-            value=value,
-            unit=unit,
-            **extra,
-        )
+        attributes: Mapping[str, ObservabilityAttribute] | None = None,
+    ) -> None: ...
 
     @staticmethod
-    def attributes(**attributes: ObservabilityAttribute) -> None:
-        """
-        Record attributes within current scope context.
-
-        Parameters
-        ----------
-        **attributes: ObservabilityAttribute,
-            attributes to be recorded within current context.
+    def record(
+        level: ObservabilityLevel = ObservabilityLevel.DEBUG,
+        /,
+        *,
+        event: str | None = None,
+        metric: str | None = None,
+        value: float | int | None = None,
+        unit: str | None = None,
+        attributes: Mapping[str, ObservabilityAttribute] | None = None,
+    ) -> None:
+        if event is not None:
+            assert metric is None  # nosec: B101
+            ObservabilityContext.record_event(
+                level,
+                event,
+                attributes=attributes or {},
+            )
 
-        Returns
-        -------
-        None
-        """
+        elif metric is not None:
+            assert event is None  # nosec: B101
+            assert value is not None  # nosec: B101
+            ObservabilityContext.record_metric(
+                level,
+                metric,
+                value=value,
+                unit=unit,
+                attributes=attributes or {},
+            )
 
-        ObservabilityContext.record_attributes(
-            **attributes,
-        )
+        else:
+            ObservabilityContext.record_attributes(
+                level,
+                attributes=attributes or {},
+            )

haiway/context/observability.py

@@ -1,4 +1,4 @@
-from collections.abc import Sequence
+from collections.abc import Mapping, Sequence
 from contextvars import ContextVar, Token
 from enum import IntEnum
 from logging import DEBUG as DEBUG_LOGGING
@@ -10,9 +10,9 @@ from types import TracebackType
 from typing import Any, Final, Protocol, Self, final, runtime_checkable
 
 from haiway.context.identifier import ScopeIdentifier
-
-# from haiway.context.logging import LoggerContext
 from haiway.state import State
+from haiway.types import Missing
+from haiway.utils.formatting import format_str
 
 __all__ = (
     "DEBUG",
@@ -46,7 +46,16 @@ INFO: Final[int] = ObservabilityLevel.INFO
 DEBUG: Final[int] = ObservabilityLevel.DEBUG
 
 type ObservabilityAttribute = (
-    Sequence[str] | Sequence[float] | Sequence[int] | Sequence[bool] | str | float | int | bool
+    Sequence[str]
+    | Sequence[float]
+    | Sequence[int]
+    | Sequence[bool]
+    | str
+    | float
+    | int
+    | bool
+    | None
+    | Missing
 )
 
 
@@ -60,7 +69,6 @@ class ObservabilityLogRecording(Protocol):
         message: str,
         *args: Any,
         exception: BaseException | None,
-        **extra: Any,
     ) -> None: ...
 
 
@@ -70,10 +78,10 @@ class ObservabilityEventRecording(Protocol):
         self,
         scope: ScopeIdentifier,
         /,
-        *,
         level: ObservabilityLevel,
-        event: State,
-        **extra: Any,
+        *,
+        event: str,
+        attributes: Mapping[str, ObservabilityAttribute],
     ) -> None: ...
 
 
@@ -83,11 +91,12 @@ class ObservabilityMetricRecording(Protocol):
         self,
         scope: ScopeIdentifier,
         /,
+        level: ObservabilityLevel,
         *,
         metric: str,
         value: float | int,
         unit: str | None,
-        **extra: Any,
+        attributes: Mapping[str, ObservabilityAttribute],
     ) -> None: ...
 
 
@@ -97,7 +106,8 @@ class ObservabilityAttributesRecording(Protocol):
         self,
         scope: ScopeIdentifier,
         /,
-        **attributes: ObservabilityAttribute,
+        level: ObservabilityLevel,
+        attributes: Mapping[str, ObservabilityAttribute],
     ) -> None: ...
 
 
@@ -209,7 +219,6 @@ def _logger_observability(
         message: str,
         *args: Any,
         exception: BaseException | None,
-        **extra: Any,
     ) -> None:
         logger.log(
             level,
@@ -221,42 +230,51 @@ def _logger_observability(
     def event_recording(
         scope: ScopeIdentifier,
         /,
-        *,
         level: ObservabilityLevel,
-        event: State,
-        **extra: Any,
+        *,
+        event: str,
+        attributes: Mapping[str, ObservabilityAttribute],
     ) -> None:
         logger.log(
             level,
-            f"{scope.unique_name} Recorded event:\n{event.to_str(pretty=True)}",
+            f"{scope.unique_name} Recorded event: {event} {format_str(attributes)}",
         )
 
     def metric_recording(
         scope: ScopeIdentifier,
         /,
+        level: ObservabilityLevel,
         *,
         metric: str,
         value: float | int,
         unit: str | None,
-        **extra: Any,
+        attributes: Mapping[str, ObservabilityAttribute],
     ) -> None:
-        logger.log(
-            INFO,
-            f"{scope.unique_name} Recorded metric: {metric}={value}{unit or ''}",
-        )
+        if attributes:
+            logger.log(
+                level,
+                f"{scope.unique_name} Recorded metric: {metric}={value}{unit or ''}"
+                f"\n{format_str(attributes)}",
+            )
+
+        else:
+            logger.log(
+                level,
+                f"{scope.unique_name} Recorded metric: {metric}={value}{unit or ''}",
+            )
 
     def attributes_recording(
         scope: ScopeIdentifier,
         /,
-        **attributes: ObservabilityAttribute,
+        level: ObservabilityLevel,
+        attributes: Mapping[str, ObservabilityAttribute],
     ) -> None:
         if not attributes:
             return
 
         logger.log(
-            INFO,
-            f"{scope.unique_name} Recorded attributes:"
-            f"\n{'\n'.join([f'{k}: {v}' for k, v in attributes.items()])}",
+            level,
+            f"{scope.unique_name} Recorded attributes: {format_str(attributes)}",
         )
 
     def scope_entering[Metric: State](
@@ -349,7 +367,6 @@ class ObservabilityContext:
         /,
         *args: Any,
         exception: BaseException | None,
-        **extra: Any,
     ) -> None:
         try:  # catch exceptions - we don't wan't to blow up on observability
             context: Self = cls._context.get()
@@ -361,7 +378,6 @@ class ObservabilityContext:
                     message,
                     *args,
                     exception=exception,
-                    **extra,
                 )
 
         except LookupError:
@@ -375,11 +391,11 @@ class ObservabilityContext:
     @classmethod
     def record_event(
         cls,
-        event: State,
+        level: ObservabilityLevel,
+        event: str,
         /,
         *,
-        level: ObservabilityLevel,
-        **extra: Any,
+        attributes: Mapping[str, ObservabilityAttribute],
     ) -> None:
         try:  # catch exceptions - we don't wan't to blow up on observability
             context: Self = cls._context.get()
@@ -389,7 +405,7 @@ class ObservabilityContext:
                     context._scope,
                     level=level,
                     event=event,
-                    **extra,
+                    attributes=attributes,
                 )
 
         except Exception as exc:
@@ -402,12 +418,13 @@ class ObservabilityContext:
     @classmethod
     def record_metric(
         cls,
+        level: ObservabilityLevel,
         metric: str,
         /,
         *,
         value: float | int,
         unit: str | None,
-        **extra: Any,
+        attributes: Mapping[str, ObservabilityAttribute],
     ) -> None:
         try:  # catch exceptions - we don't wan't to blow up on observability
             context: Self = cls._context.get()
@@ -415,10 +432,11 @@ class ObservabilityContext:
             if context.observability is not None:
                 context.observability.metric_recording(
                     context._scope,
+                    level=level,
                     metric=metric,
                     value=value,
                     unit=unit,
-                    **extra,
+                    attributes=attributes,
                 )
 
         except Exception as exc:
@@ -431,7 +449,10 @@ class ObservabilityContext:
     @classmethod
     def record_attributes(
         cls,
-        **attributes: ObservabilityAttribute,
+        level: ObservabilityLevel,
+        /,
+        *,
+        attributes: Mapping[str, ObservabilityAttribute],
     ) -> None:
         try:  # catch exceptions - we don't wan't to blow up on observability
             context: Self = cls._context.get()
@@ -439,13 +460,14 @@ class ObservabilityContext:
             if context.observability is not None:
                 context.observability.attributes_recording(
                     context._scope,
-                    **attributes,
+                    level=level,
+                    attributes=attributes,
                 )
 
         except Exception as exc:
             cls.record_log(
                 ERROR,
-                f"Failed to record attributes: {attributes}",
+                "Failed to record attributes",
                 exception=exc,
             )
 

haiway/helpers/__init__.py

@@ -4,14 +4,13 @@ from haiway.helpers.observability import LoggerObservability
 from haiway.helpers.retries import retry
 from haiway.helpers.throttling import throttle
 from haiway.helpers.timeouted import timeout
-from haiway.helpers.tracing import ResultTrace, traced
+from haiway.helpers.tracing import traced
 
 __all__ = (
     "CacheMakeKey",
     "CacheRead",
     "CacheWrite",
     "LoggerObservability",
-    "ResultTrace",
     "asynchronous",
     "cache",
     "retry",

haiway/helpers/observability.py

@@ -1,10 +1,12 @@
-from collections.abc import Sequence
-from logging import Logger
+from collections.abc import Mapping
+from logging import Logger, getLogger
 from time import monotonic
 from typing import Any
 
 from haiway.context import Observability, ObservabilityLevel, ScopeIdentifier
+from haiway.context.observability import ObservabilityAttribute
 from haiway.state import State
+from haiway.utils.formatting import format_str
 
 __all__ = ("LoggerObservability",)
 
@@ -62,12 +64,13 @@ class ScopeStore:
 
 
 def LoggerObservability(  # noqa: C901, PLR0915
-    logger: Logger,
+    logger: Logger | None = None,
     /,
     *,
-    summarize_context: bool = __debug__,
+    debug_context: bool = __debug__,
 ) -> Observability:
     root_scope: ScopeIdentifier | None = None
+    root_logger: Logger | None = logger
     scopes: dict[str, ScopeStore] = {}
 
     def log_recording(
@@ -77,12 +80,12 @@ def LoggerObservability(  # noqa: C901, PLR0915
         message: str,
         *args: Any,
         exception: BaseException | None,
-        **extra: Any,
     ) -> None:
         assert root_scope is not None  # nosec: B101
+        assert root_logger is not None  # nosec: B101
         assert scope.scope_id in scopes  # nosec: B101
 
-        logger.log(
+        root_logger.log(
             level,
             f"{scope.unique_name} {message}",
             *args,
@@ -92,19 +95,20 @@ def LoggerObservability(  # noqa: C901, PLR0915
     def event_recording(
         scope: ScopeIdentifier,
         /,
-        *,
         level: ObservabilityLevel,
-        event: State,
-        **extra: Any,
+        *,
+        event: str,
+        attributes: Mapping[str, ObservabilityAttribute],
     ) -> None:
         assert root_scope is not None  # nosec: B101
+        assert root_logger is not None  # nosec: B101
         assert scope.scope_id in scopes  # nosec: B101
 
-        event_str: str = f"Event:\n{event.to_str(pretty=True)}"
-        if summarize_context:  # store only for summary
+        event_str: str = f"Event: {event} {format_str(attributes)}"
+        if debug_context:  # store only for summary
             scopes[scope.scope_id].store.append(event_str)
 
-        logger.log(
+        root_logger.log(
             level,
             f"{scope.unique_name} {event_str}",
         )
@@ -112,41 +116,50 @@ def LoggerObservability(  # noqa: C901, PLR0915
     def metric_recording(
         scope: ScopeIdentifier,
         /,
+        level: ObservabilityLevel,
         *,
         metric: str,
         value: float | int,
         unit: str | None,
-        **extra: Any,
+        attributes: Mapping[str, ObservabilityAttribute],
     ) -> None:
         assert root_scope is not None  # nosec: B101
+        assert root_logger is not None  # nosec: B101
         assert scope.scope_id in scopes  # nosec: B101
 
-        metric_str: str = f"Metric: {metric}={value}{unit or ''}"
-        if summarize_context:  # store only for summary
+        metric_str: str
+        if attributes:
+            metric_str = f"Metric: {metric}={value}{unit or ''}\n{format_str(attributes)}"
+
+        else:
+            metric_str = f"Metric: {metric}={value}{unit or ''}"
+
+        if debug_context:  # store only for summary
             scopes[scope.scope_id].store.append(metric_str)
 
-        logger.log(
-            ObservabilityLevel.INFO,
+        root_logger.log(
+            level,
             f"{scope.unique_name} {metric_str}",
         )
 
     def attributes_recording(
         scope: ScopeIdentifier,
         /,
-        **attributes: Sequence[str | float | int] | str | float | int,
+        level: ObservabilityLevel,
+        attributes: Mapping[str, ObservabilityAttribute],
     ) -> None:
+        assert root_scope is not None  # nosec: B101
+        assert root_logger is not None  # nosec: B101
+
         if not attributes:
             return
 
-        attributes_str: str = (
-            f"{scope.unique_name} Attributes:"
-            f"\n{'\n'.join([f'{k}: {v}' for k, v in attributes.items()])}"
-        )
-        if summarize_context:  # store only for summary
+        attributes_str: str = f"Attributes: {format_str(attributes)}"
+        if debug_context:  # store only for summary
             scopes[scope.scope_id].store.append(attributes_str)
 
-        logger.log(
-            ObservabilityLevel.INFO,
+        root_logger.log(
+            level,
             attributes_str,
         )
 
@@ -158,18 +171,21 @@ def LoggerObservability(  # noqa: C901, PLR0915
         scope_store: ScopeStore = ScopeStore(scope)
         scopes[scope.scope_id] = scope_store
 
-        logger.log(
-            ObservabilityLevel.INFO,
-            f"{scope.unique_name} Entering scope: {scope.label}",
-        )
-
         nonlocal root_scope
+        nonlocal root_logger
         if root_scope is None:
             root_scope = scope
+            root_logger = logger or getLogger(scope.label)
 
         else:
             scopes[scope.parent_id].nested.append(scope_store)
 
+        assert root_logger is not None  # nosec: B101
+        root_logger.log(
+            ObservabilityLevel.INFO,
+            f"{scope.unique_name} Entering scope: {scope.label}",
+        )
+
     def scope_exiting[Metric: State](
         scope: ScopeIdentifier,
         /,
@@ -177,8 +193,10 @@ def LoggerObservability(  # noqa: C901, PLR0915
         exception: BaseException | None,
     ) -> None:
         nonlocal root_scope
+        nonlocal root_logger
         nonlocal scopes
         assert root_scope is not None  # nosec: B101
+        assert root_logger is not None  # nosec: B101
         assert scope.scope_id in scopes  # nosec: B101
 
         scopes[scope.scope_id].exit()
@@ -186,15 +204,15 @@ def LoggerObservability(  # noqa: C901, PLR0915
         if not scopes[scope.scope_id].try_complete():
             return  # not completed yet or already completed
 
-        logger.log(
+        root_logger.log(
             ObservabilityLevel.INFO,
             f"{scope.unique_name} Exiting scope: {scope.label}",
         )
         metric_str: str = f"Metric - scope_time:{scopes[scope.scope_id].time:.3f}s"
-        if summarize_context:  # store only for summary
+        if debug_context:  # store only for summary
             scopes[scope.scope_id].store.append(metric_str)
 
-        logger.log(
+        root_logger.log(
             ObservabilityLevel.INFO,
             f"{scope.unique_name} {metric_str}",
         )
@@ -206,14 +224,15 @@ def LoggerObservability(  # noqa: C901, PLR0915
 
         # check for root completion
         if scopes[root_scope.scope_id].completed:
-            if summarize_context:
-                logger.log(
+            if debug_context:
+                root_logger.log(
                     ObservabilityLevel.DEBUG,
                     f"Observability summary:\n{_tree_summary(scopes[root_scope.scope_id])}",
                 )
 
             # finished root - cleanup state
             root_scope = None
+            root_logger = None
             scopes = {}
 
     return Observability(