gpdatacached 0.1.0__py3-none-any.whl

gpdatacached/builtins/registry.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+import datetime
+
+from ..types import GPDCTypeRegistry
+from .bool_object import BoolCodec, BoolObject
+from .datetime_object import (
+    DateCodec,
+    DateObject,
+    DateTimeCodec,
+    DateTimeObject,
+    TimeCodec,
+    TimeObject,
+)
+from .dict_object import DictCodec, DictObject
+from .float_object import FloatCodec, FloatObject
+from .int_object import IntCodec, IntObject
+from .list_object import ListCodec, ListObject
+from .none_object import NoneCodec, NoneObject
+from .set_object import SetCodec, SetObject
+from .str_object import StrCodec, StrObject
+from .tuple_object import TupleCodec, TupleObject
+
+
+def _register_builtin_types() -> None:
+    GPDCTypeRegistry.register(
+        python_type=type(None),
+        gpdc_type="scalar:none",
+        object_class=NoneObject,
+        codec_class=NoneCodec,
+        priority=0,
+    )
+    GPDCTypeRegistry.register(
+        python_type=bool,
+        gpdc_type="scalar:bool",
+        object_class=BoolObject,
+        codec_class=BoolCodec,
+        priority=10,
+    )
+    GPDCTypeRegistry.register(
+        python_type=int,
+        gpdc_type="scalar:int",
+        object_class=IntObject,
+        codec_class=IntCodec,
+        priority=0,
+    )
+    GPDCTypeRegistry.register(
+        python_type=float,
+        gpdc_type="scalar:float",
+        object_class=FloatObject,
+        codec_class=FloatCodec,
+        priority=0,
+    )
+    GPDCTypeRegistry.register(
+        python_type=str,
+        gpdc_type="scalar:str",
+        object_class=StrObject,
+        codec_class=StrCodec,
+        priority=0,
+    )
+    GPDCTypeRegistry.register(
+        python_type=datetime.datetime,
+        gpdc_type="scalar:datetime",
+        object_class=DateTimeObject,
+        codec_class=DateTimeCodec,
+        priority=10,
+    )
+    GPDCTypeRegistry.register(
+        python_type=datetime.date,
+        gpdc_type="scalar:date",
+        object_class=DateObject,
+        codec_class=DateCodec,
+        priority=0,
+    )
+    GPDCTypeRegistry.register(
+        python_type=datetime.time,
+        gpdc_type="scalar:time",
+        object_class=TimeObject,
+        codec_class=TimeCodec,
+        priority=0,
+    )
+    GPDCTypeRegistry.register(
+        python_type=tuple,
+        gpdc_type="scalar:tuple",
+        object_class=TupleObject,
+        codec_class=TupleCodec,
+        priority=0,
+    )
+
+    GPDCTypeRegistry.register(
+        python_type=list,
+        gpdc_type="collection:list",
+        object_class=ListObject,
+        codec_class=ListCodec,
+        priority=0,
+    )
+    GPDCTypeRegistry.register(
+        python_type=dict,
+        gpdc_type="collection:dict",
+        object_class=DictObject,
+        codec_class=DictCodec,
+        priority=0,
+    )
+    GPDCTypeRegistry.register(
+        python_type=set,
+        gpdc_type="collection:set",
+        object_class=SetObject,
+        codec_class=SetCodec,
+        priority=0,
+    )

