当black与pydocstyle规则冲突时，如何解决代码格式矛盾？

问题代码 #

from typing import Callable

# 假设FieldStringer、PayloadSetter、Payload为已定义的类型
FieldStringer = Callable[[], str]
PayloadSetter = Callable[[object, dict], None]
Payload = dict

def dictionary_updater(key: str) -> Callable[[FieldStringer], PayloadSetter]:
    """Convert string-converter to dictionary modifier.
    """
    # Create the actual decorator method and return it
    def inner(func: FieldStringer) -> PayloadSetter:
        # Create the method that should actually be called when the decorated function
        # is invoked
        def with_dict(self, payload: Payload) -> None:
            payload[key] = func(self)

        return with_dict

    return inner

问题描述 #

我编写了上述Python装饰器代码，遇到工具冲突：格式化工具Black会自动在文档字符串后添加空行，但代码检查工具pydocstyle会因文档字符串与函数体间存在空行而报错。尝试分别禁用两者对应规则但未生效，且无法修改CI/CD管道的工具配置，也不想禁用整个文件的检查，该如何解决？

解决方案 #

方案1：调整单行文档字符串格式（最稳妥） #

Black对单行文档字符串的处理逻辑是：如果文档字符串没有末尾换行，不会在其后添加空行。将文档字符串修改为无 trailing 换行的形式，即可同时满足两个工具的要求：

def dictionary_updater(key: str) -> Callable[[FieldStringer], PayloadSetter]:
    """Convert string-converter to dictionary modifier."""
    # Create the actual decorator method and return it
    def inner(func: FieldStringer) -> PayloadSetter:
        # 剩余代码保持不变
        def with_dict(self, payload: Payload) -> None:
            payload[key] = func(self)

        return with_dict

    return inner

方案2：行内规则忽略（备用） #

如果调整文档字符串格式不可行，可以尝试行内注释针对性忽略规则：

• 忽略pydocstyle的对应检查：在文档字符串后的第一行添加# noqa: D203（D203通常是"文档字符串后不应有空行"的规则，需根据实际报错码调整）
• 忽略Black的格式化：在函数定义行末尾添加# fmt: skip，阻止Black修改该函数的格式

示例（忽略pydocstyle）：

def dictionary_updater(key: str) -> Callable[[FieldStringer], PayloadSetter]:
    """Convert string-converter to dictionary modifier.
    """
    # noqa: D203
    # Create the actual decorator method and return it
    def inner(func: FieldStringer) -> PayloadSetter:
        # 剩余代码不变

内容的提问来源于stack exchange，提问作者Woody1193