gpdatacached 0.2.0__tar.gz → 0.3.0__tar.gz

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

@@ -192,6 +192,9 @@ __marimo__/
 draft/
 dev_docs/
 
+# Agent demo scripts (runnable demos for review/verification workflows)
+demos/
+
 # user progress
 PROGRESS.md
 progress.md

{gpdatacached-0.2.0 → gpdatacached-0.3.0}/CHANGELOG.md

@@ -8,6 +8,94 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 GitHub Releases (with download artifacts) are published at
 <https://github.com/LinnetCodes/gpdatacached/releases>.
 
+## [0.3.0] — 2026-10-16
+
+### Added
+
+- **Dotted domain names via the `@` filename escape (`GPDataCache`)** —
+  domain names may now contain `.` end-to-end through the config-file path.
+  gpconfig addresses configs by dot-separated paths, so a `.` in a config
+  filename is consumed as a path separator and the file becomes
+  unaddressable; the new convention writes each `.` in a domain name as `@`
+  in the filename (chosen for its internet-address connotation — the natural
+  spelling when a domain mirrors an internet domain):
+  `domain_name@com.yaml` configures the domain `"domain_name.com"`, and
+  `cache.get_domain("domain_name.com")`, `name in cache`, and
+  `gpdc://domain_name.com/{ns}/{obj}[...]` URIs resolve it transparently.
+  The mapping is injective because `@` is not a legal character in GPDC
+  names. `GPDataCache.get_domain` now validates the requested name against
+  the GPDC domain-name rules (`ValueError` otherwise; URI resolution reports
+  the same case as `ObjectNotFoundByURIError`, and `has_uri` stays aligned).
+  `GPDCDomain`'s name resolution restores `@` → `.` for names derived from
+  a config-file stem (before the name-mismatch check), so gpconfig's
+  object factory path also constructs correctly-named domains:
+  `folder.get_object("domain_name@com")` yields the domain
+  `"domain_name.com"`, identical to `GPDataCache.get_domain(
+  "domain_name.com")`. An explicit `name=` argument containing `@` is
+  still rejected. The escape helpers (`DOMAIN_DOT_ESCAPE`,
+  `escape_domain_name`, `unescape_domain_name`) are exported from the
+  package root. **No gpconfig-side change is
+  needed or wanted** (owner ruling 2026-10-16): gpconfig keeps
+  `config.name` as the raw stem, preserving the
+  `config.name == addressable path component` invariant; a gpconfig-side
+  request (fail-fast validation of config filenames containing `.` at manager
+  init, plus a docs note) is recorded in
+  `dev_docs/issue-gpconfig-at-escape-in-config-names.md`); that request
+  has since landed in gpconfig 0.4.0.
+- **Startup warning for unaddressable config filenames** — `GPDataCache`
+  construction logs one warning per config file whose name contains a real
+  `.` (listed by `list_configs()` but never loadable by gpconfig's
+  dot-notation), suggesting the `@` spelling.
+
+### Fixed
+
+- `GPDataCache.__contains__` and `get_domain` no longer disagree for
+  config files whose stem contains `.` (previously `in` returned `True`
+  while `get_domain` raised `ConfigNotFoundError`; such files are now
+  warned about at construction and looked up only through valid names).
+
+## [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.
+
+### Changed
+
+- Require `gpconfig>=0.4.0` (was `>=0.3.0`, a version never published).
+  gpconfig 0.4.0 ships fail-fast validation of config filenames containing
+  `.` plus the `@`-convention documentation; gpdatacached's own
+  construction-time warning remains as defense for it.
+
+### 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

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: gpdatacached
-Version: 0.2.0
+Version: 0.3.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
@@ -20,7 +20,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
-Requires-Dist: gpconfig>=0.3.0
+Requires-Dist: gpconfig>=0.4.0
 Requires-Dist: pydantic>=2.0
 Requires-Dist: redis>=5.0
 Provides-Extra: dev
@@ -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,7 +53,7 @@ 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.
@@ -105,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()
 ```

{gpdatacached-0.2.0 → gpdatacached-0.3.0}/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,7 +16,7 @@ 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.
@@ -68,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()
 ```

