FastAPI

https://fastapi.tiangolo.com/reference/
Admin
FastAPI is a modern Python web framework for building fast APIs with automatic interactive...
Tokens:240,227
Snippets:1,512
Trust Score:9
Update:1 day ago
Show doc for...
Tokens:
Raw
### FastAPI GET path operation example

Source: https://fastapi.tiangolo.com/reference/fastapi/

Example from the get() method documentation showing how to define a GET endpoint that returns a list of items.

```python
from fastapi import FastAPI

app = FastAPI()

@app.get("/items/")
def read_items():
    return [{"name": "Empanada"}, {"name": "Arepa"}]

```

--------------------------------

### include_router with dependencies example

Source: https://fastapi.tiangolo.com/reference/fastapi/

Example of including a router with a list of dependencies applied to all path operations.

```python
from fastapi import Depends, FastAPI

from .dependencies import get_token_header
from .internal import admin

app = FastAPI()

app.include_router(
    admin.router,
    dependencies=[Depends(get_token_header)],
)
```

--------------------------------

### Example of using @app.get()

Source: https://fastapi.tiangolo.com/reference/fastapi/

Example of adding a GET path operation with the @app.get() decorator. It defines a read_items() function that returns a list of dictionaries.

```python
from fastapi import FastAPI

app = FastAPI()

@app.get("/items/")
def read_items():
    return [{"name": "Empanada"}, {"name": "Arepa"}]
```

--------------------------------

### include_router basic example

Source: https://fastapi.tiangolo.com/reference/fastapi/

Example of including an APIRouter into the app without any options.

```python
from fastapi import FastAPI

from .users import users_router

app = FastAPI()

app.include_router(users_router)
```

--------------------------------

### Example of using @router.get

Source: https://fastapi.tiangolo.com/reference/apirouter/

Example of defining a GET path operation with the @router.get decorator. It returns a list of dictionaries and the router is included in the app.

```python
from fastapi import APIRouter, FastAPI

app = FastAPI()
router = APIRouter()

@router.get("/items/")
def read_items():
    return [{"name": "Empanada"}, {"name": "Arepa"}]

app.include_router(router)
```

--------------------------------

### FastAPI OPTIONS path operation example

Source: https://fastapi.tiangolo.com/reference/fastapi/

Example from the options() method documentation showing how to define an OPTIONS endpoint for /items/ that returns a JSON object with additions.

```python
from fastapi import FastAPI

app = FastAPI()

@app.options("/items/")
def get_item_options():
    return {"additions": ["Aji", "Guacamole"]}

```

--------------------------------

### Jinja2Templates usage example

Source: https://fastapi.tiangolo.com/reference/templating/

Example of creating a Jinja2Templates instance and using TemplateResponse to render a template.

```python
from starlette.templating import Jinja2Templates

templates = Jinja2Templates(directory="templates")

async def homepage(request: Request) -> Response:
    return templates.TemplateResponse(request, "index.html")
```

--------------------------------

### FastAPI redoc_url example

Source: https://fastapi.tiangolo.com/reference/fastapi/

Customizes the path for the alternative automatic interactive API documentation provided by ReDoc. The example sets docs_url to '/documentation' and redoc_url to 'redocumentation'.

```python
from fastapi import FastAPI

app = FastAPI(docs_url="/documentation", redoc_url="redocumentation")
```

--------------------------------

### Example: Using @router.trace

Source: https://fastapi.tiangolo.com/reference/apirouter/

A complete example showing how to create a FastAPI app, an APIRouter, and a trace endpoint. The endpoint returns None and is included in the app via app.include_router(router).

```python
from fastapi import APIRouter, FastAPI
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    description: str | None = None

app = FastAPI()
router = APIRouter()

@router.trace("/items/{item_id}")
def trace_item(item_id: str):
    return None

app.include_router(router)
```

--------------------------------

### Create a FastAPI app instance

Source: https://fastapi.tiangolo.com/reference/fastapi/

Basic example of creating a FastAPI application instance.

```python
from fastapi import FastAPI

app = FastAPI()
```

--------------------------------

### Example of using @app.middleware("http")

Source: https://fastapi.tiangolo.com/reference/fastapi/

Example from the documentation showing how to add an HTTP middleware that measures processing time and adds an X-Process-Time header. The middleware is defined as an async function that calls call_next and modifies the response.

```python
import time
from typing import Awaitable, Callable

from fastapi import FastAPI, Request, Response

app = FastAPI()


@app.middleware("http")
async def add_process_time_header(
    request: Request, call_next: Callable[[Request], Awaitable[Response]]
) -> Response:
    start_time = time.time()
    response = await call_next(request)
    process_time = time.time() - start_time
    response.headers["X-Process-Time"] = str(process_time)
    return response
```

--------------------------------

### Example: UploadFile path operation

Source: https://fastapi.tiangolo.com/reference/uploadfile/

Example FastAPI application with two endpoints: one accepting a file as bytes and another accepting an UploadFile, returning the filename.

```python
from typing import Annotated

from fastapi import FastAPI, File, UploadFile

app = FastAPI()


@app.post("/files/")
async def create_file(file: Annotated[bytes, File()]):
    return {"file_size": len(file)}


@app.post("/uploadfile/")
async def create_upload_file(file: UploadFile):
    return {"filename": file.filename}
```

--------------------------------

### include_router with deprecated example

Source: https://fastapi.tiangolo.com/reference/fastapi/

Example of including a router and marking all its path operations as deprecated.

```python
from fastapi import FastAPI

from .internal import old_api

app = FastAPI()

app.include_router(
    old_api.router,
    deprecated=True,
)
```

