# Contributor handoff — TheAlgorithms/Python

> Canonical page: https://codevetter.com/unpack/python/agent-handoff

# Contributor handoff — TheAlgorithms/Python

Scanned commit 52b9b913e08ea5afe81e82c1f502887c049750ba (2026-09-22). Generated by codevetter codevetter 1.12.0 on 2026-09-22.

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. — [AGENTS.md](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/AGENTS.md)
- 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. — [AGENTS.md](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/AGENTS.md) [.github/pull_request_template.md#L1-6](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/pull_request_template.md#L1-L6)
- Scope rules: one algorithm file per PR; never change code and its doctests in the same PR; keep diffs minimal and preserve existing style. — [AGENTS.md](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/AGENTS.md) [.github/pull_request_template.md#L5-13](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/pull_request_template.md#L5-L13)
- 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. — [AGENTS.md](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/AGENTS.md) [pyproject.toml#L13-38](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/pyproject.toml#L13-L38) [.pre-commit-config.yaml](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.pre-commit-config.yaml)
- 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. — [CONTRIBUTING.md#L216](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/CONTRIBUTING.md#L216) [.github/workflows/directory_writer.yml#L17-27](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/directory_writer.yml#L17-L27) [scripts/build_directory_md.py](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/scripts/build_directory_md.py)
- 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. — [.github/workflows/build.yml#L42-58](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/build.yml#L42-L58) [AGENTS.md](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/AGENTS.md)
- Doctest honesty rule: never fabricate expected output — run the doctest and paste the real result; exception-testing uses `# doctest: +IGNORE_EXCEPTION_DETAIL`. — [AGENTS.md](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/AGENTS.md) [sorts/bubble_sort.py#L68-71](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/sorts/bubble_sort.py#L68-L71)
- 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). — [project_euler/README.md#L19-50](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/project_euler/README.md#L19-L50) [scripts/validate_solutions.py#L98-108](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/scripts/validate_solutions.py#L98-L108) [CONTRIBUTING.md#L209](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/CONTRIBUTING.md#L209)
- 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. — [pyproject.toml#L44-64](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/pyproject.toml#L44-L64) [.github/workflows/build.yml#L29](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/build.yml#L29)
- 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) — [AGENTS.md](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/AGENTS.md) [CONTRIBUTING.md](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/CONTRIBUTING.md) [project_euler/README.md](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/project_euler/README.md) [pyproject.toml](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/pyproject.toml)
- 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. — [.github/workflows/ty.yml#L13-17](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/ty.yml#L13-L17) [CONTRIBUTING.md#L187-199](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/CONTRIBUTING.md#L187-L199) [.github/pull_request_template.md#L17](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/pull_request_template.md#L17)
- 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. — [pyproject.toml#L123-155](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/pyproject.toml#L123-L155) [AGENTS.md](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/AGENTS.md)

Every claim links to its cited files at the pinned commit. Citations identify source evidence; they do not establish runtime correctness. Independent CodeVetter scan — not reviewed by upstream maintainers.

## Public product links

- [CodeVetter](https://codevetter.com/)
- [Download](https://codevetter.com/download)
- [Documentation](https://codevetter.com/docs/)
- [Source](https://github.com/Codevetter/codevetter)