{gpdatacached-0.2.0 → gpdatacached-0.3.0}/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,7 +16,7 @@
 
 跨进程共享可变状态一直很麻烦：`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`（滑动窗口）缓存模式，并将策略级联传播到所拥有的子树。
@@ -68,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()
 ```

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

@@ -110,6 +110,7 @@ folder = mgr.get_config("gpdc")        # -> GPConfigFolder; sample layouts in te
 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
+    site = cache.get_domain("domain_name.com")             # dotted name -> domain_name@com.yaml
 
     # 3. Resolve objects by GPDC URI — including anonymous nested objects.
     ns = domain.get_namespace("core_app")
@@ -202,7 +203,7 @@ Configuration for a `GPDCDomain`. All fields are validated; lock fields must be
 | `gc_lock_ttl_seconds` | `int` | `30` | TTL for locks acquired by GC (must be `≥ 1`). |
 | `gc_lock_wait_seconds` | `int` | `5` | GC per-object try-lock timeout (must be `≥ 0`). |
 
-👉 These four fields are consistent across every process that opens the same domain. See [Multi-Process Locking](./locking.md) for what each controls, the cost locks impose, and the GC contract.
+👉 These four fields must be kept consistent across every process that opens the same domain (mismatch raises `GPDCLockConfigInconsistentError` at domain construction). See [Multi-Process Locking](./locking.md) for what each controls, the cost locks impose, and the GC contract.
 
 ---
 
@@ -214,7 +215,7 @@ class GPDCNamespace(name, domain, *, config=None)   # MutableMapping
 
 A logical isolation space inside a `GPDCDomain`. Implements the full `MutableMapping` protocol backed by Redis.
 
-**Naming rule:** names may use letters, digits, `.` and `_`; names wrapped in `__xxx__` are reserved. Anonymous objects (internal names starting with `~`) are hidden from the public mapping API. Common characters that are **rejected** because they fall outside the allow-list (and, for `:`, collide with the Redis key separator): hyphen `-`, spaces, and `:` — use `_` or `.` instead.
+**Naming rule:** names may use letters, digits, `.` and `_`; names wrapped in `__xxx__` are reserved. Anonymous objects (internal names starting with `~`) are hidden from the public mapping API. Common characters that are **rejected** because they fall outside the allow-list (and, for `:`, collide with the Redis key separator): hyphen `-`, spaces, and `:` — use `_` or `.` instead. This rule applies to **object and namespace names**, and to **domain names** (a `.` in a domain name is legal everywhere in GPDC — but when the domain is driven by a config file through `GPDataCache`, the `.` must be spelled `@` in the filename; see the [`GPDataCache` `@` escape](#gpdatacache)).
 
 **Properties**
 
@@ -296,15 +297,34 @@ 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.
+folder reference only — **no domain is created** (it does scan the folder once
+to warn about unaddressable config filenames; see below). Domains are
+constructed lazily 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.
 
+> **Dots in domain names — the `@` escape.** gpconfig addresses configs by
+> dot-separated paths, so a `.` in a config filename is consumed as a path
+> separator and the file becomes unaddressable. To use a dotted domain name —
+> the natural shape when a domain mirrors an internet domain, e.g.
+> `domain_name.com` — write each `.` as `@` in the config filename:
+> `domain_name@com.yaml` configures the domain `"domain_name.com"`, and
+> `cache.get_domain("domain_name.com")` /
+> `cache.get_object_by_uri("gpdc://domain_name.com/ns/obj")` resolve it
+> transparently. The mapping is unambiguous because `@` is not a legal
+> character in GPDC names. `GPDCDomain` itself performs the `@` → `.`
+> restore for names derived from a config-file stem, so gpconfig's object
+> factory path also works: `folder.get_object("domain_name@com")`
+> constructs a domain named `domain_name.com`, identical to
+> `cache.get_domain("domain_name.com")`. An explicit `name=` argument
+> containing `@` is still rejected — the escape exists for filenames;
+> in code, write the `.` directly. Config files whose names contain a real `.` are
+> listed by the folder but can never be loaded; `GPDataCache` logs a warning
+> about them once at construction.
+
 > **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
@@ -312,7 +332,7 @@ domains use [`GPDCDomain`](#gpdcdomain) directly.
 
 **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.
+- `name in cache` → `True` iff a config for `name` exists in the folder (dotted names look up their `@`-escaped filename). 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. Names that are not legal GPDC domain names (e.g. containing `@`) return `False`. 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.
@@ -321,7 +341,7 @@ domains use [`GPDCDomain`](#gpdcdomain) directly.
 
 | 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_domain(name)` | Return the cached `GPDCDomain` for `name`, constructing it lazily on first access. Dotted names resolve to their `@`-escaped config file (see above). Raises `ValueError` if `name` is not a legal domain name; 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. |
