Metadata-Version: 2.5
Name: flaxkv2
Version: 0.3.8
Summary: A high-performance dictionary database.
Project-URL: Homepage, https://github.com/KenyonY/flaxkv2
Project-URL: Documentation, https://github.com/KenyonY/flaxkv2#flaxkv2
Project-URL: Issues, https://github.com/KenyonY/flaxkv2/issues
Project-URL: Source, https://github.com/KenyonY/flaxkv2
Author-email: "K.Y" <beidongjiedeguang@gmail.com>
License-File: LICENSE
Keywords: Deep Learning,Machine Learning,lmdb,on-disk dict,persistent-storage
Classifier: Development Status :: 5 - Production/Stable
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: cryptography
Requires-Dist: fire
Requires-Dist: lmdb!=2.1.0,>=1.4.0
Requires-Dist: lz4
Requires-Dist: msgpack
Requires-Dist: numpy
Requires-Dist: psutil
Requires-Dist: pyzmq>=25.0.0
Requires-Dist: rich
Requires-Dist: tomli>=2.0.0; python_version < '3.11'
Provides-Extra: full
Requires-Dist: hnswlib>=0.7.0; extra == 'full'
Requires-Dist: pandas; extra == 'full'
Provides-Extra: migration
Requires-Dist: plyvel-ci>=1.5.0; (sys_platform == 'darwin') and extra == 'migration'
Requires-Dist: plyvel-ci>=1.5.0; (sys_platform == 'linux' and platform_machine == 'aarch64') and extra == 'migration'
Requires-Dist: plyvel-ci>=1.5.0; (sys_platform == 'win32') and extra == 'migration'
Requires-Dist: plyvel>=1.5.0; (sys_platform == 'linux' and platform_machine == 'x86_64') and extra == 'migration'
Provides-Extra: pandas
Requires-Dist: pandas; extra == 'pandas'
Provides-Extra: test
Requires-Dist: pandas; extra == 'test'
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-asyncio; extra == 'test'
Requires-Dist: pytest-cov; extra == 'test'
Requires-Dist: pytest-xdist; extra == 'test'
Provides-Extra: vector
Requires-Dist: hnswlib>=0.7.0; extra == 'vector'
Description-Content-Type: text/markdown

<div align="center">

# FlaxKV2

**Python 的字典接口，LMDB 的持久化存储。**

本地读写 · 跨进程共享 · 可选远程访问

