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

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 文档

missing-suboption-docs

文档

错误

argument_spec 中的参数具有子选项，但文档未定义子选项

module-incorrect-version-added

文档

错误

模块级别的 version_added 不正确

module-invalid-version-added

文档

错误

模块级别的 version_added 不是有效的版本号

module-utils-specific-import

导入

错误

module_utils 导入应导入特定组件，而不是 *

multiple-utils-per-requires

导入

错误

Ansible.ModuleUtils 需求不支持每个语句多个模块

multiple-csharp-utils-per-requires

导入

错误

Ansible C# 实用程序需求不支持每个语句多个实用程序

no-default-for-required-parameter

文档

错误

选项标记为必需，但指定了默认值。具有默认值的参数不应标记为必需

no-log-needed

参数

错误

选项名称暗示该选项包含秘密值，而参数规范中未为该选项指定no_log。如果这是一个误报，请显式设置no_log=False

不存在的参数文档

文档

错误

参数列在DOCUMENTATION.options中，但模块不接受

选项版本添加错误

文档

错误

新选项的version_added不正确

选项版本添加无效

文档

错误

选项的version_added不是有效的版本号

参数无效

文档

错误

argument_spec中的参数不是有效的Python标识符

参数元素无效

文档

错误

只有当“type”的值为list时，“elements”的值才有效

隐含参数类型不匹配

文档

错误

Argument_spec暗示type="str"，但文档将其定义为不同的数据类型

参数类型未在文档中

文档

错误

argument_spec中定义了Type值，但文档未指定类型

参数别名重复

参数

错误

argument_spec中的参数在aliases中至少有一个别名被多次指定

参数别名自身

参数

错误

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__.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条目包含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中未出现的选项（可能是选项的别名？）

版本添加必须为主版本或次版本

文档

错误

根据语义版本控制规范（https://semver.org/），允许添加功能的版本只有主版本和次版本 (x.y.0)