lionherd-core 1.0.0a3__py3-none-any.whl

lionherd_core/protocols.py

@@ -0,0 +1,181 @@
+# Copyright (c) 2025, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Any, Protocol, runtime_checkable
+from uuid import UUID
+
+__all__ = (
+    "Adaptable",
+    "Allowable",
+    "AsyncAdaptable",
+    "Containable",
+    "Deserializable",
+    "Hashable",
+    "Invocable",
+    "Observable",
+    "Serializable",
+    "implements",
+)
+
+
+@runtime_checkable
+class ObservableProto(Protocol):
+    """Objects with unique UUID identifier. Check via isinstance()."""
+
+    @property
+    def id(self) -> UUID:
+        """Unique identifier."""
+        ...
+
+
+@runtime_checkable
+class Serializable(Protocol):
+    """Objects that can be serialized to dict via to_dict()."""
+
+    def to_dict(self, **kwargs: Any) -> dict[str, Any]:
+        """Serialize to dict. Args: serialization options (mode, format, etc.)."""
+        ...
+
+
+@runtime_checkable
+class Deserializable(Protocol):
+    """Objects that can be deserialized from dict via from_dict() classmethod."""
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any], **kwargs: Any) -> Any:
+        """Deserialize from dict. Args: data dict, deserialization options."""
+        ...
+
+
+@runtime_checkable
+class Adaptable(Protocol):
+    """Sync adapter protocol for format conversion (TOML/YAML/JSON/SQL). Use AsyncAdaptable for async."""
+
+    def adapt_to(self, obj_key: str, many: bool = False, **kwargs: Any) -> Any:
+        """Convert to external format. Args: adapter key, many flag, adapter kwargs."""
+        ...
+
+    @classmethod
+    def adapt_from(cls, obj: Any, obj_key: str, many: bool = False, **kwargs: Any) -> Any:
+        """Create from external format. Args: source object, adapter key, many flag."""
+        ...
+
+    @classmethod
+    def register_adapter(cls, adapter: Any) -> None:
+        """Register adapter for this class."""
+        ...
+
+
+@runtime_checkable
+class AsyncAdaptable(Protocol):
+    """Async adapter protocol for I/O-bound format conversion (DBs, network, files). Use Adaptable for sync."""
+
+    async def adapt_to_async(self, obj_key: str, many: bool = False, **kwargs: Any) -> Any:
+        """Async convert to external format. Args: adapter key, many flag, adapter kwargs."""
+        ...
+
+    @classmethod
+    async def adapt_from_async(
+        cls, obj: Any, obj_key: str, many: bool = False, **kwargs: Any
+    ) -> Any:
+        """Async create from external format. Args: source object, adapter key, many flag."""
+        ...
+
+    @classmethod
+    def register_async_adapter(cls, adapter: Any) -> None:
+        """Register async adapter for this class."""
+        ...
+
+
+@runtime_checkable
+class Containable(Protocol):
+    """Objects that support membership testing via 'in' operator (__contains__)."""
+
+    def __contains__(self, item: Any) -> bool:
+        """Check if item is in collection (by UUID or instance)."""
+        ...
+
+
+@runtime_checkable
+class Invocable(Protocol):
+    """Objects that can be invoked/executed via async invoke() method."""
+
+    async def invoke(self) -> Any:
+        """Invoke/execute the object. Returns: execution result (any value or None)."""
+        ...
+
+
+@runtime_checkable
+class Hashable(Protocol):
+    """Objects that can be hashed via __hash__() for use in sets/dicts."""
+
+    def __hash__(self) -> int:
+        """Return hash value for object (must be immutable or ID-based)."""
+        ...
+
+
+@runtime_checkable
+class Allowable(Protocol):
+    """Objects with defined set of allowed values/keys via allowed()."""
+
+    def allowed(self) -> set[str]:
+        """Return set of allowed keys/values."""
+        ...
+
+
+Observable = ObservableProto
+
+
+def implements(*protocols: type):
+    """Declare protocol implementations (Rust-like: MUST define in class body).
+
+    CRITICAL SEMANTICS (strictest interpretation):
+        @implements() means the class **LITERALLY** implements/overrides the method
+        or declares the attribute IN ITS OWN CLASS BODY. Inheritance does NOT count.
+
+        This is Rust-like trait implementation: you must provide the implementation
+        in the impl block, not rely on inheritance.
+
+    Rules:
+        - Method must be defined in class body (even if it calls super())
+        - Property must be declared in class body (cannot inherit from parent)
+        - Classmethod must be defined in class body
+        - NO inheritance: @implements means "I define this, not my parent"
+
+    Args:
+        *protocols: Protocol classes that the decorated class **literally** implements
+
+    Returns:
+        Class decorator that stores protocols on cls.__protocols__
+
+    Usage:
+        ✓ CORRECT: Literal implementation
+        @implements(Serializable, Deserializable)
+        class MyClass:
+            def to_dict(self, **kwargs): ...      # Defined in this class
+            @classmethod
+            def from_dict(cls, data, **kwargs): ...  # Defined in this class
+
+        ✗ WRONG: Relying on inheritance
+        @implements(Serializable)  # VIOLATION!
+        class Child(Parent):  # Parent has to_dict()
+            pass  # No to_dict in Child body → not allowed!
+
+        ✓ CORRECT: Explicit override
+        @implements(Serializable)
+        class Child(Parent):
+            def to_dict(self, **kwargs):  # Explicit in Child body
+                return super().to_dict(**kwargs)  # Can call parent
+
+    Rationale:
+        - Explicit > Implicit (Rust philosophy)
+        - Clear ownership: each class declares what it implements
+        - No ambiguity about where implementation lives
+        - Prevents accidental protocol claims through inheritance
+    """
+
+    def decorator(cls):
+        cls.__protocols__ = protocols
+        return cls
+
+    return decorator

lionherd_core/types/__init__.py

@@ -0,0 +1,46 @@
+# Copyright (c) 2025, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from ._sentinel import (
+    MaybeSentinel,
+    MaybeUndefined,
+    MaybeUnset,
+    SingletonType,
+    T,
+    Undefined,
+    UndefinedType,
+    Unset,
+    UnsetType,
+    is_sentinel,
+    not_sentinel,
+)
+from .base import DataClass, Enum, KeysDict, KeysLike, Meta, ModelConfig, Params
+from .operable import Operable
+from .spec import CommonMeta, Spec
+
+__all__ = (
+    "CommonMeta",
+    "DataClass",
+    "Enum",
+    "KeysDict",
+    "KeysLike",
+    "MaybeSentinel",
+    "MaybeUndefined",
+    "MaybeUnset",
+    "Meta",
+    # Base classes
+    "ModelConfig",
+    "Operable",
+    "Params",
+    "SingletonType",
+    # Spec system
+    "Spec",
+    "T",
+    # Sentinel types
+    "Undefined",
+    "UndefinedType",
+    "Unset",
+    "UnsetType",
+    "is_sentinel",
+    "not_sentinel",
+)

lionherd_core/types/_sentinel.py

@@ -0,0 +1,131 @@
+# Copyright (c) 2025, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from typing import Any, ClassVar, Final, Literal, Self, TypeAlias, TypeGuard, TypeVar
+
+__all__ = (
+    "MaybeSentinel",
+    "MaybeUndefined",
+    "MaybeUnset",
+    "SingletonType",
+    "T",
+    "Undefined",
+    "UndefinedType",
+    "Unset",
+    "UnsetType",
+    "is_sentinel",
+    "not_sentinel",
+)
+
+T = TypeVar("T")
+
+
+class _SingletonMeta(type):
+    """Metaclass: ensures one instance per subclass for safe 'is' checks."""
+
+    _cache: ClassVar[dict[type, SingletonType]] = {}
+
+    def __call__(cls, *a, **kw):
+        if cls not in cls._cache:
+            cls._cache[cls] = super().__call__(*a, **kw)
+        return cls._cache[cls]
+
+
+class SingletonType(metaclass=_SingletonMeta):
+    """Base for singleton sentinels. Falsy, identity-preserving across copy/deepcopy."""
+
+    __slots__: tuple[str, ...] = ()
+
+    def __deepcopy__(self, memo: dict[int, Any]) -> Self:
+        """Preserve singleton identity across deepcopy."""
+        return self
+
+    def __copy__(self) -> Self:
+        """Preserve singleton identity across copy."""
+        return self
+
+    # concrete classes *must* override the two methods below
+    def __bool__(self) -> bool:
+        raise NotImplementedError
+
+    def __repr__(self) -> str:
+        raise NotImplementedError
+
+
+class UndefinedType(SingletonType):
+    """Sentinel: field/key entirely missing from namespace. Use for missing keys, never-set fields."""
+
+    __slots__ = ()
+
+    def __bool__(self) -> Literal[False]:
+        return False
+
+    def __repr__(self) -> Literal["Undefined"]:
+        return "Undefined"
+
+    def __str__(self) -> Literal["Undefined"]:
+        return "Undefined"
+
+    def __reduce__(self) -> tuple[type[UndefinedType], tuple[()]]:
+        """Preserve singleton identity across pickle/unpickle."""
+        return (UndefinedType, ())
+
+
+class UnsetType(SingletonType):
+    """Sentinel: key present but value not provided. Use to distinguish None from 'not provided'."""
+
+    __slots__ = ()
+
+    def __bool__(self) -> Literal[False]:
+        return False
+
+    def __repr__(self) -> Literal["Unset"]:
+        return "Unset"
+
+    def __str__(self) -> Literal["Unset"]:
+        return "Unset"
+
+    def __reduce__(self) -> tuple[type[UnsetType], tuple[()]]:
+        """Preserve singleton identity across pickle/unpickle."""
+        return (UnsetType, ())
+
+
+Undefined: Final[UndefinedType] = UndefinedType()
+"""A key or field entirely missing from a namespace"""
+Unset: Final[UnsetType] = UnsetType()
+"""A key present but value not yet provided."""
+
+MaybeUndefined: TypeAlias = T | UndefinedType
+MaybeUnset: TypeAlias = T | UnsetType
+MaybeSentinel: TypeAlias = T | UndefinedType | UnsetType
+
+_EMPTY_TUPLE: tuple[Any, ...] = (tuple(), set(), frozenset(), dict(), list(), "")
+
+
+def is_sentinel(
+    value: Any,
+    *,
+    none_as_sentinel: bool = False,
+    empty_as_sentinel: bool = False,
+) -> bool:
+    """Check if a value is any sentinel (Undefined or Unset)."""
+    if none_as_sentinel and value is None:
+        return True
+    if empty_as_sentinel and value in _EMPTY_TUPLE:
+        return True
+    return value is Undefined or value is Unset
+
+
+def not_sentinel(
+    value: T | UndefinedType | UnsetType,
+    none_as_sentinel: bool = False,
+    empty_as_sentinel: bool = False,
+) -> TypeGuard[T]:
+    """Type-narrowing check: NOT a sentinel. Narrows MaybeSentinel[T] to T for type checkers."""
+    return not is_sentinel(
+        value,
+        none_as_sentinel=none_as_sentinel,
+        empty_as_sentinel=empty_as_sentinel,
+    )

