Ansible核心文档

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核心引擎内部使用
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`
缺少Python解释器	语法	错误	解释器行不是`#!/usr/bin/python`
缺少返回值	文档	错误	未提供`RETURN`文档
缺少旧版返回值	文档	警告	未提供旧版模块的`RETURN`文档
缺少子选项文档	文档	错误	argument_spec中的参数包含子选项，但文档未定义子选项
模块版本添加错误	文档	错误	模块级别的`version_added`不正确
模块版本添加无效	文档	错误	模块级别的`version_added`不是有效的版本号
模块实用程序特定导入	导入	错误	`module_utils`导入应导入特定组件，而不是`*`
每个requires有多个实用程序	导入	错误	`Ansible.ModuleUtils`需求不支持每个语句多个模块
每个requires有多个C#实用程序	导入	错误	Ansible C#实用程序需求不支持每个语句多个实用程序
必需参数缺少默认值	文档	错误	选项标记为必需，但指定了默认值。具有默认值的参数不应标记为必需
无需日志记录	参数	错误	选项名称表明该选项包含秘密值，而参数规范中未为此选项指定`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中的参数在别名中至少指定了一个重复的别名
参数自身作为别名	参数	错误	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` for return value is not a valid version number
子目录缺少__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冲突	文档	错误	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)