Skip to content

Commit 368a4c1

Browse files
committed
Add instructions for AI coding agents.
1 parent d061796 commit 368a4c1

1 file changed

Lines changed: 116 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
# Guidance for coding agents
2+
3+
## Project overview
4+
5+
websockets is a Python implementation of the WebSocket protocol (RFC 6455).
6+
7+
Its priorities are correctness, simplicity, robustness, and performance.
8+
9+
## Architecture & layout
10+
11+
websockets provides five implementations:
12+
13+
* a [Sans-I/O](https://sans-io.readthedocs.io/) protocol implementation
14+
in `src/websockets/`
15+
* three I/O integrations
16+
* asyncio in `src/websockets/asyncio/`
17+
* threading in `src/websockets/sync/`
18+
* trio in `src/websockets/trio/`
19+
* legacy implementation in `src/websockets/legacy/`
20+
21+
The Sans-I/O protocol implementation contains notably:
22+
23+
* `protocol.py` and `frames.py`: core protocol
24+
* `extensions/permessage_deflate.py`: compression (RFC 7692)
25+
* `client.py` and `server.py`: opening handshake
26+
27+
Each I/O integration includes:
28+
29+
* `connection.py`: `Connection` provides I/O integration
30+
* `messages.py`: `Assembler` reassembles fragmented messages
31+
* `client.py`: `connect` is the entrypoint for clients
32+
* `server.py`: `serve` is the entrypoint for servers; also defines `Server`
33+
* `router.py`: `route` adds URL routing with `werkzeug`
34+
35+
A CLI is defined in `src/websockets/cli.py`.
36+
37+
Lazy imports with `src/websockets/imports.py` make it possible to import from
38+
the `websockets` root package while loading only modules that are really used.
39+
40+
## Environment
41+
42+
A Python environment with all required dependencies is configured with direnv,
43+
and the local repository is installed there.
44+
45+
Prefix all commands with `direnv exec . ` to run them in this environment.
46+
47+
## Tests
48+
49+
Every source module has a matching test module e.g.
50+
`src/websockets/protocol.py -> tests/test_protocol.py`.
51+
52+
Run tests for a module with `python -m unittest ...` e.g.
53+
`direnv exec . python -m unittest tests.test_protocol`.
54+
55+
Run a single test with `python -m unittest -k ...` e.g.
56+
`direnv exec . python -m unittest -k test_client_sends_text`.
57+
58+
Run the entire test suite with `direnv exec . make tests`. It takes ~15 seconds.
59+
60+
Each source module must have a test module providing 100% branch coverage,
61+
except for the legacy implementation and four modules without testable logic.
62+
63+
Check this requirement with `direnv exec . make maxi_cov`. It takes ~30 seconds.
64+
65+
When encountering a flaky test, re-run with WEBSOCKETS_TESTS_TIMEOUT_FACTOR=10.
66+
67+
## Docs
68+
69+
Documentation follows the [Diataxis](https://diataxis.fr/) framework.
70+
71+
* tutorials in `docs/intro`
72+
* how-to guides in `docs/howto`, `docs/deploy`, and `docs/faq`
73+
* explanations in `docs/topics`
74+
* API reference in `docs/reference`, generated from docstrings
75+
76+
## Making changes
77+
78+
* Avoid backwards-incompatible changes to documented APIs.
79+
80+
* Keep changes minimal. Write terse comments. Ask before adding tests.
81+
82+
* When changing an I/O integration, review the other I/O integrations and
83+
determine if the same change must be applied. Code, tests, and docs are
84+
highly consistent across integrations; they must remain in sync.
85+
86+
* When a change has user-visible consequences, include a short changelog entry
87+
in `docs/project/changelog.rst`.
88+
89+
* When finalizing a change, always format code with `direnv exec . make style`,
90+
check types with `direnv exec . make types`, and ensure test coverage with
91+
`direnv exec . make maxi_cov`.
92+
93+
* Don't edit the legacy implementation, unless requested specifically. If you
94+
do, ensure test coverage with `direnv exec . make coverage`.
95+
96+
* Write code compatible with Python 3.11+.
97+
98+
## Code style
99+
100+
* Never prefix variable and class names with an underscore. This project doesn't
101+
use the _-prefix convention for private APIs.
102+
103+
## Development commands
104+
105+
Run commands from the repository root, prefixed with `direnv exec . `.
106+
107+
```bash
108+
make build # Build the C extension - only needed after changing speedups.c
109+
make tests # Run the test suite
110+
make coverage # Run tests and require 100% branch coverage
111+
make maxi_cov # Run tests, except legacy, and require 100% per-module branch coverage
112+
make types # Run mypy in strict mode
113+
make style # Format and auto-fix code with ruff
114+
make spell # Apply codespell fixes - not needed
115+
make clean # Remove build artifacts and generated files - not needed
116+
```

0 commit comments

Comments
 (0)