lionherd_core/types/base.py

@@ -0,0 +1,341 @@
+# Copyright (c) 2025, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from collections.abc import MutableMapping, MutableSequence, MutableSet, Sequence
+from dataclasses import dataclass
+from enum import (
+    Enum as _Enum,
+    StrEnum,
+)
+from typing import Any, ClassVar, Literal, Self, TypedDict
+
+from typing_extensions import override
+
+from ..protocols import Allowable, Hashable, Serializable, implements
+from ._sentinel import Undefined, Unset, is_sentinel
+
+__all__ = (
+    "DataClass",
+    "Enum",
+    "KeysDict",
+    "KeysLike",
+    "Meta",
+    "ModelConfig",
+    "Params",
+)
+
+
+@implements(Allowable)
+class Enum(StrEnum):
+    """String-backed enum (Python 3.11+). Members are strings, support JSON serialization."""
+
+    @classmethod
+    def allowed(cls) -> tuple[str, ...]:
+        """Return tuple of all allowed string values."""
+        return tuple(e.value for e in cls)
+
+
+class KeysDict(TypedDict, total=False):
+    """TypedDict for keys dictionary."""
+
+    key: Any  # Represents any key-type pair
+
+
+@dataclass(slots=True, frozen=True)
+class ModelConfig:
+    """Config for Params/DataClass: sentinel handling, validation, serialization."""
+
+    # Sentinel handling (controls what gets excluded from to_dict)
+    none_as_sentinel: bool = False
+    empty_as_sentinel: bool = False
+
+    # Validation
+    strict: bool = False
+    prefill_unset: bool = True
+
+    # Serialization
+    use_enum_values: bool = False
+
+
+@implements(Serializable, Allowable, Hashable)
+@dataclass(slots=True, frozen=True, init=False)
+class Params:
+    """Base for function parameters with sentinel handling. Configure via _config."""
+
+    _config: ClassVar[ModelConfig] = ModelConfig()
+    _allowed_keys: ClassVar[set[str]] = set()
+
+    def __init__(self, **kwargs: Any):
+        """Init from kwargs. Validates and sets attributes."""
+        # Set all attributes from kwargs, allowing for sentinel values
+        for k, v in kwargs.items():
+            if k in self.allowed():
+                object.__setattr__(self, k, v)
+            else:
+                raise ValueError(f"Invalid parameter: {k}")
+
+        # Validate after setting all attributes
+        self._validate()
+
+    @classmethod
+    def _is_sentinel(cls, value: Any) -> bool:
+        """Check if value is sentinel (respects config)."""
+        return is_sentinel(
+            value,
+            none_as_sentinel=cls._config.none_as_sentinel,
+            empty_as_sentinel=cls._config.empty_as_sentinel,
+        )
+
+    @classmethod
+    def _normalize_value(cls, value: Any) -> Any:
+        """Normalize value for serialization (enum handling, etc.)."""
+        if cls._config.use_enum_values and isinstance(value, _Enum):
+            return value.value
+        return value
+
+    @classmethod
+    def allowed(cls) -> set[str]:
+        """Return the keys of the parameters."""
+        if cls._allowed_keys:
+            return cls._allowed_keys
+        cls._allowed_keys = {i for i in cls.__dataclass_fields__ if not i.startswith("_")}
+        return cls._allowed_keys
+
+    def _validate(self) -> None:
+        """Validate params. Collects errors in ExceptionGroup. Prefills unset if configured."""
+        missing: list[Exception] = []
+        for k in self.allowed():
+            if self._config.strict and self._is_sentinel(getattr(self, k, Unset)):
+                missing.append(ValueError(f"Missing required parameter: {k}"))
+            if self._config.prefill_unset and getattr(self, k, Undefined) is Undefined:
+                object.__setattr__(self, k, Unset)
+        if missing:
+            raise ExceptionGroup("Missing required parameters", missing)
+
+    def default_kw(self) -> Any:
+        # create a partial function with the current parameters
+        dict_ = self.to_dict()
+
+        # handle kwargs if present, handle both 'kwargs' and 'kw'
+        kw_ = {}
+        kw_.update(dict_.pop("kwargs", {}))
+        kw_.update(dict_.pop("kw", {}))
+        dict_.update(kw_)
+        return dict_
+
+    def to_dict(self, exclude: set[str] | None = None) -> dict[str, Any]:
+        data = {}
+        exclude = exclude or set()
+        for k in self.allowed():
+            if k not in exclude:
+                v = getattr(self, k, Undefined)
+                if not self._is_sentinel(v):
+                    data[k] = self._normalize_value(v)
+        return data
+
+    def __hash__(self) -> int:
+        from ..ln._hash import hash_dict
+
+        return hash_dict(self.to_dict())
+
+    def __eq__(self, other: object) -> bool:
+        """Equality via hash comparison. Returns NotImplemented for non-Params types."""
+        if not isinstance(other, Params):
+            return NotImplemented
+        return hash(self) == hash(other)
+
+    def with_updates(
+        self, copy_containers: Literal["shallow", "deep"] | None = None, **kwargs: Any
+    ) -> Self:
+        """Return new instance with updated fields.
+
+        Args:
+            copy_containers: None (no copy), "shallow" (top-level), or "deep" (recursive).
+            **kwargs: Field updates.
+        """
+        dict_ = self.to_dict()
+
+        def _out(d: dict):
+            d.update(kwargs)
+            return type(self)(**d)
+
+        if copy_containers is None:
+            return _out(dict_)
+
+        match copy_containers:
+            case "shallow":
+                for k, v in dict_.items():
+                    if k not in kwargs and isinstance(
+                        v, (MutableSequence, MutableMapping, MutableSet)
+                    ):
+                        dict_[k] = v.copy()
+                return _out(dict_)
+
+            case "deep":
+                import copy
+
+                for k, v in dict_.items():
+                    if k not in kwargs and isinstance(
+                        v, (MutableSequence, MutableMapping, MutableSet)
+                    ):
+                        dict_[k] = copy.deepcopy(v)
+                return _out(dict_)
+
+        raise ValueError(
+            f"Invalid copy_containers: {copy_containers!r}. Must be 'shallow', 'deep', or None."
+        )
+
+
+@implements(Serializable, Allowable, Hashable)
+@dataclass(slots=True)
+class DataClass:
+    """Base for dataclasses with strict parameter handling. Configure via _config."""
+
+    _config: ClassVar[ModelConfig] = ModelConfig()
+    _allowed_keys: ClassVar[set[str]] = set()
+
+    def __post_init__(self):
+        """Post-init: validates all fields."""
+        self._validate()
+
+    @classmethod
+    def allowed(cls) -> set[str]:
+        """Return the keys of the parameters."""
+        if cls._allowed_keys:
+            return cls._allowed_keys
+        cls._allowed_keys = {i for i in cls.__dataclass_fields__ if not i.startswith("_")}
+        return cls._allowed_keys
+
+    def _validate(self) -> None:
+        """Validate params. Collects errors in ExceptionGroup. Prefills unset if configured."""
+        missing: list[Exception] = []
+        for k in self.allowed():
+            if self._config.strict and self._is_sentinel(getattr(self, k, Unset)):
+                missing.append(ValueError(f"Missing required parameter: {k}"))
+            if self._config.prefill_unset and getattr(self, k, Undefined) is Undefined:
+                self.__setattr__(k, Unset)
+        if missing:
+            raise ExceptionGroup("Missing required parameters", missing)
+
+    def to_dict(self, exclude: set[str] | None = None) -> dict[str, Any]:
+        data = {}
+        exclude = exclude or set()
+        for k in type(self).allowed():
+            if k not in exclude:
+                v = getattr(self, k)
+                if not self._is_sentinel(v):
+                    data[k] = self._normalize_value(v)
+        return data
+
+    @classmethod
+    def _is_sentinel(cls, value: Any) -> bool:
+        """Check if value is sentinel (respects config)."""
+        return is_sentinel(
+            value,
+            none_as_sentinel=cls._config.none_as_sentinel,
+            empty_as_sentinel=cls._config.empty_as_sentinel,
+        )
+
+    @classmethod
+    def _normalize_value(cls, value: Any) -> Any:
+        """Normalize value for serialization (enum handling, etc.)."""
+        from enum import Enum as _Enum
+
+        if cls._config.use_enum_values and isinstance(value, _Enum):
+            return value.value
+        return value
+
+    def with_updates(
+        self, copy_containers: Literal["shallow", "deep"] | None = None, **kwargs: Any
+    ) -> Self:
+        """Return new instance with updated fields.
+
+        Args:
+            copy_containers: None (no copy), "shallow" (top-level), or "deep" (recursive).
+            **kwargs: Field updates.
+        """
+        dict_ = self.to_dict()
+
+        def _out(d: dict):
+            d.update(kwargs)
+            return type(self)(**d)
+
+        if copy_containers is None:
+            return _out(dict_)
+
+        match copy_containers:
+            case "shallow":
+                for k, v in dict_.items():
+                    if k not in kwargs and isinstance(
+                        v, (MutableSequence, MutableMapping, MutableSet)
+                    ):
+                        dict_[k] = v.copy()
+                return _out(dict_)
+
+            case "deep":
+                import copy
+
+                for k, v in dict_.items():
+                    if k not in kwargs and isinstance(
+                        v, (MutableSequence, MutableMapping, MutableSet)
+                    ):
+                        dict_[k] = copy.deepcopy(v)
+                return _out(dict_)
+
+        raise ValueError(
+            f"Invalid copy_containers: {copy_containers!r}. Must be 'shallow', 'deep', or None."
+        )
+
+    def __hash__(self) -> int:
+        from ..ln._hash import hash_dict
+
+        return hash_dict(self.to_dict())
+
+    def __eq__(self, other: object) -> bool:
+        """Equality via hash comparison. Returns NotImplemented for non-DataClass types."""
+        if not isinstance(other, DataClass):
+            return NotImplemented
+        return hash(self) == hash(other)
+
+
+KeysLike = Sequence[str] | KeysDict
+
+
+@implements(Hashable)
+@dataclass(slots=True, frozen=True)
+class Meta:
+    """Immutable metadata container. Hashable for caching (callables hashed by id)."""
+
+    key: str
+    value: Any
+
+    @override
+    def __hash__(self) -> int:
+        """Hash metadata. Callables use id() for identity semantics."""
+        # For callables, use their id
+        if callable(self.value):
+            return hash((self.key, id(self.value)))
+        # For other values, try to hash directly
+        try:
+            return hash((self.key, self.value))
+        except TypeError:
+            # Fallback for unhashable types
+            return hash((self.key, str(self.value)))
+
+    @override
+    def __eq__(self, other: object) -> bool:
+        """Equality: callables compared by id, others by standard equality."""
+        if not isinstance(other, Meta):
+            return NotImplemented
+
+        if self.key != other.key:
+            return False
+
+        # For callables, compare by identity
+        if callable(self.value) and callable(other.value):
+            return id(self.value) == id(other.value)
+
+        # For other values, use standard equality
+        return bool(self.value == other.value)