flake8-plugin-utils

该软件包为flake8插件编写提供基础类和实用工具。

安装

pip install flake8-plugin-utils

示例

编写简单插件

from flake8_plugin_utils import Error, Visitor, Plugin

class MyError(Error):
    code = 'X100'
    message = 'my error'

class MyVisitor(Visitor):
    def visit_ClassDef(self, node):
        self.error_from_node(MyError, node)

class MyPlugin(Plugin):
    name = 'MyPlugin'
    version = '0.1.0'
    visitors = [MyVisitor]

并用pytest测试它

from flake8_plugin_utils import assert_error, assert_not_error

def test_code_with_error():
    assert_error(MyVisitor, 'class Y: pass', MyError)

def test_code_without_error():
    assert_not_error(MyVisitor, 'x = 1')

配置

要将配置添加到插件中，请执行以下操作

1. 按照flake8文档，在您的插件类中实现classmethod add_options。
2. 覆盖插件类中的classmethod parse_options_to_config，以返回包含您所需选项的任何对象。
3. 如果您的访问者需要自定义 __init__，确保它接受名为 config 的关键字参数，并将其传递给 super().__init__
4. 在访问者代码中使用 self.config。

示例

from flake8_plugin_utils import Error, Visitor, Plugin, assert_error

class MyError(Error):
    code = 'X100'
    message = 'my error with {thing}'

class MyConfig:
    def __init__(self, config_option):
        self.config_option = config_option

class MyVisitorWithConfig(Visitor):
    def visit_ClassDef(self, node):
        self.error_from_node(
            MyError, node, thing=f'{node.name} {self.config.config_option}'
        )

class MyPluginWithConfig(Plugin):
    name = 'MyPluginWithConfig'
    version = '0.0.1'
    visitors = [MyVisitorWithConfig]

    @classmethod
    def add_options(cls, options_manager):
        options_manager.add_option('--config_option', parse_from_config=True, ...)

    @classmethod
    def parse_options_to_config(cls, option_manager, options, args):
        return MyConfig(config_option=options.config_option)


def test_code_with_error():
    assert_error(
        MyVisitorWithConfig,
        'class Y: pass',
        MyError,
        config=MyConfig(config_option='123'),
        thing='Y 123',
    )

格式化

您的 Error 可以在其 message 中接受格式化参数

from flake8_plugin_utils import Error, Visitor, assert_error

class MyFormattedError(Error):
    code = 'X101'
    message = 'my error with {thing}'

class MyFormattedVisitor(Visitor):
    def visit_ClassDef(self, node):
        self.error_from_node(MyFormattedError, node, thing=node.name)

def test_code_with_error():
    assert_error(
        MyFormattedVisitor,
        'class Y: pass',
        MyFormattedError,
        thing='Y',
    )

与typing/mypy一起使用

Plugin 和 Visitor 类与config类作为类型参数是通用的。如果您的插件没有配置，则从 Plugin[None] 继承它，并从 Visitor[None] 继承访问者。否则，使用配置类作为类型参数（例如，在上面的示例中，使用 Plugin[MyConfig] 和 Visitor[MyConfig]）。

实用函数

• assert_error，assert_not_error 测试访问者的实用工具（请参阅上面的示例）。

• is_true、is_false、is_none 简便函数，用于检查AST节点是否代表 True / False / None 值。

• check_equivalent_nodes 检查两个给定的AST节点是否等效。以下情况下节点被认为是等效的

  • 字典 -- 如果它们包含相同的键值对，可能顺序不同，考虑重复项和 **expansions
  • 集合 -- 如果它们包含相同的元素，可能顺序不同，考虑重复项
  • 其他任何内容 -- 如果它们代表相同的AST，不考虑格式（在集合内任何字典都根据上述规则检查）

针对开发者

显示帮助

make help

创建venv并安装依赖项

make init

安装git precommit钩子

make precommit

运行linters、autoformat、测试等。

make pretty lint test

提升新版本

make bump_major
make bump_minor
make bump_patch

变更日志

未发布

• ...

1.3.3 - 2022-01-14

• 添加 py.typed 文件 (#78)

1.3.2 - 2021-05-05

• 删除noqa检测 (#56)
• 文档：为Makefile添加帮助

1.3.1 - 2020-08-06

• 修复加载文件时的编码处理 (#37)

1.3.0 - 2020-03-26

• 添加 check_equivalent_nodes 工具函数

1.2.0 - 2020-03-06

• 将 config 参数添加到 assert_error 和 assert_not_error

1.1.1 - 2020-03-02

• 在读取字符串以进行noqa验证时忽略编码错误

1.1.0 - 2020-03-01

• 添加插件解析和使用配置的能力 注意：此更改会破坏使用typing/mypy的类型检查。请将代码修改为从 Plugin[None] 和 Visitor[None] 继承以修复。

1.0.0 - 2019-05-23

• 为Error添加消息格式化

0.2.1 - 2019-04-01

• 在_error_from_src中在src dedent之前不要去除缩进
• 添加 is_none、is_true、is_false 工具函数

0.2.0 - 2019.02.21

• 添加断言方法

0.1.0 - 2019.02.09

• 初始版本