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

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.0.dist-info → haiway-0.27.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: haiway
-Version: 0.26.0
+Version: 0.27.0
 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.0.dist-info → haiway-0.27.0.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=Itpweo9sRFuf_Gu601v6_lWXmAJa4qYsmz2dQ7m7pYA,31527
 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
@@ -12,14 +12,14 @@ haiway/context/types.py,sha256=LoW8238TTdbUgmxyHDi0LVc8M8ZwTHLWKkAPttTsTeg,746
 haiway/helpers/__init__.py,sha256=gyKM1mWyuQwSx_2ajpI0UF1nA8l5D7wrzZOt9XUkWJA,780
 haiway/helpers/asynchrony.py,sha256=Ddj8UdXhVczAbAC-rLpyhWa4RJ_W2Eolo45Veorq7_4,5362
 haiway/helpers/caching.py,sha256=BqgcUGQSAmXsuLi5V8EwlZzuGyutHOn1V4k7BHsGKeg,14347
-haiway/helpers/concurrent.py,sha256=fU6je62XvbySylZKDgzC_AGKPC7Kimmd5SmkVpySBUo,13115
-haiway/helpers/files.py,sha256=L6vXd8gdgWx5jPL8azloU8IGoFq2xnxjMc4ufz-gdl4,11650
-haiway/helpers/observability.py,sha256=R4md41g7iTslzvtRaY5W9pgXqmuzJuGByjFb6vsO4W4,10994
+haiway/helpers/concurrent.py,sha256=kTcm_wLAKqVQOKgTHIKwbkMX5hJ5GIXOAc5RRIUvbo4,13063
+haiway/helpers/files.py,sha256=MzGR-GF8FpBzSihDeen7wdxmX2R-JjAT1MB9aMW-8-g,11626
+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.0.dist-info/METADATA,sha256=IWQSIN2nqYPQETpjzyJYJ6dv2L--xrP-RG9J9qoQXoc,4919
-haiway-0.26.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-haiway-0.26.0.dist-info/licenses/LICENSE,sha256=3phcpHVNBP8jsi77gOO0E7rgKeDeu99Pi7DSnK9YHoQ,1069
-haiway-0.26.0.dist-info/RECORD,,
+haiway-0.27.0.dist-info/METADATA,sha256=0dw_DzT7Ui0OY25vJ8Xem5Wo52jDepyfYIg45BnuroI,4919
+haiway-0.27.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+haiway-0.27.0.dist-info/licenses/LICENSE,sha256=3phcpHVNBP8jsi77gOO0E7rgKeDeu99Pi7DSnK9YHoQ,1069
+haiway-0.27.0.dist-info/RECORD,,