--------------------------------

### Nested router example

Source: https://fastapi.tiangolo.com/reference/apirouter/

Example of using include_router to nest an internal router within an app router.

```python
from fastapi import APIRouter, FastAPI

app = FastAPI()
internal_router = APIRouter()
users_router = APIRouter()

@users_router.get("/users/")
def read_users():
    return [{"name": "Rick"}, {"name": "Morty"}]

internal_router.include_router(users_router)
app.include_router(internal_router)
```

--------------------------------

### Example scope string

Source: https://fastapi.tiangolo.com/reference/security/

Example of a scope string containing multiple scopes separated by spaces, as used in the OAuth2 password flow.

```python
"items:read items:write users:read profile openid"
```

--------------------------------

### Example: send notification in background

Source: https://fastapi.tiangolo.com/reference/background/

Complete example showing how to declare a BackgroundTasks parameter in a path operation function and add a background task to write a notification to a file after the response is sent.

```python
from fastapi import BackgroundTasks, FastAPI

app = FastAPI()


def write_notification(email: str, message=""):
    with open("log.txt", mode="w") as email_file:
        content = f"notification for {email}: {message}"
        email_file.write(content)


@app.post("/send-notification/{email}")
async def send_notification(email: str, background_tasks: BackgroundTasks):
    background_tasks.add_task(write_notification, email, message="some notification")
    return {"message": "Notification sent in the background"}
```

--------------------------------

### HTTPBasic usage example with FastAPI

Source: https://fastapi.tiangolo.com/reference/security/

Example of using HTTPBasic as a dependency to protect an endpoint. The dependency returns HTTPBasicCredentials with username and password.

```python
from typing import Annotated

from fastapi import Depends, FastAPI
from fastapi.security import HTTPBasic, HTTPBasicCredentials

app = FastAPI()

security = HTTPBasic()


@app.get("/users/me")
def read_current_user(credentials: Annotated[HTTPBasicCredentials, Depends(security)]):
    return {"username": credentials.username, "password": credentials.password}
```

--------------------------------

### Using app.frontend() in app/main.py

Source: https://fastapi.tiangolo.com/reference/fastapi/

Example of using the frontend() method in a FastAPI app. It mounts the frontend build from the 'dist' directory at the root path.

```python
from fastapi import FastAPI

app = FastAPI()
app.frontend("/", directory="dist")
```

--------------------------------

### FastAPI docs_url example

Source: https://fastapi.tiangolo.com/reference/fastapi/

Customizes the path for the automatic interactive API documentation (Swagger UI). The example sets docs_url to '/documentation' and disables redoc_url by setting it to None.

```python
from fastapi import FastAPI

app = FastAPI(docs_url="/documentation", redoc_url=None)
```

--------------------------------

### WebSocket endpoint example

Source: https://fastapi.tiangolo.com/reference/fastapi/

Example of using the @app.websocket decorator to create a WebSocket endpoint that echoes received text messages.

```python
from fastapi import FastAPI, WebSocket

app = FastAPI()

@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()
    while True:
        data = await websocket.receive_text()
        await websocket.send_text(f"Message text was: {data}")
```

--------------------------------

### APIRouter.post() example

Source: https://fastapi.tiangolo.com/reference/apirouter/

Example of using the post() method to add a POST path operation. It defines an Item model, creates a FastAPI app and router, adds a route that creates an item, and includes the router in the app.

```python
from fastapi import APIRouter, FastAPI
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    description: str | None = None

app = FastAPI()
router = APIRouter()

@router.post("/items/")
def create_item(item: Item):
    return {"message": "Item created"}

app.include_router(router)
```

--------------------------------

### TrustedHostMiddleware __init__ source code

Source: https://fastapi.tiangolo.com/reference/middleware/

Source code for the __init__ method. It validates allowed_hosts patterns, asserting that wildcards only appear at the start and that patterns starting with '*' must be '*.' unless it's just '*'. It sets the app, allowed_hosts, allow_any, and www_redirect attributes.

```python
def __init__(
    self,
    app: ASGIApp,
    allowed_hosts: Sequence[str] | None = None,
    www_redirect: bool = True,
) -> None:
    if allowed_hosts is None:
        allowed_hosts = ["*"]

    for pattern in allowed_hosts:
        assert "*" not in pattern[1:], ENFORCE_DOMAIN_WILDCARD
        if pattern.startswith("*") and pattern != "*":
            assert pattern.startswith("*."), ENFORCE_DOMAIN_WILDCARD
    self.app = app
    self.allowed_hosts = list(allowed_hosts)
    self.allow_any = "*" in allowed_hosts
    self.www_redirect = www_redirect
```

--------------------------------

### Set API summary

Source: https://fastapi.tiangolo.com/reference/fastapi/

Example of setting the summary parameter for the API.

```python
from fastapi import FastAPI

app = FastAPI(summary="Deadpond's favorite app. Nuff said.")
```

--------------------------------

### FastAPI PUT path operation example

Source: https://fastapi.tiangolo.com/reference/fastapi/

Example from the put() method documentation showing how to define a PUT endpoint that replaces an item using a Pydantic model.

```python
from fastapi import FastAPI
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    description: str | None = None

app = FastAPI()

@app.put("/items/{item_id}")
def replace_item(item_id: str, item: Item):
    return {"message": "Item replaced", "id": item_id}

```

--------------------------------

### Set API version

Source: https://fastapi.tiangolo.com/reference/fastapi/

Example of setting the version parameter for the API.

```python
from fastapi import FastAPI

app = FastAPI(version="0.0.1")
```

--------------------------------

