gpdatacached 0.1.0__tar.gz → 0.2.0__tar.gz

{gpdatacached-0.1.0 → gpdatacached-0.2.0}/.gitignore

@@ -177,6 +177,9 @@ CLAUDE.md
 AGENTS.md
 .opencode/
 
+# ZCode
+.zcode/
+
 # Github Copilot
 .github/copilot-instructions.md
 
@@ -195,3 +198,4 @@ progress.md
 
 # user ignore
 tests/mocks/log/
+/.superpowers/

gpdatacached-0.2.0/CHANGELOG.md

@@ -0,0 +1,116 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+GitHub Releases (with download artifacts) are published at
+<https://github.com/LinnetCodes/gpdatacached/releases>.
+
+## [0.2.0] — 2026-07-26
+
+### Added
+
+- **`GPDataCache` facade** — a config-driven entry point that discovers
+  `GPDCDomain` instances from a `gpconfig` `GPConfigFolder`, lazily constructs
+  them on first access, and resolves GPDC URIs to live `GPDCDataObject`
+  instances. Includes `__contains__` (config-snapshot membership, usable after
+  `close()`), `close()` (closes all cached domains), and the URI accessors below.
+- **GPDC URI access** — `GPDataCache.get_object_by_uri(uri)` and
+  `has_uri(uri)`, with multi-segment path traversal into nested containers
+  (e.g. `gpdc://domain/ns/order_obj/items/0`). Terminals on a scalar field
+  raise `ObjectNotFoundByURIError`. The utilities `make_uri` /
+  `uri_to_redis_key` / `validate_object_name` are part of the public surface.
+- **`expire_now()`** on `GPDCDataObject` — an explicit, mode-independent
+  "delete now" entry point (full teardown incl. anonymous subtrees; raises
+  `CanonicalObjectReferencedError` if still referenced). Use this instead of
+  `expire_in(0)` / `expire_at(past)` when you want unambiguous immediate
+  deletion.
+- **Public exception bases** — `GPDCError` (root of the whole hierarchy) and
+  `GPDCLockError` (base for lock-acquisition/ownership errors) are now
+  exported, so callers can catch by category: `except GPDCError` catches every
+  library error; `except GPDCLockError` catches every lock failure.
+- **`ObjectNotFoundByURIError`** — raised by URI resolution on any
+  unresolvable URI (missing domain/namespace/object, broken traversal,
+  scalar terminal, malformed syntax).
+- **Pydantic container-mode field validation** —
+  `BaseModelContainerObject.__setitem__` now validates the value against the
+  field's declared type *before* any Redis write (single-field via pydantic's
+  `TypeAdapter`); a type mismatch raises `pydantic.ValidationError` at the
+  call site and leaves the object untouched. Cross-field validators still
+  require the scalar codec.
+- gpconfig integration: `GPDCDomain` / `GPDCDomainConfig` are registered with
+  `gpconfig`'s object factory at import time, so a domain can be constructed
+  directly from a config file via `folder.get_object(name)`.
+
+### Changed
+
+- **BREAKING:** `GPDCDomain.__init__` signature changed from
+  `(name, config)` to `(config, name=None)`, conforming to gpconfig's
+  `cls(config)` configurable convention. The old call order raises
+  `TypeError` with migration guidance before any Redis connection is made.
+  `config.name` (the filename stem when loaded from a file) is preferred as
+  the domain name; the explicit `name` argument is the fallback.
+- `expire_in(seconds)` now requires `seconds > 0` (raises `ValueError`
+  otherwise). Use `expire_now()` for immediate deletion.
+- `GC interval` validation: `gc_interval_seconds` must now be `>= 30`
+  (default `300` unchanged). Smaller values busy-looped the background GC
+  thread.
+
+### Fixed
+
+- **Pandas non-unit `RangeIndex`** — `DataFrameObject.__len__` and
+  `SeriesObject`/`DataFrameObject` `extend` now honour the stored
+  `range_step` instead of assuming `step == 1`. Extending a non-unit-step
+  DataFrame now stays in the compact range representation (previously
+  promoted to labelled levels).
+- **`SeriesObject.name` identity** — `.name` now returns the namespace
+  binding (inherited from `GPDCDataObject`, matching `.canonical_name` /
+  `.uri`); the pandas label is exposed as `.series_name`. Restores the
+  base-class identity contract that `SeriesObject` had been overriding.
+- **Failed multi-element encodes** — `encode_session` now also reverses
+  ref-count increments it made on pre-existing containers, and a failed
+  first-time store cleans up the just-written binding `obj:`/`raw:`/`ref:`
+  keys, so a failed encode no longer leaves phantom referrers or orphan
+  metadata.
+- **Stale-handle mutations** — every container mutator now runs a
+  `_check_alive()` liveness guard *before* its first Redis write, so a
+  handle whose object has been deleted/expired raises `ObjectGoneError`
+  without first corrupting the `raw:` key.
+- **Sliding-TTL performance characterization** — sliding refresh batches the
+  TTL re-apply into one pipeline per tree level (the load-bearing cost is the
+  per-child `HGETALL`), corrected in the Performance Guide.
+
+### Documentation
+
+- New MkDocs site (Material theme) with full EN + Simplified-Chinese (ZH)
+  documentation: overview, API reference, lifecycle, locking, performance
+  guide, extensibility, pydantic/pandas support.
+- Durable explicit-anchor scheme (`{ #id }` attributes) + a `mkdocs build
+  --strict` validation gate, so editing a heading never silently breaks an
+  in-page cross-reference.
+
+[0.2.0]: https://github.com/LinnetCodes/gpdatacached/releases/tag/version-0.2.0
+
+## [0.1.0] — 2026-07-04
+
+Initial public release.
+
+Core typed cross-process data sharing and caching over Redis:
+
+- `GPDCDomain` / `GPDCNamespace` / `GPDCDataObject` three-tier model.
+- Typed scalars (int/float/str/bool/datetime/date/time/none/tuple) and live
+  containers (list/dict/set) with reference semantics — mutate in place, no
+  read-modify-write.
+- Per-object lifecycle: `permanent` / `ttl` / `sliding-window` cache modes
+  with cascade propagation.
+- Anonymous nested objects with reference counting and cascade delete.
+- Opt-in distributed locking (`obj.lock()` / `try_lock()`) via
+  `SET NX EX` + `BLPOP` with Lua-atomic release.
+- Background GC for orphaned/expired keys.
+- Extensibility: `GPDCTypeRegistry`, codec/object ABCs, pandas
+  (`Series`/`DataFrame`) and pydantic support extensions.
+- Strict config validation; `reset_domain_config` utility.
+
+[0.1.0]: https://github.com/LinnetCodes/gpdatacached/releases/tag/version-0.1.0

