Imported from originalankur/GenerateAgents.md (projects/flask/AGENTS.md). Install upstream with npx skills add originalankur/GenerateAgents.md --skill flask. Copyright stays with the author.

AGENTS.md — flask

Code Style & Strict Rules

Code style is strictly enforced by ruff, and its rules are non-negotiable.

• Linter Rules: The following ruff rule sets are enforced. All code must comply with them.
  • B: flake8-bugbear (Finds potential bugs)
  • E: pycodestyle (Errors)
  • F: pyflakes (Undefined names, unused imports)
  • I: isort (Import sorting)
  • UP: pyupgrade (Modernizes Python syntax)
  • W: pycodestyle (Warnings)
• Import Style: Imports must be written one per line. Grouping imports on a single line is forbidden.
  • Correct:

  from flask import Flask
  from flask import request

  • Incorrect:

  from flask import Flask, request

Anti-Patterns & Restrictions

The following patterns are strictly forbidden to maintain code quality, security, and performance.

• 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.
• NEVER wrap the app object directly for middleware. To apply middleware, you MUST assign it to the internal WSGI application.
  • Correct:

  app.wsgi_app = MyMiddleware(app.wsgi_app)

  • Incorrect:

  app = MyMiddleware(app)

• 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.
• 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.
  • Correct (within a view):

  @app.route('/profile')
  def profile():
      user_agent = request.headers.get('User-Agent')
      return f"Your user agent is: {user_agent}"

  • Correct (outside a request, e.g., in a script):

  with app.app_context():
      # url_for() can be used here
      print(url_for('profile'))

  • Incorrect (global scope):

  # This will raise a RuntimeError
  profile_url = url_for('profile')

• 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.

Security & Compliance

All contributions must strictly adhere to the following security and compliance rules.

• License: All code must be compatible with the BSD-3-Clause license.
• 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.
• 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.
• 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.
• 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.

Lessons Learned (Past Failures)

The following principles are derived from past experience in maintaining and evolving the framework.

• 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.
• 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.
• 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.

Repository Quirks & Gotchas

These are non-obvious characteristics of the Flask repository that are essential to understand for effective development.

• "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.
• 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.
• 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.
• 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.
• 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.

Execution Commands

The agent is permitted to execute the following commands for development, testing, and maintenance.

• Run development server:

  flask run

• Run the full test suite:

  tox

• Run tests for a specific Python environment:

  tox -e py3.12

• Check for linting and style issues:

  ruff check .

• Automatically fix linting and style issues:

  ruff check --fix .

• Format code:

  ruff format .

• Build documentation:

  tox -e docs