Pyrefly 忽略指令控制指南深入解析permissive-ignores与enabled-ignores【免费下载链接】pyreflyA fast type checker and language server for Python项目地址: https://gitcode.com/GitHub_Trending/py/pyrefly在大型 Python 代码库中引入类型检查器时# type: ignore这类忽略注释是让存量代码快速获得干净信号的关键工具。Pyrefly 不仅支持标准的# type: ignore还支持# pyrefly: ignore、# pyright: ignore、# mypy: ignore-errors、# pyre-ignore等多种工具的忽略指令。默认情况下 Pyrefly 只尊重其中一部分如何精确控制尊重哪些工具的忽略指令正是permissive-ignores与enabled-ignores两个配置项要解决的问题。本文以 test/ignores.md 中的 7 组可复现命令为基础结合仓库源码ignore.rs、config.rs、args.rs完整讲解这两个配置项的行为、优先级、命令行覆盖规则以及它们背后的实现原理。一、背景Pyrefly 支持哪些工具的忽略指令在进入配置之前先明确 Pyrefly 能识别哪些工具的忽略注释。定义位于 crates/pyrefly_python/src/ignore.rs 的Tool枚举共 7 种工具名启用的忽略指令说明type# type: ignorePEP 484 标准注释另支持文件级# type: ignorepyrefly# pyrefly: ignore、# pyrefly: ignore-errorsPyrefly 自身可携带具体错误码pyright# pyright: ignorePyright 风格注释mypy# mypy: ignore-errorsMypy 文件级指令ty# ty: ignoreTy 类型检查器pyre# pyre: ignore、# pyre-ignore、# pyre-fixme、# pyre-ignore-all-errorsPyre 兼容形式zuban# zuban: ignoreZuban 类型检查器两个关键集合在源码中直接可见ignore.rsTool::default_enabled()返回{type, pyrefly}—— 这就是默认只尊重标准注释与自家注释Tool::all()返回全部 7 种工具 —— 这正是permissive-ignores true所等价的行为。注意schemas/pyrefly.json中enabled-ignores的枚举值为[type, pyrefly, mypy, pyright, pyre, ty]不含zuban与 Rust 枚举存在细微差异配置时以 schema 为准。二、默认行为只启用# type: ignore与# pyrefly: ignore从 test/ignores.md 的第一组命令可以看到默认行为$ mkdir $TMPDIR/enabled_ignores \ touch $TMPDIR/enabled_ignores/pyrefly.toml \ echo -e 1 1 # type: ignore\n1 1 # pyrefly: ignore\n1 1 # pyright: ignore $TMPDIR/enabled_ignores/foo.py \ $PYREFLY check $TMPDIR/enabled_ignores/foo.py --output-formatmin-text ERROR */foo.py:3* (glob) [1]foo.py三行代码分别带有# type: ignore、# pyrefly: ignore、# pyright: ignore注释每行都会产生1 1的类型错误。检查结果中只有第 3 行pyright被报告第 1、2 行被静默。这印证了Tool::default_enabled()的实现默认只信任type与pyrefly两个工具的忽略指令。从实现上看这一过滤发生在 ignore.rs 的suppression_effect方法中所有解析出的Suppression会先经过enabled_ignores.contains(supp.tool)过滤只有工具在启用集合内其SuppressionEffect才会被考虑最终取最强的效果max()排序为None DowngradeToWarning Suppress作用于该行诊断。三、enabled-ignores精确控制启用的工具集合如果希望尊重某个具体工具的忽略注释比如只启用# pyright: ignore在pyrefly.toml中设置enabled-ignores [pyright]验证效果来自 test/ignores.md 第二组命令$ echo enabled-ignores [pyright] $TMPDIR/enabled_ignores/pyrefly.toml \ $PYREFLY check $TMPDIR/enabled_ignores/foo.py --output-formatmin-text ERROR */foo.py:1* (glob) ERROR */foo.py:2* (glob) [1]结果反转第 3 行被# pyright: ignore抑制而第 1、2 行的# type: ignore和# pyrefly: ignore不再生效错误被如实报告。参数细节依据 args.rs 与 configuration.mdx类型工具名列表可用值type、pyrefly、mypy、pyright、pyre、ty默认值[type, pyrefly]命令行等价物--enabled-ignores可重复传参也支持逗号分隔列表value_delimiter ,例如--enabled-ignorespyright,mypy行为enabled-ignores会完全替换默认集合而不是在默认集合上追加。四、permissive-ignores一键尊重所有工具的忽略指令如果代码库同时混用了 Pyright、Mypy、Pyre 等工具的忽略注释逐一列举工具名过于繁琐此时permissive-ignores提供了快捷方式permissive-ignores true验证效果第三组命令$ echo permissive-ignores true $TMPDIR/enabled_ignores/pyrefly.toml \ $PYREFLY check $TMPDIR/enabled_ignores/foo.py --output-formatmin-text [0]三行全部被抑制退出码为 0。源码层面config.rs 将permissive-ignores true展开为Tool::all()即所有 7 种工具全部加入启用集合。参数细节依据 args.rs 与 configuration.mdx类型bool默认值false命令行等价物--permissive-ignores且支持--permissive-ignorestrue/false显式赋值num_args 0..1require_equals true等价关系启用它等价于把全部工具名传给enabled-ignores反过来enabled-ignores列出全部工具也等价于启用permissive-ignoresconfiguration.mdx。五、同一配置文件中两者互斥enabled-ignores优先如果在同一个pyrefly.toml中同时设置两个选项会触发告警且permissive-ignores被忽略第四组命令$ echo -e enabled-ignores [pyright]\npermissive-ignores true $TMPDIR/enabled_ignores/pyrefly.toml \ $PYREFLY check $TMPDIR/enabled_ignores/foo.py --output-formatmin-text --summarynone WARN * permissive-ignores will be ignored. (glob) ERROR */foo.py:1* (glob) ERROR */foo.py:2* (glob) [1]输出中的 WARN 正是 config.rs 的合并逻辑产生的let enabled_ignores match ( tools_from_permissive_ignores, self.root.enabled_ignores.clone(), ) { (None, None) Tool::default_enabled(), (None, Some(tools)) | (Some(tools), None) tools, (Some(_), Some(tools)) { configure_errors.push(anyhow!(Cannot use both permissive-ignores and enabled-ignores: permissive-ignores will be ignored.)); tools } };即两者都设置时保留enabled-ignores的值本示例中只有pyrightpermissive-ignores静默失效并通过配置错误以 WARN 形式呈现告知用户。六、命令行同样互斥--permissive-ignores与--enabled-ignores不能同时出现与配置文件内的互斥不同命令行参数之间是硬性报错第五组命令$ rm -f $TMPDIR/enabled_ignores/pyrefly.toml \ $PYREFLY check $TMPDIR/enabled_ignores/foo.py --enabled-ignorespyright --permissive-ignores Cannot use both --permissive-ignores and --enabled-ignores [1]这里的错误在参数解析阶段就发生args.rsif self.permissive_ignores.is_some() self.enabled_ignores.is_some() { return Err(anyhow!(Cannot use both --permissive-ignores and --enabled-ignores)); }注意与配置文件内行为的两处不同配置内是告警 忽略 permissive进程仍继续检查命令行是直接拒绝执行进程以非零退出码终止不会运行任何检查。七、命令行覆盖配置文件优先级规则当命令行与配置文件各设一项时命令行总是胜出。这是 args.rs 中三个分支的逻辑行为如下场景 1配置文件设enabled-ignores命令行传--permissive-ignores→ 结果 permissive$ echo enabled-ignores [pyright] $TMPDIR/enabled_ignores/pyrefly.toml \ $PYREFLY check $TMPDIR/enabled_ignores/foo.py --permissive-ignores --output-formatmin-text --summarynone [0]三行全部被抑制。源码中这一分支的特殊逻辑是当配置文件只设置了enabled-ignores未设permissive-ignores而命令行传入--permissive-ignores时直接用命令行值整体改写enabled-ignores集合args.rs。场景 2配置文件设permissive-ignores true命令行传--enabled-ignorespyright→ 结果 enabled-ignores$ echo permissive-ignores true $TMPDIR/enabled_ignores/pyrefly.toml \ $PYREFLY check $TMPDIR/enabled_ignores/foo.py --enabled-ignorespyright --output-formatmin-text --summarynone ERROR */foo.py:1* (glob) ERROR */foo.py:2* (glob) [1]第 1、2 行重新报错。对应源码命令行设置enabled-ignores时会清除配置里的permissive-ignores只保留命令行指定的工具args.rs。场景 3配置文件设enabled-ignores命令行显式传--permissive-ignoresfalse→ 结果 仅默认集合命令行覆盖配置文件$ echo enabled-ignores [pyright] $TMPDIR/enabled_ignores/pyrefly.toml \ $PYREFLY check $TMPDIR/enabled_ignores/foo.py \ --permissive-ignoresfalse --output-formatmin-text --summarynone ERROR */foo.py:3* (glob) [1]此时只有第 3 行报错——配置里的[pyright]被--permissive-ignoresfalse覆盖实际生效的是Tool::default_enabled(){type, pyrefly}所以只有# pyright: ignore失效。这展示了--permissive-ignoresfalse的另一种用途用显式布尔值覆盖任何已有的工具集合配置。完整的优先级总结如下配置来源配置来源结果配置文件enabled-ignores配置文件permissive-ignoresenabled-ignores生效permissive 告警并忽略命令行--enabled-ignores命令行--permissive-ignores直接报错拒绝执行配置文件enabled-ignores命令行--permissive-ignores命令行 permissive 覆盖配置文件permissive-ignores命令行--enabled-ignores命令行 enabled-ignores 覆盖配置文件enabled-ignores命令行--permissive-ignoresfalse回退到默认{type, pyrefly}八、从源码看两个配置的解析链路理解完整数据流有助于排查问题参数定义args.rs 定义 CLI 参数--permissive-ignores为Optionbool可带true/false--enabled-ignores为OptionVecTool逗号分隔配置结构base.rs 中ConfigBase持有permissive_ignores: Optionbool与enabled_ignores: OptionSmallSetTool命令行改写解析 CLI 时按第七节的三条分支规则改写配置树的这两个字段args.rs合并归一config.rs 将两个字段合并为唯一的enabled_ignores集合默认{type, pyrefly}同时报告配置内冲突生效判定ignore.rs 在报告诊断时通过enabled_ignores.contains(supp.tool)决定该行抑制是否有效。配置文件的 schema 定义见 schemas/pyrefly.jsonpermissive-ignores为boolean默认falseenabled-ignores为字符串数组默认[type, pyrefly]可用于编辑器补全与配置校验。九、最佳实践建议刚迁移到 Pyrefly、代码里只有# type: ignore保持默认即可无需任何配置与 Pyright 长期共存的项目优先用精确的enabled-ignores [type, pyrefly, pyright]避免permissive-ignores意外尊重未来新工具如zuban的注释从 Mypy 迁移、代码里有大量# mypy: ignore-errors可临时开启permissive-ignores true获得干净信号迁移完成后收紧为明确的工具列表CI 脚本优先使用命令行--enabled-ignores它覆盖配置文件便于按 job 差异化例如 CI 严格模式只保留type、pyrefly务必记住两条互斥规则同一配置文件内两者并存时 permissive 被忽略WARN同一命令行上两者并存时直接报错退出。最后提醒上述所有验证命令均可参照 test/ignores.md 原样运行替换$PYREFLY与$TMPDIR为你的环境变量--output-formatmin-text用于最小化输出--summarynone关闭总结以突出关键行这些命令本身就是仓库的回归测试用例确保行为与本文描述完全一致。【免费下载链接】pyreflyA fast type checker and language server for Python项目地址: https://gitcode.com/GitHub_Trending/py/pyrefly创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Pyrefly 忽略指令控制指南：深入解析 `permissive-ignores` 与 `enabled-ignores`
Pyrefly 忽略指令控制指南深入解析permissive-ignores与enabled-ignores【免费下载链接】pyreflyA fast type checker and language server for Python项目地址: https://gitcode.com/GitHub_Trending/py/pyrefly在大型 Python 代码库中引入类型检查器时# type: ignore这类忽略注释是让存量代码快速获得干净信号的关键工具。Pyrefly 不仅支持标准的# type: ignore还支持# pyrefly: ignore、# pyright: ignore、# mypy: ignore-errors、# pyre-ignore等多种工具的忽略指令。默认情况下 Pyrefly 只尊重其中一部分如何精确控制尊重哪些工具的忽略指令正是permissive-ignores与enabled-ignores两个配置项要解决的问题。本文以 test/ignores.md 中的 7 组可复现命令为基础结合仓库源码ignore.rs、config.rs、args.rs完整讲解这两个配置项的行为、优先级、命令行覆盖规则以及它们背后的实现原理。一、背景Pyrefly 支持哪些工具的忽略指令在进入配置之前先明确 Pyrefly 能识别哪些工具的忽略注释。定义位于 crates/pyrefly_python/src/ignore.rs 的Tool枚举共 7 种工具名启用的忽略指令说明type# type: ignorePEP 484 标准注释另支持文件级# type: ignorepyrefly# pyrefly: ignore、# pyrefly: ignore-errorsPyrefly 自身可携带具体错误码pyright# pyright: ignorePyright 风格注释mypy# mypy: ignore-errorsMypy 文件级指令ty# ty: ignoreTy 类型检查器pyre# pyre: ignore、# pyre-ignore、# pyre-fixme、# pyre-ignore-all-errorsPyre 兼容形式zuban# zuban: ignoreZuban 类型检查器两个关键集合在源码中直接可见ignore.rsTool::default_enabled()返回{type, pyrefly}—— 这就是默认只尊重标准注释与自家注释Tool::all()返回全部 7 种工具 —— 这正是permissive-ignores true所等价的行为。注意schemas/pyrefly.json中enabled-ignores的枚举值为[type, pyrefly, mypy, pyright, pyre, ty]不含zuban与 Rust 枚举存在细微差异配置时以 schema 为准。二、默认行为只启用# type: ignore与# pyrefly: ignore从 test/ignores.md 的第一组命令可以看到默认行为$ mkdir $TMPDIR/enabled_ignores \ touch $TMPDIR/enabled_ignores/pyrefly.toml \ echo -e 1 1 # type: ignore\n1 1 # pyrefly: ignore\n1 1 # pyright: ignore $TMPDIR/enabled_ignores/foo.py \ $PYREFLY check $TMPDIR/enabled_ignores/foo.py --output-formatmin-text ERROR */foo.py:3* (glob) [1]foo.py三行代码分别带有# type: ignore、# pyrefly: ignore、# pyright: ignore注释每行都会产生1 1的类型错误。检查结果中只有第 3 行pyright被报告第 1、2 行被静默。这印证了Tool::default_enabled()的实现默认只信任type与pyrefly两个工具的忽略指令。从实现上看这一过滤发生在 ignore.rs 的suppression_effect方法中所有解析出的Suppression会先经过enabled_ignores.contains(supp.tool)过滤只有工具在启用集合内其SuppressionEffect才会被考虑最终取最强的效果max()排序为None DowngradeToWarning Suppress作用于该行诊断。三、enabled-ignores精确控制启用的工具集合如果希望尊重某个具体工具的忽略注释比如只启用# pyright: ignore在pyrefly.toml中设置enabled-ignores [pyright]验证效果来自 test/ignores.md 第二组命令$ echo enabled-ignores [pyright] $TMPDIR/enabled_ignores/pyrefly.toml \ $PYREFLY check $TMPDIR/enabled_ignores/foo.py --output-formatmin-text ERROR */foo.py:1* (glob) ERROR */foo.py:2* (glob) [1]结果反转第 3 行被# pyright: ignore抑制而第 1、2 行的# type: ignore和# pyrefly: ignore不再生效错误被如实报告。参数细节依据 args.rs 与 configuration.mdx类型工具名列表可用值type、pyrefly、mypy、pyright、pyre、ty默认值[type, pyrefly]命令行等价物--enabled-ignores可重复传参也支持逗号分隔列表value_delimiter ,例如--enabled-ignorespyright,mypy行为enabled-ignores会完全替换默认集合而不是在默认集合上追加。四、permissive-ignores一键尊重所有工具的忽略指令如果代码库同时混用了 Pyright、Mypy、Pyre 等工具的忽略注释逐一列举工具名过于繁琐此时permissive-ignores提供了快捷方式permissive-ignores true验证效果第三组命令$ echo permissive-ignores true $TMPDIR/enabled_ignores/pyrefly.toml \ $PYREFLY check $TMPDIR/enabled_ignores/foo.py --output-formatmin-text [0]三行全部被抑制退出码为 0。源码层面config.rs 将permissive-ignores true展开为Tool::all()即所有 7 种工具全部加入启用集合。参数细节依据 args.rs 与 configuration.mdx类型bool默认值false命令行等价物--permissive-ignores且支持--permissive-ignorestrue/false显式赋值num_args 0..1require_equals true等价关系启用它等价于把全部工具名传给enabled-ignores反过来enabled-ignores列出全部工具也等价于启用permissive-ignoresconfiguration.mdx。五、同一配置文件中两者互斥enabled-ignores优先如果在同一个pyrefly.toml中同时设置两个选项会触发告警且permissive-ignores被忽略第四组命令$ echo -e enabled-ignores [pyright]\npermissive-ignores true $TMPDIR/enabled_ignores/pyrefly.toml \ $PYREFLY check $TMPDIR/enabled_ignores/foo.py --output-formatmin-text --summarynone WARN * permissive-ignores will be ignored. (glob) ERROR */foo.py:1* (glob) ERROR */foo.py:2* (glob) [1]输出中的 WARN 正是 config.rs 的合并逻辑产生的let enabled_ignores match ( tools_from_permissive_ignores, self.root.enabled_ignores.clone(), ) { (None, None) Tool::default_enabled(), (None, Some(tools)) | (Some(tools), None) tools, (Some(_), Some(tools)) { configure_errors.push(anyhow!(Cannot use both permissive-ignores and enabled-ignores: permissive-ignores will be ignored.)); tools } };即两者都设置时保留enabled-ignores的值本示例中只有pyrightpermissive-ignores静默失效并通过配置错误以 WARN 形式呈现告知用户。六、命令行同样互斥--permissive-ignores与--enabled-ignores不能同时出现与配置文件内的互斥不同命令行参数之间是硬性报错第五组命令$ rm -f $TMPDIR/enabled_ignores/pyrefly.toml \ $PYREFLY check $TMPDIR/enabled_ignores/foo.py --enabled-ignorespyright --permissive-ignores Cannot use both --permissive-ignores and --enabled-ignores [1]这里的错误在参数解析阶段就发生args.rsif self.permissive_ignores.is_some() self.enabled_ignores.is_some() { return Err(anyhow!(Cannot use both --permissive-ignores and --enabled-ignores)); }注意与配置文件内行为的两处不同配置内是告警 忽略 permissive进程仍继续检查命令行是直接拒绝执行进程以非零退出码终止不会运行任何检查。七、命令行覆盖配置文件优先级规则当命令行与配置文件各设一项时命令行总是胜出。这是 args.rs 中三个分支的逻辑行为如下场景 1配置文件设enabled-ignores命令行传--permissive-ignores→ 结果 permissive$ echo enabled-ignores [pyright] $TMPDIR/enabled_ignores/pyrefly.toml \ $PYREFLY check $TMPDIR/enabled_ignores/foo.py --permissive-ignores --output-formatmin-text --summarynone [0]三行全部被抑制。源码中这一分支的特殊逻辑是当配置文件只设置了enabled-ignores未设permissive-ignores而命令行传入--permissive-ignores时直接用命令行值整体改写enabled-ignores集合args.rs。场景 2配置文件设permissive-ignores true命令行传--enabled-ignorespyright→ 结果 enabled-ignores$ echo permissive-ignores true $TMPDIR/enabled_ignores/pyrefly.toml \ $PYREFLY check $TMPDIR/enabled_ignores/foo.py --enabled-ignorespyright --output-formatmin-text --summarynone ERROR */foo.py:1* (glob) ERROR */foo.py:2* (glob) [1]第 1、2 行重新报错。对应源码命令行设置enabled-ignores时会清除配置里的permissive-ignores只保留命令行指定的工具args.rs。场景 3配置文件设enabled-ignores命令行显式传--permissive-ignoresfalse→ 结果 仅默认集合命令行覆盖配置文件$ echo enabled-ignores [pyright] $TMPDIR/enabled_ignores/pyrefly.toml \ $PYREFLY check $TMPDIR/enabled_ignores/foo.py \ --permissive-ignoresfalse --output-formatmin-text --summarynone ERROR */foo.py:3* (glob) [1]此时只有第 3 行报错——配置里的[pyright]被--permissive-ignoresfalse覆盖实际生效的是Tool::default_enabled(){type, pyrefly}所以只有# pyright: ignore失效。这展示了--permissive-ignoresfalse的另一种用途用显式布尔值覆盖任何已有的工具集合配置。完整的优先级总结如下配置来源配置来源结果配置文件enabled-ignores配置文件permissive-ignoresenabled-ignores生效permissive 告警并忽略命令行--enabled-ignores命令行--permissive-ignores直接报错拒绝执行配置文件enabled-ignores命令行--permissive-ignores命令行 permissive 覆盖配置文件permissive-ignores命令行--enabled-ignores命令行 enabled-ignores 覆盖配置文件enabled-ignores命令行--permissive-ignoresfalse回退到默认{type, pyrefly}八、从源码看两个配置的解析链路理解完整数据流有助于排查问题参数定义args.rs 定义 CLI 参数--permissive-ignores为Optionbool可带true/false--enabled-ignores为OptionVecTool逗号分隔配置结构base.rs 中ConfigBase持有permissive_ignores: Optionbool与enabled_ignores: OptionSmallSetTool命令行改写解析 CLI 时按第七节的三条分支规则改写配置树的这两个字段args.rs合并归一config.rs 将两个字段合并为唯一的enabled_ignores集合默认{type, pyrefly}同时报告配置内冲突生效判定ignore.rs 在报告诊断时通过enabled_ignores.contains(supp.tool)决定该行抑制是否有效。配置文件的 schema 定义见 schemas/pyrefly.jsonpermissive-ignores为boolean默认falseenabled-ignores为字符串数组默认[type, pyrefly]可用于编辑器补全与配置校验。九、最佳实践建议刚迁移到 Pyrefly、代码里只有# type: ignore保持默认即可无需任何配置与 Pyright 长期共存的项目优先用精确的enabled-ignores [type, pyrefly, pyright]避免permissive-ignores意外尊重未来新工具如zuban的注释从 Mypy 迁移、代码里有大量# mypy: ignore-errors可临时开启permissive-ignores true获得干净信号迁移完成后收紧为明确的工具列表CI 脚本优先使用命令行--enabled-ignores它覆盖配置文件便于按 job 差异化例如 CI 严格模式只保留type、pyrefly务必记住两条互斥规则同一配置文件内两者并存时 permissive 被忽略WARN同一命令行上两者并存时直接报错退出。最后提醒上述所有验证命令均可参照 test/ignores.md 原样运行替换$PYREFLY与$TMPDIR为你的环境变量--output-formatmin-text用于最小化输出--summarynone关闭总结以突出关键行这些命令本身就是仓库的回归测试用例确保行为与本文描述完全一致。【免费下载链接】pyreflyA fast type checker and language server for Python项目地址: https://gitcode.com/GitHub_Trending/py/pyrefly创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考