Darglint2

一个功能文档字符串检查器，用于检查文档字符串的描述是否与实际的函数/方法实现匹配。《Darglint2》期望使用Google Python风格指南、Sphinx风格指南或Numpy风格指南格式化文档字符串。

如果您发现问题或希望在《darglint2》中添加功能，请随时提交问题/拉取请求。

目录:

• 项目状态
• 安装
• 配置
• 使用
• 范围
• Sphinx
• Numpy
• 集成
• Flake8
• 路线图
• 贡献

项目状态

这是darglint的分支重命名，由@terrencepreilly创建，我正在维护它并接受错误修复。

安装

要安装《darglint2》，请使用pip。

pip install darglint2

或者，克隆仓库，使用cd进入目录，

pip install .

配置

《darglint2》可以使用配置文件进行配置。配置文件必须命名为.darglint2、.darglint、setup.cfg或tox.ini。它还必须有一个以[darglint2]开头的部分。最后，配置文件必须位于调用《darglint2》的目录或该工作目录的父目录中。

目前，配置文件允许我们忽略错误，指定消息模板，指定检查的严格程度，以及忽略常见异常。

错误配置

如果我们想忽略ExcessRaiseError（因为我们知道底层函数会抛出异常），那么我们可以将其错误代码添加到名为.darglint2的文件中。

[darglint2]
ignore=DAR402

我们可以使用逗号分隔的列表来忽略多个错误。

[darglint2]
ignore=DAR402,DAR103

除了指定要忽略的一般错误代码外，还可以指定正则表达式来排除测试中某些函数名。例如，以下配置将禁用所有私有方法的lint检查。

[darglint2]
ignore_regex=^_(.*)

消息模板配置

如果我们想指定消息模板，可以按照以下方式操作

[darglint2]
message_template={msg_id}@{path}:{line}

这将生成类似DAR102@driver.py:72的消息。

最后，我们可以使用docstring_style（默认为“google”）来指定文档字符串样式类型。

[darglint2]
docstring_style=sphinx

严格程度配置

严格程度决定了darglint2在检查文档字符串时的宽松程度。有三个级别的严格程度可用

• short：一行描述是可接受的；任何更多内容都将进行全面检查的文档字符串。

• long：一行描述以及没有参数/返回/yields等部分的描述将被允许。任何更多内容都将进行全面检查。

• full：（默认）文档字符串将进行全面检查。

例如，如果我们有以下函数

def double(x):
    # <docstring>
    return x * 2

则以下表格描述了在每种配置（列）下对每个文档字符串（行）进行检查时将引发哪些错误

┌──────────────────────────────┬──────────────────┬────────────────┬──────────────────┐
│ Docstring                    │  short           │  long          │  full            │
├──────────────────────────────┼──────────────────┼────────────────┼──────────────────┤
│ """Doubles the argument."""  │ None             │ None           │ Missing argument │
│                              │                  │                │ Missing return   │
│                              │                  │                │                  │
│                              │                  │                │                  │
├──────────────────────────────┼──────────────────┼────────────────┼──────────────────┤
│ """Doubles the argument.     │ Missing argument │ None           │ Missing argument │
│                              │ Missing return   │                │ Missing return   │
│ Not very pythonic.           │                  │                │                  │
│                              │                  │                │                  │
│ """                          │                  │                │                  │
│                              │                  │                │                  │
├──────────────────────────────┼──────────────────┼────────────────┼──────────────────┤
│ """Doubles the argument.     │ Missing return   │ Missing return │ Missing return   │
│                              │                  │                │                  │
│ Args:                        │                  │                │                  │
│     x: The number to double. │                  │                │                  │
│                              │                  │                │                  │
│ """                          │                  │                │                  │
└──────────────────────────────┴──────────────────┴────────────────┴──────────────────┘

简而言之，如果您想能够有单行文档字符串，并检查其他所有文档字符串的描述参数，您可以在配置文件中指定

[darglint2]
strictness=short

。

忽略常见异常

我们可以指定一个不需要在文档字符串的raises部分中记录的异常列表。例如

[darglint2]
ignore_raise=ValueError,MyCustomError

记录

当darglint2意外失败时，您可以在提交错误时尝试通过运行记录来收集更多信息。例如

darglint2 --log-level=INFO unexpected_failures.py

Darglint2接受以下级别：DEBUG、INFO、WARNING、ERROR和CRITICAL。

使用

命令行使用

给定一个Python源文件，例如serializers.py，您将按照以下方式检查文档字符串

darglint2 serializers.py

您可以为darglint2提供可选的详细程度设置。例如

darglint2 -v 2 *.py

将给出错误的描述以及有关此特定实例的信息。默认详细程度为1，它给出文件名、函数名、行号、错误代码和一些一般提示。

