Metadata-Version: 2.4
Name: autocrud
Version: 0.3.2
Summary: 自動產生 CRUD API 的 Python 函式庫
Project-URL: Homepage, https://github.com/HYChou0515/autocrud
Project-URL: Documentation, https://HYChou0515.github.io/autocrud/
Project-URL: Repository, https://github.com/HYChou0515/autocrud.git
Project-URL: Issues, https://github.com/HYChou0515/autocrud/issues
Author-email: HYChou0515 <hychou.svm@example.com>
License: MIT License
        
        Copyright (c) 2025 HYChou0515
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: api,automation,crud,fastapi,rest
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
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.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.116.1
Requires-Dist: jsonpatch>=1.33
Requires-Dist: msgpack>=1.1.1
Requires-Dist: msgspec>=0.19.0
Requires-Dist: pydantic>=2.11.7
Requires-Dist: xxhash>=3.5.0
Provides-Extra: dev
Requires-Dist: coverage>=7.9.2; extra == 'dev'
Requires-Dist: pytest-asyncio>=1.1.0; extra == 'dev'
Requires-Dist: pytest>=8.4.1; extra == 'dev'
Requires-Dist: ruff>=0.12.4; extra == 'dev'
Provides-Extra: docs
Requires-Dist: furo>=2025.7.19; extra == 'docs'
Requires-Dist: linkify-it-py>=2.0.3; extra == 'docs'
Requires-Dist: myst-parser>=4.0.1; extra == 'docs'
Requires-Dist: sphinx-autodoc-typehints>=3.2.0; extra == 'docs'
Requires-Dist: sphinx-design>=0.6.1; extra == 'docs'
Requires-Dist: sphinx>=8.2.3; extra == 'docs'
Description-Content-Type: text/markdown

# AutoCRUD

🚀 **自動生成 CRUD API 的 Python 庫** - 支持多種數據類型，零配置快速構建 REST API

[![Python](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![FastAPI](https://img.shields.io/badge/FastAPI-compatible-green.svg)](https://fastapi.tiangolo.com/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

## ✨ 特色功能

- 🎯 **多數據類型支持**: TypedDict、Pydantic BaseModel、dataclass、msgspec.Struct
- ⚡ **零配置**: 一行代碼生成完整 CRUD API
- 🔧 **高度可定制**: 靈活的路由模板和命名約定
- 📚 **自動文檔**: 集成 Swagger/OpenAPI 文檔
- 🏎️ **高性能**: 基於 FastAPI 和 msgspec
- 🔒 **類型安全**: 完整的 TypeScript 風格類型檢查

## 🚀 快速開始

### 安裝

```bash
pip install autocrud
# 或使用 uv
uv add autocrud
```

### 5 分鐘創建 API

```python
from pydantic import BaseModel
from fastapi import FastAPI, APIRouter
from autocrud.crud.core import (
    AutoCRUD, CreateRouteTemplate, ReadRouteTemplate,
    UpdateRouteTemplate, DeleteRouteTemplate, ListRouteTemplate
)

# 定義數據模型
class User(BaseModel):
    name: str
    email: str
    age: int = None

# 創建 AutoCRUD 實例
crud = AutoCRUD(model_naming="kebab")

# 添加 CRUD 操作
crud.add_route_template(CreateRouteTemplate())
crud.add_route_template(ReadRouteTemplate())
crud.add_route_template(UpdateRouteTemplate())
crud.add_route_template(DeleteRouteTemplate())
crud.add_route_template(ListRouteTemplate())

# 註冊模型 - 就這麼簡單！
crud.add_model(User)

# 集成到 FastAPI
app = FastAPI(title="User API")
router = APIRouter()
crud.apply(router)
app.include_router(router)

# 運行: uvicorn main:app --reload
```

**🎉 完成！** 現在你有了一個完整的 CRUD API：

- `POST /user` - 創建用戶
- `GET /user/{id}` - 獲取用戶
- `PUT /user/{id}` - 更新用戶
- `DELETE /user/{id}` - 刪除用戶
- `GET /user` - 列出所有用戶

## 📊 多數據類型支持

AutoCRUD 支持 Python 主流數據類型，你可以選擇最適合的：

```python
from typing import TypedDict, Optional
from dataclasses import dataclass
from pydantic import BaseModel
import msgspec

# 1. TypedDict - 輕量級
class Product(TypedDict):
    name: str
    price: float
    in_stock: bool

# 2. Pydantic - 強驗證
class User(BaseModel):
    username: str
    email: str
    age: Optional[int] = None

# 3. dataclass - 原生支持
@dataclass
class Order:
    customer_id: str
    items: list
    total: float = 0.0

# 4. msgspec - 高性能
class Event(msgspec.Struct):
    type: str
    data: dict
    timestamp: float

# 一次註冊所有類型
crud.add_model(Product)   # /product
crud.add_model(User)      # /user  
crud.add_model(Order)     # /order
crud.add_model(Event)     # /event
```

## 🎯 實際示例

### 博客 API

```python
from dataclasses import dataclass
from pydantic import BaseModel, EmailStr
from typing import List, Optional

class Author(BaseModel):
    name: str
    email: EmailStr
    bio: Optional[str] = None

@dataclass
class BlogPost:
    title: str
    content: str
    author_id: str
    tags: List[str] = None
    published: bool = False

# 創建完整博客 API
crud = AutoCRUD(model_naming="kebab")
# ... 添加路由模板
crud.add_model(Author)    # /author
crud.add_model(BlogPost)  # /blog-post
```

### 電商系統

```python
from decimal import Decimal
from enum import Enum

class OrderStatus(str, Enum):
    PENDING = "pending"
    SHIPPED = "shipped"
    DELIVERED = "delivered"

class Product(BaseModel):
    name: str
    price: Decimal
    stock: int
    category: str

class Order(BaseModel):
    customer_id: str
    items: List[dict]
    status: OrderStatus = OrderStatus.PENDING
    total: Decimal

# 完整電商 CRUD
crud.add_model(Product)  # /product
crud.add_model(Order)    # /order
```

## ⚙️ 配置選項

### 命名約定

```python
# kebab-case (推薦)
crud = AutoCRUD(model_naming="kebab")
# UserProfile -> /user-profile

# snake_case
crud = AutoCRUD(model_naming="snake") 
# UserProfile -> /user_profile

# 自定義
def custom_naming(model_type):
    return f"api_{model_type.__name__.lower()}"
crud = AutoCRUD(model_naming=custom_naming)
```

### 選擇性 CRUD 操作

```python
# 只讀 API
crud.add_route_template(ReadRouteTemplate())
crud.add_route_template(ListRouteTemplate())

# 基本 CRUD
crud.add_route_template(CreateRouteTemplate())
crud.add_route_template(ReadRouteTemplate()) 
crud.add_route_template(UpdateRouteTemplate())
crud.add_route_template(DeleteRouteTemplate())

# 高級功能
crud.add_route_template(PatchRouteTemplate())        # 部分更新
crud.add_route_template(SwitchRevisionRouteTemplate()) # 版本控制
crud.add_route_template(RestoreRouteTemplate())       # 恢復刪除
```

## 📖 文檔

- 📚 [完整文檔](docs/source/index.md)
- 🚀 [快速開始](docs/source/quickstart_new.md)
- 📖 [用戶指南](docs/source/user_guide_new.md)
- 💡 [示例集合](docs/source/examples_new.md)
- 🔧 [API 參考](docs/source/api_reference.md)

## 🏃‍♂️ 運行示例

克隆倉庫並運行示例：

```bash
git clone https://github.com/HYChou0515/autocrud.git
cd autocrud

# 博客 API 示例
python examples/blog_api_example.py

# 電商 API 示例  
python examples/ecommerce_api_example.py

# 多數據類型示例
python examples/simple_quickstart.py
```

然後訪問 http://localhost:8000/docs 查看 API 文檔。

## 🧪 測試

```bash
# 安裝依賴
uv install

# 運行測試
uv run pytest

# 運行特定測試
uv run pytest tests/test_multiple_data_types.py -v
```

## 🤝 貢獻

歡迎貢獻！請查看 [貢獻指南](docs/source/contributing.md)。

## 📄 許可證

MIT License - 詳見 [LICENSE](LICENSE) 文件。

## 🌟 為什麼選擇 AutoCRUD？

### 傳統方式 😫
```python
# 需要手寫大量樣板代碼
@app.post("/users")
async def create_user(user: UserCreate):
    # 驗證邏輯
    # 業務邏輯  
    # 數據庫操作
    # 錯誤處理
    # 響應格式化
    pass

@app.get("/users/{user_id}")
async def get_user(user_id: str):
    # 更多樣板代碼...
    pass

# ... 重複 5+ 個端點
```

### AutoCRUD 方式 😎
```python
# 一行代碼，完整 CRUD API
crud.add_model(User)
```

**節省 90% 的開發時間！** 🎯
