|
1 | | -# Context |
2 | | - |
3 | | -You are in the CPython repo helping work on the implementation of the Python |
4 | | -language runtime and standard library itself. |
5 | | - |
6 | | -Use the `gh` tool to get information about an issue or PR in the repo. |
7 | | -Including using the GraphQL API via `gh` when appropriate. |
8 | | - |
9 | | -Source files in this repo can be very long. Check their size to consider if |
10 | | -you really need to read the entire thing. |
11 | | - |
12 | | -If tools such as `rg` (ripgrep), `gh`, `jq`, or `pre-commit` are not found, ask |
13 | | -the user to install them. ALWAYS prefer using `rg` rather than `find` or `grep`. |
14 | | - |
15 | | -# Expanding your knowledge |
16 | | - |
17 | | -* ALWAYS load a `.claude/pr-{PR_NUMBER}.md` or `.claude/branch-{branch_name_without_slashes}.md` file when you are told a PR number or when the current git branch is not `main`. |
18 | | -* Keep the file up to date as an engineering notebook of your learnings and project state as you work on a task and after you commit. The goal of our notebook is to make it easier to pick up and resume work later. |
19 | | - |
20 | | -## Optional developer guides and PEPs |
21 | | - |
22 | | -* If `REPO_ROOT/../devguide/` exists, its `developer-workflow/` and `documentation/` subdirs contain detailed info on how we like to work on code and docs. |
23 | | -* PEPs might exist in a `REPO_ROOT/../peps/` tree. |
24 | | - |
25 | | -# Source code |
26 | | - |
27 | | -* The runtime is implemented in C as are many of the core types and extension modules |
28 | | -* The Python standard library (stdlib) itself lives in the `Lib/` tree |
29 | | -* stdlib C extension modules live in the `Modules/` Tree |
30 | | -* builtins, objects, and the runtime itself live in `Objects/` and `Python/` |
31 | | -* NEVER edit files in a `**/clinic/**` subdirectory; those are generated by argument clinic |
32 | | -* Unittests for everything live in the `Lib/test/` tree. Ex: |
33 | | - * `Lib/zipfile/` contains the code for the stdlib `zipfile` module |
34 | | - * `Lib/test/test_zipfile**` are tests for `zipfile` |
35 | | - * `Modules/_csv.c` contains the code for the stdlib `csv` module |
36 | | - * `Lib/test/test_csv.py` are tests for `csv` |
37 | | -* C header files are in the `Include/` tree |
38 | | -* Documentation is written in .rst format in `Doc/` - this is source for the public facing official Python documentation. |
39 | | -* CPython internals are documented for maintainers in @InternalDocs/README.md. |
40 | | -* Build time tools such as Argument Clinic live under the `Tools/` tree |
41 | | - |
42 | | -## Coding style |
43 | | - |
44 | | -* For C, follow PEP-7. For Python, follow PEP-8. |
45 | | -* Be consistent with existing nearby code style unless asked to do otherwise. |
46 | | -* NEVER leave trailing whitespace on any line. |
47 | | -* ALWAYS preserve the newline at the end of files. |
48 | | -* We do not autoformat code in this codebase. If the user asks you to run ruff format on a specific file, it can be found in `Doc/venv/bin/ruff`. |
49 | | -* NEVER add Python type annotations to Python code in the `Lib/` tree. |
50 | | - |
51 | | -## Building |
52 | | - |
53 | | -ONLY build in a `build/` subdirectory that you create at the repo root. |
54 | | - |
55 | | -* Use sub-agents when running configure and make build steps |
56 | | -* `REPO_ROOT` is the root of the cpython git repo |
57 | | -* let `BUILD_DIR=REPO_ROOT/build` |
58 | | -* Setup: `cd BUILD_DIR && ../configure --with-pydebug` |
59 | | -* `make -C BUILD_DIR -j $(nproc)` will rebuild |
60 | | -* Check what OS you are running on. Let `BUILT_PY=BUILD_DIR/python` or `BUILD_DIR/python.exe` on macOS (.exe is used to avoid a case insensitive fs name conflict) |
61 | | -* If you are on Windows, ask the user how to build. |
62 | | - |
63 | | -## Running our built Python and tests |
64 | | - |
65 | | -* ALWAYS use sub-agents when running builds or tests |
66 | | -* NEVER use `pytest`. CPython tests are `unittest` based. |
67 | | -* use `BUILT_PY` to run the interpreter we've built |
68 | | -* Individual test files can be run directly using `BUILT_PY Lib/test/test_csv.py` |
69 | | -* `BUILT_PY -m test test_zipfile -j $(nproc)` will properly run all `Lib/test/test_zipfile` tests |
70 | | -* `BUILT_PY -m test` supports a `--match TESTNAME_GLOB` flag to run specific tests, pass `--help` to learn its other capabilities. NEVER try to pass `-k` as this is not pytest based, use `--match` instead. |
71 | | -* `make -C BUILD_DIR clinic` will regenerate argument clinic generated code. Do this after you've edited a corresponding input .c file in a way that changes a C extension module function signature or docstring |
72 | | -* `make -C BUILD_DIR test` will run the entire test suite. Do that sparingly. Focus on specific tests first and ask before running the entire test suite. |
73 | | -* Some tests are packages rather than a single .py file. These require `load_tests()` logic in their `test_package/__init__.py` file in order to work via `BUILT_PY -m test` commands. |
74 | | -* To collect Python code coverage from part of the test suite, use `BUILT_PY -m test -j $(nproc) --coverage test_name --coveragedir .claude/coverage_dir/`; this uses a `trace` based mechanism as implemented using libregrtest. |
75 | | - |
76 | | -## Common workflows |
77 | | - |
78 | | -* After editing C code: `make -C BUILD_DIR && BUILT_PY -m test relevant_tests` |
79 | | -* After editing stdlib Python: `BUILT_PY -m test relevant_tests --match specific_test_name_glob` (no rebuild needed) |
80 | | -* After editing .rst documentation: `make -C BUILD_DIR/Doc check` |
81 | | -* Before committing: `make -C BUILD_DIR patchcheck && pre-commit run --all-files` |
82 | | - |
83 | | -### Debugging |
84 | | - |
85 | | -* For interactive debugging (pdb, lldb, or gdb) or when working on an interactive feature such as the REPL: control a tmux session to drive that. |
86 | | - |
87 | | -## Scratch space |
88 | | - |
89 | | -* NEVER create throw away idea exploration files in the top directory of the repo. Use a `.claude/sandbox/` directory for those. They will never be committed. |
| 1 | +@AGENTS.md |
90 | 2 |
|
| 3 | +Keep agent instructions in AGENTS.md files instead of CLAUDE.md |
0 commit comments