gpdatacached 0.1.0__tar.gz → 0.2.1__tar.gz

{gpdatacached-0.1.0 → gpdatacached-0.2.1}/.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.1/CHANGELOG.md

@@ -0,0 +1,151 @@
+# 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.1] — 2026-10-12
+
+### Added
+
+- **`Decimal` builtin scalar type** — `decimal.Decimal` is auto-registered on
+  `import gpdatacached` as `scalar:decimal`; `DecimalObject` and `DecimalCodec`
+  are exported from the package root. Encoded losslessly as
+  `decimal:{str(value)}`: coefficient/exponent (significance) are preserved
+  exactly, extreme exponents use scientific notation, and non-finite values
+  (`NaN`, `sNaN`, `±Infinity`) plus `-0` roundtrip as-is — the same policy as
+  `float`'s `nan`/`inf`. Works everywhere a registered scalar does: standalone
+  objects, container elements, dict keys, set members, tuple elements, and
+  pandas object-dtype columns/index labels. Malformed payloads raise
+  `ValueError` on decode. Note the documented cross-type-equality caveat:
+  natively-equal values of different numeric types (`1` vs `Decimal(1)`) are
+  distinct GPDC dict keys/set members, as `1` vs `1.0` already were.
+
+### Documentation
+
+- Full docs-vs-code synchronization pass across `docs/` (English + zh-CN
+  mirrors) and both READMEs: README now lists `Decimal` among the supported
+  scalar types and its Quick Start lifecycle example is runnable as written
+  (`update_cache_mode_and_ttl` instead of mode-restricted `expire_in`);
+  `api.md` documents `remaining_ttl()` and the exact `ObjectGoneError`
+  surface; the extensibility codec diagram and the overview layer-dependency
+  edge were corrected to match the code (`GPDCContainerCodec` is a sibling
+  root of `GPDCCodec`, and the extensions depend on the type-system layer,
+  not the builtins); performance-guide RTT attributions were updated; the
+  zh-CN mirrors gained the translated §7 ownership heading (with a durable
+  explicit anchor) and several translation fixes. `keys.py`'s `make_ref_key`
+  docstring and the pandas `UnsupportedElementTypeError` guidance message
+  were corrected to match reality (hash, not set; `decimal` included). The
+  README status badge now reads Beta, aligned with the packaging
+  classifier `Development Status :: 4 - Beta`.
+
+## [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.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: gpdatacached
-Version: 0.1.0
+Version: 0.2.1
 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
