refactor-fastapi_skill

Overview

This skill refactors FastAPI/Python code to improve maintainability, readability, and adherence to best practices. It transforms working code into idiomatic FastAPI, applying Pydantic v2 patterns, SOLID principles, and clear async/sync boundaries. The result is skinny route handlers, testable services, and consistent project structure.

How this skill works

I inspect route handlers, Pydantic models, dependency usage, and I/O patterns to locate smells: business logic in routes, blocking calls inside async functions, duplicated code, and Pydantic v1 patterns. I then extract services, repositories, and dependencies; convert models to Pydantic v2 idioms; add precise type hints; and reorganize routers by domain. Changes aim to be incremental and safe for existing behavior.

When to use it

• Routes contain business logic or long handlers (>25 lines).
• Async endpoints call blocking libraries (time.sleep, blocking DB drivers).
• Code uses Pydantic v1 patterns or mixed v1/v2 styles.
• Project shows duplicated logic across handlers or modules.
• Missing dependency injection, hard-to-test functions, or monolithic routers.

Best practices

• Keep routes thin: validate input, call services, return responses.
• Use async only with async I/O libraries; prefer def for blocking operations.
• Adopt Pydantic v2: model_config, Annotated Fields, field_validator/model_validator.
• Extract repositories and services; follow SRP and DI via Depends.
• Organize code by domain (router, service, repository, schemas, dependencies).

Example use cases

• Convert a route with embedded DB queries into a route that Depends on a repository and service.
• Replace time.sleep in an async endpoint with await asyncio.sleep or make the handler sync.
• Migrate models from Pydantic v1 Config class to v2 model_config and Annotated fields.
• Introduce background tasks for fire-and-forget email sending after user creation.
• Add a lifespan context to initialize and close database and redis connections.