Add docs for CBV

Author: David Montague

Makefile

@@ -2,6 +2,7 @@
 
 pkg_src = fastapi_utils
 tests_src = tests
+docs_src = docs/src
 all_src = $(pkg_src) $(tests_src)
 
 isort = isort -rc $(all_src)
@@ -93,6 +94,12 @@ docs-build:
 	cp ./docs/index.md ./README.md
 	cp ./docs/contributing.md ./CONTRIBUTING.md
 
+.PHONY: docs-format  ## Format the python code that is part of the docs
+docs-format:
+	isort -rc docs/src
+	autoflake -r --remove-all-unused-imports --ignore-init-module-imports docs/src
+	black -l 82 docs/src
+
 
 .PHONY: docs-live  ## Serve the docs with live reload as you make changes
 docs-live:

docs/src/api_model.py

@@ -19,6 +19,7 @@ class UserORM:
     """
     You can pretend this class is a SQLAlchemy model
     """
+
     user_id: UserID
     email_address: str
 

docs/src/class_based_views1.py

@@ -0,0 +1,107 @@
+from typing import NewType, Optional
+from uuid import UUID
+
+import sqlalchemy as sa
+from fastapi import Depends, FastAPI, Header, HTTPException
+from sqlalchemy.ext.declarative import declarative_base
+from sqlalchemy.orm import Session
+from starlette.status import HTTP_403_FORBIDDEN, HTTP_404_NOT_FOUND
+
+from fastapi_utils.api_model import APIMessage, APIModel
+from fastapi_utils.guid_type import GUID
+
+# Begin setup
+UserID = NewType("UserID", UUID)
+ItemID = NewType("ItemID", UUID)
+
+Base = declarative_base()
+
+
+class ItemORM(Base):
+    __tablename__ = "item"
+
+    item_id = sa.Column(GUID, primary_key=True)
+    owner = sa.Column(GUID, nullable=False)
+    name = sa.Column(sa.String, nullable=False)
+
+
+class ItemCreate(APIModel):
+    name: str
+
+
+class ItemInDB(ItemCreate):
+    item_id: ItemID
+    owner: UserID
+
+
+def get_jwt_user(authorization: str = Header(...)) -> UserID:
+    """ Pretend this function gets a UserID from a JWT in the auth header """
+
+
+def get_db() -> Session:
+    """ Pretend this function returns a SQLAlchemy ORM session"""
+
+
+def get_owned_item(session: Session, owner: UserID, item_id: ItemID) -> ItemORM:
+    item: Optional[ItemORM] = session.query(ItemORM).get(item_id)
+    if item is not None and item.owner != owner:
+        raise HTTPException(status_code=HTTP_403_FORBIDDEN)
+    if item is None:
+        raise HTTPException(status_code=HTTP_404_NOT_FOUND)
+    return item
+
+
+# End setup
+app = FastAPI()
+
+
+@app.post("/item", response_model=ItemInDB)
+def create_item(
+    *,
+    session: Session = Depends(get_db),
+    user_id: UserID = Depends(get_jwt_user),
+    item: ItemCreate,
+) -> ItemInDB:
+    item_orm = ItemORM(name=item.name, owner=user_id)
+    session.add(item_orm)
+    session.commit()
+    return ItemInDB.from_orm(item_orm)
+
+
+@app.get("/item/{item_id}", response_model=ItemInDB)
+def read_item(
+    *,
+    session: Session = Depends(get_db),
+    user_id: UserID = Depends(get_jwt_user),
+    item_id: ItemID,
+) -> ItemInDB:
+    item_orm = get_owned_item(session, user_id, item_id)
+    return ItemInDB.from_orm(item_orm)
+
+
+@app.put("/item/{item_id}", response_model=ItemInDB)
+def update_item(
+    *,
+    session: Session = Depends(get_db),
+    user_id: UserID = Depends(get_jwt_user),
+    item_id: ItemID,
+    item: ItemCreate,
+) -> ItemInDB:
+    item_orm = get_owned_item(session, user_id, item_id)
+    item_orm.name = item.name
+    session.add(item_orm)
+    session.commit()
+    return ItemInDB.from_orm(item_orm)
+
+
+@app.delete("/item/{item_id}", response_model=APIMessage)
+def delete_item(
+    *,
+    session: Session = Depends(get_db),
+    user_id: UserID = Depends(get_jwt_user),
+    item_id: ItemID,
+) -> APIMessage:
+    item = get_owned_item(session, user_id, item_id)
+    session.delete(item)
+    session.commit()
+    return APIMessage(detail=f"Deleted item {item_id}")

