Skip to content

AGENTS.md

Latest commit

 

History

History
62 lines (49 loc) · 2.83 KB

AGENTS.md

File metadata and controls

62 lines (49 loc) · 2.83 KB
Raw

AGENTS.md

Guidance for AI coding agents (and their humans) contributing to TheAlgorithms/Python. This complements — and never overrides — CONTRIBUTING.md. Read that first.

This repository is educational: implementations should be clear and correct rather than maximally optimized. Every change goes through CI and the algorithms-keeper bot, both of which reject non-conforming PRs automatically.

Before opening a pull request

  • Check at least one box in the PR description. The algorithms-keeper bot closes any PR whose "Describe your change" section has no checked box (* [x]). Fill in the template that ships in .github/pull_request_template.md and tick every item that applies before you submit — this is the single most common reason automated PRs get closed.
  • One algorithm file per PR. Split unrelated changes into separate PRs to keep review focused.
  • Don't change code and its doctests in the same PR. If you're only updating tests, say so and touch nothing else.

Code conventions (enforced by CI)

  • Formatting & linting: ruff (uvx ruff check . and uvx ruff format .). Run uvx pre-commit run --all-files locally to catch everything CI will.
  • Type hints: annotate every function parameter and return value with type hints.
  • Doctests: every function needs at least one doctest that passes under python -m doctest -v your_file.py (and pytest).
  • Naming: filenames are all-lowercase with underscores (no spaces or dashes); functions and variables follow standard Python naming.
  • Placement: new files go inside an existing directory.
  • References: new algorithms include a URL to Wikipedia or a comparable explanation.

Running the suite locally

This project is managed with uv — there is no requirements.txt. Dependencies live in pyproject.toml/uv.lock, and uvx runs a tool in a throwaway environment without polluting yours:

uvx pre-commit run --all-files                       # ruff, formatting, hooks
uvx pytest your_module/your_file.py --doctest-modules

(uv run pytest ... works too if you'd rather use the project's locked environment.)

Some directories are intentionally skipped in CI (--ignore entries in .github/workflows/build.yml), usually because a heavy dependency lacks a wheel for the CPython version the repo currently targets. Check that list before assuming a file is untested.

Good agent behavior

  • Keep diffs minimal and scoped to the stated change.
  • Preserve existing style and structure; prefer clarity over cleverness.
  • Never fabricate doctest output — run it and paste the real result.
  • If CI is red, read the log and fix the cause rather than re-running blindly.