asterstore

本地文件数据管理库
轻量读取 · 显式发布 · 可恢复治理

快速开始 · API · 示例 · 设计 · 参与贡献

数据仍然是普通文件。asterstore 为它们管理发布、保留与回收：哪些文件组成一次发布，哪些对象仍被任务使用，哪些残留可以清理。

框架负责生产数据，Polars、Arrow 等引擎负责读取和计算。asterstore 连接这些环节，核心无第三方运行依赖，也不依赖 Aster 或任何业务框架。

治理明确，读取轻量

• 发布有边界。 写入候选后显式提交，以原子切换使新发布可见；未变化的受管对象可以直接复用。
• 读取走短路径。 默认情况下，稳定状态打开当前发布只读两份控制记录；绑定后反复选择文件路径，不扫描目录、不逐文件预检、不计算内容哈希。
• 保留由任务决定。 需要的发布显式保留，使用完成后按引用版本释放；绑定或读取本身不产生保留记录。
• 回收可以恢复。 先预览，再按固定计划退役与删除；中断后沿原计划恢复，清理范围不扩大。

两种管理方式，同一套模型

两者共用 Declaration、Binding 和治理接口。登记外部文件不会改变其生产流程，也不会赋予库删除权。详见声明与资源绑定。

读、写和运维治理分开：读写可显式选择检查强度，默认 check="none"；全仓检查、数据集下线、数据回收和控制历史归档由调用方独立执行。检查开销发生在选定的阶段，Binding.files() 始终只做内存中的路径选择。

快速开始

需要 Python 3.11+，在你的 uv 项目中安装：

uv add asterstore
# 使用 Polars 接口时：
uv add 'asterstore[polars]'

本文以 0.3.0 为准，新增读写可选检查、候选盘点、控制历史归档和整批下线；0.2.0 不包含这些接口。从源码开发见贡献指南。

写入一次，显式发布。 将下面代码保存为 demo.py，运行 uv run python demo.py：

from asterstore import Repository

store = Repository("./demo-store")
store.initialize(
    resource_ids=["data"],
    managed_resource_id="data",
    lifecycle=True,
)

with store.prepare(
    "measurements",
    publication_id="run:1",
    operation_id="write:1",
    expected_generation=0,
) as writer:
    writer.write_bytes("readings", b"sensor,value\nA,21.5\n", relative_path="part.csv")
    writer.commit()

# 捕获这次发布的成员与路径，交给文件读取或数据引擎。
binding = store.open("measurements")
print(binding.files(keys=["readings"])[0].read_text())

operation_id 标识一次固定写入请求，expected_generation 用于检测并发更新。退出候选上下文不会自动提交；完整的复用与恢复流程见发布示例。

from asterstore import RetentionScope

held = store.governance.retain("analysis", "measurements", "run:1", scope=RetentionScope.OBJECTS)
try:
    inputs = store.governance.open("analysis", expected_revision=held.revision)
    print(inputs.files()[0].read_text())
finally:
    store.governance.release("analysis", expected_revision=held.revision)

使用 Polars，可在源码仓库中运行增量发布、延迟查询与回收的完整示例：

uv sync --locked --extra polars
uv run --locked --extra polars python examples/parquet.py

文档导航

项目状态

当前版本：0.3.0，新增可选读写检查、控制历史归档和整批数据集下线。已完成 Aster 真实分钟行情的本地受管接入，验证发布、增量复用、读取、保留与回收；详见接入验收。诊断与检查需要 0.2.0 或更高版本；实际发行状态以 PyPI 和 GitHub Release 为准。

当前验证范围为本地 Linux/POSIX；NFS 等共享挂载需要单独验证。核心以单个数据集发布为提交单位。0.3.0支持显式 控制历史压缩，保留原路径身份、历史和重试语义；不是自动后台任务。支持范围与后续工作见首版范围、路线图及格式边界。

Apache-2.0 · 变更记录 · 安全报告 · 问题反馈