haiway 0.26.0__py3-none-any.whl → 0.27.0__py3-none-any.whl

haiway/__init__.py

@@ -37,8 +37,13 @@ from haiway.types import (
     unwrap_missing,
 )
 from haiway.utils import (
+    META_EMPTY,
     AsyncQueue,
     AsyncStream,
+    Meta,
+    MetaTags,
+    MetaValue,
+    MetaValues,
     always,
     as_dict,
     as_list,
@@ -59,6 +64,7 @@ from haiway.utils import (
 )
 
 __all__ = (
+    "META_EMPTY",
     "MISSING",
     "AsyncQueue",
     "AsyncStream",
@@ -73,6 +79,10 @@ __all__ = (
     "FileAccess",
     "Immutable",
     "LoggerObservability",
+    "Meta",
+    "MetaTags",
+    "MetaValue",
+    "MetaValues",
     "Missing",
     "MissingContext",
     "MissingState",

haiway/context/__init__.py

@@ -9,6 +9,7 @@ from haiway.context.observability import (
     ObservabilityEventRecording,
     ObservabilityLevel,
     ObservabilityLogRecording,
+    ObservabilityMetricKind,
     ObservabilityMetricRecording,
     ObservabilityScopeEntering,
     ObservabilityScopeExiting,
@@ -33,6 +34,7 @@ __all__ = (
     "ObservabilityEventRecording",
     "ObservabilityLevel",
     "ObservabilityLogRecording",
+    "ObservabilityMetricKind",
     "ObservabilityMetricRecording",
     "ObservabilityScopeEntering",
     "ObservabilityScopeExiting",

haiway/context/access.py

@@ -25,6 +25,7 @@ from haiway.context.observability import (
     ObservabilityAttribute,
     ObservabilityContext,
     ObservabilityLevel,
+    ObservabilityMetricKind,
 )
 
 # Import after other imports to avoid circular dependencies
@@ -990,6 +991,7 @@ class ctx:
         metric: str | None = None,
         value: float | int | None = None,
         unit: str | None = None,
+        kind: ObservabilityMetricKind | None = None,
         attributes: Mapping[str, ObservabilityAttribute] | None = None,
     ) -> None:
         if event is not None:
@@ -1003,11 +1005,13 @@ class ctx:
         elif metric is not None:
             assert event is None  # nosec: B101
             assert value is not None  # nosec: B101
+            assert kind is not None  # nosec: B101
             ObservabilityContext.record_metric(
                 level,
                 metric,
                 value=value,
                 unit=unit,
+                kind=kind,
                 attributes=attributes or {},
             )
 

haiway/context/observability.py

@@ -7,7 +7,7 @@ from logging import INFO as INFO_LOGGING
 from logging import WARNING as WARNING_LOGGING
 from logging import Logger, getLogger
 from types import TracebackType
-from typing import Any, ClassVar, Protocol, Self, runtime_checkable
+from typing import Any, ClassVar, Literal, Protocol, Self, runtime_checkable
 from uuid import UUID, uuid4
 
 from haiway.context.identifier import ScopeIdentifier
@@ -23,6 +23,7 @@ __all__ = (
     "ObservabilityEventRecording",
     "ObservabilityLevel",
     "ObservabilityLogRecording",
+    "ObservabilityMetricKind",
     "ObservabilityMetricRecording",
     "ObservabilityScopeEntering",
     "ObservabilityScopeExiting",
@@ -118,6 +119,9 @@ class ObservabilityEventRecording(Protocol):
     ) -> None: ...
 
 
+type ObservabilityMetricKind = Literal["counter", "histogram", "gauge"]
+
+
 @runtime_checkable
 class ObservabilityMetricRecording(Protocol):
     """
@@ -136,6 +140,7 @@ class ObservabilityMetricRecording(Protocol):
         metric: str,
         value: float | int,
         unit: str | None,
+        kind: ObservabilityMetricKind,
         attributes: Mapping[str, ObservabilityAttribute],
     ) -> None: ...
 
@@ -278,6 +283,7 @@ def _logger_observability(
         metric: str,
         value: float | int,
         unit: str | None,
+        kind: ObservabilityMetricKind,
         attributes: Mapping[str, ObservabilityAttribute],
     ) -> None:
         if attributes:
@@ -553,6 +559,7 @@ class ObservabilityContext(Immutable):
         *,
         value: float | int,
         unit: str | None,
+        kind: ObservabilityMetricKind,
         attributes: Mapping[str, ObservabilityAttribute],
     ) -> None:
         """
@@ -571,6 +578,8 @@ class ObservabilityContext(Immutable):
             The numeric value of the metric
         unit: str | None
             Optional unit for the metric (e.g., "ms", "bytes")
+        kind: ObservabilityMetricKind
+            The metric kind defining its value handling.
         attributes: Mapping[str, ObservabilityAttribute]
             Key-value attributes associated with the metric
         """
@@ -584,6 +593,7 @@ class ObservabilityContext(Immutable):
                     metric=metric,
                     value=value,
                     unit=unit,
+                    kind=kind,
                     attributes=attributes,
                 )
 

haiway/helpers/concurrent.py

@@ -3,8 +3,8 @@ from collections.abc import (
     AsyncIterable,
     AsyncIterator,
     Callable,
-    Collection,
     Coroutine,
+    Iterable,
     MutableSequence,
     Sequence,
 )
@@ -20,7 +20,7 @@ __all__ = (
 
 
 async def process_concurrently[Element](  # noqa: C901, PLR0912
-    source: AsyncIterator[Element],
+    source: AsyncIterable[Element],
     /,
     handler: Callable[[Element], Coroutine[Any, Any, None]],
     *,
@@ -80,8 +80,7 @@ async def process_concurrently[Element](  # noqa: C901, PLR0912
     assert concurrent_tasks > 0  # nosec: B101
     running: set[Task[None]] = set()
     try:
-        while True:
-            element: Element = await anext(source)
+        async for element in source:
             running.add(ctx.spawn(handler, element))
             if len(running) < concurrent_tasks:
                 continue  # keep spawning tasks
@@ -132,7 +131,7 @@ async def process_concurrently[Element](  # noqa: C901, PLR0912
 async def execute_concurrently[Element, Result](
     handler: Callable[[Element], Coroutine[Any, Any, Result]],
     /,
-    elements: Collection[Element],
+    elements: Iterable[Element],
     *,
     concurrent_tasks: int = 2,
 ) -> Sequence[Result]: ...
@@ -142,7 +141,7 @@ async def execute_concurrently[Element, Result](
 async def execute_concurrently[Element, Result](
     handler: Callable[[Element], Coroutine[Any, Any, Result]],
     /,
-    elements: Collection[Element],
+    elements: Iterable[Element],
     *,
     concurrent_tasks: int = 2,
     return_exceptions: Literal[True],
@@ -152,7 +151,7 @@ async def execute_concurrently[Element, Result](
 async def execute_concurrently[Element, Result](  # noqa: C901
     handler: Callable[[Element], Coroutine[Any, Any, Result]],
     /,
-    elements: Collection[Element],
+    elements: Iterable[Element],
     *,
     concurrent_tasks: int = 2,
     return_exceptions: bool = False,
@@ -175,8 +174,8 @@ async def execute_concurrently[Element, Result](  # noqa: C901
     ----------
     handler : Callable[[Element], Coroutine[Any, Any, Result]]
         A coroutine function that processes each element and returns a result.
-    elements : Collection[Element]
-        A collection of elements to process. The collection size determines
+    elements : Iterable[Element]
+        A source of elements to process. The source size determines
         the result sequence length.
     concurrent_tasks : int, default=2
         Maximum number of concurrent tasks. Must be greater than 0. Higher

haiway/helpers/files.py

@@ -188,7 +188,7 @@ class FileAccessing(Protocol):
     locking, and resource management.
     """
 
-    async def __call__(
+    def __call__(
         self,
         path: Path | str,
         create: bool,
@@ -275,7 +275,7 @@ def _close_file_handle(
     os.close(file_handle)
 
 
-async def _file_access_context(
+def _file_access_context(
     path: Path | str,
     create: bool,
     exclusive: bool,
@@ -375,7 +375,7 @@ class FileAccess(State):
     """
 
     @classmethod
-    async def open(
+    def open(
         cls,
         path: Path | str,
         create: bool = False,
@@ -412,7 +412,7 @@ class FileAccess(State):
             If the file cannot be opened with the specified parameters, or if
             a file is already open in the current context scope
         """
-        return await ctx.state(cls).accessing(
+        return ctx.state(cls).accessing(
             path,
             create=create,
             exclusive=exclusive,

haiway/helpers/observability.py

@@ -4,8 +4,13 @@ from time import monotonic
 from typing import Any
 from uuid import UUID, uuid4
 
-from haiway.context import Observability, ObservabilityLevel, ScopeIdentifier
-from haiway.context.observability import ObservabilityAttribute
+from haiway.context import (
+    Observability,
+    ObservabilityAttribute,
+    ObservabilityLevel,
+    ObservabilityMetricKind,
+    ScopeIdentifier,
+)
 from haiway.utils.formatting import format_str
 
 __all__ = ("LoggerObservability",)
@@ -189,6 +194,7 @@ def LoggerObservability(  # noqa: C901, PLR0915
         metric: str,
         value: float | int,
         unit: str | None,
+        kind: ObservabilityMetricKind,
         attributes: Mapping[str, ObservabilityAttribute],
     ) -> None:
         assert root_scope is not None  # nosec: B101

haiway/opentelemetry/observability.py

@@ -12,7 +12,7 @@ from opentelemetry.exporter.otlp.proto.grpc._log_exporter import OTLPLogExporter
 from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import OTLPMetricExporter
 from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
 from opentelemetry.metrics._internal import Meter
-from opentelemetry.metrics._internal.instrument import Counter
+from opentelemetry.metrics._internal.instrument import Counter, Gauge, Histogram
 from opentelemetry.sdk._logs import LoggerProvider
 from opentelemetry.sdk._logs._internal import LogRecord
 from opentelemetry.sdk._logs._internal.export import (
@@ -33,6 +33,7 @@ from haiway.context import (
     Observability,
     ObservabilityAttribute,
     ObservabilityLevel,
+    ObservabilityMetricKind,
     ScopeIdentifier,
     ctx,
 )
@@ -54,6 +55,8 @@ class ScopeStore:
         "_completed",
         "_counters",
         "_exited",
+        "_gauges",
+        "_histograms",
         "_token",
         "context",
         "identifier",
@@ -91,6 +94,8 @@ class ScopeStore:
         self.identifier: ScopeIdentifier = identifier
         self.nested: list[ScopeStore] = []
         self._counters: dict[str, Counter] = {}
+        self._histograms: dict[str, Histogram] = {}
+        self._gauges: dict[str, Gauge] = {}
         self._exited: bool = False
         self._completed: bool = False
         self.span: Span = span
@@ -251,6 +256,7 @@ class ScopeStore:
         *,
         value: float | int,
         unit: str | None,
+        kind: ObservabilityMetricKind,
         attributes: Mapping[str, ObservabilityAttribute],
     ) -> None:
         """
@@ -267,23 +273,59 @@ class ScopeStore:
             The value to add to the metric
         unit : str | None
             The unit of the metric (if any)
+        kind: ObservabilityMetricKind
+            The metric kind defining its value handling.
         attributes : Mapping[str, ObservabilityAttribute]
             Attributes to attach to the metric
         """
-        if name not in self._counters:
-            self._counters[name] = self.meter.create_counter(
-                name=name,
-                unit=unit or "",
-            )
+        match kind:
+            case "counter":
+                if name not in self._counters:
+                    self._counters[name] = self.meter.create_counter(
+                        name=name,
+                        unit=unit or "",
+                    )
+
+                self._counters[name].add(
+                    value,
+                    attributes={
+                        key: cast(Any, value)
+                        for key, value in attributes.items()
+                        if value is not None and value is not MISSING
+                    },
+                )
 
-        self._counters[name].add(
-            value,
-            attributes={
-                key: cast(Any, value)
-                for key, value in attributes.items()
-                if value is not None and value is not MISSING
-            },
-        )
+            case "histogram":
+                if name not in self._histograms:
+                    self._histograms[name] = self.meter.create_histogram(
+                        name=name,
+                        unit=unit or "",
+                    )
+
+                self._histograms[name].record(
+                    value,
+                    attributes={
+                        key: cast(Any, value)
+                        for key, value in attributes.items()
+                        if value is not None and value is not MISSING
+                    },
+                )
+
+            case "gauge":
+                if name not in self._gauges:
+                    self._gauges[name] = self.meter.create_gauge(
+                        name=name,
+                        unit=unit or "",
+                    )
+
+                self._gauges[name].set(
+                    value,
+                    attributes={
+                        key: cast(Any, value)
+                        for key, value in attributes.items()
+                        if value is not None and value is not MISSING
+                    },
+                )
 
     def record_attributes(
         self,
@@ -589,6 +631,7 @@ class OpenTelemetry:
             metric: str,
             value: float | int,
             unit: str | None,
+            kind: ObservabilityMetricKind,
             attributes: Mapping[str, ObservabilityAttribute],
         ) -> None:
             """
@@ -609,6 +652,8 @@ class OpenTelemetry:
                 The numeric value of the metric
             unit: str | None
                 Optional unit for the metric (e.g., "ms", "bytes")
+            kind: ObservabilityMetricKind
+                The metric kind defining its value handling.
             attributes: Mapping[str, ObservabilityAttribute]
                 Key-value attributes associated with the metric
             """
@@ -622,6 +667,7 @@ class OpenTelemetry:
                 metric,
                 value=value,
                 unit=unit,
+                kind=kind,
                 attributes=attributes,
             )
 

haiway/utils/__init__.py

@@ -11,14 +11,26 @@ from haiway.utils.env import (
 )
 from haiway.utils.formatting import format_str
 from haiway.utils.logs import setup_logging
+from haiway.utils.metadata import (
+    META_EMPTY,
+    Meta,
+    MetaTags,
+    MetaValue,
+    MetaValues,
+)
 from haiway.utils.mimic import mimic_function
 from haiway.utils.noop import async_noop, noop
 from haiway.utils.queue import AsyncQueue
 from haiway.utils.stream import AsyncStream
 
 __all__ = (
+    "META_EMPTY",
     "AsyncQueue",
     "AsyncStream",
+    "Meta",
+    "MetaTags",
+    "MetaValue",
+    "MetaValues",
     "always",
     "as_dict",
     "as_list",

haiway/utils/collections.py

@@ -14,20 +14,20 @@ __all__ = (
 
 @overload
 def as_list[T](
-    collection: Iterable[T],
+    iterable: Iterable[T],
     /,
 ) -> list[T]: ...
 
 
 @overload
 def as_list[T](
-    collection: Iterable[T] | None,
+    iterable: Iterable[T] | None,
     /,
 ) -> list[T] | None: ...
 
 
 def as_list[T](
-    collection: Iterable[T] | None,
+    iterable: Iterable[T] | None,
     /,
 ) -> list[T] | None:
     """
@@ -35,44 +35,44 @@ def as_list[T](
 
     Parameters
     ----------
-    collection : Iterable[T] | None
-        The input collection to be converted to a list.
+    iterable : Iterable[T] | None
+        The input iterable to be converted to a list.
         If None is provided, None is returned.
 
     Returns
     -------
     list[T] | None
-        A new list containing all elements of the input collection,
+        A new list containing all elements of the input iterable,
         or the original list if it was already one.
         Returns None if None was provided.
     """
 
-    if collection is None:
+    if iterable is None:
         return None
 
-    elif isinstance(collection, list):
-        return collection
+    elif isinstance(iterable, list):
+        return iterable
 
     else:
-        return list(collection)
+        return list(iterable)
 
 
 @overload
 def as_tuple[T](
-    collection: Iterable[T],
+    iterable: Iterable[T],
     /,
 ) -> tuple[T, ...]: ...
 
 
 @overload
 def as_tuple[T](
-    collection: Iterable[T] | None,
+    iterable: Iterable[T] | None,
     /,
 ) -> tuple[T, ...] | None: ...
 
 
 def as_tuple[T](
-    collection: Iterable[T] | None,
+    iterable: Iterable[T] | None,
     /,
 ) -> tuple[T, ...] | None:
     """
@@ -80,26 +80,26 @@ def as_tuple[T](
 
     Parameters
     ----------
-    collection : Iterable[T] | None
-        The input collection to be converted to a tuple.
+    iterable : Iterable[T] | None
+        The input iterable to be converted to a tuple.
         If None is provided, None is returned.
 
     Returns
     -------
     tuple[T, ...] | None
-        A new tuple containing all elements of the input collection,
+        A new tuple containing all elements of the input iterable,
         or the original tuple if it was already one.
         Returns None if None was provided.
     """
 
-    if collection is None:
+    if iterable is None:
         return None
 
-    elif isinstance(collection, tuple):
-        return collection
+    elif isinstance(iterable, tuple):
+        return iterable
 
     else:
-        return tuple(collection)
+        return tuple(iterable)
 
 
 @overload
@@ -149,20 +149,20 @@ def as_set[T](
 
 @overload
 def as_dict[K, V](
-    collection: Mapping[K, V],
+    mapping: Mapping[K, V],
     /,
 ) -> dict[K, V]: ...
 
 
 @overload
 def as_dict[K, V](
-    collection: Mapping[K, V] | None,
+    mapping: Mapping[K, V] | None,
     /,
 ) -> dict[K, V] | None: ...
 
 
 def as_dict[K, V](
-    collection: Mapping[K, V] | None,
+    mapping: Mapping[K, V] | None,
     /,
 ) -> dict[K, V] | None:
     """
@@ -170,30 +170,30 @@ def as_dict[K, V](
 
     Parameters
     ----------
-    collection : Mapping[K, V] | None
-        The input collection to be converted to a dict.
+    mapping : Mapping[K, V] | None
+        The input mapping to be converted to a dict.
         If None is provided, None is returned.
 
     Returns
     -------
     dict[K, V] | None
-        A new dict containing all elements of the input collection,
+        A new dict containing all elements of the input mapping,
         or the original dict if it was already one.
         Returns None if None was provided.
     """
 
-    if collection is None:
+    if mapping is None:
         return None
 
-    elif isinstance(collection, dict):
-        return collection
+    elif isinstance(mapping, dict):
+        return mapping
 
     else:
-        return dict(collection)
+        return dict(mapping)
 
 
 @overload
-def without_missing[T: Mapping[str, Any]](
+def without_missing(
     mapping: Mapping[str, Any],
     /,
 ) -> Mapping[str, Any]: ...