cmueller/ansible
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

validate-modules - Use error codes instead of numbers (#60711)

Browse source
This commit is contained in:
Sam Doran 2019-08-28 17:12:56 -04:00 committed by Matt Clay
parent af01cb114c
commit 73248bf27d
6 changed files with 4297 additions and 4353 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
changelogs/fragments/validate-modules-change-error-codes.yaml Normal file
View file

@ -0,0 +1,2 @@
minor_changes:
- validate-modules - change numeric error codes to descriptive strings (https://github.com/ansible/ansible/pull/60711)

187
docs/docsite/rst/dev_guide/testing_validate-modules.rst
View file

@ -58,115 +58,78 @@ The ``validate-modules`` tool has a `schema.py <https://github.com/ansible/ansib
Codes Codes
===== =====
Errors ============================================================ ================== ==================== =========================================================================================
------ **Error Code** **Type** **Level** **Sample Message**
------------------------------------------------------------ ------------------ -------------------- -----------------------------------------------------------------------------------------
========= =================== 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.
code sample message 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
**1xx** **Locations** doc-default-does-not-match-spec Documentation Error Value for "default" from the argument_spec does not match the documentation
101 Interpreter line is not ``#!/usr/bin/python`` doc-default-incompatible-type Documentation Error Default value from the documentation is not compatible with type defined in the argument_spec
102 Interpreter line is not ``#!powershell`` doc-missing-type Documentation Error Documentation doesn't specify a type but argument in ``argument_spec`` use default type (``str``)
103 Did not find a call to ``main()`` (or ``removed_module()`` in the case of deprecated & docs only modules) doc-type-does-not-match-spec Documentation Error Argument_spec defines type different than documentation does
104 Call to ``main()`` not the last line (or ``removed_module()`` in the case of deprecated & docs only modules) documentation-error Documentation Error Unknown ``DOCUMENTATION`` error
105 GPLv3 license header not found documentation-syntax-error Documentation Error Invalid ``DOCUMENTATION`` schema
106 Import found before documentation variables. All imports must appear below illegal-future-imports Imports Error Only the following ``from __future__`` imports are allowed: ``absolute_import``, ``division``, and ``print_function``.
``DOCUMENTATION``/``EXAMPLES``/``RETURN``/``ANSIBLE_METADATA`` import-before-documentation Imports Error Import found before documentation variables. All imports must appear below ``DOCUMENTATION``/``EXAMPLES``/``RETURN``/``ANSIBLE_METADATA``
107 Imports should be directly below ``DOCUMENTATION``/``EXAMPLES``/``RETURN``/``ANSIBLE_METADATA`` import-error Documentation Error ``Exception`` attempting to import module for ``argument_spec`` introspection
108 GPLv3 license header should be the :ref:`short form <copyright>` for new modules import-placement Locations Warning Imports should be directly below ``DOCUMENTATION``/``EXAMPLES``/``RETURN``/``ANSIBLE_METADATA`` for legacy modules
109 Next to last line is not ``if __name__ == "__main__":`` imports-improper-location Imports Error Imports should be directly below ``DOCUMENTATION``/``EXAMPLES``/``RETURN``/``ANSIBLE_METADATA``
.. 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
**2xx** **Imports** invalid-argument-spec Documentation Error Argument in argument_spec must be a dictionary/hash when used
201 Did not find a ``module_utils`` import invalid-argument-spec-options Documentation Error Suboptions in argument_spec are invalid
203 ``requests`` import found, should use ``ansible.module_utils.urls`` instead invalid-documentation Documentation Error ``DOCUMENTATION`` is not valid YAML
204 ``boto`` import found, new modules should use ``boto3`` invalid-documentation-options Documentation Error ``DOCUMENTATION.options`` must be a dictionary/hash when used
205 ``sys.exit()`` call found. Should be ``exit_json``/``fail_json`` invalid-examples Documentation Error ``EXAMPLES`` is not valid YAML
206 ``WANT_JSON`` not found in module invalid-extension Naming Error Official Ansible modules must have a ``.py`` extension for python modules or a ``.ps1`` for powershell modules
207 ``REPLACER_WINDOWS`` not found in module invalid-metadata-status Documentation Error ``ANSIBLE_METADATA.status`` of deprecated or removed can't include other statuses
208 ``module_utils`` imports should import specific components, not ``*`` invalid-metadata-type Documentation Error ``ANSIBLE_METADATA`` was not provided as a dict, YAML not supported, Invalid ``ANSIBLE_METADATA`` schema
209 Only the following ``from __future__`` imports are allowed: invalid-module-schema Documentation Error ``AnsibleModule`` schema validation error
``absolute_import``, ``division``, and ``print_function``. invalid-requires-extension Naming Error Module ``#AnsibleRequires -CSharpUtil`` should not end in .cs, Module ``#Requires`` should not end in .psm1
210 ``subprocess.Popen`` used instead of ``module.run_command`` last-line-main-call Syntax Error Call to ``main()`` not the last line (or ``removed_module()`` in the case of deprecated & docs only modules)
211 ``os.call`` used instead of ``module.run_command`` metadata-changed Documentation Error ``ANSIBLE_METADATA`` cannot be changed in a point release for a stable branch
.. missing-doc-fragment Documentation Error ``DOCUMENTATION`` fragment missing
--------- ------------------- missing-existing-doc-fragment Documentation Warning Pre-existing ``DOCUMENTATION`` fragment missing
**3xx** **Documentation** missing-documentation Documentation Error No ``DOCUMENTATION`` provided
301 No ``DOCUMENTATION`` provided missing-examples Documentation Error No ``EXAMPLES`` provided
302 ``DOCUMENTATION`` is not valid YAML missing-gplv3-license Documentation Error GPLv3 license header not found
303 ``DOCUMENTATION`` fragment missing missing-if-name-main Syntax Error Next to last line is not ``if __name__ == "__main__":``
304 Unknown ``DOCUMENTATION`` error missing-main-call Syntax Error Did not find a call to ``main()`` (or ``removed_module()`` in the case of deprecated & docs only modules)
305 Invalid ``DOCUMENTATION`` schema missing-metadata Documentation Error No ``ANSIBLE_METADATA`` provided
306 Module level ``version_added`` is not a valid version number missing-module-utils-basic-import Imports Warning Did not find ``ansible.module_utils.basic`` import
307 Module level ``version_added`` is incorrect missing-module-utils-import Imports Error Did not find a ``module_utils`` import
308 ``version_added`` for new option is not a valid version number missing-module-utils-import-c# Imports Error No ``Ansible.ModuleUtils`` or C# Ansible util requirements/imports found
309 ``version_added`` for new option is incorrect missing-powershell-interpreter Syntax Error Interpreter line is not ``#!powershell``
310 No ``EXAMPLES`` provided missing-python-doc Naming Error Missing python documentation file
311 ``EXAMPLES`` is not valid YAML missing-python-interpreter Syntax Error Interpreter line is not ``#!/usr/bin/python``
312 No ``RETURN`` documentation provided missing-return Documentation Error No ``RETURN`` documentation provided
313 ``RETURN`` is not valid YAML missing-return-legacy Documentation Warning No ``RETURN`` documentation provided for legacy module
314 No ``ANSIBLE_METADATA`` provided missing-subption-docs Documentation Error Argument in argument_spec has sub-options but documentation does not define sub-options
315 ``ANSIBLE_METADATA`` was not provided as a dict, YAML not supported module-incorrect-version-added Documentation Error Module level ``version_added`` is incorrect
316 Invalid ``ANSIBLE_METADATA`` schema module-invalid-version-added Documentation Error Module level ``version_added`` is not a valid version number
317 option is marked as required but specifies a default. module-utils-specific-import Imports Error ``module_utils`` imports should import specific components, not ``*``
Arguments with a default should not be marked as required multiple-utils-per-requires Imports Error ``Ansible.ModuleUtils`` requirements do not support multiple modules per statement
318 Module marked as deprecated or removed in at least one of the filename, its metadata, or multiple-c#-utils-per-requires Imports Error Ansible C# util requirements do not support multiple utils per statement
in DOCUMENTATION (setting DOCUMENTATION.deprecated for deprecation or removing all 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
documentation for removed) but not in all three places. nonexistent-parameter-documented Documentation Error Argument is listed in DOCUMENTATION.options, but not accepted by the module
319 ``RETURN`` fragments missing or invalid option-incorrect-version-added Documentation Error ``version_added`` for new option is incorrect
320 ``DOCUMENTATION.options`` must be a dictionary/hash when used option-invalid-version-added Documentation Error ``version_added`` for new option is not a valid version number
321 ``Exception`` attempting to import module for ``argument_spec`` introspection parameter-invalid Documentation Error Argument in argument_spec is not a valid python identifier
322 argument is listed in the argument_spec, but not documented in the module parameter-invalid-elements Documentation Error Value for "elements" is valid only when value of "type" is ``list``
323 argument is listed in DOCUMENTATION.options, but not accepted by the module implied-parameter-type-mismatch Documentation Error Argument_spec implies ``type="str"`` but documentation defines it as different data type
324 Value for "default" from the argument_spec does not match the documentation parameter-type-not-in-doc Documentation Error Type value is defined in ``argument_spec`` but documentation doesn't specify a type
325 argument_spec defines type different than documentation does python-syntax-error Syntax Error Python ``SyntaxError`` while parsing module
326 Value for "choices" from the argument_spec does not match the documentation return-syntax-error Documentation Error ``RETURN`` is not valid YAML, ``RETURN`` fragments missing or invalid
327 Default value from the documentation is not compatible with type defined in the argument_spec subdirectory-missing-init Naming Error Ansible module subdirectories must contain an ``__init__.py``
328 Choices value from the documentation is not compatible with type defined in the argument_spec try-except-missing-has Imports Warning Try/Except ``HAS_`` expression missing
329 Default value from the argument_spec is not compatible with type defined in the argument_spec undocumented-parameter Documentation Error Argument is listed in the argument_spec, but not documented in the module
330 Choices value from the argument_spec is not compatible with type defined in the argument_spec unidiomatic-typecheck Syntax Error Type comparison using ``type()`` found. Use ``isinstance()`` instead
331 argument in argument_spec must be a dictionary/hash when used unknown-doc-fragment Documentation Warning Unknown pre-existing ``DOCUMENTATION`` error
332 ``AnsibleModule`` schema validation error use-boto3 Imports Error ``boto`` import found, new modules should use ``boto3``
333 ``ANSIBLE_METADATA.status`` of deprecated or removed can't include other statuses use-fail-json-not-sys-exit Imports Error ``sys.exit()`` call found. Should be ``exit_json``/``fail_json``
334 ``ANSIBLE_METADATA`` cannot be changed in a point release for a stable branch use-module-utils-urls Imports Error ``requests`` import found, should use ``ansible.module_utils.urls`` instead
335 argument_spec implies type="str" but documentation defines it as different data type use-run-command-not-os-call Imports Error ``os.call`` used instead of ``module.run_command``
336 argument in argument_spec is not a valid python identifier use-run-command-not-popen Imports Error ``subprocess.Popen`` used instead of ``module.run_command``
337 Type value is defined in ``argument_spec`` but documentation doesn't specify a type use-short-gplv3-license Documentation Error GPLv3 license header should be the :ref:`short form <copyright>` for new modules
338 documentation doesn't specify a type but argument in ``argument_spec`` use default type (``str``) ============================================================ ================== ==================== =========================================================================================
339 Value for "elements" is valid only when value of "type" is ``list``
340 argument in argument_spec has sub-options but documentation does not define sub-options
..
--------- -------------------
**4xx** **Syntax**
401 Python ``SyntaxError`` while parsing module
403 Type comparison using ``type()`` found. Use ``isinstance()`` instead
..
--------- -------------------
**5xx** **Naming**
501 Official Ansible modules must have a ``.py`` extension for python
modules or a ``.ps1`` for powershell modules
502 Ansible module subdirectories must contain an ``__init__.py``
503 Missing python documentation file
========= ===================
Warnings
--------
========= ===================
code sample message
--------- -------------------
**1xx** **Locations**
107 Imports should be directly below ``DOCUMENTATION``/``EXAMPLES``/``RETURN``/``ANSIBLE_METADATA`` for legacy modules
..
--------- -------------------
**2xx** **Imports**
208 ``module_utils`` imports should import specific components for legacy module, not ``*``
291 Try/Except ``HAS_`` expression missing
292 Did not find ``ansible.module_utils.basic`` import
..
--------- -------------------
**3xx** **Documentation**
312 No ``RETURN`` documentation provided for legacy module
391 Unknown pre-existing ``DOCUMENTATION`` error
392 Pre-existing ``DOCUMENTATION`` fragment missing
========= ===================

177
test/lib/ansible_test/_data/sanity/validate-modules/validate_modules/main.py
View file

@ -68,7 +68,7 @@ BLACKLIST_IMPORTS = {
'requests': { 'requests': {
'new_only': True, 'new_only': True,
'error': { 'error': {
'code': 203, 'code': 'use-module-utils-urls',
'msg': ('requests import found, should use ' 'msg': ('requests import found, should use '
'ansible.module_utils.urls instead') 'ansible.module_utils.urls instead')
} }
@ -76,7 +76,7 @@ BLACKLIST_IMPORTS = {
r'boto(?:\.|$)': { r'boto(?:\.|$)': {
'new_only': True, 'new_only': True,
'error': { 'error': {
'code': 204, 'code': 'use-boto3',
'msg': 'boto import found, new modules should use boto3' 'msg': 'boto import found, new modules should use boto3'
} }
}, },
@ -354,7 +354,7 @@ class ModuleValidator(Validator):
if not self.text.startswith('#!powershell\n'): if not self.text.startswith('#!powershell\n'):
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=102, code='missing-powershell-interpreter',
msg='Interpreter line is not "#!powershell"' msg='Interpreter line is not "#!powershell"'
) )
return return
@ -362,8 +362,8 @@ class ModuleValidator(Validator):
if not self.text.startswith('#!/usr/bin/python'): if not self.text.startswith('#!/usr/bin/python'):
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=101, code='missing-python-interpreter',
msg='Interpreter line is not "#!/usr/bin/python"' msg='Interpreter line is not "#!/usr/bin/python"',
) )
def _check_type_instead_of_isinstance(self, powershell=False): def _check_type_instead_of_isinstance(self, powershell=False):
@ -375,7 +375,7 @@ class ModuleValidator(Validator):
# TODO: add column # TODO: add column
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=403, code='unidiomatic-typecheck',
msg=('Type comparison using type() found. ' msg=('Type comparison using type() found. '
'Use isinstance() instead'), 'Use isinstance() instead'),
line=line_no + 1 line=line_no + 1
@ -392,7 +392,7 @@ class ModuleValidator(Validator):
# TODO: add column # TODO: add column
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=205, code='use-fail-json-not-sys-exit',
msg='sys.exit() call found. Should be exit_json/fail_json', msg='sys.exit() call found. Should be exit_json/fail_json',
line=line_no + 1 line=line_no + 1
) )
@ -403,7 +403,7 @@ class ModuleValidator(Validator):
('version 3' not in header and 'v3.0' not in header)): ('version 3' not in header and 'v3.0' not in header)):
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=105, code='missing-gplv3-license',
msg='GPLv3 license header not found in the first 20 lines of the module' msg='GPLv3 license header not found in the first 20 lines of the module'
) )
elif self._is_new_module(): elif self._is_new_module():
@ -411,7 +411,7 @@ class ModuleValidator(Validator):
if 'GNU General Public License' in line]) > 1: if 'GNU General Public License' in line]) > 1:
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=108, code='use-short-gplv3-license',
msg='Found old style GPLv3 license header: ' msg='Found old style GPLv3 license header: '
'https://docs.ansible.com/ansible/devel/dev_guide/developing_modules_documenting.html#copyright' 'https://docs.ansible.com/ansible/devel/dev_guide/developing_modules_documenting.html#copyright'
) )
@ -425,7 +425,7 @@ class ModuleValidator(Validator):
if sp_match: if sp_match:
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=210, code='use-run-command-not-popen',
msg=('subprocess.Popen call found. Should be module.run_command'), msg=('subprocess.Popen call found. Should be module.run_command'),
line=(line_no + 1), line=(line_no + 1),
column=(sp_match.span()[0] + 1) column=(sp_match.span()[0] + 1)
@ -438,7 +438,7 @@ class ModuleValidator(Validator):
if os_call_match: if os_call_match:
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=211, code='use-run-command-not-os-call',
msg=('os.call() call found. Should be module.run_command'), msg=('os.call() call found. Should be module.run_command'),
line=(line_no + 1), line=(line_no + 1),
column=(os_call_match.span()[0] + 1) column=(os_call_match.span()[0] + 1)
@ -494,7 +494,7 @@ class ModuleValidator(Validator):
isinstance(name, ast.alias) and isinstance(name, ast.alias) and
name.name == '*'): name.name == '*'):
msg = ( msg = (
208, 'module-utils-specific-import',
('module_utils imports should import specific ' ('module_utils imports should import specific '
'components, not "*"') 'components, not "*"')
) )
@ -520,13 +520,13 @@ class ModuleValidator(Validator):
if not linenos: if not linenos:
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=201, code='missing-module-utils-import',
msg='Did not find a module_utils import' msg='Did not find a module_utils import'
) )
elif not found_basic: elif not found_basic:
self.reporter.warning( self.reporter.warning(
path=self.object_path, path=self.object_path,
code=292, code='missing-module-utils-basic-import',
msg='Did not find "ansible.module_utils.basic" import' msg='Did not find "ansible.module_utils.basic" import'
) )
@ -580,7 +580,7 @@ class ModuleValidator(Validator):
if not mainchecked: if not mainchecked:
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=109, code='missing-if-name-main',
msg='Next to last line should be: if __name__ == "__main__":', msg='Next to last line should be: if __name__ == "__main__":',
line=child.lineno line=child.lineno
) )
@ -594,7 +594,7 @@ class ModuleValidator(Validator):
if lineno < self.length - 1: if lineno < self.length - 1:
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=104, code='last-line-main-call',
msg=('Call to %s() not the last line' % look_for), msg=('Call to %s() not the last line' % look_for),
line=lineno line=lineno
) )
@ -602,7 +602,7 @@ class ModuleValidator(Validator):
if not lineno: if not lineno:
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=103, code='missing-main-call',
msg=('Did not find a call to %s()' % look_for) msg=('Did not find a call to %s()' % look_for)
) )
@ -627,7 +627,7 @@ class ModuleValidator(Validator):
# TODO: Add line/col # TODO: Add line/col
self.reporter.warning( self.reporter.warning(
path=self.object_path, path=self.object_path,
code=291, code='try-except-missing-has',
msg='Found Try/Except block without HAS_ assignment' msg='Found Try/Except block without HAS_ assignment'
) )
@ -654,7 +654,7 @@ class ModuleValidator(Validator):
if future_import.name not in self.WHITELIST_FUTURE_IMPORTS: if future_import.name not in self.WHITELIST_FUTURE_IMPORTS:
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=209, code='illegal-future-imports',
msg=('Only the following from __future__ imports are allowed: %s' msg=('Only the following from __future__ imports are allowed: %s'
% ', '.join(self.WHITELIST_FUTURE_IMPORTS)), % ', '.join(self.WHITELIST_FUTURE_IMPORTS)),
line=child.lineno line=child.lineno
@ -666,7 +666,7 @@ class ModuleValidator(Validator):
if child.lineno < min_doc_line: if child.lineno < min_doc_line:
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=106, code='import-before-documentation',
msg=('Import found before documentation variables. ' msg=('Import found before documentation variables. '
'All imports must appear below ' 'All imports must appear below '
'DOCUMENTATION/EXAMPLES/RETURN/ANSIBLE_METADATA.'), 'DOCUMENTATION/EXAMPLES/RETURN/ANSIBLE_METADATA.'),
@ -683,7 +683,7 @@ class ModuleValidator(Validator):
if grandchild.lineno < min_doc_line: if grandchild.lineno < min_doc_line:
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=106, code='import-before-documentation',
msg=('Import found before documentation ' msg=('Import found before documentation '
'variables. All imports must appear below ' 'variables. All imports must appear below '
'DOCUMENTATION/EXAMPLES/RETURN/' 'DOCUMENTATION/EXAMPLES/RETURN/'
@ -695,7 +695,7 @@ class ModuleValidator(Validator):
for import_line in import_lines: for import_line in import_lines:
if not (max_doc_line < import_line < first_callable): if not (max_doc_line < import_line < first_callable):
msg = ( msg = (
107, 'import-placement',
('Imports should be directly below DOCUMENTATION/EXAMPLES/' ('Imports should be directly below DOCUMENTATION/EXAMPLES/'
'RETURN/ANSIBLE_METADATA.') 'RETURN/ANSIBLE_METADATA.')
) )
@ -730,7 +730,7 @@ class ModuleValidator(Validator):
if len(module_list) > 1: if len(module_list) > 1:
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=210, code='multiple-utils-per-requires',
msg='Ansible.ModuleUtils requirements do not support multiple modules per statement: "%s"' % req_stmt.group(0) msg='Ansible.ModuleUtils requirements do not support multiple modules per statement: "%s"' % req_stmt.group(0)
) )
continue continue
@ -740,7 +740,7 @@ class ModuleValidator(Validator):
if module_name.lower().endswith('.psm1'): if module_name.lower().endswith('.psm1'):
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=211, code='invalid-requires-extension',
msg='Module #Requires should not end in .psm1: "%s"' % module_name msg='Module #Requires should not end in .psm1: "%s"' % module_name
) )
@ -751,7 +751,7 @@ class ModuleValidator(Validator):
if len(module_list) > 1: if len(module_list) > 1:
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=210, code='multiple-c#-utils-per-requires',
msg='Ansible C# util requirements do not support multiple utils per statement: "%s"' % req_stmt.group(0) msg='Ansible C# util requirements do not support multiple utils per statement: "%s"' % req_stmt.group(0)
) )
continue continue
@ -761,7 +761,7 @@ class ModuleValidator(Validator):
if module_name.lower().endswith('.cs'): if module_name.lower().endswith('.cs'):
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=211, code='illegal-extension-cs',
msg='Module #AnsibleRequires -CSharpUtil should not end in .cs: "%s"' % module_name msg='Module #AnsibleRequires -CSharpUtil should not end in .cs: "%s"' % module_name
) )
@ -769,7 +769,7 @@ class ModuleValidator(Validator):
if not found_requires and REPLACER_WINDOWS not in self.text: if not found_requires and REPLACER_WINDOWS not in self.text:
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=207, code='missing-module-utils-import-c#-requirements',
msg='No Ansible.ModuleUtils or C# Ansible util requirements/imports found' msg='No Ansible.ModuleUtils or C# Ansible util requirements/imports found'
) )
@ -780,7 +780,7 @@ class ModuleValidator(Validator):
if not os.path.isfile(py_path): if not os.path.isfile(py_path):
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=503, code='missing-python-doc',
msg='Missing python documentation file' msg='Missing python documentation file'
) )
return py_path return py_path
@ -897,7 +897,7 @@ class ModuleValidator(Validator):
if not bool(doc_info['ANSIBLE_METADATA']['value']): if not bool(doc_info['ANSIBLE_METADATA']['value']):
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=314, code='missing-metadata',
msg='No ANSIBLE_METADATA provided' msg='No ANSIBLE_METADATA provided'
) )
else: else:
@ -906,36 +906,15 @@ class ModuleValidator(Validator):
doc_info['ANSIBLE_METADATA']['value'] doc_info['ANSIBLE_METADATA']['value']
) )
else: else:
# ANSIBLE_METADATA doesn't properly support YAML
# we should consider removing it from the spec
# Below code kept, incase we change our minds
# metadata, errors, traces = parse_yaml(
# doc_info['ANSIBLE_METADATA']['value'].s,
# doc_info['ANSIBLE_METADATA']['lineno'],
# self.name, 'ANSIBLE_METADATA'
# )
# for error in errors:
# self.reporter.error(
# path=self.object_path,
# code=315,
# **error
# )
# for trace in traces:
# self.reporter.trace(
# path=self.object_path,
# tracebk=trace
# )
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=315, code='missing-metadata-format',
msg='ANSIBLE_METADATA was not provided as a dict, YAML not supported' msg='ANSIBLE_METADATA was not provided as a dict, YAML not supported'
) )
if metadata: if metadata:
self._validate_docs_schema(metadata, metadata_1_1_schema(), self._validate_docs_schema(metadata, metadata_1_1_schema(),
'ANSIBLE_METADATA', 316) 'ANSIBLE_METADATA', 'invalid-metadata-type')
# We could validate these via the schema if we knew what the values are ahead of # We could validate these via the schema if we knew what the values are ahead of
# time. We can figure that out for deprecated but we can't for removed. Only the # time. We can figure that out for deprecated but we can't for removed. Only the
# metadata has that information. # metadata has that information.
@ -946,7 +925,7 @@ class ModuleValidator(Validator):
if (deprecated or removed) and len(metadata['status']) > 1: if (deprecated or removed) and len(metadata['status']) > 1:
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=333, code='missing-metadata-status',
msg='ANSIBLE_METADATA.status must be exactly one of "deprecated" or "removed"' msg='ANSIBLE_METADATA.status must be exactly one of "deprecated" or "removed"'
) )
@ -954,7 +933,7 @@ class ModuleValidator(Validator):
if not bool(doc_info['DOCUMENTATION']['value']): if not bool(doc_info['DOCUMENTATION']['value']):
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=301, code='missing-documentation',
msg='No DOCUMENTATION provided' msg='No DOCUMENTATION provided'
) )
else: else:
@ -967,7 +946,7 @@ class ModuleValidator(Validator):
for error in errors: for error in errors:
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=302, code='documentation-syntax-error',
**error **error
) )
for trace in traces: for trace in traces:
@ -984,7 +963,7 @@ class ModuleValidator(Validator):
fragment = doc['extends_documentation_fragment'] fragment = doc['extends_documentation_fragment']
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=303, code='missing-doc-fragment',
msg='DOCUMENTATION fragment missing: %s' % fragment msg='DOCUMENTATION fragment missing: %s' % fragment
) )
missing_fragment = True missing_fragment = True
@ -995,7 +974,7 @@ class ModuleValidator(Validator):
) )
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=304, code='documentation-error',
msg='Unknown DOCUMENTATION error, see TRACE: %s' % e msg='Unknown DOCUMENTATION error, see TRACE: %s' % e
) )
@ -1005,7 +984,7 @@ class ModuleValidator(Validator):
if 'options' in doc and doc['options'] is None: if 'options' in doc and doc['options'] is None:
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=320, code='invalid-documentation-options',
msg='DOCUMENTATION.options must be a dictionary/hash when used', msg='DOCUMENTATION.options must be a dictionary/hash when used',
) )
@ -1024,7 +1003,7 @@ class ModuleValidator(Validator):
version_added=not bool(self.collection) version_added=not bool(self.collection)
), ),
'DOCUMENTATION', 'DOCUMENTATION',
305 'invalid-documentation',
) )
else: else:
# This is the normal case # This is the normal case
@ -1035,7 +1014,7 @@ class ModuleValidator(Validator):
version_added=not bool(self.collection) version_added=not bool(self.collection)
), ),
'DOCUMENTATION', 'DOCUMENTATION',
305 'invalid-documentation',
) )
if not self.collection: if not self.collection:
@ -1045,7 +1024,7 @@ class ModuleValidator(Validator):
if not bool(doc_info['EXAMPLES']['value']): if not bool(doc_info['EXAMPLES']['value']):
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=310, code='missing-examples',
msg='No EXAMPLES provided' msg='No EXAMPLES provided'
) )
else: else:
@ -1055,7 +1034,7 @@ class ModuleValidator(Validator):
for error in errors: for error in errors:
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=311, code='invalid-examples',
**error **error
) )
for trace in traces: for trace in traces:
@ -1068,25 +1047,25 @@ class ModuleValidator(Validator):
if self._is_new_module(): if self._is_new_module():
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=312, code='missing-return',
msg='No RETURN provided' msg='No RETURN provided'
) )
else: else:
self.reporter.warning( self.reporter.warning(
path=self.object_path, path=self.object_path,
code=312, code='missing-return-legacy',
msg='No RETURN provided' msg='No RETURN provided'
) )
else: else:
data, errors, traces = parse_yaml(doc_info['RETURN']['value'], data, errors, traces = parse_yaml(doc_info['RETURN']['value'],
doc_info['RETURN']['lineno'], doc_info['RETURN']['lineno'],
self.name, 'RETURN') self.name, 'RETURN')
self._validate_docs_schema(data, return_schema, 'RETURN', 319) self._validate_docs_schema(data, return_schema, 'RETURN', 'return-syntax-error')
for error in errors: for error in errors:
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=313, code='return-syntax-error',
**error **error
) )
for trace in traces: for trace in traces:
@ -1108,7 +1087,7 @@ class ModuleValidator(Validator):
if mismatched_deprecation: if mismatched_deprecation:
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=318, code='deprecation-mismatch',
msg='Module deprecation/removed must agree in Metadata, by prepending filename with' msg='Module deprecation/removed must agree in Metadata, by prepending filename with'
' "_", and setting DOCUMENTATION.deprecated for deprecation or by removing all' ' "_", and setting DOCUMENTATION.deprecated for deprecation or by removing all'
' documentation for removed' ' documentation for removed'
@ -1125,7 +1104,7 @@ class ModuleValidator(Validator):
if self._is_new_module() or version_added != 'historical': if self._is_new_module() or version_added != 'historical':
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=306, code='module-invalid-version-added',
msg='version_added is not a valid version number: %r' % version_added msg='version_added is not a valid version number: %r' % version_added
) )
return return
@ -1133,7 +1112,7 @@ class ModuleValidator(Validator):
if existing_doc and str(version_added_raw) != str(existing_doc.get('version_added')): if existing_doc and str(version_added_raw) != str(existing_doc.get('version_added')):
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=307, code='module-incorrect-version-added',
msg='version_added should be %r. Currently %r' % (existing_doc.get('version_added'), msg='version_added should be %r. Currently %r' % (existing_doc.get('version_added'),
version_added_raw) version_added_raw)
) )
@ -1148,7 +1127,7 @@ class ModuleValidator(Validator):
strict_ansible_version < version_added): strict_ansible_version < version_added):
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=307, code='module-incorrect-version-added',
msg='version_added should be %r. Currently %r' % (should_be, version_added_raw) msg='version_added should be %r. Currently %r' % (should_be, version_added_raw)
) )
@ -1158,7 +1137,7 @@ class ModuleValidator(Validator):
except AnsibleModuleImportError as e: except AnsibleModuleImportError as e:
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=321, code='import-error',
msg="Exception attempting to import module for argument_spec introspection, '%s'" % e msg="Exception attempting to import module for argument_spec introspection, '%s'" % e
) )
self.reporter.trace( self.reporter.trace(
@ -1167,7 +1146,7 @@ class ModuleValidator(Validator):
) )
return return
self._validate_docs_schema(kwargs, ansible_module_kwargs_schema, 'AnsibleModule', 332) self._validate_docs_schema(kwargs, ansible_module_kwargs_schema, 'AnsibleModule', 'invalid-ansiblemodule-schema')
self._validate_argument_spec(docs, spec, kwargs) self._validate_argument_spec(docs, spec, kwargs)
@ -1202,7 +1181,7 @@ class ModuleValidator(Validator):
msg += " must be a dictionary/hash when used" msg += " must be a dictionary/hash when used"
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=331, code='invalid-argument-spec',
msg=msg, msg=msg,
) )
continue continue
@ -1216,7 +1195,7 @@ class ModuleValidator(Validator):
if data.get('options') is not None and not isinstance(data.get('options'), Mapping): if data.get('options') is not None and not isinstance(data.get('options'), Mapping):
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=331, code='invalid-argument-spec-options',
msg="Argument 'options' in argument_spec['provider'] must be a dictionary/hash when used", msg="Argument 'options' in argument_spec['provider'] must be a dictionary/hash when used",
) )
elif data.get('options'): elif data.get('options'):
@ -1233,7 +1212,7 @@ class ModuleValidator(Validator):
" default should not be marked as required" " default should not be marked as required"
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=317, code='no-default-for-required-parameter',
msg=msg msg=msg
) )
@ -1259,7 +1238,7 @@ class ModuleValidator(Validator):
msg += " defines elements as %s but it is valid only when value of parameter type is list" % _elements msg += " defines elements as %s but it is valid only when value of parameter type is list" % _elements
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=339, code='parameter-invalid-elements',
msg=msg msg=msg
) )
@ -1275,7 +1254,7 @@ class ModuleValidator(Validator):
msg += " defines default as (%r) but this is incompatible with parameter type %r" % (data['default'], _type) msg += " defines default as (%r) but this is incompatible with parameter type %r" % (data['default'], _type)
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=329, code='incompatible-default-type',
msg=msg msg=msg
) )
continue continue
@ -1297,7 +1276,7 @@ class ModuleValidator(Validator):
msg += " defines default as (%r) but this is incompatible with parameter type %r" % (doc_options_arg.get('default'), _type) msg += " defines default as (%r) but this is incompatible with parameter type %r" % (doc_options_arg.get('default'), _type)
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=327, code='doc-default-incompatible-type',
msg=msg msg=msg
) )
continue continue
@ -1309,7 +1288,7 @@ class ModuleValidator(Validator):
msg += " defines default as (%r) but documentation defines default as (%r)" % (arg_default, doc_default) msg += " defines default as (%r) but documentation defines default as (%r)" % (arg_default, doc_default)
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=324, code='doc-default-does-not-match-spec',
msg=msg msg=msg
) )
@ -1323,7 +1302,7 @@ class ModuleValidator(Validator):
msg += " defines type as %r but documentation doesn't define type" % (data['type']) msg += " defines type as %r but documentation doesn't define type" % (data['type'])
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=337, code='parameter-type-not-in-doc',
msg=msg msg=msg
) )
elif data['type'] != doc_type: elif data['type'] != doc_type:
@ -1333,7 +1312,7 @@ class ModuleValidator(Validator):
msg += " defines type as %r but documentation defines type as %r" % (data['type'], doc_type) msg += " defines type as %r but documentation defines type as %r" % (data['type'], doc_type)
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=325, code='doc-type-does-not-match-spec',
msg=msg msg=msg
) )
else: else:
@ -1344,7 +1323,7 @@ class ModuleValidator(Validator):
msg += " uses default type ('str') but documentation doesn't define type" msg += " uses default type ('str') but documentation doesn't define type"
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=338, code='doc-missing-type',
msg=msg msg=msg
) )
elif doc_type != 'str': elif doc_type != 'str':
@ -1354,7 +1333,7 @@ class ModuleValidator(Validator):
msg += "implies type as 'str' but documentation defines as %r" % doc_type msg += "implies type as 'str' but documentation defines as %r" % doc_type
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=335, code='implied-parameter-type-mismatch',
msg=msg msg=msg
) )
@ -1371,7 +1350,7 @@ class ModuleValidator(Validator):
msg += " defines choices as (%r) but this is incompatible with argument type %r" % (choice, _type) msg += " defines choices as (%r) but this is incompatible with argument type %r" % (choice, _type)
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=328, code='doc-choices-incompatible-type',
msg=msg msg=msg
) )
raise StopIteration() raise StopIteration()
@ -1391,7 +1370,7 @@ class ModuleValidator(Validator):
msg += " defines choices as (%r) but this is incompatible with argument type %r" % (choice, _type) msg += " defines choices as (%r) but this is incompatible with argument type %r" % (choice, _type)
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=330, code='incompatible-choices',
msg=msg msg=msg
) )
raise StopIteration() raise StopIteration()
@ -1405,7 +1384,7 @@ class ModuleValidator(Validator):
msg += " defines choices as (%r) but documentation defines choices as (%r)" % (arg_choices, doc_choices) msg += " defines choices as (%r) but documentation defines choices as (%r)" % (arg_choices, doc_choices)
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=326, code='doc-choices-do-not-match-spec',
msg=msg msg=msg
) )
@ -1419,7 +1398,7 @@ class ModuleValidator(Validator):
msg += " has sub-options but documentation does not define it" msg += " has sub-options but documentation does not define it"
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=340, code='missing-subption-docs',
msg=msg msg=msg
) )
self._validate_argument_spec({'options': doc_suboptions}, spec_suboptions, kwargs, context=context + [arg]) self._validate_argument_spec({'options': doc_suboptions}, spec_suboptions, kwargs, context=context + [arg])
@ -1432,7 +1411,7 @@ class ModuleValidator(Validator):
msg += " is not a valid python identifier" msg += " is not a valid python identifier"
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=336, code='parameter-invalid',
msg=msg msg=msg
) )
@ -1464,7 +1443,7 @@ class ModuleValidator(Validator):
msg += " is listed in the argument_spec, but not documented in the module documentation" msg += " is listed in the argument_spec, but not documented in the module documentation"
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=322, code='undocumented-parameter',
msg=msg msg=msg
) )
for arg in docs_missing_from_args: for arg in docs_missing_from_args:
@ -1478,7 +1457,7 @@ class ModuleValidator(Validator):
msg += " is listed in DOCUMENTATION.options, but not accepted by the module argument_spec" msg += " is listed in DOCUMENTATION.options, but not accepted by the module argument_spec"
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=323, code='nonexistent-parameter-documented',
msg=msg msg=msg
) )
@ -1494,7 +1473,7 @@ class ModuleValidator(Validator):
fragment = doc['extends_documentation_fragment'] fragment = doc['extends_documentation_fragment']
self.reporter.warning( self.reporter.warning(
path=self.object_path, path=self.object_path,
code=392, code='missing-existing-doc-fragment',
msg='Pre-existing DOCUMENTATION fragment missing: %s' % fragment msg='Pre-existing DOCUMENTATION fragment missing: %s' % fragment
) )
return return
@ -1505,7 +1484,7 @@ class ModuleValidator(Validator):
) )
self.reporter.warning( self.reporter.warning(
path=self.object_path, path=self.object_path,
code=391, code='unknown-doc-fragment',
msg=('Unknown pre-existing DOCUMENTATION error, see TRACE. Submodule refs may need updated') msg=('Unknown pre-existing DOCUMENTATION error, see TRACE. Submodule refs may need updated')
) )
return return
@ -1524,7 +1503,7 @@ class ModuleValidator(Validator):
if metadata != existing_metadata: if metadata != existing_metadata:
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=334, code='metadata-changed',
msg=('ANSIBLE_METADATA cannot be changed in a point release for a stable branch') msg=('ANSIBLE_METADATA cannot be changed in a point release for a stable branch')
) )
@ -1549,7 +1528,7 @@ class ModuleValidator(Validator):
if str(current_version) != str(existing_version): if str(current_version) != str(existing_version):
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=309, code='option-incorrect-version-added',
msg=('version_added for new option (%s) should ' msg=('version_added for new option (%s) should '
'be %r. Currently %r' % 'be %r. Currently %r' %
(option, existing_version, current_version)) (option, existing_version, current_version))
@ -1565,7 +1544,7 @@ class ModuleValidator(Validator):
version_added = details.get('version_added', '0.0') version_added = details.get('version_added', '0.0')
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=308, code='module-invalid-version-added-number',
msg=('version_added for new option (%s) ' msg=('version_added for new option (%s) '
'is not a valid version number: %r' % 'is not a valid version number: %r' %
(option, version_added)) (option, version_added))
@ -1582,7 +1561,7 @@ class ModuleValidator(Validator):
strict_ansible_version < version_added)): strict_ansible_version < version_added)):
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=309, code='option-incorrect-version-added',
msg=('version_added for new option (%s) should ' msg=('version_added for new option (%s) should '
'be %r. Currently %r' % 'be %r. Currently %r' %
(option, should_be, version_added)) (option, should_be, version_added))
@ -1612,7 +1591,7 @@ class ModuleValidator(Validator):
if not self._python_module() and not self._powershell_module(): if not self._python_module() and not self._powershell_module():
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=501, code='invalid-extension',
msg=('Official Ansible modules must have a .py ' msg=('Official Ansible modules must have a .py '
'extension for python modules or a .ps1 ' 'extension for python modules or a .ps1 '
'for powershell modules') 'for powershell modules')
@ -1622,7 +1601,7 @@ class ModuleValidator(Validator):
if self._python_module() and self.ast is None: if self._python_module() and self.ast is None:
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=401, code='python-syntax-error',
msg='Python SyntaxError while parsing module' msg='Python SyntaxError while parsing module'
) )
try: try:
@ -1714,7 +1693,7 @@ class PythonPackageValidator(Validator):
if not os.path.exists(init_file): if not os.path.exists(init_file):
self.reporter.error( self.reporter.error(
path=self.object_path, path=self.object_path,
code=502, code='subdirectory-missing-init',
msg='Ansible module subdirectories must contain an __init__.py' msg='Ansible module subdirectories must contain an __init__.py'
) )

2
test/lib/ansible_test/_internal/sanity/validate_modules.py
View file

@ -117,7 +117,7 @@ class ValidateModulesTest(SanitySingleVersion):
line=int(item['line']) if 'line' in item else 0, line=int(item['line']) if 'line' in item else 0,
column=int(item['column']) if 'column' in item else 0, column=int(item['column']) if 'column' in item else 0,
level='error', level='error',
code='E%s' % item['code'], code='%s' % item['code'],
message=item['msg'], message=item['msg'],
)) ))

2
test/lib/ansible_test/_internal/test.py
View file

@ -497,7 +497,7 @@ class TestMessage:
:rtype: str :rtype: str
""" """
if self.__code: if self.__code:
msg = '%s %s' % (self.__code, self.__message) msg = '%s: %s' % (self.__code, self.__message)
else: else:
msg = self.__message msg = self.__message

8278
test/sanity/ignore.txt
View file

File diff suppressed because it is too large Load diff