docs/src/class_based_views2.py

@@ -0,0 +1,97 @@
+from typing import NewType, Optional
+from uuid import UUID
+
+import sqlalchemy as sa
+from fastapi import Depends, FastAPI, Header, HTTPException
+from sqlalchemy.ext.declarative import declarative_base
+from sqlalchemy.orm import Session
+from starlette.status import HTTP_403_FORBIDDEN, HTTP_404_NOT_FOUND
+
+from fastapi_utils.api_model import APIMessage, APIModel
+from fastapi_utils.cbv import cbv
+from fastapi_utils.guid_type import GUID
+
+# Begin Setup
+from fastapi_utils.inferring_router import InferringRouter
+
+UserID = NewType("UserID", UUID)
+ItemID = NewType("ItemID", UUID)
+
+Base = declarative_base()
+
+
+class ItemORM(Base):
+    __tablename__ = "item"
+
+    item_id = sa.Column(GUID, primary_key=True)
+    owner = sa.Column(GUID, nullable=False)
+    name = sa.Column(sa.String, nullable=False)
+
+
+class ItemCreate(APIModel):
+    name: str
+    owner: UserID
+
+
+class ItemInDB(ItemCreate):
+    item_id: ItemID
+
+
+def get_jwt_user(authorization: str = Header(...)) -> UserID:
+    """ Pretend this function gets a UserID from a JWT in the auth header """
+
+
+def get_db() -> Session:
+    """ Pretend this function returns a SQLAlchemy ORM session"""
+
+
+def get_owned_item(session: Session, owner: UserID, item_id: ItemID) -> ItemORM:
+    item: Optional[ItemORM] = session.query(ItemORM).get(item_id)
+    if item is not None and item.owner != owner:
+        raise HTTPException(status_code=HTTP_403_FORBIDDEN)
+    if item is None:
+        raise HTTPException(status_code=HTTP_404_NOT_FOUND)
+    return item
+
+
+# End Setup
+app = FastAPI()
+router = InferringRouter()  # Step 1: Create a router
+
+
+@cbv(router)  # Step 2: Create and decorate a class to hold the endpoints
+class ItemCBV:
+    # Step 3: Add dependencies as class attributes
+    session: Session = Depends(get_db)
+    user_id: UserID = Depends(get_jwt_user)
+
+    @router.post("/item")
+    def create_item(self, item: ItemCreate) -> ItemInDB:
+        # Step 4: Use `self.<dependency_name>` to access shared dependencies
+        item_orm = ItemORM(name=item.name, owner=self.user_id)
+        self.session.add(item_orm)
+        self.session.commit()
+        return ItemInDB.from_orm(item_orm)
+
+    @router.get("/item/{item_id}")
+    def read_item(self, item_id: ItemID) -> ItemInDB:
+        item_orm = get_owned_item(self.session, self.user_id, item_id)
+        return ItemInDB.from_orm(item_orm)
+
+    @router.put("/item/{item_id}")
+    def update_item(self, item_id: ItemID, item: ItemCreate) -> ItemInDB:
+        item_orm = get_owned_item(self.session, self.user_id, item_id)
+        item_orm.name = item.name
+        self.session.add(item_orm)
+        self.session.commit()
+        return ItemInDB.from_orm(item_orm)
+
+    @router.delete("/item/{item_id}")
+    def delete_item(self, item_id: ItemID) -> APIMessage:
+        item = get_owned_item(self.session, self.user_id, item_id)
+        self.session.delete(item)
+        self.session.commit()
+        return APIMessage(detail=f"Deleted item {item_id}")
+
+
+app.include_router(router)

docs/src/inferring_router1.py

@@ -3,7 +3,16 @@
 app = FastAPI()
 
 
-@app.get("/resource")
+@app.get("/default")
 def get_resource(resource_id: int) -> str:
     # the response will be serialized as a JSON number, *not* a string
     return resource_id
+
+
+def get_response_schema(openapi_spec, endpoint_path):
+    responses = openapi_spec["paths"][endpoint_path]["get"]["responses"]
+    return responses["200"]["content"]["application/json"]["schema"]
+
+
+openapi_spec = app.openapi()
+assert get_response_schema(openapi_spec, "/default") == {}

docs/src/inferring_router2.py

@@ -5,7 +5,7 @@
 app = FastAPI()
 
 
-@app.get("/resource")
+@app.get("/default")
 def get_resource(resource_id: int) -> str:
     # the response will be serialized as a JSON number, *not* a string
     return resource_id
@@ -14,20 +14,20 @@ def get_resource(resource_id: int) -> str:
 router = InferringRouter()
 
 