### APIRouter usage example

Source: https://fastapi.tiangolo.com/reference/apirouter/

Example showing how to create an APIRouter, define a path operation with the @router.get decorator, and include the router in a FastAPI app. This is useful for structuring an application into multiple files.

```python
from fastapi import APIRouter, FastAPI

app = FastAPI()
router = APIRouter()


@router.get("/users/", tags=["users"])
async def read_users():
    return [{"username": "Rick"}, {"username": "Morty"}]


app.include_router(router)
```

--------------------------------

### FastAPI @app.head decorator example

Source: https://fastapi.tiangolo.com/reference/fastapi/

Example from the FastAPI docs for adding a HEAD path operation. Sets a custom response header and returns a 204 status code.

```python
from fastapi import FastAPI, Response

app = FastAPI()

@app.head("/items/", status_code=204)
def get_items_headers(response: Response):
    response.headers["X-Cat-Dog"] = "Alone in the world"

```

--------------------------------

### Set API description with Markdown

Source: https://fastapi.tiangolo.com/reference/fastapi/

Example of setting the description parameter with Markdown content.

```python
from fastapi import FastAPI

app = FastAPI(
    description="""
                ChimichangApp API helps you do awesome stuff. 🚀

                ## Items

                You can **read items**.

                ## Users

                You will be able to:

                * **Create users** (_not implemented_).
                * **Read users** (_not implemented_).

                """
)
```

--------------------------------

### FastAPI dependencies example

Source: https://fastapi.tiangolo.com/reference/fastapi/

Adds global dependencies that are applied to each path operation, including sub-routers. The example imports func_dep_1 and func_dep_2 from a local dependencies module and passes them via Depends.

```python
from fastapi import Depends, FastAPI

from .dependencies import func_dep_1, func_dep_2

app = FastAPI(dependencies=[Depends(func_dep_1), Depends(func_dep_2)])
```

--------------------------------

### Import GZipMiddleware from fastapi

Source: https://fastapi.tiangolo.com/reference/middleware/

Shows how to import GZipMiddleware from fastapi.

```python
from fastapi.middleware.gzip import GZipMiddleware
```

--------------------------------

### Set API title

Source: https://fastapi.tiangolo.com/reference/fastapi/

Example of setting the title parameter for the API.

```python
from fastapi import FastAPI

app = FastAPI(title="ChimichangApp")
```

--------------------------------

### Using fastapi.Path with Annotated for a path parameter

Source: https://fastapi.tiangolo.com/reference/parameters/

Example of declaring a path parameter with metadata using fastapi.Path inside Annotated. The parameter is required and the title is set to 'The ID of the item to get'.

```python
from typing import Annotated

from fastapi import FastAPI, Path

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    item_id: Annotated[int, Path(title="The ID of the item to get")],
):
    return {"item_id": item_id}
```

--------------------------------

### get method signature

Source: https://fastapi.tiangolo.com/reference/testclient/

Signature of the get method. Sends a GET request. Parameters are the same as httpx.request.

```python
get(
    url,
    *,
    params=None,
    headers=None,
    cookies=None,
    auth=USE_CLIENT_DEFAULT,
    follow_redirects=USE_CLIENT_DEFAULT,
    timeout=USE_CLIENT_DEFAULT,
    extensions=None
)
```

--------------------------------

### get

Source: https://fastapi.tiangolo.com/reference/testclient/

Sends a GET request. This is a convenience method that delegates to the request method with the HTTP method set to 'GET'.

```APIDOC
## get

### Description
Sends a `GET` request. This is a convenience method that delegates to the `request` method with the HTTP method set to `GET`.

### Method
get

### Signature
```
get(
    url,
    *,
    params=None,
    headers=None,
    cookies=None,
    auth=USE_CLIENT_DEFAULT,
    follow_redirects=USE_CLIENT_DEFAULT,
    timeout=USE_CLIENT_DEFAULT,
    extensions=None
)
```

### Parameters
- **url** (URL | str) - Required - The URL to send the request to.
- **params** (QueryParamTypes | None) - Optional - Query parameters to include in the request.
- **headers** (HeaderTypes | None) - Optional - Headers to include in the request.
- **cookies** (CookieTypes | None) - Optional - Cookies to include in the request.
- **auth** (AuthTypes | UseClientDefault | None) - Optional - Authentication credentials. Defaults to USE_CLIENT_DEFAULT.
- **follow_redirects** (bool | UseClientDefault) - Optional - Whether to follow redirects. Defaults to USE_CLIENT_DEFAULT.
- **timeout** (TimeoutTypes | UseClientDefault) - Optional - Timeout configuration. Defaults to USE_CLIENT_DEFAULT.
- **extensions** (RequestExtensions | None) - Optional - Request extensions.

### Returns
- **Response** - The response object.

### Source Code
```python
def get(
    self,
    url: URL | str,
    *,
    params: QueryParamTypes | None = None,
    headers: HeaderTypes | None = None,
    cookies: CookieTypes | None = None,
    auth: AuthTypes | UseClientDefault | None = USE_CLIENT_DEFAULT,
    follow_redirects: bool | UseClientDefault = USE_CLIENT_DEFAULT,
    timeout: TimeoutTypes | UseClientDefault = USE_CLIENT_DEFAULT,
    extensions: RequestExtensions | None = None,
) -> Response:
    """
    Send a `GET` request.

    **Parameters**: See `httpx.request`.
    """
    return self.request(
        "GET",
        url,
        params=params,
        headers=headers,
        cookies=cookies,
        auth=auth,
        follow_redirects=follow_redirects,
        timeout=timeout,
        extensions=extensions,
    )
