# Simple KVDB
一个轻量级的键值存储数据库，使用JSON文件格式存储数据。
## 特性
- 🚀 简单易用的API
- 📁 使用JSON文件存储，数据可读性强
- 🔒 线程安全
- ⚡ 轻量级，无外部依赖
- 🛡️ 自动备份和错误处理
- 📊 支持复杂数据类型
## 安装
```bash
pip install simple-kvdb
```
## 快速开始
### 基本使用
```python
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} 个键值对")
```
### 高级功能
```python
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"})
```
### 上下文管理器
```python
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)`: 导入数据
## 错误处理
```python
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！
Raw data
{
"_id": null,
"home_page": "https://github.com/yourusername/simple-kvdb",
"name": "simple-kvdb",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "database, key-value, json, storage, lightweight",
"author": "Your Name",
"author_email": "your.email@example.com",
"download_url": "https://files.pythonhosted.org/packages/2f/0e/012b9e8b843dd98d82bd186d8f83f8f779ec7bc7779f9ca526052d2ebf8e/simple_kvdb-1.0.0.tar.gz",
"platform": null,
"description": "# Simple KVDB\r\n\r\n\u4e00\u4e2a\u8f7b\u91cf\u7ea7\u7684\u952e\u503c\u5b58\u50a8\u6570\u636e\u5e93\uff0c\u4f7f\u7528JSON\u6587\u4ef6\u683c\u5f0f\u5b58\u50a8\u6570\u636e\u3002\r\n\r\n## \u7279\u6027\r\n\r\n- \ud83d\ude80 \u7b80\u5355\u6613\u7528\u7684API\r\n- \ud83d\udcc1 \u4f7f\u7528JSON\u6587\u4ef6\u5b58\u50a8\uff0c\u6570\u636e\u53ef\u8bfb\u6027\u5f3a\r\n- \ud83d\udd12 \u7ebf\u7a0b\u5b89\u5168\r\n- \u26a1 \u8f7b\u91cf\u7ea7\uff0c\u65e0\u5916\u90e8\u4f9d\u8d56\r\n- \ud83d\udee1\ufe0f \u81ea\u52a8\u5907\u4efd\u548c\u9519\u8bef\u5904\u7406\r\n- \ud83d\udcca \u652f\u6301\u590d\u6742\u6570\u636e\u7c7b\u578b\r\n\r\n## \u5b89\u88c5\r\n\r\n```bash\r\npip install simple-kvdb\r\n```\r\n\r\n## \u5feb\u901f\u5f00\u59cb\r\n\r\n### \u57fa\u672c\u4f7f\u7528\r\n\r\n```python\r\nfrom simple_kvdb import KVDB\r\n\r\n# \u521b\u5efa\u6570\u636e\u5e93\u5b9e\u4f8b\r\ndb = KVDB(\"my_database.json\")\r\n\r\n# \u5b58\u50a8\u6570\u636e\r\ndb.set(\"user:1\", {\"name\": \"\u5f20\u4e09\", \"age\": 25})\r\ndb.set(\"user:2\", {\"name\": \"\u674e\u56db\", \"age\": 30})\r\n\r\n# \u83b7\u53d6\u6570\u636e\r\nuser = db.get(\"user:1\")\r\nprint(user) # {'name': '\u5f20\u4e09', 'age': 25}\r\n\r\n# \u68c0\u67e5\u952e\u662f\u5426\u5b58\u5728\r\nif db.exists(\"user:1\"):\r\n print(\"\u7528\u6237\u5b58\u5728\")\r\n\r\n# \u5220\u9664\u6570\u636e\r\ndb.delete(\"user:2\")\r\n\r\n# \u83b7\u53d6\u6240\u6709\u952e\r\nall_keys = db.keys()\r\nprint(all_keys) # ['user:1']\r\n\r\n# \u83b7\u53d6\u6570\u636e\u5e93\u5927\u5c0f\r\nsize = db.size()\r\nprint(f\"\u6570\u636e\u5e93\u5305\u542b {size} \u4e2a\u952e\u503c\u5bf9\")\r\n```\r\n\r\n### \u9ad8\u7ea7\u529f\u80fd\r\n\r\n```python\r\nfrom simple_kvdb import KVDB\r\n\r\ndb = KVDB(\"advanced_db.json\")\r\n\r\n# \u6279\u91cf\u64cd\u4f5c\r\ndb.set_many({\r\n \"config:theme\": \"dark\",\r\n \"config:language\": \"zh-CN\",\r\n \"stats:visits\": 1000\r\n})\r\n\r\n# \u83b7\u53d6\u591a\u4e2a\u503c\r\nvalues = db.get_many([\"config:theme\", \"config:language\"])\r\nprint(values) # {'config:theme': 'dark', 'config:language': 'zh-CN'}\r\n\r\n# \u6761\u4ef6\u67e5\u8be2\r\ntheme = db.get(\"config:theme\", default=\"light\")\r\nprint(theme) # dark\r\n\r\n# \u539f\u5b50\u64cd\u4f5c\r\ndb.atomic_update(\"stats:visits\", lambda x: x + 1)\r\n\r\n# \u6e05\u7a7a\u6570\u636e\u5e93\r\ndb.clear()\r\n\r\n# \u5bfc\u51fa\u6570\u636e\r\ndata = db.export()\r\nprint(data) # {}\r\n\r\n# \u4ece\u5b57\u5178\u5bfc\u5165\u6570\u636e\r\ndb.import_data({\"key1\": \"value1\", \"key2\": \"value2\"})\r\n```\r\n\r\n### \u4e0a\u4e0b\u6587\u7ba1\u7406\u5668\r\n\r\n```python\r\nfrom simple_kvdb import KVDB\r\n\r\n# \u4f7f\u7528\u4e0a\u4e0b\u6587\u7ba1\u7406\u5668\u786e\u4fdd\u6570\u636e\u5b89\u5168\u4fdd\u5b58\r\nwith KVDB(\"temp_db.json\") as db:\r\n db.set(\"temp_key\", \"temp_value\")\r\n # \u9000\u51fa\u65f6\u81ea\u52a8\u4fdd\u5b58\r\n```\r\n\r\n## API \u53c2\u8003\r\n\r\n### KVDB \u7c7b\r\n\r\n#### \u521d\u59cb\u5316\u53c2\u6570\r\n\r\n- `file_path` (str): \u6570\u636e\u5e93\u6587\u4ef6\u8def\u5f84\r\n- `auto_save` (bool): \u662f\u5426\u81ea\u52a8\u4fdd\u5b58\uff0c\u9ed8\u8ba4\u4e3a True\r\n- `backup_count` (int): \u5907\u4efd\u6587\u4ef6\u6570\u91cf\uff0c\u9ed8\u8ba4\u4e3a 3\r\n\r\n#### \u4e3b\u8981\u65b9\u6cd5\r\n\r\n- `set(key, value)`: \u8bbe\u7f6e\u952e\u503c\u5bf9\r\n- `get(key, default=None)`: \u83b7\u53d6\u503c\r\n- `delete(key)`: \u5220\u9664\u952e\u503c\u5bf9\r\n- `exists(key)`: \u68c0\u67e5\u952e\u662f\u5426\u5b58\u5728\r\n- `keys()`: \u83b7\u53d6\u6240\u6709\u952e\r\n- `values()`: \u83b7\u53d6\u6240\u6709\u503c\r\n- `items()`: \u83b7\u53d6\u6240\u6709\u952e\u503c\u5bf9\r\n- `size()`: \u83b7\u53d6\u6570\u636e\u5e93\u5927\u5c0f\r\n- `clear()`: \u6e05\u7a7a\u6570\u636e\u5e93\r\n- `save()`: \u624b\u52a8\u4fdd\u5b58\u6570\u636e\r\n- `load()`: \u91cd\u65b0\u52a0\u8f7d\u6570\u636e\r\n- `backup()`: \u521b\u5efa\u5907\u4efd\r\n- `set_many(data)`: \u6279\u91cf\u8bbe\u7f6e\r\n- `get_many(keys)`: \u6279\u91cf\u83b7\u53d6\r\n- `atomic_update(key, func)`: \u539f\u5b50\u66f4\u65b0\r\n- `export()`: \u5bfc\u51fa\u6570\u636e\r\n- `import_data(data)`: \u5bfc\u5165\u6570\u636e\r\n\r\n## \u9519\u8bef\u5904\u7406\r\n\r\n```python\r\nfrom simple_kvdb import KVDB, KVDBError\r\n\r\ntry:\r\n db = KVDB(\"test.json\")\r\n db.set(\"key\", \"value\")\r\nexcept KVDBError as e:\r\n print(f\"\u6570\u636e\u5e93\u9519\u8bef: {e}\")\r\n```\r\n\r\n## \u6027\u80fd\u8003\u8651\r\n\r\n- \u5bf9\u4e8e\u5927\u91cf\u6570\u636e\uff0c\u5efa\u8bae\u5b9a\u671f\u8c03\u7528 `save()` \u65b9\u6cd5\r\n- \u4f7f\u7528 `auto_save=False` \u53ef\u4ee5\u63d0\u9ad8\u5199\u5165\u6027\u80fd\r\n- \u5bf9\u4e8e\u9891\u7e41\u8bbf\u95ee\u7684\u6570\u636e\uff0c\u8003\u8651\u4f7f\u7528\u7f13\u5b58\r\n\r\n## \u8bb8\u53ef\u8bc1\r\n\r\nMIT License\r\n\r\n## \u8d21\u732e\r\n\r\n\u6b22\u8fce\u63d0\u4ea4 Issue \u548c Pull Request\uff01 \r\n",
"bugtrack_url": null,
"license": null,
"summary": "\u4e00\u4e2a\u8f7b\u91cf\u7ea7\u7684\u952e\u503c\u5b58\u50a8\u6570\u636e\u5e93\uff0c\u4f7f\u7528JSON\u6587\u4ef6\u683c\u5f0f",
"version": "1.0.0",
"project_urls": {
"Bug Reports": "https://github.com/yourusername/simple-kvdb/issues",
"Homepage": "https://github.com/yourusername/simple-kvdb",
"Source": "https://github.com/yourusername/simple-kvdb"
},
"split_keywords": [
"database",
" key-value",
" json",
" storage",
" lightweight"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1ac01effe2954f7146988e8ce20dcc691a72b57bed22c7267b1f5bee7acc50bb",
"md5": "e74194a143ccb5d8d68002cbd617473d",
"sha256": "953ff6268a93104119db464dce693febcc3ded626bb9e350111b586383f8ee78"
},
"downloads": -1,
"filename": "simple_kvdb-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e74194a143ccb5d8d68002cbd617473d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 9521,
"upload_time": "2025-07-18T06:35:50",
"upload_time_iso_8601": "2025-07-18T06:35:50.075315Z",
"url": "https://files.pythonhosted.org/packages/1a/c0/1effe2954f7146988e8ce20dcc691a72b57bed22c7267b1f5bee7acc50bb/simple_kvdb-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2f0e012b9e8b843dd98d82bd186d8f83f8f779ec7bc7779f9ca526052d2ebf8e",
"md5": "fbb2ef99f699eec38b2a85107e074ddc",
"sha256": "e693d4d22270b4e2ea346b434730f5200bffcc67fdb5a86900b7b1a9d34c1e8d"
},
"downloads": -1,
"filename": "simple_kvdb-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "fbb2ef99f699eec38b2a85107e074ddc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 12038,
"upload_time": "2025-07-18T06:35:51",
"upload_time_iso_8601": "2025-07-18T06:35:51.662959Z",
"url": "https://files.pythonhosted.org/packages/2f/0e/012b9e8b843dd98d82bd186d8f83f8f779ec7bc7779f9ca526052d2ebf8e/simple_kvdb-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-18 06:35:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yourusername",
"github_project": "simple-kvdb",
"github_not_found": true,
"lcname": "simple-kvdb"
}
JSON