@@ -370,9 +390,10 @@ For example, given `ns["cfg"] = {"port": 8080}`, `gpdc://d/ns/cfg/port` raises
 
 **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.
+three segments, empty segment), an invalid domain/namespace/object name (each
+locating segment is validated up front), 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"]}`:
 
@@ -395,7 +416,7 @@ 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
+an invalid domain/namespace/object name, 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
@@ -431,12 +452,14 @@ Abstract base class for every GPDC data object. Subclasses are split into [`GPDC
 |---|---|---|
 | `type` | `str` | GPDC type string, e.g. `"scalar:int"`, `"collection:list"`. |
 | `meta` | `ObjectMeta \| None` | Full metadata record; `None` if the object has vanished. |
-| `cache_mode` | `str` | Effective cache mode; raises `ObjectGoneError` if missing. |
+| `cache_mode` | `str` | Effective cache mode. |
 | `ttl` | `int` | Declared TTL in seconds (`0` = permanent). |
 | `created_at` | `datetime \| None` | Creation timestamp. |
 | `updated_at` | `datetime \| None` | Last update timestamp. |
 | `value` | `object` | The Python value (abstract; subclasses implement). |
 
+> The meta-backed properties (`cache_mode`, `ttl`, `created_at`, `updated_at`) each raise `ObjectGoneError` if the object's metadata no longer exists.
+
 **Lifecycle methods**
 
 > This is the API summary. For the full model — policy resolution, sliding refresh, ownership, anonymous/reference lifecycle, and pitfalls — see [Lifecycle Management](./lifecycle.md).
@@ -449,6 +472,7 @@ Abstract base class for every GPDC data object. Subclasses are split into [`GPDC
 | `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. |
+| `remaining_ttl()` | Remaining TTL in seconds on the canonical key, as reported by the Redis `TTL` command (`-1` = no expiry, `-2` = key missing). |
 | `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)
@@ -480,7 +504,7 @@ Base class for every scalar object. A scalar stores a single encoded value in it
 - `value` getter decodes the stored value via the registered codec.
 - `value` setter validates the Python type against the registered codec, updates metadata, and refreshes TTL when `cache_mode="sliding"`.
 
