Pylint missing-return-type-doc（W9012）详解：强制要求文档中声明返回类型的配置与实践

静态分析代码质量Lint开发工具【免费下载链接】pylintIts not just a linter that annoys you!项目地址https://gitcode.com/gh_mirrors/pyl/pylint点击查看免费下载导读missing-return-type-docW9012是 Pylint 官方扩展docparams提供的一条文档规范检查消息用于在函数返回非None值且 docstring 中缺失返回类型声明如 Sphinx 的:rtype:时发出警告。它只在配置项accept-no-return-doc被显式设为no时才会触发本文将从消息定义、触发条件、源码判定逻辑、三种主流 docstring 风格的写法以及测试证据等维度带你完整掌握这条消息的启用方式与修复方法。消息定义与所属插件missing-return-type-doc属于 Pylint 的parameter_documentation检查器checker该检查器由官方扩展插件 pylint/extensions/docparams.py 提供用于校验 Sphinx、Google、Numpy 三种风格的 docstring。在 pylint/extensions/docparams.py 中该消息被定义为W9012: ( Missing return type documentation, missing-return-type-doc, Please document the type returned by this method., ),其消息类型为WWarning警告对应的官方文档页位于 extensions.rst。要启用这条消息需要在配置中通过load-pluginspylint.extensions.docparams加载扩展插件详见 missing-return-type-doc 的示例配置。触发条件核心开关 accept-no-return-doc官方消息文档 details.rst 只有一句话却点明了这条消息的命门This message is raised only when parameteraccept-no-return-docis set tono.也就是说missing-return-type-doc默认不会触发。插件对函数有返回值但 docstring 里完全没有返回文档这件事默认持宽容态度只有当你把accept-no-return-doc设为no强制要求每个有返回值的函数都必须写出返回文档时这条消息及其姊妹消息missing-return-doc才会被激活。配置项的源码定义在 pylint/extensions/docparams.py 中accept-no-return-doc的定义如下( accept-no-return-doc, { default: True, type: yn, metavar: y or n, help: Whether to accept totally missing return documentation in the docstring of a function that returns a statement., }, ),关键信息默认值为True即默认接受函数有返回值但 docstring 完全没写返回说明的情况取值类型为yn只能填yes/no、y/n或true/false这类布尔值语义当函数体内存在return语句时是否允许 docstring 中完全没有返回相关的说明。与它并列的还有accept-no-param-doc参数文档开关、accept-no-raise-doc异常文档开关和accept-no-yields-doc生成器 yield 文档开关它们共享相同的yn类型与默认值True共同组成docparams插件的宽松度控制组。三种配置方式方式一pylintrc 文件官方示例 pylintrc[main] load-pluginspylint.extensions.docparams [Parameter_documentation] accept-no-return-docno方式二pyproject.tomlPEP 621 风格的tool.pylint配置[tool.pylint.main] load-plugins pylint.extensions.docparams [tool.pylint.Parameter_documentation] accept-no-return-doc no方式三命令行直接传入pylint --load-pluginspylint.extensions.docparams \ --accept-no-return-docno your_module.py注意在命令行中传递yn类型参数时同样使用no或yes字样。官方示例bad 与 good 对照Pylint 官方消息库为这条消息准备了成对的示例文件位于 doc/data/messages/m/missing-return-type-doc/。触发警告的写法bad.pybad.pydef integer_sum(a: int, b: int): # [missing-return-type-doc] Returns sum of two integers :param a: first integer :param b: second integer :return: sum of parameters a and b return a b这个函数虽然已经在 docstring 里用:return:写明了返回什么签名中也有a: int, b: int的参数类型标注但存在两个缺口docstring 中缺少:rtype:字段即没有在文档中声明返回类型函数签名缺少- int的返回类型标注——在 visit_return 的实现 中函数没有返回类型注解func_node.returns为None时检查器会继续要求 docstring 中必须存在返回类型声明于是报出missing-return-type-doc。通过检查的写法good.pygood.pydef integer_sum(a: int, b: int) - int: Returns sum of two integers :param a: first integer :param b: second integer :return: sum of parameters a and b return a b唯一的差异是补上了- int返回类型标注。这正对应源码中的关键逻辑只要函数签名里有返回类型注解func_node.returns或type_comment_returns就无需再在 docstring 里重复写:rtype:。源码级判定逻辑剖析missing-return-type-doc的判定入口是 pylint/extensions/docparams.py 中的visit_return方法整体流程如下def visit_return(self, node: nodes.Return) - None: if not utils.returns_something(node): return # ① 返回 None 或裸 return跳过 if self.linter.config.accept_no_return_doc: return # ② 开关为 yes直接放过 func_node: nodes.FunctionDef node.frame() # ③ 匹配 no-docstring-rgx 的函数跳过 no_docstring_rgx self.linter.config.no_docstring_rgx if no_docstring_rgx and re.match(no_docstring_rgx, func_node.name): return doc utils.docstringify( func_node.doc_node, self.linter.config.default_docstring_type ) is_property checker_utils.decorated_with_property(func_node) # ④ 没有返回说明报 missing-return-doc if not (doc.has_returns() or (doc.has_property_returns() and is_property)): self.add_message(missing-return-doc, nodefunc_node, confidenceHIGH) # ⑤ 已有返回类型注解则不需要 :rtype: if func_node.returns or func_node.type_comment_returns: return # ⑥ 没有返回类型说明报 missing-return-type-doc if not (doc.has_rtype() or (doc.has_property_type() and is_property)): self.add_message(missing-return-type-doc, nodefunc_node, confidenceHIGH)逐层拆解先看是否真的返回了值utils.returns_something()定义在 pylint/extensions/_check_docs_utils.py它判定return节点是否有非None的值——裸return和return None都会被过滤掉因此返回None的函数不需要返回文档再看开关accept-no-return-doc为真默认值True时直接结束访问这正是只有设为no才报错的源码根因函数名豁免匹配no-docstring-rgx正则如默认的私有函数下划线前缀规则的函数被跳过测试文件 missing_return_doc_required.py 中的_function就展示了这一豁免区分两条消息missing-return-docW9011针对没有描述返回什么missing-return-type-docW9012针对没有声明返回类型二者可以同时触发详见下文测试一节类型注解优先函数签名已写- T或type_comment时docstring 不必再写:rtype:——这是官方 bad/good 示例的核心差异property 特殊处理对property装饰的函数判定改用has_property_returns()与has_property_type()即允许用 property 自己的 docstring 承担返回文档职责。Docstring 的是否包含返回/类型说明由基类Docstring及各风格子类实现pylint/extensions/_check_docs_utils.py。以 Sphinx 为例has_returns()通过正则:returns?:匹配:return:/:returns:字段has_rtype()通过:rtype:匹配pylint/extensions/_check_docs_utils.py。三种 docstring 风格的返回类型写法docparams支持 Sphinx、Google、Numpy 三种风格由default-docstring-type决定无法自动识别时的回退风格官方测试覆盖了三种风格在accept-no-return-docno下的完整行为以下写法均可避免missing-return-type-doc。Sphinx 风格:rtype:字段def my_func(self): find_sphinx_returns :return: Always False :rtype: bool return False当签名没有-注解时:rtype: bool就是检查器唯一认可的返回类型声明。如果只写了:return:而没有:rtype:则会触发 missing-return-type-doc 对应的测试用例。Google 风格Returns:段中的类型:前缀def my_func(self): Warn partial google returns Returns: bool: Always False return FalseGoogle 风格要求Returns:段中先写类型再接冒号和描述bool: ...反之只写描述不写类型会触发missing-return-type-doc只写类型不写描述会触发missing-return-doc两种缺陷在 missing_return_doc_required_Google.py 中都有对应的部分缺失用例。Numpy 风格Returns段下划线标题 类型行def my_func(self, doc_type): warn_partial_numpy_returns_type Arguments --------- doc_type : str Numpy Returns ------- bool return FalseNumpy 风格在Returns标题下方的类型行如bool即视为返回类型声明。若只写了Returns标题而类型行缺描述会报missing-return-doc整个Returns段缺失时两条消息同时出现参见 missing_return_doc_required_Numpy.py。何时两条消息同时出现missing-return-doc与missing-return-type-doc是相互独立的两个检查前者检查返回值的含义描述后者检查返回值的类型声明。当函数有非None返回值、accept-no-return-docno、且 docstring 中既无返回描述也无返回类型时两条消息会同时报出。官方测试 missing_return_doc_required.txt 给出了预期输出missing-return-doc:6:0:6:22:warns_no_docstring:Missing return documentation:HIGH missing-return-type-doc:6:0:6:22:warns_no_docstring:Missing return type documentation:HIGH其中被触发的是 missing_return_doc_required.py 中第 6 行的warns_no_docstring函数——它既不写 docstring也没有返回类型注解。注意该测试通过 missing_return_doc_required.rc 加载插件并设置accept-no-return-docno与官方消息库示例的配置方式完全一致。常见豁免与边界情况结合源码与测试以下几类函数即使accept-no-return-docno也不会触发该消息返回None的函数return None或裸return被returns_something()过滤pylint/extensions/_check_docs_utils.py签名带返回注解的函数- T或 type comment 一旦存在就不再要求 docstring 写:rtype:匹配no-docstring-rgx的函数如以下划线开头的私有函数_functionproperty的 settersetter 的返回文档职责转移到对应 property 的 docstringget_setters_property逻辑见 pylint/extensions/_check_docs_utils.py函数体过短受docstring-min-length约束或匹配no-docstring-rgx的情况在visit_functiondef入口处即被跳过pylint/extensions/docparams.py。总结从宽松到严格的启用路径missing-return-type-doc是一条默认关闭、需要显式开启的文档强制消息。开启的完整路径是加载pylint.extensions.docparams插件 → 将accept-no-return-doc设为no→ 为每个有非None返回值的函数补齐返回文档。补齐时有两条捷径要么在函数签名中写出- 类型注解要么按所用 docstring 风格Sphinx 的:rtype:、Google 的Returns:类型前缀、Numpy 的Returns类型行在文档中声明返回类型。仓库中的官方示例 bad.py 与 good.py 只差一个- int注解恰好演示了这条消息最典型的修复方式。赞分享静态分析代码质量Lint开发工具【免费下载链接】pylintIts not just a linter that annoys you!项目地址https://gitcode.com/gh_mirrors/pyl/pylint点击查看免费下载相关推荐pylint missing-return-doc用 accept-no-return-doc 强制函数返回值文档化pylint missing return doc用 accept no return doc 强制函数返回值文档化 本指南讲解 pylint 可选扩展 py静态分析代码质量Lint开发工具NgRx ESLint 规则深度解析updater-explicit-return-type 强制 ComponentStore Updater 显式声明返回类型NgRx ESLint 规则深度解析updater explicit return type 强制 ComponentStore Updater 显式声明返回前端状态管理TypeScript 函数返回类型推断Type from Func Return从实现推导返回值类型TypeScript 函数返回类型推断Type from Func Return从实现推导返回值类型 导读本文聚焦 TypeScript 中根据函数实文档教程上一篇BlackDex性能终极评测5大主流设备脱壳速度对比与效率分析下一篇czsc ang 模块信号全解析ADTM、ASI、SKDJ 等 10 个能量动量类 K 线信号的参数模板与源码实现创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考