-@router.get("/inferred-resource")
+@router.get("/inferred")
 def get_resource(resource_id: int) -> str:
-    # thanks to InferringRouter, the response *will* be serialized as a JSON string
+    # thanks to InferringRouter, the response will be serialized as a string
     return resource_id
 
 
 app.include_router(router)
-openapi_paths = app.openapi()["paths"]
-resource_response_schema = (
-    openapi_paths["/resource"]["get"]["responses"]["200"]["content"]["application/json"]["schema"]
-)
-assert resource_response_schema == {}
-
-inferred_resource_response_schema = (
-    openapi_paths["/inferred-resource"]["get"]["responses"]["200"]["content"]["application/json"]["schema"]
-)
-assert inferred_resource_response_schema["type"] == "string"
+
+
+def get_response_schema(openapi_spec, endpoint_path):
+    responses = openapi_spec["paths"][endpoint_path]["get"]["responses"]
+    return responses["200"]["content"]["application/json"]["schema"]
+
+
+openapi_spec = app.openapi()
+assert get_response_schema(openapi_spec, "/default") == {}
+assert get_response_schema(openapi_spec, "/inferred")["type"] == "string"

docs/src/openapi1.py

@@ -8,5 +8,6 @@ def get_resource(resource_id: int) -> int:
     return resource_id
 
 
-operation_id = app.openapi()["paths"]["/api/v1/resource/{resource_id}"]["get"]["operationId"]
+path_spec = app.openapi()["paths"]["/api/v1/resource/{resource_id}"]
+operation_id = path_spec["get"]["operationId"]
 assert operation_id == "get_resource_api_v1_resource__resource_id__get"

docs/src/openapi2.py

@@ -12,5 +12,6 @@ def get_resource(resource_id: int) -> int:
 
 simplify_operation_ids(app)
 
-operation_id = app.openapi()["paths"]["/api/v1/resource/{resource_id}"]["get"]["operationId"]
+path_spec = app.openapi()["paths"]["/api/v1/resource/{resource_id}"]
+operation_id = path_spec["get"]["operationId"]
 assert operation_id == "get_resource"

docs/user-guide/basics/api-model.md

@@ -54,6 +54,6 @@ In addition, if you set the `response_model` argument to the endpoint decorator
 be converted to a dict, but has appropriately named fields, FastAPI will use pydantic's `orm_mode` to automatically
 serialize it.
 
-```python hl_lines="29 30 31"
+```python hl_lines="30 32"
 {!./src/api_model.py!}
 ```

docs/user-guide/class-based-views.md

@@ -1 +1,50 @@
-Coming soon!
+As you create more complex FastAPI applications, you may find yourself
+frequently repeating the same dependencies in multiple related endpoints.
+
+A common question people have as they become more comfortable with FastAPI
+is how they can reduce the number of times they have to copy/paste the same dependency
+into related routes.
+
+`fastapi_utils` provides a "class-based view" decorator (`@cbv`) to help reduce the amount of boilerplate
+necessary when developing related routes.
+
+## A basic CRUD app
+
+Consider a basic create-read-update-delete (CRUD) app where users can create "Item" instances,
+but only the user that created an item is allowed to view or modify it:
+
+```python hl_lines="61 62 74 75 85 86 100 101"
+{!./src/class_based_views1.py!}
+```
+
+If you look at the highlighted lines above, you can see `get_db`
+and `get_jwt_user` repeated in each endpoint.
+
+
+## The `@cbv` decorator
+
+By using the `fastapi_utils.cbv.cbv` decorator, we can consolidate the
+endpoint signatures and reduce the number of repeated dependencies.
+
+To use the `@cbv` decorator, you need to:
+
+1. Create an APIRouter to which you will add the endpoints
+2. Create a class whose methods will be endpoints with shared depedencies, and decorate it with `@cbv(router)`
+3. For each shared dependency, add a class attribute with a value of type `Depends`
+4. Replace use of the original "unshared" dependencies with accesses like `self.dependency` 
+
+Let's follow these steps to simplify the example above, while preserving all of the original logic:
+
+```python hl_lines="59 62 64 65 66 70 71 72"
+{!./src/class_based_views2.py!}
+```
+
+The highlighted lines above show the results of performing each of the numbered steps.
+
+Note how the signature of each endpoint definition now includes only the parts specific
+to that endpoint. 
+
+(Also note that we've also used the [`InferringRouter`](inferring-router.md){.internal-link target=_blank}
+here to remove the need to specify a `response_model` in the endpoint decorators.)
+
+Hopefully this helps you to better reuse dependencies across endpoints!