codespell 2.3.0

有用链接

• GitHub项目

• 仓库

• 版本

需求

Python 3.8或更高版本。

安装

您可以使用 pip 安装 codespell，例如：

pip install codespell

用法

以下是一些简单的用法示例，以演示该工具的工作原理。有关完整的用法信息，请查看 codespell -h 的输出。

在当前目录的所有文件中运行 codespell

codespell

在特定的文件或目录中运行 codespell（通过其名称或glob模式指定）

codespell some_file some_dir/ *.ext

一些值得注意的标志

codespell -w, --write-changes

“-w” 标志实际上将实现 codespell 推荐的更改。不使用 “-w” 标志与执行干跑相同。建议使用 “-i” 或 “--interactive” 标志运行。

codespell -I FILE, --ignore-words=FILE

可以使用 “-I” 标志来指定 codespell 字典中允许的某些单词列表。文件格式是每行一个单词。使用以下方式调用：codespell -I path/to/file.txt 来执行 codespell，并参考该允许单词列表。有关更多详细信息，请参阅 忽略单词。

codespell -L word1,word2,word3,word4

可以使用 “-L” 标志来允许紧跟其后的逗号分隔的某些单词。有关更多详细信息，请参阅 忽略单词。

codespell -x FILE, --exclude-file=FILE

忽略与 FILE 中匹配的整个行。在 FILE 中的行应与要排除的行完全匹配。

codespell -S, --skip=

要跳过的文件的逗号分隔列表。它也接受通配符。例如

• 要跳过 .eps 和 .txt 文件，请调用 codespell --skip="*.eps,*.txt"

• 要跳过目录，请调用 codespell --skip="./src/3rd-Party,./src/Test"

有用命令

codespell -d -q 3 --skip="*.po,*.ts,./src/3rdParty,./src/Test"

列出除翻译文件和一些目录之外的所有发现的错误。以不带终端颜色和静默级别 3 显示它们。

codespell -i 3 -w

运行交互模式级别 3 并将更改写入文件。

我们提供了一组字典，这是在 Linux 内核、EFL、oFono 等项目中应用后改进的版本，这些版本可在 维基百科 上找到。您可以提供自己的字典版本，但对于新/不同的条目补丁非常欢迎。

想要知道您提出的单词是否已在 codespell 中存在？可以通过以下方式测试单词与当前存在于 codespell_lib/data/dictionary*.txt 的当前集合字典：

echo "word" | codespell -
echo "1stword,2ndword" | codespell -

您可以使用 “--builtin” 选项选择可选字典。

忽略单词

在忽略假阳性时，请注意拼写错误是 不区分大小写 的，但要忽略的单词是 区分大小写 的。例如，字典条目 wrod 也会匹配拼写错误 Wrod，但为了忽略它，您必须传递 wrod。

要忽略的单词可以通过两种方式传递

1. -I：一个包含要忽略的单词每行的文件

   codespell -I FILE, --ignore-words=FILE

2. -L：命令行上要忽略的单词的逗号分隔列表

   codespell -L word1,word2,word3,word4

内联忽略

某些情况下可能需要忽略特定位置的具体单词。这可以通过在源代码中添加注释来实现。您可以选择忽略单个单词或单词列表。注释的格式为 codespell:ignore <words>。单词应该用逗号分隔。

1. 忽略特定单词

   def wrod() # codespell:ignore wrod
       pass

2. 忽略多个单词

   def wrod(wrods) # codespell:ignore
       pass

使用配置文件

命令行选项也可以在配置文件中指定。

运行 codespell 时，它将在当前目录中查找名为 setup.cfg 或 .codespellrc（或通过 --config 指定的文件），其中包含名为 [codespell] 的条目。每个命令行参数都可以在此文件中指定（不包含前导短横线），例如

[codespell]
skip = *.po,*.ts,./src/3rdParty,./src/Test
count =
quiet-level = 3

.codespellrc 文件是一个 INI文件，使用Python的 configparser 读取。例如，可以使用 ; 或 # 作为第一字符添加注释。

Codespell 还会在当前目录中查找 pyproject.toml（或通过 --toml <filename> 指定的路径）文件，并使用 [tool.codespell] 条目，但仅当为Python 3.11之前的版本安装了 tomli 包时。例如

[tool.codespell]
skip = '*.po,*.ts,./src/3rdParty,./src/Test'
count = true
quiet-level = 3

这两者都相当于运行

codespell --quiet-level 3 --count --skip "*.po,*.ts,./src/3rdParty,./src/Test"

如果存在多个配置文件，它们的读取顺序如下

1. pyproject.toml（仅当 tomli 库可用时）

2. setup.cfg

3. .codespellrc

4. 通过 --config 供应的任何其他文件

如果在这些文件中的多个文件中提供了 codespell 配置，则最后读取的文件的配置将覆盖先前指定的配置。