[![Python](https://img.shields.io/badge/Python-3.10%2B-475569?style=flat-square)](pyproject.toml)
[![License](https://img.shields.io/badge/License-Apache_2.0-475569?style=flat-square)](LICENSE)

[快速开始](#快速开始) · [核心能力](#核心能力) · [远程访问](#远程访问) · [文档](#文档)

</div>

---

FlaxKV2 是一个面向 Python 的持久化键值存储库。使用熟悉的 `db[key] = value` 保存数据，
支持字典、列表、NumPy 数组和可选的 Pandas DataFrame。

适合本地缓存、数据处理的中间结果、任务状态和数组存储。本地模式直接读写 LMDB 文件，
多个进程可共享同一数据库；跨机器访问时，可以启用 ZeroMQ 服务。

## 快速开始

需要 Python 3.10 或更新版本。

```bash
pip install flaxkv2
```

```python
import numpy as np
from flaxkv2 import FlaxKV

with FlaxKV("app", "./data") as db:
    db["config"] = {"retries": 3, "timeout": 30}
    db["embedding"] = np.array([0.1, 0.2, 0.3], dtype=np.float32)

# 重新打开，继续读取之前保存的数据。
with FlaxKV("app", "./data") as db:
    print(db["config"]["retries"])   # 3
    print(db["embedding"].shape)     # (3,)
```

`with` 管理数据库的生命周期，退出时关闭数据库并刷新写缓冲。

按需安装扩展：

```bash
pip install 'flaxkv2[pandas]'     # Pandas DataFrame
pip install 'flaxkv2[vector]'     # hnswlib 向量索引
pip install 'flaxkv2[migration]'  # 旧版 LevelDB 数据迁移
```

`flaxkv2[full]` 包含 Pandas 和向量索引；Web UI 是独立包，见 [Inspector 指南](docs/INSPECTOR.md)。

## 核心能力

| 能力 | 用法 |
| --- | --- |
| 字典接口 | `get`、`update`、`pop`、`setdefault` 和批量读写 |
| 数据类型 | 内置类型与 NumPy 数组自动序列化；Pandas 按需安装 |
| 事务与隔离 | Named Sub-DB，以及同一 LMDB 环境内的跨库原子读写 |
| 过期与嵌套 | TTL、后台过期清理、嵌套字典和列表的局部更新 |
| 缓存与缓冲 | 可选读缓存、写缓冲，以及显式 `flush()` / `sync()` |
| 数据结构 | 持久化列表、FIFO 队列、时间序列和按时间分片的日志 |
| 远程与工具 | ZeroMQ、CurveZMQ 加密、LZ4 压缩、Inspector CLI 与独立 Web UI |

### 批量读写与范围迭代

```python
from flaxkv2 import FlaxKV

with FlaxKV("users", "./data") as db:
    db.update({"user:alice": {"score": 95}, "user:bob": {"score": 87}})
    scores = db.batch_get(["user:alice", "user:bob"])

    for key, value in db.items_iter(prefix="user:"):
        print(key, value)
```

迭代器支持 `prefix`、`start`、`stop` 和 `reverse`。使用 `*_iter()` 可避免一次加载全部值；
普通序列化模式下仍会收集键集合。排序和范围比较基于编码后的键字节，详见
[遍历与一致性](docs/design/TRANSACTIONS_AND_CONCURRENCY.md#4-遍历与一致性)。

### TTL 与嵌套更新

```python
from flaxkv2 import FlaxKV

with FlaxKV("sessions", "./data", default_ttl=3600) as db:
    db["session:alice"] = {"role": "editor"}
    db.set_ttl("session:alice", 300)

with FlaxKV("settings", "./data", auto_nested=True) as db:
    db["server"] = {"host": "localhost", "port": 8080}
    db["server"]["port"] = 9000
```

`auto_nested=True` 让字段独立存储，适合频繁修改大型对象的局部内容；默认关闭。

### 跨 Sub-DB 事务

同名数据库的多个 `sub_db` 共享一个 LMDB 环境。可以在一个事务中完成条件判断和写入：

```python
from flaxkv2 import FlaxKV, cross_db_txn

with (
    FlaxKV("service", "./data", sub_db="counters") as counters,
    FlaxKV("service", "./data", sub_db="grants") as grants,
):
    with cross_db_txn(counters, grants) as txn:
        used = txn.get(counters, "used", 0)
        if used < 10:
            txn.put(counters, "used", used + 1)
            txn.put(grants, f"slot:{used}", {"status": "reserved"})
```

本地字典的 `pop` / `setdefault` 也在单个事务内完成读写；远程版本不保证原子性。
事务内使用 `txn` 读写，不能跨 `await` 持有。大批量、可重放的事务可使用 `atomic_txn`，
详见[事务与并发原语](docs/design/TRANSACTIONS_AND_CONCURRENCY.md)。

## 持久化数据结构

沿用相同的名称、路径和上下文管理方式：

```python
from flaxkv2 import FlaxList

with FlaxList("events", "./data") as events:
    events.append({"type": "click", "user": "alice"})
    events.extend([{"type": "scroll"}, {"type": "submit"}])
    print(events[-1])
```

| 数据结构 | 适用场景 |
| --- | --- |
| `FlaxList` | 按索引访问、批量读写、排序、筛选和统计 |
| `FlaxQueue` | 持久化 FIFO、批量入队与出队、容量限制 |
| `FlaxTimeSeries` | 时间范围查询、聚合、降采样和保留策略 |
| `RotatingFlaxList` | 按小时或天分片，清理过期日志 |

更多示例见[数据结构指南](docs/DATA_STRUCTURES.md)。

## 远程访问

先在本机启动服务：

```bash
flaxkv2 run --port 5555 --data-dir ./data
```

再通过 URL 连接：

```python
from flaxkv2 import FlaxKV

with FlaxKV("shared", "tcp://127.0.0.1:5555") as db:
    db["status"] = {"ready": True}
    print(db["status"])
```

服务默认监听回环地址。跨机器访问需设置 `--host`，并配置加密认证或可信隧道，
见[密码认证指南](docs/development/PASSWORD_AUTH_GUIDE.md)。远程后端与本地后端的
事务和部分配置能力不同，不应直接互换这些保证。

Inspector 可以直接浏览本地数据库：

```bash
flaxkv2 inspect keys app --path ./data
flaxkv2 inspect get app config --path ./data
flaxkv2 inspect stats app --path ./data
```

## 性能与持久性

默认使用无缓存的 `RawLmdbDict`，LMDB 写事务提交时执行 fsync。
需要优化时，根据访问模式选择：

| 访问模式 | 配置方式 | 需要了解 |
| --- | --- | --- |
| 默认读写 | `FlaxKV("app", "./data")` | 无应用层写缓冲 |
| 批量写入 | `db.update(...)` 或 `atomic_txn` | 合并事务提交 |
| 持续写入 | `write_buffer_size=1000` | 缓冲中的数据尚未持久化 |
| 热点读取 | `CachedLmdbDict(..., enable_write_buffer=False)` | 开启读缓存，关闭写缓冲 |

```python
from flaxkv2 import CachedLmdbDict

with CachedLmdbDict(
    "cache", "./data", read_cache_size=10_000, enable_write_buffer=False
) as db:
    db["model:config"] = {"dimensions": 768}
    print(db["model:config"])
```

缓存容量按**条目数**计。`FlaxKV` 当前只传 `read_cache_size` 仍会附带写缓冲并发出
`FutureWarning`；仅需读缓存时使用上面的显式配置。读缓存会在检测到其他进程提交后失效。

开启写缓冲后，正常 `close()` 会刷新数据，进程崩溃仍会丢失未刷新的内容。
`flush()` 将缓冲写入 LMDB；`sync()` 在刷新后强制同步到磁盘。缓冲落盘失败时会抛出
`FlushError` 并保留缓冲数据。`sync` / `metasync` 是同一 LMDB 环境共享的配置，
`performance_profile` 只设置 `map_size` 和 `max_readers`。

性能数字受硬件、文件系统、数据大小和缓存状态影响。使用仓库中的脚本在目标环境测量：

```bash
python tests/benchmarks/benchmark_core.py
python tests/benchmarks/benchmark_durability.py
```

更多配置见[快速参考](docs/QUICK_REFERENCE.md)和[缓存设计](docs/UNIFIED_CACHE_DESIGN.md)。

## 信任边界

复杂对象可能使用 pickle 编解码，只应读取可信来源的数据库。远程客户端默认
`allow_pickle=False`，需要 pickle 的值会被拒绝；只有所有写入方可信时才应开启。

## 文档

| 从这里开始 | 深入了解 |
| --- | --- |
| [快速参考](docs/QUICK_REFERENCE.md) — 常用 API 与配置 | [架构设计](docs/design/ARCHITECTURE.md) — 后端与数据流 |
| [数据结构](docs/DATA_STRUCTURES.md) — 列表、队列、时间序列、日志 | [事务与并发](docs/design/TRANSACTIONS_AND_CONCURRENCY.md) — 原子性与实例生命周期 |
| [Inspector](docs/INSPECTOR.md) — CLI 与 Web UI | [Named Sub-DB](docs/design/NAMED_SUB_DB_DESIGN.md) — 存储隔离 |
| [配置文件](docs/CONFIG_FILE_GUIDE.md) — TOML 与配置优先级 | [键值编码](docs/design/KEY_VALUE_ENCODING_EXPLAINED.md) — 序列化格式 |
| [向量存储](docs/VECTOR_STORE.md) — hnswlib 索引 | [变更日志](docs/CHANGELOG.md) — 版本变化与迁移 |

完整目录见 [docs/README.md](docs/README.md)。

## 参与开发

安装、测试和提交说明见[贡献指南](CONTRIBUTING.md)。问题和功能建议可提交到
[GitHub Issues](https://github.com/KenyonY/flaxkv2/issues)。

FlaxKV2 基于 [LMDB](https://www.symas.com/lmdb)、[py-lmdb](https://github.com/jnwatson/py-lmdb)
和 [ZeroMQ](https://zeromq.org/)，采用 [Apache License 2.0](LICENSE)。
