haiway 0.7.1__tar.gz → 0.8.0__tar.gz

{haiway-0.7.1/src/haiway.egg-info → haiway-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: haiway
-Version: 0.7.1
+Version: 0.8.0
 Summary: Framework for dependency injection and state management within structured concurrency model.
 Maintainer-email: Kacper Kaliński <kacper.kalinski@miquido.com>
 License: MIT License

{haiway-0.7.1 → haiway-0.8.0}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "haiway"
 description = "Framework for dependency injection and state management within structured concurrency model."
-version = "0.7.1"
+version = "0.8.0"
 readme = "README.md"
 maintainers = [
   { name = "Kacper Kaliński", email = "kacper.kalinski@miquido.com" },

{haiway-0.7.1 → haiway-0.8.0}/src/haiway/__init__.py

@@ -1,13 +1,19 @@
 from haiway.context import (
     Disposable,
     Disposables,
+    MetricsContext,
+    MetricsHandler,
+    MetricsRecording,
+    MetricsScopeEntering,
+    MetricsScopeExiting,
     MissingContext,
     MissingState,
-    ScopeMetrics,
+    ScopeIdentifier,
     ctx,
 )
 from haiway.helpers import (
     ArgumentsTrace,
+    MetricsLogger,
     ResultTrace,
     asynchronous,
     cache,
@@ -50,11 +56,17 @@ __all__ = [
     "AttributeRequirement",
     "Disposable",
     "Disposables",
+    "MetricsContext",
+    "MetricsHandler",
+    "MetricsLogger",
+    "MetricsRecording",
+    "MetricsScopeEntering",
+    "MetricsScopeExiting",
     "Missing",
     "MissingContext",
     "MissingState",
     "ResultTrace",
-    "ScopeMetrics",
+    "ScopeIdentifier",
     "State",
     "always",
     "async_always",

haiway-0.8.0/src/haiway/context/__init__.py

@@ -0,0 +1,25 @@
+from haiway.context.access import ctx
+from haiway.context.disposables import Disposable, Disposables
+from haiway.context.identifier import ScopeIdentifier
+from haiway.context.metrics import (
+    MetricsContext,
+    MetricsHandler,
+    MetricsRecording,
+    MetricsScopeEntering,
+    MetricsScopeExiting,
+)
+from haiway.context.types import MissingContext, MissingState
+
+__all__ = [
+    "Disposable",
+    "Disposables",
+    "MetricsContext",
+    "MetricsHandler",
+    "MetricsRecording",
+    "MetricsScopeEntering",
+    "MetricsScopeExiting",
+    "MissingContext",
+    "MissingState",
+    "ScopeIdentifier",
+    "ctx",
+]

{haiway-0.7.1 → haiway-0.8.0}/src/haiway/context/access.py

@@ -1,4 +1,4 @@
-from asyncio import CancelledError, Task, current_task
+from asyncio import CancelledError, Task, current_task, iscoroutinefunction
 from collections.abc import (
     AsyncGenerator,
     AsyncIterator,
@@ -9,14 +9,16 @@ from collections.abc import (
 from contextvars import Context, copy_context
 from logging import Logger
 from types import TracebackType
-from typing import Any, final
+from typing import Any, final, overload
 
 from haiway.context.disposables import Disposable, Disposables
-from haiway.context.metrics import MetricsContext, ScopeMetrics
+from haiway.context.identifier import ScopeIdentifier
+from haiway.context.logging import LoggerContext
+from haiway.context.metrics import MetricsContext, MetricsHandler
 from haiway.context.state import StateContext
 from haiway.context.tasks import TaskGroupContext
 from haiway.state import State
-from haiway.utils import freeze
+from haiway.utils import freeze, mimic_function
 
 __all__ = [
     "ctx",
@@ -25,38 +27,42 @@ __all__ = [
 
 @final
 class ScopeContext:
-    def __init__(  # noqa: PLR0913
+    def __init__(
         self,
-        trace_id: str | None,
-        name: str,
+        label: str,
         logger: Logger | None,
         state: tuple[State, ...],
         disposables: Disposables | None,
-        completion: Callable[[ScopeMetrics], Coroutine[None, None, None]]
-        | Callable[[ScopeMetrics], None]
-        | None,
+        metrics: MetricsHandler | None,
     ) -> None:
+        self._identifier: ScopeIdentifier = ScopeIdentifier.scope(label)
+        self._logger_context: LoggerContext = LoggerContext(
+            self._identifier,
+            logger=logger,
+        )
         self._task_group_context: TaskGroupContext = TaskGroupContext()
-        # postponing state creation to include disposables if needed
+        # postponing state creation to include disposables state when prepared
         self._state_context: StateContext
         self._state: tuple[State, ...] = state
         self._disposables: Disposables | None = disposables
         # pre-building metrics context to ensure nested context registering
         self._metrics_context: MetricsContext = MetricsContext.scope(
-            name,
-            logger=logger,
-            trace_id=trace_id,
-            completion=completion,
+            self._identifier,
+            metrics=metrics,
         )
 
         freeze(self)
 
-    def __enter__(self) -> None:
+    def __enter__(self) -> str:
         assert self._disposables is None, "Can't enter synchronous context with disposables"  # nosec: B101
+        self._identifier.__enter__()
+        self._logger_context.__enter__()
         self._state_context = StateContext.updated(self._state)
         self._state_context.__enter__()
         self._metrics_context.__enter__()
 
+        return self._identifier.trace_id
+
     def __exit__(
         self,
         exc_type: type[BaseException] | None,
@@ -75,7 +81,21 @@ class ScopeContext:
             exc_tb=exc_tb,
         )
 
-    async def __aenter__(self) -> None:
+        self._logger_context.__exit__(
+            exc_type=exc_type,
+            exc_val=exc_val,
+            exc_tb=exc_tb,
+        )
+
+        self._identifier.__exit__(
+            exc_type=exc_type,
+            exc_val=exc_val,
+            exc_tb=exc_tb,
+        )
+
+    async def __aenter__(self) -> str:
+        self._identifier.__enter__()
+        self._logger_context.__enter__()
         await self._task_group_context.__aenter__()
 
         if self._disposables is not None:
@@ -89,6 +109,8 @@ class ScopeContext:
         self._state_context.__enter__()
         self._metrics_context.__enter__()
 
+        return self._identifier.trace_id
+
     async def __aexit__(
         self,
         exc_type: type[BaseException] | None,
@@ -120,35 +142,82 @@ class ScopeContext:
             exc_tb=exc_tb,
         )
 
+        self._logger_context.__exit__(
+            exc_type=exc_type,
+            exc_val=exc_val,
+            exc_tb=exc_tb,
+        )
+
+        self._identifier.__exit__(
+            exc_type=exc_type,
+            exc_val=exc_val,
+            exc_tb=exc_tb,
+        )
+
+    @overload
+    def __call__[Result, **Arguments](
+        self,
+        function: Callable[Arguments, Coroutine[None, None, Result]],
+    ) -> Callable[Arguments, Coroutine[None, None, Result]]: ...
+
+    @overload
+    def __call__[Result, **Arguments](
+        self,
+        function: Callable[Arguments, Result],
+    ) -> Callable[Arguments, Result]: ...
+
+    def __call__[Result, **Arguments](
+        self,
+        function: Callable[Arguments, Coroutine[None, None, Result]] | Callable[Arguments, Result],
+    ) -> Callable[Arguments, Coroutine[None, None, Result]] | Callable[Arguments, Result]:
+        if iscoroutinefunction(function):
+
+            async def async_context(
+                *args: Arguments.args,
+                **kwargs: Arguments.kwargs,
+            ) -> Result:
+                async with self:
+                    return await function(*args, **kwargs)
+
+            return mimic_function(function, within=async_context)
+
+        else:
+
+            def sync_context(
+                *args: Arguments.args,
+                **kwargs: Arguments.kwargs,
+            ) -> Result:
+                with self:
+                    return function(*args, **kwargs)  # pyright: ignore[reportReturnType]
+
+            return mimic_function(function, within=sync_context)  # pyright: ignore[reportReturnType]
+
 
 @final
 class ctx:
     @staticmethod
     def scope(
-        name: str,
+        label: str,
         /,
         *state: State,
         disposables: Disposables | Iterable[Disposable] | None = None,
         logger: Logger | None = None,
-        trace_id: str | None = None,
-        completion: Callable[[ScopeMetrics], Coroutine[None, None, None]]
-        | Callable[[ScopeMetrics], None]
-        | None = None,
+        metrics: MetricsHandler | None = None,
     ) -> ScopeContext:
         """
-        Access scope context with given parameters. When called within an existing context\
-         it becomes nested with current context as its predecessor.
+        Prepare scope context with given parameters. When called within an existing context\
+         it becomes nested with current context as its parent.
 
         Parameters
         ----------
-        name: Value
+        label: str
             name of the scope context
 
         *state: State | Disposable
             state propagated within the scope context, will be merged with current state by\
              replacing current with provided on conflict.
 
-        disposables: Disposables | list[Disposable] | None
+        disposables: Disposables | Iterable[Disposable] | None
             disposables consumed within the context when entered. Produced state will automatically\
              be added to the scope state. Using asynchronous context is required if any disposables\
              were provided.
@@ -157,21 +226,17 @@ class ctx:
             logger used within the scope context, when not provided current logger will be used\
              if any, otherwise the logger with the scope name will be requested.
 
-        trace_id: str | None = None
-            tracing identifier included in logs produced within the scope context, when not\
-             provided current identifier will be used if any, otherwise it random id will\
-             be generated
-
-        completion: Callable[[ScopeMetrics], Coroutine[None, None, None]] | Callable[[ScopeMetrics], None] | None = None
-            completion callback called on exit from the scope granting access to finished\
-             scope metrics. Completion is called outside of the context when its metrics is\
-             already finished. Make sure to avoid any long operations within the completion.
+        metrics_store: MetricsStore | None = None
+            metrics storage solution responsible for recording and storing metrics.\
+             Metrics recroding will be ignored if storage is not provided.
+            Assigning metrics_store within existing context will result in an error.
 
         Returns
         -------
         ScopeContext
-            context object intended to enter context manager with it
-        """  # noqa: E501
+            context object intended to enter context manager with.\
+             context manager will provide trace_id of current context.
+        """
 
         resolved_disposables: Disposables | None
         match disposables:
@@ -185,12 +250,11 @@ class ctx:
                 resolved_disposables = Disposables(*iterable)
 
         return ScopeContext(
-            trace_id=trace_id,
-            name=name,
+            label=label,
             logger=logger,
             state=state,
             disposables=resolved_disposables,
-            completion=completion,
+            metrics=metrics,
         )
 
     @staticmethod
@@ -339,32 +403,25 @@ class ctx:
         )
 
     @staticmethod
-    def record[Metric: State](
-        metric: Metric,
+    def record(
+        metric: State,
         /,
-        merge: Callable[[Metric, Metric], Metric] = lambda lhs, rhs: rhs,
     ) -> None:
         """
         Record metric within current scope context.
 
         Parameters
         ----------
-        metric: MetricType
-            value of metric to be recorded
-
-        merge: Callable[[MetricType, MetricType], MetricType] = lambda lhs, rhs: rhs
-            merge method used on to resolve conflicts when a metric of the same type\
-             was already recorded. When not provided value will be override current if any.
+        metric: State
+            value of metric to be recorded. When a metric implements __add__ it will be added to\
+             current value if any, otherwise subsequent calls may replace existing value.
 
         Returns
         -------
         None
         """
 
-        MetricsContext.record(
-            metric,
-            merge=merge,
-        )
+        MetricsContext.record(metric)
 
     @staticmethod
     def log_error(
@@ -393,7 +450,7 @@ class ctx:
         None
         """
 
-        MetricsContext.log_error(
+        LoggerContext.log_error(
             message,
             *args,
             exception=exception,
@@ -426,7 +483,7 @@ class ctx:
         None
         """
 
-        MetricsContext.log_warning(
+        LoggerContext.log_warning(
             message,
             *args,
             exception=exception,
@@ -455,7 +512,7 @@ class ctx:
         None
         """
 
-        MetricsContext.log_info(
+        LoggerContext.log_info(
             message,
             *args,
         )
@@ -487,7 +544,7 @@ class ctx:
         None
         """
 
-        MetricsContext.log_debug(
+        LoggerContext.log_debug(
             message,
             *args,
             exception=exception,

haiway-0.8.0/src/haiway/context/identifier.py

@@ -0,0 +1,75 @@
+from contextvars import ContextVar, Token
+from types import TracebackType
+from typing import Self, final
+from uuid import uuid4
+
+__all__ = [
+    "ScopeIdentifier",
+]
+
+
+@final
+class ScopeIdentifier:
+    _context = ContextVar[Self]("ScopeIdentifier")
+
+    @classmethod
+    def scope(
+        cls,
+        label: str,
+        /,
+    ) -> Self:
+        current: Self
+        try:  # check for current scope
+            current = cls._context.get()
+
+        except LookupError:
+            # create root scope when missing
+            trace_id: str = uuid4().hex
+            return cls(
+                label=label,
+                scope_id=uuid4().hex,
+                parent_id=trace_id,  # trace_id is parent_id for root
+                trace_id=trace_id,
+            )
+
+        # create nested scope otherwise
+        return cls(
+            label=label,
+            scope_id=uuid4().hex,
+            parent_id=current.scope_id,
+            trace_id=current.trace_id,
+        )
+
+    def __init__(
+        self,
+        trace_id: str,
+        parent_id: str,
+        scope_id: str,
+        label: str,
+    ) -> None:
+        self.trace_id: str = trace_id
+        self.parent_id: str = parent_id
+        self.scope_id: str = scope_id
+        self.label: str = label
+        self.unique_name: str = f"[{trace_id}] [{label}] [{scope_id}]"
+
+    @property
+    def is_root(self) -> bool:
+        return self.trace_id == self.parent_id
+
+    def __str__(self) -> str:
+        return self.unique_name
+
+    def __enter__(self) -> None:
+        assert not hasattr(self, "_token"), "Context reentrance is not allowed"  # nosec: B101
+        self._token: Token[ScopeIdentifier] = ScopeIdentifier._context.set(self)
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        assert hasattr(self, "_token"), "Unbalanced context enter/exit"  # nosec: B101
+        ScopeIdentifier._context.reset(self._token)
+        del self._token

haiway-0.8.0/src/haiway/context/logging.py

@@ -0,0 +1,176 @@
+from contextvars import ContextVar, Token
+from logging import DEBUG, ERROR, INFO, WARNING, Logger, getLogger
+from time import monotonic
+from types import TracebackType
+from typing import Any, Self, final
+
+from haiway.context.identifier import ScopeIdentifier
+
+__all__ = [
+    "LoggerContext",
+]
+
+
+@final
+class LoggerContext:
+    _context = ContextVar[Self]("LoggerContext")
+
+    @classmethod
+    def scope(
+        cls,
+        scope: ScopeIdentifier,
+        /,
+        *,
+        logger: Logger | None,
+    ) -> Self:
+        current: Self
+        try:  # check for current scope
+            current = cls._context.get()
+
+        except LookupError:
+            # create root scope when missing
+            return cls(
+                scope=scope,
+                logger=logger,
+            )
+
+        # create nested scope otherwise
+        return cls(
+            scope=scope,
+            logger=logger or current._logger,
+        )
+
+    @classmethod
+    def log_error(
+        cls,
+        message: str,
+        /,
+        *args: Any,
+        exception: BaseException | None = None,
+    ) -> None:
+        try:
+            cls._context.get().log(
+                ERROR,
+                message,
+                *args,
+                exception=exception,
+            )
+
+        except LookupError:
+            getLogger().log(
+                ERROR,
+                message,
+                *args,
+                exc_info=exception,
+            )
+
+    @classmethod
+    def log_warning(
+        cls,
+        message: str,
+        /,
+        *args: Any,
+        exception: Exception | None = None,
+    ) -> None:
+        try:
+            cls._context.get().log(
+                WARNING,
+                message,
+                *args,
+                exception=exception,
+            )
+
+        except LookupError:
+            getLogger().log(
+                WARNING,
+                message,
+                *args,
+                exc_info=exception,
+            )
+
+    @classmethod
+    def log_info(
+        cls,
+        message: str,
+        /,
+        *args: Any,
+    ) -> None:
+        try:
+            cls._context.get().log(
+                INFO,
+                message,
+                *args,
+            )
+
+        except LookupError:
+            getLogger().log(
+                INFO,
+                message,
+                *args,
+            )
+
+    @classmethod
+    def log_debug(
+        cls,
+        message: str,
+        /,
+        *args: Any,
+        exception: Exception | None = None,
+    ) -> None:
+        try:
+            cls._context.get().log(
+                DEBUG,
+                message,
+                *args,
+                exception=exception,
+            )
+
+        except LookupError:
+            getLogger().log(
+                DEBUG,
+                message,
+                *args,
+                exc_info=exception,
+            )
+
+    def __init__(
+        self,
+        scope: ScopeIdentifier,
+        logger: Logger | None,
+    ) -> None:
+        self._prefix: str = scope.unique_name
+        self._logger: Logger = logger or getLogger(name=scope.label)
+
+    def log(
+        self,
+        level: int,
+        message: str,
+        /,
+        *args: Any,
+        exception: BaseException | None = None,
+    ) -> None:
+        self._logger.log(
+            level,
+            f"{self._prefix} {message}",
+            *args,
+            exc_info=exception,
+        )
+
+    def __enter__(self) -> None:
+        assert not hasattr(self, "_token"), "Context reentrance is not allowed"  # nosec: B101
+        assert not hasattr(self, "_entered"), "Context reentrance is not allowed"  # nosec: B101
+        self._entered: float = monotonic()
+        self._token: Token[LoggerContext] = LoggerContext._context.set(self)
+        self.log(DEBUG, "Entering context...")
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        assert hasattr(self, "_token"), "Unbalanced context enter/exit"  # nosec: B101
+        LoggerContext._context.reset(self._token)
+        del self._token
+        self.log(DEBUG, f"...exiting context after {monotonic() - self._entered:.2f}s")
+        del self._entered