haiway 0.1.0__py3-none-any.whl

haiway/state/attributes.py

@@ -0,0 +1,360 @@
+import sys
+import types
+import typing
+from collections.abc import Mapping
+from types import NoneType, UnionType
+from typing import (
+    Any,
+    ClassVar,
+    ForwardRef,
+    Generic,
+    Literal,
+    TypeAliasType,
+    TypeVar,
+    get_args,
+    get_origin,
+    get_type_hints,
+)
+
+__all__ = [
+    "attribute_annotations",
+    "AttributeAnnotation",
+]
+
+
+class AttributeAnnotation:
+    def __init__(
+        self,
+        *,
+        origin: Any,
+        arguments: list[Any],
+    ) -> None:
+        self.origin: Any = origin
+        self.arguments: list[Any] = arguments
+
+    def __eq__(
+        self,
+        other: Any,
+    ) -> bool:
+        return self is other or (
+            isinstance(other, self.__class__)
+            and self.origin == other.origin
+            and self.arguments == other.arguments
+        )
+
+
+def attribute_annotations(
+    cls: type[Any],
+    /,
+    type_parameters: dict[str, Any] | None = None,
+) -> dict[str, AttributeAnnotation]:
+    type_parameters = type_parameters or {}
+
+    self_annotation = AttributeAnnotation(
+        origin=cls,
+        arguments=[],  # ignore self arguments here, Structure will have them resolved at this stage
+    )
+    localns: dict[str, Any] = {cls.__name__: cls}
+    recursion_guard: dict[Any, AttributeAnnotation] = {cls: self_annotation}
+    attributes: dict[str, AttributeAnnotation] = {}
+
+    for key, annotation in get_type_hints(cls, localns=localns).items():
+        # do not include ClassVars, private or dunder items
+        if ((get_origin(annotation) or annotation) is ClassVar) or key.startswith("_"):
+            continue
+
+        attributes[key] = _resolve_attribute_annotation(
+            annotation,
+            self_annotation=self_annotation,
+            type_parameters=type_parameters,
+            module=cls.__module__,
+            localns=localns,
+            recursion_guard=recursion_guard,
+        )
+
+    return attributes
+
+
+def _resolve_attribute_annotation(  # noqa: C901, PLR0911, PLR0912, PLR0913
+    annotation: Any,
+    /,
+    self_annotation: AttributeAnnotation | None,
+    type_parameters: dict[str, Any],
+    module: str,
+    localns: dict[str, Any],
+    recursion_guard: Mapping[Any, AttributeAnnotation],  # TODO: verify recursion!
+) -> AttributeAnnotation:
+    # resolve annotation directly if able
+    match annotation:
+        # None
+        case types.NoneType | types.NoneType():
+            return AttributeAnnotation(
+                origin=NoneType,
+                arguments=[],
+            )
+
+        # forward reference through string
+        case str() as forward_ref:
+            return _resolve_attribute_annotation(
+                ForwardRef(forward_ref, module=module)._evaluate(
+                    globalns=None,
+                    localns=localns,
+                    recursive_guard=frozenset(),
+                ),
+                self_annotation=self_annotation,
+                type_parameters=type_parameters,
+                module=module,
+                localns=localns,
+                recursion_guard=recursion_guard,  # we might need to update it somehow?
+            )
+
+        # forward reference directly
+        case typing.ForwardRef() as reference:
+            return _resolve_attribute_annotation(
+                reference._evaluate(
+                    globalns=None,
+                    localns=localns,
+                    recursive_guard=frozenset(),
+                ),
+                self_annotation=self_annotation,
+                type_parameters=type_parameters,
+                module=module,
+                localns=localns,
+                recursion_guard=recursion_guard,  # we might need to update it somehow?
+            )
+
+        # generic alias aka parametrized type
+        case types.GenericAlias() as generic_alias:
+            match get_origin(generic_alias):
+                # check for an alias with parameters
+                case typing.TypeAliasType() as alias:  # pyright: ignore[reportUnnecessaryComparison]
+                    type_alias: AttributeAnnotation = AttributeAnnotation(
+                        origin=TypeAliasType,
+                        arguments=[],
+                    )
+                    resolved: AttributeAnnotation = _resolve_attribute_annotation(
+                        alias.__value__,
+                        self_annotation=None,
+                        type_parameters=type_parameters,
+                        module=module,
+                        localns=localns,
+                        recursion_guard=recursion_guard,
+                    )
+                    type_alias.origin = resolved.origin
+                    type_alias.arguments = resolved.arguments
+                    return type_alias
+
+                # check if we can resolve it as generic
+                case parametrized if issubclass(parametrized, Generic):
+                    parametrized_type: Any = parametrized.__class_getitem__(  # pyright: ignore[reportUnknownMemberType, reportAttributeAccessIssue]
+                        *(
+                            type_parameters.get(
+                                arg.__name__,
+                                arg.__bound__ or Any,
+                            )
+                            if isinstance(arg, TypeVar)
+                            else arg
+                            for arg in get_args(generic_alias)
+                        )
+                    )
+
+                    match parametrized_type:
+                        # verify if we got any specific type or generic alias again
+                        case types.GenericAlias():
+                            return AttributeAnnotation(
+                                origin=parametrized,
+                                arguments=[
+                                    _resolve_attribute_annotation(
+                                        argument,
+                                        self_annotation=self_annotation,
+                                        type_parameters=type_parameters,
+                                        module=module,
+                                        localns=localns,
+                                        recursion_guard=recursion_guard,
+                                    )
+                                    for argument in get_args(generic_alias)
+                                ],
+                            )
+
+                        # use resolved type if it is not an alias again
+                        case _:
+                            return AttributeAnnotation(
+                                origin=parametrized_type,
+                                arguments=[],
+                            )
+
+                # anything else - try to resolve a concrete type or use as is
+                case origin:
+                    return AttributeAnnotation(
+                        origin=origin,
+                        arguments=[
+                            _resolve_attribute_annotation(
+                                argument,
+                                self_annotation=self_annotation,
+                                type_parameters=type_parameters,
+                                module=module,
+                                localns=localns,
+                                recursion_guard=recursion_guard,
+                            )
+                            for argument in get_args(generic_alias)
+                        ],
+                    )
+
+        # type alias
+        case typing.TypeAliasType() as alias:
+            type_alias: AttributeAnnotation = AttributeAnnotation(
+                origin=TypeAliasType,
+                arguments=[],
+            )
+            resolved: AttributeAnnotation = _resolve_attribute_annotation(
+                alias.__value__,
+                self_annotation=None,
+                type_parameters=type_parameters,
+                module=module,
+                localns=localns,
+                recursion_guard=recursion_guard,
+            )
+            type_alias.origin = resolved.origin
+            type_alias.arguments = resolved.arguments
+            return type_alias
+
+        # type parameter
+        case typing.TypeVar():
+            return _resolve_attribute_annotation(
+                # try to resolve it from current parameters if able
+                type_parameters.get(
+                    annotation.__name__,
+                    # use bound as default or Any otherwise
+                    annotation.__bound__ or Any,
+                ),
+                self_annotation=None,
+                type_parameters=type_parameters,
+                module=module,
+                localns=localns,
+                recursion_guard=recursion_guard,
+            )
+
+        case typing.ParamSpec():
+            sys.stderr.write(
+                "ParamSpec is not supported for attribute annotations,"
+                " ignoring with Any type - it might incorrectly validate types\n"
+            )
+            return AttributeAnnotation(
+                origin=Any,
+                arguments=[],
+            )
+
+        case typing.TypeVarTuple():
+            sys.stderr.write(
+                "TypeVarTuple is not supported for attribute annotations,"
+                " ignoring with Any type - it might incorrectly validate types\n"
+            )
+            return AttributeAnnotation(
+                origin=Any,
+                arguments=[],
+            )
+
+        case _:
+            pass  # proceed to resolving based on origin
+
+    # resolve based on origin if any
+    match get_origin(annotation) or annotation:
+        case types.UnionType | typing.Union:
+            return AttributeAnnotation(
+                origin=UnionType,  # pyright: ignore[reportArgumentType]
+                arguments=[
+                    recursion_guard.get(
+                        argument,
+                        _resolve_attribute_annotation(
+                            argument,
+                            self_annotation=self_annotation,
+                            type_parameters=type_parameters,
+                            module=module,
+                            localns=localns,
+                            recursion_guard=recursion_guard,
+                        ),
+                    )
+                    for argument in get_args(annotation)
+                ],
+            )
+
+        case typing.Callable:  # pyright: ignore[reportUnknownMemberType, reportAttributeAccessIssue]
+            return AttributeAnnotation(
+                origin=typing.Callable,
+                arguments=[
+                    _resolve_attribute_annotation(
+                        argument,
+                        self_annotation=self_annotation,
+                        type_parameters=type_parameters,
+                        module=module,
+                        localns=localns,
+                        recursion_guard=recursion_guard,
+                    )
+                    for argument in get_args(annotation)
+                ],
+            )
+
+        case typing.Self:  # pyright: ignore[reportUnknownMemberType]
+            if not self_annotation:
+                sys.stderr.write(
+                    "Unresolved Self attribute annotation,"
+                    " ignoring with Any type - it might incorrectly validate types\n"
+                )
+                return AttributeAnnotation(
+                    origin=Any,
+                    arguments=[],
+                )
+
+            return self_annotation
+
+        # unwrap from irrelevant type wrappers
+        case typing.Annotated | typing.Final | typing.Required | typing.NotRequired:
+            return _resolve_attribute_annotation(
+                get_args(annotation)[0],
+                self_annotation=self_annotation,
+                type_parameters=type_parameters,
+                module=module,
+                localns=localns,
+                recursion_guard=recursion_guard,
+            )
+
+        case typing.Optional:  # optional is a Union[Value, None]
+            return AttributeAnnotation(
+                origin=UnionType,  # pyright: ignore[reportArgumentType]
+                arguments=[
+                    _resolve_attribute_annotation(
+                        get_args(annotation)[0],
+                        self_annotation=self_annotation,
+                        type_parameters=type_parameters,
+                        module=module,
+                        localns=localns,
+                        recursion_guard=recursion_guard,
+                    ),
+                    AttributeAnnotation(
+                        origin=NoneType,
+                        arguments=[],
+                    ),
+                ],
+            )
+
+        case typing.Literal:
+            return AttributeAnnotation(
+                origin=Literal,
+                arguments=list(get_args(annotation)),
+            )
+
+        case other:  # finally use whatever there was
+            return AttributeAnnotation(
+                origin=other,
+                arguments=[
+                    _resolve_attribute_annotation(
+                        argument,
+                        self_annotation=self_annotation,
+                        type_parameters=type_parameters,
+                        module=module,
+                        localns=localns,
+                        recursion_guard=recursion_guard,
+                    )
+                    for argument in get_args(other)
+                ],
+            )

