CodeVetter · Repo Unpack · Contributor handoff
TheAlgorithms/Python
Read AGENTS.md and CONTRIBUTING.md first — they are the contract. Edits should be one file, one algorithm, minimal diff. The enforcement surface is: ruff check/format (uvx ruff), pytest doctests per file, snake_case lowercase filenames inside existing directories, type hints on all params/returns, and a checked checkbox in the PR template or algorithms-keeper auto-closes. Never touch DIRECTORY.md (bot-generated), never fabricate doctest output, and check build.yml's --ignore list before assuming a file is tested. Run `uvx pre-commit run --all-files` to replicate CI locally.
- AGENTS.md is the authoritative agent doc: mandates ruff (uvx ruff check/format), type hints on every parameter and return, ≥1 passing doctest per function, lowercase-underscore filenames, placement inside existing directories, and a reference URL for new algorithms.
- The single most common automated rejection: algorithms-keeper closes any PR whose 'Describe your change' section has no checked box — the template is .github/pull_request_template.md; always tick at least one box.
- Scope rules: one algorithm file per PR; never change code and its doctests in the same PR; keep diffs minimal and preserve existing style.
- Local verification commands: `uvx pre-commit run --all-files` for lint/format/hooks and `uvx pytest <dir>/<file>.py --doctest-modules` (or `uv run pytest`) for tests — there is no requirements.txt; deps come from pyproject.toml + uv.lock.
- Never edit DIRECTORY.md or README.md index sections by hand — DIRECTORY.md is regenerated and force-pushed by directory_writer.yml from scripts/build_directory_md.py output.
- Some directories/files are intentionally skipped in CI via --ignore in build.yml (cv2/qiskit/tf/network-bound files); check that list before assuming a file is exercised, and add new ignores there if a new heavy dep is introduced.
- Doctest honesty rule: never fabricate expected output — run the doctest and paste the real result; exception-testing uses `# doctest: +IGNORE_EXCEPTION_DETAIL`.
- Project Euler submissions have extra rules: read project_euler/README.md, use problem_NNN dir naming with __init__.py, expose solution() with the question input as default arg, and do not doctest the final answer (the sha256 oracle does that).
- Known trap: `uv sync` on free-threaded 3.14t cannot install opencv-python or qiskit (kept in optional groups); use `uv sync --group=test` like CI, and add --group=cv/--group=quantum only when needed.
- Files to read before editing any given area: the target algorithm file, AGENTS.md, CONTRIBUTING.md, and for Euler project_euler/README.md; for CI changes also pyproject.toml and the relevant workflow file. (inferred)
- Type checking with ty is informational only — agents should still add annotations (PR checklist requires them) but ty failures will not block merge; run `ty check <file>` locally per CONTRIBUTING.md.
- Ruff ignore-list traps: many style classes are globally suppressed (S101 assert allowed, S311 weak-random, B904) — matching repo style means not 'fixing' unrelated lint noise outside your file's diff.