```
```

--------------------------------

### get method source code

Source: https://fastapi.tiangolo.com/reference/testclient/

Source code of the get method from httpx/_client.py. It delegates to self.request with the HTTP method 'GET' and passes all parameters through.

```python
def get(
    self,
    url: URL | str,
    *,
    params: QueryParamTypes | None = None,
    headers: HeaderTypes | None = None,
    cookies: CookieTypes | None = None,
    auth: AuthTypes | UseClientDefault | None = USE_CLIENT_DEFAULT,
    follow_redirects: bool | UseClientDefault = USE_CLIENT_DEFAULT,
    timeout: TimeoutTypes | UseClientDefault = USE_CLIENT_DEFAULT,
    extensions: RequestExtensions | None = None,
) -> Response:
    """
    Send a `GET` request.

    **Parameters**: See `httpx.request`.
    """
    return self.request(
        "GET",
        url,
        params=params,
        headers=headers,
        cookies=cookies,
        auth=auth,
        follow_redirects=follow_redirects,
        timeout=timeout,
        extensions=extensions,
    )
```

--------------------------------

### get method signature

Source: https://fastapi.tiangolo.com/reference/apirouter/

Signature of the get method. It adds a path operation for HTTP GET requests and accepts many optional parameters such as response_model, status_code, tags, dependencies, and more.

```python
get(
    path,
    *,
    response_model=Default(None),
    status_code=None,
    tags=None,
    dependencies=None,
    summary=None,
    description=None,
    response_description="Successful Response",
    responses=None,
    deprecated=None,
    operation_id=None,
    response_model_include=None,
    response_model_exclude=None,
    response_model_by_alias=True,
    response_model_exclude_unset=False,
    response_model_exclude_defaults=False,
    response_model_exclude_none=False,
    include_in_schema=True,
    response_class=Default(JSONResponse),
    name=None,
    callbacks=None,
    openapi_extra=None,
    generate_unique_id_function=Default(generate_unique_id)
)
```

--------------------------------

### Typical project structure for frontend

Source: https://fastapi.tiangolo.com/reference/apirouter/

Shows a typical project layout with a pyproject.toml, an app package, and a dist directory containing static files. This structure is used with the frontend method to serve the build.

```text
.
├── pyproject.toml
├── app
│   ├── __init__.py
│   └── main.py
└── dist
    ├── index.html
    └── assets
        └── app.js
```

--------------------------------

### FastAPI servers example

Source: https://fastapi.tiangolo.com/reference/fastapi/

Specifies a list of servers for the OpenAPI schema. Each server dict contains a url and optional description. Useful when the app is served from different domains.

```python
from fastapi import FastAPI

app = FastAPI(
    servers=[
        {"url": "https://stag.example.com", "description": "Staging environment"},
        {"url": "https://prod.example.com", "description": "Production environment"},
    ]
)
```

--------------------------------

### FastAPI default_response_class example

Source: https://fastapi.tiangolo.com/reference/fastapi/

Sets the default response class for the application. The example uses ORJSONResponse from fastapi.responses.

```python
from fastapi import FastAPI
from fastapi.responses import ORJSONResponse

app = FastAPI(default_response_class=ORJSONResponse)
```

--------------------------------

### wait_startup signature

Source: https://fastapi.tiangolo.com/reference/testclient/

Signature of the wait_startup async method.

```python
wait_startup()
```

--------------------------------

### wait_startup

Source: https://fastapi.tiangolo.com/reference/testclient/

Waits for the application startup to complete. It sends the lifespan.startup message and asserts that the startup completes or fails.

```APIDOC
## wait_startup

### Description
Waits for the application startup to complete. It sends the lifespan.startup message and asserts that the startup completes or fails.

### Method
async

### Endpoint
wait_startup()

### Parameters
None

### Request Example
```python
await client.wait_startup()
```

### Response
#### Success Response (200)
None
```

--------------------------------

### WebSocket endpoint example

Source: https://fastapi.tiangolo.com/reference/apirouter/

Example of using @router.websocket to create a WebSocket endpoint that echoes received text messages.

```python
from fastapi import APIRouter, FastAPI, WebSocket

app = FastAPI()
router = APIRouter()

@router.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()
    while True:
        data = await websocket.receive_text()
        await websocket.send_text(f"Message text was: {data}")

app.include_router(router)
```

--------------------------------

### APIKeyCookie usage example

Source: https://fastapi.tiangolo.com/reference/security/

Example of using APIKeyCookie as a dependency. The dependency result is a string containing the cookie value.

```python
from fastapi import Depends, FastAPI
from fastapi.security import APIKeyCookie

app = FastAPI()

cookie_scheme = APIKeyCookie(name="session")


@app.get("/items/")
async def read_items(session: str = Depends(cookie_scheme)):
    return {"session": session}
```

--------------------------------

### StaticFiles.get_directories implementation

Source: https://fastapi.tiangolo.com/reference/staticfiles/

Builds a list of directories from the directory argument and each package, resolving package static directories and asserting they exist.

```python
def get_directories(
    self,
    directory: PathLike | None = None,
    packages: list[str | tuple[str, str]] | None = None,
) -> list[PathLike]:
    """
    Given `directory` and `packages` arguments, return a list of all the
    directories that should be used for serving static files from.
    """
    directories = []
    if directory is not None:
        directories.append(directory)

    for package in packages or []:
        if isinstance(package, tuple):
            package, statics_dir = package
        else:
            statics_dir = "statics"
        spec = importlib.util.find_spec(package)
        assert spec is not None, f"Package {package!r} could not be found."
        assert spec.origin is not None, f"Package {package!r} could not be found."
        package_directory = os.path.normpath(os.path.join(spec.origin, "..", statics_dir))
        assert os.path.isdir(package_directory), (
            f"Directory '{statics_dir!r}' in package {package!r} could not be found."
        )
        directories.append(package_directory)

    return directories
```

