From 9ad40dbff79a55cf500d0d1246004eb8a3670e60 Mon Sep 17 00:00:00 2001 From: Chris Pinard Date: Sun, 14 Jul 2024 22:33:12 -0400 Subject: [PATCH] Doc/docstring updates using model/schemas. --- docs/usage/crud.md | 56 +++++++++++++++-- fastcrud/crud/fast_crud.py | 57 ++++++++++++++++- fastcrud/endpoint/crud_router.py | 102 ++++++++++++++++++++++++++++--- 3 files changed, 199 insertions(+), 16 deletions(-) diff --git a/docs/usage/crud.md b/docs/usage/crud.md index 6c3e981..97866db 100644 --- a/docs/usage/crud.md +++ b/docs/usage/crud.md @@ -35,6 +35,51 @@ Define your SQLAlchemy models and Pydantic schemas for data representation. --8<-- ``` + ??? example "`customer/model.py`" + + ```python + --8<-- + fastcrud/examples/customer/model.py:imports + fastcrud/examples/customer/model.py:model + --8<-- + ``` + + ??? example "`customer/schemas.py`" + + ```python + --8<-- + fastcrud/examples/customer/schemas.py:imports + fastcrud/examples/customer/schemas.py:readschema + --8<-- + ``` + + ??? example "`product/model.py`" + + ```python + --8<-- + fastcrud/examples/product/model.py:imports + fastcrud/examples/product/model.py:model + --8<-- + ``` + + ??? example "`order/model.py`" + + ```python + --8<-- + fastcrud/examples/order/model.py:imports + fastcrud/examples/order/model.py:model + --8<-- + ``` + + ??? example "`order/schemas.py`" + + ```python + --8<-- + fastcrud/examples/order/schemas.py:imports + fastcrud/examples/order/schemas.py:readschema + --8<-- + ``` + ### Step 2: Initialize FastCRUD Create a `FastCRUD` instance for your model to handle CRUD operations. @@ -44,6 +89,7 @@ from fastcrud import FastCRUD # Creating a FastCRUD instance item_crud = FastCRUD(Item) +order_crud = FastCRUD(Order) ``` ### Step 3: Pick your Method @@ -281,14 +327,14 @@ get_joined( ``` **Purpose**: To fetch a single record with one or multiple joins on other models. -**Usage Example**: Fetches order details for a specific order by joining with the `Customer` table, selecting specific columns as defined in `OrderSchema` and `CustomerSchema`. +**Usage Example**: Fetches order details for a specific order by joining with the `Customer` table, selecting specific columns as defined in `ReadOrderSchema` and `ReadCustomerSchema`. ```python order_details = await order_crud.get_joined( db, + schema_to_select=ReadOrderSchema, join_model=Customer, - schema_to_select=OrderSchema, - join_schema_to_select=CustomerSchema, + join_schema_to_select=ReadCustomerSchema, id=order_id, ) ``` @@ -325,9 +371,9 @@ get_multi_joined( ```python orders = await order_crud.get_multi_joined( db, - schema_to_select=OrderSchema, + schema_to_select=ReadOrderSchema, join_model=Customer, - join_schema_to_select=CustomerSchema, + join_schema_to_select=ReadCustomerSchema, offset=0, limit=5, ) diff --git a/fastcrud/crud/fast_crud.py b/fastcrud/crud/fast_crud.py index 72e3a54..4f6ce94 100644 --- a/fastcrud/crud/fast_crud.py +++ b/fastcrud/crud/fast_crud.py @@ -104,9 +104,59 @@ class FastCRUD( Soft deletes a record if it has an `"is_deleted"` attribute (or other attribute as defined by `is_deleted_column`); otherwise, performs a hard delete. Examples: + Basic Setup: + + ??? example "Models and Schemas Used Below" + + ??? example "`customer/model.py`" + + ```python + --8<-- + fastcrud/examples/customer/model.py:imports + fastcrud/examples/customer/model.py:model + --8<-- + ``` + + ??? example "`product/model.py`" + + ```python + --8<-- + fastcrud/examples/product/model.py:imports + fastcrud/examples/product/model.py:model + --8<-- + ``` + + ??? example "`product/schemas.py`" + + ```python + --8<-- + fastcrud/examples/product/schemas.py:imports + fastcrud/examples/product/schemas.py:readschema + --8<-- + ``` + + ??? example "`order/model.py`" + + ```python + --8<-- + fastcrud/examples/order/model.py:imports + fastcrud/examples/order/model.py:model + --8<-- + ``` + + ??? example "`order/schemas.py`" + + ```python + --8<-- + fastcrud/examples/order/schemas.py:imports + fastcrud/examples/order/schemas.py:readschema + --8<-- + ``` + Example 1: Basic Usage ---------------------- Create a FastCRUD instance for a `User` model and perform basic CRUD operations. + ```python # Assuming you have a User model (either SQLAlchemy or SQLModel) # pydantic schemas for creation, update and deletion and an async session `db` @@ -130,6 +180,7 @@ class FastCRUD( Example 2: Advanced Filtering and Pagination -------------------------------------------- Use advanced filtering, sorting, and pagination for fetching records. + ```python product_crud = FastCRUD(Product) products = await product_crud.get_multi( @@ -144,14 +195,15 @@ class FastCRUD( Example 3: Join Operations with Custom Schemas ---------------------------------------------- Perform join operations between two models using custom schemas for selection. + ```python order_crud = FastCRUD(Order) orders = await order_crud.get_multi_joined( db, - schema_to_select=OrderReadSchema, + schema_to_select=ReadOrderSchema, join_model=Product, join_prefix="product_", - join_schema_to_select=ProductReadSchema, + join_schema_to_select=ReadProductSchema, offset=0, limit=5, ) @@ -160,6 +212,7 @@ class FastCRUD( Example 4: Cursor Pagination ---------------------------- Implement cursor-based pagination for efficient data retrieval in large datasets. + ```python class Comment(Base): id = Column(Integer, primary_key=True) diff --git a/fastcrud/endpoint/crud_router.py b/fastcrud/endpoint/crud_router.py index c685dcd..94f37d0 100644 --- a/fastcrud/endpoint/crud_router.py +++ b/fastcrud/endpoint/crud_router.py @@ -106,6 +106,69 @@ def crud_router( --8<-- ``` + ??? example "`customer/model.py`" + + ```python + --8<-- + fastcrud/examples/customer/model.py:imports + fastcrud/examples/customer/model.py:model + --8<-- + ``` + + ??? example "`customer/schemas.py`" + + ```python + --8<-- + fastcrud/examples/customer/schemas.py:imports + fastcrud/examples/customer/schemas.py:createschema + fastcrud/examples/customer/schemas.py:readschema + fastcrud/examples/customer/schemas.py:updateschema + fastcrud/examples/customer/schemas.py:deleteschema + --8<-- + ``` + + ??? example "`product/model.py`" + + ```python + --8<-- + fastcrud/examples/product/model.py:imports + fastcrud/examples/product/model.py:model + --8<-- + ``` + + ??? example "`product/schemas.py`" + + ```python + --8<-- + fastcrud/examples/product/schemas.py:imports + fastcrud/examples/product/schemas.py:createschema + fastcrud/examples/product/schemas.py:readschema + fastcrud/examples/product/schemas.py:updateschema + fastcrud/examples/product/schemas.py:deleteschema + --8<-- + ``` + + ??? example "`order/model.py`" + + ```python + --8<-- + fastcrud/examples/order/model.py:imports + fastcrud/examples/order/model.py:model + --8<-- + ``` + + ??? example "`order/schemas.py`" + + ```python + --8<-- + fastcrud/examples/order/schemas.py:imports + fastcrud/examples/order/schemas.py:createschema + fastcrud/examples/order/schemas.py:readschema + fastcrud/examples/order/schemas.py:updateschema + fastcrud/examples/order/schemas.py:deleteschema + --8<-- + ``` + ```python mymodel_router = crud_router( session=async_session, @@ -137,9 +200,9 @@ def get_current_user(token: str = Depends(oauth2_scheme)): Adding Delete Endpoints: ```python - router = crud_router( + product_router = crud_router( session=async_session, - model=ProductModel, + model=Product, create_schema=CreateProductSchema, update_schema=UpdateProductSchema, delete_schema=DeleteProductSchema, @@ -150,12 +213,19 @@ def get_current_user(token: str = Depends(oauth2_scheme)): Customizing Path and Tags: ```python - router = crud_router( + CRUDOrder = FastCRUD[ + Order, + CreateOrderSchema, + UpdateOrderSchema, + UpdateOrderSchema, + DeleteOrderSchema, + ] + order_router = crud_router( session=async_session, - model=OrderModel, + model=Order, create_schema=CreateOrderSchema, update_schema=UpdateOrderSchema, - crud=CRUDOrderModel(OrderModel), + crud=CRUDOrder(Order), path="/orders", tags=["Orders", "Sales"], ) @@ -163,22 +233,36 @@ def get_current_user(token: str = Depends(oauth2_scheme)): Integrating Multiple Models: ```python + CRUDProduct = FastCRUD[ + Product, + CreateProductSchema, + UpdateProductSchema, + UpdateProductSchema, + DeleteProductSchema, + ] product_router = crud_router( session=async_session, - model=ProductModel, + model=Product, create_schema=CreateProductSchema, update_schema=UpdateProductSchema, - crud=CRUDProductModel(ProductModel), + crud=CRUDProduct(Product), path="/products", tags=["Inventory"], ) + CRUDCustomer = FastCRUD[ + Customer, + CreateCustomerSchema, + UpdateCustomerSchema, + UpdateCustomerSchema, + DeleteCustomerSchema, + ] customer_router = crud_router( session=async_session, - model=CustomerModel, + model=Customer, create_schema=CreateCustomerSchema, update_schema=UpdateCustomerSchema, - crud=CRUDCustomerModel(CustomerModel), + crud=CRUDCustomer(Customer), path="/customers", tags=["CRM"], )