@@ -41,7 +41,7 @@ Description-Content-Type: text/markdown
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
-[![Development Status](https://img.shields.io/badge/status-alpha-orange.svg)](https://pypi.org/project/gpdatacached/)
+[![Development Status](https://img.shields.io/badge/status-beta-blue.svg)](https://pypi.org/project/gpdatacached/)
 
 A Redis-based **cross-process data sharing and caching** library for Python. Any process that can reach the same Redis instance can share live, mutable, typed data structures — scalars, lists, dicts, sets — with reference semantics, lifecycle control, and optional distributed locking.
 
@@ -53,12 +53,13 @@ A Redis-based **cross-process data sharing and caching** library for Python. Any
 
 Sharing mutable state across processes is painful. `multiprocessing.Manager` is single-process-bottlenecked; raw Redis forces you to (de)serialize everything by hand and gives you no type safety, no reference tracking, no TTL cascades. `gpdatacached` gives you a dict-like API on top of Redis with:
 
-- **Typed objects** — store `int`, `str`, `datetime`, `list`, `dict`, `set`, … and get the same type back.
+- **Typed objects** — store `int`, `decimal.Decimal`, `str`, `datetime`, `list`, `dict`, `set`, … and get the same type back.
 - **Live containers** — `ns["tags"].append("x")` mutates Redis directly; no read-modify-write races on the whole structure.
 - **Reference sharing** — bind the same container under multiple names inside a namespace; the data is stored once.
 - **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.
@@ -104,7 +105,7 @@ assert ns["tags"].value == ["b", "c", "d"]
 
 # Lifecycle control.
 ns["temp"] = "x"
-ns.get_object("temp").expire_in(60)   # requires cache_mode="ttl"
+ns.get_object("temp").update_cache_mode_and_ttl("ttl", 60)   # permanent → ttl, expires in 60s
 
 domain.close()
 ```
@@ -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.1}/README.md

@@ -4,7 +4,7 @@
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
-[![Development Status](https://img.shields.io/badge/status-alpha-orange.svg)](https://pypi.org/project/gpdatacached/)
+[![Development Status](https://img.shields.io/badge/status-beta-blue.svg)](https://pypi.org/project/gpdatacached/)
 
 A Redis-based **cross-process data sharing and caching** library for Python. Any process that can reach the same Redis instance can share live, mutable, typed data structures — scalars, lists, dicts, sets — with reference semantics, lifecycle control, and optional distributed locking.
 
@@ -16,12 +16,13 @@ A Redis-based **cross-process data sharing and caching** library for Python. Any
 
 Sharing mutable state across processes is painful. `multiprocessing.Manager` is single-process-bottlenecked; raw Redis forces you to (de)serialize everything by hand and gives you no type safety, no reference tracking, no TTL cascades. `gpdatacached` gives you a dict-like API on top of Redis with:
 
-- **Typed objects** — store `int`, `str`, `datetime`, `list`, `dict`, `set`, … and get the same type back.
+- **Typed objects** — store `int`, `decimal.Decimal`, `str`, `datetime`, `list`, `dict`, `set`, … and get the same type back.
 - **Live containers** — `ns["tags"].append("x")` mutates Redis directly; no read-modify-write races on the whole structure.
 - **Reference sharing** — bind the same container under multiple names inside a namespace; the data is stored once.
 - **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.
@@ -67,7 +68,7 @@ assert ns["tags"].value == ["b", "c", "d"]
 
 # Lifecycle control.
 ns["temp"] = "x"
-ns.get_object("temp").expire_in(60)   # requires cache_mode="ttl"
+ns.get_object("temp").update_cache_mode_and_ttl("ttl", 60)   # permanent → ttl, expires in 60s
 
 domain.close()
 ```
@@ -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.1}/README.zh-CN.md

@@ -4,7 +4,7 @@
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
-[![Development Status](https://img.shields.io/badge/status-alpha-orange.svg)](https://pypi.org/project/gpdatacached/)
+[![Development Status](https://img.shields.io/badge/status-beta-blue.svg)](https://pypi.org/project/gpdatacached/)
 
 一个基于 Redis 的**跨进程数据共享与缓存** Python 库。任何能够访问同一 Redis 实例的进程，都可以共享活跃的、可变的、带类型的数据结构 —— 标量、list、dict、set —— 并具备引用语义、生命周期控制以及可选的分布式锁。
 
@@ -16,12 +16,13 @@
 
 跨进程共享可变状态一直很麻烦：`multiprocessing.Manager` 会形成单进程瓶颈；直接使用 Redis 又需要你手动序列化所有数据，且没有类型安全、没有引用追踪、没有 TTL 级联。`gpdatacached` 在 Redis 之上提供了一套类 dict 的 API，特性包括：
 
-- **带类型的对象** —— 存储 `int`、`str`、`datetime`、`list`、`dict`、`set` …，读取时得到相同类型。
+- **带类型的对象** —— 存储 `int`、`decimal.Decimal`、`str`、`datetime`、`list`、`dict`、`set` …，读取时得到相同类型。
 - **活跃容器** —— `ns["tags"].append("x")` 直接修改 Redis，避免对整个结构的“读-改-写”竞态。
 - **引用共享** —— 在同一 namespace 内，同一个容器可绑定到多个名称；数据仅存储一份。
 - **生命周期控制** —— 每个对象可设置 `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 值。
@@ -67,7 +68,7 @@ assert ns["tags"].value == ["b", "c", "d"]
 
 # 生命周期控制。
 ns["temp"] = "x"
-ns.get_object("temp").expire_in(60)   # 要求 cache_mode="ttl"
+ns.get_object("temp").update_cache_mode_and_ttl("ttl", 60)   # permanent → ttl，60 秒后过期
 
 domain.close()
 ```
@@ -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]"`。
 
 ---