--------------------------------

### get

Source: https://fastapi.tiangolo.com/reference/fastapi/

Adds a path operation using an HTTP GET operation. This decorator is used to define endpoints that retrieve resources.

```APIDOC
## GET

### Description
Adds a path operation using an HTTP GET operation.

### Method
GET

### Endpoint
`{path}` (provided as the first argument)

### Parameters
#### Path Parameters
- `path` (str) - Required - The URL path for the operation.

#### Query Parameters
- `response_model` (Any) - Optional - The type used for the response. Default: `None`.
- `status_code` (int | None) - Optional - Default status code for the response. Default: `None`.
- `tags` (list[str | Enum] | None) - Optional - List of tags for the operation. Default: `None`.
- `dependencies` (Sequence[Depends] | None) - Optional - List of dependencies. Default: `None`.
- `summary` (str | None) - Optional - Summary of the operation.
- `description` (str | None) - Optional - Description of the operation.
- `response_description` (str) - Optional - Description of the response. Default: `"Successful Response"`.
- `responses` (dict | None) - Optional - Additional responses.
- `deprecated` (bool | None) - Optional - Mark as deprecated.
- `operation_id` (str | None) - Optional - Unique operation ID.
- `response_model_include` (set[str] | None) - Optional - Fields to include in the response.
- `response_model_exclude` (set[str] | None) - Optional - Fields to exclude from the response.
- `response_model_by_alias` (bool) - Optional - Use aliases in response. Default: `True`.
- `response_model_exclude_unset` (bool) - Optional - Exclude unset fields. Default: `False`.
- `response_model_exclude_defaults` (bool) - Optional - Exclude fields with default values. Default: `False`.
- `response_model_exclude_none` (bool) - Optional - Exclude None fields. Default: `False`.
- `include_in_schema` (bool) - Optional - Include in OpenAPI schema. Default: `True`.
- `response_class` (type) - Optional - Response class. Default: `JSONResponse`.
- `name` (str | None) - Optional - Name of the operation.
- `callbacks` (list | None) - Optional - Callbacks.
- `openapi_extra` (dict | None) - Optional - Extra OpenAPI fields.
- `generate_unique_id_function` (callable) - Optional - Function to generate unique IDs. Default: `generate_unique_id`.

### Request Example
```python
from fastapi import FastAPI

app = FastAPI()

@app.get("/items/")
def read_items():
    return [{"name": "Empanada"}, {"name": "Arepa"}]
```

### Response
#### Success Response (200)
- Returns the response model serialized as JSON.

#### Response Example
```json
[{"name": "Empanada"}, {"name": "Arepa"}]
```
```

--------------------------------

### wait_startup source code

Source: https://fastapi.tiangolo.com/reference/testclient/

Source code for the wait_startup async method. It sends a lifespan.startup message and waits for the startup complete or failed message, raising the task result if the message is None.

```python
async def wait_startup(self) -> None:
    await self.stream_receive.send({"type": "lifespan.startup"})

    async def receive() -> Any:
        message = await self.stream_send.receive()
        if message is None:
            self.task.result()
        return message

    message = await receive()
    assert message["type"] in (
        "lifespan.startup.complete",
        "lifespan.startup.failed",
    )
    if message["type"] == "lifespan.startup.failed":
        await receive()
```

--------------------------------

### APIKeyQuery usage example

Source: https://fastapi.tiangolo.com/reference/security/

Example of using APIKeyQuery as a dependency to extract the API key from a query parameter named 'api_key'.

```python
from fastapi import Depends, FastAPI
from fastapi.security import APIKeyQuery

app = FastAPI()

query_scheme = APIKeyQuery(name="api_key")


@app.get("/items/")
async def read_items(api_key: str = Depends(query_scheme)):
    return {"api_key": api_key}
```

--------------------------------

### APIKeyHeader usage example

Source: https://fastapi.tiangolo.com/reference/security/

Example of using APIKeyHeader as a dependency in FastAPI. It extracts the key from the 'x-key' header and returns it in the response.

```python
from fastapi import Depends, FastAPI
from fastapi.security import APIKeyHeader

app = FastAPI()

header_scheme = APIKeyHeader(name="x-key")


@app.get("/items/")
async def read_items(key: str = Depends(header_scheme)):
    return {"key": key}
```

--------------------------------

### APIRouter.get

Source: https://fastapi.tiangolo.com/reference/apirouter/

Adds a path operation using an HTTP GET operation. This method is used to register a route that handles GET requests.

```APIDOC
## APIRouter.get

### Description
Adds a *path operation* using an HTTP GET operation. This method is used to register a route that handles GET requests.

### Method
GET

### Endpoint
`{path}` - The path is provided as the first argument to the method.

### Parameters
#### Path Parameters
- **path** (str) - Required - The URL path to be used for this *path operation*. For example, in `http://example.com/items`, the path is `/items`.

