haiway 0.26.1__py3-none-any.whl → 0.27.1__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
@@ -978,6 +979,7 @@ class ctx:
         metric: str,
         value: float | int,
         unit: str | None = None,
+        kind: ObservabilityMetricKind,
         attributes: Mapping[str, ObservabilityAttribute] | None = None,
     ) -> None: ...
 
@@ -990,6 +992,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 +1006,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/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]: ...

haiway/utils/formatting.py

@@ -1,14 +1,18 @@
-from collections.abc import ItemsView, Mapping, Sequence
+from collections.abc import ItemsView, Mapping, Sequence, Set
+from datetime import datetime
 from typing import Any
+from uuid import UUID
 
 from haiway.types.missing import MISSING
 
 __all__ = ("format_str",)
 
 
-def format_str(  # noqa: PLR0911
+def format_str(  # noqa: PLR0911 PLR0912 C901
     value: Any,
     /,
+    *,
+    indent: int = 0,
 ) -> str:
     """
     Format any Python value into a readable string representation.
@@ -37,108 +41,153 @@ def format_str(  # noqa: PLR0911
     - MISSING values are converted to empty strings
     - Nested structures maintain proper indentation
     """
-    # check for string
-    if isinstance(value, str):
+    if value is None:
+        return "None"
+
+    elif isinstance(value, str):
         if "\n" in value:
-            return f'"""\n{value.replace("\n", "\n  ")}\n"""'
+            indent_str = " " * (indent + 2)
+            indented_value = value.replace("\n", f"\n{indent_str}")
+            return f'"""\n{indent_str}{indented_value}\n{" " * indent}"""'
 
         else:
             return f'"{value}"'
 
-    # check for bytes
-    elif isinstance(value, bytes):
-        return f"b'{value!r}'"
+    elif isinstance(value, int | float | complex):
+        return str(value)
+
+    elif isinstance(value, bool):
+        return str(value)
+
+    elif isinstance(value, set | frozenset | Set):
+        return _set_str(
+            value,
+            indent=indent,
+        )
 
-    # try unpack mapping
     elif isinstance(value, Mapping):
-        return _mapping_str(value)
+        return _mapping_str(
+            value,
+            indent=indent,
+        )
 
-    # try unpack sequence
     elif isinstance(value, Sequence):
-        return _sequence_str(value)
+        return _sequence_str(
+            value,
+            indent=indent,
+        )
 
     elif value is MISSING:
         return ""
 
+    elif isinstance(value, UUID):
+        return str(value)
+
+    elif isinstance(value, datetime):
+        return value.isoformat()
+
+    elif isinstance(value, bytes):
+        return repr(value)
+
     else:  # fallback to object
-        return _object_str(value)
+        return _object_str(
+            value,
+            indent=indent,
+        )
 
 
 def _attribute_str(
     *,
     key: str,
     value: str,
+    indent: int,
 ) -> str:
+    indent_str = " " * indent
     if "\n" in value:
-        formatted_value: str = value.replace("\n", "\n|  ")
-        return f"┝ {key}:\n{formatted_value}"
+        # Don't add extra indentation - value should already handle it
+        return f"{indent_str}┝ {key}:\n{value}"
 
     else:
-        return f"┝ {key}: {value}"
+        return f"{indent_str}┝ {key}: {value}"
 
 
 def _element_str(
     *,
     key: Any,
-    value: Any,
+    value: str,
+    indent: int,
 ) -> str:
+    indent_str = " " * indent
     if "\n" in value:
-        formatted_value: str = value.replace("\n", "\n  ")
-        return f"[{key}]:\n{formatted_value}"
+        # Don't add extra indentation - value should already handle it
+        return f"{indent_str}[{key}]:\n{value}"
 
     else:
-        return f"[{key}]: {value}"
+        return f"{indent_str}[{key}]: {value}"
 
 
 def _object_str(
     other: object,
     /,
+    *,
+    indent: int,
 ) -> str:
+    indent_str: str = " " * indent
     if not hasattr(other, "__dict__"):
-        return str(other)
+        return f"{indent_str}{other}"
 
     variables: ItemsView[str, Any] = vars(other).items()
-
-    parts: list[str] = [f"┍━ {type(other).__name__}:"]
+    header = f"{indent_str}┍━ {type(other).__name__}:"
+    parts: list[str] = [header]
     for key, value in variables:
         if key.startswith("_"):
             continue  # skip private and dunder
 
-        value_string: str = format_str(value)
+        value_string: str = format_str(
+            value,
+            indent=indent + 2,
+        )
 
         if value_string:
             parts.append(
                 _attribute_str(
                     key=key,
                     value=value_string,
+                    indent=indent,
                 )
             )
 
         else:
             continue  # skip empty elements
 
-    if parts:
-        return "\n".join(parts) + "\n┕━"
-
-    else:
-        return ""
+    return "\n".join(parts) + f"\n{indent_str}┕━"
 
 
 def _mapping_str(
     mapping: Mapping[Any, Any],
     /,
+    *,
+    indent: int,
 ) -> str:
     items: ItemsView[Any, Any] = mapping.items()
 
+    indent_str = " " * indent
     parts: list[str] = []
     for key, value in items:
-        value_string: str = format_str(value)
+        value_string: str = format_str(
+            value,
+            indent=indent + 2,
+        )
 
         if value_string:
             parts.append(
                 _element_str(
-                    key=key,
+                    key=format_str(
+                        key,
+                        indent=indent + 2,
+                    ),
                     value=value_string,
+                    indent=indent + 2,
                 )
             )
 
@@ -146,25 +195,64 @@ def _mapping_str(
             continue  # skip empty items
 
     if parts:
-        return "{\n" + "\n".join(parts) + "\n}"
+        open_brace = "{\n" if indent == 0 else f"{indent_str}{{\n"
+        close_brace = "\n}" if indent == 0 else f"\n{indent_str}}}"
+        return open_brace + "\n".join(parts) + close_brace
 
     else:
-        return "{}"
+        return "{}" if indent == 0 else f"{indent_str}{{}}"
+
+
+def _set_str(
+    set_value: Set[Any] | set[Any] | frozenset[Any],
+    /,
+    *,
+    indent: int,
+) -> str:
+    indent_str: str = " " * indent
+    element_indent_str: str = " " * (indent + 2)
+    parts: list[str] = []
+    for element in set_value:
+        element_string: str = format_str(
+            element,
+            indent=indent + 2,
+        )
+
+        if element_string:
+            parts.append(f"{element_indent_str}{element_string}")
+
+        else:
+            continue  # skip empty elements
+
+    if parts:
+        open_brace: str = f"{indent_str}{{\n"
+        close_brace: str = f"\n{indent_str}}}"
+        return open_brace + ",\n".join(parts) + close_brace
+
+    else:
+        return f"{indent_str}{{}}"
 
 
 def _sequence_str(
     sequence: Sequence[Any],
     /,
+    *,
+    indent: int,
 ) -> str:
+    indent_str: str = " " * indent
     parts: list[str] = []
     for idx, element in enumerate(sequence):
-        element_string: str = format_str(element)
+        element_string: str = format_str(
+            element,
+            indent=indent + 2,
+        )
 
         if element_string:
             parts.append(
                 _element_str(
                     key=idx,
                     value=element_string,
+                    indent=indent + 2,
                 )
             )
 
@@ -172,7 +260,9 @@ def _sequence_str(
             continue  # skip empty elements
 
     if parts:
-        return "[\n" + "\n".join(parts) + "\n]"
+        open_bracket: str = f"{indent_str}[\n"
+        close_bracket: str = f"\n{indent_str}]"
+        return open_bracket + "\n".join(parts) + close_bracket
 
     else:
-        return "[]"
+        return f"{indent_str}[]"

haiway/utils/metadata.py

@@ -0,0 +1,480 @@
+import json
+from collections.abc import Collection, Iterator, Mapping
+from datetime import datetime
+from types import EllipsisType
+from typing import Any, ClassVar, Final, Self, cast, final
+from uuid import UUID
+
+__all__ = (
+    "META_EMPTY",
+    "Meta",
+    "MetaTags",
+    "MetaValue",
+    "MetaValues",
+)
+
+type MetaValue = Mapping[str, MetaValue] | Collection[MetaValue] | str | float | int | bool | None
+type MetaValues = Mapping[str, MetaValue]
+type MetaTags = Collection[str]
+
+
+@final
+class Meta(Mapping[str, MetaValue]):
+    """
+    Immutable metadata container with type-safe access to common fields.
+
+    Meta provides a structured way to store and access metadata as key-value pairs
+    with built-in support for common metadata fields like identifiers, names,
+    descriptions, tags, and timestamps. All values are validated to ensure they
+    conform to the MetaValue type constraints.
+
+    The class implements the Mapping protocol, allowing dict-like access while
+    maintaining immutability. It provides builder-style methods (with_*) for
+    creating modified copies and convenience properties for accessing standard
+    metadata fields.
+
+    Examples
+    --------
+    >>> meta = Meta.of({"kind": "user", "name": "John"})
+    >>> meta = meta.with_tags(["active", "verified"])
+    >>> print(meta.kind)  # "user"
+    >>> print(meta.tags)  # ("active", "verified")
+    """
+
+    __IMMUTABLE__: ClassVar[EllipsisType] = ...
+
+    __slots__ = ("_values",)
+
+    def __init__(
+        self,
+        values: MetaValues,
+        /,
+    ):
+        assert isinstance(values, Mapping)  # nosec: B101
+        self._values: MetaValues
+        object.__setattr__(
+            self,
+            "_values",
+            values,
+        )
+
+    @classmethod
+    def of(
+        cls,
+        meta: Self | MetaValues | None,
+    ) -> Self:
+        """
+        Create a Meta instance from various input types.
+
+        This factory method provides a flexible way to create Meta instances,
+        handling None values, existing Meta instances, and raw mappings.
+
+        Parameters
+        ----------
+        meta : Self | MetaValues | None
+            The metadata to wrap. Can be None (returns META_EMPTY),
+            an existing Meta instance (returns as-is), or a mapping
+            of values to validate and wrap.
+
+        Returns
+        -------
+        Self
+            A Meta instance containing the provided metadata.
+        """
+        if meta is None:
+            return cast(Self, META_EMPTY)
+
+        elif isinstance(meta, Meta):
+            return cast(Self, meta)
+
+        else:
+            assert isinstance(meta, Mapping)  # nosec: B101
+            return cls({key: _validated_meta_value(value) for key, value in meta.items()})
+
+    @classmethod
+    def from_mapping(
+        cls,
+        mapping: Mapping[str, Any],
+        /,
+    ) -> Self:
+        return cls({key: _validated_meta_value(value) for key, value in mapping.items()})
+
+    @classmethod
+    def from_json(
+        cls,
+        value: str | bytes,
+        /,
+    ) -> Self:
+        match json.loads(value):
+            case {**values}:
+                return cls({key: _validated_meta_value(val) for key, val in values.items()})
+
+            case other:
+                raise ValueError(f"Invalid json: {other}")
+
+    def to_str(self) -> str:
+        return self.__str__()
+
+    def to_mapping(
+        self,
+    ) -> Mapping[str, Any]:
+        return self._values
+
+    def to_json(
+        self,
+    ) -> str:
+        return json.dumps(self._values)
+
+    @property
+    def kind(self) -> str | None:
+        match self._values.get("kind"):
+            case str() as kind:
+                return kind
+
+            case _:
+                return None
+
+    def with_kind(
+        self,
+        kind: str,
+        /,
+    ) -> Self:
+        return self.__class__(
+            {
+                **self._values,
+                "kind": kind,
+            }
+        )
+
+    def _get_uuid(
+        self,
+        key: str,
+        /,
+    ) -> UUID | None:
+        match self._values.get(key):
+            case str() as identifier:
+                try:
+                    return UUID(identifier)
+                except ValueError:
+                    return None
+            case _:
+                return None
+
+    def _with_uuid(
+        self,
+        key: str,
+        /,
+        *,
+        value: UUID,
+    ) -> Self:
+        return self.__class__(
+            {
+                **self._values,
+                key: str(value),
+            }
+        )
+
+    @property
+    def identifier(self) -> UUID | None:
+        return self._get_uuid("identifier")
+
+    def with_identifier(
+        self,
+        identifier: UUID,
+        /,
+    ) -> Self:
+        return self._with_uuid(
+            "identifier",
+            value=identifier,
+        )
+
+    @property
+    def origin_identifier(self) -> UUID | None:
+        return self._get_uuid("origin_identifier")
+
+    def with_origin_identifier(
+        self,
+        identifier: UUID,
+        /,
+    ) -> Self:
+        return self._with_uuid(
+            "origin_identifier",
+            value=identifier,
+        )
+
+    @property
+    def predecessor_identifier(self) -> UUID | None:
+        return self._get_uuid("predecessor_identifier")
+
+    def with_predecessor_identifier(
+        self,
+        identifier: UUID,
+        /,
+    ) -> Self:
+        return self._with_uuid(
+            "predecessor_identifier",
+            value=identifier,
+        )
+
+    @property
+    def successor_identifier(self) -> UUID | None:
+        return self._get_uuid("successor_identifier")
+
+    def with_successor_identifier(
+        self,
+        identifier: UUID,
+        /,
+    ) -> Self:
+        return self._with_uuid(
+            "successor_identifier",
+            value=identifier,
+        )
+
+    @property
+    def name(self) -> str | None:
+        match self._values.get("name"):
+            case str() as name:
+                return name
+
+            case _:
+                return None
+
+    def with_name(
+        self,
+        name: str,
+        /,
+    ) -> Self:
+        return self.__class__(
+            {
+                **self._values,
+                "name": name,
+            }
+        )
+
+    @property
+    def description(self) -> str | None:
+        match self._values.get("description"):
+            case str() as description:
+                return description
+
+            case _:
+                return None
+
+    def with_description(
+        self,
+        description: str,
+        /,
+    ) -> Self:
+        return self.__class__(
+            {
+                **self._values,
+                "description": description,
+            }
+        )
+
+    @property
+    def tags(self) -> MetaTags:
+        match self._values.get("tags"):
+            case [*tags]:
+                return tuple(tag for tag in tags if isinstance(tag, str))
+
+            case _:
+                return ()
+
+    def with_tags(
+        self,
+        tags: MetaTags,
+        /,
+    ) -> Self:
+        match self._values.get("tags"):
+            case [*current_tags]:
+                return self.__class__(
+                    {
+                        **self._values,
+                        "tags": (
+                            *current_tags,
+                            *(
+                                _validated_meta_value(tag)
+                                for tag in tags
+                                if tag not in current_tags
+                            ),
+                        ),
+                    }
+                )
+
+            case _:
+                return self.__class__({**self._values, "tags": tags})
+
+    def has_tags(
+        self,
+        tags: MetaTags,
+        /,
+    ) -> bool:
+        match self._values.get("tags"):
+            case [*meta_tags]:
+                return all(tag in meta_tags for tag in tags)
+
+            case _:
+                return False
+
+    @property
+    def creation(self) -> datetime | None:
+        match self._values.get("creation"):
+            case str() as iso_value:
+                try:
+                    return datetime.fromisoformat(iso_value)
+
+                except ValueError:
+                    return None
+
+            case _:
+                return None
+
+    def with_creation(
+        self,
+        creation: datetime,
+        /,
+    ) -> Self:
+        return self.__class__(
+            {
+                **self._values,
+                "creation": creation.isoformat(),
+            }
+        )
+
+    def merged_with(
+        self,
+        values: Self | MetaValues | None,
+        /,
+    ) -> Self:
+        if not values:
+            return self  # do not make a copy when nothing will be updated
+
+        return self.__class__(
+            {
+                **self._values,  # already validated
+                **{key: _validated_meta_value(value) for key, value in values.items()},
+            }
+        )
+
+    def excluding(
+        self,
+        *excluded: str,
+    ) -> Self:
+        if not excluded:
+            return self
+
+        excluded_set: set[str] = set(excluded)
+        return self.__class__(
+            {key: value for key, value in self._values.items() if key not in excluded_set}
+        )
+
+    def updated(
+        self,
+        **values: MetaValue,
+    ) -> Self:
+        return self.__replace__(**values)
+
+    def __replace__(
+        self,
+        **values: Any,
+    ) -> Self:
+        return self.merged_with(values)
+
+    def __bool__(self) -> bool:
+        return bool(self._values)
+
+    def __contains__(
+        self,
+        element: Any,
+    ) -> bool:
+        return element in self._values
+
+    def __setattr__(
+        self,
+        name: str,
+        value: Any,
+    ) -> Any:
+        raise AttributeError(
+            f"Can't modify immutable {self.__class__.__qualname__},"
+            f" attribute - '{name}' cannot be modified"
+        )
+
+    def __delattr__(
+        self,
+        name: str,
+    ) -> None:
+        raise AttributeError(
+            f"Can't modify immutable {self.__class__.__qualname__},"
+            f" attribute - '{name}' cannot be deleted"
+        )
+
+    def __setitem__(
+        self,
+        key: str,
+        value: Any,
+    ) -> MetaValue:
+        raise AttributeError(
+            f"Can't modify immutable {self.__class__.__qualname__},"
+            f" item - '{key}' cannot be modified"
+        )
+
+    def __delitem__(
+        self,
+        key: str,
+    ) -> MetaValue:
+        raise AttributeError(
+            f"Can't modify immutable {self.__class__.__qualname__},"
+            f" item - '{key}' cannot be deleted"
+        )
+
+    def __getitem__(
+        self,
+        key: str,
+    ) -> MetaValue:
+        return self._values[key]
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._values)
+
+    def __len__(self) -> int:
+        return len(self._values)
+
+    def __copy__(self) -> Self:
+        return self  # Metadata is immutable, no need to provide an actual copy
+
+    def __deepcopy__(
+        self,
+        memo: dict[int, Any] | None,
+    ) -> Self:
+        return self  # Metadata is immutable, no need to provide an actual copy
+
+
+def _validated_meta_value(value: Any) -> MetaValue:  # noqa: PLR0911
+    match value:
+        case None:
+            return value
+
+        case str():
+            return value
+
+        case int():
+            return value
+
+        case float():
+            return value
+
+        case bool():
+            return value
+
+        case [*values]:
+            return tuple(_validated_meta_value(value) for value in values)
+
+        case {**values}:
+            return {key: _validated_meta_value(value) for key, value in values.items()}
+
+        case other:
+            raise TypeError(f"Invalid Meta value: {type(other)}")
+
+
+META_EMPTY: Final[Meta] = Meta({})

{haiway-0.26.1.dist-info → haiway-0.27.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: haiway
-Version: 0.26.1
+Version: 0.27.1
 Summary: Framework for dependency injection and state management within structured concurrency model.
 Project-URL: Homepage, https://miquido.com
 Project-URL: Repository, https://github.com/miquido/haiway.git

{haiway-0.26.1.dist-info → haiway-0.27.1.dist-info}/RECORD

@@ -1,10 +1,10 @@
-haiway/__init__.py,sha256=tJpU6TzK-o-Pt8joGrJah5eC08STVoRzvhXeLn3oTKo,2095
+haiway/__init__.py,sha256=qzLQvEsgGKFNHp9A34sTg_MrBSvPUq4UtmQS172TfaI,2247
 haiway/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-haiway/context/__init__.py,sha256=DKcf1AHGEqLWF8Kki30YKQ07GjonUjpAA8I51P4AxAg,1296
-haiway/context/access.py,sha256=g8WdrKNvg6sO3X7Km_9X9syafxS0Shm_EP-JKqRLyxI,31367
+haiway/context/__init__.py,sha256=fjWNPXgBsW_nBsT8aR0SuiRehxDylRHHXA-nU2Rvy_Y,1356
+haiway/context/access.py,sha256=93IvbUoBCMy-oBAVHoRuZDzU_N7zm_LoDj5br6-cIG0,31566
 haiway/context/disposables.py,sha256=7Jo-5qzS3UQvZUf4yOqUgfnueMg8I65jwHDp-4g6w54,7998
 haiway/context/identifier.py,sha256=ps7YM1ZnUrj66SPVyxqMhTRMaYOMNSb82J3FfMRVHm4,4690
-haiway/context/observability.py,sha256=rZoZT7g4ZM5_OKIFV0uA0rJodHxondw8X2bMSf_W6_s,20244
+haiway/context/observability.py,sha256=-Q-uzGdtYV1TYaSbhZLMQSTJEMRKBMKTiIv6RoyZXTM,20601
 haiway/context/presets.py,sha256=NVRv-PzuzonxdzIEJmt8SRMRO0lUgKb-jR-2ixUtkzI,10760
 haiway/context/state.py,sha256=1oeON23_vaX7IgyckPcA5jWMXije93TNuSh0l9dQqNE,9920
 haiway/context/tasks.py,sha256=0LdoxkQW0op4-QhAA-IDQO0PQr6Q3Vp4mO5ssEFbclU,4930
@@ -14,12 +14,12 @@ haiway/helpers/asynchrony.py,sha256=Ddj8UdXhVczAbAC-rLpyhWa4RJ_W2Eolo45Veorq7_4,
 haiway/helpers/caching.py,sha256=BqgcUGQSAmXsuLi5V8EwlZzuGyutHOn1V4k7BHsGKeg,14347
 haiway/helpers/concurrent.py,sha256=kTcm_wLAKqVQOKgTHIKwbkMX5hJ5GIXOAc5RRIUvbo4,13063
 haiway/helpers/files.py,sha256=MzGR-GF8FpBzSihDeen7wdxmX2R-JjAT1MB9aMW-8-g,11626
-haiway/helpers/observability.py,sha256=R4md41g7iTslzvtRaY5W9pgXqmuzJuGByjFb6vsO4W4,10994
+haiway/helpers/observability.py,sha256=ylDilsseZwTsPBmLO6GSUrbiTV593fwNqi3nL8wk814,11043
 haiway/helpers/retries.py,sha256=OH__I9e-PUFxcSwuQLIzJ9F1MwXgbz1Ur4jEjJiOmjQ,8974
 haiway/helpers/throttling.py,sha256=KBWUSHdKVMC5_nRMmmoPNwfp-3AcerQ6OczJa9gNLM0,5796
 haiway/helpers/timeouting.py,sha256=GQ8-btb36f0Jq7TnorAPYXyKScNmf0nxHXCYxqGl-o8,3949
 haiway/opentelemetry/__init__.py,sha256=TV-1C14mDAtcHhFZ29ActFQdrGH6x5KuGV9w-JlKYJg,91
-haiway/opentelemetry/observability.py,sha256=uFgSuvwOgW7IbffROY6Kc4ZRJGoQV6rEWqIQltU_Iho,27365
+haiway/opentelemetry/observability.py,sha256=7VugyXLxGA75VUTSS9fBoVx4SvqZebFpGkOVV70q4-s,29142
 haiway/state/__init__.py,sha256=mtYgg2TojOBNjFsfoRjYkfZPDhKV5sPJXxDGFBvB8-0,417
 haiway/state/attributes.py,sha256=sububiFP23aBB8RGk6OvTUp7BEY6S0kER_uHC09yins,26733
 haiway/state/immutable.py,sha256=YStOo1RQs8JoyLuumOmFXp9IrwOMzIHExVvDmcqj4lE,3693
@@ -30,17 +30,18 @@ haiway/state/validation.py,sha256=8IKm9-rJDmP0xJhqRCPc1mm7J1nnjbZDdInmCHZxaeg,24
 haiway/types/__init__.py,sha256=BQKjbPZQej4DQsD_y4linn4rQMWdfaahKW-t-gapSjs,285
 haiway/types/default.py,sha256=59chcOaoGqI2to08RamCCLluimfYbJp5xbYl3fWaLrM,4153
 haiway/types/missing.py,sha256=V9FWUgAWUsmFuSXc57MORQOVh2wO2vlF1qYopmcEA2A,5760
-haiway/utils/__init__.py,sha256=FkY6EUwkZmb2Z8Z5UpMW3i9J0l9JoowgrULy-s_6X5M,943
+haiway/utils/__init__.py,sha256=ZmRloJ3IUqotOjN1_ejS3NYb4A30LKR78YTaY5b3nao,1133
 haiway/utils/always.py,sha256=dd6jDQ1j4DpJjTKO1J2Tv5xS8X1LnMC4kQ0D7DtKUvw,1230
-haiway/utils/collections.py,sha256=W2K5haxogHdngEw2JF_qEUr0O28dhirdy2kzSbeW4wE,4745
+haiway/utils/collections.py,sha256=LExyiwpJX7nc0FKhrK12Yim90IcHzHBWRXvnjLjJrz8,4653
 haiway/utils/env.py,sha256=mCMveOWwOphgp8Ir5NEpZQFENyG7MBOoLlUeHzzIYEQ,11262
-haiway/utils/formatting.py,sha256=SQ-gjBa2nxg_UhIP0AhNXIRwcDRei2ZZUiCLMiYLYUo,4041
+haiway/utils/formatting.py,sha256=cqZHlRc9E4ybNq0Uo826JPJ7WuOWOOY995mCe_2URQw,6499
 haiway/utils/logs.py,sha256=-MVyxVGU892yJKFh0bkshW_NEg1aiJt9wv2cUY2w98o,1847
+haiway/utils/metadata.py,sha256=I_e9D5rhHLm7fpHyZFjChm1FnNxPPkeTulD8uhDn_a4,11754
 haiway/utils/mimic.py,sha256=xaZiUKp096QFfdSw7cNIKEWt2UIS7vf880KF54gny38,1831
 haiway/utils/noop.py,sha256=U8ocfoCgt-pY0owJDPtrRrj53cabeIXH9qCKWMQnoRk,1336
 haiway/utils/queue.py,sha256=6v2u3pA6A44IuCCTOjmCt3yLyOcm7PCRnrIGo25j-1o,6402
 haiway/utils/stream.py,sha256=lXaeveTY0-AYG5xVzcQYaiC6SUD5fUtHoMXiQcrQAAM,5723
-haiway-0.26.1.dist-info/METADATA,sha256=IEiaciUkopUmCqO7MxJZdfjUrELAI_tDRGBvFL8jUCg,4919
-haiway-0.26.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-haiway-0.26.1.dist-info/licenses/LICENSE,sha256=3phcpHVNBP8jsi77gOO0E7rgKeDeu99Pi7DSnK9YHoQ,1069
-haiway-0.26.1.dist-info/RECORD,,
+haiway-0.27.1.dist-info/METADATA,sha256=W4rwS9P4_1f50cENKaEeXRtP1SIJFlYL408ndVGZIzo,4919
+haiway-0.27.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+haiway-0.27.1.dist-info/licenses/LICENSE,sha256=3phcpHVNBP8jsi77gOO0E7rgKeDeu99Pi7DSnK9YHoQ,1069
+haiway-0.27.1.dist-info/RECORD,,