haiway/state/structure.py

@@ -0,0 +1,254 @@
+from collections.abc import Callable
+from copy import deepcopy
+from types import GenericAlias
+from typing import (
+    Any,
+    ClassVar,
+    Generic,
+    Self,
+    TypeVar,
+    cast,
+    dataclass_transform,
+    final,
+    get_origin,
+)
+from weakref import WeakValueDictionary
+
+from haiway.state.attributes import AttributeAnnotation, attribute_annotations
+from haiway.state.validation import attribute_type_validator
+from haiway.types.missing import MISSING, Missing
+
+__all__ = [
+    "Structure",
+]
+
+
+@final
+class StructureAttribute[Value]:
+    def __init__(
+        self,
+        annotation: AttributeAnnotation,
+        default: Value | Missing,
+        validator: Callable[[Any], Value],
+    ) -> None:
+        self.annotation: AttributeAnnotation = annotation
+        self.default: Value | Missing = default
+        self.validator: Callable[[Any], Value] = validator
+
+    def validated(
+        self,
+        value: Any | Missing,
+        /,
+    ) -> Value:
+        return self.validator(self.default if value is MISSING else value)
+
+
+@dataclass_transform(
+    kw_only_default=True,
+    frozen_default=True,
+    field_specifiers=(),
+)
+class StructureMeta(type):
+    def __new__(
+        cls,
+        /,
+        name: str,
+        bases: tuple[type, ...],
+        namespace: dict[str, Any],
+        type_parameters: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        structure_type = type.__new__(
+            cls,
+            name,
+            bases,
+            namespace,
+            **kwargs,
+        )
+
+        attributes: dict[str, StructureAttribute[Any]] = {}
+
+        if bases:  # handle base class
+            for key, annotation in attribute_annotations(
+                structure_type,
+                type_parameters=type_parameters,
+            ).items():
+                # do not include ClassVars and dunder items
+                if ((get_origin(annotation) or annotation) is ClassVar) or key.startswith("__"):
+                    continue
+
+                attributes[key] = StructureAttribute(
+                    annotation=annotation,
+                    default=getattr(structure_type, key, MISSING),
+                    validator=attribute_type_validator(annotation),
+                )
+
+        structure_type.__ATTRIBUTES__ = attributes  # pyright: ignore[reportAttributeAccessIssue]
+        structure_type.__slots__ = frozenset(attributes.keys())  # pyright: ignore[reportAttributeAccessIssue]
+        structure_type.__match_args__ = structure_type.__slots__  # pyright: ignore[reportAttributeAccessIssue]
+
+        return structure_type
+
+
+_types_cache: WeakValueDictionary[
+    tuple[
+        Any,
+        tuple[Any, ...],
+    ],
+    Any,
+] = WeakValueDictionary()
+
+
+class Structure(metaclass=StructureMeta):
+    """
+    Base class for immutable data structures.
+    """
+
+    __ATTRIBUTES__: ClassVar[dict[str, StructureAttribute[Any]]]
+
+    def __class_getitem__(
+        cls,
+        type_argument: tuple[type[Any], ...] | type[Any],
+    ) -> type[Self]:
+        assert Generic in cls.__bases__, "Can't specialize non generic type!"  # nosec: B101
+
+        type_arguments: tuple[type[Any], ...]
+        match type_argument:
+            case [*arguments]:
+                type_arguments = tuple(arguments)
+
+            case argument:
+                type_arguments = (argument,)
+
+        if any(isinstance(argument, TypeVar) for argument in type_arguments):  # pyright: ignore[reportUnnecessaryIsInstance]
+            # if we got unfinished type treat it as an alias instead of resolving
+            return cast(type[Self], GenericAlias(cls, type_arguments))
+
+        assert len(type_arguments) == len(  # nosec: B101
+            cls.__type_params__
+        ), "Type arguments count has to match type parameters count"
+
+        if cached := _types_cache.get((cls, type_arguments)):
+            return cached
+
+        type_parameters: dict[str, Any] = {
+            parameter.__name__: argument
+            for (parameter, argument) in zip(
+                cls.__type_params__ or (),
+                type_arguments or (),
+                strict=False,
+            )
+        }
+
+        parameter_names: str = ",".join(
+            getattr(
+                argument,
+                "__name__",
+                str(argument),
+            )
+            for argument in type_arguments
+        )
+        name: str = f"{cls.__name__}[{parameter_names}]"
+        bases: tuple[type[Self]] = (cls,)
+
+        parametrized_type: type[Self] = StructureMeta.__new__(
+            cls.__class__,
+            name=name,
+            bases=bases,
+            namespace={"__module__": cls.__module__},
+            type_parameters=type_parameters,
+        )
+        _types_cache[(cls, type_arguments)] = parametrized_type
+        return parametrized_type
+
+    def __init__(
+        self,
+        **kwargs: Any,
+    ) -> None:
+        for name, attribute in self.__ATTRIBUTES__.items():
+            object.__setattr__(
+                self,  # pyright: ignore[reportUnknownArgumentType]
+                name,
+                attribute.validated(
+                    kwargs.get(
+                        name,
+                        MISSING,
+                    ),
+                ),
+            )
+
+    def updated(
+        self,
+        **kwargs: Any,
+    ) -> Self:
+        return self.__replace__(**kwargs)
+
+    def as_dict(self) -> dict[str, Any]:
+        return vars(self)
+
+    def __str__(self) -> str:
+        attributes: str = ", ".join([f"{key}: {value}" for key, value in vars(self).items()])
+        return f"{self.__class__.__name__}({attributes})"
+
+    def __repr__(self) -> str:
+        return str(self)
+
+    def __eq__(
+        self,
+        other: Any,
+    ) -> bool:
+        if not issubclass(other.__class__, self.__class__):
+            return False
+
+        return all(
+            getattr(self, key, MISSING) == getattr(other, key, MISSING)
+            for key in self.__ATTRIBUTES__.keys()
+        )
+
+    def __setattr__(
+        self,
+        name: str,
+        value: Any,
+    ) -> Any:
+        raise AttributeError(
+            f"Can't modify immutable structure {self.__class__.__qualname__},"
+            f" attribute - '{name}' cannot be modified"
+        )
+
+    def __delattr__(
+        self,
+        name: str,
+    ) -> None:
+        raise AttributeError(
+            f"Can't modify immutable structure {self.__class__.__qualname__},"
+            f" attribute - '{name}' cannot be deleted"
+        )
+
+    def __copy__(self) -> Self:
+        return self.__class__(**vars(self))
+
+    def __deepcopy__(
+        self,
+        memo: dict[int, Any] | None,
+    ) -> Self:
+        copy: Self = self.__class__(
+            **{
+                key: deepcopy(
+                    value,
+                    memo,
+                )
+                for key, value in vars(self).items()
+            }
+        )
+        return copy
+
+    def __replace__(
+        self,
+        **kwargs: Any,
+    ) -> Self:
+        return self.__class__(
+            **{
+                **vars(self),
+                **kwargs,
+            }
+        )