Skip to content

AGENTS.md

Latest commit

 

History

History
121 lines (97 loc) · 4.74 KB

AGENTS.md

File metadata and controls

121 lines (97 loc) · 4.74 KB
Raw

AGENTS.md

Guidelines for AI agents working on the pika codebase.

Project overview

pika is a pure-Python implementation of the AMQP 0-9-1 protocol. It targets Python 3 with requires-python >= 3.7. The CI matrix tests Python 3.10 through 3.14. Older Python 3 versions (3.7 through 3.9) are not tested but should still work.

Repository layout

pika/                   # library source
pika/adapters/          # connection adapters (asyncio, blocking, gevent,
                        #   select, tornado, twisted)
pika/adapters/utils/    # adapter internals (io_services, nbio_interface,
                        #   connection_workflow, selector_ioloop_adapter)
pika/spec.py            # auto-generated AMQP spec (see below)
tests/unit/             # unit tests
tests/acceptance/       # acceptance tests (require a running RabbitMQ)
utils/codegen.py        # code generator for pika/spec.py
examples/               # usage examples

Code style

  • Formatter: yapf with Google style. Run hatch run fmt-check to check, hatch run fmt to format in place.
  • Linter: ruff. Configuration is in pyproject.toml under [tool.ruff]. Run hatch run lint.
  • Type checking: mypy. Configuration is in mypy.ini. Run hatch run typecheck.
  • Use single quotes for strings unless the string contains a single quote.
  • No trailing whitespace. Check before committing.

Auto-generated code

pika/spec.py is generated by utils/codegen.py. Never edit spec.py directly. Changes to spec classes or constants require modifying the code generator and regenerating the file. Pull requests that modify spec.py without corresponding utils/codegen.py changes will be rejected.

Git conventions

  • Commit message format: 50-70 character subject line in active voice, present tense. Wrap the body at 72 characters. Use backticks around code identifiers in commit messages.
  • No em-dashes in any git or GitHub text (commit messages, PR titles, PR bodies, review comments, issue bodies). Use regular dashes (- or --) instead.
  • PR and review bodies: write to a temp file and use --body-file, never inline --body for multi-line content.
  • No backticks around commit SHAs in GitHub markdown.
  • No H1 headers (#) in PR or review comment bodies. Use H2 (##) or lower.
  • No hard-wrap in GitHub-rendered markdown (PR bodies, issue bodies, comments). Hard-wrap only in commit message bodies (at 72 characters).
  • Use git commit -F <file> for commit messages longer than a single line.

CI workflows

  • Format (.github/workflows/yapf.yaml): runs yapf check on every push and pull request.
  • Lint (.github/workflows/lint.yaml): runs ruff check on every push and pull request.
  • Type check (.github/workflows/mypy.yaml): runs mypy on every push and pull request. Requires tornado and twisted to be installed so mypy can resolve optional-dependency types.
  • Tests (.github/workflows/main.yaml): runs the full test suite with pytest on Python 3.10-3.14. Acceptance tests require a RabbitMQ server (started via Docker in CI).
  • Legacy tests (.github/workflows/legacy-python.yaml): same as above, but for Python 3.7-3.9.

Running tests locally

Install Hatch if you do not have it:

pipx install hatch

Run tests with Hatch (it creates the environment and installs dependencies automatically):

# Unit tests only (no RabbitMQ needed)
hatch run unit

# All tests (requires RabbitMQ running on localhost)
hatch run test

# Start RabbitMQ via Docker
hatch run rabbitmq

PR conventions

  • Base branch is main.
  • Branch naming: gh-<issue-number> for issue-linked work, descriptive slug for other work.
  • Assign the PR to relevant maintainers.
  • Set the milestone when one applies.
  • Add labels from the existing set when appropriate (Enhancement, Documentation, etc.).
  • PR descriptions should include a summary of changes, what was tested, and reference any related issues with Fixes #NNN or See #NNN.

Key technical details

  • pika/compat.py contains Python compatibility utilities. A cleanup effort is tracked in issue #1559 to remove Python 2 remnants and rename this module.
  • The interrupt socket pair in select_connection.py uses _TRY_IO_AGAIN_SOCK_ERROR_CODES = (errno.EAGAIN, errno.EWOULDBLOCK) to handle platform differences between POSIX and Windows. Both errno values must always be checked.
  • pika/adapters/twisted_connection.py and pika/adapters/tornado_connection.py depend on optional third-party libraries. Type annotations in these files use type: ignore comments that are only valid when the libraries are installed.