fastapi-crud-toolkit 0.1.0

Production-ready BaseRepository, BaseService, BaseSchema, BaseRouter, and Model Mixins for FastAPI + SQLAlchemy 2.0 projects

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

pip install fastapi-crud-toolkit

Or install from GitHub:

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

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

from fastapi_crud_toolkit import BaseRepository

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

3. Create service

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)

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

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

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="[e-mail]")
# → 409: "User with email='[e-mail]' already exists"

Requirements

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

License

MIT