{"owner":"falconry","repo":"falcon","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# Falcon Agent Guide\n\nRead `CONTRIBUTING.md` first. Treat `pyproject.toml` and `tox.ini` as the\nexecutable source of truth when prose and configuration differ. In accordance\nwith the \"Use of LLMs\" policy in `CONTRIBUTING.md`, carefully review and test\nall generated changes.\n\n## Repository map\n\n- `falcon/app.py`, `falcon/request.py`, and `falcon/response.py` implement the\n  WSGI flavor, as well as base behavior that `falcon/asgi/` subclasses for\n  ASGI and WebSocket support. More shared behavior lives in modules such as\n  `falcon/app_helpers.py`, `falcon/routing/`, `falcon/media/`, and\n  `falcon/util/`.\n- `falcon/testing/` contains public test helpers. Primary tests live in\n  `tests/`, with ASGI-specific coverage in `tests/asgi/`. Tutorial and example\n  suites have dedicated tox environments.\n- `falcon/cyutil/*.pyx` contains optional Cython-optimized counterparts of\n  pure Python modules such as `falcon/util/reader.py` and `falcon/util/uri.py`.\n  When available, the optimized versions are selected at import time (in\n  `falcon/util/uri.py`, `falcon/util/misc.py`, and -- for the buffered\n  reader -- `falcon/util/__init__.py`). Preserve both modes when changing\n  these paths, and use a Cython tox environment.\n- Documentation is reStructuredText under `docs/`. Put runnable recipe snippets\n  in `examples/recipes/`; documentation includes them with `literalinclude`.\n\n## Change rules\n\n- Keep patches narrow. Preserve Falcon's public API compatibility, HTTP/RFC\n  correctness, and Python 3.9+ support on CPython and PyPy unless the task\n  explicitly changes those contracts.\n- Check both WSGI and ASGI surfaces when shared request, response, routing,\n  middleware, media, error, or testing behavior changes. Add or update the\n  corresponding tests; do not assume inheritance makes behavior identical.\n- Maintain 100% branch coverage for changed behavior, including error and\n  version-specific paths. Do not add production dependencies casually;\n  `[project].dependencies` is currently empty.\n- Treat request and response hot paths as performance-sensitive. Reuse existing\n  helpers. When throughput or allocation behavior could change, benchmark with\n  `tox -e py310_bench -- <falcon-bench args>`.\n- Do not bulk-modernize `%` formatting in `falcon/`. `pyproject.toml`\n  deliberately ignores Ruff's `UP030`, `UP031`, and `UP032` there pending\n  inspection and benchmarks.\n\n## Style\n\n- Ruff targets Python 3.9, 88 columns, and single quotes.\n- Public classes, attributes, methods, and functions require\n  Napoleon/Google-style docstrings. Start immediately after the opening quotes\n  with a roughly 70-character summary that ends in a period.\n- Name caught exceptions `ex`. Limit single-character names to trivial indices\n  and standard formulas.\n- Format non-trivial tagged comments as\n  `TODO|NOTE|PERF|APPSEC(<GitHub handle>):`. If the author's handle is\n  unavailable, do not invent one and don't impersonate other users;\n  avoid the tagged comment unless necessary.\n\n## Verification\n\nRun commands from the repository root. Start with the focused test, run only\naffected specialized environments next, and reserve the complete `tox` gate\nfor broad or final validation.\n\n- Prepare a development environment by installing the project in editable\n  mode together with the test dependencies:\n  `pip install -e . -r requirements/tests`.\n- In a prepared development environment, get focused feedback with\n  `pytest tests/test_<area>.py -k '<case>'` or\n  `pytest tests/asgi/test_<area>.py -k '<case>'`.\n- Run all Python tests and collect coverage data with `tox -e pytest`; check\n  minimum-dependency compatibility with `tox -e mintest`; verify optional\n  Cython behavior with a matching environment such as `tox -e py312_cython`.\n- Check formatting and lint with `tox -e ruff,pep8,pep8-docstrings`. Apply\n  formatting and safe fixes only with `tox -e reformat`.\n- For typing changes, run `tox -e mypy,mypy_tests`. For documentation or\n  docstring changes, run `tox -e docs`.\n- Always finish with a plain `tox` run without arguments (or `tox -r` to\n  recreate environments): the default env selection is the complete local\n  gate, and it must pass together with the 100% combined coverage check\n  before changes are handed over to the operator.\n  Documentation-only changes may instead finish with `tox -e docs`.\n\n## Documentation and changelog\n\n- Update user and API documentation when behavior or public contracts change;\n  build it with `tox -e docs`.\n- Functionality changes require\n  `docs/_newsfragments/{issue_number}.{fragment_type}.rst`. The exact fragment\n  types are `breakingchange`, `newandimproved`, `bugfix`, and `misc`. Name the\n  fragment after the issue the change closes; use the PR number itself only\n  when no associated issue exists.\n  `tox -e docs` renders pending fragments as a draft into the built\n  documentation without modifying the changelog file; preview the result\n  there.\n- Never invent an issue or PR number. If none is available, report that the\n  fragment cannot be named instead of creating a placeholder.\n- For recipes, put executable code in `examples/recipes/`, include it from\n  `docs/user/recipes/`, and add coverage in `tests/test_recipes.py` when\n  practical.\n\n## Operator boundaries\n\n- Never create, submit, or open a GitHub pull request, regardless of the\n  mechanism: `gh`, direct API calls, web automation, and pushing a branch and\n  then accepting GitHub's suggestion all count, and draft pull requests are\n  still pull requests. Prepare the changes and verification evidence, then ask\n  the human operator to open the pull request.\n- Never tick, check, or otherwise complete a pull request checklist on the\n  operator's behalf. The human operator must review the changes and complete\n  every checklist item manually.\n- Do not take any other outward actions on Falcon's GitHub repositories\n  either: opening issues, posting comments or reviews, and editing pull\n  request metadata are all reserved for the human operator.\n\nSee `CONTRIBUTING.md` for commit-message format, full docstring markup rules,\nreview policy, and contributor conduct.\n"},"files":{"AGENTS.md":"# Falcon Agent Guide\n\nRead `CONTRIBUTING.md` first. Treat `pyproject.toml` and `tox.ini` as the\nexecutable source of truth when prose and configuration differ. In accordance\nwith the \"Use of LLMs\" policy in `CONTRIBUTING.md`, carefully review and test\nall generated changes.\n\n## Repository map\n\n- `falcon/app.py`, `falcon/request.py`, and `falcon/response.py` implement the\n  WSGI flavor, as well as base behavior that `falcon/asgi/` subclasses for\n  ASGI and WebSocket support. More shared behavior lives in modules such as\n  `falcon/app_helpers.py`, `falcon/routing/`, `falcon/media/`, and\n  `falcon/util/`.\n- `falcon/testing/` contains public test helpers. Primary tests live in\n  `tests/`, with ASGI-specific coverage in `tests/asgi/`. Tutorial and example\n  suites have dedicated tox environments.\n- `falcon/cyutil/*.pyx` contains optional Cython-optimized counterparts of\n  pure Python modules such as `falcon/util/reader.py` and `falcon/util/uri.py`.\n  When available, the optimized versions are selected at import time (in\n  `falcon/util/uri.py`, `falcon/util/misc.py`, and -- for the buffered\n  reader -- `falcon/util/__init__.py`). Preserve both modes when changing\n  these paths, and use a Cython tox environment.\n- Documentation is reStructuredText under `docs/`. Put runnable recipe snippets\n  in `examples/recipes/`; documentation includes them with `literalinclude`.\n\n## Change rules\n\n- Keep patches narrow. Preserve Falcon's public API compatibility, HTTP/RFC\n  correctness, and Python 3.9+ support on CPython and PyPy unless the task\n  explicitly changes those contracts.\n- Check both WSGI and ASGI surfaces when shared request, response, routing,\n  middleware, media, error, or testing behavior changes. Add or update the\n  corresponding tests; do not assume inheritance makes behavior identical.\n- Maintain 100% branch coverage for changed behavior, including error and\n  version-specific paths. Do not add production dependencies casually;\n  `[project].dependencies` is currently empty.\n- Treat request and response hot paths as performance-sensitive. Reuse existing\n  helpers. When throughput or allocation behavior could change, benchmark with\n  `tox -e py310_bench -- <falcon-bench args>`.\n- Do not bulk-modernize `%` formatting in `falcon/`. `pyproject.toml`\n  deliberately ignores Ruff's `UP030`, `UP031`, and `UP032` there pending\n  inspection and benchmarks.\n\n## Style\n\n- Ruff targets Python 3.9, 88 columns, and single quotes.\n- Public classes, attributes, methods, and functions require\n  Napoleon/Google-style docstrings. Start immediately after the opening quotes\n  with a roughly 70-character summary that ends in a period.\n- Name caught exceptions `ex`. Limit single-character names to trivial indices\n  and standard formulas.\n- Format non-trivial tagged comments as\n  `TODO|NOTE|PERF|APPSEC(<GitHub handle>):`. If the author's handle is\n  unavailable, do not invent one and don't impersonate other users;\n  avoid the tagged comment unless necessary.\n\n## Verification\n\nRun commands from the repository root. Start with the focused test, run only\naffected specialized environments next, and reserve the complete `tox` gate\nfor broad or final validation.\n\n- Prepare a development environment by installing the project in editable\n  mode together with the test dependencies:\n  `pip install -e . -r requirements/tests`.\n- In a prepared development environment, get focused feedback with\n  `pytest tests/test_<area>.py -k '<case>'` or\n  `pytest tests/asgi/test_<area>.py -k '<case>'`.\n- Run all Python tests and collect coverage data with `tox -e pytest`; check\n  minimum-dependency compatibility with `tox -e mintest`; verify optional\n  Cython behavior with a matching environment such as `tox -e py312_cython`.\n- Check formatting and lint with `tox -e ruff,pep8,pep8-docstrings`. Apply\n  formatting and safe fixes only with `tox -e reformat`.\n- For typing changes, run `tox -e mypy,mypy_tests`. For documentation or\n  docstring changes, run `tox -e docs`.\n- Always finish with a plain `tox` run without arguments (or `tox -r` to\n  recreate environments): the default env selection is the complete local\n  gate, and it must pass together with the 100% combined coverage check\n  before changes are handed over to the operator.\n  Documentation-only changes may instead finish with `tox -e docs`.\n\n## Documentation and changelog\n\n- Update user and API documentation when behavior or public contracts change;\n  build it with `tox -e docs`.\n- Functionality changes require\n  `docs/_newsfragments/{issue_number}.{fragment_type}.rst`. The exact fragment\n  types are `breakingchange`, `newandimproved`, `bugfix`, and `misc`. Name the\n  fragment after the issue the change closes; use the PR number itself only\n  when no associated issue exists.\n  `tox -e docs` renders pending fragments as a draft into the built\n  documentation without modifying the changelog file; preview the result\n  there.\n- Never invent an issue or PR number. If none is available, report that the\n  fragment cannot be named instead of creating a placeholder.\n- For recipes, put executable code in `examples/recipes/`, include it from\n  `docs/user/recipes/`, and add coverage in `tests/test_recipes.py` when\n  practical.\n\n## Operator boundaries\n\n- Never create, submit, or open a GitHub pull request, regardless of the\n  mechanism: `gh`, direct API calls, web automation, and pushing a branch and\n  then accepting GitHub's suggestion all count, and draft pull requests are\n  still pull requests. Prepare the changes and verification evidence, then ask\n  the human operator to open the pull request.\n- Never tick, check, or otherwise complete a pull request checklist on the\n  operator's behalf. The human operator must review the changes and complete\n  every checklist item manually.\n- Do not take any other outward actions on Falcon's GitHub repositories\n  either: opening issues, posting comments or reviews, and editing pull\n  request metadata are all reserved for the human operator.\n\nSee `CONTRIBUTING.md` for commit-message format, full docstring markup rules,\nreview policy, and contributor conduct.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# Falcon Agent Guide\n\nRead `CONTRIBUTING.md` first. Treat `pyproject.toml` and `tox.ini` as the\nexecutable source of truth when prose and configuration differ. In accordance\nwith the \"Use of LLMs\" policy in `CONTRIBUTING.md`, carefully review and test\nall generated changes.\n\n## Repository map\n\n- `falcon/app.py`, `falcon/request.py`, and `falcon/response.py` implement the\n  WSGI flavor, as well as base behavior that `falcon/asgi/` subclasses for\n  ASGI and WebSocket support. More shared behavior lives in modules such as\n  `falcon/app_helpers.py`, `falcon/routing/`, `falcon/media/`, and\n  `falcon/util/`.\n- `falcon/testing/` contains public test helpers. Primary tests live in\n  `tests/`, with ASGI-specific coverage in `tests/asgi/`. Tutorial and example\n  suites have dedicated tox environments.\n- `falcon/cyutil/*.pyx` contains optional Cython-optimized counterparts of\n  pure Python modules such as `falcon/util/reader.py` and `falcon/util/uri.py`.\n  When available, the optimized versions are selected at import time (in\n  `falcon/util/uri.py`, `falcon/util/misc.py`, and -- for the buffered\n  reader -- `falcon/util/__init__.py`). Preserve both modes when changing\n  these paths, and use a Cython tox environment.\n- Documentation is reStructuredText under `docs/`. Put runnable recipe snippets\n  in `examples/recipes/`; documentation includes them with `literalinclude`.\n\n## Change rules\n\n- Keep patches narrow. Preserve Falcon's public API compatibility, HTTP/RFC\n  correctness, and Python 3.9+ support on CPython and PyPy unless the task\n  explicitly changes those contracts.\n- Check both WSGI and ASGI surfaces when shared request, response, routing,\n  middleware, media, error, or testing behavior changes. Add or update the\n  corresponding tests; do not assume inheritance makes behavior identical.\n- Maintain 100% branch coverage for changed behavior, including error and\n  version-specific paths. Do not add production dependencies casually;\n  `[project].dependencies` is currently empty.\n- Treat request and response hot paths as performance-sensitive. Reuse existing\n  helpers. When throughput or allocation behavior could change, benchmark with\n  `tox -e py310_bench -- <falcon-bench args>`.\n- Do not bulk-modernize `%` formatting in `falcon/`. `pyproject.toml`\n  deliberately ignores Ruff's `UP030`, `UP031`, and `UP032` there pending\n  inspection and benchmarks.\n\n## Style\n\n- Ruff targets Python 3.9, 88 columns, and single quotes.\n- Public classes, attributes, methods, and functions require\n  Napoleon/Google-style docstrings. Start immediately after the opening quotes\n  with a roughly 70-character summary that ends in a period.\n- Name caught exceptions `ex`. Limit single-character names to trivial indices\n  and standard formulas.\n- Format non-trivial tagged comments as\n  `TODO|NOTE|PERF|APPSEC(<GitHub handle>):`. If the author's handle is\n  unavailable, do not invent one and don't impersonate other users;\n  avoid the tagged comment unless necessary.\n\n## Verification\n\nRun commands from the repository root. Start with the focused test, run only\naffected specialized environments next, and reserve the complete `tox` gate\nfor broad or final validation.\n\n- Prepare a development environment by installing the project in editable\n  mode together with the test dependencies:\n  `pip install -e . -r requirements/tests`.\n- In a prepared development environment, get focused feedback with\n  `pytest tests/test_<area>.py -k '<case>'` or\n  `pytest tests/asgi/test_<area>.py -k '<case>'`.\n- Run all Python tests and collect coverage data with `tox -e pytest`; check\n  minimum-dependency compatibility with `tox -e mintest`; verify optional\n  Cython behavior with a matching environment such as `tox -e py312_cython`.\n- Check formatting and lint with `tox -e ruff,pep8,pep8-docstrings`. Apply\n  formatting and safe fixes only with `tox -e reformat`.\n- For typing changes, run `tox -e mypy,mypy_tests`. For documentation or\n  docstring changes, run `tox -e docs`.\n- Always finish with a plain `tox` run without arguments (or `tox -r` to\n  recreate environments): the default env selection is the complete local\n  gate, and it must pass together with the 100% combined coverage check\n  before changes are handed over to the operator.\n  Documentation-only changes may instead finish with `tox -e docs`.\n\n## Documentation and changelog\n\n- Update user and API documentation when behavior or public contracts change;\n  build it with `tox -e docs`.\n- Functionality changes require\n  `docs/_newsfragments/{issue_number}.{fragment_type}.rst`. The exact fragment\n  types are `breakingchange`, `newandimproved`, `bugfix`, and `misc`. Name the\n  fragment after the issue the change closes; use the PR number itself only\n  when no associated issue exists.\n  `tox -e docs` renders pending fragments as a draft into the built\n  documentation without modifying the changelog file; preview the result\n  there.\n- Never invent an issue or PR number. If none is available, report that the\n  fragment cannot be named instead of creating a placeholder.\n- For recipes, put executable code in `examples/recipes/`, include it from\n  `docs/user/recipes/`, and add coverage in `tests/test_recipes.py` when\n  practical.\n\n## Operator boundaries\n\n- Never create, submit, or open a GitHub pull request, regardless of the\n  mechanism: `gh`, direct API calls, web automation, and pushing a branch and\n  then accepting GitHub's suggestion all count, and draft pull requests are\n  still pull requests. Prepare the changes and verification evidence, then ask\n  the human operator to open the pull request.\n- Never tick, check, or otherwise complete a pull request checklist on the\n  operator's behalf. The human operator must review the changes and complete\n  every checklist item manually.\n- Do not take any other outward actions on Falcon's GitHub repositories\n  either: opening issues, posting comments or reviews, and editing pull\n  request metadata are all reserved for the human operator.\n\nSee `CONTRIBUTING.md` for commit-message format, full docstring markup rules,\nreview policy, and contributor conduct.\n","category":"root","tokens":1526}]}