# TheAlgorithms/Python — codebase unpack

> Canonical page: https://codevetter.com/unpack/python

This is a deterministic Repo Unpack scan of TheAlgorithms/Python — a structural map, not a review, security audit, or maintainer-endorsed description.

- Scanned commit: 52b9b913e08ea5afe81e82c1f502887c049750ba (2026-09-22)
- Last upstream commit: refactor(maths): use direct iteration instead of index-based loops in persistence.py (#14767)
- Generated by codevetter 1.12.0 on 2026-09-22
- 1697 files scanned · 5.6 MB

## Languages

- Python: 1582 files
- Markdown: 37 files
- YAML: 17 files
- Shell: 7 files
- JSON: 3 files
- TOML: 1 files

## Repository structure

- project_euler/ — 344 files
- maths/ — 217 files
- data_structures/ — 144 files
- graphs/ — 69 files
- strings/ — 65 files
- sorts/ — 62 files
- ciphers/ — 56 files
- dynamic_programming/ — 53 files

Probable source entrypoint: `project_euler/` (inferred from the tree, not upstream docs)

## Source layout — project_euler/

- project_euler/problem_001/ — 8 files
- project_euler/problem_006/ — 5 files
- project_euler/problem_007/ — 4 files
- project_euler/problem_008/ — 4 files
- project_euler/problem_009/ — 5 files
- project_euler/problem_030/ — 2 files
- project_euler/problem_031/ — 3 files
- project_euler/problem_036/ — 2 files
- project_euler/problem_037/ — 2 files
- project_euler/problem_038/ — 2 files
- project_euler/problem_039/ — 2 files
- project_euler/problem_052/ — 2 files
- project_euler/problem_053/ — 2 files
- project_euler/problem_054/ — 4 files

## Package

- pyproject.toml: thealgorithms-python v0.0.1 — 0 declared dependencies

## Structural health signals

Average score 6.8/10 across 96 files; 20 hotspots. These are deterministic review leads, not proof of a bug.

## Recent history

- 52b9b913e08e (2026-09-22) refactor(maths): use direct iteration instead of index-based loops in persistence.py (#14767)
- a5f5f60cd501 (2026-09-22) fix typo in binomial_distribution.py output (#14779)
- a0b2ef538a26 (2026-09-22) Fix incorrect doctest and improve log handling in num_digits functions (#13850)
- e2ada021591d (2026-09-22) chore: uv sync --upgrade + relock; make scripts/pr_file_map.py executable (#15398)
- 7202e13f8267 (2026-09-22) Add t-SNE implementation and tests for dimensionality reduction (#13337)

## Overview

TheAlgorithms/Python is a large, flat collection of ~1,500 self-contained educational algorithm implementations in Python, organized by topic into ~45 top-level directories (sorts/, graphs/, maths/, ciphers/, project_euler/, etc.). It is not a deployable application — each file is an independent, doctest-driven module aimed at learners, and the project's real 'system' is its CI machinery: pytest running doctests across the whole tree on free-threaded Python 3.14t, ruff linting, an informational ty type-check, a SHA-256 answer oracle for Project Euler solutions, and bots/workflows that regenerate DIRECTORY.md and docs. Contributions are gated by strict conventions (doctests, type hints, snake_case filenames, one algorithm per PR) enforced by GitHub Actions and the algorithms-keeper bot.

## System map

There is no runnable service or package entrypoint — the repo is a flat namespace of independent algorithm modules, declared as a 'virtual' project (no [build-system] in pyproject.toml) so `uv sync` installs only dependencies. The de-facto runtime is CI: eight GitHub Actions workflows gate PRs (build, ruff, ty, project_euler, sphinx, directory_writer, hacktoberfest_prep, devcontainer_ci). Tooling lives in scripts/ (directory generation, filename validation, Euler answer validation, PR janitor shell scripts). Storage is limited to checked-in artifacts: DIRECTORY.md (generated index), scripts/project_euler_answers.json (hashed answers), uv.lock, and docs/hacktober_2026_prep.md (bot-maintained tracker). External integrations are GitHub's API (gh CLI, GITHUB_TOKEN), GitHub Pages for Sphinx docs, and incidental web scraping inside web_programming/ modules.
- pyproject.toml declares project 'thealgorithms-python' v0.0.1 with requires-python >=3.14 and no [build-system] table, so uv treats the repo as a virtual project and installs only dependencies — it is never built as a wheel. — [pyproject.toml#L1-12](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/pyproject.toml#L1-L12) [.github/workflows/ty.yml#L27-34](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/ty.yml#L27-L34)
- The interpreter target is free-threaded CPython 3.14t, pinned via .python-version (contents '3.14t'); classifiers advertise Python 3.14/3.15 and 'Free Threading :: 2 - Beta'. — [.python-version](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.python-version) [pyproject.toml#L7-12](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/pyproject.toml#L7-L12)
- Dependencies (numpy, scipy, pandas, scikit-learn, keras, matplotlib, pillow, sympy, httpx2, etc.) are managed by uv with a checked-in uv.lock; there is intentionally no requirements.txt. — [pyproject.toml#L13-32](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/pyproject.toml#L13-L32) [AGENTS.md](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/AGENTS.md)
- opencv-python and qiskit are quarantined into optional dependency groups 'cv' and 'quantum' because they lack free-threaded 3.14t wheels, and the corresponding test trees are --ignore'd in CI. — [pyproject.toml#L44-64](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/pyproject.toml#L44-L64) [.github/workflows/build.yml#L42-58](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/build.yml#L42-L58)
- Eight workflows in .github/workflows/ form the entire build/deploy pipeline: build.yml (pytest+coverage), ruff.yml (lint gate), ty.yml (informational type check), project_euler.yml (Euler doctests + answer validation), sphinx.yml (docs→GitHub Pages), directory_writer.yml (regenerate DIRECTORY.md on push), hacktoberfest_prep.yml (daily tracker bot), devcontainer_ci.yml. — [.github/workflows/build.yml](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/build.yml) [.github/workflows/ruff.yml](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/ruff.yml) [.github/workflows/sphinx.yml](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/sphinx.yml) [.github/workflows/directory_writer.yml](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/directory_writer.yml)
- scripts/ is the only 'application code' layer: build_directory_md.py generates DIRECTORY.md, validate_filenames.py enforces naming, validate_solutions.py is the Euler oracle, hacktoberfest_prep_update.py and pr_file_map.py are maintainer bots, and close_pull_requests_with_*.sh are janitor scripts. — [scripts/build_directory_md.py](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/scripts/build_directory_md.py) [scripts/validate_solutions.py](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/scripts/validate_solutions.py) [scripts/hacktoberfest_prep_update.py](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/scripts/hacktoberfest_prep_update.py) [scripts/README.md](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/scripts/README.md)
- scripts/project_euler_answers.json is the persistent store of expected Project Euler answers as SHA-256 hex digests, loaded at module import time by validate_solutions.py. — [scripts/project_euler_answers.json](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/scripts/project_euler_answers.json) [scripts/validate_solutions.py#L21-28](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/scripts/validate_solutions.py#L21-L28)
- DIRECTORY.md is a fully generated artifact — build_directory_md.py walks the tree and prints a nested Markdown index, and directory_writer.yml regenerates and force-pushes it on every push; CONTRIBUTING.md forbids editing it by hand. — [scripts/build_directory_md.py#L67-96](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/scripts/build_directory_md.py#L67-L96) [.github/workflows/directory_writer.yml#L17-27](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/directory_writer.yml#L17-L27) [CONTRIBUTING.md#L216](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/CONTRIBUTING.md#L216)
- Documentation deployment is Sphinx + sphinx-autoapi + myst-parser: docs/conf.py enumerates 43 algorithm dirs in autoapi_dirs and sphinx.yml builds docs/_build/html and deploys to GitHub Pages on non-PR events. — [docs/conf.py#L19-78](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/docs/conf.py#L19-L78) [.github/workflows/sphinx.yml#L42-58](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/sphinx.yml#L42-L58)
- Local dev tooling is uv + pre-commit: .pre-commit-config.yaml wires ruff-check, ruff-format, codespell, pyproject-fmt, rumdl, auto-walrus, uv-lock, validate-pyproject, and a local validate-filenames hook. — [.pre-commit-config.yaml](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.pre-commit-config.yaml)
- A devcontainer (.devcontainer/devcontainer.json, Dockerfile, post_install) and .gitpod.yml provide reproducible contributor environments; devcontainer_ci.yml builds it on changes. — [.devcontainer/devcontainer.json](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.devcontainer/devcontainer.json) [.devcontainer/Dockerfile](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.devcontainer/Dockerfile) [.github/workflows/devcontainer_ci.yml](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/devcontainer_ci.yml) [.gitpod.yml](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.gitpod.yml)
- Each algorithm directory is a self-contained namespace (typically <topic>/<file>.py plus __init__.py); modules do not import each other across directories in general, so there is no internal package graph to map. (inferred) — [DIRECTORY.md](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/DIRECTORY.md) [sorts/bubble_sort.py](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/sorts/bubble_sort.py) [project_euler/problem_001/sol1.py](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/project_euler/problem_001/sol1.py)

## Feature catalog

'Features' here are per-topic algorithm collections rather than product features: ~45 directories covering classic CS domains (sorts, searches, graphs, data_structures, dynamic_programming, ciphers, strings, maths), applied domains (machine_learning, neural_network, computer_vision, digital_image_processing, physics, electronics, financial, geodesy), curiosities (fractals, cellular_automata, fuzzy_logic, genetic_algorithm, quantum), a 344-file project_euler/ tree with a strict solution() contract, and web_programming/ scrapers that hit live third-party sites. Every module is directly runnable via its __main__ block and self-testing via doctests.
- sorts/ contains ~60 comparison and non-comparison sorts; sorts/bubble_sort.py alone ships bubble_sort_iterative and bubble_sort_recursive behind a shared Comparable Protocol and exercises a timing benchmark in its __main__ block. — [sorts/bubble_sort.py#L4-11](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/sorts/bubble_sort.py#L4-L11) [sorts/bubble_sort.py#L153-176](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/sorts/bubble_sort.py#L153-L176) [tests/test_sorts.py#L25-47](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/tests/test_sorts.py#L25-L47)
- project_euler/ holds per-problem packages problem_NNN/ with multiple solN.py variants, each exposing a solution() function whose default arguments answer the problem (e.g. problem_001/sol1.py solution(n: int = 1000)). — [project_euler/problem_001/sol1.py#L13-33](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/project_euler/problem_001/sol1.py#L13-L33) [project_euler/README.md#L28-30](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/project_euler/README.md#L28-L30)
- web_programming/ is a set of live scrapers/API clients: current_stock_price.py fetches Yahoo Finance HTML and parses a data-testid span with BeautifulSoup; fetch_anime_and_play.py scrapes gogoanime2.org search/episode/download URLs using fake-useragent. — [web_programming/current_stock_price.py#L23-38](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/web_programming/current_stock_price.py#L23-L38) [web_programming/fetch_anime_and_play.py#L14-41](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/web_programming/fetch_anime_and_play.py#L14-L41)
- Other web_programming modules cover Hacker News, IMDb top-250 CSV export, COVID stats via XPath, GitHub info, currency conversion, Slack messages, reCAPTCHA verification, Reddit, NASA data, and Google result crawling — each a standalone network client. — [web_programming/get_top_hn_posts.py](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/web_programming/get_top_hn_posts.py) [web_programming/get_imdb_top_250_movies_csv.py](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/web_programming/get_imdb_top_250_movies_csv.py) [web_programming/covid_stats_via_xpath.py](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/web_programming/covid_stats_via_xpath.py) [web_programming/recaptcha_verification.py](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/web_programming/recaptcha_verification.py)
- data_structures/ (144 files) implements linked lists, stacks/queues, hash maps, binary trees, kd-trees, suffix trees, tries, disjoint sets, and hashing — several with dedicated tests/ subdirectories (e.g. hashing/tests/test_hash_map.py, kd_tree/tests/test_kdtree.py). — [data_structures/hashing/tests/test_hash_map.py](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/data_structures/hashing/tests/test_hash_map.py) [data_structures/kd_tree/tests/test_kdtree.py](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/data_structures/kd_tree/tests/test_kdtree.py) [data_structures/suffix_tree/tests/test_suffix_tree.py](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/data_structures/suffix_tree/tests/test_suffix_tree.py)
- maths/ (217 files) is the largest non-Euler domain — primality tests, factorials, number theory, geometry helpers — with sibling test files like test_prime_check.py and test_factorial.py alongside implementations. — [maths/test_prime_check.py](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/maths/test_prime_check.py) [maths/test_factorial.py](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/maths/test_factorial.py) [maths/solovay_strassen_primality_test.py](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/maths/solovay_strassen_primality_test.py)
- file_transfer/send_file.py + receive_file.py demonstrate raw TCP socket file transfer on port 12312, with a testing flag so tests/test_send_file.py can exercise one accept loop. — [file_transfer/send_file.py#L1-31](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/file_transfer/send_file.py#L1-L31) [file_transfer/tests/test_send_file.py](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/file_transfer/tests/test_send_file.py)
- machine_learning/ and neural_network/ implement algorithms from scratch (linear regression, sequential minimal optimization for SVM, LSTM prediction, input_data MNIST loader) rather than being thin wrappers, per CONTRIBUTING.md's 'add unique value' rule. — [machine_learning/sequential_minimum_optimization.py](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/machine_learning/sequential_minimum_optimization.py) [machine_learning/linear_regression.py](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/machine_learning/linear_regression.py) [neural_network/input_data.py](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/neural_network/input_data.py) [CONTRIBUTING.md#L67-68](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/CONTRIBUTING.md#L67-L68)
- graphs/ (69 files) covers traversal, shortest paths (Floyd-Warshall, Johnson), minimum spanning trees (Kruskal, Prim), and flow networks, with a graphs/tests/ subdirectory of pytest modules. — [graphs/tests/test_min_spanning_tree_kruskal.py](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/graphs/tests/test_min_spanning_tree_kruskal.py) [graphs/tests/test_graphs_floyd_warshall.py](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/graphs/tests/test_graphs_floyd_warshall.py) [graphs/tests/test_johnson.py](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/graphs/tests/test_johnson.py)
- ciphers/ (56 files) implements classical and modern ciphers; hashes/enigma_machine.py is one of a few files granted a per-file ruff ignore (BLE001 blind-except) in pyproject.toml. — [pyproject.toml#L156-176](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/pyproject.toml#L156-L176) [hashes/enigma_machine.py](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/hashes/enigma_machine.py)
- quantum/q_fourier_transform.py is the single module importing qiskit; it is skipped in the 3.14t CI run because qiskit re-enables the GIL under free threading. — [pyproject.toml#L56-64](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/pyproject.toml#L56-L64) [.github/workflows/build.yml#L40-55](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/build.yml#L40-L55)
- digital_image_processing/ is almost entirely cv2-based and is excluded wholesale from the free-threaded test run until a cp314t opencv wheel ships. — [.github/workflows/build.yml#L31-49](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/build.yml#L31-L49) [pyproject.toml#L44-51](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/pyproject.toml#L44-L51)

## Data flow

Because there is no service, 'data flow' means contributor/CI data flow. Inputs are algorithm modules (pure functions with doctests) and repo metadata. pytest --doctest-modules imports every module and runs embedded examples, feeding a coverage report; Project Euler answers flow through importlib-loaded modules' solution() into a SHA-256 comparison against a checked-in JSON oracle; DIRECTORY.md flows from an os.walk of the tree into a force-pushed commit; and the hacktoberfest bot flows GitHub API data into a tracked markdown file and a rolling PR. Output boundaries are stdout/CI logs, generated markdown files, and a GitHub Pages site.
- pytest is configured via [tool.pytest] ini_options with --doctest-modules, --durations=10, --showlocals and a 'mat_ops' marker; the build workflow runs it under pytest-run-parallel with --iterations=8 and --parallel-threads=auto to flush out GIL-dependent code. — [pyproject.toml#L217-225](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/pyproject.toml#L217-L225) [.github/workflows/build.yml#L42-43](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/build.yml#L42-L43)
- Coverage omits .env/* and project_euler/* and sorts the report by coverage percentage; the build job emits --cov-report=term-missing:skip-covered --cov=. . — [pyproject.toml#L227-232](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/pyproject.toml#L227-L232) [.github/workflows/build.yml#L59-60](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/build.yml#L59-L60)
- Euler validation flow: collect_solution_file_paths() picks either PR-added sol*.py files (via GITHUB_EVENT_PATH → GitHub API /files) or all of project_euler/; convert_path_to_module() exec_module's each file; test_project_euler calls solution(), SHA-256-hashes the stringified answer, and asserts equality with PROBLEM_ANSWERS[problem_number]. — [scripts/validate_solutions.py#L30-48](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/scripts/validate_solutions.py#L30-L48) [scripts/validate_solutions.py#L82-108](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/scripts/validate_solutions.py#L82-L108)
- DIRECTORY.md generation flow: good_file_paths() os.walks the repo skipping dot-dirs/venv/scripts/__init__.py, yields .py/.ipynb paths, print_directory_md() sorts them and prints a numbered table of contents plus nested bullet links via print_path()/md_prefix()/md_anchor(). — [scripts/build_directory_md.py#L7-18](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/scripts/build_directory_md.py#L7-L18) [scripts/build_directory_md.py#L67-92](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/scripts/build_directory_md.py#L67-L92)
- directory_writer.yml pipes build_directory_md.py stdout through `tee DIRECTORY.md`, commits as the actor, and force-pushes — so the generated file is an output boundary written back into the repo by automation. — [.github/workflows/directory_writer.yml#L17-27](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/directory_writer.yml#L17-L27)
- hacktoberfest_prep_update.py reads docs/hacktober_2026_prep.md, parses tracked rows with ROW_RE (`N. [ ] #PR ...`), queries the GitHub REST API through a single httpx2.AsyncClient at CONCURRENCY=5, ticks merged/closed PRs, and rewrites the '## Automated statistics' section in place. — [scripts/hacktoberfest_prep_update.py#L1-28](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/scripts/hacktoberfest_prep_update.py#L1-L28) [scripts/hacktoberfest_prep_update.py#L39-59](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/scripts/hacktoberfest_prep_update.py#L39-L59)
- The hacktoberfest workflow deliberately separates dry-run (push/PR events show a git diff only) from persistence (scheduled/manual runs commit to a rolling branch chore/hacktoberfest-2026-prep-refresh and open/update one PR via gh), because master is protected. — [.github/workflows/hacktoberfest_prep.yml#L51-105](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/hacktoberfest_prep.yml#L51-L105)
- Sphinx docs flow: docs/conf.py loads project metadata from pyproject.toml via tomllib, autoapi_dirs lists 43 source trees to scan, sphinx-build -c docs . docs/_build/html produces the site, upload-pages-artifact + deploy-pages publish to GitHub Pages. — [docs/conf.py#L6-24](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/docs/conf.py#L6-L24) [.github/workflows/sphinx.yml#L42-58](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/sphinx.yml#L42-L58) [index.md](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/index.md)
- Web-scraper modules are input boundaries to the live internet: current_stock_price.py builds a Yahoo Finance URL from a symbol and returns parsed text; no caching, rate limiting, or schema validation exists — output is whatever BeautifulSoup finds. — [web_programming/current_stock_price.py#L23-38](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/web_programming/current_stock_price.py#L23-L38) [web_programming/fetch_anime_and_play.py#L36-47](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/web_programming/fetch_anime_and_play.py#L36-L47)
- Individual files declare their own PEP-723 inline script metadata (`# /// script ... dependencies`) so they can be run standalone with uv/uvx without the full project env (e.g. current_stock_price.py, validate_solutions.py). — [web_programming/current_stock_price.py#L1-7](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/web_programming/current_stock_price.py#L1-L7) [scripts/validate_solutions.py#L3-9](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/scripts/validate_solutions.py#L3-L9) [web_programming/fetch_anime_and_play.py#L1-8](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/web_programming/fetch_anime_and_play.py#L1-L8)
- validate_filenames.py reuses good_file_paths() from build_directory_md.py and exits non-zero listing files with uppercase, spaces, hyphens, or no parent directory — filename hygiene is enforced as data flowing through the pre-commit local hook. — [scripts/validate_filenames.py#L10-34](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/scripts/validate_filenames.py#L10-L34) [.pre-commit-config.yaml#L49-55](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.pre-commit-config.yaml#L49-L55)
- pr_file_map.py is a maintainer-facing flow: it shells out to `gh` to list open PRs, maps files touched per PR, and emits a Markdown report that isolates DIRECTORY.md conflicts into their own section. — [scripts/pr_file_map.py#L1-20](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/scripts/pr_file_map.py#L1-L20)

## Behavior traces

Three flows characterize the system. (1) PR validation: a contributor push triggers ruff, then the build job syncs uv deps on 3.14t and runs pytest-run-parallel doctests across the tree with a long --ignore list, emitting coverage; ty runs non-blocking in parallel; project_euler changes additionally trigger doctest+answer validation. (2) Merge/push: directory_writer regenerates DIRECTORY.md and force-pushes; sphinx rebuilds and deploys Pages. (3) Euler answer check: pytest parametrizes over solution files, imports each with importlib, calls solution(), hashes, compares to JSON. A fourth operational flow is the daily hacktoberfest tracker refresh.
- PR flow step order: actions/checkout → setup-uv (cache on uv.lock) → setup-python from .python-version (3.14t, prereleases allowed) → conditional apt install libhdf5-dev for keras on pre-release Python → `uv sync --group=test` → `uv run --with=pytest-run-parallel pytest ...` → on success regenerate DIRECTORY.md via tee. — [.github/workflows/build.yml#L11-62](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/build.yml#L11-L62)
- The pytest invocation ignores 13 paths (cv2-dependent computer_vision files, digital_image_processing/, tensorflow/qiskit/MNIST-dependent modules, network-bound web_programming files, project_euler/, docs/conf.py, validate_solutions.py) before running doctests with coverage. — [.github/workflows/build.yml#L42-60](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/build.yml#L42-L60)
- Ruff gate: ruff.yml runs `uvx ruff check --output-format=github .` on push/PR to master using pyproject.toml's lint.select list of ~45 rule families (target py314), with a long lint.ignore list of deferred FIX ME/DO NOT FIX rules. — [.github/workflows/ruff.yml#L10-18](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/ruff.yml#L10-L18) [pyproject.toml#L66-122](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/pyproject.toml#L66-L122)
- ty type-check is advisory: workflow sets continue-on-error: true and invokes `ty check --exit-zero` pinned to regular-GIL Python 3.14, emitting ::error annotations without failing; pyproject [tool.ty] pre-ignores a dozen rule kinds as the baseline is cleaned. — [.github/workflows/ty.yml#L11-17](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/ty.yml#L11-L17) [.github/workflows/ty.yml#L35-53](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/ty.yml#L35-L53) [pyproject.toml#L200-215](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/pyproject.toml#L200-L215)
- Euler CI trace: project_euler.yml is path-filtered to project_euler/**, the workflow file, and validate_solutions.py; job 1 runs `pytest --doctest-modules --cov=project_euler/ project_euler/`, job 2 runs `pytest scripts/validate_solutions.py` with GITHUB_TOKEN. — [.github/workflows/project_euler.yml#L1-41](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/project_euler.yml#L1-L41)
- Inside validate_solutions: at import time PROBLEM_ANSWERS is loaded from scripts/project_euler_answers.json; collect_solution_file_paths() → all_solution_file_paths() iterates problem_* dirs skipping files starting with '_' or 'test'; parametrized test_project_euler → convert_path_to_module → spec.loader.exec_module → module.solution() → sha256(answer) == expected. — [scripts/validate_solutions.py#L26-48](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/scripts/validate_solutions.py#L26-L48) [scripts/validate_solutions.py#L93-108](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/scripts/validate_solutions.py#L93-L108)
- DIRECTORY.md trace on push: directory_writer.yml → checkout fetch-depth:0 → setup-python → `scripts/build_directory_md.py 2>&1 | tee DIRECTORY.md` → git config actor → commit -am 'updating DIRECTORY.md' || true → push --force HEAD:$GITHUB_REF || true. — [.github/workflows/directory_writer.yml#L8-27](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/directory_writer.yml#L8-L27)
- build_directory_md.py print order: good_file_paths() yields sorted paths → a numbered 'Table of Contents' of top-level sections with md_anchor() slugs → print_path() emits '##' headings for new top dirs and nested bullets → each file becomes a titled link with underscores→spaces and %20-escaped URLs. — [scripts/build_directory_md.py#L52-92](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/scripts/build_directory_md.py#L52-L92)
- Hacktoberfest bot trace (scheduled): checkout → pip install httpx2 → python scripts/hacktoberfest_prep_update.py (exit code captured, not fatal) → on schedule/dispatch, diff check docs/hacktober_2026_prep.md → gh auth setup-git → switch -c rolling branch → force-push → gh pr create if none open → propagate script exit code. — [.github/workflows/hacktoberfest_prep.yml#L40-109](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/hacktoberfest_prep.yml#L40-L109)
- The prep script intentionally exits non-zero on/after 2026-10-01 (HACKTOBERFEST_START) so the workflow fails loudly as a retirement signal; transient API failures raise BestEffortError which callers degrade rather than fail. — [scripts/hacktoberfest_prep_update.py#L15-16](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/scripts/hacktoberfest_prep_update.py#L15-L16) [scripts/hacktoberfest_prep_update.py#L44-69](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/scripts/hacktoberfest_prep_update.py#L44-L69)
- Module self-run convention: algorithm files end with `if __name__ == '__main__':` calling doctest.testmod() and/or printing solution() results — e.g. bubble_sort.py runs a 10k-iteration timeit benchmark comparing iterative vs recursive. — [sorts/bubble_sort.py#L153-176](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/sorts/bubble_sort.py#L153-L176) [project_euler/problem_001/sol1.py#L32-33](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/project_euler/problem_001/sol1.py#L32-L33) [web_programming/current_stock_price.py#L42-48](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/web_programming/current_stock_price.py#L42-L48)
- Devcontainer trace: devcontainer_ci.yml only triggers on .devcontainer/** or its own workflow path, and runs devcontainers/ci@v0.3 with push:never and runCmd 'true' — a smoke test that the image builds. — [.github/workflows/devcontainer_ci.yml#L3-23](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/devcontainer_ci.yml#L3-L23)

## Testing signals

The dominant test mechanism is doctests: pytest runs with --doctest-modules across the entire repo, and CONTRIBUTING/AGENTS require every function to carry passing doctests. A minority of modules have real pytest test files — either colocated (maths/test_*.py) or in per-domain tests/ subdirectories (data_structures, graphs, knapsack, geometry, divide_and_conquer, file_transfer) plus a top-level tests/test_sorts.py battery. Project Euler has a dedicated hashed-answer oracle. Coverage is reported but project_euler is excluded; many files are excluded from the 3.14t run entirely via --ignore flags.
- pytest config sets --doctest-modules, --durations=10, --showlocals globally, so every docstring example in every .py file is executed as a test in CI. — [pyproject.toml#L217-222](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/pyproject.toml#L217-L222) [.github/workflows/build.yml#L42-60](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/build.yml#L42-L60)
- tests/test_sorts.py is a shared contract harness: it parametrizes ~20 general-purpose comparison sorts against a common battery and documents which sorts are deliberately excluded (counting/radix/pigeon integer-only, stalin/wiggle not fully sorting, etc.). — [tests/test_sorts.py#L1-60](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/tests/test_sorts.py#L1-L60)
- Dedicated pytest files exist in pockets: data_structures/{hashing,kd_tree,suffix_tree}/tests/, graphs/tests/, knapsack/tests/, geometry/tests/, divide_and_conquer/tests/, file_transfer/tests/, and colocated maths/test_*.py — most of the repo relies solely on doctests. — [data_structures/hashing/tests/test_hash_map.py](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/data_structures/hashing/tests/test_hash_map.py) [graphs/tests/test_min_spanning_tree_kruskal.py](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/graphs/tests/test_min_spanning_tree_kruskal.py) [knapsack/tests/test_knapsack.py](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/knapsack/tests/test_knapsack.py) [maths/test_prime_check.py](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/maths/test_prime_check.py)
- scripts/validate_solutions.py is itself a pytest module: test_project_euler is parametrized over discovered solution paths and asserts the SHA-256 of str(solution()) matches the stored digest, so Euler correctness is verified without exposing plaintext answers. — [scripts/validate_solutions.py#L93-108](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/scripts/validate_solutions.py#L93-L108) [scripts/project_euler_answers.json](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/scripts/project_euler_answers.json)
- The build runs pytest under pytest-run-parallel with --iterations=8 --parallel-threads=auto --ignore-gil-enabled on free-threaded 3.14t, actively probing thread-safety of pure-Python algorithms while tolerating GIL-re-enabling wheels. — [.github/workflows/build.yml#L35-43](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/build.yml#L35-L43)
- Coverage is collected (--cov=. with term-missing report) but project_euler/* and .env/* are omitted from the report; there is no coverage threshold gate. — [pyproject.toml#L227-232](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/pyproject.toml#L227-L232) [.github/workflows/build.yml#L59-60](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/build.yml#L59-L60)
- Thirteen paths are excluded from the test run via --ignore flags — including the whole digital_image_processing/ tree, project_euler/ (tested in its own workflow), and network-dependent web_programming files — so 'CI green' does not mean those files ran. — [.github/workflows/build.yml#L44-58](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/build.yml#L44-L58) [AGENTS.md](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/AGENTS.md)
- Doctest conventions include exception tests (doctest: +IGNORE_EXCEPTION_DETAIL for TypeError on mixed-type input) and randomized-sample assertions (random.sample inputs compared to sorted()), which make doctests double as property-ish tests. — [sorts/bubble_sort.py#L60-71](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/sorts/bubble_sort.py#L60-L71)
- Live-network tests exist: current_stock_price.py's doctests call stock_price('GOOG') expecting a float-parseable string and 'EEEE' expecting an error string — inherently flaky and excluded from CI. — [web_programming/current_stock_price.py#L24-29](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/web_programming/current_stock_price.py#L24-L29) [.github/workflows/build.yml#L57-58](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/build.yml#L57-L58)
- Static checks act as tests: ruff.yml gates on `ruff check`, pre-commit runs ruff-format/codespell/validate-filenames/uv-lock, and ty runs informationally — no unit-test framework other than pytest+doctest is used. — [.github/workflows/ruff.yml#L18](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/ruff.yml#L18) [.pre-commit-config.yaml#L36-65](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.pre-commit-config.yaml#L36-L65) [.github/workflows/ty.yml#L53](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/ty.yml#L53)
- project_euler.yml runs pytest --doctest-modules --cov=project_euler/ only on PRs touching Euler paths (plus daily cron), so Euler doctests are validated separately from the main suite. — [.github/workflows/project_euler.yml#L2-26](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/project_euler.yml#L2-L26)
- There is no conftest.py anywhere in the repo — no shared fixtures; each test file is self-contained, consistent with the one-file-per-algorithm contribution model. — [tests/test_sorts.py](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/tests/test_sorts.py) [data_structures/hashing/tests/test_hash_map.py](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/data_structures/hashing/tests/test_hash_map.py)

## Risk map

Risks are mostly process/supply-chain and flaky-network rather than exploitable bugs in a running system (there is none). Notable: workflows that force-push and write to the repo with a token, web scrapers hitting live third-party sites inside doctests, a daily bot that consumes the shared 1000-req/hour GITHUB_TOKEN budget, a hash oracle that will hard-fail if any Euler module import has side effects, known-buggy code (an undefined variable in fetch_anime_and_play.py), and large intentional gaps in test coverage (cv2/qiskit/tf files ignored on 3.14t).
- fetch_anime_and_play.py references `anime_name` inside search_anime_episode_list's error message, but that variable is not defined in that scope — a latent NameError that only triggers when the episode list element is missing. — [web_programming/fetch_anime_and_play.py#L102-105](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/web_programming/fetch_anime_and_play.py#L102-L105)
- directory_writer.yml force-pushes to the pushed ref using GITHUB_TOKEN embedded in the remote URL (x-access-token), and both commit and push end with `|| true` — failures are silently swallowed and a bad regeneration can overwrite the ref. — [.github/workflows/directory_writer.yml#L20-27](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/directory_writer.yml#L20-L27)
- hacktoberfest_prep.yml runs with contents:write and pull-requests:write permissions and uses `gh auth setup-git` to push a rolling branch; the workflow file itself documents that GITHUB_TOKEN is capped at 1000 requests/hour per repo shared across concurrent runs, making the daily job rate-limit-fragile. — [.github/workflows/hacktoberfest_prep.yml#L21-24](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/hacktoberfest_prep.yml#L21-L24) [.github/workflows/hacktoberfest_prep.yml#L70-105](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/hacktoberfest_prep.yml#L70-L105) [scripts/hacktoberfest_prep_update.py#L46-53](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/scripts/hacktoberfest_prep_update.py#L46-L53)
- validate_solutions.py exec_module's arbitrary contributed Python files during CI — necessary for the design, but it means any module-level code in a submitted sol*.py executes in a job that holds GITHUB_TOKEN. (inferred) — [scripts/validate_solutions.py#L30-35](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/scripts/validate_solutions.py#L30-L35) [.github/workflows/project_euler.yml#L39-41](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/project_euler.yml#L39-L41)
- Web scrapers depend on live third-party DOM structure: current_stock_price.py matches span[data-testid='qsp-price'] on Yahoo Finance and fetch_anime_and_play.py targets a hard-coded BASE_URL 'https://ww7.gogoanime2.org' — both will break silently or flake on site changes/rotating pirate domains. — [web_programming/current_stock_price.py#L30-38](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/web_programming/current_stock_price.py#L30-L38) [web_programming/fetch_anime_and_play.py#L14](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/web_programming/fetch_anime_and_play.py#L14)
- file_transfer/send_file.py binds a listening TCP socket on port 12312 to the machine hostname and loops accept() forever unless testing=True; receive counterpart likewise — running it as a script is a permanently open unauthenticated file server. — [file_transfer/send_file.py#L1-31](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/file_transfer/send_file.py#L1-L31)
- CI skips are a blind spot: digital_image_processing/, quantum/q_fourier_transform.py, tensorflow-dependent dynamic_programming/k_means_clustering_tensorflow.py, neural_network/input_data.py, and cv2 computer_vision files are never exercised on the 3.14t runner. — [.github/workflows/build.yml#L42-58](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/build.yml#L42-L58) [pyproject.toml#L44-64](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/pyproject.toml#L44-L64)
- Ruff config ignores dozens of rules marked 'FIX ME'/'DO NOT FIX' (B904 raise-from, PLW2901, RET505, S311 weak-random, SLF001 private-access, blind-except per-file ignores), so real bug classes are deliberately unenforced repo-wide. — [pyproject.toml#L123-176](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/pyproject.toml#L123-L176)
- Ty checking is explicitly non-blocking (continue-on-error + --exit-zero) and [tool.ty] suppresses a dozen diagnostic kinds including unresolved-import/unresolved-attribute — type errors currently cannot fail CI. — [.github/workflows/ty.yml#L13-17](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/ty.yml#L13-L17) [.github/workflows/ty.yml#L44-53](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/ty.yml#L44-L53) [pyproject.toml#L204-215](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/pyproject.toml#L204-L215)
- Several modules read input() interactively in __main__ blocks (e.g. fetch_anime_and_play.py prompts three times) and CONTRIBUTING.md discourages but permits input() with .strip() — scripts hang waiting on stdin if run non-interactively. — [web_programming/fetch_anime_and_play.py#L166-197](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/web_programming/fetch_anime_and_play.py#L166-L197) [CONTRIBUTING.md#L173-185](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/CONTRIBUTING.md#L173-L185)
- Euler correctness depends on scripts/project_euler_answers.json staying in sync: test_project_euler indexes PROBLEM_ANSWERS[problem_number] with no missing-key handling, so a new problem dir without an answers entry raises KeyError, not a clean failure. — [scripts/validate_solutions.py#L98-108](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/scripts/validate_solutions.py#L98-L108)
- blast-radius: a single bad commit to pyproject.toml (deps), .python-version, or a workflow affects every subsequent CI run for all PRs; conversely individual algorithm files are isolated and nearly impossible to damage each other. (inferred) — [pyproject.toml](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/pyproject.toml) [.python-version](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.python-version) [.github/workflows/build.yml](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/build.yml)

## Extension points

The extension model is 'add a file': drop a snake_case .py module into an existing topic directory, give every function doctests + type hints + a reference URL, and CI/pytest auto-discovers it via --doctest-modules with zero registration. Project Euler has a stricter contract (problem_NNN dirs, solN.py files, one solution() entrypoint, an answers-JSON entry). Generated surfaces (DIRECTORY.md, Sphinx autoapi, coverage) pick up new files automatically; new top-level directories additionally require updating docs/conf.py autoapi_dirs. Optional dependency groups (cv, quantum, euler-validate, docs, test) are the seam for heavy new deps.
- Auto-discovery is the plugin mechanism: pytest --doctest-modules plus os.walk-based good_file_paths() mean a new .py file in any existing directory is tested and indexed with no registry edits. — [pyproject.toml#L217-222](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/pyproject.toml#L217-L222) [scripts/build_directory_md.py#L7-18](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/scripts/build_directory_md.py#L7-L18)
- New top-level directories DO require manual registration: docs/conf.py's autoapi_dirs is a hardcoded list of 43 dirs, and CONTRIBUTING.md says avoid creating new directories anyway. — [docs/conf.py#L24-68](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/docs/conf.py#L24-L68) [CONTRIBUTING.md#L212](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/CONTRIBUTING.md#L212)
- Project Euler extension contract: create project_euler/problem_<NNN>/__init__.py + sol1.py (etc.) exposing solution() whose defaults yield the answer; module docstring must link the problem; answers are enforced by scripts/project_euler_answers.json. — [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) [project_euler/problem_001/sol1.py](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/project_euler/problem_001/sol1.py)
- Per-domain tests/ subdirectories are the pattern for adding real pytest coverage beyond doctests (hashing/tests/, kd_tree/tests/, graphs/tests/, knapsack/tests/), discovered automatically by pytest. — [data_structures/hashing/tests/test_hash_map.py](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/data_structures/hashing/tests/test_hash_map.py) [graphs/tests/test_min_spanning_tree_kruskal.py](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/graphs/tests/test_min_spanning_tree_kruskal.py) [knapsack/tests/test_knapsack.py](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/knapsack/tests/test_knapsack.py)
- New third-party dependencies extend via pyproject.toml dependencies or an optional [dependency-groups] section; the uv-lock pre-commit hook regenerates uv.lock, and heavy/GIL-bound deps should follow the cv/quantum optional-group precedent plus a build.yml --ignore entry. — [pyproject.toml#L13-64](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/pyproject.toml#L13-L64) [.pre-commit-config.yaml#L57-60](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.pre-commit-config.yaml#L57-L60) [.github/workflows/build.yml#L42-58](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/build.yml#L42-L58) [CONTRIBUTING.md#L205](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/CONTRIBUTING.md#L205)
- PEP-723 inline script metadata (`# /// script`) is the lightweight seam for standalone runnable files needing extra deps without touching pyproject — used by web_programming scrapers and validate_solutions.py. — [web_programming/current_stock_price.py#L1-7](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/web_programming/current_stock_price.py#L1-L7) [scripts/validate_solutions.py#L3-9](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/scripts/validate_solutions.py#L3-L9)
- Ruff per-file-ignores in pyproject.toml are the sanctioned escape hatch when a new file legitimately violates a rule (existing entries for BLE001, SIM115, SIM103). — [pyproject.toml#L156-176](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/pyproject.toml#L156-L176)
- Pre-commit local hooks are the extension point for new repo-wide checks — validate-filenames is a `repo: local` hook entry-pointing to scripts/validate_filenames.py; new validators can be added the same way. — [.pre-commit-config.yaml#L49-55](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.pre-commit-config.yaml#L49-L55) [scripts/validate_filenames.py](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/scripts/validate_filenames.py)
- Reusable Comparable Protocol + TypeVar pattern in sorts/bubble_sort.py is the house generic-typing idiom for container algorithms; new sorts should reuse it to satisfy the shared tests/test_sorts.py battery contract (return sorted list, comparable items). — [sorts/bubble_sort.py#L4-11](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/sorts/bubble_sort.py#L4-L11) [tests/test_sorts.py#L1-17](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/tests/test_sorts.py#L1-L17)
- Maintainer automation extends via scripts/ + workflows: hacktoberfest_prep_update.py shows the pattern (httpx2 AsyncClient, GITHUB_TOKEN, TRACKER file rewrite, rolling-branch PR) reusable for new bots. — [scripts/hacktoberfest_prep_update.py#L1-59](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/scripts/hacktoberfest_prep_update.py#L1-L59) [.github/workflows/hacktoberfest_prep.yml#L70-105](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/workflows/hacktoberfest_prep.yml#L70-L105)
- GitHub Skills under .github/skills/ (code-review, new-pull-request, review-open-issue SKILL.md files) encode agent-facing contribution procedures — the repo's own extension surface for AI agents. — [.github/skills/code-review/SKILL.md](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/skills/code-review/SKILL.md) [.github/skills/new-pull-request/SKILL.md](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/skills/new-pull-request/SKILL.md) [.github/skills/review-open-issue/SKILL.md](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/skills/review-open-issue/SKILL.md)
- The one-algorithm-per-PR rule plus 'identical implementations not allowed' in CONTRIBUTING.md defines the feature-addition boundary: variants of an existing algorithm must differ meaningfully (complexity, representation), matching the sol1..solN pattern in project_euler. — [CONTRIBUTING.md#L18](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/CONTRIBUTING.md#L18) [.github/pull_request_template.md#L13](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/.github/pull_request_template.md#L13) [project_euler/problem_001/sol1.py](https://github.com/TheAlgorithms/Python/blob/52b9b913e08ea5afe81e82c1f502887c049750ba/project_euler/problem_001/sol1.py)

## Contributor handoff

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)

Source repository: https://github.com/TheAlgorithms/Python
Full evidence corpus: https://github.com/Codevetter/codevetter/tree/main/benchmarks/repo-unpacks/python.json

## Public product links

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