simple-kvdb

Simple KVDB

一个轻量级的键值存储数据库，使用JSON文件格式存储数据。

特性

• 🚀 简单易用的API
• 📁 使用JSON文件存储，数据可读性强
• 🔒 线程安全
• ⚡ 轻量级，无外部依赖
• 🛡️ 自动备份和错误处理
• 📊 支持复杂数据类型

安装

pip install simple-kvdb

快速开始

基本使用

from simple_kvdb import KVDB

# 创建数据库实例
db = KVDB("my_database.json")

# 存储数据
db.set("user:1", {"name": "张三", "age": 25})
db.set("user:2", {"name": "李四", "age": 30})

# 获取数据
user = db.get("user:1")
print(user)  # {'name': '张三', 'age': 25}

# 检查键是否存在
if db.exists("user:1"):
    print("用户存在")

# 删除数据
db.delete("user:2")

# 获取所有键
all_keys = db.keys()
print(all_keys)  # ['user:1']

# 获取数据库大小
size = db.size()
print(f"数据库包含 {size} 个键值对")

高级功能

from simple_kvdb import KVDB

db = KVDB("advanced_db.json")

# 批量操作
db.set_many({
    "config:theme": "dark",
    "config:language": "zh-CN",
    "stats:visits": 1000
})

# 获取多个值
values = db.get_many(["config:theme", "config:language"])
print(values)  # {'config:theme': 'dark', 'config:language': 'zh-CN'}

# 条件查询
theme = db.get("config:theme", default="light")
print(theme)  # dark

# 原子操作
db.atomic_update("stats:visits", lambda x: x + 1)

# 清空数据库
db.clear()

# 导出数据
data = db.export()
print(data)  # {}

# 从字典导入数据
db.import_data({"key1": "value1", "key2": "value2"})

上下文管理器

from simple_kvdb import KVDB

# 使用上下文管理器确保数据安全保存
with KVDB("temp_db.json") as db:
    db.set("temp_key", "temp_value")
    # 退出时自动保存

API 参考

KVDB 类

初始化参数

• file_path (str): 数据库文件路径
• auto_save (bool): 是否自动保存，默认为 True
• backup_count (int): 备份文件数量，默认为 3

主要方法

• set(key, value): 设置键值对
• get(key, default=None): 获取值
• delete(key): 删除键值对
• exists(key): 检查键是否存在
• keys(): 获取所有键
• values(): 获取所有值
• items(): 获取所有键值对
• size(): 获取数据库大小
• clear(): 清空数据库
• save(): 手动保存数据
• load(): 重新加载数据
• backup(): 创建备份
• set_many(data): 批量设置
• get_many(keys): 批量获取
• atomic_update(key, func): 原子更新
• export(): 导出数据
• import_data(data): 导入数据

错误处理

from simple_kvdb import KVDB, KVDBError

try:
    db = KVDB("test.json")
    db.set("key", "value")
except KVDBError as e:
    print(f"数据库错误: {e}")

性能考虑

• 对于大量数据，建议定期调用 save() 方法
• 使用 auto_save=False 可以提高写入性能
• 对于频繁访问的数据，考虑使用缓存

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！