# 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](https://pypi.org/project/yapf/) with Google style.
  Run `hatch run fmt-check` to check, `hatch run fmt` to format in place.
- **Linter:** [ruff](https://docs.astral.sh/ruff/). Configuration is in
  `pyproject.toml` under `[tool.ruff]`. Run `hatch run lint`.
- **Type checking:** [mypy](https://mypy-lang.org/). 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](https://hatch.pypa.io/) if you do not have it:

```bash
pipx install hatch
```

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

```bash
# 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.
