Metadata-Version: 2.4
Name: simple-kvdb
Version: 1.0.0
Summary: 一个轻量级的键值存储数据库，使用JSON文件格式
Home-page: https://github.com/yourusername/simple-kvdb
Author: Your Name
Author-email: your.email@example.com
Project-URL: Bug Reports, https://github.com/yourusername/simple-kvdb/issues
Project-URL: Source, https://github.com/yourusername/simple-kvdb
Keywords: database,key-value,json,storage,lightweight
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0; extra == "dev"
Requires-Dist: black>=21.0; extra == "dev"
Requires-Dist: flake8>=3.8; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-python
Dynamic: summary

# 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！ 
