选项和配置处理¶

期权管理¶

命令行选项通常也设置在配置文件中 Flake8 . 虽然并非所有选项都要从配置文件中解析，但许多默认选项也要从配置文件以及大多数插件选项中解析。

在 Flake8 2，插件收到 optparse.OptionParser 实例并调用 optparse.OptionParser.add_option() 注册选项。如果插件作者还想从配置文件中解析该选项，他们还必须执行以下操作：

parser.config_options.append('my_config_option')
parser.config_options.extend(['config_opt1', 'config_opt2'])

这是以前没有记录的，导致了很多关于为什么注册的选项不能从配置文件中自动解析的混淆。

自从 Flake8 3是从头重写的，我们决定采用不同的方法来解析配置文件。不需要知道pep8所寻找的未记录属性， Flake8 现在接受参数3 add_option ，具体来说 parse_from_config 它是一个布尔值。

Flake8 通过在 argparse . 第一个抽象是 flake8.options.manager.Option 班级。第二个是 flake8.options.manager.OptionManager . 实际上，我们添加了三个新参数：

parse_from_config
comma_separated_list
normalize_paths

最后两个不是专门用于配置文件处理的，但是它们确实显著地改进了这一点。我们发现有些选项，当在配置文件中指定时，通常需要多行，而这些选项几乎总是以逗号分隔。例如，让我们考虑一个项目的用户忽略的错误代码列表：

[flake8]
ignore =
    # Reasoning
    E111,
    # Reasoning
    E711,
    # Reasoning
    E712,
    # Reasoning
    E121,
    # Reasoning
    E122,
    # Reasoning
    E123,
    # Reasoning
    E131,
    # Reasoning
    E251

允许用户以这种方式指定值是有意义的，但是，标准库的 configparser.RawConfigParser 类返回的字符串

"\nE111,  \nE711,  \nE712,  \nE121,  \nE122,  \nE123,  \nE131,  \nE251  "

这意味着 str.split() 具有 ',' 在这里是不够的。告诉 Flake8 一个逗号分隔的列表（例如。， comma_separated_list=True )我会帮你处理的。 Flake8 将返回：

["E111", "E711", "E712", "E121", "E122", "E123", "E131", "E251"]

接下来，让我们看看用户可能希望如何指定他们的 exclude 列表。目前OpenStack的Nova项目在他们的 tox.ini ：

