ansible-core 2.19.4rc1__py3-none-any.whl → 2.20.0__py3-none-any.whl

ansible_test/_util/controller/sanity/pylint/plugins/unwanted.py

@@ -2,10 +2,12 @@
 
 from __future__ import annotations
 
+import functools
 import os
 import typing as t
 
-import astroid
+import astroid.exceptions
+import astroid.nodes
 
 from pylint.checkers import BaseChecker
 
@@ -80,36 +82,35 @@ class AnsibleUnwantedChecker(BaseChecker):
                'Identifies imports which should not be used.'),
     )
 
-    unwanted_imports = dict(
-        # Additional imports that we may want to start checking:
-        # boto=UnwantedEntry('boto3', modules_only=True),
-        # requests=UnwantedEntry('ansible.module_utils.urls', modules_only=True),
-        # urllib=UnwantedEntry('ansible.module_utils.urls', modules_only=True),
-
+    unwanted_imports = {
         # see https://docs.python.org/2/library/urllib2.html
-        urllib2=UnwantedEntry('ansible.module_utils.urls',
-                              ignore_paths=(
-                                  '/lib/ansible/module_utils/urls.py',
-                              )),
+        'urllib2': UnwantedEntry(
+            'ansible.module_utils.urls',
+            ignore_paths=(
+                '/lib/ansible/module_utils/urls.py',
+            )
+        ),
 
         # see https://docs.python.org/3/library/collections.abc.html
-        collections=UnwantedEntry('ansible.module_utils.six.moves.collections_abc',
-                                  names=(
-                                      'MappingView',
-                                      'ItemsView',
-                                      'KeysView',
-                                      'ValuesView',
-                                      'Mapping', 'MutableMapping',
-                                      'Sequence', 'MutableSequence',
-                                      'Set', 'MutableSet',
-                                      'Container',
-                                      'Hashable',
-                                      'Sized',
-                                      'Callable',
-                                      'Iterable',
-                                      'Iterator',
-                                  )),
-    )
+        'collections': UnwantedEntry(
+            'collections.abc',
+            names=(
+                'MappingView',
+                'ItemsView',
+                'KeysView',
+                'ValuesView',
+                'Mapping', 'MutableMapping',
+                'Sequence', 'MutableSequence',
+                'Set', 'MutableSet',
+                'Container',
+                'Hashable',
+                'Sized',
+                'Callable',
+                'Iterable',
+                'Iterator',
+            )
+        ),
+    }
 
     unwanted_functions = {
         # see https://docs.python.org/3/library/tempfile.html#tempfile.mktemp
@@ -133,21 +134,34 @@ class AnsibleUnwantedChecker(BaseChecker):
                                         modules_only=True),
     }
 
