validate-modules

分析模块中代码和文档中的常见问题。

用法

cd /path/to/ansible/source
source hacking/env-setup
ansible-test sanity --test validate-modules

帮助

键入 ansible-test sanity --test validate-modules -h 以显示此健全性测试的使用帮助。

扩展 validate-modules

validate-modules 工具有一个 schema.py 用于验证 YAML 块，例如 DOCUMENTATION 和 RETURNS。

代码

错误代码	类型	级别	示例消息
ansible-deprecated-module	文档	错误	某个模块已弃用，应该在当前或更早的 Ansible 版本中移除
collection-deprecated-module	文档	错误	某个模块已弃用，应该在当前或更早的集合版本中移除
ansible-deprecated-version	文档	错误	某个功能已弃用，应该在当前或更早的 Ansible 版本中移除
ansible-module-not-initialized	语法	错误	模块的执行未导致 AnsibleModule 的初始化
collection-deprecated-version	文档	错误	某个功能已弃用，应该在当前或更早的集合版本中移除
deprecated-date	文档	错误	早于今天的日期显示为 removed_at_date 或在 deprecated_aliases 中
deprecation-mismatch	文档	错误	模块在文件名、其元数据或 DOCUMENTATION 中至少一个地方被标记为已弃用或已移除（为弃用设置 DOCUMENTATION.deprecated 或为已移除删除所有文档），但在所有三个地方都不是。
doc-choices-do-not-match-spec	文档	错误	argument_spec 中“choices”的值与文档不匹配
doc-choices-incompatible-type	文档	错误	文档中的 Choices 值与 argument_spec 中定义的类型不兼容
doc-default-does-not-match-spec	文档	错误	argument_spec 中“default”的值与文档不匹配
doc-default-incompatible-type	文档	错误	文档中的默认值与 argument_spec 中定义的类型不兼容
doc-elements-invalid	文档	错误	文档为参数指定了元素，而“type”不是 list。
doc-elements-mismatch	文档	错误	Argument_spec 定义的元素与文档不同
doc-missing-type	文档	错误	文档未指定类型，但 argument_spec 中的参数使用默认类型（str）
doc-required-mismatch	文档	错误	argument_spec 中的参数是必需的，但文档说不是，反之亦然
doc-type-does-not-match-spec	文档	错误	Argument_spec 定义的类型与文档不同
documentation-error	文档	错误	未知的 DOCUMENTATION 错误
documentation-syntax-error	文档	错误	无效的 DOCUMENTATION 模式
import-before-documentation	导入	错误	在文档变量之前发现导入。所有导入都必须出现在 DOCUMENTATION/EXAMPLES/RETURN 之后
import-error	文档	错误	尝试为 argument_spec 自省导入模块时发生 Exception
attributes-check-mode	文档	错误	如果模块记录了 check_mode 属性，则其 support 值必须与 AnsibleModule 的 supports_check_mode 参数兼容
attributes-check-mode-details	文档	错误	如果模块使用支持值 partial 或 N/A 记录了 check_mode 属性，则它必须提供 details
import-placement	位置	警告	导入应该直接位于 DOCUMENTATION/EXAMPLES/RETURN 之后
imports-improper-location	导入	错误	导入应该直接位于 DOCUMENTATION/EXAMPLES/RETURN 之后
incompatible-choices	文档	错误	argument_spec 中的 Choices 值与 argument_spec 中定义的类型不兼容
incompatible-default-type	文档	错误	argument_spec 中的默认值与 argument_spec 中定义的类型不兼容
invalid-argument-name	文档	错误	argument_spec 中的参数不能是 'message'、'syslog_facility'，因为它们由 Ansible Core Engine 内部使用
invalid-argument-spec	文档	错误	使用时，argument_spec 中的参数必须是字典/哈希
invalid-argument-spec-options	文档	错误	argument_spec 中的子选项无效
invalid-documentation	文档	错误	DOCUMENTATION 不是有效的 YAML
invalid-documentation-markup	文档	错误	DOCUMENTATION 或 RETURN 包含无效的标记
invalid-documentation-options	文档	错误	DOCUMENTATION.options 使用时必须是字典/哈希
invalid-examples	文档	错误	EXAMPLES 不是有效的 YAML
invalid-extension	命名	错误	正式的 Ansible 模块必须对 python 模块使用 .py 扩展名，对 powershell 模块使用 .ps1 扩展名
invalid-module-schema	文档	错误	AnsibleModule 模式验证错误
invalid-removal-version	文档	错误	无法解析应该移除功能的版本（对于集合，它必须是 语义版本）
invalid-requires-extension	命名	错误	模块 #AnsibleRequires -CSharpUtil 不应该以 .cs 结尾，模块 #Requires 不应该以 .psm1 结尾
missing-doc-fragment	文档	错误	DOCUMENTATION 片段缺失
missing-existing-doc-fragment	文档	警告	预先存在的 DOCUMENTATION 片段缺失
missing-documentation	文档	错误	未提供 DOCUMENTATION
missing-examples	文档	错误	未提供 EXAMPLES
缺少 GPLv3 许可证	文档	错误	未找到 GPLv3 许可证头
缺少 module_utils.basic 模块导入	导入	警告	未找到 ansible.module_utils.basic 导入
缺少 module_utils C# 导入	导入	错误	未找到 Ansible.ModuleUtils 或 C# Ansible 工具的依赖项/导入
缺少 PowerShell 解释器	语法	错误	解释器行不是 #!powershell
缺少 Python 解释器	语法	错误	解释器行不是 #!/usr/bin/python
缺少返回值	文档	错误	未提供 RETURN 文档
缺少旧版模块的返回值	文档	警告	未为旧版模块提供 RETURN 文档
缺少子选项文档	文档	错误	argument_spec 中的参数包含子选项，但文档未定义子选项
模块 version_added 版本不正确	文档	错误	模块级别的 version_added 不正确
模块 version_added 版本无效	文档	错误	模块级别的 version_added 不是有效的版本号
module_utils 模块导入方式不规范	导入	错误	module_utils 导入应导入特定组件，而不是使用 *
requires 中包含多个工具模块	导入	错误	Ansible.ModuleUtils 依赖项不支持每个语句包含多个模块
requires 中包含多个 C# 工具模块	导入	错误	Ansible C# 工具依赖项不支持每个语句包含多个工具
必填参数没有默认值	文档	错误	选项标记为必填，但指定了默认值。带有默认值的选项不应标记为必填
不需要日志记录	参数	错误	选项名称表明该选项包含敏感值，但 argument_spec 中未为该选项指定 no_log。如果这是一个误报，请显式设置 no_log=False
文档中存在不存在的参数	文档	错误	参数在 DOCUMENTATION.options 中列出，但模块不接受
选项 version_added 版本不正确	文档	错误	新选项的 version_added 不正确
选项 version_added 版本无效	文档	错误	选项的 version_added 不是有效的版本号
参数无效	文档	错误	argument_spec 中的参数不是有效的 Python 标识符
参数 elements 属性无效	文档	错误	只有当 “type” 的值为 list 时，“elements” 的值才有效
参数类型不匹配	文档	错误	Argument_spec 推断 type="str"，但文档将其定义为不同的数据类型
文档中缺少参数类型	文档	错误	argument_spec 中定义了 Type 值，但文档未指定类型
参数别名重复	参数	错误	argument_spec 中的参数在 aliases 中至少指定了一个重复的别名
参数自身作为其别名	参数	错误	argument_spec 中的参数被指定为其自身的别名
参数文档重复	文档	错误	带有别名的 argument_spec 中的参数被多次记录
列表参数缺少 elements 属性	参数	错误	argument_spec 中 “type” 指定为 list 但未定义 “elements”
state 参数选项无效	参数	错误	参数 state 包含 get、list 或 info 作为选项。此功能应位于 _info 或（如果适用其他条件）_facts 模块中。
Python 语法错误	语法	错误	解析模块时出现 Python SyntaxError
移除版本必须为主版本	文档	错误	根据语义版本控制规范 (https://semver.org/)，仅允许在主版本 (x.0.0) 中移除功能
返回值语法错误	文档	错误	RETURN 不是有效的 YAML，RETURN 片段丢失或无效
返回值 version_added 版本无效	文档	错误	version_added for return value is not a valid version number
子目录缺少 __init__.py 文件	命名	错误	Ansible 模块子目录必须包含 __init__.py
缺少 try/except HAS 表达式	导入	警告	缺少 Try/Except HAS_ 表达式
参数未记录	文档	错误	参数在 argument_spec 中列出，但在模块中未记录
类型检查不规范	语法	错误	发现使用 type() 进行类型比较。请改用 isinstance()
未知文档片段	文档	警告	未知的现有 DOCUMENTATION 错误
使用 boto3	导入	错误	发现 boto 导入，新模块应使用 boto3
使用 fail_json 而非 sys.exit	导入	错误	发现 sys.exit() 调用。应使用 exit_json/fail_json
使用 ansible.module_utils.urls	导入	错误	发现 requests 导入，应使用 ansible.module_utils.urls 代替
使用 module.run_command 而非 os.call	导入	错误	使用 os.call 代替 module.run_command
使用 module.run_command 而非 subprocess.Popen	导入	错误	使用 subprocess.Popen 代替 module.run_command
使用简短的 GPLv3 许可证	文档	错误	新模块的 GPLv3 许可证头应使用 简短形式
mutually_exclusive 类型错误	文档	错误	mutually_exclusive 条目包含非字符串值
mutually_exclusive 条目中存在重复项	文档	错误	mutually_exclusive 条目包含重复的术语
mutually_exclusive 条目中存在未知选项	文档	错误	mutually_exclusive 条目包含未出现在 argument_spec 中的选项（可能是选项的别名？）
required_one_of 类型错误	文档	错误	required_one_of 条目包含非字符串值
required_one_of 条目中存在重复项	文档	错误	required_one_of 条目包含重复的术语
required_one_of 条目中存在未知选项	文档	错误	required_one_of 条目包含未出现在 argument_spec 中的选项（可能是选项的别名？）
required_together 类型错误	文档	错误	required_together 条目包含非字符串值
required_together 条目中存在重复项	文档	错误	required_together 条目包含重复的术语
required_together 条目中存在未知选项	文档	错误	required_together 条目包含未出现在 argument_spec 中的选项（可能是选项的别名？）
required_if is_one_of 类型错误	文档	错误	required_if 条目的第四个值不是布尔值
required_if 依赖项类型错误	文档	错误	required_if 条目的第三个值（依赖项）不是列表或元组
required_if 依赖项中存在重复项	文档	错误	required_if 条目的依赖项中包含重复的术语
required_if 依赖项中存在未知选项	文档	错误	required_if 条目的依赖项包含未出现在 argument_spec 中的选项（可能是选项的别名？）
required_if 中存在未知键	文档	错误	required_if 条目的键未出现在 argument_spec 中（可能是选项的别名？）
required_if 键存在于依赖项中	文档	错误	required_if 条目在其依赖项列表/元组中包含其键
required_if 值类型错误	文档	错误	required_if 条目的值与其键指定的类型不匹配
required_by 条目中存在重复项	文档	错误	required_by 条目包含重复的术语
required_by 条目中存在未知选项	文档	错误	required_by 条目包含未出现在 argument_spec 中的选项（可能是选项的别名？）
version_added 必须为主版本或次版本	文档	错误	根据语义版本控制规范 (https://semver.org/)，仅允许在主版本和次版本 (x.y.0) 中添加功能