.cursorrules Python FastAPI Best Practices

by @Caio Barbieri

You are an expert in Python, FastAPI, and scalable API development.

Write concise, technical responses with accurate Python examples. Use functional, declarative programming; avoid classes where possible. Prefer iteration and modularization over code duplication. Use descriptive variable names with auxiliary verbs (e.g., is_active, has_permission). Use lowercase with underscores for directories and files (e.g., routers/user_routes.py). Favor named exports for routes and utility functions. Use the Receive an Object, Return an Object (RORO) pattern. Use def for pure functions and async def for asynchronous operations. Use type hints for all function signatures. Prefer Pydantic models over raw dictionaries for input validation.

File structure: exported router, sub-routes, utilities, static content, types (models, schemas).

Avoid unnecessary curly braces in conditional statements. For single-line statements in conditionals, omit curly braces. Use concise, one-line syntax for simple conditional statements (e.g., if condition: do_something()).

Prioritize error handling and edge cases:

FastAPI
Pydantic v2
Async database libraries like asyncpg or aiomysql
SQLAlchemy 2.0 (if using ORM features)

Use functional components (plain functions) and Pydantic models for input validation and response schemas. Use declarative route definitions with clear return type annotations. Use def for synchronous operations and async def for asynchronous ones. Minimize @app.on_event("startup") and @app.on_event("shutdown"); prefer lifespan context managers for managing startup and shutdown events. Use middleware for logging, error monitoring, and performance optimization. Optimize for performance using async functions for I/O-bound tasks, caching strategies, and lazy loading. Use HTTPException for expected errors and model them as specific HTTP responses. Use middleware for handling unexpected errors, logging, and error monitoring. Use Pydantic's BaseModel for consistent input/output validation and response schemas. Minimize blocking I/O operations; use asynchronous operations for all database calls and external API requests. Implement caching for static and frequently accessed data using tools like Redis or in-memory stores. Optimize data serialization and deserialization with Pydantic. Use lazy loading techniques for large datasets and substantial API responses. Refer to FastAPI documentation for Data Models, Path Operations, and Middleware for best practices.


---
description: Defines the preferred file structure and component usage for FastAPI applications.
globs: **/main.py
---
- File structure: exported router, sub-routes, utilities, static content, types (models, schemas).
- Use functional components (plain functions) and Pydantic models for input validation and response schemas.
- Use declarative route definitions with clear return type annotations.
- Use def for synchronous operations and async def for asynchronous ones.
- Minimize @app.on_event("startup") and @app.on_event("shutdown"); prefer lifespan context managers for managing startup and shutdown events.
- Use middleware for logging, error monitoring, and performance optimization.


---
description: Specifies the preferred asynchronous database libraries and interaction patterns for FastAPI applications.
globs: **/db/**/*.py
---
- Async database libraries like asyncpg or aiomysql.
- SQLAlchemy 2.0 (if using ORM features).
- Minimize blocking I/O operations; use asynchronous operations for all database calls.


---
description: Provides a reminder to refer to the FastAPI documentation for guidance on best practices for data models, path operations, and middleware.
globs: **/routers/**/*.py
---
- Refer to FastAPI documentation for Data Models, Path Operations, and Middleware for best practices.


---
description: Defines how errors should be handled within FastAPI applications using middleware.
globs: **/middleware.py
---
- Use middleware for handling unexpected errors, logging, and error monitoring.
- Prioritize error handling and edge cases.
- Use Pydantic's BaseModel for consistent input/output validation and response schemas.


---
description: Optimizes performance in FastAPI APIs by using async functions, caching, and other techniques.
globs: **/api/**/*.py
---
- Optimize for performance using async functions for I/O-bound tasks, caching strategies, and lazy loading.
- Use HTTPException for expected errors and model them as specific HTTP responses.
- Minimize blocking I/O operations; use asynchronous operations for all database calls and external API requests.
- Implement caching for static and frequently accessed data using tools like Redis or in-memory stores.
- Optimize data serialization and deserialization with Pydantic.
- Use lazy loading techniques for large datasets and substantial API responses.


---
description: Enforces general Python coding style guidelines, including functional programming preferences and naming conventions.
globs: **/*.py
---
- Write concise, technical responses with accurate Python examples.
- Use functional, declarative programming; avoid classes where possible.
- Prefer iteration and modularization over code duplication.
- Use descriptive variable names with auxiliary verbs (e.g., is_active, has_permission).
- Use lowercase with underscores for directories and files (e.g., routers/user_routes.py).
- Favor named exports for routes and utility functions.
- Use the Receive an Object, Return an Object (RORO) pattern.
- Use def for pure functions and async def for asynchronous operations.
- Use type hints for all function signatures.
- Prefer Pydantic models over raw dictionaries for input validation.
- Avoid unnecessary curly braces in conditional statements.
- For single-line statements in conditionals, omit curly braces.
- Use concise, one-line syntax for simple conditional statements (e.g., if condition: do_something()).

FastAPI Development Toolkit

A collection of tools designed to enhance the development, performance, and scalability of FastAPI applications, focusing on asynchronous data processing, robust error handling, and efficient caching.

Core Tools

Scalable API Development Platform:
Simplifies API development with templates and modules for setting up API routes, input validation, and performance monitoring.
Async Data Processing Library:
Focuses on asynchronous data processing tasks, integrating with async libraries like asyncpg and caching mechanisms.
API Performance Analyzer:
Analyzes applications for performance bottlenecks, providing recommendations for optimizing asynchronous flows.

Validation & Error Handling

Pydantic Validation Toolkit:
Enhances Pydantic validation with advanced error handling and logging capabilities, including custom error types and validation schemas.
API Error Handling Framework:
Standardizes error handling with consistent error messages, logging strategies, and error monitoring.

Middleware & Caching Solutions

FastAPI Middleware Extensions:
Offers middleware for logging, error monitoring, and performance optimization, managing startup/shutdown events and HTTP error responses.
API Caching System:
Implements caching using tools like Redis to efficiently manage cacheable responses and static content.

Database & Route Management

Database Interaction ORM:
A lightweight ORM optimized for asynchronous database interactions using SQLAlchemy 2.0, reducing blocking operations and caching frequently accessed data.
Declarative Route Builder:
Builds FastAPI routes using a declarative syntax emphasizing type safety and modular components.
Lazy Data Loading Service:
Facilitates lazy loading of large datasets with APIs for managing paginated responses and on-demand data fetching strategies.

Key Technologies:

FastAPI
Pydantic
Asyncpg
Redis
SQLAlchemy 2.0

Overview of .cursorrules prompt

The .cursorrules file outlines best practices and guidelines for Python and FastAPI development, emphasizing scalable API solutions. It covers principles like functional and declarative programming, error handling, and performance optimization. It recommends concise and accurate Python examples, type hints, Pydantic models for validation, and asynchronous operations. Developers are encouraged to use FastAPI’s dependency injection and middleware for improved performance and maintainability, with specific focus on managing startup and shutdown processes efficiently and employing caching strategies. The file prioritizes readability, modularization, and error logging, along with leveraging FastAPI-specific features like Pydantic models for consistency.

Updated: March 17, 2025

Developers creating scalable APIs with FastAPI will benefit from this prompt to design performant, modular, and maintainable services using Python and modern asynchronous techniques.

Usefull for: