The Algorithms - Python

先接受一件事：这是教科书，不是库

README 顶部原话：这些实现只用于学习目的，效率可能不如 Python 标准库里的实现，自行斟酌使用。

这不是客套。标准库的 sorted、heapq、bisect 是 C 实现的，性能不在一个量级。

当成教科书和练习集用，不要当成生产库用。 装进热路径之前，先找个正经的库。

从 DIRECTORY.md 进

DIRECTORY.md（在新标签页打开） 是导航入口，85KB，按 45 个类别列全所有实现。比在仓库文件树里翻清楚得多。

分类里有些是标准算法教材不会覆盖的：

想找冷门算法的现成实现，这里往往比搜索引擎快。

读一份实现时留意 doctest

这是这个项目比一般算法集认真的地方。贡献规范要求每份实现：

• docstring 里要有清晰说明和/或来源 URL
• doctest 要同时测试有效输入和错误输入

「同时测错误输入」这一条意味着你看到的示例不是只演示顺利路径——异常分支也有覆盖。读代码时可以直接信它给的例子。

自己跑一下某个文件的 doctest：

bashpython -m doctest <文件路径> -v

它的工程规范值得学

规范严到有点不必要，但其中一条原则我认为是精华：

展开缩写。 gcd() 不好懂，greatest_common_divisor() 就懂。规范里明确写「用描述性命名帮你省掉冗余注释」。

意思是：与其写注释解释 gcd 是什么意思，不如把它叫 greatest_common_divisor。命名做好了，注释就省了。

其他可借鉴的：

• 遵循 Python 命名约定：变量和函数小写、常量全大写、类名驼峰（PEP 8）
• 代码风格检查用 ruff
• 格式用 pre-commit 自动处理，不用手改

要提 PR 的话，两条硬规则

一、不接受重复实现。 已有同一算法的实现就别再提一个功能相同的。但官方明确欢迎这几种：

• 同一问题的新解法
• 同一数据结构的不同表示
• 不同复杂度的算法设计

提交前先搜一遍。

二、不要为贡献算法去开 issue，直接提 PR。 仓库官方明说「我们不在这个仓库分配 issue，所以不要请求许可」。开 issue 问「我可以贡献吗」是白费功夫。

测试怎么跑

所有提交会过 GitHub Actions：ruff check 加测试（跑的是 doctest）。提 PR 后页面底部会显示运行状态，失败点 details 能看输出。

在线改

仓库有 Gitpod 支持，徽章就在 README 顶部。不用配环境就能在浏览器里改一个算法练手，对想快速试一段代码很方便。

怎么用它学

推荐顺序：

1. 从 DIRECTORY.md 找一个你正在学的概念
2. 读那份实现的 docstring——它会给你来源链接，那往往是原始论文或教科书
3. 照着它自己写一遍，不要复制
4. 跑 doctest 确认你的理解没错
5. 想贡献就按上面的规范改，命名那一条认真做

第3 步是关键：这个项目的价值在于让你看懂并自己写出实现，复制粘贴等于没学。

什么时候别用它

• 生产代码 —— 官方明说可能不如标准库
• 需要性能保证 —— 这些实现是清晰优先，不是性能优先
• 需要长期维护的库 —— 它是学习集合，不承诺 API 稳定

社区在 Discord（the-algorithms.com/discord），有问题可以在那里问。