gpdatacached 0.2.1__tar.gz → 0.3.0__tar.gz

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

@@ -8,6 +8,52 @@ 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
@@ -25,6 +71,13 @@ GitHub Releases (with download artifacts) are published at
   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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: gpdatacached
-Version: 0.2.1
+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

{gpdatacached-0.2.1 → 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")
@@ -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
@@ -761,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

{gpdatacached-0.2.1 → gpdatacached-0.3.0}/docs/zh/api.md

@@ -107,6 +107,7 @@ folder = mgr.get_config("gpdc")        # -> GPConfigFolder；示例布局见 tes
 with GPDataCache(folder) as cache:
     "core_domain" in cache                                  # 存在对应配置时为 True（不触碰 Redis）
     domain = cache.get_domain("core_domain")                # 惰性构造 + 缓存
+    site = cache.get_domain("domain_name.com")             # 带点名字 -> domain_name@com.yaml
 
     # 3. 通过 GPDC URI 解析对象 —— 包括匿名嵌套对象。
     ns = domain.get_namespace("core_app")
@@ -209,7 +210,7 @@ class GPDCNamespace(name, domain, *, config=None)   # MutableMapping
 
 `GPDCDomain` 内部的逻辑隔离空间，完整实现了由 Redis 支撑的 `MutableMapping` 协议。
 
-**命名规则：** 名称只能使用字母、数字、`.` 和 `_`；形如 `__xxx__` 的名称被保留。匿名对象（内部名称以 `~` 开头）不会出现在公开的映射 API 中。常见的**被拒绝**字符（不在允许清单内；且 `:` 还会与 Redis key 分隔符冲突）：连字符 `-`、空格、`:` —— 请改用 `_` 或 `.`。
+**命名规则：** 名称只能使用字母、数字、`.` 和 `_`；形如 `__xxx__` 的名称被保留。匿名对象（内部名称以 `~` 开头）不会出现在公开的映射 API 中。常见的**被拒绝**字符（不在允许清单内；且 `:` 还会与 Redis key 分隔符冲突）：连字符 `-`、空格、`:` —— 请改用 `_` 或 `.`。该规则适用于**对象名与 namespace 名**，也适用于 **domain 名**（domain 名中的 `.` 在 GPDC 内部处处合法 —— 但当 domain 由配置文件经 `GPDataCache` 驱动时，文件名中的 `.` 必须写作 `@`，见 [`GPDataCache` 的 `@` 转义](#gpdatacache)）。
 
 **属性**
 
@@ -286,15 +287,17 @@ class GPDataCache(folder: gpconfig.GPConfigFolder)   # 上下文管理器
 
 一个门面（facade），负责管理从 [`gpconfig`](https://github.com/linnetcodes/gpconfig) 的 `GPConfigFolder` 中发现的 `GPDCDomain` 实例，并将 GPDC URI 解析为 [`GPDCDataObject`](#gpdcdataobject) 实例。当你的 domain 由配置文件驱动、而非在代码中临时构造时，它是推荐的入口。
 
-**构造。** 基于 `GPConfigFolder` 构造。构造时只会保存该文件夹的引用 —— **不会创建任何 domain**。Domain 在首次通过 [`get_domain`](#gpdatacache) 访问时惰性构造（经由 gpconfig 的对象工厂 `folder.get_object(name)`），并缓存在一个内部 dict 中。该缓存是一个快照：构造之后被编辑的配置文件**不会**被重新读取；要应用变更需重建 `GPDataCache`。
+**构造。** 基于 `GPConfigFolder` 构造。构造时只会保存该文件夹的引用 —— **不会创建任何 domain**（但会扫描一次文件夹，对无法寻址的配置文件名发出告警，见下）。Domain 在首次通过 [`get_domain`](#gpdatacache) 访问时惰性构造，并缓存在一个内部 dict 中。该缓存是一个快照：构造之后被编辑的配置文件**不会**被重新读取；要应用变更需重建 `GPDataCache`。
 
 `GPDataCache` **不会**创建缺少配置文件的 domain —— 临时 domain 请直接使用 [`GPDCDomain`](#gpdcdomain)。
 
+> **Domain 名中的点号 —— `@` 转义。** gpconfig 以点分路径寻址配置，因此配置文件名中的 `.` 会被当作路径分隔符消费，该文件将无法被寻址。要使用带点的 domain 名 —— 当一个 domain 对应一个互联网域名时的自然形态，例如 `domain_name.com` —— 请在配置文件名中将每个 `.` 写作 `@`：`domain_name@com.yaml` 配置 domain `"domain_name.com"`，`cache.get_domain("domain_name.com")` / `cache.get_object_by_uri("gpdc://domain_name.com/ns/obj")` 会透明解析。该映射是无歧义的，因为 `@` 不是 GPDC 名称的合法字符。`GPDCDomain` 自身会对来自配置文件 stem 的名字做 `@` → `.` 还原，因此 gpconfig 的对象工厂路径同样可用：`folder.get_object("domain_name@com")` 构造出名为 `domain_name.com` 的 domain，与 `cache.get_domain("domain_name.com")` 完全一致。显式 `name=` 参数含 `@` 仍会被拒绝 —— 转义只服务于文件名，代码里直接写 `.` 即可。名字中含真实 `.` 的配置文件会被文件夹列出但永远无法加载；`GPDataCache` 在构造时会对这类文件记录一次告警。
+
 > **注册副作用。** `import gpdatacached` 会将 `GPDCDomain` 和 `GPDCDomainConfig` 注册到 gpconfig 的对象工厂（幂等），这正是 `folder.get_object(name)` 能够构造 `GPDCDomain` 的原因。无需额外设置。
 
 **支持的协议方法**
 
-- `name in cache` → 文件夹中存在名为 `name` 的配置时为 `True`。这是纯配置快照检查：**不**触碰 Redis，也不构造（或要求存在）`GPDCDomain` 实例 —— 答案只取决于配置文件是否存在，与是否调用过 `get_domain(name)` 无关。domain 实例在首次 `get_domain(name)` 访问时惰性创建。
+- `name in cache` → 文件夹中存在 `name` 的配置时为 `True`（带点的名字会查找其 `@` 转义后的文件名）。这是纯配置快照检查：**不**触碰 Redis，也不构造（或要求存在）`GPDCDomain` 实例 —— 答案只取决于配置文件是否存在，与是否调用过 `get_domain(name)` 无关。domain 实例在首次 `get_domain(name)` 访问时惰性创建。
 - `with cache as c` / `__exit__` → 退出时关闭所有已缓存的 domain；`close()` 是幂等的。
 
 > **`close()` 后的行为 —— 成员检查的例外。** `cache.close()` 之后，触碰资源的方法（`get_domain`、`get_object_by_uri`、`has_uri`）会抛 `RuntimeError("GPDataCache is closed")`。`name in cache` 成员检查是**故意的例外**：因为它只读配置快照、不触碰任何资源，所以在 `close()` 后仍然可用。这是有意为之 —— "这个 domain 是否有配置？" 这个问题与 cache 是否打开无关。
@@ -303,7 +306,7 @@ class GPDataCache(folder: gpconfig.GPConfigFolder)   # 上下文管理器
 
 | 方法 | 说明 |
 |---|---|
-| `get_domain(name)` | 返回 `name` 对应的已缓存 `GPDCDomain`，首次访问时惰性构造。若 `name` 无对应配置，则抛出 gpconfig 的 `ConfigNotFoundError`。`close()` 后抛 `RuntimeError`。 |
+| `get_domain(name)` | 返回 `name` 对应的已缓存 `GPDCDomain`，首次访问时惰性构造。带点的名字会解析到其 `@` 转义后的配置文件（见上）。`name` 不是合法 domain 名时抛 `ValueError`；无对应配置时抛出 gpconfig 的 `ConfigNotFoundError`。`close()` 后抛 `RuntimeError`。 |
 | [`get_object_by_uri(uri)`](#get_object_by_uri) | 将 GPDC URI 解析为 `GPDCDataObject`。`close()` 后抛 `RuntimeError`。 |
 | `has_uri(uri)` | 当 `get_object_by_uri(uri)` 会成功时返回 `True`。`close()` 后抛 `RuntimeError`。 |
 | `close()` | 关闭所有已缓存的 domain。幂等。 |
@@ -337,7 +340,7 @@ gpdc://{domain}/{namespace}/{name}[/{path_segment}...]
 
 **标量终结点会被拒绝。** 嵌套在容器内部的标量以内联值形式存储（而非作为被引用对象），因此深入到一个标量元素得到的是原生 Python 值。由于 `get_object_by_uri` 只返回对象，终止于标量的路径会抛出 `ObjectNotFoundByURIError`。例如，给定 `ns["cfg"] = {"port": 8080}`，`gpdc://d/ns/cfg/port` 会抛错（值 `8080` 是标量，而非数据对象）。
 
-**错误。** 每一种失败情况都会抛出 [`ObjectNotFoundByURIError`](#objectnotfoundbyurierror)（携带 `.uri` 和 `.reason`）：URI 格式错误（缺少 `gpdc://`、分段少于三段、存在空分段）、未知的 domain、缺少 namespace、缺少根对象、某个路径分段失败（`KeyError`/`IndexError`/`TypeError`），以及标量终结点。
+**错误。** 每一种失败情况都会抛出 [`ObjectNotFoundByURIError`](#objectnotfoundbyurierror)（携带 `.uri` 和 `.reason`）：URI 格式错误（缺少 `gpdc://`、分段少于三段、存在空分段）、非法的 domain/namespace/object 名（三个定位分段都会预先校验）、未知的 domain、缺少 namespace、缺少根对象、某个路径分段失败（`KeyError`/`IndexError`/`TypeError`），以及标量终结点。
 
 **示例。** 给定 `ns["cfg"] = {"server": {"host": "x"}, "tags": ["a","b"]}`：
 
@@ -357,7 +360,7 @@ gpdc://{domain}/{namespace}/{name}[/{path_segment}...]
 class ObjectNotFoundByURIError(GPDCError)
 ```
 
-当 GPDC URI 无法解析为 `GPDCDataObject` 时，由 [`GPDataCache.get_object_by_uri`](#get_object_by_uri) 抛出。涵盖所有失败情况：URI 语法格式错误、未知的 domain（无配置）、缺少 namespace、缺少根对象、某个路径分段失败，以及标量终结点。携带 `.uri`（URI 字符串）和 `.reason`（简短说明）。
+当 GPDC URI 无法解析为 `GPDCDataObject` 时，由 [`GPDataCache.get_object_by_uri`](#get_object_by_uri) 抛出。涵盖所有失败情况：URI 语法格式错误、非法的 domain/namespace/object 名、未知的 domain（无配置）、缺少 namespace、缺少根对象、某个路径分段失败，以及标量终结点。携带 `.uri`（URI 字符串）和 `.reason`（简短说明）。
 
 `has_uri` 只会吞掉这个异常；基础设施错误（如 Redis 连接失败）会继续向上传播。
 
@@ -719,6 +722,20 @@ def validate_object_name(name: str) -> None
 
 校验 `name` 仅包含字母、数字、`.` 或 `_`，且不是被保留的 `__xxx__` 名称。否则抛出 `ValueError`。（内部还存在等价的 domain 名称与 namespace 名称校验器。）
 
+### Domain 名 `@` 转义辅助函数
+
+```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"   ('@' -> '.')
+```
+
+[`GPDataCache` `@` 转义约定](#gpdatacache)的辅助函数：gpconfig 以点分路径寻址配置，因此 domain 配置文件名中的 `.` 无法被寻址 —— domain 名中的每个 `.` 在文件名中写作 `@`。由于 `@` 不是 GPDC 名称的合法字符，该映射是单射的；同理 `unescape_domain_name` 可安全地作用于任何 stem 来源的名字。通常无需直接使用 —— `GPDataCache`（寻址时转义）与 `GPDCDomain`（加载时还原）会自动应用。
+
 ---
 
 ## 异常

{gpdatacached-0.2.1 → gpdatacached-0.3.0}/pyproject.toml

@@ -21,7 +21,7 @@ classifiers = [
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]
 dependencies = [
-    "gpconfig>=0.3.0",
+    "gpconfig>=0.4.0",
     "pydantic>=2.0",
     "redis>=5.0",
 ]

{gpdatacached-0.2.1 → gpdatacached-0.3.0}/src/gpdatacached/__init__.py

@@ -2,7 +2,7 @@
 
 # Software library version (SemVer), tracks feature releases and bugfixes.
 # Independent of GPDC_PROTOCOL_VERSION in domain.py.
-__version__ = "0.2.1"
+__version__ = "0.3.0"
 
 from .codec import GPDCCodec, GPDCContainerCodec, GPDCScalarCodec
 from .config import GPDCDomainConfig, GPDCNamespaceConfig
@@ -17,7 +17,14 @@ from .exceptions import (
     ObjectNotFoundByURIError,
 )
 from .domain import GPDCDomain, reset_domain_config
-from .keys import make_uri, uri_to_redis_key, validate_object_name
+from .keys import (
+    DOMAIN_DOT_ESCAPE,
+    escape_domain_name,
+    make_uri,
+    unescape_domain_name,
+    uri_to_redis_key,
+    validate_object_name,
+)
 from .namespace import GPDCNamespace
 from .types import GPDCTypeRegistry
 from .object import GPDCDataObject
@@ -91,6 +98,9 @@ __all__ = [
     "GPDCContainerCodec",
     "GPDCScalarCodec",
     "GPDCTypeRegistry",
+    "DOMAIN_DOT_ESCAPE",
+    "escape_domain_name",
+    "unescape_domain_name",
     "validate_object_name",
     "make_uri",
     "uri_to_redis_key",

{gpdatacached-0.2.1 → gpdatacached-0.3.0}/src/gpdatacached/data_cache.py

@@ -8,10 +8,18 @@ from typing import TYPE_CHECKING
 from gpconfig import ConfigNotFoundError
 
 from .exceptions import ObjectNotFoundByURIError
+from .keys import (
+    DOMAIN_DOT_ESCAPE,
+    escape_domain_name,
+    validate_domain_name,
+    validate_namespace_name,
+    validate_object_name,
+)
 
 if TYPE_CHECKING:
     from gpconfig import GPConfigFolder
 
+    from .config import GPDCDomainConfig
     from .domain import GPDCDomain
     from .object import GPDCDataObject
 
@@ -21,9 +29,11 @@ logger = logging.getLogger(__name__)
 class GPDataCache:
     """Manage GPDCDomain instances from a GPConfigFolder and resolve GPDC URIs.
 
-    Domains are constructed lazily via gpconfig's object factory
-    (``folder.get_object(name)``) and cached. Construction happens on first
-    ``get_domain`` access; ``__init__`` does not create any domain.
+    Domain configs are loaded lazily on first ``get_domain`` access and
+    cached; ``__init__`` does not create any domain. Domain names may contain
+    '.' — gpconfig cannot address dotted filenames, so a '.' in a domain name
+    is written as '@' in its config file (``domain_name@com.yaml`` configures
+    domain ``"domain_name.com"``; see DOMAIN_DOT_ESCAPE).
 
     The cache is a snapshot: config files edited after construction are NOT
     re-read. Rebuild the GPDataCache to pick up changes.
@@ -38,29 +48,97 @@ class GPDataCache:
         self._folder = folder
         self._domains: dict[str, GPDCDomain] = {}
         self._closed = False
+        self._warn_dotted_config_stems()
+
+    def _warn_dotted_config_stems(self) -> None:
+        """Warn once about config stems containing '.' — they are unaddressable.
+
+        gpconfig's dot-notation consumes '.' as a path separator, so such a
+        file is listed by ``list_configs()`` but can never be loaded by name.
+        The '@' escape (DOMAIN_DOT_ESCAPE) is the supported way to spell a
+        dotted domain name in a filename.
+        """
+        try:
+            names = self._folder.list_configs()
+        except Exception:
+            # __init__ must stay side-effect-free relative to the folder; a
+            # broken listing will surface on first real use instead.
+            return
+        for name in names:
+            if "." in name:
+                logger.warning(
+                    "Config %r in config folder %r contains '.' and cannot be addressed "
+                    "by gpconfig's dot-notation; rename it to %r ('.' in a domain name "
+                    "is written as '%s' in the config filename).",
+                    name,
+                    self._folder.path,
+                    escape_domain_name(name),
+                    DOMAIN_DOT_ESCAPE,
+                )
 
     def __contains__(self, domain_name: object) -> bool:
         """Return True iff ``domain_name`` has a config in this folder.
 
         Pure config-snapshot check via ``folder.list_configs()``: does not
-        touch Redis and does not construct a GPDCDomain.
+        touch Redis and does not construct a GPDCDomain. The name is validated
+        and '@'-escaped first, so ``"domain_name.com" in cache`` matches the
+        config file ``domain_name@com.yaml``; names that are not legal GPDC
+        domain names (including any containing '@') return False.
         """
         if not isinstance(domain_name, str):
             return False
-        return domain_name in self._folder.list_configs()
+        try:
+            validate_domain_name(domain_name)
+        except ValueError:
+            return False
+        return escape_domain_name(domain_name) in self._folder.list_configs()
 
     def get_domain(self, domain_name: str) -> "GPDCDomain":
         """Return the cached GPDCDomain for ``domain_name``, creating it lazily.
 
-        Propagates gpconfig's ``ConfigNotFoundError`` if the domain has no
-        config file in this folder. GPDataCache does not create domains
-        without a config (use GPDCDomain directly for ad-hoc domains).
+        ``domain_name`` is validated against the GPDC name rules and
+        '@'-escaped for the config lookup (see DOMAIN_DOT_ESCAPE), so a
+        dotted domain name resolves to its '@'-escaped config file. The
+        config is loaded as GPDCDomainConfig and constructed directly —
+        GPDCDomain's own name resolution restores the '@'-escaped stem
+        (``domain_name@com``) to the real dotted name
+        (``domain_name.com``), so the same factory-built path via
+        ``folder.get_object("domain_name@com")`` yields an identically
+        named domain.
+
+        Raises ValueError for names that are not legal GPDC domain names,
+        and gpconfig's ``ConfigNotFoundError`` if the domain has no config
+        file in this folder. GPDataCache does not create domains without a
+        config (use GPDCDomain directly for ad-hoc domains).
         """
         self._check_open()
+        validate_domain_name(domain_name)
         if domain_name not in self._domains:
-            self._domains[domain_name] = self._folder.get_object(domain_name)
+            config = self._load_domain_config(domain_name)
+            # Imported lazily to keep this module decoupled from the
+            # package's import order (same rationale as _traverse).
+            from .domain import GPDCDomain
+
+            self._domains[domain_name] = GPDCDomain(config)
         return self._domains[domain_name]
 
+    def _load_domain_config(self, domain_name: str) -> "GPDCDomainConfig":
+        """Load the domain config for ``domain_name`` (via its '@'-escaped stem).
+
+        The config keeps its raw stem in ``config.name``; GPDCDomain's name
+        resolution performs the '@' -> '.' restore. Raises
+        ConfigNotFoundError when no config answers to the escaped name, or
+        when something other than a domain config does (e.g. a subfolder
+        shadows the config file).
+        """
+        from .config import GPDCDomainConfig
+
+        escaped = escape_domain_name(domain_name)
+        config = self._folder.get_config(escaped, config_cls=GPDCDomainConfig)
+        if not isinstance(config, GPDCDomainConfig):
+            raise ConfigNotFoundError(escaped, f"resolves to {type(config).__name__}, not a GPDCDomainConfig")
+        return config
+
     def get_object_by_uri(self, uri: str) -> "GPDCDataObject":
         """Resolve a GPDC URI to a GPDCDataObject.
 
@@ -72,8 +150,9 @@ class GPDataCache:
         terminates on a scalar value raises ObjectNotFoundByURIError.
 
         Raises ObjectNotFoundByURIError for every failure mode: malformed
-        URI, missing domain config, missing namespace, missing root object,
-        broken path, scalar terminal.
+        URI, invalid domain/namespace/object name, missing domain config,
+        missing namespace, missing root object, broken path, scalar
+        terminal.
         """
         self._check_open()
         domain_name, ns_name, obj_name, path_parts = self._parse_uri(uri)
@@ -88,17 +167,13 @@ class GPDataCache:
         try:
             ns = domain.get_namespace(ns_name)
         except KeyError as e:
-            raise ObjectNotFoundByURIError(
-                uri, f"namespace {ns_name!r} not found in domain {domain_name!r}"
-            ) from e
+            raise ObjectNotFoundByURIError(uri, f"namespace {ns_name!r} not found in domain {domain_name!r}") from e
 
         # Root object: get_object returns the object itself (not a value).
         try:
             root = ns.get_object(obj_name)
         except KeyError as e:
-            raise ObjectNotFoundByURIError(
-                uri, f"object {obj_name!r} not found in namespace {ns_name!r}"
-            ) from e
+            raise ObjectNotFoundByURIError(uri, f"object {obj_name!r} not found in namespace {ns_name!r}") from e
 
         # _traverse descends path_parts via __getitem__ (int-coercing ListObject
         # segments) and enforces the object-only terminal contract; with no
@@ -125,15 +200,30 @@ class GPDataCache:
         """Split a GPDC URI into (domain, namespace, name, path_parts)."""
         if not uri.startswith("gpdc://"):
             raise ObjectNotFoundByURIError(uri, "URI must start with 'gpdc://'")
-        rest = uri[len("gpdc://"):]
+        rest = uri[len("gpdc://") :]
         parts = rest.split("/")
         if len(parts) < 3:
-            raise ObjectNotFoundByURIError(
-                uri, "URI must have at least domain/namespace/name segments"
-            )
+            raise ObjectNotFoundByURIError(uri, "URI must have at least domain/namespace/name segments")
         if any(p == "" for p in parts):
             raise ObjectNotFoundByURIError(uri, "URI contains an empty segment")
         domain, ns_name, obj_name = parts[0], parts[1], parts[2]
+        # Validate all three locating segments up front so every URI failure
+        # mode surfaces as ObjectNotFoundByURIError: a ValueError from any
+        # downstream validator (e.g. namespace.get_object validates object
+        # names before its existence check) must not leak through
+        # get_object_by_uri, and has_uri relies on that contract. Path
+        # segments are NOT validated here — they are dict keys / list
+        # indices, and invalid ones fail traversal with KeyError/IndexError,
+        # which _traverse already wraps.
+        for label, segment, validator in (
+            ("domain", domain, validate_domain_name),
+            ("namespace", ns_name, validate_namespace_name),
+            ("object", obj_name, validate_object_name),
+        ):
+            try:
+                validator(segment)
+            except ValueError as e:
+                raise ObjectNotFoundByURIError(uri, f"invalid {label} name {segment!r}: {e}") from e
         path_parts = parts[3:]
         return domain, ns_name, obj_name, path_parts
 
@@ -164,16 +254,14 @@ class GPDataCache:
             if not hasattr(current, "__getitem__"):
                 raise ObjectNotFoundByURIError(
                     uri,
-                    f"path segment {part!r} cannot descend: "
-                    f"{current.canonical_uri} does not support subscript access",
+                    f"path segment {part!r} cannot descend: {current.canonical_uri} does not support subscript access",
                 )
             # Type-based key coercion (decision D9).
             if isinstance(current, ListObject):
                 if not part.isdigit():
                     raise ObjectNotFoundByURIError(
                         uri,
-                        f"path segment {part!r} invalid for ListObject: "
-                        f"must be a non-negative integer",
+                        f"path segment {part!r} invalid for ListObject: must be a non-negative integer",
                     )
                 key = int(part)
             else:
@@ -186,9 +274,7 @@ class GPDataCache:
                 ) from e
         # Terminal check: must be a GPDCDataObject, not a scalar value.
         if not isinstance(current, GPDCDataObject):
-            raise ObjectNotFoundByURIError(
-                uri, "terminal is a scalar value; get_object_by_uri returns objects only"
-            )
+            raise ObjectNotFoundByURIError(uri, "terminal is a scalar value; get_object_by_uri returns objects only")
         return current
 
     def close(self) -> None:

{gpdatacached-0.2.1 → gpdatacached-0.3.0}/src/gpdatacached/domain.py

@@ -15,6 +15,7 @@ from .keys import (
     make_domain_meta_key,
     make_domain_namespaces_key,
     make_namespace_meta_key,
+    unescape_domain_name,
     validate_domain_name,
 )
 
@@ -52,7 +53,22 @@ class GPDCDomain(GPConfigurable):
         # loaded from a file (== filename stem); it is "" for a programmatically
         # constructed config. Prefer config.name, fall back to the explicit name
         # argument, and reject a conflict between the two.
+        #
+        # A '@' in config.name is the filename escape for '.' (see
+        # keys.DOMAIN_DOT_ESCAPE): gpconfig's dot-notation cannot address
+        # dotted filenames, so domain_name@com.yaml spells the domain
+        # "domain_name.com". Restore it here — before the mismatch check and
+        # validation — so both gpconfig's object factory
+        # (folder.get_object("domain_name@com")) and GPDataCache construct the
+        # identically-named domain. The restore applies to any non-empty
+        # config.name (which for a file-loaded config IS the stem; a
+        # programmatically assigned name containing '@' is restored the same
+        # way — '@' cannot occur in a legal domain name, so this never alters
+        # an already-valid name). An explicit name= argument containing '@' is
+        # NOT restored and is rejected loudly by validate_domain_name below.
         config_name = config.name
+        if config_name:
+            config_name = unescape_domain_name(config_name)
         if name is not None and config_name:
             if name != config_name:
                 raise ValueError(

{gpdatacached-0.2.1 → gpdatacached-0.3.0}/src/gpdatacached/keys.py

@@ -112,6 +112,35 @@ def validate_namespace_name(name: str) -> None:
     _validate_name(name, "namespace name")
 
 
+DOMAIN_DOT_ESCAPE = "@"
+"""Escape for '.' in domain config filenames (internet-domain adaptation).
+
+gpconfig addresses configs by dot-separated paths, so a '.' in a config file
+stem is consumed as a path separator and the file becomes unaddressable
+(listed by ``list_configs`` but never found). A '@' in the stem instead
+stands for a literal '.' in the domain name: ``domain_name@com.yaml``
+configures the domain ``"domain_name.com"``. The '@' was chosen for its
+internet-address connotation (user@host); the mapping is injective because
+'@' is not a legal character in GPDC names, so two distinct domain names can
+never escape to the same filename.
+"""
+
+
+def escape_domain_name(name: str) -> str:
+    """Return the config-file form of a domain name ('.' -> '@')."""
+    return name.replace(".", DOMAIN_DOT_ESCAPE)
+
+
+def unescape_domain_name(stem: str) -> str:
+    """Return the domain name for a config-file stem ('@' -> '.').
+
+    Inverse of :func:`escape_domain_name`. Safe to apply unconditionally to
+    a stem-derived name: '@' cannot occur in a legal GPDC domain name, so
+    this never alters an already-valid name.
+    """
+    return stem.replace(DOMAIN_DOT_ESCAPE, ".")
+
+
 def collect_ref_names_from_raw(r, raw_key: str, raw_type: str) -> list[str]:
     """Scan a container's raw Redis data and return the names of all referenced objects.