-    def visit_import(self, node):  # type: (astroid.node_classes.Import) -> None
+    def __init__(self, *args, **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+        # ansible.module_utils.six is deprecated and collections can still use it until it is removed
+        if self.is_ansible_core:
+            self.unwanted_imports['ansible.module_utils.six'] = UnwantedEntry(
+                'the Python standard library equivalent'
+            )
+
+    @functools.cached_property
+    def is_ansible_core(self) -> bool:
+        """True if ansible-core is being tested."""
+        return not self.linter.config.collection_name
+
+    def visit_import(self, node: astroid.nodes.Import) -> None:
         """Visit an import node."""
         for name in node.names:
             self._check_import(node, name[0])
 
-    def visit_importfrom(self, node):  # type: (astroid.node_classes.ImportFrom) -> None
+    def visit_importfrom(self, node: astroid.nodes.ImportFrom) -> None:
         """Visit an import from node."""
         self._check_importfrom(node, node.modname, node.names)
 
-    def visit_attribute(self, node):  # type: (astroid.node_classes.Attribute) -> None
+    def visit_attribute(self, node: astroid.nodes.Attribute) -> None:
         """Visit an attribute node."""
         last_child = node.last_child()
 
         # this is faster than using type inference and will catch the most common cases
-        if not isinstance(last_child, astroid.node_classes.Name):
+        if not isinstance(last_child, astroid.nodes.Name):
             return
 
         module = last_child.name
@@ -158,13 +172,13 @@ class AnsibleUnwantedChecker(BaseChecker):
             if entry.applies_to(self.linter.current_file, node.attrname):
                 self.add_message(self.BAD_IMPORT_FROM, args=(node.attrname, entry.alternative, module), node=node)
 
-    def visit_call(self, node):  # type: (astroid.node_classes.Call) -> None
+    def visit_call(self, node: astroid.nodes.Call) -> None:
         """Visit a call node."""
         try:
             for i in node.func.inferred():
                 func = None
 
-                if isinstance(i, astroid.scoped_nodes.FunctionDef) and isinstance(i.parent, astroid.scoped_nodes.Module):
+                if isinstance(i, astroid.nodes.FunctionDef) and isinstance(i.parent, astroid.nodes.Module):
                     func = '%s.%s' % (i.parent.name, i.name)
 
                 if not func:
@@ -177,7 +191,7 @@ class AnsibleUnwantedChecker(BaseChecker):
         except astroid.exceptions.InferenceError:
             pass
 
-    def _check_import(self, node, modname):  # type: (astroid.node_classes.Import, str) -> None
+    def _check_import(self, node: astroid.nodes.Import, modname: str) -> None:
         """Check the imports on the specified import node."""
         self._check_module_import(node, modname)
 
@@ -189,7 +203,7 @@ class AnsibleUnwantedChecker(BaseChecker):
         if entry.applies_to(self.linter.current_file):
             self.add_message(self.BAD_IMPORT, args=(entry.alternative, modname), node=node)
 
-    def _check_importfrom(self, node, modname, names):  # type: (astroid.node_classes.ImportFrom, str, t.List[str]) -> None
+    def _check_importfrom(self, node: astroid.nodes.ImportFrom, modname: str, names: list[tuple[str, str | None]]) -> None:
         """Check the imports on the specified import from node."""
         self._check_module_import(node, modname)
 
@@ -202,7 +216,7 @@ class AnsibleUnwantedChecker(BaseChecker):
             if entry.applies_to(self.linter.current_file, name[0]):
                 self.add_message(self.BAD_IMPORT_FROM, args=(name[0], entry.alternative, modname), node=node)
 
-    def _check_module_import(self, node, modname):  # type: (t.Union[astroid.node_classes.Import, astroid.node_classes.ImportFrom], str) -> None
+    def _check_module_import(self, node: astroid.nodes.Import | astroid.nodes.ImportFrom, modname: str) -> None:
         """Check the module import on the given import or import from node."""
         if not is_module_path(self.linter.current_file):
             return

ansible_test/_util/controller/sanity/validate-modules/validate_modules/main.py

@@ -72,7 +72,7 @@ from ansible.module_utils.compat.version import StrictVersion, LooseVersion
 from ansible.module_utils.basic import to_bytes
 from ansible.plugins.loader import fragment_loader
 from ansible.plugins.list import IGNORE as REJECTLIST
-from ansible.utils.plugin_docs import add_collection_to_versions_and_dates, add_fragments, get_docstring
+from ansible.utils.plugin_docs import AnsibleFragmentError, add_collection_to_versions_and_dates, add_fragments, get_docstring
 from ansible.utils.version import SemanticVersion
 
 from .module_args import AnsibleModuleImportError, AnsibleModuleNotInitialized, get_py_argument_spec, get_ps_argument_spec
@@ -1003,21 +1003,15 @@ class ModuleValidator(Validator):
             add_collection_to_versions_and_dates(doc, self.collection_name,
                                                  is_module=self.plugin_type == 'module')
 
-            missing_fragment = False
             with CaptureStd():
                 try:
                     get_docstring(os.path.abspath(self.path), fragment_loader=fragment_loader,
                                   verbose=True,
                                   collection_name=self.collection_name,
                                   plugin_type=self.plugin_type)
-                except AssertionError:
-                    fragment = doc['extends_documentation_fragment']
-                    self.reporter.error(
-                        path=self.object_path,
-                        code='missing-doc-fragment',
-                        msg='DOCUMENTATION fragment missing: %s' % fragment
-                    )
-                    missing_fragment = True
+                except AnsibleFragmentError:
+                    # Will be re-triggered below when explicitly calling add_fragments()
+                    pass
                 except Exception as e:
                     self.reporter.trace(
                         path=self.object_path,
@@ -1029,9 +1023,16 @@ class ModuleValidator(Validator):
                         msg='Unknown DOCUMENTATION error, see TRACE: %s' % e
                     )
 
-            if not missing_fragment:
+            try:
                 add_fragments(doc, os.path.abspath(self.object_path), fragment_loader=fragment_loader,
-                              is_module=self.plugin_type == 'module')
+                              is_module=self.plugin_type == 'module', section='DOCUMENTATION')
+            except AnsibleFragmentError as exc:
+                error = str(exc).replace(os.path.abspath(self.object_path), self.object_path)
+                self.reporter.error(
+                    path=self.object_path,
+                    code='doc-fragment-error',
+                    msg=f'Error while adding fragments: {error}'
+                )
 
             if 'options' in doc and doc['options'] is None:
                 self.reporter.error(
@@ -1130,6 +1131,16 @@ class ModuleValidator(Validator):
                     self.collection_name,
                     is_module=self.plugin_type == 'module',
                     return_docs=True)
