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