#### Query Parameters
- **response_model** (Any) - Optional - The type to use for the response. It could be any valid Pydantic *field* type. So, it doesn't have to be a Pydantic model, it could be other things, like a `list`, `dict`, etc.
- **status_code** (int) - Optional - The status code to use for the response.
- **tags** (list[str]) - Optional - A list of tags to be applied to the *path operation*.
- **dependencies** (list[Depends]) - Optional - A list of dependencies to be applied to the *path operation*.
- **summary** (str) - Optional - A summary for the *path operation*.
- **description** (str) - Optional - A description for the *path operation*.
- **response_description** (str) - Optional - The description for the default response.
- **responses** (dict) - Optional - Additional responses.
- **deprecated** (bool) - Optional - Whether the *path operation* is deprecated.
- **operation_id** (str) - Optional - An operation ID for the *path operation*.
- **response_model_include** (set[str]) - Optional - A set of field names to include in the response.
- **response_model_exclude** (set[str]) - Optional - A set of field names to exclude from the response.
- **response_model_by_alias** (bool) - Optional - Whether to use field aliases in the response.
- **response_model_exclude_unset** (bool) - Optional - Whether to exclude unset fields from the response.
- **response_model_exclude_defaults** (bool) - Optional - Whether to exclude fields with default values from the response.
- **response_model_exclude_none** (bool) - Optional - Whether to exclude fields with `None` values from the response.
- **include_in_schema** (bool) - Optional - Whether to include the *path operation* in the OpenAPI schema.
- **response_class** (type) - Optional - The response class to use for the response.
- **name** (str) - Optional - Name for this *path operation*. Only used internally.
- **callbacks** (list[BaseRoute]) - Optional - List of *path operations* that will be used as OpenAPI callbacks.
- **openapi_extra** (dict) - Optional - Extra metadata to be included in the OpenAPI schema for this *path operation*.
- **generate_unique_id_function** (Callable) - Optional - Customize the function used to generate unique IDs for the *path operations* shown in the generated OpenAPI.

### Request Example
```python
from fastapi import APIRouter, FastAPI

app = FastAPI()
router = APIRouter()

@router.get("/items/")
def read_items():
    return [{"name": "Empanada"}, {"name": "Arepa"}]

app.include_router(router)
```

### Response
#### Success Response (200)
- **response** (Any) - The response body, which is the return value of the decorated function.

#### Response Example
```json
[{"name": "Empanada"}, {"name": "Arepa"}]
```
```

--------------------------------

### GZipMiddleware source code (__init__)

Source: https://fastapi.tiangolo.com/reference/middleware/

Source code for GZipMiddleware.__init__ from starlette/middleware/gzip.py. It initializes the middleware with the provided parameters and normalizes the excluded content types.

```python
def __init__(
    self,
    app: ASGIApp,
    minimum_size: int = 500,
    compresslevel: int = 9,
    thread_minimum_size: int = 128 * 1024,  # 128 KiB
    *,
    exclude_content_types: tuple[str, ...] = DEFAULT_EXCLUDED_CONTENT_TYPES,
) -> None:
    self.app = app
    self.minimum_size = minimum_size
    self.compresslevel = compresslevel
    self.thread_minimum_size = thread_minimum_size
    self.exclude_content_types = _normalize_content_types(exclude_content_types)
```

--------------------------------

### HTTPBearer usage example with Depends

Source: https://fastapi.tiangolo.com/reference/security/

Example of using HTTPBearer as a dependency. The dependency result is an HTTPAuthorizationCredentials object containing scheme and credentials.

```python
from typing import Annotated

from fastapi import Depends, FastAPI
from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer

app = FastAPI()

security = HTTPBearer()


@app.get("/users/me")
def read_current_user(
    credentials: Annotated[HTTPAuthorizationCredentials, Depends(security)]
):
    return {"scheme": credentials.scheme, "credentials": credentials.credentials}
```

--------------------------------

### FastAPI dependency example with Depends

Source: https://fastapi.tiangolo.com/reference/dependencies/

Example showing how to use Depends with a common_parameters dependency and Annotated. The dependency is called by FastAPI, not directly.

```python
from typing import Annotated

from fastapi import Depends, FastAPI

app = FastAPI()


async def common_parameters(q: str | None = None, skip: int = 0, limit: int = 100):
    return {"q": q, "skip": skip, "limit": limit}


@app.get("/items/")
async def read_items(commons: Annotated[dict, Depends(common_parameters)]):
    return commons
```

--------------------------------

### StaticFiles constructor

Source: https://fastapi.tiangolo.com/reference/staticfiles/

Creates a StaticFiles instance to serve static files. Parameters include directory, packages, html, check_dir, and follow_symlink.

```APIDOC
## StaticFiles(directory=None, packages=None, html=False, check_dir=True, follow_symlink=False)

### Description
Initializes a StaticFiles instance to serve static files from specified directories or packages.

### Parameters
- **directory** (PathLike | None) - Optional - The directory to serve static files from.
- **packages** (list[str | tuple[str, str]] | None) - Optional - A list of packages or (package, statics_dir) tuples to serve static files from.
- **html** (bool) - Optional - If True, serves index.html for directory requests.
- **check_dir** (bool) - Optional - If True, checks that the directory exists and raises RuntimeError if not.
- **follow_symlink** (bool) - Optional - If True, follows symbolic links.

### Example
```python
from fastapi.staticfiles import StaticFiles

app.mount("/static", StaticFiles(directory="static"), name="static")
```
```

--------------------------------

### Example: Raising HTTPException in a FastAPI route

Source: https://fastapi.tiangolo.com/reference/exceptions/

Example of raising HTTPException with status code 404 and a custom detail message when an item is not found.

```python
from fastapi import FastAPI, HTTPException

app = FastAPI()

items = {"foo": "The Foo Wrestlers"}


@app.get("/items/{item_id}")
async def read_item(item_id: str):
    if item_id not in items:
        raise HTTPException(status_code=404, detail="Item not found")
    return {"item": items[item_id]}
