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 用于弃用或删除所有 Documentation 用于删除）标记为已弃用或已删除，但并非在所有三个位置都标记。
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
missing-gplv3-license	文档	错误	未找到 GPLv3 许可头
missing-module-utils-basic-import	导入	警告	未找到 ansible.module_utils.basic 导入
missing-module-utils-import-csharp-requirements	导入	错误	未找到 Ansible.ModuleUtils 或 C# Ansible 实用工具的要求/导入
missing-powershell-interpreter	语法	错误	解释器行不是 #!powershell
missing-python-interpreter	语法	错误	解释器行不是 #!/usr/bin/python
missing-return	文档	错误	未提供 RETURN 文档
missing-return-legacy	文档	警告	遗留模块没有提供 RETURN 文档。
缺少子选项文档。	文档	错误	argument_spec 中的参数有子选项，但文档未定义子选项。
模块级别添加的版本号不正确。	文档	错误	模块级别的 version_added 不正确。
模块级别的添加版本号无效。	文档	错误	模块级别的 version_added 不是有效的版本号。
模块实用程序特定导入。	导入	错误	module_utils 导入应该导入特定的组件，而不是 *。
每个 requirements 有多个实用程序。	导入	错误	Ansible.ModuleUtils requirements 不支持每个语句有多个模块。
每个 requirements 有多个 C# 实用程序。	导入	错误	Ansible C# 实用程序 requirements 不支持每个语句有多个实用程序。
必需参数没有默认值。	文档	错误	选项被标记为必需，但指定了默认值。有默认值的参数不应标记为必需。
不需要日志。	参数。	错误	选项名称暗示该选项包含一个秘密值，而 argument spec 中没有为此选项指定 no_log。如果这是误报，请显式设置 no_log=False。
文档中记录了不存在的参数。	文档	错误	参数在 DOCUMENTATION.options 中列出，但模块不接受它。
新选项添加的版本号不正确。	文档	错误	新选项的 version_added 不正确。
选项的添加版本号无效。	文档	错误	选项的 version_added 不是有效的版本号。
参数无效。	文档	错误	argument_spec 中的参数不是有效的 Python 标识符。
参数元素无效。	文档	错误	只有当“type”的值为 list 时，“elements”的值才有效。
隐含的参数类型不匹配。	文档	错误	Argument_spec 暗示 type="str"，但文档将其定义为不同的数据类型。
文档中没有参数类型。	文档	错误	Type 值在 argument_spec 中定义，但文档没有指定类型。
参数别名重复。	参数。	错误	argument_spec 中的参数在别名中至少重复指定了一次。
参数别名是自身。	参数。	错误	argument_spec 中的参数被指定为其自身的别名。
参数多次记录在文档中。	文档	错误	带有别名的 argument_spec 中的参数被多次记录在文档中。
列表参数没有元素。	参数。	错误	argument_spec 中 “type” 被指定为 list 而没有定义“elements”。
参数状态无效选择。	参数。	错误	参数 state 包括 get、list 或 info 作为选择。功能应该在 _info 中，或者（如果适用其他条件）_facts 模块中。
Python 语法错误。	语法	错误	解析模块时出现 Python SyntaxError。
删除的版本必须是主版本。	文档	错误	根据语义版本规范 (https://semver.org/)，允许删除功能的唯一版本是主版本 (x.0.0)。
返回语法错误。	文档	错误	RETURN 不是有效的 YAML，RETURN 片段缺失或无效。
返回值的添加版本号无效。	文档	错误	返回值的 version_added 不是有效的版本号。
子目录缺少 init 文件。	命名	错误	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。
使用 module_utils.urls。	导入	错误	发现导入了 requests，应该使用 ansible.module_utils.urls 代替。
使用 run_command 而不是 os.call。	导入	错误	使用了 os.call 而不是 module.run_command。
使用 run_command 而不是 popen。	导入	错误	使用了 subprocess.Popen 而不是 module.run_command。
使用简短的 GPLv3 许可证。	文档	错误	新模块的 GPLv3 许可证头应该使用简短形式。
互斥类型。	文档	错误	mutually_exclusive 条目包含非字符串值。
互斥冲突。	文档	错误	mutually_exclusive 条目有重复的项。
互斥未知。	文档	错误	mutually_exclusive 条目包含在 argument_spec 中没有出现的选项（可能是选项的别名？）。
必须选择其中一个类型。	文档	错误	required_one_of 条目包含非字符串值。
必须选择其中一个冲突。	文档	错误	required_one_of 条目有重复的项。
必须选择其中一个未知。	文档	错误	required_one_of 条目包含在 argument_spec 中没有出现的选项（可能是选项的别名？）。
必须一起类型。	文档	错误	required_together 条目包含非字符串值。
必须一起冲突。	文档	错误	required_together 条目有重复的项。
必须一起未知。	文档	错误	required_together 条目包含在 argument_spec 中没有出现的选项（可能是选项的别名？）。
required_if is_one_of 类型。	文档	错误	required_if 条目有第四个值，它不是布尔值。
required_if requirements 类型。	文档	错误	required_if 条目有第三个值（requirements），它不是列表或元组。
required_if requirements 冲突。	文档	错误	required_if 条目的 requirements 中有重复的项。
required_if requirements 未知。	文档	错误	required_if 条目的 requirements 中包含在 argument_spec 中没有出现的选项（可能是选项的别名？）。
required_if 未知键。	文档	错误	required_if 条目的键在 argument_spec 中没有出现（可能是选项的别名？）。
required_if 键在 requirements 中。	文档	错误	required_if 条目的 requirements 列表/元组中包含其键。
required_if 值类型。	文档	错误	required_if 条目的值不是为其键指定的值类型。
必须由冲突引起。	文档	错误	required_by 条目有重复的项。
必须由未知引起。	文档	错误	required_by 条目包含在 argument_spec 中没有出现的选项（可能是选项的别名？）。
添加的版本必须是主版本或次版本。	文档	错误	根据语义版本规范 (https://semver.org/)，允许添加功能的唯一版本是主版本和次版本 (x.y.0)。