FastCRUD is a Python package for FastAPI, offering robust async CRUD operations and flexible endpoint creation utilities.
Project description
Powerful CRUD methods and automatic endpoint creation for FastAPI.
FastCRUD is a Python package for FastAPI, offering robust async CRUD operations and flexible endpoint creation utilities, streamlined through advanced features like auto-detected join conditions, dynamic sorting, and offset and cursor pagination.
Documentation: 🚧 Coming Soon 🚧
Features
- ⚡️ Fully Async: Leverages Python's async capabilities for non-blocking database operations.
- 📚 SQLAlchemy 2.0: Works with the latest SQLAlchemy version for robust database interactions.
- 🦾 Powerful CRUD Functionality: Full suite of efficient CRUD operations with support for joins.
- ⚙️ Dynamic Query Building: Supports building complex queries dynamically, including filtering, sorting, and pagination.
- 🤝 Advanced Join Operations: Facilitates performing SQL joins with other models with automatic join condition detection.
- 📖 Built-in Offset Pagination: Comes with ready-to-use offset pagination.
- ➤ Cursor-based Pagination: Implements efficient pagination for large datasets, ideal for infinite scrolling interfaces.
- 🤸♂️ Modular and Extensible: Designed for easy extension and customization to fit your requirements.
- 🛣️ Auto-generated Endpoints: Streamlines the process of adding CRUD endpoints with custom dependencies and configurations.
Requirements
Before installing FastCRUD, ensure you have the following prerequisites:
- Python: Version 3.9 or newer.
- FastAPI: FastCRUD is built to work with FastAPI, so having FastAPI in your project is essential.
- SQLAlchemy: Version 2.0.21 or newer. FastCRUD uses SQLAlchemy for database operations.
- Pydantic: Version 2.4.1 or newer. FastCRUD leverages Pydantic models for data validation and serialization.
- SQLAlchemy-Utils: Optional, but recommended for additional SQLAlchemy utilities.
Installing
To install, just run:
pip install fastcrud
Or, if using poetry:
poetry add fastcrud
Usage
FastCRUD offers two primary ways to use its functionalities:
- By using
crud_router
for automatic endpoint creation. - By integrating
FastCRUD
directly into your FastAPI endpoints for more control.
Below are examples demonstrating both approaches:
Using crud_router for Automatic Endpoint Creation
Here's a quick example to get you started:
Define Your Model and Schema
from sqlalchemy import Column, Integer, String
from sqlalchemy.orm import declarative_base
from pydantic import BaseModel
Base = declarative_base()
class Item(Base):
__tablename__ = 'items'
id = Column(Integer, primary_key=True)
name = Column(String)
description = Column(String)
class ItemCreateSchema(BaseModel):
name: str
description: str
class ItemUpdateSchema(BaseModel):
name: str
description: str
Set Up FastAPI and FastCRUD
from fastapi import FastAPI
from fastcrud import FastCRUD, crud_router
from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
from sqlalchemy.orm import sessionmaker
# Database setup (Async SQLAlchemy)
DATABASE_URL = "sqlite+aiosqlite:///./test.db"
engine = create_async_engine(DATABASE_URL, echo=True)
async_session = sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
# FastAPI app
app = FastAPI()
# CRUD operations setup
crud = FastCRUD(Item)
# CRUD router setup
item_router = crud_router(
session=async_session,
model=Item,
crud=crud,
create_schema=ItemCreateSchema,
update_schema=ItemUpdateSchema,
path="/items",
tags=["Items"]
)
app.include_router(item_router)
Using FastCRUD in User-Defined FastAPI Endpoints
For more control over your endpoints, you can use FastCRUD directly within your custom FastAPI route functions. Here's an example:
from fastapi import FastAPI, Depends, HTTPException
from sqlalchemy.ext.asyncio import AsyncSession
from fastcrud import FastCRUD
from yourapp.models import Item
from yourapp.schemas import ItemCreateSchema, ItemUpdateSchema
app = FastAPI()
# Assume async_session is already set up as per the previous example
# Instantiate FastCRUD with your model
item_crud = FastCRUD(Item)
@app.post("/custom/items/")
async def create_item(item_data: ItemCreateSchema, db: AsyncSession = Depends(async_session)):
return await item_crud.create(db, item_data)
@app.get("/custom/items/{item_id}")
async def read_item(item_id: int, db: AsyncSession = Depends(async_session)):
item = await item_crud.get(db, id=item_id)
if not item:
raise HTTPException(status_code=404, detail="Item not found")
return item
# You can add more routes for update and delete operations in a similar fashion
In this example, we define custom endpoints for creating and reading items using FastCRUD directly, providing more flexibility in how the endpoints are structured and how the responses are handled.
Understanding FastCRUD Methods
FastCRUD offers a comprehensive suite of methods for CRUD operations, each designed to handle different aspects of database interactions efficiently.
1. Create
create(
db: AsyncSession,
object: CreateSchemaType
) -> ModelType
Purpose: To create a new record in the database.
Usage Example:
# creates an item with name 'New Item'
new_item = await item_crud.create(db, ItemCreateSchema(name="New Item"))
2. Get
get(
db: AsyncSession,
schema_to_select: Optional[Union[type[BaseModel], list]] = None,
**kwargs: Any
) -> Optional[dict]
Purpose: To fetch a single record based on filters, with an option to select specific columns using a Pydantic schema.
Usage Example:
# fetches the item with item_id as its id
item = await item_crud.get(db, id=item_id)
3. Exists
exists(
db: AsyncSession,
**kwargs: Any
) -> bool
Purpose: To check if a record exists based on provided filters.
Usage Example:
# checks whether an item with name 'Existing Item' exists
exists = await item_crud.exists(db, name="Existing Item")
4. Count
count(
db: AsyncSession,
**kwargs: Any
) -> int
Purpose: To count the number of records matching provided filters.
Usage Example:
# counts the number of items with the 'Books' category
count = await item_crud.count(db, category="Books")
5. Get Multi
get_multi(
db: AsyncSession,
offset: int = 0,
limit: int = 100,
schema_to_select: Optional[type[BaseModel]] = None,
sort_columns: Optional[Union[str, list[str]]] = None,
sort_orders: Optional[Union[str, list[str]]] = None,
return_as_model: bool = False,
**kwargs: Any
) -> dict[str, Any]</
Purpose: To fetch multiple records with optional sorting, pagination, and model conversion.
Usage Example:
# fetches a subset of 5 items, starting from the 11th item in the database.
items = await item_crud.get_multi(db, offset=10, limit=5)
6. Update
update(
db: AsyncSession,
object: Union[UpdateSchemaType, dict[str, Any]],
**kwargs: Any
) -> None
Purpose: To update an existing record in the database.
Usage Example:
# updates the description of the item with item_id as its id
await item_crud.update(db, ItemUpdateSchema(description="Updated"), id=item_id)
7. Delete
delete(
db: AsyncSession,
db_row: Optional[Row] = None,
**kwargs: Any
) -> None
Purpose: To delete a record from the database, with support for soft delete.
Usage Example:
# deletes the item with item_id as its id
# it performs a soft_delete if the model has the 'is_deleted' column
await item_crud.delete(db, id=item_id)
8. Hard Delete
db_delete(
db: AsyncSession,
**kwargs: Any
) -> None
Purpose: To hard delete a record from the database.
Usage Example:
# hard deletes the item with item_id as its id
await item_crud.db_delete(db, id=item_id)
Advanced Methods for Complex Queries and Joins
FastCRUD also provides advanced methods for more complex operations like querying multiple records with filters, sorting, pagination (get_multi
), handling join operations (get_joined
, get_multi_joined
), and cursor-based pagination (get_multi_by_cursor
).
Advanced Methods for Complex Queries and Joins
FastCRUD extends its functionality with advanced methods tailored for complex query operations and handling joins. These methods cater to specific use cases where more sophisticated data retrieval and manipulation are required.
1. Get Multi
get_multi(
db: AsyncSession,
offset: int = 0,
limit: int = 100,
schema_to_select: Optional[type[BaseModel]] = None,
sort_columns: Optional[Union[str, list[str]]] = None,
sort_orders: Optional[Union[str, list[str]]] = None,
return_as_model: bool = False,
**kwargs: Any
) -> dict[str, Any]
Purpose: To fetch multiple records based on specified filters, with options for sorting and pagination. Ideal for listing views and tables.
Usage Example:
# gets the first 10 items sorted by 'name' in ascending order
items = await item_crud.get_multi(db, offset=0, limit=10, sort_columns=['name'], sort_orders=['asc'])
2. Get Joined
get_joined(
db: AsyncSession,
join_model: type[ModelType],
join_prefix: Optional[str] = None,
join_on: Optional[Union[Join, None]] = None,
schema_to_select: Optional[Union[type[BaseModel], list]] = None,
join_schema_to_select: Optional[Union[type[BaseModel], list]] = None,
join_type: str = "left", **kwargs: Any
) -> Optional[dict[str, Any]]
Purpose: To fetch a single record while performing a join operation with another model. This method is useful when data from related tables is needed.
Usage Example:
# fetches order details for a specific order by joining with the Customer table,
# selecting specific columns as defined in OrderSchema and CustomerSchema.
order_details = await order_crud.get_joined(
db,
join_model=Customer,
schema_to_select=OrderSchema,
join_schema_to_select=CustomerSchema,
id=order_id
)
3. Get Multi Joined
get_multi_joined(
db: AsyncSession,
join_model: type[ModelType],
join_prefix: Optional[str] = None,
join_on: Optional[Join] = None,
schema_to_select: Optional[type[BaseModel]] = None,
join_schema_to_select: Optional[type[BaseModel]] = None,
join_type: str = "left",
offset: int = 0,
limit: int = 100,
sort_columns: Optional[Union[str, list[str]]] = None,
sort_orders: Optional[Union[str, list[str]]] = None,
return_as_model: bool = False,
**kwargs: Any
) -> dict[str, Any]
Purpose: Similar to get_joined
, but for fetching multiple records. Supports pagination and sorting on the joined tables.
Usage Example:
# retrieves a paginated list of orders (up to 5), joined with the Customer table,
# using specified schemas for selective column retrieval from both tables.
orders = await order_crud.get_multi_joined(
db,
join_model=Customer,
offset=0,
limit=5,
schema_to_select=OrderSchema,
join_schema_to_select=CustomerSchema
)
4. Get Multi By Cursor
get_multi_by_cursor(
db: AsyncSession,
cursor: Any = None,
limit: int = 100,
schema_to_select: Optional[type[BaseModel]] = None,
sort_column: str = "id",
sort_order: str = "asc",
**kwargs: Any
) -> dict[str, Any]
Purpose: Implements cursor-based pagination for efficient data retrieval in large datasets. This is particularly useful for infinite scrolling interfaces.
Usage Example:
# fetches the next 10 items after the last cursor for efficient pagination,
# sorted by creation date in descending order.
paginated_items = await item_crud.get_multi_by_cursor(
db,
cursor=last_cursor,
limit=10,
sort_column='created_at',
sort_order='desc'
)
These advanced methods enhance FastCRUD's capabilities, allowing for more tailored and optimized interactions with the database, especially in scenarios involving complex data relationships and large datasets.
References
This project was heavily inspired by CRUDBase in FastAPI Microservices
by @kludex.
10. License
11. Contact
Igor Magalhaes – @igormagalhaesr – igormagalhaesr@gmail.com github.com/igorbenav
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.