```

--------------------------------

### HTTPDigest usage example with FastAPI

Source: https://fastapi.tiangolo.com/reference/security/

Example of using HTTPDigest as a dependency in a FastAPI route. The dependency result is an HTTPAuthorizationCredentials object containing scheme and credentials.

```python
from typing import Annotated

from fastapi import Depends, FastAPI
from fastapi.security import HTTPAuthorizationCredentials, HTTPDigest

app = FastAPI()

security = HTTPDigest()


@app.get("/users/me")
def read_current_user(
    credentials: Annotated[HTTPAuthorizationCredentials, Depends(security)]
):
    return {"scheme": credentials.scheme, "credentials": credentials.credentials}
```

--------------------------------

### Import TrustedHostMiddleware from fastapi

Source: https://fastapi.tiangolo.com/reference/middleware/

Shows how to import TrustedHostMiddleware from the fastapi module.

```python
from fastapi.middleware.trustedhost import TrustedHostMiddleware
```

--------------------------------

### FastAPI TRACE path operation example

Source: https://fastapi.tiangolo.com/reference/fastapi/

Example of using the @app.trace decorator to add a TRACE path operation. It defines a trace_item function that returns None.

```python
from fastapi import FastAPI

app = FastAPI()

@app.trace("/items/{item_id}")
def trace_item(item_id: str):
    return None
```

--------------------------------

### GZipMiddleware constructor signature

Source: https://fastapi.tiangolo.com/reference/middleware/

Shows the constructor signature for GZipMiddleware with default parameters: minimum_size=500, compresslevel=9, thread_minimum_size=128*1024, and exclude_content_types=DEFAULT_EXCLUDED_CONTENT_TYPES.

```python
GZipMiddleware(
    app,
    minimum_size=500,
    compresslevel=9,
    thread_minimum_size=128 * 1024,
    *,
    exclude_content_types=DEFAULT_EXCLUDED_CONTENT_TYPES
)
```

--------------------------------

### get_directories(directory=None, packages=None)

Source: https://fastapi.tiangolo.com/reference/staticfiles/

Returns a list of all directories that should be used for serving static files, based on the directory and packages arguments.

```APIDOC
## get_directories(directory=None, packages=None)

### Description
Given `directory` and `packages` arguments, return a list of all the directories that should be used for serving static files from.

### Parameters
- **directory** (PathLike | None) - Optional - The directory to include.
- **packages** (list[str | tuple[str, str]] | None) - Optional - A list of packages or (package, statics_dir) tuples to include.

### Returns
- **list[PathLike]** - A list of directory paths.

### Example
```python
static_files = StaticFiles()
directories = static_files.get_directories(directory="static", packages=["mypackage"])
```
```

--------------------------------

### FastAPI DELETE path operation example

Source: https://fastapi.tiangolo.com/reference/fastapi/

Example from the APIRouter.delete documentation showing how to define a DELETE endpoint that takes a path parameter and returns a JSON response.

```python
from fastapi import FastAPI

app = FastAPI()

@app.delete("/items/{item_id}")
def delete_item(item_id: str):
    return {"message": "Item deleted"}

```

--------------------------------

### StaticFiles __init__ implementation

Source: https://fastapi.tiangolo.com/reference/staticfiles/

Initializes the StaticFiles instance, setting attributes and raising RuntimeError if the directory does not exist when check_dir is True.

```python
def __init__(
    self,
    *,
    directory: PathLike | None = None,
    packages: list[str | tuple[str, str]] | None = None,
    html: bool = False,
    check_dir: bool = True,
    follow_symlink: bool = False,
) -> None:
    self.directory = directory
    self.packages = packages
    self.all_directories = self.get_directories(directory, packages)
    self.html = html
    self.config_checked = False
    self.follow_symlink = follow_symlink
    if check_dir and directory is not None and not os.path.isdir(directory):
        raise RuntimeError(f"Directory '{directory}' does not exist")
```

--------------------------------

### Example usage of OAuth2PasswordRequestForm

Source: https://fastapi.tiangolo.com/reference/security/

Example FastAPI endpoint that uses OAuth2PasswordRequestForm as a dependency to collect form data. It iterates over form_data.scopes and includes client_id and client_secret if present.

```python
from typing import Annotated

from fastapi import Depends, FastAPI
from fastapi.security import OAuth2PasswordRequestForm

app = FastAPI()


@app.post("/login")
def login(form_data: Annotated[OAuth2PasswordRequestForm, Depends()]):
    data = {}
    data["scopes"] = []
    for scope in form_data.scopes:
        data["scopes"].append(scope)
    if form_data.client_id:
        data["client_id"] = form_data.client_id
    if form_data.client_secret:
        data["client_secret"] = form_data.client_secret
    return data
```

--------------------------------

### FastAPI with openapi_external_docs

Source: https://fastapi.tiangolo.com/reference/fastapi/

Shows how to pass external documentation links to the FastAPI constructor. The dictionary must contain 'description' and a valid 'url'.

```python
from fastapi import FastAPI

external_docs = {
    "description": "Detailed API Reference",
    "url": "https://example.com/api-docs",
}

app = FastAPI(openapi_external_docs=external_docs)
```

--------------------------------

### frontend(path, *, directory, fallback='auto', check_dir='auto')

Source: https://fastapi.tiangolo.com/reference/apirouter/

Serves a static frontend build as low-priority routes. FastAPI path operations are checked first, and the frontend files are checked only if no normal route matched. Use this for frontend tools that build static files into a directory, such as 'dist'.

```APIDOC
## frontend(path, *, directory, fallback='auto', check_dir='auto')

