Pylint 2.12.1相较于2.11.1出现Google风格参数文档识别异常问题

问题背景 #

我们在将项目使用的Pylint从2.11.1版本升级到2.12.1版本时，发现旧版本校验通过的代码在新版本中出现异常报错：已在docstring中明确声明的参数，仍然被判定为缺少参数文档。

复现代码与报错信息 #

存在误报的方法定义 #

async def run_callback(callback: common_types.AnyCallback) -> None:
    """Run the callback, handles sync and async functions.

    This WILL block the event loop if a sync function is called this way.
    IF a sync callback needs to be called, it should be wrapped in an
    async function and then called with run in executor. This cannot be
    done at this level because run_in_executor is a separate thread.
    Most async stuff is not thread safe and vice versa, so this is the
    minimal abstraction which won't introduce race conditions, the
    developer needs to handle it by manually doing a run_in_executor.

    Example:
        def sync_thing():
            pass

        async def async_thing():
            pass

        from cmnlibpy import utils

        await util.run_callback(sync_thing)
        await util.run_callback(async_thing)

    Args:
        callback:
            sync or async function which will be called
    """

参数类型定义 #

参数使用的类型来自同包的common_types.py，定义如下：

from typing import Union, Awaitable, Callable

SyncCallback = Callable[[], None]
AsyncCallback = Callable[[], Awaitable[None]]
AnyCallback = Union[SyncCallback, AsyncCallback]

Pylint报错信息 #

************* Module blah.blah.blah
blah/blah/blah.py:20:0: W9015: "callback" missing in parameter documentation (missing-param-doc)

我们尝试过调整参数在docstring中的位置、重命名参数等多种操作，均无法解决该问题。

问题原因 #

该问题并非官方弃用了Google风格的参数声明规范，而是Pylint 2.12.1版本中文档校验模块的正则匹配逻辑存在缺陷。

对比extensions/_check_docs_utils.py文件中GoogleDocstring匹配参数行的正则表达式变更记录，新版本规则要求要么参数后接冒号且描述写在同一行，要么参数后不加冒号且描述换行：

- \s*  (\w+)                                                          # identifier
- \s*  :
- \s*  (?:({GoogleDocstring.re_multiple_type})(?:,\s+optional)?)?     # optional type declaration
- \n                                                                  # description starts on a new line
- \s* (.*)                                                            # description

+ \s*  (\*{{0,2}}\w+)(\s?(:|\n))                                      # identifier with potential asterisks
+ \s*  (?:({GoogleDocstring.re_multiple_type})(?:,\s+optional)?\n)?   # optional type declaration
+ \s* (.*)                                                            # optional description

实际测试中，只有参数和描述写在同一行的写法可以被正常识别，例如：

callback: description goes here.

即使按照变更后的规则去掉参数行末尾的冒号，多行参数描述的写法依旧无法被正常识别，属于版本bug。目前该问题已经提交给Pylint开发团队处理。

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