命令行中指定的任何选项都将 覆盖 配置文件中的选项。

pre-commit 钩子

codespell 还可以与 pre-commit 一起使用

- repo: https://github.com/codespell-project/codespell
  rev: v2.2.4
  hooks:
  - id: codespell

如果使用 pyproject.toml 文件配置 codespell，则使用

- repo: https://github.com/codespell-project/codespell
  rev: v2.2.4
  hooks:
  - id: codespell
    additional_dependencies:
      - tomli

字典格式

字典的格式受到它们最初来源的影响，即来自维基百科。区别在于如何处理多个选项，以及最后一个参数是为什么某个条目不能直接应用的理由（为什么应该手动检查）。例如

1. 简单条目：一个错误的单词/一个建议

   calulated->calculated

2. 具有多个建议修复的条目

   fiel->feel, field, file, phial,

   注意最后一个逗号！您必须使用它，否则最后一个建议将被丢弃（下面将解释原因）。当有多个建议时，无法自动修复，我们所能做的就是向用户提供发生错误的文件和行以及建议。

3. 只有一个单词但自动修复已禁用的条目

   clas->class, disabled because of name clash in c++

   注意行尾没有逗号。最后一个参数被视为为什么建议不能自动应用的理由。

   也可以有多个建议，但任何自动修复都将再次禁用

   clas->class, clash, disabled because of name clash in c++

开发设置

如 Python 打包用户指南 所建议，在从源安装之前，请确保 pip、setuptools 和 wheel 都是最新的。具体来说，您需要最新的 setuptools 和 setuptools_scm 版本。

pip install --upgrade pip setuptools setuptools_scm wheel

您可以通过在 codespell 源代码的检出中运行以下命令来安装开发所需的依赖项

pip install -e ".[dev]"

要针对代码库运行测试，请运行

make check

发送 pull 请求

如果您有一个希望合并的拼写建议，请按照以下步骤操作

1. 请确保您已经阅读了上面 字典格式 部分中提到的说明，以正确格式提交条目。

2. 选择正确的字典文件以添加您的拼写错误。有关不同字典的解释，请参阅 codespell –help。

3. 对字典进行排序。这通过在 codespell/ 的顶级目录下调用（

   make check-dictionaries

   如果 make 脚本发现你需要排序字典，请运行以下命令：

   make sort-dictionaries

4. 只有在完成此过程后，我们才建议你提交 PR。

重要提示

• 如果字典未预先排序就提交，PR 将会通过我们的各种 CI 工具失败。

• 并非所有 PR 都会合并。这取决于开发人员、维护人员和社区的判断。

更新

为了跟上 codespell 的发展，你可以通过 GitHub 构建 codespell：

pip install --upgrade git+https://github.com/codespell-project/codespell.git

重要提示

• 有时通过 pip 安装会抱怨权限问题。如果是这样，请用以下命令运行：

  pip install --user --upgrade git+https://github.com/codespell-project/codespell.git

• 据报道，从 pip 安装后，codespell 无法找到。请检查 $PATH 变量，看 ~/.local/bin 是否存在。如果不存在，请将其添加到你的路径中。

• 如果你决定通过 pip 安装，请确保移除任何之前安装的 codespell 版本（通过你平台首选的应用程序管理器）。

更新字典

在用户不想跟随 codespell 的开发版本，但仍想从频繁更新的字典文件中受益的情况下，我们建议运行以下简单命令集来达到这个目的：

wget https://raw.githubusercontent.com/codespell-project/codespell/master/codespell_lib/data/dictionary.txt
codespell -D dictionary.txt

上述命令简单地下载最新的 dictionary.txt 文件，然后通过使用 -D 标志允许用户将新下载的 dictionary.txt 作为自定义字典，而不是默认字典。

你也可以为这里列出的其他字典做同样的事情

https://github.com/codespell-project/codespell/tree/master/codespell_lib/data

许可证

Python 脚本 codespell 及其库 codespell_lib 以下列条款提供：(tl;dr: GPL v2)

版权 (C) 2010-2011 Lucas De Marchi <lucas.de.marchi@gmail.com>

版权 (C) 2011 ProFUSION embedded systems

本程序是自由软件；您可以按照自由软件基金会发布的 GNU 通用公共许可证的条款重新分发和/或修改它；许可证版本 2。

本程序按“希望有用”的原则提供，但不提供任何保证；甚至不提供适销性或特定用途的隐含保证。有关详细信息，请参阅 GNU 通用公共许可证。

您应该已随本程序收到一份 GNU 通用公共许可证副本；如果没有，请参阅 <https://gnu.ac.cn/licenses/old-licenses/gpl-2.0.html>。

dictionary.txt 和其他 dictionary_*.txt 文件是英语维基百科的衍生作品，并按 Creative Commons Attribution-Share-Alike License 3.0 发布。