exclude = .venv,.git,.tox,dist,doc,*openstack/common/*,*lib/python*,*egg,build,tools/xenserver*,releasenotes

我们认为大家都同意这样读起来更容易：

exclude =
    .venv,
    .git,
    .tox,
    dist,
    doc,
    *openstack/common/*,
    *lib/python*,
    *egg,
    build,
    tools/xenserver*,
    releasenotes

在本例中，由于这些实际上是路径，所以我们将同时指定这两个路径 comma_separated_list=True 和 normalize_paths=True 因为我们希望提供给我们的路径具有一定的一致性（不管是否都是绝对路径）。

现在让我们来看看这将如何实际使用。大多数插件开发人员都会收到 OptionManager 因此，为了简化转换，我们保留了与 optparse.OptionParser 对象。唯一的区别是 add_option() 接受我们上面强调的三个额外参数。

配置文件管理¶

在 Flake8 配置文件的发现和管理由pep8处理。在pep8的1.6发行版系列中，它彻底打破了发现和合并的工作方式（作为对其进行改进的结果）。以避免依赖关系中断 Flake8 在未来，我们再次创造了自己的发现和管理。作为自己管理的一部分，我们决定将管理/发现更改为3.0.0。我们做了以下工作：

用户文件（存储在用户主目录中或存储在其主目录内的XDG目录中的文件）是第一个读取的文件。例如，如果用户有 ~/.flake8 文件，我们先读一下。
接下来读取项目文件（存储在当前目录中的文件）并将其合并到用户文件的顶部。换句话说，项目文件中的配置优先于用户文件中的配置。
新版本3.0 用户可以指定 --append-config <path-to-file> 重复以包含应被读取并优先于用户和项目文件的额外配置文件。
新版本3.0 用户可以指定 --config <path-to-file> 因此，此文件是唯一使用的配置文件。这是从 Flake8 其中pep8只需将此配置文件合并到由用户和项目文件生成的配置中（优先）。
新版本3.0 用户可以指定 --isolated 通过发现的配置文件禁用配置。

为了方便配置文件管理，我们采用了与pep8不同的方法来发现和管理文件。在pep8 1.5、1.6和1.7中，配置发现和管理集中在 66 lines of very terse python 这让人很困惑，也不是很明确。这个函数的简洁性( Flake8 作者认为）导致了pep8的1.6系列的混乱和问题。像这样的， Flake8 将发现、管理和合并分离到一个模块中，使关于这些部分的推理更简单、更明确（以及更易于测试）。

配置文件发现由 ConfigFileFinder 对象。此对象需要知道有关程序名、传递给它的任何额外参数以及应附加到已发现文件列表中的任何配置文件的信息。它提供了查找文件的方法和解析这些fle的类似方法。例如，它提供 local_config_files() 查找已知的本地配置文件（并附加额外的配置文件），它还提供 local_configs() 解析这些配置文件。

注解

local_config_files 同时过滤掉不存在的文件。

配置文件合并和管理由 MergedConfigParser . 这需要 OptionManager 程序正在使用的、附加的配置文件的列表和额外参数的列表。此对象当前是 ConfigFileFinder 对象。它适当地初始化对象并在每个

parse_cli_config()
parse_local_config()
parse_user_config()

最后， merge_user_and_local_config() 获取由解析的用户和本地配置文件 parse_local_config() 和 parse_user_config() . 的主要用法 MergedConfigParser 是在 aggregate_options() .

聚合配置文件和命令行参数¶

aggregate_options() 接受的实例 OptionManager 并执行分析用户传递的命令行参数的工作，这些参数是创建 MergedConfigParser .

在分析配置文件之后，我们确定默认的忽略列表。我们使用OptionManager的默认值，并用解析的配置文件更新这些默认值。最后，我们最后一次解析用户提供的选项，使用选项默认值和配置文件值作为默认值。解析器为我们合并命令行指定的参数，这样我们就有了最终的、确定的、聚合的选项。

API文档¶

flake8.options.aggregator.aggregate_options(manager, config_finder, argv)[源代码]¶

聚合和合并CLI和配置文件选项。

参数

manager (flake8.options.manager.OptionManager) -- 我们目前正在使用的OptionManager的实例。
config_finder (flake8.options.config.ConfigFileFinder) -- 要使用的配置文件查找器。
argv (list) -- 在要传递给的初步选项分析期间未知的剩余命令行参数的列表 manager.parse_args .

返回

返回的已解析选项和额外参数的元组 manager.parse_args .

返回类型

tuple(argparse.Namespace, list)

class flake8.options.manager.Option(short_option_name=<_ARG.NO: 1>, long_option_name=<_ARG.NO: 1>, action=<_ARG.NO: 1>, default=<_ARG.NO: 1>, type=<_ARG.NO: 1>, dest=<_ARG.NO: 1>, nargs=<_ARG.NO: 1>, const=<_ARG.NO: 1>, choices=<_ARG.NO: 1>, help=<_ARG.NO: 1>, metavar=<_ARG.NO: 1>, callback=<_ARG.NO: 1>, callback_args=<_ARG.NO: 1>, callback_kwargs=<_ARG.NO: 1>, required=<_ARG.NO: 1>, parse_from_config=False, comma_separated_list=False, normalize_paths=False)[源代码]¶

我们的包装器包含一个argparse参数解析器来添加特性。

__init__(short_option_name=<_ARG.NO: 1>, long_option_name=<_ARG.NO: 1>, action=<_ARG.NO: 1>, default=<_ARG.NO: 1>, type=<_ARG.NO: 1>, dest=<_ARG.NO: 1>, nargs=<_ARG.NO: 1>, const=<_ARG.NO: 1>, choices=<_ARG.NO: 1>, help=<_ARG.NO: 1>, metavar=<_ARG.NO: 1>, callback=<_ARG.NO: 1>, callback_args=<_ARG.NO: 1>, callback_kwargs=<_ARG.NO: 1>, required=<_ARG.NO: 1>, parse_from_config=False, comma_separated_list=False, normalize_paths=False)[源代码]¶

初始化选项实例。

以下都直接传递给argparse。

参数

short_option_name (str) -- 选项的简称（例如。， -x ). 这将是传递给 ArgumentParser.add_argument
long_option_name (str) -- 选项的长名称（例如。， --xtra-long-option ). 这将是传递给 ArgumentParser.add_argument
default -- 选项的默认值。
dest -- 将解析的选项值存储为的属性名称。
nargs -- 要为此选项分析的参数数。
const -- 要存储在公共目标上的常量值。通常与 action="store_const" .
choices (iterable) -- 选项的可能值。
help (str) -- 使用信息中显示的帮助文本。
metavar (str) -- 要使用的名称，而不是帮助文本的长选项名称。
required (bool) -- 是否需要此选项。

以下选项可以直接传递给 argparse 但可能需要按摩。

参数

type -- 一个可调用的规范化类型（如 argparse ). 不推荐：您还可以传递类型字符串，例如 'int' 由谁来处理 optparse .
action (str) -- 允许的任何行动 argparse . 不推荐：这也理解 action='callback' 来自的操作 optparse .
callback (callable) -- 如果操作是 "callback" . 不推荐：请使用 action= 相反。
callback_args (iterable) -- 回调可调用的其他位置参数。不推荐：请使用 action= 相反（可能是 functools.partial ）
callback_kwargs (dictionary) -- 回调callable的关键字参数。不推荐：请使用 action= 相反（可能是 functools.partial ）

以下参数仅用于Flake8的选项处理。

参数

parse_from_config (bool) -- 是否应从配置文件中解析此选项。
comma_separated_list (bool) -- 从配置文件进行解析时，该选项是否为逗号分隔的列表。
normalize_paths (bool) -- 选项是否需要路径或路径列表，并应尝试将路径规范化为绝对路径。

normalize(value, *normalize_args)[源代码]¶: 基于选项配置规范化值。

to_argparse()[源代码]¶: 将Flake8选项转换为argparse add_argument 争论。

class flake8.options.manager.OptionManager(prog, version, usage='%(prog)s [options] file file ...', parents=None)[源代码]¶

在添加后期处理时管理选项和OptionParser。

__init__(prog, version, usage='%(prog)s [options] file file ...', parents=None)[源代码]¶

初始化OptionManager实例。

参数

prog (str) -- 实际程序的名称（例如，flake8）。
version (str) -- 程序的版本字符串。
usage (str) -- OptionParser使用的基本用法字符串。
parents (argparse.ArgumentParser) -- ArgumentParser对象的列表，这些对象的参数也应包括在内。

__weakref__¶: 对象的弱引用列表（如果已定义）

add_option(*args, **kwargs)[源代码]¶

创建并注册新选项。

有关详细信息，请参见参数 Option 此方法的可接受参数。

注解

short_option_name 和 long_option_name 可以像通常使用argparse一样按位置指定。

extend_default_ignore(error_codes)[源代码]¶

使用提供的错误代码扩展默认忽略列表。

参数: error_codes (list) -- 字符串列表，这些字符串是用于扩展默认忽略列表的错误/警告代码。

extend_default_select(error_codes)[源代码]¶

使用提供的错误代码扩展默认选择列表。

参数: error_codes (list) -- 用于扩展默认选择列表的错误/警告代码字符串列表。

generate_epilog()[源代码]¶: 用每个插件的版本和名称创建一个epilog。

generate_versions(format_str='%(name)s: %(version)s', join_on=', ')[源代码]¶: 生成插件版本的逗号分隔列表。

group(name)[源代码]¶: 在此上下文期间将选项附加到argparse组。

parse_args(args=None, values=None)[源代码]¶: 代理调用OptionParser的parseu args方法。

parse_known_args(args=None)[源代码]¶

只分析参数值中的已知参数。

当我们还在optparse上时，复制一些argparse行为。

register_plugin(name, version, local=False)[源代码]¶

注册依赖于OptionManager的插件。

参数

name (str) -- 检查器本身的名称。这将是 name 从入口点加载的类或函数的属性。
version (str) -- 我们使用的检查器版本。
local (bool) -- 插件是否是项目/存储库的本地插件。

remove_from_default_ignore(error_codes)[源代码]¶

从默认忽略列表中删除指定的错误代码。

参数: error_codes (list) -- 要尝试从扩展的默认忽略列表中删除的错误/警告代码的字符串列表。

update_version_string()[源代码]¶: 更新flake8版本字符串。

class flake8.options.config.ConfigFileFinder(program_name, extra_config_files=None, config_file=None, ignore_config_files=False)[源代码]¶

封装查找和读取配置文件的逻辑。

__init__(program_name, extra_config_files=None, config_file=None, ignore_config_files=False)[源代码]¶

初始化对象以查找配置文件。

参数

program_name (str) -- 当前程序的名称（例如，flake8）。
extra_config_files (list) -- 用户指定要读取的额外配置文件。
config_file (str) -- 配置文件重写为仅从中读取配置。
ignore_config_files (bool) -- 确定是否忽略配置文件。

__weakref__¶: 对象的弱引用列表（如果已定义）

cli_config(files)[源代码]¶: 读取并解析命令行上指定的配置文件。

generate_possible_local_files()[源代码]¶: 查找并生成所有本地配置文件。

local_config_files()[源代码]¶

查找所有实际存在的本地配置文件。

筛选结果来自 generate_possible_local_files() 基于文件名是否存在。

返回: 存在的文件列表，这些文件是附加到该列表（也存在）的本地项目配置文件。
返回类型: [str]

local_configs()[源代码]¶: 将所有本地配置文件解析为一个配置对象。

local_configs_with_files()[源代码]¶

将所有本地配置文件解析为一个配置对象。

Return（config，found_config_files）元组。

user_config()[源代码]¶: 将用户配置文件解析为配置对象。

class flake8.options.config.MergedConfigParser(option_manager, config_finder)[源代码]¶

封装合并不同类型的配置文件。

这将解析出在配置文件中指定的注册选项，处理额外的配置文件，并返回包含解析值的字典。

GETBOOL_ACTIONS = {'store_false', 'store_true'}¶: 应该使用 getbool() 方法。

__init__(option_manager, config_finder)[源代码]¶

初始化MergedConfigParser实例。

参数

option_manager (flake8.options.manager.OptionManager) -- 已初始化OptionManager。
config_finder (flake8.options.config.ConfigFileFinder) -- 已初始化ConfigFileFinder。

__weakref__¶: 对象的弱引用列表（如果已定义）

config_finder¶: 我们的实例 ConfigFileFinder

config_options¶: 将配置选项名称映射到 Option 实例

is_configured_by(config)[源代码]¶: 检查指定的配置解析器是否有适当的节。

merge_user_and_local_config()[源代码]¶

合并已解析的用户和本地配置文件。

返回: 已解析和合并配置选项的字典。
返回类型: dict

option_manager¶: 我们的flake8实例。options.manager.OptionManager

parse()[源代码]¶

解析并返回本地和用户配置文件。

首先，它复制解析的本地配置，然后迭代用户配置中的选项，如果这些选项不是由本地配置文件设置的，则进行设置。

返回: 解析的配置选项字典
返回类型: dict

parse_cli_config(config_path)[源代码]¶: 解析并返回--config指定的文件。

parse_local_config()[源代码]¶: 解析并返回本地配置文件。

parse_user_config()[源代码]¶: 解析并返回用户配置文件。

program_name¶: cli解析器的prog值