From 596dd48a73531b44cbee75d2797468f2529fa77c Mon Sep 17 00:00:00 2001 From: Santosh Bhavani Date: Mon, 23 Feb 2026 10:12:02 -0600 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Add=20PRD.md=20and=20ROADMAP.md?= =?UTF-8?q?=20documentation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add Product Requirements Document (PRD.md) with P0-P3 user stories - Add Roadmap.md with future ideas and lessons learned - Add .specify/memory/constitution.md with FastAPI principles Co-Authored-By: Claude Opus 4.6 --- .specify/memory/constitution.md | 83 ++++++++++++++++ docs/PRD.md | 170 ++++++++++++++++++++++++++++++++ docs/ROADMAP.md | 49 +++++++++ 3 files changed, 302 insertions(+) create mode 100644 .specify/memory/constitution.md create mode 100644 docs/PRD.md create mode 100644 docs/ROADMAP.md diff --git a/.specify/memory/constitution.md b/.specify/memory/constitution.md new file mode 100644 index 0000000000..ec409c8c8b --- /dev/null +++ b/.specify/memory/constitution.md @@ -0,0 +1,83 @@ + + +# FastAPI Constitution + +## Core Principles + +### I. Standards-Based + +FastAPI MUST be built on open standards for APIs. All features MUST support OpenAPI (formerly Swagger) and JSON Schema. The framework MUST generate compliant API documentation automatically. Rationale: Ensures interoperability and automatic tooling support (client generation, documentation). + +### II. Type Safety (NON-NEGOTIABLE) + +FastAPI MUST leverage Python type hints for request validation, response serialization, and automatic documentation. Type checking MUST pass with mypy at strict level. Rationale: Catches bugs at development time, enables IDE autocomplete, powers automatic documentation. + +### III. Test-First Development + +All new features MUST have tests written before implementation. The framework MUST maintain comprehensive test coverage. Tests MUST verify both functionality and API contract compliance. Rationale: FastAPI is a framework used in production by millions; regressions are costly. + +### IV. Performance + +FastAPI MUST achieve performance comparable to NodeJS and Go frameworks. Async support MUST be first-class with no performance penalty for sync code paths. Rationale: Performance is a primary feature claim; benchmarks MUST remain competitive. + +### V. Developer Experience + +The framework MUST provide intuitive APIs with minimal boilerplate. Error messages MUST be clear and actionable. Documentation MUST include runnable examples. Rationale: "Fast to code" is a core value proposition; reduces developer cognitive load. + +## Additional Constraints + +### Technology Stack + +- **Language**: Python 3.8+ (subject to Python release support policy) +- **Core Dependencies**: Starlette for routing, Pydantic for data validation +- **Async**: First-class support for asyncio +- **Standards**: OpenAPI 3.0+, JSON Schema + +### Compatibility + +- **Python Versions**: Support Python versions according to PEP 594 +- **Breaking Changes**: Follow semantic versioning; MAJOR version bumps require deprecation warnings in prior minor releases +- **Dependencies**: Pin minimal required versions; allow compatible updates + +## Development Workflow + +### Code Quality Gates + +- All PRs MUST pass type checking (mypy --strict) +- All PRs MUST maintain or increase test coverage +- All PRs MUST include documentation for new features +- All PRs MUST pass CI/CD pipeline (lint, test, coverage) + +### Contribution Process + +1. Fork and create feature branch +2. Write tests first (must fail) +3. Implement feature +4. Ensure tests pass and coverage maintained +5. Update documentation +6. Submit PR with description + +### Release Process + +- Follow semantic versioning strictly +- Maintain changelog +- Publish release notes +- Ensure backwards compatibility within MAJOR version + +## Governance + +The FastAPI Constitution supersedes all other development practices. Amendments to this constitution MUST be documented with: + +1. Rationale for the change +2. Impact assessment on existing workflows +3. Migration plan if applicable + +All PRs and code reviews MUST verify compliance with these principles. Complexity MUST be justified against simpler alternatives. + +**Version**: 1.0.0 | **Ratified**: 2026-02-23 | **Last Amended**: 2026-02-23 diff --git a/docs/PRD.md b/docs/PRD.md new file mode 100644 index 0000000000..38310bc1ed --- /dev/null +++ b/docs/PRD.md @@ -0,0 +1,170 @@ +# PRD: FastAPI Framework + +FastAPI is a modern, high-performance Python web framework for building APIs with Python type hints. This document outlines the product requirements for the FastAPI framework itself. + +## Implementation Status + +The core framework is mature and well-established. This PRD tracks major feature initiatives and improvements beyond the stable release. + +## User Stories + +### P0: Core Framework (Must Have) — ✅ Complete + +**As a** Python developer, +**I want** to build APIs quickly using type hints, +**So that** I get automatic validation, documentation, and IDE support. + +- [P0-US1] ✅ Route definition via decorators with path parameters +- [P0-US2] ✅ Query, header, and cookie parameter extraction with type hints +- [P0-US3] ✅ Request body validation using Pydantic models +- [P0-US4] ✅ Automatic OpenAPI schema generation +- [P0-US5] ✅ Interactive API documentation (Swagger UI + ReDoc) +- [P0-US6] ✅ Dependency injection system +- [P0-US7] ✅ Error handling with custom exception handlers +- [P0-US8] ✅ Response model typing with automatic serialization + +**Acceptance Criteria:** +- All core HTTP methods supported (GET, POST, PUT, DELETE, PATCH, OPTIONS) +- Type hints enable validation and documentation without boilerplate +- OpenAPI 3.0+ compliant schema generation + +### P1: Async & Performance (Must Have) — ✅ Complete + +**As a** developer building high-throughput APIs, +**I want** first-class async support, +**So that** I can handle many concurrent connections efficiently. + +- [P1-US1] ✅ Async route handlers with `async def` +- [P1-US2] ✅ Background tasks for deferred processing +- [P1-US3] ✅ WebSocket support for real-time communication +- [P1-US4] ✅ Middleware stack (request/response processing) +- [P1-US5] ✅ Sub-application mounting for modular apps + +**Acceptance Criteria:** +- Async handlers perform comparably to Node.js/Go +- WebSocket connections maintained efficiently +- Middleware applies correctly to all routes + +### P1: Security & Authentication (Should Have) — ✅ Complete + +**As a** developer building secure APIs, +**I want** built-in authentication and authorization, +**So that** I don't have to implement common patterns from scratch. + +- [P1-US6] ✅ OAuth2 password flow implementation +- [P1-US7] ✅ JWT token support +- [P1-US8] ✅ CORS middleware +- [P1-US9] ✅ HTTP Basic Auth +- [P1-US10] ✅ Dependency-based authorization scopes + +**Acceptance Criteria:** +- OAuth2 with JWT tokens works out of the box +- Security schemes documented in OpenAPI spec + +### P2: Developer Experience (Should Have) — ✅ Complete + +**As a** FastAPI user, +**I want** excellent tooling and error messages, +**So that** I can develop quickly and debug easily. + +- [P2-US1] ✅ FastAPI CLI for running and generating projects +- [P2-US2] ✅ Clear validation error messages with field locations +- [P2-US3] ✅ Static type checking support with mypy +- [P2-US4] ✅ Response model documentation in OpenAPI + +**Acceptance Criteria:** +- CLI provides `fastapi dev` and `fastapi run` +- Error responses include details for each validation failure +- Type hints work with pyright/mypy + +### P2: Extensibility (Should Have) — ✅ Complete + +**As a** framework contributor, +**I want** to extend FastAPI without modifying core code, +**So that** I can add custom behaviors. + +- [P2-US5] ✅ Custom response classes +- [P2-US6] ✅ Custom parameter types +- [P2-US7] ✅ Custom middleware interfaces +- [P2-US8] ✅ OpenAPI extension hooks + +**Acceptance Criteria:** +- Extensions integrate seamlessly with FastAPI +- Custom components documented in OpenAPI + +### P3: Advanced Features (Could Have) — ✅ Complete + +**As an** advanced user, +**I want** sophisticated deployment options, +**So that** I can optimize for production. + +- [P3-US1] ✅ Testing utilities with TestClient +- [P3-US2] ✅ Dependency overrides for testing +- [P3-US3] ✅ ASGI server integration (Uvicorn, Hypercorn) +- [P3-US4] ✅ Gunicorn worker support +- [P3-US5] ✅ Docker integration and multi-stage builds + +**Acceptance Criteria:** +- Testing patterns documented and working +- Production deployment guides available + +## Architecture: Starlette + Pydantic + +FastAPI builds on two key libraries: + +| Component | Role | +|-----------|------| +| Starlette | Routing, middleware, ASGI handler | +| Pydantic | Data validation, serialization, OpenAPI generation | + +### Request/Response Flow + +``` +Request → ASGI Handler → Middleware → Route Handler → Dependency Injection + ↓ +Response ← Serialization ← Pydantic Model ← Return Value +``` + +### Key Components + +| Component | File | Role | +|-----------|------|------| +| FastAPI app | `fastapi/applications.py` | Main application class | +| Routing | `fastapi/routing.py` | Route resolution, OpenAPI generation | +| Dependencies | `fastapi/dependencies.py` | Dependency injection system | +| Params | `fastapi/params.py` | Parameter definitions | +| Response | `fastapi/response.py` | Response handling | +| OpenAPI | `fastapi/openapi/` | Schema generation | + +## Non-Functional Requirements + +### Performance +- Request/response latency comparable to Node.js and Go +- Minimal overhead for sync handlers +- Efficient async task scheduling + +### Compatibility +- Python 3.8+ (subject to PEP 594) +- OpenAPI 3.0+ and JSON Schema +- ASGI specification compliance + +### Security +- Input validation via Pydantic +- Secure defaults for authentication +- No sensitive data in error messages + +### Reliability +- Comprehensive test coverage +- Deprecation warnings for breaking changes +- Stable API surface within major versions + +## Test Scenarios + +1. **Basic API**: Create endpoint, verify request/response +2. **Validation**: Send invalid data, verify 422 error with details +3. **Async**: Test async handler with concurrent requests +4. **Dependencies**: Verify dependency injection ordering +5. **Auth**: Test OAuth2 flow end-to-end +6. **Documentation**: Verify OpenAPI schema accuracy +7. **Middleware**: Test request/response modification +8. **Sub-app**: Mount app, verify routing isolation diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md new file mode 100644 index 0000000000..578c0b6aca --- /dev/null +++ b/docs/ROADMAP.md @@ -0,0 +1,49 @@ +# Roadmap + +Future enhancements and improvements for the FastAPI framework. + +## Completed + +All P0–P3 user stories from the original PRD are implemented. See [PRD.md](PRD.md) for details. + +Key milestones achieved: +- Core routing with type hints and automatic validation +- Async support with first-class performance +- OAuth2, JWT, and security utilities +- FastAPI CLI and developer tooling +- Extensibility via custom components +- Comprehensive testing utilities +- Production deployment options + +## Ideas (Unprioritized) + +These are potential directions. None have user stories or acceptance criteria yet — they need to be scoped before work begins. + +- **Improved Error Messages**: More helpful validation errors with suggestions +- **Typed Middleware**: Type-safe middleware definitions +- **Enhanced OpenAPI**: More detailed schema generation options +- **Plugin System**: Formal extension mechanism for third-party integrations +- **Native gRPC Support**: gRPC reflection and transcoding +- **GraphQL Integration**: More mature GraphQL schema generation +- **Better Type Inference**: Improved type hints for complex scenarios +- **Streaming Responses**: Native support for Server-Sent Events +- **HTTP/2 Support**: Push promises and header compression +- **Zero-Config Deployments**: Simplified production setup + +## Won't Have + +- **Built-in Database ORM**: Users should choose their own (SQLAlchemy, Prisma, etc.) +- **Built-in Authentication Provider**: Identity management is outside framework scope +- **Template Engine**: Use external libraries (Jinja2, etc.) directly +- **Full-Stack Framework**: FastAPI remains focused on APIs only + +## Lessons Learned + +From years of maintaining FastAPI as a community-driven framework: + +1. **Good**: Type hints provide excellent developer experience and IDE support +2. **Good**: OpenAPI integration enables rich ecosystem (clients, docs, testing) +3. **Good**: Dependency injection promotes loose coupling and testability +4. **Issue**: Balancing new features with stability is challenging +5. **Fix**: Semantic versioning with clear deprecation paths +6. **Fix**: Comprehensive documentation with examples