Metadata-Version: 2.4
Name: fastapi-crud-toolkit
Version: 0.1.0
Summary: Production-ready BaseRepository, BaseService, BaseSchema, BaseRouter, and Model Mixins for FastAPI + SQLAlchemy 2.0 projects
Project-URL: Homepage, https://github.com/your-username/fastapi-crud-toolkit
Project-URL: Repository, https://github.com/your-username/fastapi-crud-toolkit
Project-URL: Documentation, https://github.com/your-username/fastapi-crud-toolkit#readme
Project-URL: Issues, https://github.com/your-username/fastapi-crud-toolkit/issues
Author-email: Le Van Hiep <vanhiep2008@gmail.com>
License-Expression: MIT
Keywords: async,base-repository,base-service,crud,fastapi,postgresql,pydantic,repository-pattern,service-layer,sqlalchemy
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: fastapi>=0.100.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: sqlalchemy>=2.0.0
Provides-Extra: dev
Requires-Dist: aiosqlite>=0.19; extra == 'dev'
Requires-Dist: httpx>=0.24; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# FastAPI CRUD Toolkit

Production-ready base classes for **FastAPI + SQLAlchemy 2.0** projects.

Stop writing repetitive CRUD code. This toolkit provides generic, reusable base classes that handle 90% of common backend operations.

## Installation

```bash
pip install fastapi-crud-toolkit
```

Or install from GitHub:

```bash
pip install git+https://github.com/your-username/fastapi-crud-toolkit.git
```

## What's Included

| Module | Description | Methods |
|--------|-------------|---------|
| `BaseRepository` | Generic async repository | 26 DB operations |
| `BaseService` | Generic service layer | 40+ business logic operations |
| `BaseSchema` | Pydantic schemas | 16 request/response patterns |
| `BaseCRUDRouter` | Auto-generated endpoints | 8 REST endpoints |
| `Model Mixins` | Reusable column patterns | 9 mixins |
| `Exceptions` | Structured HTTP errors | 16 exception classes |

## Quick Start

### 1. Define your model

```python
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
from fastapi_crud_toolkit import UUIDMixin, TimestampMixin

class Base(DeclarativeBase):
    pass

class User(UUIDMixin, TimestampMixin, Base):
    __tablename__ = "users"
    name: Mapped[str] = mapped_column(String(255))
    email: Mapped[str] = mapped_column(String(255), unique=True)
```

### 2. Create repository

```python
from fastapi_crud_toolkit import BaseRepository

class UserRepository(BaseRepository[User]):
    def __init__(self, db: AsyncSession):
        super().__init__(User, db)
```

### 3. Create service

```python
from fastapi_crud_toolkit import BaseService

class UserService(BaseService[User, UserRepository]):
    resource_type = "user"
    audit_enabled = True
    searchable_fields = ["name", "email"]

    def __init__(self, db: AsyncSession):
        super().__init__(UserRepository(db), db)
```

### 4. Create endpoints (auto-generated)

```python
from fastapi_crud_toolkit import BaseCRUDRouter

crud = BaseCRUDRouter(
    service_class=UserService,
    response_schema=UserResponse,
    create_schema=UserCreate,
    update_schema=UserUpdate,
    resource_name="user",
    tags=["users"],
    get_db=get_db,
    get_current_user=get_current_user,
)

app.include_router(crud.router, prefix="/api/v1/users")
```

This generates: `GET /`, `GET /{id}`, `POST /`, `PUT /{id}`, `DELETE /{id}`, `GET /search`, `GET /count`, `POST /bulk-delete`

### 5. Register exception handlers

```python
from fastapi_crud_toolkit import register_exception_handlers

app = FastAPI()
register_exception_handlers(app)
```

## BaseRepository Methods

| Category | Methods |
|----------|---------|
| Read | `get_by_id`, `get_by_ids`, `get_all`, `get_by_filters`, `get_first`, `paginate`, `search` |
| Count | `count`, `exists`, `exists_by_field` |
| Create | `create`, `bulk_create`, `get_or_create`, `upsert` |
| Update | `update`, `update_by_id`, `bulk_update` |
| Delete | `delete`, `delete_by_id`, `bulk_delete`, `soft_delete`, `restore` |
| Aggregate | `aggregate` (count/sum/avg/min/max + group_by) |
| Utility | `refresh`, `execute_raw` |

## BaseService Methods

Includes everything from BaseRepository plus:

| Category | Methods |
|----------|---------|
| CRUD | All repo methods + automatic audit logging |
| Hooks | `_validate_create`, `_pre_create`, `_post_create`, `_validate_update`, `_pre_update`, `_post_update`, `_pre_delete`, `_post_delete` |
| Permissions | `check_permission`, `check_permission_or_raise` |
| Export/Import | `to_dict`, `export_list`, `import_list` |
| Utility | `clone`, `archive`, `refresh`, `search` |

## Exceptions

```python
from fastapi_crud_toolkit import NotFoundException, DuplicateException

raise NotFoundException("User", id="abc-123")
# → 404: "User with id 'abc-123' not found"

raise DuplicateException("User", field="email", value="test@mail.com")
# → 409: "User with email='test@mail.com' already exists"
```

## Requirements

- Python >= 3.10
- SQLAlchemy >= 2.0
- Pydantic >= 2.0
- FastAPI >= 0.100

## License

MIT