+                try:
+                    add_fragments(returns, os.path.abspath(self.object_path), fragment_loader=fragment_loader,
+                                  is_module=self.plugin_type == 'module', section='RETURN')
+                except AnsibleFragmentError as exc:
+                    error = str(exc).replace(os.path.abspath(self.object_path), self.object_path)
+                    self.reporter.error(
+                        path=self.object_path,
+                        code='return-fragment-error',
+                        msg=f'Error while adding fragments: {error}'
+                    )
             self._validate_docs_schema(
                 returns,
                 return_schema(for_collection=bool(self.collection), plugin_type=self.plugin_type),
@@ -1268,16 +1279,18 @@ class ModuleValidator(Validator):
         if not isinstance(options, dict):
             return
         for key, value in options.items():
-            self._validate_semantic_markup(value.get('description'))
-            self._validate_semantic_markup_options(value.get('suboptions'))
+            if isinstance(value, dict):
+                self._validate_semantic_markup(value.get('description'))
+                self._validate_semantic_markup_options(value.get('suboptions'))
 
     def _validate_semantic_markup_return_values(self, return_vars):
         if not isinstance(return_vars, dict):
             return
         for key, value in return_vars.items():
-            self._validate_semantic_markup(value.get('description'))
-            self._validate_semantic_markup(value.get('returned'))
-            self._validate_semantic_markup_return_values(value.get('contains'))
+            if isinstance(value, dict):
+                self._validate_semantic_markup(value.get('description'))
+                self._validate_semantic_markup(value.get('returned'))
+                self._validate_semantic_markup_return_values(value.get('contains'))
 
     def _validate_all_semantic_markup(self, docs, return_docs):
         if not isinstance(docs, dict):
@@ -1617,7 +1630,7 @@ class ModuleValidator(Validator):
         try:
             if not context:
                 add_fragments(docs, os.path.abspath(self.object_path), fragment_loader=fragment_loader,
-                              is_module=self.plugin_type == 'module')
+                              is_module=self.plugin_type == 'module', section='DOCUMENTATION')
         except Exception:
             # Cannot merge fragments
             return

ansible_test/_util/controller/sanity/validate-modules/validate_modules/module_args.py

@@ -28,7 +28,6 @@ from contextlib import contextmanager
 
 from ansible.executor.powershell.module_manifest import PSModuleDepFinder
 from ansible.module_utils.basic import FILE_COMMON_ARGUMENTS, AnsibleModule
-from ansible.module_utils.six import reraise
 from ansible.module_utils.common.text.converters import to_bytes, to_text
 
 from .utils import CaptureStd, find_executable, get_module_name_from_filename
@@ -153,7 +152,7 @@ def get_py_argument_spec(filename, collection):
             pass
         except BaseException as e:
             # we want to catch all exceptions here, including sys.exit
-            reraise(AnsibleModuleImportError, AnsibleModuleImportError('%s' % e), sys.exc_info()[2])
+            raise AnsibleModuleImportError from e
 
         if not fake.called:
             raise AnsibleModuleNotInitialized()