Metadata-Version: 2.1
Name: pyadminkit
Version: 0.1.0
Summary: A lightweight and highly extensible Python admin system middleware
Home-page: https://github.com/pyadminkit/pyadminkit
Author: PyAdminKit Team
Author-email: PyAdminKit Team <admin@pyadminkit.com>
Maintainer-email: PyAdminKit Team <admin@pyadminkit.com>
License: MIT
Project-URL: Homepage, https://github.com/pyadminkit/pyadminkit
Project-URL: Documentation, https://pyadminkit.readthedocs.io/
Project-URL: Repository, https://github.com/pyadminkit/pyadminkit.git
Project-URL: Bug Reports, https://github.com/pyadminkit/pyadminkit/issues
Project-URL: Changelog, https://github.com/pyadminkit/pyadminkit/blob/main/CHANGELOG.md
Keywords: admin,dashboard,cms,management,database,orm,fastapi,flask,django,async,mysql,postgresql,sqlite,mongodb,crud,api,web,framework
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Database
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Office/Business
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Framework :: AsyncIO
Classifier: Framework :: FastAPI
Classifier: Framework :: Flask
Classifier: Framework :: Django
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0.0
Requires-Dist: typing-extensions>=4.0.0
Provides-Extra: mysql
Requires-Dist: aiomysql>=0.2.0; extra == "mysql"
Provides-Extra: postgresql
Requires-Dist: asyncpg>=0.28.0; extra == "postgresql"
Provides-Extra: sqlite
Requires-Dist: aiosqlite>=0.19.0; extra == "sqlite"
Provides-Extra: mongodb
Requires-Dist: motor>=3.3.0; extra == "mongodb"
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.100.0; extra == "fastapi"
Provides-Extra: flask
Requires-Dist: flask>=2.0.0; extra == "flask"
Provides-Extra: django
Requires-Dist: django>=4.0.0; extra == "django"
Provides-Extra: full
Requires-Dist: aiomysql>=0.2.0; extra == "full"
Requires-Dist: asyncpg>=0.28.0; extra == "full"
Requires-Dist: aiosqlite>=0.19.0; extra == "full"
Requires-Dist: motor>=3.3.0; extra == "full"
Requires-Dist: fastapi>=0.100.0; extra == "full"
Requires-Dist: flask>=2.0.0; extra == "full"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Requires-Dist: build>=0.10.0; extra == "dev"

# PyAdminKit

一个轻量级、高度可扩展的Python管理系统中间件，让开发者能够在几分钟内搭建起功能完整的后台管理系统。

## 🎯 特性

- **开箱即用** - 5分钟内搭建完整管理系统
- **多数据库支持** - PostgreSQL、MySQL、SQLite、MongoDB
- **异步支持** - 基于现代异步编程，高性能处理
- **类型安全** - 完整的类型提示支持
- **灵活查询** - 链式查询构建器和QuerySet
- **自动迁移** - 版本化数据库迁移管理
- **事务支持** - 完整的数据库事务功能

## 🚀 快速开始

### 安装

```bash
pip install pyadminkit
```

### 基本使用

```python
import asyncio
from datetime import datetime
from pyadminkit import db, BaseModel

# 定义模型
class User(BaseModel):
    __tablename__ = "users"
    
    id: int = None
    username: str
    email: str
    is_active: bool = True
    created_at: datetime = None

# 设置数据库并运行
async def main():
    # 连接数据库
    await db.set_default_database("sqlite:///app.db")
    
    # 注册模型
    db.register_model(User)
    
    # 运行迁移
    await db.migrate()
    
    # 创建用户
    user = User(username="alice", email="alice@example.com")
    await user.save()
    
    # 查询用户
    users = await User.find_all()
    print(f"找到 {len(users)} 个用户")

if __name__ == "__main__":
    asyncio.run(main())
```

## 📚 核心功能

### 1. 模型定义

