Agent-Skills.md

Agent Skills: FastAPI Advanced Patterns

Advanced FastAPI patterns including hierarchical dependency injection, background task management, and type-safe dependency annotation. Triggers: fastapi, dependency-injection, background-tasks, annotated-dependency, permission-chain.

UncategorizedID: cuba6112/skillfactory/fastapi-patterns

Repository

cuba6112/skillfactory
cuba6112

Install this agent skill to your local

pnpm dlx add-skill https://github.com/cuba6112/skillfactory/tree/HEAD/skills/fastapi-patterns

Skill Files

Browse the full folder contents for fastapi-patterns.

Download Skill

Loading file tree…

skills/fastapi-patterns/SKILL.md

Skill Metadata

Name
fastapi-patterns
Description
Advanced FastAPI patterns including hierarchical dependency injection, background task management, and type-safe dependency annotation. Triggers: fastapi, dependency-injection, background-tasks, annotated-dependency, permission-chain.

FastAPI Advanced Patterns

Overview

FastAPI leverages Python's type hints and async capabilities to provide a robust framework for building APIs. Its core strength lies in its Dependency Injection system, which allows for clean, reusable, and hierarchical code structure.

When to Use

  • Shared Logic: When multiple endpoints need the same authentication, database session, or pagination logic.
  • Offloading I/O: When a request triggers a slow operation (like sending an email) that shouldn't block the user response.
  • Complex Security: When you need multi-level permission checks (e.g., User -> Active User -> Admin).

Decision Tree

  1. Do you need the same logic in 3+ endpoints?
    • YES: Create a reusable Dependency.
  2. Does an operation take more than 50ms and doesn't return data to the user?
    • YES: Use BackgroundTasks.
  3. Do you want full IDE autocompletion for injected values?
    • YES: Use Annotated[Type, Depends(func)] syntax.

Workflows

1. Implementing Reusable Shared Logic

  1. Define a dependency function that extracts common parameters (e.g., pagination or auth).
  2. Create a type alias using Annotated[Type, Depends(dependency_function)].
  3. Inject this alias into multiple path operation functions to access the shared logic results.

2. Offloading Tasks to the Background

  1. Define a standard Python function for the slow task (e.g., sending an email).
  2. Include background_tasks: BackgroundTasks as a parameter in the API endpoint.
  3. Call background_tasks.add_task(task_function, *args) inside the endpoint.
  4. Return a response immediately to the user while the task runs in the background.

3. Hierarchical Permission Checks

  1. Create a base dependency for get_current_user.
  2. Create a sub-dependency get_active_user that depends on get_current_user.
  3. Create a final get_admin_user that depends on get_active_user.
  4. FastAPI will execute the chain in order and stop if any dependency raises an HTTPException.

Non-Obvious Insights

  • Dependency Tree Resolution: FastAPI resolves a full tree of dependencies automatically; if three different dependencies all require the same database session, FastAPI can be configured to call the session creator only once per request.
  • Annotated is Best Practice: Using Annotated keeps your code DRY (Don't Repeat Yourself) and ensures that static analysis tools understand exactly what type is being injected.
  • Flexible Background Tasks: BackgroundTasks can be declared anywhere in the dependency chain, not just in the final endpoint function.

Evidence

  • "Dependency Injection means... that there is a way for your code to declare things that it requires to work and use." - FastAPI Docs
  • "BackgroundTasks is useful for operations that need to happen after a request... client doesn't really have to be waiting." - FastAPI Docs
  • "Annotated dependencies... type information will be preserved, which means your editor will keep providing autocompletion." - FastAPI Docs

Scripts

  • scripts/fastapi-patterns_tool.py: Example of Dependency Injection and Background Tasks.
  • scripts/fastapi-patterns_tool.js: (Simulated) Pattern comparison for Node.js middleware.

Dependencies

  • fastapi
  • pydantic

References