{gpdatacached-0.1.0 → gpdatacached-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gpdatacached
-Version: 0.1.0
+Version: 0.2.0
 Summary: Redis-based cross-process data sharing and caching library
 Project-URL: Homepage, https://github.com/linnetcodes/gpdatacached
 Project-URL: Documentation, https://linnetcodes.github.io/gpdatacached
@@ -59,6 +59,7 @@ Sharing mutable state across processes is painful. `multiprocessing.Manager` is
 - **Lifecycle control** — per-object `permanent` / `ttl` / `sliding-window` cache modes, with cascade propagation to owned subtrees.
 - **Background GC** — reclaims expired and orphaned anonymous objects.
 - **Opt-in distributed locking** — serialize writes across processes with `obj.lock()`.
+- **URI-based access** — manage multiple domains from config and resolve `gpdc://{domain}/{namespace}/{name}` URIs to data objects via `GPDataCache`, including traversal into anonymous nested containers.
 - **Optional extensions** — cache [pydantic](https://docs.pydantic.dev/) `BaseModel` records and [pandas](https://pandas.pydata.org/) `Series` / `DataFrame` (see [Extensions](#extensions)).
 
 ---
@@ -89,7 +90,7 @@ config = GPDCDomainConfig(
     redis_port=6379,
     redis_password="secret",
 )
-domain = GPDCDomain("mydomain", config)
+domain = GPDCDomain(config, name="mydomain")
 ns = domain.ensure_namespace("analytics")
 
 # Scalars read back as native Python values.
@@ -129,21 +130,21 @@ GPDCDomain ── GPDCNamespace ── GPDCDataObject (scalar | container)
 
 ## Documentation
 
-📖 **[Full documentation index](./docs/index.md)** — the entry point to all guides and references below.
+📖 **[Full documentation index](./docs/en/index.md)** — the entry point to all guides and references below.
 
-- **[Overview](./docs/overview.md)** — design purpose, philosophy, and end-to-end architecture (start here to understand the library as a whole).
-- **[API Reference](./docs/api.md)** — complete public API reference.
-- **[Lifecycle Management](./docs/lifecycle.md)** — how object creation, expiry, refresh, and deletion work, including anonymous and reference objects (read this to set correct expectations).
-- **[Extensibility](./docs/extensibility.md)** — the type system explained, with worked examples for adding your own scalar and container types (codecs, object classes, registration).
-- **[Performance Guide](./docs/performance-guide.md)** — usage patterns that degrade performance (sliding TTL overuse, deep nesting, unnecessary GC/locking) and their recommended alternatives. Read before putting GPDC on a hot path.
-- **[Multi-Process Locking](./docs/locking.md)** — when to lock, performance impact, recommended usage, deadlock avoidance, and GC interaction.
+- **[Overview](./docs/en/overview.md)** — design purpose, philosophy, and end-to-end architecture (start here to understand the library as a whole).
+- **[API Reference](./docs/en/api.md)** — complete public API reference.
+- **[Lifecycle Management](./docs/en/lifecycle.md)** — how object creation, expiry, refresh, and deletion work, including anonymous and reference objects (read this to set correct expectations).
+- **[Extensibility](./docs/en/extensibility.md)** — the type system explained, with worked examples for adding your own scalar and container types (codecs, object classes, registration).
+- **[Performance Guide](./docs/en/performance-guide.md)** — usage patterns that degrade performance (sliding TTL overuse, deep nesting, unnecessary GC/locking) and their recommended alternatives. Read before putting GPDC on a hot path.
+- **[Multi-Process Locking](./docs/en/locking.md)** — when to lock, performance impact, recommended usage, deadlock avoidance, and GC interaction.
 
 ## Extensions
 
 Optional built-in extensions under `gpdatacached.extensions`:
 
-- **[Pydantic Support](./docs/pydantic-support.md)** — cache pydantic `BaseModel` records. Two storage modes: scalar (atomic JSON) for scalar-only models, container (Redis hash) for models needing field-level access or nested `list`/`dict`/`set` fields. Pydantic is a core dependency; no extra install needed.
-- **[Pandas Support](./docs/pandas-support.md)** — cache pandas `Series` / `DataFrame` as live objects. Online selective accessors (`.iloc`, `.loc`, `df[col]`) for one-shot subset reads; `.value` for full restore; `extend` for appends. Requires `pip install "gpdatacached[pandas]"`.
+- **[Pydantic Support](./docs/en/pydantic-support.md)** — cache pydantic `BaseModel` records. Two storage modes: scalar (atomic JSON) for scalar-only models, container (Redis hash) for models needing field-level access or nested `list`/`dict`/`set` fields. Pydantic is a core dependency; no extra install needed.
+- **[Pandas Support](./docs/en/pandas-support.md)** — cache pandas `Series` / `DataFrame` as live objects. Online selective accessors (`.iloc`, `.loc`, `df[col]`) for one-shot subset reads; `.value` for full restore; `extend` for appends. Requires `pip install "gpdatacached[pandas]"`.
 
 ---
 

{gpdatacached-0.1.0 → gpdatacached-0.2.0}/README.md

@@ -22,6 +22,7 @@ Sharing mutable state across processes is painful. `multiprocessing.Manager` is
 - **Lifecycle control** — per-object `permanent` / `ttl` / `sliding-window` cache modes, with cascade propagation to owned subtrees.
 - **Background GC** — reclaims expired and orphaned anonymous objects.
 - **Opt-in distributed locking** — serialize writes across processes with `obj.lock()`.
+- **URI-based access** — manage multiple domains from config and resolve `gpdc://{domain}/{namespace}/{name}` URIs to data objects via `GPDataCache`, including traversal into anonymous nested containers.
 - **Optional extensions** — cache [pydantic](https://docs.pydantic.dev/) `BaseModel` records and [pandas](https://pandas.pydata.org/) `Series` / `DataFrame` (see [Extensions](#extensions)).
 
 ---
@@ -52,7 +53,7 @@ config = GPDCDomainConfig(
     redis_port=6379,
     redis_password="secret",
 )
-domain = GPDCDomain("mydomain", config)
+domain = GPDCDomain(config, name="mydomain")
 ns = domain.ensure_namespace("analytics")
 
 # Scalars read back as native Python values.
@@ -92,21 +93,21 @@ GPDCDomain ── GPDCNamespace ── GPDCDataObject (scalar | container)
 
 ## Documentation
 
-📖 **[Full documentation index](./docs/index.md)** — the entry point to all guides and references below.
+📖 **[Full documentation index](./docs/en/index.md)** — the entry point to all guides and references below.
 
-- **[Overview](./docs/overview.md)** — design purpose, philosophy, and end-to-end architecture (start here to understand the library as a whole).
-- **[API Reference](./docs/api.md)** — complete public API reference.
-- **[Lifecycle Management](./docs/lifecycle.md)** — how object creation, expiry, refresh, and deletion work, including anonymous and reference objects (read this to set correct expectations).
-- **[Extensibility](./docs/extensibility.md)** — the type system explained, with worked examples for adding your own scalar and container types (codecs, object classes, registration).
-- **[Performance Guide](./docs/performance-guide.md)** — usage patterns that degrade performance (sliding TTL overuse, deep nesting, unnecessary GC/locking) and their recommended alternatives. Read before putting GPDC on a hot path.
-- **[Multi-Process Locking](./docs/locking.md)** — when to lock, performance impact, recommended usage, deadlock avoidance, and GC interaction.
+- **[Overview](./docs/en/overview.md)** — design purpose, philosophy, and end-to-end architecture (start here to understand the library as a whole).
+- **[API Reference](./docs/en/api.md)** — complete public API reference.
+- **[Lifecycle Management](./docs/en/lifecycle.md)** — how object creation, expiry, refresh, and deletion work, including anonymous and reference objects (read this to set correct expectations).
+- **[Extensibility](./docs/en/extensibility.md)** — the type system explained, with worked examples for adding your own scalar and container types (codecs, object classes, registration).
+- **[Performance Guide](./docs/en/performance-guide.md)** — usage patterns that degrade performance (sliding TTL overuse, deep nesting, unnecessary GC/locking) and their recommended alternatives. Read before putting GPDC on a hot path.
+- **[Multi-Process Locking](./docs/en/locking.md)** — when to lock, performance impact, recommended usage, deadlock avoidance, and GC interaction.
 
 ## Extensions
 
 Optional built-in extensions under `gpdatacached.extensions`:
 
-- **[Pydantic Support](./docs/pydantic-support.md)** — cache pydantic `BaseModel` records. Two storage modes: scalar (atomic JSON) for scalar-only models, container (Redis hash) for models needing field-level access or nested `list`/`dict`/`set` fields. Pydantic is a core dependency; no extra install needed.
-- **[Pandas Support](./docs/pandas-support.md)** — cache pandas `Series` / `DataFrame` as live objects. Online selective accessors (`.iloc`, `.loc`, `df[col]`) for one-shot subset reads; `.value` for full restore; `extend` for appends. Requires `pip install "gpdatacached[pandas]"`.
+- **[Pydantic Support](./docs/en/pydantic-support.md)** — cache pydantic `BaseModel` records. Two storage modes: scalar (atomic JSON) for scalar-only models, container (Redis hash) for models needing field-level access or nested `list`/`dict`/`set` fields. Pydantic is a core dependency; no extra install needed.
+- **[Pandas Support](./docs/en/pandas-support.md)** — cache pandas `Series` / `DataFrame` as live objects. Online selective accessors (`.iloc`, `.loc`, `df[col]`) for one-shot subset reads; `.value` for full restore; `extend` for appends. Requires `pip install "gpdatacached[pandas]"`.
 
 ---
 

{gpdatacached-0.1.0 → gpdatacached-0.2.0}/README.zh-CN.md

@@ -22,6 +22,7 @@
 - **生命周期控制** —— 每个对象可设置 `permanent` / `ttl` / `sliding`（滑动窗口）缓存模式，并将策略级联传播到所拥有的子树。
 - **后台 GC** —— 自动回收过期或成为孤儿的匿名对象。
 - **可选的分布式锁** —— 通过 `obj.lock()` 在多进程间串行化写入。
+- **基于 URI 的访问** —— 通过 `GPDataCache` 从配置管理多个 domain，并将 `gpdc://{domain}/{namespace}/{name}` 形式的 URI 解析为数据对象，包括对匿名嵌套容器的遍历。
 - **可选扩展** —— 可缓存 [pydantic](https://docs.pydantic.dev/) `BaseModel` 记录与 [pandas](https://pandas.pydata.org/) `Series` / `DataFrame`（见[扩展](#扩展)）。
 
 ---
@@ -52,7 +53,7 @@ config = GPDCDomainConfig(
     redis_port=6379,
     redis_password="secret",
 )
-domain = GPDCDomain("mydomain", config)
+domain = GPDCDomain(config, name="mydomain")
 ns = domain.ensure_namespace("analytics")
 
 # 标量读取出来是原生 Python 值。
@@ -92,21 +93,21 @@ GPDCDomain ── GPDCNamespace ── GPDCDataObject (标量 | 容器)
 
 ## 文档
 
-📖 **[完整文档索引](./docs/zh-CN/index.md)** —— 以下所有指南与参考的入口。
+📖 **[完整文档索引](./docs/zh/index.md)** —— 以下所有指南与参考的入口。
 
-- **[总体概览](./docs/zh-CN/overview.md)** —— 设计目的、设计理念与端到端整体架构（从这里开始，从整体上理解本库）。
-- **[API 参考](./docs/zh-CN/api.md)** —— 完整的公共 API 参考。
-- **[生命周期管理](./docs/zh-CN/lifecycle.md)** —— 对象的创建、过期、刷新与删除如何运作，含匿名对象与引用对象（阅读本文以建立合理预期）。
-- **[可扩展性](./docs/zh-CN/extensibility.md)** —— 类型系统详解，含添加自定义标量与容器类型的完整示例（codec、对象类、注册）。
-- **[性能指南](./docs/zh-CN/performance-guide.md)** —— 会拖累性能的用法（滥用 sliding TTL、过深嵌套、不必要地启用 GC/加锁）及其推荐替代。把 GPDC 放上热路径前必读。
-- **[多进程加锁](./docs/zh-CN/locking.md)** —— 何时需要加锁、性能影响、推荐用法、避免死锁的顺序以及与 GC 的交互。
+- **[总体概览](./docs/zh/overview.md)** —— 设计目的、设计理念与端到端整体架构（从这里开始，从整体上理解本库）。
+- **[API 参考](./docs/zh/api.md)** —— 完整的公共 API 参考。
+- **[生命周期管理](./docs/zh/lifecycle.md)** —— 对象的创建、过期、刷新与删除如何运作，含匿名对象与引用对象（阅读本文以建立合理预期）。
+- **[可扩展性](./docs/zh/extensibility.md)** —— 类型系统详解，含添加自定义标量与容器类型的完整示例（codec、对象类、注册）。
+- **[性能指南](./docs/zh/performance-guide.md)** —— 会拖累性能的用法（滥用 sliding TTL、过深嵌套、不必要地启用 GC/加锁）及其推荐替代。把 GPDC 放上热路径前必读。
+- **[多进程加锁](./docs/zh/locking.md)** —— 何时需要加锁、性能影响、推荐用法、避免死锁的顺序以及与 GC 的交互。
 
 ## 扩展
 
 `gpdatacached.extensions` 下的可选内建扩展：
 
-- **[Pydantic 支持](./docs/zh-CN/pydantic-support.md)** —— 缓存 pydantic `BaseModel` 记录。两种存储模式：标量模式（原子 JSON，适用于纯标量模型）和容器模式（Redis hash，适用于需要字段级访问或嵌套 `list`/`dict`/`set` 字段的模型）。pydantic 是核心依赖，无需额外安装。
-- **[Pandas 支持](./docs/zh-CN/pandas-support.md)** —— 将 pandas `Series` / `DataFrame` 缓存为活跃对象。在线选择性访问器（`.iloc`、`.loc`、`df[col]`）用于一次性子集读取；`.value` 用于完整还原；`extend` 用于追加。需要 `pip install "gpdatacached[pandas]"`。
+- **[Pydantic 支持](./docs/zh/pydantic-support.md)** —— 缓存 pydantic `BaseModel` 记录。两种存储模式：标量模式（原子 JSON，适用于纯标量模型）和容器模式（Redis hash，适用于需要字段级访问或嵌套 `list`/`dict`/`set` 字段的模型）。pydantic 是核心依赖，无需额外安装。
+- **[Pandas 支持](./docs/zh/pandas-support.md)** —— 将 pandas `Series` / `DataFrame` 缓存为活跃对象。在线选择性访问器（`.iloc`、`.loc`、`df[col]`）用于一次性子集读取；`.value` 用于完整还原；`extend` 用于追加。需要 `pip install "gpdatacached[pandas]"`。
 
 ---
 

{gpdatacached-0.1.0 → gpdatacached-0.2.0}/docs/en/api.md

@@ -44,7 +44,7 @@ GPDCDomain  ──┬── GPDCNamespace ──┬── GPDCDataObject (scalar
 
 ---
 
-## Quick Start
+## Quick Start { #api-quick-start }
 
 ```python
 import gpdatacached
@@ -57,7 +57,7 @@ config = GPDCDomainConfig(
     redis_db=0,
     redis_password="secret",
 )
-domain = GPDCDomain("mydomain", config)
+domain = GPDCDomain(config, name="mydomain")
 
 # 2. Get or create a namespace.
 ns = domain.ensure_namespace("analytics")
@@ -90,12 +90,49 @@ domain.close()
 
 ---
 
+## Managing Domains via Configuration: `GPDataCache`
+
+When your application drives many domains from configuration files managed by
+[`gpconfig`](https://github.com/linnetcodes/gpconfig), `GPDataCache` is the
+higher-level entry point. It holds a `GPConfigFolder`, lazily constructs and
+caches `GPDCDomain` instances from it, and resolves GPDC URIs to data objects.
+
+```python
+from gpconfig import GPConfigManager
+import gpdatacached                                       # registers GPDCDomain with gpconfig
+from gpdatacached import GPDataCache
+
+# 1. Build a GPConfigFolder for the "gpdc" subfolder of your config folder.
+mgr = GPConfigManager("myproject", cfg_folder="/path/to/configs")
+folder = mgr.get_config("gpdc")        # -> GPConfigFolder; sample layouts in tests/configs/gpdc
+
+# 2. GPDataCache manages the domains found in that folder.
+with GPDataCache(folder) as cache:
+    "core_domain" in cache                                  # True iff a config exists (no Redis)
+    domain = cache.get_domain("core_domain")                # lazy construct + cache
+
+    # 3. Resolve objects by GPDC URI — including anonymous nested objects.
+    ns = domain.get_namespace("core_app")
+    ns["config"] = {"server": {"host": "localhost", "port": 8080}, "tags": ["a", "b"]}
+
+    cfg = cache.get_object_by_uri("gpdc://core_domain/core_app/config")
+    server = cache.get_object_by_uri("gpdc://core_domain/core_app/config/server")
+    cache.has_uri("gpdc://core_domain/core_app/missing")    # False
+# close() on exit closes every cached domain (idempotent).
+```
+
+See [`GPDataCache`](#gpdatacache) below for the full API and the [URI resolution
+rules](#get_object_by_uri) (path traversal, scalar terminals, `ListObject`
+index coercion).
+
+---
+
 ## Core Types
 
 ### `GPDCDomain`
 
 ```python
-class GPDCDomain(name: str, config: GPDCDomainConfig)
+class GPDCDomain(config: GPDCDomainConfig, name: str | None = None)
 ```
 
 The configuration root and Redis connection pool. On construction it:
@@ -158,7 +195,7 @@ Configuration for a `GPDCDomain`. All fields are validated; lock fields must be
 | `default_cache_mode` | `str` | `"permanent"` | One of `"permanent"`, `"ttl"`, `"sliding"`. |
 | `default_ttl_seconds` | `int` | `0` | Default TTL; must be `> 0` when mode is `"ttl"`/`"sliding"`. |
 | `gc_enabled` | `bool` | `False` | Start the background GC thread. |
-| `gc_interval_seconds` | `int` | `300` | Background GC cycle interval. |
+| `gc_interval_seconds` | `int` | `300` | Background GC cycle interval (must be `≥ 30`; smaller values busy-loop the GC thread and flood Redis). |
 | `namespaces` | `dict[str, GPDCNamespaceConfig]` | `{}` | Predefined namespaces to create eagerly. |
 | `default_lock_ttl_seconds` | `int` | `30` | TTL on lock keys (must be `≥ 1`). |
 | `default_lock_acquire_timeout_seconds` | `int` | `30` | Blocking timeout for `obj.lock()` (must be `≥ 0`). |
@@ -239,13 +276,133 @@ Delete the four lock-config fields (`default_lock_ttl_seconds`, `default_lock_ac
 
 ```python
 reset_domain_config("mydomain", old_config)     # must be called BEFORE construction
-domain = GPDCDomain("mydomain", new_config)     # writes the new lock config
+domain = GPDCDomain(new_config, name="mydomain")     # writes the new lock config
 ```
 
 Only the Redis connection fields on `config` are read; lock fields on the passed config are ignored.
 
 ---
 
+### `GPDataCache`
+
+```python
+class GPDataCache(folder: gpconfig.GPConfigFolder)   # context manager
+```
+
+A facade that manages `GPDCDomain` instances discovered in a
+[`gpconfig`](https://github.com/linnetcodes/gpconfig) `GPConfigFolder`, and
+resolves GPDC URIs to [`GPDCDataObject`](#gpdcdataobject) instances. It is the
+recommended entry point when your domains are driven by config files rather
+than constructed ad-hoc in code.
+
+**Construction.** Built from a `GPConfigFolder`. On construction it stores the
+folder reference only — **no domain is created**. Domains are constructed
+lazily (via gpconfig's object factory `folder.get_object(name)`) on first
+[`get_domain`](#gpdatacache) access, and cached in an internal dict. The cache
+is a snapshot: config files edited after construction are **not** re-read;
+rebuild the `GPDataCache` to pick up changes.
+
+`GPDataCache` does **not** create domains lacking a config file — for ad-hoc
+domains use [`GPDCDomain`](#gpdcdomain) directly.
+
+> **Registration side effect.** `import gpdatacached` registers `GPDCDomain`
+> and `GPDCDomainConfig` with gpconfig's object factory (idempotent), which is
+> what makes `folder.get_object(name)` able to construct a `GPDCDomain`. No
+> extra setup is needed.
+
+**Dunder protocols**
+
+- `name in cache` → `True` iff a config named `name` exists in the folder. This is a pure config-snapshot check: it does **not** touch Redis and does not construct (or require) a `GPDCDomain` instance — the answer depends only on whether the config file is present, not on whether `get_domain(name)` has been called. The domain instance is created lazily on first `get_domain(name)` access.
+- `with cache as c` / `__exit__` → closes every cached domain on exit; `close()` is idempotent.
+
+> **`close()` behaviour — the membership exception.** After `cache.close()`, the resource-touching methods (`get_domain`, `get_object_by_uri`, `has_uri`) raise `RuntimeError("GPDataCache is closed")`. The `name in cache` membership check is the **deliberate exception**: because it only reads the config snapshot and touches no resources, it keeps working after `close()`. This is intentional — "does a config for this domain exist?" is meaningful regardless of whether the cache is open.
+
+**Methods**
+
+| Method | Description |
+|---|---|
+| `get_domain(name)` | Return the cached `GPDCDomain` for `name`, constructing it lazily on first access. Propagates gpconfig's `ConfigNotFoundError` if no config exists for `name`. Raises `RuntimeError` after `close()`. |
+| [`get_object_by_uri(uri)`](#get_object_by_uri) | Resolve a GPDC URI to a `GPDCDataObject`. Raises `RuntimeError` after `close()`. |
+| `has_uri(uri)` | Return `True` iff `get_object_by_uri(uri)` would succeed. Raises `RuntimeError` after `close()`. |
+| `close()` | Close every cached domain. Idempotent. |
+
+---
+
+#### `get_object_by_uri`
+
+```python
+def get_object_by_uri(self, uri: str) -> GPDCDataObject
+```
+
+Resolve a GPDC URI to a [`GPDCDataObject`](#gpdcdataobject). The URI must begin
+with `gpdc://` and has the form:
+
+```
+gpdc://{domain}/{namespace}/{name}[/{path_segment}...]
+```
+
+- The first three segments (`domain` / `namespace` / `name`) locate the **root
+  object**, fetched via `namespace.get_object(name)` — so the root is always
+  returned as a `GPDCDataObject`, **even when it is a scalar** (unlike
+  `ns[name]`, which unwraps scalars to native values).
+- Any further segments form a **path** that descends into the object via
+  `__getitem__`, one segment at a time. This is how anonymous nested containers
+  become reachable: `gpdc://d/ns/obj/key/0` walks `obj["key"][0]`.
+
+**Returns objects, never values.** `get_object_by_uri` always returns a
+`GPDCDataObject`. It cannot be used to read a scalar value or an element value
+directly.
+
+**Path-segment rules**
+
+| Current object | Segment handling |
+|---|---|
+| `ListObject` | The segment must be a **non-negative integer** (a pure-digit string); it is converted to `int` before indexing. Negative indices, decimals, and slices are rejected. |
+| `DictObject` / pydantic container-mode model / other subscriptable container | The segment is used as-is (a string key). |
+| `SetObject`, scalar objects | Have no `__getitem__` — any further path segment raises `ObjectNotFoundByURIError`. |
+
+**Scalar terminals are rejected.** Scalars nested inside a container are stored
+as inlined values (not as referenced objects), so descending into a scalar
+element yields a native Python value. Because `get_object_by_uri` returns
+objects only, a path that terminates on a scalar raises `ObjectNotFoundByURIError`.
+For example, given `ns["cfg"] = {"port": 8080}`, `gpdc://d/ns/cfg/port` raises
+(the value `8080` is a scalar, not a data object).
+
+**Errors.** Every failure mode raises [`ObjectNotFoundByURIError`](#objectnotfoundbyurierror)
+(carries `.uri` and `.reason`): malformed URI (missing `gpdc://`, fewer than
+three segments, empty segment), unknown domain, missing namespace, missing root
+object, a path segment that fails (`KeyError`/`IndexError`/`TypeError`), and a
+scalar terminal.
+
+**Example.** Given `ns["cfg"] = {"server": {"host": "x"}, "tags": ["a","b"]}`:
+
+| URI | Result |
+|---|---|
+| `gpdc://d/ns/cfg` | the `DictObject` for `cfg` |
+| `gpdc://d/ns/cfg/server` | the nested `DictObject` for `server` |
+| `gpdc://d/ns/cfg/server/host` | raises — `host` is the scalar `"x"` |
+| `gpdc://d/ns/cfg/tags/0` | raises — `tags[0]` is the scalar `"a"` |
+| `gpdc://d/ns/cfg/missing` | raises — `KeyError` on the path segment |
+
+---
+
+### `ObjectNotFoundByURIError`
+
+```python
+class ObjectNotFoundByURIError(GPDCError)
+```
+
+Raised by [`GPDataCache.get_object_by_uri`](#get_object_by_uri) when a GPDC URI
+cannot be resolved to a `GPDCDataObject`. Covers every failure mode: malformed
+URI syntax, unknown domain (no config), missing namespace, missing root object,
+a path segment that fails, and a scalar terminal. Carries `.uri` (the URI
+string) and `.reason` (a short explanation).
+
+`has_uri` swallows only this exception; infrastructure errors (e.g. Redis
+connection failures) propagate.
+
+---
+
 ## Data Objects
 
 ### `GPDCDataObject`
@@ -286,12 +443,13 @@ Abstract base class for every GPDC data object. Subclasses are split into [`GPDC
 
 | Method | Description |
 |---|---|
-| `expire_in(seconds)` | Set a new TTL. Object must be in `cache_mode="ttl"`. Requires ownership. |
+| `expire_in(seconds)` | Set a new TTL. Object must be in `cache_mode="ttl"`. `seconds` must be `> 0` — to delete now, use `expire_now()`. Requires ownership. |
 | `expire_at(when)` | Set absolute expiry time. Object must be in `cache_mode="ttl"`. Requires ownership. Deletes the object immediately if `when` is in the past (equivalent to `del ns[name]`: cleans `obj:`/`raw:`/`ref:` and cascade-deletes anonymous subtrees; raises `CanonicalObjectReferencedError` if the owner is still referenced — check `has_referrers()` first). |
+| `expire_now()` | Delete this object immediately. Equivalent to `del ns[canonical_name]`: full teardown (obj:/raw:/ref: + cascade-delete of anonymous subtrees). Works in any `cache_mode` (unlike `expire_in`/`expire_at`, which require `cache_mode="ttl"`). Requires ownership; raises `CanonicalObjectReferencedError` if the owner is still referenced by aliases — check `has_referrers()` first. |
 | `persist()` | Switch to `cache_mode="permanent"` with `ttl=0`. Requires ownership. |
 | `update_cache_mode_and_ttl(cache_mode, ttl)` | Replace the full cache policy. Requires ownership. |
 | `refresh_ttl()` | Re-apply this object's own TTL to its keys and cascade-refresh its owned subtree (used by the sliding-window path). No-op for permanent objects. |
-| `take_ownership()` | Promote a reference object to be the canonical owner of its own data. Only valid for named references. |
+| `take_ownership()` | Promote **the referenced object** to own itself (primary use case: a named reference to an anonymous nested object). On a reference to a named (already self-owned) object it is a correct no-op. The call itself must be made via a named reference handle. See [Lifecycle §7](./lifecycle.md#7-the-ownership-model). |
 
 **Locking methods** (opt-in, never called automatically by mutations)
 
@@ -467,7 +625,7 @@ Members may be any hashable scalar (no containers, no empty tuple). Implements t
 
 ## Codecs
 
-Codecs convert between Python values and their Redis storage representation. Every type registered with [`GPDCTypeRegistry`](#type-registry) must supply a codec.
+Codecs convert between Python values and their Redis storage representation. Every type registered with [`GPDCTypeRegistry`](#api-type-registry) must supply a codec.
 
 > This section is the API summary. For a full walkthrough of writing codecs — scalar and container, with worked examples (`Color`, `Counter`) and the mutation hooks every container must call — see the dedicated [Extensibility](./extensibility.md) document.
 
@@ -516,7 +674,7 @@ Abstract base for container codecs. Containers store their elements in a dedicat
 
 ---
 
-## Type Registry
+## Type Registry { #api-type-registry }
 
 ### `GPDCTypeRegistry`
 
@@ -562,7 +720,10 @@ GPDCTypeRegistry.register(
 
 ## Key & URI Utilities
 
-Low-level helpers for working with GPDC's key/URI scheme. Most applications never need these directly.
+Low-level helpers for working with GPDC's key/URI scheme. For actually
+*resolving* a URI to a data object, use
+[`GPDataCache.get_object_by_uri`](#get_object_by_uri) — these helpers only build
+or convert URI/key strings and are rarely needed directly.
 
 ### `make_uri`
 
@@ -592,7 +753,23 @@ Validate that `name` contains only letters, digits, `.` or `_` and is not a rese
 
 ## Exceptions
 
-All public exceptions descend from a private `GPDCError(Exception)` base. Catch them individually for precise error handling.
+All public exceptions descend from the public `GPDCError(Exception)` root. Use `except GPDCError` to catch every gpdatacached error, or catch them individually for precise handling. The lock-acquisition errors additionally share a public `GPDCLockError` base — `except GPDCLockError` catches every lock-acquisition/ownership failure (currently `LockAcquisitionTimeout`).
+
+### `GPDCError`
+
+```python
+class GPDCError(Exception)
+```
+
+The root of the gpdatacached exception hierarchy. Every exception raised by this library is a subclass of `GPDCError`, so `except GPDCError` is the broad catch-all. Prefer catching the specific subclass when you need to distinguish failure modes.
+
+### `GPDCLockError`
+
+```python
+class GPDCLockError(GPDCError)
+```
+
+Base class for lock-acquisition/ownership errors. `except GPDCLockError` catches every lock-related failure (currently `LockAcquisitionTimeout`; `LockOwnershipError` also descends from it but is swallowed internally by `HeldLock.release()`).
 
 ### `ObjectGoneError`
 
@@ -624,7 +801,7 @@ Raised during encoding when a container references itself (directly or transitiv
 class LockAcquisitionTimeout(GPDCLockError)
 ```
 
-Raised when `obj.lock()` cannot acquire the lock within the configured `timeout`. Carries `.lock_key` and `.timeout`. See [Multi-Process Locking](./locking.md).
+Raised when `obj.lock()` cannot acquire the lock within the configured `timeout`. Carries `.lock_key` and `.timeout`. It extends the public `GPDCLockError` base, so `except GPDCLockError` catches it. See [Multi-Process Locking](./locking.md).
 
 ### `GPDCLockConfigInconsistentError`