validate-modules

Analyze modules for common issues in code and documentation.

Usage

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

Help

Type ansible-test sanity --test validate-modules -h to display help for using this sanity test.

Extending validate-modules

The validate-modules tool has a schema.py that is used to validate the YAML blocks, such as DOCUMENTATION and RETURNS.

Codes

Error Code

Type

Level

Sample Message

ansible-deprecated-module

Documentation

Error

A module is deprecated and supposed to be removed in the current or an earlier Ansible version

collection-deprecated-module

Documentation

Error

A module is deprecated and supposed to be removed in the current or an earlier collection version

ansible-deprecated-version

Documentation

Error

A feature is deprecated and supposed to be removed in the current or an earlier Ansible version

ansible-module-not-initialized

Syntax

Error

Execution of the module did not result in initialization of AnsibleModule

collection-deprecated-version

Documentation

Error

A feature is deprecated and supposed to be removed in the current or an earlier collection version

deprecated-date

Documentation

Error

A date before today appears as removed_at_date or in deprecated_aliases

deprecation-mismatch

Documentation

Error

Module marked as deprecated or removed in at least one of the filename, its metadata, or in DOCUMENTATION (setting DOCUMENTATION.deprecated for deprecation or removing all Documentation for removed) but not in all three places.

doc-choices-do-not-match-spec

Documentation

Error

Value for “choices” from the argument_spec does not match the documentation

doc-choices-incompatible-type

Documentation

Error

Choices value from the documentation is not compatible with type defined in the argument_spec

doc-default-does-not-match-spec

Documentation

Error

Value for “default” from the argument_spec does not match the documentation

doc-default-incompatible-type

Documentation

Error

Default value from the documentation is not compatible with type defined in the argument_spec

doc-elements-invalid

Documentation

Error

Documentation specifies elements for argument, when “type” is not list.

doc-elements-mismatch

Documentation

Error

Argument_spec defines elements different than documentation does

doc-missing-type

Documentation

Error

Documentation doesn’t specify a type but argument in argument_spec use default type (str)

doc-required-mismatch

Documentation

Error

argument in argument_spec is required but documentation says it is not, or vice versa

doc-type-does-not-match-spec

Documentation

Error

Argument_spec defines type different than documentation does

documentation-error

Documentation

Error

Unknown DOCUMENTATION error

documentation-syntax-error

Documentation

Error

Invalid DOCUMENTATION schema

import-before-documentation

Imports

Error

Import found before documentation variables. All imports must appear below DOCUMENTATION/EXAMPLES/RETURN

import-error

Documentation

Error

Exception attempting to import module for argument_spec introspection

attributes-check-mode

Documentation

Error

If a module documents the check_mode attribute, its support value must be compatible with the supports_check_mode parameter of AnsibleModule

attributes-check-mode-details

Documentation

Error

If a module documents the check_mode attribute with support values partial or N/A, it must provide details

import-placement

Locations

Warning

Imports should be directly below DOCUMENTATION/EXAMPLES/RETURN

imports-improper-location

Imports

Error

Imports should be directly below DOCUMENTATION/EXAMPLES/RETURN

incompatible-choices

Documentation

Error

Choices value from the argument_spec is not compatible with type defined in the argument_spec

incompatible-default-type

Documentation

Error

Default value from the argument_spec is not compatible with type defined in the argument_spec

invalid-argument-name

Documentation

Error

Argument in argument_spec must not be one of ‘message’, ‘syslog_facility’ as it is used internally by Ansible Core Engine

invalid-argument-spec

Documentation

Error

Argument in argument_spec must be a dictionary/hash when used

invalid-argument-spec-options

Documentation

Error

Suboptions in argument_spec are invalid

invalid-documentation

Documentation

Error

DOCUMENTATION is not valid YAML

invalid-documentation-markup

Documentation

Error

DOCUMENTATION or RETURN contains invalid markup

invalid-documentation-options

Documentation

Error

DOCUMENTATION.options must be a dictionary/hash when used

invalid-examples

Documentation

Error

EXAMPLES is not valid YAML

invalid-extension

Naming

Error

Official Ansible modules must have a .py extension for python modules or a .ps1 for powershell modules

invalid-module-schema

Documentation

Error

AnsibleModule schema validation error

invalid-removal-version

Documentation

Error

The version at which a feature is supposed to be removed cannot be parsed (for collections, it must be a semantic version)

invalid-requires-extension

Naming

Error

Module #AnsibleRequires -CSharpUtil should not end in .cs, Module #Requires should not end in .psm1

missing-doc-fragment

Documentation

Error

DOCUMENTATION fragment missing

missing-existing-doc-fragment

Documentation

Warning

Pre-existing DOCUMENTATION fragment missing

missing-documentation

Documentation

Error

No DOCUMENTATION provided

missing-examples

Documentation

Error

No EXAMPLES provided

missing-gplv3-license

Documentation

Error

GPLv3 license header not found

missing-module-utils-basic-import

Imports

Warning

Did not find ansible.module_utils.basic import

missing-module-utils-import-csharp-requirements

Imports

Error

No Ansible.ModuleUtils or C# Ansible util requirements/imports found

missing-powershell-interpreter

Syntax

Error

Interpreter line is not #!powershell

missing-python-interpreter

Syntax

Error

Interpreter line is not #!/usr/bin/python

missing-return

Documentation

Error

No RETURN documentation provided

missing-return-legacy

Documentation

Warning

No RETURN documentation provided for legacy module

missing-suboption-docs

Documentation