要使用任意错误格式，您可以传递一个消息模板，它是一个Python格式字符串。例如，如果我们传递以下消息模板

darglint2 -m "{path}:{line} -> {msg_id}" darglint2/driver.py

则我们会得到以下错误消息

darglint2/driver.py :61 -> DAR101

以下属性可以传递给格式字符串

• line：行号，
• msg：错误消息，
• msg_id：错误代码，
• obj：函数/方法名，
• path：相对文件路径。

消息模板也可以在配置文件中指定为message_template的值。

darglint2与实用程序find结合使用特别有用。这允许我们一次性检查我们项目中所有文件。例如，当我倾向于“吃自己的狗粮”时，我会按照以下方式调用darglint2

find . -name "*.py" | xargs darglint2

其中我在当前目录及其子目录中递归搜索所有以".py"结尾的文件，并依次对每个文件调用darglint2。

在文档字符串中忽略错误

您可以在特定的文档字符串中忽略特定的错误。语法与pycodestyle等类似。它通常采取以下形式

# noqa: <error> <argument>

其中<error>是要忽略的特定错误（例如DAR402或DAR201），而<argument>是忽略语句指代的（如果什么也不指代，则不指定）。

假设我们想要忽略以下文档字符串中缺少的返回语句

def we_dont_want_a_returns_section():
  """Return the value, 3.

  # noqa: DAR201

  """
  return 3

我们将 noqa 放置在文档字符串的最高级别中。但是，如果我们缺少更具体的内容，比如一个参数，那么它将不起作用。我们可能也不希望忽略所有缺少的参数，只针对一个特定的参数。例如，我们可能正在编写一个函数，该函数接受一个类实例作为 self。（比如说在一个绑定的 celery 任务中。）那么我们可能这样做

def a_bound_function(self, arg1):
  """Do something interesting.

  Args:
    arg1: The first argument.

  # noqa: DAR101 arg1

  """
  arg1.execute(self)

因此，参数出现在错误信息的右边。

我们可能还希望标记多余的文档为正常。例如，我们可能不希望显式地捕获并引发一个 ZeroDivisionError。我们可以这样做

def always_raises_exception(x):
    """Raise a zero division error or type error.o

    Args:
      x: The argument which could be a number or could not be.

    Raises:
      ZeroDivisionError: If x is a number.  # noqa: DAR402
      TypeError: If x is not a number.  # noqa: DAR402

    """
    x / 0

因此，在这种情况下，noqa 的参数实际上一直延伸到左边。（或者我们正在解析的任何描述。）我们也可以将其放在单独的一行上，如 # noqa: DAR402 ZeroDivisionError。

类型注解

Darglint2 解析文档字符串中的类型注解，并且可以（可选地）将文档中的类型与实际的类型注解进行比较。这在将代码库迁移到使用类型注解时非常有用。

为了进行比较，Darglint2 只接受 Python 所接受的类型（参见 PEP 484）。也就是说，它不接受类型签名中的括号。（如果类型签名中使用了括号，Darglint2 将标记该参数为缺失。参见问题 #90。）

错误代码

• DAR001：由于语法错误，文档字符串没有被正确解析。
• DAR002：参数/异常缺少描述
• DAR003：一行缩进不足或过多。
• DAR004：文档字符串中不应该有额外的换行符。
• DAR005：项目包含一个类型部分（括号），但没有类型。
• DAR101：文档字符串在定义中缺少参数。
• DAR102：文档字符串包含函数中不存在的参数。
• DAR103：文档字符串参数类型与函数不匹配。
• DAR104：（已禁用）文档字符串参数没有指定类型
• DAR105：文档字符串参数类型格式不正确。
• DAR201：文档字符串在定义中缺少返回值。
• DAR202：文档字符串有返回值但不在定义中。
• DAR203：文档字符串参数类型与函数不匹配。
• DAR301：文档字符串在定义中缺少定义中存在的 yield。
• DAR302：文档字符串有定义中不存在的 yield。
• DAR401：文档字符串缺少引发异常。
• DAR402：文档字符串描述了一个未显式引发的异常。
• DAR501：文档字符串描述了一个未定义的变量。

百位数字缩小了文档字符串中错误的位置范围

• 000：语法、格式和样式
• 100：Args 部分
• 200：Returns 部分
• 300：Yields 部分
• 400：Raises 部分
• 500：Variables 部分

您可以在配置文件中使用 enable 选项启用默认禁用的异常。它接受由逗号分隔的错误代码列表。

[darglint2]
enable=DAR104

范围

