dataioc 0.1.0__tar.gz

dataioc-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+site/
+*.egg-info/

dataioc-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 dyuu7
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dataioc-0.1.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: dataioc
+Version: 0.1.0
+Summary: Declarative data dependency graphs for Python, resolved on demand with provider overrides.
+Project-URL: Documentation, https://dyuu7.github.io/dataioc/
+Project-URL: Issues, https://github.com/dyuu7/dataioc/issues
+Project-URL: Repository, https://github.com/dyuu7/dataioc
+Author: yanang007, dyuu7
+Maintainer: dyuu7
+License-Expression: MIT
+License-File: LICENSE
+Keywords: IoC,data dependencies,dependency graph,dependency injection,lazy evaluation,providers
+Classifier: Development Status :: 4 - Beta
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: typing-extensions>=4.10.0; python_version < '3.11'
+Provides-Extra: numpy
+Requires-Dist: numpy<3,>=1.26; extra == 'numpy'
+Description-Content-Type: text/markdown
+
+# dataioc
+
+**Declarative data dependency graphs for Python.**
+
+Each `DataDescriptor` names a quantity and defines how it is derived from its direct dependencies. `DataIoC` composes these local rules into a graph, then resolves and caches only the subgraph required by the result you request. Bind a provider to any quantity to replace that part of the graph without changing downstream calculations.
+
+[English](https://github.com/dyuu7/dataioc/blob/main/README.md) | [简体中文](https://github.com/dyuu7/dataioc/blob/main/README.zh-CN.md) | [Documentation](https://dyuu7.github.io/dataioc/) | [PyPI](https://pypi.org/project/dataioc/)
+
+[![CI](https://github.com/dyuu7/dataioc/actions/workflows/ci.yml/badge.svg)](https://github.com/dyuu7/dataioc/actions/workflows/ci.yml)
+
+## Example
+
+The raw readings `10`, `20`, and `60` represent measurements of `1`, `2`, and `6`.
+
+<img src="https://raw.githubusercontent.com/dyuu7/dataioc/main/docs/assets/data-flow.png" width="720" alt="By default, RawReadings are converted into Measurements. When a provider binds recorded data to Measurements, that default derivation is replaced while Statistics and Report remain unchanged." />
+
+```python
+from dataioc import DataDescriptor, DataIoC
+
+
+class RawReadings(DataDescriptor):
+    pass
+
+
+class Measurements(DataDescriptor):
+    def __build__(self, data):
+        return tuple(value / 10 for value in data[RawReadings])
+
+
+class Statistics(DataDescriptor):
+    def __build__(self, data):
+        values = data[Measurements]
+        return sum(values) / len(values), max(values)
+
+
+class Report(DataDescriptor):
+    def __build__(self, data):
+        mean, peak = data[Statistics]
+        return f"mean={mean:g}, peak={peak:g}"
+
+
+data = DataIoC().add(RawReadings, (10, 20, 60))
+assert data[Report] == "mean=3, peak=6"
+assert data[Measurements] is data[Measurements]
+```
+
+`data[Report]` is the only request the caller has to make. The container follows the dependencies and caches each value it builds.
+
+To use recorded measurements instead, bind a provider for `Measurements`:
+
+```python
+recorded = DataIoC().add_provider(Measurements, lambda _: (1.0, 2.0, 6.0))
+assert recorded[Report] == "mean=3, peak=6"
+```
+
+`RawReadings` is no longer needed; `Statistics` and `Report` stay as they are.
+
+## When it helps
+
+If both the inputs and the calculation path are fixed, ordinary function calls are simpler. Use `dataioc` when the relationships stay stable but a value may come from live measurements, recorded data, a simulation, or an estimate.
+
+`dataioc` grew out of [deinterf](https://github.com/dyuu7/deinterf). In its [direction-cosine example](https://github.com/dyuu7/deinterf/blob/main/examples/replace_direction_cosine_source_tmi.py), the same compensation terms work whether direction cosines are derived from magnetic-vector measurements or supplied by an INS estimate. [dvmss](https://github.com/dyuu7/dvmss) applies the pattern to simulation: supply the inputs, request `Tmi`, and let the container resolve the intermediate quantities.
+
+## Scope
+
+`dataioc` resolves data dependencies synchronously in the current process; it is not a workflow scheduler. Use a fresh container for each dataset or provider configuration. See [Core concepts](https://dyuu7.github.io/dataioc/concepts/) for caching, diagnostics, and other runtime limits.
+
+## Install
+
+```bash
+python -m pip install dataioc
+python -m pip install "dataioc[numpy]"
+```
+
+## Documentation
+
+- [Quickstart](https://dyuu7.github.io/dataioc/quickstart/): build a result from local dependency rules.
+- [Core concepts](https://dyuu7.github.io/dataioc/concepts/): understand descriptors, builders, caching, and failure behavior.
+- [Providers](https://dyuu7.github.io/dataioc/providers/): bind a quantity to another source or derivation.
+- [Indexed data](https://dyuu7.github.io/dataioc/indexed-data/): reuse one model across related data groups.
+- [NumPy](https://dyuu7.github.io/dataioc/numpy/): use array subclasses.
+- [API](https://dyuu7.github.io/dataioc/api/): look up interfaces.
+
+## Contributors
+
+[yanang007](https://github.com/yanang007) wrote the original container. [dyuu7](https://github.com/dyuu7) shaped the design, extracted it into `dataioc`, and maintains the project.
+
+[![Contributors](https://contrib.rocks/image?repo=dyuu7/dataioc)](https://github.com/dyuu7/dataioc/graphs/contributors)
+
+Licensed under the [MIT License](https://github.com/dyuu7/dataioc/blob/main/LICENSE).

dataioc-0.1.0/README.md

@@ -0,0 +1,90 @@
+# dataioc
+
+**Declarative data dependency graphs for Python.**
+
+Each `DataDescriptor` names a quantity and defines how it is derived from its direct dependencies. `DataIoC` composes these local rules into a graph, then resolves and caches only the subgraph required by the result you request. Bind a provider to any quantity to replace that part of the graph without changing downstream calculations.
+
+[English](https://github.com/dyuu7/dataioc/blob/main/README.md) | [简体中文](https://github.com/dyuu7/dataioc/blob/main/README.zh-CN.md) | [Documentation](https://dyuu7.github.io/dataioc/) | [PyPI](https://pypi.org/project/dataioc/)
+
+[![CI](https://github.com/dyuu7/dataioc/actions/workflows/ci.yml/badge.svg)](https://github.com/dyuu7/dataioc/actions/workflows/ci.yml)
+
+## Example
+
+The raw readings `10`, `20`, and `60` represent measurements of `1`, `2`, and `6`.
+
+<img src="https://raw.githubusercontent.com/dyuu7/dataioc/main/docs/assets/data-flow.png" width="720" alt="By default, RawReadings are converted into Measurements. When a provider binds recorded data to Measurements, that default derivation is replaced while Statistics and Report remain unchanged." />
+
+```python
+from dataioc import DataDescriptor, DataIoC
+
+
+class RawReadings(DataDescriptor):
+    pass
+
+
+class Measurements(DataDescriptor):
+    def __build__(self, data):
+        return tuple(value / 10 for value in data[RawReadings])
+
+
+class Statistics(DataDescriptor):
+    def __build__(self, data):
+        values = data[Measurements]
+        return sum(values) / len(values), max(values)
+
+
+class Report(DataDescriptor):
+    def __build__(self, data):
+        mean, peak = data[Statistics]
+        return f"mean={mean:g}, peak={peak:g}"
+
+
+data = DataIoC().add(RawReadings, (10, 20, 60))
+assert data[Report] == "mean=3, peak=6"
+assert data[Measurements] is data[Measurements]
+```
+
+`data[Report]` is the only request the caller has to make. The container follows the dependencies and caches each value it builds.
+
+To use recorded measurements instead, bind a provider for `Measurements`:
+
+```python
+recorded = DataIoC().add_provider(Measurements, lambda _: (1.0, 2.0, 6.0))
+assert recorded[Report] == "mean=3, peak=6"
+```
+
+`RawReadings` is no longer needed; `Statistics` and `Report` stay as they are.
+
+## When it helps
+
+If both the inputs and the calculation path are fixed, ordinary function calls are simpler. Use `dataioc` when the relationships stay stable but a value may come from live measurements, recorded data, a simulation, or an estimate.
+
+`dataioc` grew out of [deinterf](https://github.com/dyuu7/deinterf). In its [direction-cosine example](https://github.com/dyuu7/deinterf/blob/main/examples/replace_direction_cosine_source_tmi.py), the same compensation terms work whether direction cosines are derived from magnetic-vector measurements or supplied by an INS estimate. [dvmss](https://github.com/dyuu7/dvmss) applies the pattern to simulation: supply the inputs, request `Tmi`, and let the container resolve the intermediate quantities.
+
+## Scope
+
+`dataioc` resolves data dependencies synchronously in the current process; it is not a workflow scheduler. Use a fresh container for each dataset or provider configuration. See [Core concepts](https://dyuu7.github.io/dataioc/concepts/) for caching, diagnostics, and other runtime limits.
+
+## Install
+
+```bash
+python -m pip install dataioc
+python -m pip install "dataioc[numpy]"
+```
+
+## Documentation
+
+- [Quickstart](https://dyuu7.github.io/dataioc/quickstart/): build a result from local dependency rules.
+- [Core concepts](https://dyuu7.github.io/dataioc/concepts/): understand descriptors, builders, caching, and failure behavior.
+- [Providers](https://dyuu7.github.io/dataioc/providers/): bind a quantity to another source or derivation.
+- [Indexed data](https://dyuu7.github.io/dataioc/indexed-data/): reuse one model across related data groups.
+- [NumPy](https://dyuu7.github.io/dataioc/numpy/): use array subclasses.
+- [API](https://dyuu7.github.io/dataioc/api/): look up interfaces.
+
+## Contributors
+
+[yanang007](https://github.com/yanang007) wrote the original container. [dyuu7](https://github.com/dyuu7) shaped the design, extracted it into `dataioc`, and maintains the project.
+
+[![Contributors](https://contrib.rocks/image?repo=dyuu7/dataioc)](https://github.com/dyuu7/dataioc/graphs/contributors)
+
+Licensed under the [MIT License](https://github.com/dyuu7/dataioc/blob/main/LICENSE).

dataioc-0.1.0/README.zh-CN.md

@@ -0,0 +1,90 @@
+# dataioc
+
+**面向 Python 的声明式数据依赖图。**
+
+每个 `DataDescriptor` 代表一个数据量，并定义它如何由直接依赖推导。`DataIoC` 将这些局部规则组成计算图，只计算和缓存当前结果所需的子图。给任一数据量绑定 provider，就能替换图中的这一步，下游计算无需改动。
+
+[English](https://github.com/dyuu7/dataioc/blob/main/README.md) | [简体中文](https://github.com/dyuu7/dataioc/blob/main/README.zh-CN.md) | [文档](https://dyuu7.github.io/dataioc/zh/) | [PyPI](https://pypi.org/project/dataioc/)
+
+[![CI](https://github.com/dyuu7/dataioc/actions/workflows/ci.yml/badge.svg)](https://github.com/dyuu7/dataioc/actions/workflows/ci.yml)
+
+## 示例
+
+原始读数 `10`、`20`、`60` 分别表示测量值 `1`、`2`、`6`。
+
+<img src="https://raw.githubusercontent.com/dyuu7/dataioc/main/docs/assets/data-flow.png" width="720" alt="默认情况下，RawReadings 转换为 Measurements；当 provider 将历史数据绑定到 Measurements 时，这条默认推导被替换，而 Statistics 和 Report 保持不变。" />
+
+```python
+from dataioc import DataDescriptor, DataIoC
+
+
+class RawReadings(DataDescriptor):
+    pass
+
+
+class Measurements(DataDescriptor):
+    def __build__(self, data):
+        return tuple(value / 10 for value in data[RawReadings])
+
+
+class Statistics(DataDescriptor):
+    def __build__(self, data):
+        values = data[Measurements]
+        return sum(values) / len(values), max(values)
+
+
+class Report(DataDescriptor):
+    def __build__(self, data):
+        mean, peak = data[Statistics]
+        return f"mean={mean:g}, peak={peak:g}"
+
+
+data = DataIoC().add(RawReadings, (10, 20, 60))
+assert data[Report] == "mean=3, peak=6"
+assert data[Measurements] is data[Measurements]
+```
+
+调用方只需请求 `data[Report]`，容器会沿依赖关系完成其余计算，并缓存得到的值。
+
+如果这次要使用历史测量值，只需给 `Measurements` 注册另一个 provider：
+
+```python
+recorded = DataIoC().add_provider(Measurements, lambda _: (1.0, 2.0, 6.0))
+assert recorded[Report] == "mean=3, peak=6"
+```
+
+`RawReadings` 此时不再需要，`Statistics` 和 `Report` 都不用改。
+
+## 适用场景
+
+输入和计算过程都固定时，直接调用函数更简单。`dataioc` 适合关系稳定、数据来源会变的模型，例如同一个量在不同场景下来自实测、历史记录、仿真或估计。
+
+`dataioc` 最初来自 [deinterf](https://github.com/dyuu7/deinterf)：[方向余弦既可以根据磁矢量测量得到，也可以直接采用惯导估计](https://github.com/dyuu7/deinterf/blob/main/examples/replace_direction_cosine_source_tmi.py)，后面的补偿计算不用跟着改。[dvmss](https://github.com/dyuu7/dvmss) 也沿用这种组织方式：应用给出输入并请求 `Tmi`，中间量由容器补齐。
+
+## 范围
+
+`dataioc` 只负责在当前进程中同步解析数据依赖，不是工作流调度器。每组数据或 provider 配置应使用一个新容器。缓存、诊断和其他运行限制见[核心概念](https://dyuu7.github.io/dataioc/zh/concepts/)。
+
+## 安装
+
+```bash
+python -m pip install dataioc
+python -m pip install "dataioc[numpy]"
+```
+
+## 文档
+
+- [快速开始](https://dyuu7.github.io/dataioc/zh/quickstart/)：从局部依赖规则构建结果。
+- [核心概念](https://dyuu7.github.io/dataioc/zh/concepts/)：了解描述符、builder、缓存和失败行为。
+- [Provider](https://dyuu7.github.io/dataioc/zh/providers/)：将一个量绑定到另一种来源或推导方式。
+- [索引数据](https://dyuu7.github.io/dataioc/zh/indexed-data/)：让同一模型复用于多组相关数据。
+- [NumPy](https://dyuu7.github.io/dataioc/zh/numpy/)：使用数组子类。
+- [API](https://dyuu7.github.io/dataioc/zh/api/)：查询接口。
+
+## 贡献者
+
+[yanang007](https://github.com/yanang007) 编写了最初的容器实现。[dyuu7](https://github.com/dyuu7) 提出了这套设想，将其工程化以及抽取为 `dataioc`，并负责维护。
+
+[![贡献者](https://contrib.rocks/image?repo=dyuu7/dataioc)](https://github.com/dyuu7/dataioc/graphs/contributors)
+
+代码采用 [MIT License](https://github.com/dyuu7/dataioc/blob/main/LICENSE)。

dataioc-0.1.0/docs/api.md

@@ -0,0 +1,38 @@
+# API reference
+
+## Core
+
+::: dataioc.DataIoC
+    options:
+      members:
+        - with_data
+        - add
+        - add_provider
+        - __getitem__
+        - __setitem__
+        - find_builder
+        - logger
+      show_root_heading: true
+      show_source: false
+
+::: dataioc.DataDescriptor
+    options:
+      show_root_heading: true
+      show_source: false
+
+::: dataioc.IndexedData
+    options:
+      show_root_heading: true
+      show_source: false
+
+::: dataioc.UniqueData
+    options:
+      show_root_heading: true
+      show_source: false
+
+## NumPy
+
+::: dataioc.DataNDArray
+    options:
+      show_root_heading: true
+      show_source: false

dataioc-0.1.0/docs/api.zh.md

@@ -0,0 +1,38 @@
+# API 参考
+
+## 核心
+
+::: dataioc.DataIoC
+    options:
+      members:
+        - with_data
+        - add
+        - add_provider
+        - __getitem__
+        - __setitem__
+        - find_builder
+        - logger
+      show_root_heading: true
+      show_source: false
+
+::: dataioc.DataDescriptor
+    options:
+      show_root_heading: true
+      show_source: false
+
+::: dataioc.IndexedData
+    options:
+      show_root_heading: true
+      show_source: false
+
+::: dataioc.UniqueData
+    options:
+      show_root_heading: true
+      show_source: false
+
+## NumPy
+
+::: dataioc.DataNDArray
+    options:
+      show_root_heading: true
+      show_source: false

dataioc-0.1.0/docs/assets/data-flow.mmd

@@ -0,0 +1,34 @@
+---
+config:
+  theme: base
+  themeVariables:
+    fontFamily: monospace
+    fontSize: 24px
+    primaryColor: '#ffffff'
+    primaryTextColor: '#253039'
+    primaryBorderColor: '#7d8992'
+    lineColor: '#53616a'
+    background: '#ffffff'
+    clusterBkg: '#ffffff'
+    clusterBorder: '#aeb8bf'
+  flowchart:
+    htmlLabels: false
+    curve: linear
+    nodeSpacing: 24
+    rankSpacing: 32
+    padding: 12
+---
+flowchart TB
+    subgraph Default["Without a provider"]
+        direction LR
+        RawReadingsA[RawReadings] --> MeasurementsA[Measurements] --> StatisticsA[Statistics] --> ReportA[Report]
+    end
+    subgraph Replaced["With a provider bound to Measurements"]
+        direction LR
+        RecordedData[Recorded data] -->|"replaces default derivation"| MeasurementsB[Measurements] --> StatisticsB[Statistics] --> ReportB[Report]
+    end
+    classDef derived fill:#e1f3ed,stroke:#278668,stroke-width:2px
+    classDef source fill:#ffffff,stroke:#a26624,stroke-width:2px,stroke-dasharray:5 4
+    class MeasurementsA,MeasurementsB derived
+    class RecordedData source
+    linkStyle 3 stroke:#a26624,stroke-width:2px,color:#a26624

dataioc-0.1.0/docs/concepts.md

@@ -0,0 +1,94 @@
+# Core concepts
+
+`dataioc` separates three concerns: what a quantity means, how one implementation derives it, and which implementation a particular run uses. This is the data-oriented form of inversion of control.
+
+## A quantity is a stable key
+
+`DataDescriptor` identifies a value in the model. Its name can represent a domain concept such as raw readings, usable measurements, statistics, or a report.
+
+```python
+from dataioc import DataDescriptor, DataIoC
+
+
+class RawReadings(DataDescriptor[tuple[int, ...]]):
+    pass
+
+
+class Measurements(DataDescriptor[tuple[float, ...]]):
+    def __build__(self, container: DataIoC) -> tuple[float, ...]:
+        return tuple(value / 10 for value in container[RawReadings])
+
+
+class Statistics(DataDescriptor[tuple[float, float]]):
+    def __build__(self, container: DataIoC) -> tuple[float, float]:
+        values = container[Measurements]
+        return sum(values) / len(values), max(values)
+
+
+class Report(DataDescriptor[str]):
+    def __build__(self, container: DataIoC) -> str:
+        mean, peak = container[Statistics]
+        return f"mean={mean:g}, peak={peak:g}"
+```
+
+A descriptor is the container key, not the stored value itself. It may carry hashable parameters so that one descriptor class can identify related values. Do not mutate a descriptor after registration, because its parameters participate in equality and hashing.
+
+## A builder is a local rule
+
+A builder says how to obtain one quantity from its direct dependencies. In the example, `Report` knows about `Statistics`, but not about `Measurements` or `RawReadings`. Each lower layer owns the next relationship.
+
+A builder can be:
+
+- a `__build__` method on a descriptor or provider object;
+- a callable accepting one `DataIoC` argument;
+- a class with a suitable `__build__` method.
+
+Dependencies are requested with `container[Target]`. These requests are ordinary Python, so a builder can use conditions, loops, libraries, or existing domain objects.
+
+## Requests form the graph
+
+```python
+container = DataIoC().add(RawReadings, (10, 20, 60))
+assert container[Report] == "mean=3, peak=6"
+```
+
+Requesting `Report` forms and resolves `Report -> Statistics -> Measurements -> RawReadings`. The graph is implicit in the local rules and is expanded only as far as the requested result requires. Callers do not maintain a separate list of steps or execution order.
+
+This is an executable dependency model, not a workflow scheduler: evaluation is synchronous and local to one process.
+
+## Register values and implementations
+
+| Operation | Meaning |
+| --- | --- |
+| `with_data(*values)` | Register existing instances by type; indexed instances keep their descriptors |
+| `add(Target)` | Register the target's own lazy builder |
+| `add(Target, value)` | Register an existing value other than `None` |
+| `container[Target] = value` | Set a value directly, including an explicit `None` |
+| `add_provider(Target, provider)` | Bind the target to another builder |
+
+By default, the container discovers a target's own builder on first access. Strict mode requires every requested key to have data or a registered builder:
+
+```python
+strict = DataIoC(allow_implicit_registering=False)
+strict.add(Report).add(Statistics).add(Measurements)
+strict.add(RawReadings, (10, 20, 60))
+assert strict[Report] == "mean=3, peak=6"
+```
+
+`add(Target, None)` selects builder registration because `None` is the method's default argument. Use item assignment to store `None` as a value.
+
+See [Providers](providers.md) for choosing another implementation at container assembly time.
+
+## Container lifetime and cache
+
+Each successfully built key is cached, including a value of `None`. Repeated requests within one container therefore share the same result. Different indexed keys have separate cache entries; ordinary types and `UniqueData` are shared across IDs.
+
+A container represents one resolved dataset and provider configuration. Replacing a source or provider does not invalidate values already built from it. Use a fresh container when the inputs or bindings should produce fresh results.
+
+## Failure and diagnostics
+
+Failed builds are not cached; dependencies that completed successfully remain cached. A failed top-level build prints its dependency tree and re-raises the original exception. After supplying missing data or fixing the builder, the target can be requested again.
+
+Successful access trees are normally cleared. Set `record_all=True` to retain them in `container.logger`; see [Provider diagnostics](providers.md#diagnostics).
+
+The container does not provide thread safety, asynchronous construction, automatic dependent invalidation, or cycle detection.

dataioc-0.1.0/docs/concepts.zh.md

@@ -0,0 +1,94 @@
+# 核心概念
+
+`dataioc` 将三件事分开：一个量表示什么、某种实现如何推导它，以及本次运行选择哪种实现。这是控制反转在数据计算中的体现。
+
+## 数据量是稳定的键
+
+`DataDescriptor` 标识模型中的一个值。它的名称可以对应原始读数、可用的测量值、统计量或报告等领域概念。
+
+```python
+from dataioc import DataDescriptor, DataIoC
+
+
+class RawReadings(DataDescriptor[tuple[int, ...]]):
+    pass
+
+
+class Measurements(DataDescriptor[tuple[float, ...]]):
+    def __build__(self, container: DataIoC) -> tuple[float, ...]:
+        return tuple(value / 10 for value in container[RawReadings])
+
+
+class Statistics(DataDescriptor[tuple[float, float]]):
+    def __build__(self, container: DataIoC) -> tuple[float, float]:
+        values = container[Measurements]
+        return sum(values) / len(values), max(values)
+
+
+class Report(DataDescriptor[str]):
+    def __build__(self, container: DataIoC) -> str:
+        mean, peak = container[Statistics]
+        return f"mean={mean:g}, peak={peak:g}"
+```
+
+描述符是容器使用的键，不是存储的值本身。它可以携带可哈希参数，让同一个描述符类标识一组相关数据。注册后不要修改描述符，因为它的参数会参与相等比较和哈希计算。
+
+## Builder 是局部规则
+
+Builder 只说明如何从直接依赖得到一个量。在上面的例子中，`Report` 知道自己需要 `Statistics`，但不知道 `Measurements` 或 `RawReadings`。下一层关系分别由更下层的量负责。
+
+Builder 可以是：
+
+- 描述符或 provider 对象上的 `__build__` 方法；
+- 接收一个 `DataIoC` 参数的 callable；
+- 带有合适 `__build__` 方法的类。
+
+Builder 通过 `container[Target]` 请求依赖。这些请求仍然是普通 Python 代码，因此可以使用条件、循环、第三方库和已有领域对象。
+
+## 请求形成计算图
+
+```python
+container = DataIoC().add(RawReadings, (10, 20, 60))
+assert container[Report] == "mean=3, peak=6"
+```
+
+请求 `Report` 时，容器形成并解析 `Report -> Statistics -> Measurements -> RawReadings`。计算图隐含在各个局部规则中，并且只展开到当前结果所需要的范围。调用方无需另外维护步骤列表或执行顺序。
+
+这是一套可执行的依赖模型，而不是工作流调度器：求值是同步的，并且只发生在当前进程内。
+
+## 注册值和实现
+
+| 操作 | 含义 |
+| --- | --- |
+| `with_data(*values)` | 按类型注册已有实例；带索引的实例保留其描述符 |
+| `add(Target)` | 注册目标自身的 lazy builder |
+| `add(Target, value)` | 注册一个非 `None` 的已有值 |
+| `container[Target] = value` | 直接设置值，包括显式的 `None` |
+| `add_provider(Target, provider)` | 将目标绑定到另一个 builder |
+
+默认情况下，容器会在首次访问时发现目标自身的 builder。严格模式要求每个被请求的键已经提供数据或注册 builder：
+
+```python
+strict = DataIoC(allow_implicit_registering=False)
+strict.add(Report).add(Statistics).add(Measurements)
+strict.add(RawReadings, (10, 20, 60))
+assert strict[Report] == "mean=3, peak=6"
+```
+
+`add(Target, None)` 会选择注册 builder，因为 `None` 是该方法的默认参数。需要把 `None` 存为值时，使用下标赋值。
+
+如何在组装容器时选择另一种实现，详见 [Provider](providers.zh.md)。
+
+## 容器生命周期与缓存
+
+每个成功构建的键都会被缓存，包括值为 `None` 的情况。因此，同一个容器中的重复请求会共享结果。不同索引键有独立的缓存条目；普通类型和 `UniqueData` 则在各个 ID 之间共享。
+
+一个容器代表一组已经确定的数据与 provider 配置。替换来源或 provider 不会使已经构建的值失效。输入或绑定变化后需要重新计算时，使用新的容器。
+
+## 失败和诊断
+
+失败的构建不会被缓存，已经成功构建的依赖会保留。顶层构建失败时，容器打印依赖树，然后重新抛出原始异常。补充缺失数据或修正 builder 后，可以再次请求目标。
+
+成功的访问树默认会清除。设置 `record_all=True` 可以将它们保留在 `container.logger` 中，详见 [Provider 诊断](providers.zh.md)。
+
+容器不提供线程安全、异步构建、自动依赖失效或循环依赖检测。