gpdatacached/builtins/set_object.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+import collections.abc
+
+from ..codec import GPDCContainerCodec
+from ..container import GPDCContainerObject
+from ..types import decode_key, encode_key
+
+
+class SetCodec(GPDCContainerCodec):
+    """Codec for Python set values stored as Redis Sets."""
+
+    @classmethod
+    def create_raw(cls, namespace, raw_key: str, value: set, owner_name: str, cache_mode: str, ttl: int) -> None:
+        if not value:
+            return
+        from ..types import encode_key
+
+        encoded = [encode_key(elem) for elem in value]
+        namespace._redis().sadd(raw_key, *encoded)
+
+    @classmethod
+    def read_raw(cls, namespace, raw_key: str) -> set:
+        from ..types import decode_key
+
+        members = namespace._redis().smembers(raw_key)
+        if not members:
+            return set()
+        return {decode_key(m) for m in members}
+
+    @classmethod
+    def delete_raw(cls, namespace, raw_key: str) -> None:
+        namespace._redis().delete(raw_key)
+
+
+class SetObject(GPDCContainerObject, collections.abc.MutableSet):
+    """Redis-backed set object implementing MutableSet."""
+
+    TYPE = "collection:set"
+
+    @property
+    def type(self) -> str:
+        return self.TYPE
+
+    @property
+    def value(self) -> set:
+        return SetCodec.read_raw(self._namespace, self.raw_key)
+
+    @value.setter
+    def value(self, new_value: set) -> None:
+        self._reject_value_replacement()
+
+    def __len__(self) -> int:
+        return self._redis().scard(self.raw_key)
+
+    def __contains__(self, item: object) -> bool:
+        encoded = encode_key(item)
+        return self._redis().sismember(self.raw_key, encoded)
+
+    def __iter__(self):
+        members = self._redis().smembers(self.raw_key)
+        for m in members:
+            yield decode_key(m)
+
+    def add(self, value: object) -> None:
+        encoded = encode_key(value)
+        self._redis().sadd(self.raw_key, encoded)
+        self._touch()
+
+    def discard(self, value: object) -> None:
+        encoded = encode_key(value)
+        removed = self._redis().srem(self.raw_key, encoded)
+        if removed:
+            self._touch()
+
+    def remove(self, value: object) -> None:
+        encoded = encode_key(value)
+        removed = self._redis().srem(self.raw_key, encoded)
+        if not removed:
+            raise KeyError(value)
+        self._touch()
+
+    def pop(self):
+        encoded = self._redis().spop(self.raw_key)
+        if encoded is None:
+            raise KeyError("pop from an empty set")
+        self._touch()
+        return decode_key(encoded)
+
+    def clear(self) -> None:
+        self._redis().delete(self.raw_key)
+        self._touch()
+
+    def _to_encoded_set(self, other) -> set[str]:
+        if isinstance(other, SetObject):
+            return self._redis().smembers(other.raw_key)
+        return {encode_key(e) for e in other}
+
+    def _binop(self, other, op):
+        self_set = self.value
+        other_set = other.value if isinstance(other, SetObject) else set(other)
+        return op(self_set, other_set)
+
+    def __or__(self, other):
+        """Return the union as a Python ``set`` (not a ``SetObject``).
+
+        Returning a ``SetObject`` would require creating a new Redis key,
+        which is an unexpected side-effect for a binary operator.
+        Use ``obj |= other`` for in-place mutation backed by Redis.
+        """
+        return self._binop(other, set.__or__)
+
+    def __and__(self, other):
+        """Return the intersection as a Python ``set``.  See ``__or__``."""
+        return self._binop(other, set.__and__)
+
+    def __sub__(self, other):
+        """Return the difference as a Python ``set``.  See ``__or__``."""
+        return self._binop(other, set.__sub__)
+
+    def __xor__(self, other):
+        """Return the symmetric difference as a Python ``set``.  See ``__or__``."""
+        return self._binop(other, set.__xor__)
+
+    def __ior__(self, other):
+        other_encoded = self._to_encoded_set(other)
+        if other_encoded:
+            self._redis().sadd(self.raw_key, *other_encoded)
+        self._touch()
+        return self
+
+    def __iand__(self, other):
+        other_encoded = self._to_encoded_set(other)
+        current = self._redis().smembers(self.raw_key)
+        to_remove = current - other_encoded
+        if to_remove:
+            self._redis().srem(self.raw_key, *to_remove)
+        self._touch()
+        return self
+
+    def __isub__(self, other):
+        other_encoded = self._to_encoded_set(other)
+        if other_encoded:
+            self._redis().srem(self.raw_key, *other_encoded)
+        self._touch()
+        return self
+
+    def __ixor__(self, other):
+        other_encoded = self._to_encoded_set(other)
+        current = self._redis().smembers(self.raw_key)
+        to_add = other_encoded - current
+        to_remove = current & other_encoded
+        if to_remove:
+            self._redis().srem(self.raw_key, *to_remove)
+        if to_add:
+            self._redis().sadd(self.raw_key, *to_add)
+        self._touch()
+        return self
+
+    def deepcopy(self):
+        return self.value

