Black 预览风格深度解析--preview 与 --unstable 如何塑造未来的 Python 代码风格【免费下载链接】blackThe uncompromising Python code formatter项目地址: https://gitcode.com/GitHub_Trending/bl/blackBlack 通过--preview与--unstable两级 CLI 开关把实验性格式改动与稳定风格隔离开来前者是预期进入下一年度稳定风格的候选项后者则收容了带已知缺陷的功能。本文基于 Black 仓库中的 future_style.md 文档完整梳理当前收录的 13 项预览特性与 2 项不稳定特性的行为规则、格式化前后对照并结合 Preview 枚举 与格式化主流程源码说明特性的启用机制与降级路径帮助你在采用新风格前评估其对存量代码库的实际影响。预览风格Preview style的运作机制实验性、可能造成破坏的风格改动统一收在--previewCLI 开关之下。按照 The Black Code Style 描述的风格演进流程这些改动在每年年底有机会被采纳进默认风格。由于功能处于实验阶段Black 官方强烈欢迎反馈与 issue 报告。在源码层面预览特性以枚举集中声明于 src/black/mode.pyclass Preview(Enum): Individual preview style features. # NOTE: string_processing requires wrap_long_dict_values_in_parens # for https://github.com/psf/black/issues/3117 to be fixed. string_processing auto() hug_parens_with_braces_and_square_brackets auto() wrap_comprehension_in auto() simplify_power_operator_hugging auto() wrap_long_dict_values_in_parens auto() fix_if_guard_explosion_in_case_statement auto() pyi_overload_group_blank_lines auto() fix_unnecessary_parens_in_indexed_assignment auto() pyi_blank_line_before_decorated_class auto() pyi_blank_line_after_function_docstring auto() hug_comparator auto() parenthesize_tuple_in_yield auto() fmt_off_class_blank_lines auto() remove_redundant_generator_parentheses auto()特性的启用判定逻辑实现在 Mode.contains中--unstable模式下全部特性生效--preview模式下除UNSTABLE_FEATURES中的特性外全部生效此外--enable-unstable-feature单独点名的特性也始终生效。CLI 参数定义见 src/black/__init__.py--unstable的 help 文本明确写着 Implies --preview隐含启用 preview而--enable-unstable-feature的回调 enable_unstable_feature_callback 会把参数值解析为Preview枚举项。当--enable-unstable-feature未搭配--preview/--unstable使用时main 入口 会直接报错提示该选项依赖--preview。当前预览风格收录的特性清单文档目前列出以下 13 项预览特性均通过--preview一次性启用特性名作用简述wrap_comprehension_in当列表/字典推导式的in子句过长时将其折行simplify_power_operator_hugging简化幂运算符 hugging去除**两侧空白逻辑跨行时同样生效wrap_long_dict_values_in_parens为字典中的长值添加括号并移除不必要的括号fix_if_guard_explosion_in_case_statement修复case模式中带尾随逗号的if守卫表达式被过度爆炸的问题pyi_overload_group_blank_lines改进.pyi桩文件中同名装饰函数组如overload前后的空行启发式pyi_blank_line_before_decorated_class.pyi中在函数定义之后、带装饰器类定义之前强制空行fix_unnecessary_parens_in_indexed_assignment下标赋值目标过长换行时移除右侧表达式中不必要的括号pyi_blank_line_after_function_docstring.pyi中在以文档字符串为函数体的定义之后强制空行hug_comparator比较符右侧是需要强制折行的括号表达式时跳过比较符处换行、让括号爆炸parenthesize_tuple_in_yield为yield语句中的元组表达式添加括号fmt_off_class_blank_lines在 import 之后、# fmt: off块内起始的顶级类前保留两行空行remove_redundant_generator_parentheses移除生成器表达式上多余的括号以下各节按文档脉络逐项展开。对应的回归测试数据位于tests/data/cases/目录文件名以preview_前缀标识如 preview_hug_comparator.py、preview_long_dict_values.py、preview_redundant_generator_parentheses.py 等每个文件首行以# flags: --preview或--unstable声明该用例所需的开关。移除生成器表达式上多余的括号当生成器表达式是函数调用的唯一实参时调用本身的括号已经足够在其它上下文中Black 保留 Python 语法要求的括号、仅删除多余的一对。# Before any((item.is_valid() for item in items)) # After (with --preview) any(item.is_valid() for item in items)# Before [((item for item in items)), fallback] # After (with --preview) [(item for item in items), fallback]在实现上该特性在 linegen.py 与 linegen.py 两处分别对唯一实参场景和其它上下文场景进行括号裁剪判断。折行过长的推导式in子句当列表或字典推导式含有会超出最大行长度的in子句时Black 会将其折叠到多行提升复杂可迭代表达式下的可读性# Before result [ very_very_very_very_very_long_item for very_very_very_very_very_long_item in some_very_very_very_very_very_very_long_function_name ]# After result [ very_very_very_very_very_long_item for very_very_very_very_very_long_item in ( some_very_very_very_very_very_very_long_function_name ) ]字典推导式同样适用# Before mapping { very_long_key: very_very_very_long_item for very_long_key, very_very_very_long_item in very_very_very_very_long_function_name }# After mapping { for very_long_key: very_very_very_long_item for very_long_key, very_very_very_long_item in ( very_very_very_very_long_function_name ) }源码中该逻辑落在 linegen.py 的推导式处理分支内仅在Preview.wrap_comprehension_in in self.mode为真时触发。简化的幂运算符空白处理Black 的幂运算符 hugging 逻辑会在简单表达式中移除**两侧的空白x**2而非x ** 2。该特性采用更简单、更一致的实现在幂运算被拆到多行的罕见场景下也能生效# Simple expressions - whitespace is removed result x**2 y**3 value base**exponent# Complex expression split across lines result ( some_very_long_base_expression **some_very_long_exponent_expression **some_very_long_third_expression )这个特性主要改善的是 Black 内部格式化逻辑的一致性对大多数代码的视觉效果不会有显著变化。其实现散布在 linegen.py、linegen.py 与 nodes.py 中未启用时走旧的复杂判断路径。字典中括号管理的改进字典字面量中的长值现在会被包裹进括号同时不必要的括号会被移除my_dict { a key in my dict: a_very_long_variable * and_a_very_long_function_call() / 100000.0, another key: (short_value), }my_dict { a key in my dict: ( a_very_long_variable * and_a_very_long_function_call() / 100000.0 ), another key: short_value, }Preview.wrap_long_dict_values_in_parens在 linegen.py 的字典项处理、linegen.py 与 linegen.py 的拆行决策中多处参与判断。值得注意的是 mode.py 中的注释string_processing依赖wrap_long_dict_values_in_parens这也是不稳定特性仍保留在--unstable中的原因之一。.pyi桩文件中 overload 分组的空行改进在.pyi桩文件中Black 现在改进了装饰函数组共享同名、数量 ≥2 的装饰函数典型如overload组前后及组内何时出现空行的启发式。判定某装饰函数属于此类分组时应用两条规则装饰函数之前始终插入空行除非前一条语句也是同名的装饰函数即同属overload组或该函数是其所在块的第一条语句。装饰函数之后始终插入空行除非后一条语句是同名装饰函数。这两条规则与相邻语句的类型无关——无论是另一个函数定义、变量注解还是其它语句。此前当组内某个 overload 带文档字符串时Black 可能在组内部插入多余空行也不会在组边界一致地强制空行# Before overload def foo(x: int) - int: Docs. overload # unwanted blank line within group def foo(x: str) - str: ... def bar(x): ... # no blank line after group启用后overload 组保持紧凑并与周边代码清晰分隔# After (with --preview) overload def foo(x: int) - int: Docs. overload def foo(x: str) - str: ... def bar(x): ...对应的回归数据见 pyi_overload_groups.py。.pyi中带装饰器类定义前的空行.pyi文件中 Black 在多种情形下已强制类定义周围留空行但当类带装饰器时旧行为反而会删除函数与装饰器之间的空行# Before def foo(): ... - decorator class Bar: ... def baz(): ... decorator class Spam: ...启用pyi_blank_line_before_decorated_class后与未装饰类的处理保持一致地强制空行# After (with --preview) def foo(): ... decorator class Bar: ... def baz(): ... decorator class Spam: ...测试用例 pyi_decorated_class_blank_line.py 覆盖该行为。下标赋值中多余的括号当赋值目标以下标结尾如x[key] expr且整行放不下一行时Black 必须在下标括号处拆行。此前它还会额外给右侧表达式包一层括号即使表达式能放进收尾行启用fix_unnecessary_parens_in_indexed_assignment后这些多余括号会被省略# Before dictionary_of_arrays[long_key_name_for_the_example][ very_long_index_name, index_zero ] (10 - 5)# After (with --preview) dictionary_of_arrays[long_key_name_for_the_example][ very_long_index_name, index_zero ] 10 - 5目标能放进一行的赋值不受影响——那里右侧表达式带括号仍是首选风格。该场景的回归数据见 preview_prefer_rhs_split_indexed_assignment.py。.pyi中函数文档字符串之后的空行.pyi中函数或方法的整个函数体有时就是一个文档字符串。Black 此前已能把这类定义与后续函数定义隔开但在后续是注释、条件块、变量注解或其它语句时处理不一致# Before class Example: def method(self) - None: Documentation. # comment for the next member attr: int# After (with --preview) class Example: def method(self) - None: Documentation. # comment for the next member attr: int同时同名的装饰函数如overload组与 property setter 对仍然保持聚合中间不插入空行。让比较符紧贴左操作数当比较符not in、、is等位于另一个括号结构内部且其右操作数是一个必须折行的括号表达式因魔法尾逗号或行宽不足时旧行为会在比较符之前拆行——左操作数孤身一行与说明它的操作符和右操作数在视觉上断联# Before x [ t for t in y if t not in { LongNameOne, LongNameTwo, LongNameThree, } ]启用hug_comparator后Black 跳过比较符处的拆行改为让右侧括号爆炸它本来也要爆炸# After (with --preview) x [ t for t in y if t not in { LongNameOne, LongNameTwo, LongNameThree, } ]修复不限于推导式if/elif链、assert语句和带括号表达式中出现相同形状时同样生效# Before if ( is_scalar(value) and self.dtype in (np.dtype(float64), np.dtype(float32), np.dtype(object)) and (limit is not None or inplace) ): ... assert ( bool is _AnnotationExtractor(attr.fields(C).x.converter.__call__).get_return_type() )# After (with --preview) if ( is_scalar(value) and self.dtype in ( np.dtype(float64), np.dtype(float32), np.dtype(object), ) and (limit is not None or inplace) ): ... assert ( bool is _AnnotationExtractor( attr.fields(C).x.converter.__call__ ).get_return_type() )该特性的判断入口在 linegen.py 的Preview.hug_comparator in mode分支。不稳定风格Unstable style历史上 preview 风格中混入了若干带已知 bug 的特性导致无法晋升到稳定风格。如今这类特性被移入--unstable风格所有--preview特性预期能进入下一年度的稳定风格--unstable中的特性只有在问题修复后才会被稳定化若某个--preview特性被发现存在 bug会被降级到--unstable风格为避免特性从--preview降级到--unstable时用户格式来回震荡thrash可以用--enable-unstable-feature显式点名启用特定不稳定特性。源码中UNSTABLE_FEATURES集合当前包含两项src/black/mode.py并附注了降级原因string_processing问题较多见 issue #4208 汇总hug_parens_with_braces_and_square_brackets存在崩溃问题#4036及待定的调整#4098、#4099。文档列出的不稳定特性为hug_parens_with_braces_and_square_brackets嵌套括号的更紧凑格式化string_processing长字符串字面量拆分及相关改动。嵌套括号的紧凑格式化hug_parens_with_braces_and_square_brackets为提升可读性、降低纵向跨度Black 现在把圆括号()、花括号{}、方括号[]在同一行上配对foo( [ 1, 2, 3, ] ) nested_array [ [ 1, 2, 3, ] ]foo([ 1, 2, 3, ]) nested_array [[ 1, 2, 3, ]]列表/字典解包同样适用foo( *[ a_long_function_name(a_long_variable_name) for a_long_variable_name in some_generator ] )foo(*[ a_long_function_name(a_long_variable_name) for a_long_variable_name in some_generator ])可以用魔法尾逗号避免这种紧凑化由于存在尾逗号Black 默认不会重排下列代码foo( [ 1, 2, 3, ], )回归数据见 preview_hug_parens_with_braces_and_square_brackets.py 及其--unstable变体 preview_hug_parens_with_braces_and_square_brackets_no_ll1.py。实现位于 linegen.py 附近的括号闭合处理。改进的字符串处理string_processingBlack 会拆分过长的字符串字面量、合并过短的字符串在合适的位置使用括号。f-string 拆分时不需要格式化的部分会被转成普通字符串若 f-string 内部含有引号、且合并会改变其引号风格则不会合并。行续行反斜杠会被转换为带括号的字符串不必要的括号会被剥离。该特性的稳定性与状态由上游 issue #2188 跟踪。相关行为测试数据包括 preview_long_strings.py、preview_long_strings__regression.py 等字符串转换逻辑本身位于 src/black/strings.py特性开关判断在 linegen.py 与 linegen.py。如何在项目中实际使用与验证三个开关的完整命令形态如下以 src/black/__init__.py 的选项定义为准确依据# 启用全部预览特性预期进入下一年度稳定风格 black --preview . # 启用全部不稳定特性隐含 --preview存在已知 bug black --unstable . # 仅显式启用某个不稳定特性避免特性降级引起整体震荡 black --preview --enable-unstable-feature hug_parens_with_braces_and_square_brackets .要点与限制--preview的 help 说明为启用可能随下一主版本进入 Black 主功能的、有破坏性的风格改动属于实验性质反馈与 issue 报告被强烈鼓励--unstable隐含--preview其帮助文本明确警告有已知 bug或目前不预期进入下一主版本的稳定风格--enable-unstable-feature取值是Preview枚举的成员名如string_processing、hug_parens_with_braces_and_square_brackets可重复传入多个且必须与--preview或--unstable搭配否则 CLI 会报错见 src/black/__init__.py缓存键机制会区分这些开关Mode.get_cache_key 把preview、unstable布尔位与启用特性名的哈希都计入缓存键因此同一文件在不同开关组合下的格式结果互不污染。在测试体系中每个特性用例都是 tests/data/cases/ 下的一个文件首行# flags: --preview或--unstable声明所需开关由 tests/util.py 的read_data_with_mode解析后交给 tests/test_format.py 的check_file做格式化输入应等于期望输出的断言。若你要评估某个预览特性对既有代码的影响面可以直接在 CI 中对同一代码库分别运行black --check与black --check --preview用两次结果的差异来观察具体触发了哪些行为变化——这也是官方文档鼓励的反馈方式。小结Black 的风格演进采用preview 孵化、unstable 收容、年度晋升的三段式--preview收录预期进入下一年度稳定风格的 13 项特性涵盖生成器括号清理、推导式in子句折行、字典长值加括号、比较符 hugging、.pyi空行规则等--unstable则收容hug_parens_with_braces_and_square_brackets与string_processing两项带已知缺陷的功能并可用--enable-unstable-feature精确点名启用。所有特性均以 Preview 枚举 为唯一事实来源行为由 linegen.py 主格式化循环中的in self.mode分支驱动并有tests/data/cases/下同名回归用例逐一对应可据此做进一步查证。【免费下载链接】blackThe uncompromising Python code formatter项目地址: https://gitcode.com/GitHub_Trending/bl/black创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Black 预览风格深度解析：--preview 与 --unstable 如何塑造未来的 Python 代码风格
Black 预览风格深度解析--preview 与 --unstable 如何塑造未来的 Python 代码风格【免费下载链接】blackThe uncompromising Python code formatter项目地址: https://gitcode.com/GitHub_Trending/bl/blackBlack 通过--preview与--unstable两级 CLI 开关把实验性格式改动与稳定风格隔离开来前者是预期进入下一年度稳定风格的候选项后者则收容了带已知缺陷的功能。本文基于 Black 仓库中的 future_style.md 文档完整梳理当前收录的 13 项预览特性与 2 项不稳定特性的行为规则、格式化前后对照并结合 Preview 枚举 与格式化主流程源码说明特性的启用机制与降级路径帮助你在采用新风格前评估其对存量代码库的实际影响。预览风格Preview style的运作机制实验性、可能造成破坏的风格改动统一收在--previewCLI 开关之下。按照 The Black Code Style 描述的风格演进流程这些改动在每年年底有机会被采纳进默认风格。由于功能处于实验阶段Black 官方强烈欢迎反馈与 issue 报告。在源码层面预览特性以枚举集中声明于 src/black/mode.pyclass Preview(Enum): Individual preview style features. # NOTE: string_processing requires wrap_long_dict_values_in_parens # for https://github.com/psf/black/issues/3117 to be fixed. string_processing auto() hug_parens_with_braces_and_square_brackets auto() wrap_comprehension_in auto() simplify_power_operator_hugging auto() wrap_long_dict_values_in_parens auto() fix_if_guard_explosion_in_case_statement auto() pyi_overload_group_blank_lines auto() fix_unnecessary_parens_in_indexed_assignment auto() pyi_blank_line_before_decorated_class auto() pyi_blank_line_after_function_docstring auto() hug_comparator auto() parenthesize_tuple_in_yield auto() fmt_off_class_blank_lines auto() remove_redundant_generator_parentheses auto()特性的启用判定逻辑实现在 Mode.contains中--unstable模式下全部特性生效--preview模式下除UNSTABLE_FEATURES中的特性外全部生效此外--enable-unstable-feature单独点名的特性也始终生效。CLI 参数定义见 src/black/__init__.py--unstable的 help 文本明确写着 Implies --preview隐含启用 preview而--enable-unstable-feature的回调 enable_unstable_feature_callback 会把参数值解析为Preview枚举项。当--enable-unstable-feature未搭配--preview/--unstable使用时main 入口 会直接报错提示该选项依赖--preview。当前预览风格收录的特性清单文档目前列出以下 13 项预览特性均通过--preview一次性启用特性名作用简述wrap_comprehension_in当列表/字典推导式的in子句过长时将其折行simplify_power_operator_hugging简化幂运算符 hugging去除**两侧空白逻辑跨行时同样生效wrap_long_dict_values_in_parens为字典中的长值添加括号并移除不必要的括号fix_if_guard_explosion_in_case_statement修复case模式中带尾随逗号的if守卫表达式被过度爆炸的问题pyi_overload_group_blank_lines改进.pyi桩文件中同名装饰函数组如overload前后的空行启发式pyi_blank_line_before_decorated_class.pyi中在函数定义之后、带装饰器类定义之前强制空行fix_unnecessary_parens_in_indexed_assignment下标赋值目标过长换行时移除右侧表达式中不必要的括号pyi_blank_line_after_function_docstring.pyi中在以文档字符串为函数体的定义之后强制空行hug_comparator比较符右侧是需要强制折行的括号表达式时跳过比较符处换行、让括号爆炸parenthesize_tuple_in_yield为yield语句中的元组表达式添加括号fmt_off_class_blank_lines在 import 之后、# fmt: off块内起始的顶级类前保留两行空行remove_redundant_generator_parentheses移除生成器表达式上多余的括号以下各节按文档脉络逐项展开。对应的回归测试数据位于tests/data/cases/目录文件名以preview_前缀标识如 preview_hug_comparator.py、preview_long_dict_values.py、preview_redundant_generator_parentheses.py 等每个文件首行以# flags: --preview或--unstable声明该用例所需的开关。移除生成器表达式上多余的括号当生成器表达式是函数调用的唯一实参时调用本身的括号已经足够在其它上下文中Black 保留 Python 语法要求的括号、仅删除多余的一对。# Before any((item.is_valid() for item in items)) # After (with --preview) any(item.is_valid() for item in items)# Before [((item for item in items)), fallback] # After (with --preview) [(item for item in items), fallback]在实现上该特性在 linegen.py 与 linegen.py 两处分别对唯一实参场景和其它上下文场景进行括号裁剪判断。折行过长的推导式in子句当列表或字典推导式含有会超出最大行长度的in子句时Black 会将其折叠到多行提升复杂可迭代表达式下的可读性# Before result [ very_very_very_very_very_long_item for very_very_very_very_very_long_item in some_very_very_very_very_very_very_long_function_name ]# After result [ very_very_very_very_very_long_item for very_very_very_very_very_long_item in ( some_very_very_very_very_very_very_long_function_name ) ]字典推导式同样适用# Before mapping { very_long_key: very_very_very_long_item for very_long_key, very_very_very_long_item in very_very_very_very_long_function_name }# After mapping { for very_long_key: very_very_very_long_item for very_long_key, very_very_very_long_item in ( very_very_very_very_long_function_name ) }源码中该逻辑落在 linegen.py 的推导式处理分支内仅在Preview.wrap_comprehension_in in self.mode为真时触发。简化的幂运算符空白处理Black 的幂运算符 hugging 逻辑会在简单表达式中移除**两侧的空白x**2而非x ** 2。该特性采用更简单、更一致的实现在幂运算被拆到多行的罕见场景下也能生效# Simple expressions - whitespace is removed result x**2 y**3 value base**exponent# Complex expression split across lines result ( some_very_long_base_expression **some_very_long_exponent_expression **some_very_long_third_expression )这个特性主要改善的是 Black 内部格式化逻辑的一致性对大多数代码的视觉效果不会有显著变化。其实现散布在 linegen.py、linegen.py 与 nodes.py 中未启用时走旧的复杂判断路径。字典中括号管理的改进字典字面量中的长值现在会被包裹进括号同时不必要的括号会被移除my_dict { a key in my dict: a_very_long_variable * and_a_very_long_function_call() / 100000.0, another key: (short_value), }my_dict { a key in my dict: ( a_very_long_variable * and_a_very_long_function_call() / 100000.0 ), another key: short_value, }Preview.wrap_long_dict_values_in_parens在 linegen.py 的字典项处理、linegen.py 与 linegen.py 的拆行决策中多处参与判断。值得注意的是 mode.py 中的注释string_processing依赖wrap_long_dict_values_in_parens这也是不稳定特性仍保留在--unstable中的原因之一。.pyi桩文件中 overload 分组的空行改进在.pyi桩文件中Black 现在改进了装饰函数组共享同名、数量 ≥2 的装饰函数典型如overload组前后及组内何时出现空行的启发式。判定某装饰函数属于此类分组时应用两条规则装饰函数之前始终插入空行除非前一条语句也是同名的装饰函数即同属overload组或该函数是其所在块的第一条语句。装饰函数之后始终插入空行除非后一条语句是同名装饰函数。这两条规则与相邻语句的类型无关——无论是另一个函数定义、变量注解还是其它语句。此前当组内某个 overload 带文档字符串时Black 可能在组内部插入多余空行也不会在组边界一致地强制空行# Before overload def foo(x: int) - int: Docs. overload # unwanted blank line within group def foo(x: str) - str: ... def bar(x): ... # no blank line after group启用后overload 组保持紧凑并与周边代码清晰分隔# After (with --preview) overload def foo(x: int) - int: Docs. overload def foo(x: str) - str: ... def bar(x): ...对应的回归数据见 pyi_overload_groups.py。.pyi中带装饰器类定义前的空行.pyi文件中 Black 在多种情形下已强制类定义周围留空行但当类带装饰器时旧行为反而会删除函数与装饰器之间的空行# Before def foo(): ... - decorator class Bar: ... def baz(): ... decorator class Spam: ...启用pyi_blank_line_before_decorated_class后与未装饰类的处理保持一致地强制空行# After (with --preview) def foo(): ... decorator class Bar: ... def baz(): ... decorator class Spam: ...测试用例 pyi_decorated_class_blank_line.py 覆盖该行为。下标赋值中多余的括号当赋值目标以下标结尾如x[key] expr且整行放不下一行时Black 必须在下标括号处拆行。此前它还会额外给右侧表达式包一层括号即使表达式能放进收尾行启用fix_unnecessary_parens_in_indexed_assignment后这些多余括号会被省略# Before dictionary_of_arrays[long_key_name_for_the_example][ very_long_index_name, index_zero ] (10 - 5)# After (with --preview) dictionary_of_arrays[long_key_name_for_the_example][ very_long_index_name, index_zero ] 10 - 5目标能放进一行的赋值不受影响——那里右侧表达式带括号仍是首选风格。该场景的回归数据见 preview_prefer_rhs_split_indexed_assignment.py。.pyi中函数文档字符串之后的空行.pyi中函数或方法的整个函数体有时就是一个文档字符串。Black 此前已能把这类定义与后续函数定义隔开但在后续是注释、条件块、变量注解或其它语句时处理不一致# Before class Example: def method(self) - None: Documentation. # comment for the next member attr: int# After (with --preview) class Example: def method(self) - None: Documentation. # comment for the next member attr: int同时同名的装饰函数如overload组与 property setter 对仍然保持聚合中间不插入空行。让比较符紧贴左操作数当比较符not in、、is等位于另一个括号结构内部且其右操作数是一个必须折行的括号表达式因魔法尾逗号或行宽不足时旧行为会在比较符之前拆行——左操作数孤身一行与说明它的操作符和右操作数在视觉上断联# Before x [ t for t in y if t not in { LongNameOne, LongNameTwo, LongNameThree, } ]启用hug_comparator后Black 跳过比较符处的拆行改为让右侧括号爆炸它本来也要爆炸# After (with --preview) x [ t for t in y if t not in { LongNameOne, LongNameTwo, LongNameThree, } ]修复不限于推导式if/elif链、assert语句和带括号表达式中出现相同形状时同样生效# Before if ( is_scalar(value) and self.dtype in (np.dtype(float64), np.dtype(float32), np.dtype(object)) and (limit is not None or inplace) ): ... assert ( bool is _AnnotationExtractor(attr.fields(C).x.converter.__call__).get_return_type() )# After (with --preview) if ( is_scalar(value) and self.dtype in ( np.dtype(float64), np.dtype(float32), np.dtype(object), ) and (limit is not None or inplace) ): ... assert ( bool is _AnnotationExtractor( attr.fields(C).x.converter.__call__ ).get_return_type() )该特性的判断入口在 linegen.py 的Preview.hug_comparator in mode分支。不稳定风格Unstable style历史上 preview 风格中混入了若干带已知 bug 的特性导致无法晋升到稳定风格。如今这类特性被移入--unstable风格所有--preview特性预期能进入下一年度的稳定风格--unstable中的特性只有在问题修复后才会被稳定化若某个--preview特性被发现存在 bug会被降级到--unstable风格为避免特性从--preview降级到--unstable时用户格式来回震荡thrash可以用--enable-unstable-feature显式点名启用特定不稳定特性。源码中UNSTABLE_FEATURES集合当前包含两项src/black/mode.py并附注了降级原因string_processing问题较多见 issue #4208 汇总hug_parens_with_braces_and_square_brackets存在崩溃问题#4036及待定的调整#4098、#4099。文档列出的不稳定特性为hug_parens_with_braces_and_square_brackets嵌套括号的更紧凑格式化string_processing长字符串字面量拆分及相关改动。嵌套括号的紧凑格式化hug_parens_with_braces_and_square_brackets为提升可读性、降低纵向跨度Black 现在把圆括号()、花括号{}、方括号[]在同一行上配对foo( [ 1, 2, 3, ] ) nested_array [ [ 1, 2, 3, ] ]foo([ 1, 2, 3, ]) nested_array [[ 1, 2, 3, ]]列表/字典解包同样适用foo( *[ a_long_function_name(a_long_variable_name) for a_long_variable_name in some_generator ] )foo(*[ a_long_function_name(a_long_variable_name) for a_long_variable_name in some_generator ])可以用魔法尾逗号避免这种紧凑化由于存在尾逗号Black 默认不会重排下列代码foo( [ 1, 2, 3, ], )回归数据见 preview_hug_parens_with_braces_and_square_brackets.py 及其--unstable变体 preview_hug_parens_with_braces_and_square_brackets_no_ll1.py。实现位于 linegen.py 附近的括号闭合处理。改进的字符串处理string_processingBlack 会拆分过长的字符串字面量、合并过短的字符串在合适的位置使用括号。f-string 拆分时不需要格式化的部分会被转成普通字符串若 f-string 内部含有引号、且合并会改变其引号风格则不会合并。行续行反斜杠会被转换为带括号的字符串不必要的括号会被剥离。该特性的稳定性与状态由上游 issue #2188 跟踪。相关行为测试数据包括 preview_long_strings.py、preview_long_strings__regression.py 等字符串转换逻辑本身位于 src/black/strings.py特性开关判断在 linegen.py 与 linegen.py。如何在项目中实际使用与验证三个开关的完整命令形态如下以 src/black/__init__.py 的选项定义为准确依据# 启用全部预览特性预期进入下一年度稳定风格 black --preview . # 启用全部不稳定特性隐含 --preview存在已知 bug black --unstable . # 仅显式启用某个不稳定特性避免特性降级引起整体震荡 black --preview --enable-unstable-feature hug_parens_with_braces_and_square_brackets .要点与限制--preview的 help 说明为启用可能随下一主版本进入 Black 主功能的、有破坏性的风格改动属于实验性质反馈与 issue 报告被强烈鼓励--unstable隐含--preview其帮助文本明确警告有已知 bug或目前不预期进入下一主版本的稳定风格--enable-unstable-feature取值是Preview枚举的成员名如string_processing、hug_parens_with_braces_and_square_brackets可重复传入多个且必须与--preview或--unstable搭配否则 CLI 会报错见 src/black/__init__.py缓存键机制会区分这些开关Mode.get_cache_key 把preview、unstable布尔位与启用特性名的哈希都计入缓存键因此同一文件在不同开关组合下的格式结果互不污染。在测试体系中每个特性用例都是 tests/data/cases/ 下的一个文件首行# flags: --preview或--unstable声明所需开关由 tests/util.py 的read_data_with_mode解析后交给 tests/test_format.py 的check_file做格式化输入应等于期望输出的断言。若你要评估某个预览特性对既有代码的影响面可以直接在 CI 中对同一代码库分别运行black --check与black --check --preview用两次结果的差异来观察具体触发了哪些行为变化——这也是官方文档鼓励的反馈方式。小结Black 的风格演进采用preview 孵化、unstable 收容、年度晋升的三段式--preview收录预期进入下一年度稳定风格的 13 项特性涵盖生成器括号清理、推导式in子句折行、字典长值加括号、比较符 hugging、.pyi空行规则等--unstable则收容hug_parens_with_braces_and_square_brackets与string_processing两项带已知缺陷的功能并可用--enable-unstable-feature精确点名启用。所有特性均以 Preview 枚举 为唯一事实来源行为由 linegen.py 主格式化循环中的in self.mode分支驱动并有tests/data/cases/下同名回归用例逐一对应可据此做进一步查证。【免费下载链接】blackThe uncompromising Python code formatter项目地址: https://gitcode.com/GitHub_Trending/bl/black创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
