AGENTS.md

1# AGENTS.md — flask
2 
3## Code Style & Strict Rules
4 
5Code style is strictly enforced by `ruff`, and its rules are non-negotiable.
6 
7*   **Linter Rules**: The following `ruff` rule sets are enforced. All code must comply with them.
8    *   `B`: `flake8-bugbear` (Finds potential bugs)
9    *   `E`: `pycodestyle` (Errors)
10    *   `F`: `pyflakes` (Undefined names, unused imports)
11    *   `I`: `isort` (Import sorting)
12    *   `UP`: `pyupgrade` (Modernizes Python syntax)
13    *   `W`: `pycodestyle` (Warnings)
14*   **Import Style**: Imports must be written one per line. Grouping imports on a single line is forbidden.
15    *   **Correct:**
16```python
17    from flask import Flask
18    from flask import request
19```
20    *   **Incorrect:**
21```python
22    from flask import Flask, request
23```
24 
25## Anti-Patterns & Restrictions
26 
27The following patterns are strictly forbidden to maintain code quality, security, and performance.
28 
29*   **NEVER use `app.run()` in production.** This is a development-only server. For production, a proper WSGI server like Gunicorn or uWSGI must be used.
30*   **NEVER wrap the `app` object directly for middleware.** To apply middleware, you MUST assign it to the internal WSGI application.
31    *   **Correct:**
32```python
33    app.wsgi_app = MyMiddleware(app.wsgi_app)
34```
35    *   **Incorrect:**
36```python
37    app = MyMiddleware(app)
38```
39*   **NEVER use the session for caching or storing large data.** The session is a small, signed cookie intended only for small identifiers (e.g., `user_id`). Storing large objects will severely degrade performance.
40*   **NEVER use context-dependent functions outside of an active request or application context.** Functions like `url_for()` or the `request` object will fail if called at the global scope. If needed, they must be wrapped in an application context.
41    *   **Correct (within a view):**
42```python
43    @app.route('/profile')
44    def profile():
45        user_agent = request.headers.get('User-Agent')
46        return f"Your user agent is: {user_agent}"
47```
48    *   **Correct (outside a request, e.g., in a script):**
49```python
50    with app.app_context():
51        # url_for() can be used here
52        print(url_for('profile'))
53```
54    *   **Incorrect (global scope):**
55```python
56    # This will raise a RuntimeError
57    profile_url = url_for('profile')
58```
59*   **NEVER call internal methods or attributes.** Anything prefixed with an underscore (e.g., `_find_error_handler`) is considered internal and subject to change without notice. Only use the public, documented API.
60 
61## Security & Compliance
62 
63All contributions must strictly adhere to the following security and compliance rules.
64 
65*   **License**: All code must be compatible with the **`BSD-3-Clause`** license.
66*   **NEVER set `debug=True` in production.** This is a critical vulnerability that can expose an interactive debugger and allow remote code execution. The `debug` flag must always be `False` in any production environment.
67*   **NEVER store sensitive data in the user session.** Session data is signed but **not encrypted**, meaning it can be decoded and read by the user. Do not store passwords, secrets, or any Personally Identifiable Information (PII) in the session.
68*   **`secret_key` must be secure**: The application's `secret_key` must be a long, random, and confidential string. A compromised `secret_key` allows attackers to forge sessions.
69*   **Always use `send_from_directory` to serve files.** This function is specifically designed to prevent path traversal attacks. Do not manually construct file paths with user-provided input to serve files.
70 
71## Lessons Learned (Past Failures)
72 
73The following principles are derived from past experience in maintaining and evolving the framework.
74 
75*   **Graceful API Evolution is Crucial**: Instead of making immediate breaking changes, the project uses compatibility wrappers and `DeprecationWarning`. This provides a smoother transition for downstream users and is the required pattern for evolving the public API.
76*   **Proactive Upstream Testing Prevents Breakages**: The `tests-dev` tox environment tests against the `main` branches of core dependencies (Werkzeug, Jinja2, etc.). This practice is essential for detecting and fixing compatibility issues *before* new versions of dependencies are released.
77*   **Separation of Concerns (Sans-IO) Improves Testability**: The core logic is "sans-IO" (agnostic to web protocols) and lives in `src/flask/sansio`. This architectural decision has proven effective for isolating and testing business logic independently from the web layer.
78 
79## Repository Quirks & Gotchas
80 
81These are non-obvious characteristics of the Flask repository that are essential to understand for effective development.
82 
83*   **"Global" Objects are Context-Locals**: The seemingly global objects like `request`, `g`, and `session` are not true globals. They are thread-safe (or task-safe) proxies that point to the object associated with the current, active request. This is a fundamental concept in Flask.
84*   **Middleware is Applied to `app.wsgi_app`**: You do not wrap the Flask `app` object to apply WSGI middleware. Instead, you wrap the internal `app.wsgi_app` attribute.
85*   **Signals are the Preferred Extension Mechanism**: The preferred way to hook into Flask's internal operations (like `request_started` or `app_context_pushed`) is by using Blinker signals. Avoid monkeypatching framework internals.
86*   **`uv` is used for Fast Dependency Management**: The project uses `uv` as a high-performance dependency resolver and `tox` runner (`tox-uv`). Be aware that this is the primary tool for managing environments, not standard `pip`.
87*   **Dual Architecture (Sans-IO vs. WSGI)**: The codebase is split into two distinct parts: the Sans-IO core in `src/flask/sansio` and the WSGI-specific application layer in `src/flask/app`. Understanding which layer you are working in is critical.
88 
89## Execution Commands
90 
91The agent is permitted to execute the following commands for development, testing, and maintenance.
92 
93*   **Run development server:**
94```bash
95    flask run
96```
97*   **Run the full test suite:**
98```bash
99    tox
100```
101*   **Run tests for a specific Python environment:**
102```bash
103    tox -e py3.12
104```
105*   **Check for linting and style issues:**
106```bash
107    ruff check .
108```
109*   **Automatically fix linting and style issues:**
110```bash
111    ruff check --fix .
112```
113*   **Format code:**
114```bash
115    ruff format .
116```
117*   **Build documentation:**
118```bash
119    tox -e docs
120    
121```