gpdatacached/builtins/str_object.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from ..codec import GPDCScalarCodec
+from ..scalar import GPDCScalarObject
+
+
+class StrCodec(GPDCScalarCodec):
+    @classmethod
+    def encode_value(cls, value: object) -> str:
+        if not isinstance(value, str):
+            raise TypeError(f"StrCodec cannot encode {type(value).__name__!r}")
+        return f"str:{value}"
+
+    @classmethod
+    def decode_value(cls, encoded: str) -> object:
+        type_name, _ = cls._parse_encoded(encoded)
+        if type_name != "str":
+            raise ValueError(f"StrCodec cannot decode type {type_name!r}")
+        return encoded[encoded.index(":") + 1 :]
+
+
+class StrObject(GPDCScalarObject):
+    TYPE = "scalar:str"

gpdatacached/builtins/tuple_object.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import json
+
+from ..codec import GPDCScalarCodec
+from ..scalar import GPDCScalarObject
+
+
+class TupleCodec(GPDCScalarCodec):
+    @classmethod
+    def encode_value(cls, value: object) -> str:
+        if not isinstance(value, tuple):
+            raise TypeError(f"TupleCodec cannot encode {type(value).__name__!r}")
+        from ..types import GPDCTypeRegistry
+
+        encoded_elems = []
+        for elem in value:
+            if isinstance(elem, (list, dict, set)):
+                raise TypeError(f"Cannot encode non-scalar tuple element: {type(elem).__name__!r}")
+            entry = GPDCTypeRegistry.lookup_by_python_type(elem)
+            encoded_elems.append(entry.codec_class.encode_value(elem))
+        return "tuple:" + json.dumps(encoded_elems, separators=(",", ":"))
+
+    @classmethod
+    def decode_value(cls, encoded: str) -> object:
+        prefix = "tuple:"
+        if not encoded.startswith(prefix):
+            raise ValueError(f"Not a tuple-encoded string: {encoded!r}")
+        json_part = encoded[len(prefix) :]
+        encoded_elems = json.loads(json_part)
+        from ..types import GPDCTypeRegistry
+
+        result = []
+        for elem_encoded in encoded_elems:
+            if not elem_encoded or ":" not in elem_encoded:
+                raise ValueError(f"Invalid tuple element encoding: {elem_encoded!r}")
+            colon_idx = elem_encoded.index(":")
+            type_name = elem_encoded[:colon_idx]
+            gpdc_type = f"scalar:{type_name}"
+            entry = GPDCTypeRegistry.lookup_by_gpdc_type(gpdc_type)
+            result.append(entry.codec_class.decode_value(elem_encoded))
+        return tuple(result)
+
+
+# by design: tuple 注册为 scalar 而非 container。tuple 是不可变的，语义上作为"复合标量"
+# （类似数据库复合主键）存储为单个 Redis string，不占用独立的 raw key。TupleCodec 显式
+# 拒绝 list/dict/set 元素，避免嵌套引用带来的 GC 复杂性。
+class TupleObject(GPDCScalarObject):
+    TYPE = "scalar:tuple"

gpdatacached/codec.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+
+class GPDCCodec(ABC):
+    """Abstract base class for all GPDC codecs."""
+
+    @classmethod
+    @abstractmethod
+    def encode_value(cls, value: object) -> str:
+        """Encode a Python value to a string for storage in Redis metadata."""
+
+    @classmethod
+    @abstractmethod
+    def decode_value(cls, encoded: str) -> object:
+        """Decode a stored string back to a Python value."""
+
+
+class GPDCScalarCodec(GPDCCodec):
+    """Abstract base class for all scalar codecs."""
+
+    @classmethod
+    def _parse_encoded(cls, encoded: str) -> tuple[str, str]:
+        if not encoded or ":" not in encoded:
+            raise ValueError(f"Invalid scalar encoding: {encoded!r}")
+        colon_idx = encoded.index(":")
+        return encoded[:colon_idx], encoded[colon_idx + 1 :]
+
+
+class GPDCContainerCodec(ABC):
+    """Abstract base class for container codecs (list, dict, etc.)."""
+
+    @classmethod
+    @abstractmethod
+    def create_raw(cls, namespace, raw_key: str, value: object, owner_name: str, cache_mode: str, ttl: int) -> None:
+        """Create raw data storage in Redis for the given value."""
+
+    @classmethod
+    @abstractmethod
+    def read_raw(cls, namespace, raw_key: str) -> object:
+        """Restore a Python object from raw data in Redis."""
+
+    @classmethod
+    @abstractmethod
+    def delete_raw(cls, namespace, raw_key: str) -> None:
+        """Delete raw data storage from Redis."""

