flake8-annotations

flake8-annotations 是一个用于 Flake8 的插件，用于检测缺少 PEP 3107-style 函数注解。

此插件不会做以下事情：替换 mypy，检查类型注释（见： PEP 484），检查变量注解（见： PEP 526），或尊重存根文件。

安装

使用您喜欢的 pip 调用从 PyPi 安装

$ pip install flake8-annotations

然后它将作为 flake8 的一部分自动运行。

您可以在 shell 中调用以下内容以验证它是否被识别

$ flake8 --version
7.0.0 (flake8-annotations: 3.1.1, mccabe: 0.7.0, pycodestyle: 2.11.1, pyflakes: 3.2.0) CPython 3.12.3 on Darwin

警告表

除了 ANN4xx 级别的警告外，所有警告默认启用。

函数注解

方法注解

返回值注解

有偏见警告

这些警告默认禁用。

使用 extend-select 启用有偏见警告而无需覆盖其他隐式配置⁴。

注释

1. 参见：PEP 484 和 PEP 563 关于注解 self 和 cls 参数的建议
2. 参见：动态类型注意事项
3. 此插件仅考虑函数声明；不检查函数/模块体中的类型注解
4. 常见陷阱：使用 ignore 将启用所有隐式禁用的警告

配置选项

提供了一些有偏见的标志来定制发出的 linting 错误。

--suppress-none-returning: bool

对于满足以下任何一个条件的函数，抑制 ANN200 级别的错误

• 不包含任何 return 语句，或
• 显式 return 语句（显式或隐式）都返回 None。

默认值: False

--suppress-dummy-args: bool

抑制对于定义为 _ 的哑参数的 ANN000 级别错误。

默认值: False

--allow-untyped-defs: bool

抑制动态类型函数的所有错误。如果一个函数不包含任何类型提示，则认为它是动态类型的。

默认值: False

--allow-untyped-nested: bool

抑制动态类型嵌套函数的所有错误。如果一个函数不包含任何类型提示，则认为它是动态类型的。

默认值: False

--mypy-init-return: bool

如果至少有一个参数被注解，则允许省略 __init__ 的返回类型提示。有关详细信息，请参阅 mypy 的文档。

默认值: False

--dispatch-decorators: list[str]

逗号分隔的装饰器列表，flake8-annotations 应将其视为调度装饰器。对于至少由这些函数之一装饰的函数，将抑制 linting 错误。

装饰器根据其属性名称进行匹配。例如，"singledispatch" 将匹配以下任何一个

• import functools; @functools.singledispatch
• import functools as <alias>; @<alias>.singledispatch
• from functools import singledispatch; @singledispatch

注意： 不支持深层导入，例如 a.b.singledispatch。

有关更多信息，请参阅 泛型函数。

默认值: "singledispatch, singledispatchmethod"

--overload-decorators: list[str]

逗号分隔的装饰器列表，flake8-annotations 应将其视为 typing.overload 装饰器。

装饰器根据其属性名称进行匹配。例如，"overload" 将匹配以下任何一个

• import typing; @typing.overload
• import typing as <alias>; @<alias>.overload
• 从 typing 导入 overload; @overload

注意： 不支持更深层次的导入，例如 a.b.overload。

参见： The typing.overload 装饰器 获取更多信息。

默认值： "overload"

--allow-star-arg-any

抑制 ANN401 对于动态类型化的 *args 和 **kwargs。

默认值: False

--respect-type-ignore

抑制带有 # type: ignore 注释的函数的 linting 错误。同时提供对模块级别空白忽略的支持（参见： mypy: Ignoring a whole file）。

注意： 不考虑类型忽略标签，例如 # type: ignore[arg-type] 被视为与 # type: ignore 相同。 注意： 仅当模块级别的抑制作为模块第一行的唯一内容时，才考虑模块级别的抑制。

默认值: False

泛型函数

根据 Python 词汇表，一个 泛型函数 定义为

由多个函数组成，这些函数实现了相同操作的不同类型。在调用期间应使用哪个实现由调度算法确定。

在标准库中，我们有一些实现这些泛型函数的装饰器的示例： functools.singledispatch 和 functools.singledispatchmethod。按照这些装饰器的目的，忽略至少装饰了一个这些装饰器的函数缺失的注解错误。

例如，此代码

import functools

@functools.singledispatch
def foo(a):
    print(a)

@foo.register
def _(a: list) -> None:
    for idx, thing in enumerate(a):
        print(idx, thing)

对于 foo 不会引发任何 linting 错误。

可以使用 --dispatch-decorators 配置选项指定视为定义泛型函数的装饰器。

typing.overload 装饰器

根据 typing 文档

@overload 装饰器允许描述支持多种不同参数类型组合的函数和方法。一系列 @overload-装饰的定义必须紧跟一个非 @overload-装饰的定义（对于相同的函数/方法）。

按照此装饰器的目的，如果它们符合此标准，则忽略非 @overload-装饰的函数缺失的注解错误。

例如，此代码

import typing


@typing.overload
def foo(a: int) -> int:
    ...

def foo(a):
    ...

不会为非装饰的 foo 定义缺失的参数和返回注解引发 linting 错误。

可以使用 --overload-decorators 配置选项指定视为 typing.overload 的装饰器。

动态类型注意事项

仅支持以下模式

• from typing import any; foo: Any
• import typing; foo: typing.Any
• import typing as <alias>; foo: <alias>.Any

嵌套动态类型（例如 typing.Tuple[typing.Any]）和重新定义（例如 from typing import Any as Foo）将不会被识别。

贡献

Python 版本支持

我们尽力支持 Python 版本，直到它们达到 EOL，之后支持将通过下一个次要或主要版本的此包正式取消， whichever arrives first. Python 版本的状态可以在 这里 查找。

开发环境

此项目使用 Poetry 来管理依赖项。将您的分支克隆到本地计算机后，您可以使用以下命令安装项目和其依赖项以创建开发环境：

$ poetry install

注意：开发环境中需要安装可编辑的 flake8-annotations 安装，以便将插件注册到 Flake8。默认情况下，当调用 poetry install 时，Poetry 包括项目的可编辑安装。

还提供了一个pre-commit配置，以便创建预提交钩子，这样就不会提交代码风格错误

$ pre-commit install

测试和覆盖率

提供了一个pytest测试套件，并使用pytest-cov进行覆盖率报告。提供了一个tox配置，以测试所有支持的Python版本。对于找不到的Python版本将跳过测试。

$ tox

报告中提供了缺失覆盖率的详细信息，包括测试套件中的信息，以便用户可以生成额外的测试以实现完全覆盖率。