```python
from pyadminkit import BaseModel
from datetime import datetime
from typing import Optional

class Product(BaseModel):
    __tablename__ = "products"
    
    id: Optional[int] = None
    name: str
    price: float
    category: str
    description: Optional[str] = None
    is_available: bool = True
    created_at: Optional[datetime] = None
```

### 2. 数据库操作

```python
# 创建记录
product = Product(name="笔记本", price=5999.99, category="电子产品")
await product.save()

# 查询记录
products = await Product.find_all()
product = await Product.find_by_id(1)
expensive_products = await Product.find_all(price__gt=1000)

# 更新记录
product.price = 4999.99
await product.save()

# 删除记录
await product.delete()
```

### 3. 复杂查询

```python
from pyadminkit import db

# 使用QuerySet进行复杂查询
products = await db.query(Product)\\
    .filter(category="电子产品")\\
    .filter(price__gt=1000)\\
    .order_by("-price")\\
    .limit(10)\\
    .all()

# 聚合查询
total_count = await db.query(Product).count()
avg_price = await db.raw_query("SELECT AVG(price) FROM products")
```

### 4. 事务支持

```python
async with db.transaction():
    user = User(username="bob", email="bob@example.com")
    await user.save()
    
    product = Product(name="新产品", price=99.99, category="测试")
    await product.save()
    
    # 如果任何操作失败，所有更改都会回滚
```

### 5. 数据库迁移

```python
# 自动生成迁移
db.register_model(User)  # 自动创建表迁移

# 自定义迁移
migration = db.create_migration(
    "add_user_phone_20241215",
    "Add phone field to users",
    "ALTER TABLE users ADD COLUMN phone VARCHAR(20)",
    "ALTER TABLE users DROP COLUMN phone"
)

# 执行迁移
await db.migrate()

# 回滚迁移
await db.rollback(steps=1)
```

## 🔧 高级功能

### 多数据库支持

```python
# 添加多个数据库连接
await db.add_database("main", "postgresql://user:pass@localhost/main")
await db.add_database("cache", "redis://localhost:6379")
await db.add_database("logs", "mongodb://localhost:27017/logs")

# 在特定数据库上操作
await user.save(database="main")
users = await User.find_all(database="main")
```

### 原生SQL查询

```python
# 执行原生查询
results = await db.raw_query("""
    SELECT category, COUNT(*) as count, AVG(price) as avg_price
    FROM products 
    WHERE is_available = ?
    GROUP BY category
""", [True])

# 执行原生命令
await db.raw_execute("CREATE INDEX idx_product_category ON products(category)")
```

### 数据备份和恢复

```python
# 备份数据
data = await db.backup_data(Product)

# 清空表
await db.truncate_table(Product)

# 恢复数据
await db.restore_data(Product, data)
```

## 📖 完整示例

查看 `examples/database_example.py` 文件获取完整的使用示例，包括：

- 模型定义和关系
- 复杂查询操作
- 事务管理
- 迁移管理
- 性能优化技巧

## 🛠️ 开发

### 安装开发依赖

```bash
pip install -e .
pip install -r requirements.txt
```

### 运行测试

```bash
pytest
```

### 代码格式化

```bash
black pyadminkit/
isort pyadminkit/
```

## 📋 系统要求

- Python 3.8+
- 支持的数据库:
  - PostgreSQL 10+
  - MySQL 5.7+
  - SQLite 3.x
  - MongoDB 4.0+

## 🤝 贡献

欢迎提交Issue和Pull Request！请查看 [CONTRIBUTING.md](CONTRIBUTING.md) 了解详细信息。

## 📄 许可证

MIT License - 查看 [LICENSE](LICENSE) 文件了解详细信息。

## 🔗 相关链接

- [文档](https://pyadminkit.readthedocs.io/)
- [PyPI](https://pypi.org/project/pyadminkit/)
- [GitHub](https://github.com/pyadminkit/pyadminkit)
- [问题反馈](https://github.com/pyadminkit/pyadminkit/issues)

---

**PyAdminKit** - 让Python后台管理系统开发变得简单而高效！