gpdatacached/config.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from typing import ClassVar, Optional
+
+from gpconfig import GPConfig
+from pydantic import Field, field_validator, model_validator
+
+from .lifecycle import VALID_CACHE_MODES, validate_cache_mode_and_ttl
+
+
+class GPDCNamespaceConfig(GPConfig):
+    """Configuration for a GPDC namespace."""
+
+    cfg_class_name: ClassVar[str] = "GPDCNamespaceConfig"
+
+    default_cache_mode: Optional[str] = None
+    default_ttl_seconds: Optional[int] = None
+
+    @field_validator("default_cache_mode")
+    @classmethod
+    def _validate_cache_mode(cls, v: str | None) -> str | None:
+        if v is not None and v not in VALID_CACHE_MODES:
+            raise ValueError(f"Invalid default_cache_mode: {v!r}")
+        return v
+
+    @field_validator("default_ttl_seconds")
+    @classmethod
+    def _validate_ttl(cls, v: int | None) -> int | None:
+        if v is not None and v < 0:
+            raise ValueError(f"Invalid default_ttl_seconds: {v!r}")
+        return v
+
+    @model_validator(mode="after")
+    def _validate_ttl_mode_consistency(self) -> GPDCNamespaceConfig:
+        if self.default_cache_mode is not None and self.default_ttl_seconds is not None:
+            validate_cache_mode_and_ttl(self.default_cache_mode, self.default_ttl_seconds)
+        return self
+
+
+class GPDCDomainConfig(GPConfig):
+    """Configuration for a GPDC domain."""
+
+    cfg_class_name: ClassVar[str] = "GPDCDomainConfig"
+
+    redis_host: str = "localhost"
+    redis_port: int = 6379
+    redis_db: int = 0
+    redis_password: str = ""
+
+    default_cache_mode: str = "permanent"
+    default_ttl_seconds: int = 0
+
+    gc_enabled: bool = False
+    gc_interval_seconds: int = 300
+
+    namespaces: dict[str, GPDCNamespaceConfig] = Field(default_factory=dict)
+
+    # Lock configuration (see dev_docs/2026-06-21-cross-process-locking-design.md).
+    default_lock_ttl_seconds: int = 30
+    default_lock_acquire_timeout_seconds: int = 30
+    gc_lock_ttl_seconds: int = 30
+    gc_lock_wait_seconds: int = 5
+
+    @field_validator("default_cache_mode")
+    @classmethod
+    def _validate_cache_mode(cls, v: str) -> str:
+        if v not in VALID_CACHE_MODES:
+            raise ValueError(f"Invalid default_cache_mode: {v!r}")
+        return v
+
+    @field_validator("default_ttl_seconds")
+    @classmethod
+    def _validate_ttl(cls, v: int) -> int:
+        if v < 0:
+            raise ValueError(f"Invalid default_ttl_seconds: {v!r}")
+        return v
+
+    @field_validator(
+        "default_lock_ttl_seconds",
+        "gc_lock_ttl_seconds",
+    )
+    @classmethod
+    def _validate_lock_ttl_fields(cls, v: int) -> int:
+        if v < 1:
+            raise ValueError(f"Lock TTL must be >= 1 (Redis SET NX EX requires positive ttl), got {v!r}")
+        return v
+
+    @field_validator(
+        "default_lock_acquire_timeout_seconds",
+        "gc_lock_wait_seconds",
+    )
+    @classmethod
+    def _validate_lock_wait_fields(cls, v: int) -> int:
+        if v < 0:
+            raise ValueError(f"Lock wait/timeout must be >= 0 (0 = non-blocking), got {v!r}")
+        return v
+
+    @model_validator(mode="after")
+    def _validate_ttl_mode_consistency(self) -> GPDCDomainConfig:
+        validate_cache_mode_and_ttl(self.default_cache_mode, self.default_ttl_seconds)
+        return self

gpdatacached/container.py

@@ -0,0 +1,205 @@
+# src/gpdatacached/container.py
+"""GPDC container object hierarchy."""
+
+from __future__ import annotations
+
+import datetime
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .namespace import GPDCNamespace
+
+from .keys import make_object_key, make_raw_key, make_ref_key, parse_ref_encoded
+from .object import GPDCDataObject
+from .meta import ObjectMeta
+from .refset import release_ref, get_referrers, has_referrers
+from .types import decode_element
+
+
+class GPDCContainerObject(GPDCDataObject, ABC):
+    """Abstract base for container GPDC objects (lists, dicts, sets).
+
+    A container object stores its elements in a dedicated Redis key
+    (``raw_key``) and tracks which other objects reference its raw data via
+    a Redis hash (``ref_key``). Subclasses implement ``MutableSequence``,
+    ``MutableMapping``, or ``MutableSet`` semantics on top of this shared
+    infrastructure.
+
+    Key attributes:
+        raw_key: Redis key holding the container's element data (e.g. a list
+            or hash).
+        ref_key: Redis hash key recording referrer names and their reference
+            counts; used for ref-counting and cascade-deletion of anonymous
+            objects.
+    """
+
+    def __init__(self, name: str, namespace: "GPDCNamespace", *, canonical_name: str | None = None) -> None:
+        super().__init__(name, namespace, canonical_name=canonical_name)
+        domain_name = namespace.domain.name
+        ns_name = namespace.name
+        self.raw_key: str = make_raw_key(domain_name, ns_name, name)
+        self.ref_key: str = make_ref_key(domain_name, ns_name, name)
+
+    # ── Lifecycle: timestamps & sliding TTL ──────────────────────────
+
+    def _touch(self) -> None:
+        """Update metadata timestamps and apply sliding TTL if configured.
+
+        When owned by a parent, the sliding refresh propagates upward
+        through the owner chain.
+        """
+        from .lifecycle import policy_from_meta
+        from .meta import ObjectMeta
+        from .exceptions import ObjectGoneError
+
+        key = self._canonical_redis_key()
+        now = datetime.datetime.now(datetime.UTC)
+        r = self._redis()
+        item_count = self._current_item_count()
+        meta = ObjectMeta.load(r, key)
+        if meta is None:
+            raise ObjectGoneError(self.canonical_uri)
+        meta.touch(now, item_count=item_count).save(r, key)
+
+        if meta.owner == self.canonical_name:
+            policy = policy_from_meta(meta)
+            if policy.cache_mode == "sliding" and policy.declared_ttl > 0:
+                self.refresh_ttl()
+        else:
+            self._propagate_sliding_ttl_upward(meta.owner, r)
+
+    def _current_item_count(self) -> int:
+        """Return the current number of elements in this container."""
+        return len(self)
+
+    def _propagate_sliding_ttl_upward(self, owner_name: str, r) -> None:
+        """Propagate a sliding-window TTL refresh up the owner chain to the first self-owned ancestor."""
+        from .lifecycle import policy_from_meta
+        from .keys import make_object_key
+
+        while owner_name:
+            owner_obj_key = make_object_key(self.domain.name, self.namespace.name, owner_name)
+            owner_meta = ObjectMeta.load(r, owner_obj_key)
+            if owner_meta is None:
+                break
+            if owner_meta.owner == owner_name:
+                policy = policy_from_meta(owner_meta)
+                if policy.cache_mode == "sliding" and policy.declared_ttl > 0:
+                    owner_obj = self.namespace.get_object(owner_name)
+                    owner_obj.refresh_ttl()
+                break
+            owner_name = owner_meta.owner
+
+    # ── Identity: data owner resolution & encoding ───────────────────
+
+    def _data_owner_name(self) -> str:
+        """Return the canonical name that owns this container's raw data.
+
+        For references, returns ``canonical_name``; for owners, loads meta
+        to verify the raw_key mapping.
+        """
+        if self._is_reference:
+            return self._canonical_name
+        meta = ObjectMeta.load(self._redis(), self._redis_key())
+        if meta is None:
+            return self._name
+        raw_key = meta.value or self.raw_key
+        prefix = f"gpdc:{self._namespace.domain.name}:{self._namespace.name}:raw:"
+        if raw_key.startswith(prefix):
+            self.raw_key = raw_key
+            return raw_key[len(prefix) :]
+        return self._name
+
+    def _encode_as_ref_value(self) -> str:
+        """Encode this container as a ``ref:`` string for storage in parent raw data."""
+        owner_name = self._data_owner_name()
+        obj_key = make_object_key(self._namespace.domain.name, self._namespace.name, owner_name)
+        return f"ref:{obj_key}"
+
+    # ── Element reference tracking ────────────────────────────────────
+
+    def _release_element_ref(self, old_encoded: str | None) -> None:
+        """Release the ref binding held by a removed or overwritten element.
+
+        Decrements the reference count in the target's ref hash. If the
+        count reaches zero, cascade-deletes the target if it is an
+        orphaned anonymous object.
+        """
+        if not isinstance(old_encoded, str) or not old_encoded.startswith("ref:"):
+            return
+        target_name = parse_ref_encoded(old_encoded)
+        if target_name is None:
+            return
+        target_ref_key = make_ref_key(self._namespace.domain.name, self._namespace.name, target_name)
+        fully_released = release_ref(self._redis(), target_ref_key, self._data_owner_name())
+        if fully_released:
+            self._gc_anonymous_if_orphaned(target_name)
+
+    def _gc_anonymous_if_orphaned(self, target_name: str) -> None:
+        """Cascade-delete an anonymous object if it has no remaining referrers."""
+        if not target_name.startswith("~"):
+            return
+        target_ref_key = make_ref_key(self._namespace.domain.name, self._namespace.name, target_name)
+        r = self._redis()
+        if has_referrers(r, target_ref_key):
+            return
+        target_obj_key = make_object_key(self._namespace.domain.name, self._namespace.name, target_name)
+        target_meta = ObjectMeta.load(r, target_obj_key)
+        if target_meta is None or target_meta.owner == self._data_owner_name():
+            self._namespace._cascade_delete_anonymous(target_name)
+
+    # ── Value decode helpers ──────────────────────────────────────────
+
+    def _is_ref_encoded(self, encoded: str | None) -> bool:
+        """Check whether ``encoded`` value is a ``ref:`` pointer string."""
+        return isinstance(encoded, str) and encoded.startswith("ref:")
+
+    def _decode_and_copy_value(self, encoded: str) -> object:
+        """Decode an encoded element; deep-copy if it resolves to a container."""
+        value = decode_element(encoded, self._namespace)
+        if self._is_ref_encoded(encoded) and hasattr(value, "deepcopy"):
+            return value.deepcopy()
+        return value
+
+    def _reject_value_replacement(self) -> None:
+        """Always raise — containers require explicit mutation methods."""
+        raise TypeError("Container value replacement is not supported; use explicit mutating methods instead")
+
+    # ── Public inspection API ─────────────────────────────────────────
+
+    def referrers(self) -> set[str]:
+        """Return the set of object names referencing this container's raw data."""
+        owner_name = self._data_owner_name()
+        ref_key = make_ref_key(self._namespace.domain.name, self._namespace.name, owner_name)
+        return get_referrers(self._redis(), ref_key)
+
+    def has_referrers(self) -> bool:
+        """Return whether any other object references this container's raw data.
+
+        This is a cheap boolean check (no full set materialisation) to let callers
+        decide whether a ``del``/``expire_at`` of the owner would be blocked by
+        outstanding references. Resolving references before deletion/expiry is the
+        caller's responsibility — the library raises
+        :class:`~gpdatacached.exceptions.CanonicalObjectReferencedError` to *signal*
+        a blocked teardown, not to handle it.
+        """
+        owner_name = self._data_owner_name()
+        ref_key = make_ref_key(self._namespace.domain.name, self._namespace.name, owner_name)
+        return has_referrers(self._redis(), ref_key)
+
+    def copy(self) -> object:
+        """Shallow copy: return Python value with shared anon object refs."""
+        return self.value
+
+    def deepcopy(self) -> object:
+        """Deep copy: recursively clone all anon objects, return Python value."""
+        raise NotImplementedError("Subclass must implement deepcopy()")
+
+    @property
+    @abstractmethod
+    def value(self) -> object: ...
+
+    @value.setter
+    @abstractmethod
+    def value(self, new_value: object) -> None: ...