-Built-in subclasses: [`IntObject`](#intobject), [`FloatObject`](#floatobject), [`StrObject`](#strobject), [`BoolObject`](#boolobject), [`DateTimeObject`](#datetimeobject), [`DateObject`](#dateobject), [`TimeObject`](#timeobject), [`NoneObject`](#noneobject), [`TupleObject`](#tupleobject).
+Built-in subclasses: [`IntObject`](#intobject), [`FloatObject`](#floatobject), [`StrObject`](#strobject), [`BoolObject`](#boolobject), [`DateTimeObject`](#datetimeobject), [`DateObject`](#dateobject), [`TimeObject`](#timeobject), [`DecimalObject`](#decimalobject), [`NoneObject`](#noneobject), [`TupleObject`](#tupleobject).
 
 ---
 
@@ -526,6 +550,7 @@ All scalar classes inherit from [`GPDCScalarObject`](#gpdcscalarobject). Reading
 | [`DateTimeObject`](#datetimeobject) | `scalar:datetime` | `datetime.datetime` | `datetime:{isoformat}` |
 | [`DateObject`](#dateobject) | `scalar:date` | `datetime.date` (excludes `datetime`) | `date:{isoformat}` |
 | [`TimeObject`](#timeobject) | `scalar:time` | `datetime.time` | `time:{isoformat}` |
+| [`DecimalObject`](#decimalobject) | `scalar:decimal` | `decimal.Decimal` | `decimal:{str(d)}` |
 | [`NoneObject`](#noneobject) | `scalar:none` | `NoneType` | `none:None` |
 | [`TupleObject`](#tupleobject) | `scalar:tuple` | `tuple` (scalar elements only) | `tuple:{json}` |
 
@@ -557,6 +582,14 @@ Wraps `datetime.date`. Note: a `datetime.datetime` is rejected by `DateCodec` ev
 
 Wraps `datetime.time`.
 
+### `DecimalObject`
+
+Wraps `decimal.Decimal` (added in 0.2.1). Encoded as `decimal:{str(value)}`: the payload is `str(Decimal)`, which preserves the exact coefficient and exponent — `Decimal("1.10")` roundtrips as `1.10`, not `1.1`, and extreme exponents use scientific notation (`1E-27`). A malformed payload raises `ValueError` on decode.
+
+- **Non-finite values** (`NaN`, `sNaN`, `±Infinity`) and `-0` are stored and restored as-is, matching the `float` codec's treatment of `nan`/`inf`. Comparison semantics follow the standard library: `NaN != NaN`, and comparing an `sNaN` with `==` raises `decimal.InvalidOperation`.
+- **Exactness**: `str()` is context-independent — no rounding is applied on store or load. Construct from strings (`Decimal("0.1")`), not floats, if you mean the decimal literal; `Decimal(0.1)` faithfully stores the full binary expansion.
+- **Cross-type equality**: GPDC matches dict keys and set members by their encoded wire form, so natively-equal values of different numeric types become distinct entries once stored — `d[1] = "a"` followed by `d[Decimal(1)] = "b"` yields two entries (the same already holds for `1` vs `1.0`). A native literal like `{1: "a", Decimal(1): "b"}` collapses to one key before GPDC ever sees it.
+
 ### `NoneObject`
 
 Wraps `None`. Used to represent the presence of a `None` value distinctly from a missing key.
@@ -654,7 +687,7 @@ Abstract base for scalar codecs. Provides the shared helper:
 |---|---|
 | `_parse_encoded(encoded) -> tuple[str, str]` | Split a `name:payload` encoded value into `(type_name, raw)`. Raises `ValueError` on empty or colon-less input. |
 
-Built-in subclasses: `BoolCodec`, `DateTimeCodec`, `DateCodec`, `DictCodec` *(see note)*, `FloatCodec`, `IntCodec`, `ListCodec` *(see note)*, `NoneCodec`, `SetCodec` *(see note)*, `StrCodec`, `TimeCodec`, `TupleCodec`.
+Built-in subclasses: `BoolCodec`, `DateTimeCodec`, `DateCodec`, `DecimalCodec`, `DictCodec` *(see note)*, `FloatCodec`, `IntCodec`, `ListCodec` *(see note)*, `NoneCodec`, `SetCodec` *(see note)*, `StrCodec`, `TimeCodec`, `TupleCodec`.
 
 > Scalar codec classes for containers (`ListCodec`, `DictCodec`, `SetCodec`) are re-exported only for completeness — they actually inherit from [`GPDCContainerCodec`](#gpdccontainercodec).
 
@@ -749,6 +782,20 @@ def validate_object_name(name: str) -> None
 
 Validate that `name` contains only letters, digits, `.` or `_` and is not a reserved `__xxx__` name. Raises `ValueError` otherwise. (Equivalent validators exist internally for domain and namespace names.)
 
+### Domain-name `@` escape helpers
+
+```python
+DOMAIN_DOT_ESCAPE: str          # "@"
+
+def escape_domain_name(name: str) -> str
+    # "domain_name.com"  ->  "domain_name@com"   ('.' -> '@')
+
+def unescape_domain_name(stem: str) -> str
+    # "domain_name@com"  ->  "domain_name.com"   ('@' -> '.')
+```
+
+Helpers for the [`GPDataCache` `@` escape convention](#gpdatacache): gpconfig addresses configs by dot-separated paths, so a `.` in a domain config filename is unaddressable — each `.` in a domain name is written as `@` in the filename instead. The mapping is injective because `@` is not a legal character in GPDC names. `unescape_domain_name` is safe to apply to any stem-derived name for the same reason. You rarely need these directly — `GPDataCache` (lookup escaping) and `GPDCDomain` (load-time restore) apply them automatically.
+
 ---
 
 ## Exceptions
@@ -761,7 +808,7 @@ All public exceptions descend from the public `GPDCError(Exception)` root. Use `
 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.
+The root of the gpdatacached exception hierarchy. Every gpdatacached-specific exception raised by this library is a subclass of `GPDCError`, so `except GPDCError` is the broad catch-all. (Plain stdlib errors — e.g. `TypeError` for unsupported types or an invalid argument order, `ValueError` for invalid payloads — are raised as-is.) Prefer catching the specific subclass when you need to distinguish failure modes.
 
 ### `GPDCLockError`
 

{gpdatacached-0.2.0 → gpdatacached-0.3.0}/docs/en/extensibility.md

@@ -38,7 +38,7 @@ Two value families exist, with different contracts:
 
 ---
 
-## 2. The Registration Triple
+## 2. The Registration Entry
 
 Registering a type always means pairing four things via one call:
 
@@ -94,9 +94,10 @@ graph TD
     C1["GPDCScalarCodec"]
     C2["GPDCContainerCodec (ABC)"]
     C0 -->|encode_value / decode_value| C1
-    C0 -->|create_raw / read_raw / delete_raw| C2
 ```
 
+Two **independent** roots: `GPDCCodec` (scalars) and `GPDCContainerCodec` (containers) are siblings — a container codec never implements `encode_value`/`decode_value`.
+
 ### `GPDCCodec` — the root ABC
 
 ```python

{gpdatacached-0.2.0 → gpdatacached-0.3.0}/docs/en/lifecycle.md

@@ -194,7 +194,7 @@ graph TD
 
 ---
 
-## 7. The Ownership Model
+## 7. The Ownership Model { #7-the-ownership-model }
 
 Every object has an `owner` field in its metadata. Ownership determines who controls the object's lifecycle and is central to how anonymous objects work.
 
@@ -362,7 +362,7 @@ For reference, here is the complete set of user-facing lifecycle methods on `GPD
 | `take_ownership()` | Promote **the referenced object** to own itself (primary use case: a named reference to an anonymous nested object; a correct no-op on a reference to an already self-owned named object). |
 | `ttl` (property) | The declared TTL in seconds. |
 | `cache_mode` (property) | The current cache mode. |
-| `remaining_ttl()` | The actual remaining TTL reported by Redis (can be 0 or -1). |
+| `remaining_ttl()` | The actual remaining TTL reported by Redis (0; -1 = no expiry; -2 = key already gone). |
 | `created_at` / `updated_at` (properties) | Timestamps from metadata. |
 
 Plus the domain-level `domain.run_gc(namespace=None)` for manual GC.

{gpdatacached-0.2.0 → gpdatacached-0.3.0}/docs/en/overview.md

@@ -71,7 +71,7 @@ graph TD
     end
     subgraph L4["Layer 4 — Built-in types"]
         BREG["builtins.registry<br/>(auto-registered on import)"]
-        SCALARS["scalar types<br/>int·float·str·bool·datetime·date·time·none·tuple"]
+        SCALARS["scalar types<br/>int·float·decimal·str·bool·datetime·date·time·none·tuple"]
         CONTAINERS["container types<br/>list·dict·set"]
     end
     subgraph L3["Layer 3 — Type system"]
@@ -92,7 +92,7 @@ graph TD
         EXC["exceptions"]
     end
     REDIS[("Redis")]
-    L5 --> L4
+    L5 --> L3
     L4 --> L3
     L3 --> L2
     L3 --> L1

{gpdatacached-0.2.0 → gpdatacached-0.3.0}/docs/en/pandas-support.md

@@ -38,7 +38,7 @@ Two corollaries:
 |---|---|
 | **Row indexes** | `RangeIndex` (default int index, stored compactly) **and** any labelled index including `pd.MultiIndex` (stored one `collection:list` child per level). `.index_names` always returns a tuple. |
 | **DataFrame columns** | Single-level (scalar names) **or** `pd.MultiIndex` (tuple names). The row and column axes are independent and compose (a DataFrame may have both a row and a column MultiIndex). |
-| **Value dtypes** | `int64`/`Int64`, `float64`/`Float64`, `bool`/`boolean`, `str`/`string`, `object`, `datetime64` (naive & tz-aware), `category`. |
+| **Value dtypes** | Integer / float / boolean dtypes of any width (e.g. `int64`/`Int64`, `float64`/`Float64`, `bool`/`boolean`), `str`/`string`, `object` (any scalar-encodable element — including `decimal.Decimal`, builtin since 0.2.1), `datetime64` (naive & tz-aware, any unit), `category`. |
 | **Mutation** | Row `extend` (Series & DataFrame); DataFrame column `__setitem__` / `__delitem__` (structural add/replace/drop). |
 
 Notes:
@@ -185,7 +185,7 @@ GPDC type `collection:pandas_dataframe`. Backed by a Redis hash with column valu
 
 | Method | Description |
 |---|---|
-| `extend(other)` | Append rows in place. Accepts a `pd.DataFrame`, a `dict` of lists, or a list of `dict` rows. For a genuine MultiIndex-row DataFrame (`L ≥ 2`), only a `DataFrame` with a matching MultiIndex is accepted (dict/list inputs synthesise positional labels a MultiIndex cannot supply → `TypeError`; use `.value`). Mutates Redis; returns `None`. |
+| `extend(other)` | Append rows in place. Accepts a `pd.DataFrame`, a `dict` of lists, or a list of `dict` rows. For a genuine MultiIndex-row DataFrame (`L ≥ 2`), only a `DataFrame` with a matching MultiIndex is accepted (dict/list inputs synthesise positional labels a MultiIndex cannot supply → `TypeError`; use `.value`). Category columns reject values outside the stored categories (`ValueError`, raised before any Redis write). Mutates Redis; returns `None`. |
 | `deepcopy()` | Return a fully independent `pd.DataFrame` (`.value.copy(deep=True)`). |
 
 **Column-axis access (single-level columns)**
@@ -248,4 +248,4 @@ Raised when a DataFrame cannot be stored element-wise by `DataFrameObject`. The
 class UnsupportedElementTypeError(TypeError)
 ```
 
-Raised when a Series/DataFrame element is not encodable by a `GPDCScalarCodec` subclass — i.e. it is a container type (`list`/`dict`/`set`/container-registered pydantic model) or an unsupported type. Series/DataFrame elements must be scalar types encodable by a `GPDCScalarCodec` subclass. The message enumerates the allowed scalar types.
+Raised when a Series/DataFrame element is not encodable by a `GPDCScalarCodec` subclass — i.e. it is a container type (`list`/`dict`/`set`/container-registered pydantic model) or an unsupported type. Series/DataFrame elements must be scalar types encodable by a `GPDCScalarCodec` subclass. The message enumerates the allowed scalar types. Allowed builtin scalars (0.2.1+): int/float/bool/str/datetime/date/time/decimal/tuple/None, plus any scalar-registered custom type; object-dtype columns and index labels may hold any of them — including `decimal.Decimal`.

{gpdatacached-0.2.0 → gpdatacached-0.3.0}/docs/en/performance-guide.md

@@ -36,7 +36,7 @@ A quick reference. "RTT" = Redis round-trip. N = number of elements; counts are
 | `ns[k]` (scalar read) | O(1), ~3 RTT | `_resolve_binding` (`TYPE` + `HGETALL`) **plus** the scalar `.value` getter re-loads meta (`HGETALL`). |
 | `ns[k] = [a, b, c]` (flat, scalar-element container) | O(N) local encode, **O(1)** data-write RTT | One `encode_session` + one bulk `create_raw` (single `RPUSH`/`HSET`/`SADD` carrying all elements) + `HGET` ×2 (namespace-default policy) + metadata `HSET` + TTL applies on the obj/raw/ref keys (≈ 8 RTT total, independent of N for scalar elements). |
 | `ns[k] = [[...], ...]` (nested container) | O(**nested-container count**) RTT + O(N) local | Each nested container becomes one anonymous object (meta `HSET` + its own `create_raw` + `HINCRBY` ref + TTL applies ≈ 5–6 RTT each). Depth does **not** multiply — it is the total node count that scales. |
-| `container.append(x)` / `container[k] = v` (scalar element, non-sliding) | O(1), ~5–6 RTT | `HGETALL` (policy) + data write (`RPUSH`/`HSET`) + `_touch` (`LLEN`/`HLEN` + `HGETALL` + `HSET`). **Add the sliding-subtree walk if `cache_mode="sliding"`** (§3); **add ~5–6 RTT if the element is itself a container** (anonymous-object creation). |
+| `container.append(x)` / `container[k] = v` (scalar element, non-sliding) | O(1), ~5–6 RTT | `HGETALL` ×2 (liveness/policy + data-owner resolve) + data write (`RPUSH`/`HSET`) + `LLEN`/`HLEN` + metadata `HSET`. **Add the sliding-subtree walk if `cache_mode="sliding"`** (§3); **add ~5–6 RTT if the element is itself a container** (anonymous-object creation). |
 | `iter(ns)` / `len(ns)` | O(N), batched SCAN | A few RTT per ~100-key SCAN page (`len` delegates to `iter`). Don't put in a hot loop. |
 | `k in ns` | O(1), 1–4 RTT | Direct `TYPE` + `HGETALL` on the named key (1–2 RTT for owner bindings); references add a `GET` + another `TYPE` (up to 4 RTT for aliases). **Not** a SCAN. Does not scale with namespace size. |
 | `del ns[k]` (container owner) | O(owned subtree size) | `_teardown_owner_container` releases each nested ref (`HDEL`) and cascade-deletes orphaned anonymous children; ~1+ RTT per node. Raises `CanonicalObjectReferencedError` if live alias referrers exist — delete those first. |
@@ -48,7 +48,7 @@ A quick reference. "RTT" = Redis round-trip. N = number of elements; counts are
 | `.value` (full container read) | flat: 1 RTT + O(N) local; nested: +O(nested count) RTT | One bulk read (`LRANGE`/`HGETALL`/`SMEMBERS`); each `ref:` element adds one `HGETALL` + decode for its anonymous object. |
 | `name in cache` (`GPDataCache`) | **local, 0 RTT** | Pure config-snapshot check via `folder.list_configs()`. Does not touch Redis and does not construct a domain. The cheapest membership test in the library. |
 | `cache.get_domain(name)` | 1st call: domain construction (domain-meta read/verify); subsequent: **0 RTT** | First access constructs and caches the `GPDCDomain` via gpconfig's factory; later calls return the cached instance. Does not re-read config files. |
-| `cache.get_object_by_uri(uri)` | root: ~4–5 RTT; **+1 RTT per path segment** | `get_namespace` (`SISMEMBER` + namespace-meta `HGETALL`, ~2 RTT) + root resolve (`TYPE` + `HGETALL`, ~2–3 RTT). Each extra path segment is one `__getitem__` read (`LINDEX` for `ListObject`, `HGET` for `DictObject`). `cache.has_uri(uri)` has the same cost (it calls `get_object_by_uri` under a try/except). The domain is only constructed on the first access; later URIs in the same domain reuse the cached domain. |
+| `cache.get_object_by_uri(uri)` | root: ~4–5 RTT; **+1–2 RTT per path segment** | `get_namespace` (`SISMEMBER` + namespace-meta `HGETALL` + idempotent `SADD`, ~3 RTT) + root resolve (`TYPE` + `HGETALL`, ~2–3 RTT). Each extra path segment is one `__getitem__` read (ListObject: `LLEN` + `LINDEX` — 2 RTT; DictObject: `HGET` — 1 RTT). `cache.has_uri(uri)` has the same cost (it calls `get_object_by_uri` under a try/except). The domain is only constructed on the first access; later URIs in the same domain reuse the cached domain. |
 
 ---
 

{gpdatacached-0.2.0 → gpdatacached-0.3.0}/docs/en/pydantic-support.md

@@ -134,7 +134,7 @@ Stores the entire model as a single JSON-encoded Redis string. Reads return a fr
 
 The whole object is then stored as `{type_prefix}:{json}`, where `type_prefix` is the part of the GPDC type after `scalar:`.
 
-**Field type restriction.** Every field must be encodable by a `GPDCScalarCodec` subclass (int / float / bool / str / datetime / date / time / tuple / None / any scalar-registered custom type). Container field types (`list`, `dict`, `set`, container-registered pydantic models) raise `TypeError` at encode time — use container mode instead.
+**Field type restriction.** Every field must be encodable by a `GPDCScalarCodec` subclass (int / float / bool / str / datetime / date / time / decimal / tuple / None / any scalar-registered custom type). Container field types (`list`, `dict`, `set`, container-registered pydantic models) raise `TypeError` at encode time — use container mode instead.
 
 ### `PydanticModelScalarCodec`