Error

Argument in argument_spec has sub-options but documentation does not define sub-options

module-incorrect-version-added

Documentation

Error

Module level version_added is incorrect

module-invalid-version-added

Documentation

Error

Module level version_added is not a valid version number

module-utils-specific-import

Imports

Error

module_utils imports should import specific components, not *

multiple-utils-per-requires

Imports

Error

Ansible.ModuleUtils requirements do not support multiple modules per statement

multiple-csharp-utils-per-requires

Imports

Error

Ansible C# util requirements do not support multiple utils per statement

no-default-for-required-parameter

Documentation

Error

Option is marked as required but specifies a default. Arguments with a default should not be marked as required

no-log-needed

Parameters

Error

Option name suggests that the option contains a secret value, while no_log is not specified for this option in the argument spec. If this is a false positive, explicitly set no_log=False

nonexistent-parameter-documented

Documentation

Error

Argument is listed in DOCUMENTATION.options, but not accepted by the module

option-incorrect-version-added

Documentation

Error

version_added for new option is incorrect

option-invalid-version-added

Documentation

Error

version_added for option is not a valid version number

parameter-invalid

Documentation

Error

Argument in argument_spec is not a valid python identifier

parameter-invalid-elements

Documentation

Error

Value for “elements” is valid only when value of “type” is list

implied-parameter-type-mismatch

Documentation

Error

Argument_spec implies type="str" but documentation defines it as different data type

parameter-type-not-in-doc

Documentation

Error

Type value is defined in argument_spec but documentation doesn’t specify a type

parameter-alias-repeated

Parameters

Error

argument in argument_spec has at least one alias specified multiple times in aliases

parameter-alias-self

Parameters

Error

argument in argument_spec is specified as its own alias

parameter-documented-multiple-times

Documentation

Error

argument in argument_spec with aliases is documented multiple times

parameter-list-no-elements

Parameters

Error

argument in argument_spec “type” is specified as list without defining “elements”

parameter-state-invalid-choice

Parameters

Error

Argument state includes get, list or info as a choice. Functionality should be in an _info or (if further conditions apply) _facts module.

python-syntax-error

Syntax

Error

Python SyntaxError while parsing module

removal-version-must-be-major

Documentation

Error

According to the semantic versioning specification (https://semver.org/), the only versions in which features are allowed to be removed are major versions (x.0.0)

return-syntax-error

Documentation

Error

RETURN is not valid YAML, RETURN fragments missing or invalid

return-invalid-version-added

Documentation

Error

version_added for return value is not a valid version number

subdirectory-missing-init

Naming

Error

Ansible module subdirectories must contain an __init__.py

try-except-missing-has

Imports

Warning

Try/Except HAS_ expression missing

undocumented-parameter

Documentation

Error

Argument is listed in the argument_spec, but not documented in the module

unidiomatic-typecheck

Syntax

Error

Type comparison using type() found. Use isinstance() instead

unknown-doc-fragment

Documentation

Warning

Unknown pre-existing DOCUMENTATION error

use-boto3

Imports

Error

boto import found, new modules should use boto3

use-fail-json-not-sys-exit

Imports

Error

sys.exit() call found. Should be exit_json/fail_json

use-module-utils-urls

Imports

Error

requests import found, should use ansible.module_utils.urls instead

use-run-command-not-os-call

Imports

Error

os.call used instead of module.run_command

use-run-command-not-popen

Imports

Error

subprocess.Popen used instead of module.run_command

use-short-gplv3-license

Documentation

Error

GPLv3 license header should be the short form for new modules

mutually_exclusive-type

Documentation

Error

mutually_exclusive entry contains non-string value

mutually_exclusive-collision

Documentation

Error

mutually_exclusive entry has repeated terms

mutually_exclusive-unknown

Documentation

Error

mutually_exclusive entry contains option which does not appear in argument_spec (potentially an alias of an option?)

required_one_of-type

Documentation

Error

required_one_of entry contains non-string value

required_one_of-collision

Documentation

Error

required_one_of entry has repeated terms

required_one_of-unknown

Documentation

Error

required_one_of entry contains option which does not appear in argument_spec (potentially an alias of an option?)

required_together-type

Documentation

Error

required_together entry contains non-string value

required_together-collision

Documentation

Error

required_together entry has repeated terms

required_together-unknown

Documentation

Error

required_together entry contains option which does not appear in argument_spec (potentially an alias of an option?)

required_if-is_one_of-type

Documentation

Error

required_if entry has a fourth value which is not a bool

required_if-requirements-type

Documentation

Error

required_if entry has a third value (requirements) which is not a list or tuple

required_if-requirements-collision

Documentation

Error

required_if entry has repeated terms in requirements

required_if-requirements-unknown

Documentation

Error

required_if entry’s requirements contains option which does not appear in argument_spec (potentially an alias of an option?)

required_if-unknown-key

Documentation

Error

required_if entry’s key does not appear in argument_spec (potentially an alias of an option?)

required_if-key-in-requirements

Documentation

Error

required_if entry contains its key in requirements list/tuple

required_if-value-type

Documentation

Error

required_if entry’s value is not of the type specified for its key

required_by-collision

Documentation

Error

required_by entry has repeated terms

required_by-unknown

Documentation

Error

required_by entry contains option which does not appear in argument_spec (potentially an alias of an option?)

version-added-must-be-major-or-minor

Documentation

Error

According to the semantic versioning specification (https://semver.org/), the only versions in which features are allowed to be added are major and minor versions (x.y.0)