fastcrud 0.1.1

FastCRUD is a Python package for FastAPI, offering robust async CRUD operations and flexible endpoint creation utilities.

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

🚧 Coming Soon 🚧

Usage

FastCRUD offers two primary ways to use its functionalities:

1. By using crud_router for automatic endpoint creation.
2. 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

MIT

11. Contact

Igor Magalhaes – @igormagalhaesr – [e-mail] github.com/igorbenav