Darglint2 的主要重点是识别函数签名的错误和缺失文档。检查样式是一个目标，将尽力支持。Darglint2 不检查 Python 代码质量权威机构（通过如 pydocstyle 等工具）中表达的风格偏好。因此，当使用 Darglint2 时，如果希望强制执行样式，最好同时使用 pydocstyle。（例如，pydocstyle 要求简短摘要与其它部分之间有一个换行符。Darglint2 不进行此类检查。）

Sphinx

Darglint2 可以处理 Sphinx 风格的文档字符串，但在 Sphinx 风格的基础上增加了一些限制。例如，所有字段（如 :returns:）都必须是文档字符串中的最后项。它们必须在一起，并且所有缩进应为四个空格。这些限制可能在将来放宽。

要分析 Sphinx 风格的文档字符串，将样式标志传递给命令

darglint2 -s sphinx example.py
darglint2 --docstring-style sphinx example.py

或者，您可以在配置文件中使用“docstring_style”设置来指定样式

[darglint2]
docstring_style=sphinx

Numpy

Darglint2 现在对 Numpy 风格的文档字符串有一个初始实现。与 Sphinx 风格的文档字符串类似，您可以将样式标志传递给命令

darglint2 -s numpy example.py
darglint2 --docstring-style numpy example.py

或者设置在配置文件中

[darglint2]
docstring_style=numpy

Numpy 解析器和错误报告器尚未完全稳定。将问题或建议添加到跟踪错误，问题 #69。

集成

Flake8

Darglint2 可以与 Flake8 一起作为插件使用。所需的唯一设置是在同一环境中安装 Flake8 和 Darglint2。Darglint2 将从 Flake8 中获取其配置。因此，如果您想检查 Sphinx 风格的注释，那么您应该在项目目录下的 Flake8 配置文件中设置 docstring_style=sphinx。设置将输入到 flake8 配置下，而不是 Darglint2 的单独配置中。例如：

[flake8]
strictness=short
docstring_style=sphinx

要查看通过 Flake8 暴露的哪些选项，可以检查 Flake8 工具

flake8 --help | grep --before-context=2 Darglint2

SublimeLinter

可以在这里找到 SublimeLinter 的插件。请注意，它是为原始 darglint 构建的，而不是 darglint2，并且其与 darglint2 的兼容性尚未得到验证。

Pre-commit

下载 pre-commit 并 安装 它。一旦安装，请将以下内容添加到存储库中的 .pre-commit-config.yaml

repos:
-   repo: https://github.com/akaihola/darglint2
    rev: master
    hooks:
    - id: darglint2

然后运行 pre-commit install，然后您就可以使用了。在提交之前，将在已暂存的文件上运行 darglint2。如果它发现任何错误，用户将被通知，并将取消提交。在 .darglint2、.darglint、setup.cfg 或 tox.ini 中存储必要的配置（例如错误格式）。

路线图

以下是一些在 2023 年 2 月分叉时的原始 darglint 项目的功能或努力。如果与某个里程碑或问题相关联，将提到它。其中一些想法是雄心勃勃的，可能不会实现。它们按原始作者提出的优先级/可行性顺序排列。

• 通过 Sphinx 暴露命令行选项。
• 对 darglint2 造成的/遇到的错误进行健壮的记录。
• 检查类文档字符串（见 darglint#25）。
• 自动格式化文档字符串。（见 darglint milestone #3）。
• 通过命令行标志启用可选的激进风格检查。
• ALE 支持。
• Syntastic 支持。（Syntastic 不接受新的检查器，直到他们的下一个 API 稳定，所以这可能需要一些时间。）

开发和贡献

开发设置

安装 darglint2。首先，克隆存储库

git clone https://github.com/akaihola/darglint2.git

cd 进入目录，创建虚拟环境（可选），然后设置

cd darglint2/
virtualenv -p python3.6 .env
source .env/bin/activate
pip install -e .

您可以使用以下方式安装依赖项

pip install poetry
poetry install

您可以使用以下方式运行测试

python setup.py test

或者，手动安装 pytest，cd 到项目的根目录，并运行

pytest

此项目试图遵循由 pycodestyle 和 pydocstyle 强制执行的样式，以及由 darglint2 自身强制执行的样式。

存在一个 Dockerfile，用于在 Python3.4 上进行测试。尽管它不是官方支持（只支持 3.6+），但它很棒，尝试使小版本号支持它。您将构建 Dockerfile 并使用类似以下方式测试

pushd docker-build
docker build -t darglint2-34 -f Dockerfile.test34 .
popd
docker run -it --rm -v $(pwd):/code darglint2-34 pytest

贡献

如果您想处理一个问题或功能，请给我发电子邮件或在问题上进行评论，以确保它尚未被处理。贡献将通过拉取请求接受。新功能应包括单元测试，当然，还有格式良好的文档。

此外，在更新语法之前，请查看 wiki。它包括 darglint2 解析管道的描述。