### Description
Serve a static frontend build as low-priority routes. Use this for frontend tools that build static files into a directory, such as `dist`. **FastAPI** path operations are checked first, and the frontend files are checked only if no normal route matched.

### Method
APIRouter method

### Parameters
#### Path Parameters
- **path** (str) - Required - The URL path prefix where the frontend build should be served.

#### Keyword-Only Parameters
- **directory** (str | PathLike[str]) - Required - The directory containing the static frontend build output.
- **fallback** (Literal['auto', 'index.html', '404.html'] | None) - Optional - The fallback file behavior for missing frontend paths. Default: `'auto'`.
- **check_dir** (bool | Literal['auto']) - Optional - Check that the frontend directory exists when the app is created. When set to `"auto"`, skip the check with a warning when `FASTAPI_ENV` is `"development"`, and check it otherwise. The `fastapi dev` command sets `FASTAPI_ENV` to `"development"` if it is not already set. Default: `'auto'`.

### Request Example
```python
from fastapi import APIRouter, FastAPI

app = FastAPI()
router = APIRouter()
router.frontend("/", directory="dist")
app.include_router(router)
```

### Response
No return value (None).
```

--------------------------------

### Response.init_headers(headers=None)

Source: https://fastapi.tiangolo.com/reference/responses/

Initializes the response headers, adding content-length and content-type headers as needed.

```APIDOC
## Response.init_headers(headers=None)

### Description
Initializes the response headers, adding content-length and content-type headers as needed.

### Method
init_headers

### Parameters
- **headers** (Mapping[str, str] | None) - Optional - Additional headers to include.

### Returns
- None

```

--------------------------------

### FastAPI POST path operation example

Source: https://fastapi.tiangolo.com/reference/fastapi/

Example from the APIRouter.post docstring showing how to define a POST endpoint with a Pydantic model. The endpoint returns a JSON response with a message.

```python
from fastapi import FastAPI
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    description: str | None = None

app = FastAPI()

@app.post("/items/")
def create_item(item: Item):
    return {"message": "Item created"}

```

--------------------------------

### Jinja2Templates constructor

Source: https://fastapi.tiangolo.com/reference/templating/

Initializes a Jinja2Templates instance. Requires either a directory or an env argument, but not both. Sets up the Jinja2 environment with autoescaping and optional context processors.

```APIDOC
## Jinja2Templates(directory, *, context_processors=None)

### Description
Initializes a Jinja2Templates instance. Requires either a directory or an env argument, but not both. Sets up the Jinja2 environment with autoescaping and optional context processors.

### Method
Constructor

### Parameters
#### Path Parameters
- **directory** (str | PathLike[str] | Sequence[str | PathLike[str]]) - Required - Directory or list of directories where templates are located.
- **context_processors** (list[Callable[[Request], dict[str, Any]]] | None) - Optional - List of callables that take a Request and return a dict to update the template context.
- **env** (Environment) - Optional - A pre-configured Jinja2 Environment. Mutually exclusive with directory.

### Request Example
```python
from fastapi.templating import Jinja2Templates

templates = Jinja2Templates(directory="templates")
```

### Response
#### Success Response (200)
- **Jinja2Templates instance** - The initialized template renderer.

#### Response Example
```python
# No explicit response; the instance is used to render templates.
```
```

--------------------------------

### OpenIdConnect.__init__

Source: https://fastapi.tiangolo.com/reference/security/

Constructor for the OpenIdConnect security class. Initializes the security scheme with the OpenID Connect URL, scheme name, description, and auto_error behavior.

```APIDOC
## OpenIdConnect.__init__

### Description
Initializes an OpenIdConnect security instance. This is a stub for OpenID Connect authentication and does not implement the full scheme.

### Method
Constructor

### Parameters
- **openIdConnectUrl** (str) - Required - The OpenID Connect URL.
- **scheme_name** (str | None) - Optional - Security scheme name. Included in the generated OpenAPI (e.g., visible at `/docs`). Default: `None`.
- **description** (str | None) - Optional - Security scheme description. Included in the generated OpenAPI (e.g., visible at `/docs`). Default: `None`.
- **auto_error** (bool) - Optional - If `True` (default), when no HTTP Authorization header is provided, the request is automatically cancelled and an error is sent to the client. If `False`, the dependency result will be `None` when the header is missing, enabling optional authentication. Default: `True`.

### Example
```python
from fastapi.security import OpenIdConnect

openid = OpenIdConnect(
    openIdConnectUrl="https://example.com/.well-known/openid-configuration",
    scheme_name="my_openid",
    description="OpenID Connect authentication",
    auto_error=True,
)
```
```

--------------------------------

### APIRouter.delete example usage

Source: https://fastapi.tiangolo.com/reference/apirouter/

Complete example of defining a DELETE endpoint with APIRouter and including it in a FastAPI app. The endpoint returns a JSON message and is registered with app.include_router(router).

```python
from fastapi import APIRouter, FastAPI

app = FastAPI()
router = APIRouter()

@router.delete("/items/{item_id}")
def delete_item(item_id: str):
    return {"message": "Item deleted"}

app.include_router(router)
```

--------------------------------

### Using router.frontend in app/main.py

Source: https://fastapi.tiangolo.com/reference/apirouter/

Example of using the frontend method in a FastAPI application. It creates an APIRouter, registers a frontend route for the root path serving the 'dist' directory, and includes the router in the app.

```python
from fastapi import APIRouter, FastAPI

app = FastAPI()
router = APIRouter()
router.frontend("/", directory="dist")
app.include_router(router)
```
Tokens:
Raw