ansible-core 2.17.6__py3-none-any.whl → 2.18.0__py3-none-any.whl

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

@@ -838,6 +838,46 @@ class ModuleValidator(Validator):
                 msg='%s: %s' % (combined_path, error_message)
             )
 
+    def _validate_option_docs(self, options, context=None):
+        if not isinstance(options, dict):
+            return
+        if context is None:
+            context = []
+
+        normalized_option_alias_names = dict()
+
+        def add_option_alias_name(name, option_name):
+            normalized_name = str(name).lower()
+            normalized_option_alias_names.setdefault(normalized_name, {}).setdefault(option_name, set()).add(name)
+
+        for option, data in options.items():
+            if 'suboptions' in data:
+                self._validate_option_docs(data.get('suboptions'), context + [option])
+            add_option_alias_name(option, option)
+            if 'aliases' in data and isinstance(data['aliases'], list):
+                for alias in data['aliases']:
+                    add_option_alias_name(alias, option)
+
+        for normalized_name, options in normalized_option_alias_names.items():
+            if len(options) < 2:
+                continue
+
+            what = []
+            for option_name, names in sorted(options.items()):
+                if option_name in names:
+                    what.append("option '%s'" % option_name)
+                else:
+                    what.append("alias '%s' of option '%s'" % (sorted(names)[0], option_name))
+            msg = "Multiple options/aliases"
+            if context:
+                msg += " found in %s" % " -> ".join(context)
+            msg += " are equal up to casing: %s" % ", ".join(what)
+            self.reporter.error(
+                path=self.object_path,
+                code='option-equal-up-to-casing',
+                msg=msg,
+            )
+
     def _validate_docs(self):
         doc = None
         # We have three ways of marking deprecated/removed files.  Have to check each one
@@ -1015,6 +1055,9 @@ class ModuleValidator(Validator):
                     'invalid-documentation',
                 )
 
+            if doc:
+                self._validate_option_docs(doc.get('options'))
+
             self._validate_all_semantic_markup(doc, returns)
 
             if not self.collection:
@@ -1235,7 +1278,7 @@ class ModuleValidator(Validator):
                         self._validate_semantic_markup(entry.get(key))
 
         if isinstance(docs.get('deprecated'), dict):
-            for key in ('why', 'alternative'):
+            for key in ('why', 'alternative', 'alternatives'):
                 self._validate_semantic_markup(docs.get('deprecated').get(key))
 
         self._validate_semantic_markup_options(docs.get('options'))
@@ -1876,8 +1919,10 @@ class ModuleValidator(Validator):
             if len(doc_options_args) == 0:
                 # Undocumented arguments will be handled later (search for undocumented-parameter)
                 doc_options_arg = {}
+                doc_option_name = None
             else:
-                doc_options_arg = doc_options[doc_options_args[0]]
+                doc_option_name = doc_options_args[0]
+                doc_options_arg = doc_options[doc_option_name]
                 if len(doc_options_args) > 1:
                     msg = "Argument '%s' in argument_spec" % arg
                     if context:
@@ -1892,6 +1937,26 @@ class ModuleValidator(Validator):
                         msg=msg
                     )
 
+            all_aliases = set(aliases + [arg])
+            all_docs_aliases = set(
+                ([doc_option_name] if doc_option_name is not None else [])
+                +
+                (doc_options_arg['aliases'] if isinstance(doc_options_arg.get('aliases'), list) else [])
+            )
+            if all_docs_aliases and all_aliases != all_docs_aliases:
+                msg = "Argument '%s' in argument_spec" % arg
+                if context:
+                    msg += " found in %s" % " -> ".join(context)
+                msg += " has names %s, but its documentation has names %s" % (
+                    ", ".join([("'%s'" % alias) for alias in sorted(all_aliases)]),
+                    ", ".join([("'%s'" % alias) for alias in sorted(all_docs_aliases)])
+                )
+                self.reporter.error(
+                    path=self.object_path,
+                    code='parameter-documented-aliases-differ',
+                    msg=msg
+                )
+
             try:
                 doc_default = None
                 if 'default' in doc_options_arg and doc_options_arg['default'] is not None:

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

@@ -84,6 +84,22 @@ def date(error_code=None):
     return Any(isodate, error_code=error_code)
 
 
+def require_only_one(keys):
+    def f(obj):
+        found = None
+        for k in obj.keys():
+            if k in keys:
+                if found is None:
+                    found = k
+                else:
+                    raise Invalid('Found conflicting keys, must contain only one of {}'.format(keys))
+        if found is None:
+            raise Invalid('Must contain one of {}'.format(keys))
+
+        return obj
+    return f
+
+
 # Roles can also be referenced by semantic markup
 _VALID_PLUGIN_TYPES = set(DOCUMENTABLE_PLUGINS + ('role', ))
 
@@ -568,7 +584,9 @@ def list_dict_option_schema(for_collection, plugin_type):
                     {
                         # This definition makes sure everything has the correct types/values
                         'why': doc_string,
-                        'alternatives': doc_string,
+                        # TODO: phase out either plural or singular, 'alt' is exclusive group
+                        Exclusive('alternative', 'alt'): doc_string,
+                        Exclusive('alternatives', 'alt'): doc_string,
                         # vod stands for 'version or date'; this is the name of the exclusive group
                         Exclusive('removed_at_date', 'vod'): date(),
                         Exclusive('version', 'vod'): version(for_collection),
@@ -577,7 +595,7 @@ def list_dict_option_schema(for_collection, plugin_type):
                     {
                         # This definition makes sure that everything we require is there
                         Required('why'): Any(*string_types),
-                        'alternatives': Any(*string_types),
+                        Required(Any('alternatives', 'alternative')): Any(*string_types),
                         Required(Any('removed_at_date', 'version')): Any(*string_types),
                         Required('collection_name'): Any(*string_types),
                     },
@@ -761,13 +779,16 @@ def return_schema(for_collection, plugin_type='module'):
 
 
 def deprecation_schema(for_collection):
+
     main_fields = {
         Required('why'): doc_string,
-        Required('alternative'): doc_string,
-        Required('removed_from_collection'): collection_name,
-        'removed': Any(True),
+        'alternative': doc_string,
+        'alternatives': doc_string,
     }
 
+    if for_collection:
+        main_fields.update({Required('removed_from_collection'): collection_name, 'removed': Any(True)})
+
     date_schema = {
         Required('removed_at_date'): date(),
     }
@@ -791,6 +812,7 @@ def deprecation_schema(for_collection):
     if for_collection:
         result = All(
             result,
+            require_only_one(['alternative', 'alternatives']),
             partial(check_removal_version,
                     version_field='removed_in',
                     collection_name_field='removed_from_collection',

ansible_test/_util/target/common/constants.py

@@ -5,13 +5,13 @@
 from __future__ import annotations
 
 REMOTE_ONLY_PYTHON_VERSIONS = (
-    '3.7',
     '3.8',
     '3.9',
+    '3.10',
 )
 
 CONTROLLER_PYTHON_VERSIONS = (
-    '3.10',
     '3.11',
     '3.12',
+    '3.13',
 )

ansible_test/_util/target/injector/python.py

@@ -6,12 +6,15 @@ import importlib.util
 import os
 import sys
 
+NETWORKING_CLI_STUB_SCRIPT = 'ansible_connection_cli_stub.py'
+
 
 def main():
     """Main entry point."""
     name = os.path.basename(__file__)
     args = [sys.executable]
 
+    ansible_lib_root = os.environ.get('ANSIBLE_TEST_ANSIBLE_LIB_ROOT')
     coverage_config = os.environ.get('COVERAGE_CONF')
     coverage_output = os.environ.get('COVERAGE_FILE')
 
@@ -33,6 +36,8 @@ def main():
         args += ['-m', 'pytest']
     elif name == 'importer.py':
         args += [find_program(name, False)]
+    elif name == NETWORKING_CLI_STUB_SCRIPT:
+        args += [os.path.join(ansible_lib_root, 'cli/scripts', NETWORKING_CLI_STUB_SCRIPT)]
     else:
         args += [find_program(name, True)]
 

ansible_test/_util/target/pytest/plugins/ansible_pytest_coverage.py

@@ -53,6 +53,12 @@ def pytest_configure():
 
     def coverage_exit(*args, **kwargs):
         for instance in coverage_instances:
+            # skip coverage instances which have no collector, or the collector is not the active collector
+            # this avoids issues with coverage 7.4.0+ when tests create subprocesses which inherit our overridden os._exit method
+            # pylint: disable=protected-access
+            if not instance._collector or not instance._collector._collectors or instance._collector != instance._collector._collectors[-1]:
+                continue
+
             instance.stop()
             instance.save()
 

ansible_test/_util/target/sanity/import/importer.py

@@ -159,7 +159,7 @@ def main():
             loader = self._get_loader(fullname, path=path)
             if loader is not None:
                 if has_py3_loader:
-                    # loader is expected to be Optional[importlib.abc.Loader], but RestrictedModuleLoader does not inherit from importlib.abc.Loder
+                    # loader is expected to be Optional[importlib.abc.Loader], but RestrictedModuleLoader does not inherit from importlib.abc.Loader
                     return spec_from_loader(fullname, loader)  # type: ignore[arg-type]
                 raise ImportError("Failed to import '%s' due to a bug in ansible-test. Check importlib imports for typos." % fullname)
             return None

ansible_test/_util/target/setup/bootstrap.sh

@@ -53,14 +53,14 @@ customize_bashrc()
     fi
 
     # Improve shell prompts for interactive use.
-    echo "export PS1='\[\e]0;\u@\h: \w\a\]\[\033[01;32m\]\u@\h\[\033[00m\]:\[\033[01;34m\]\w\[\033[00m\]\$ '" >> ~/.bashrc
+    echo "export PS1='"'\[\e]0;\u@\h: \w\a\]\[\033[01;32m\]\u@\h\[\033[00m\]:\[\033[01;34m\]\w\[\033[00m\]\$ '"'" >> ~/.bashrc
 }
 
 install_pip() {
     if ! "${python_interpreter}" -m pip.__main__ --version --disable-pip-version-check 2>/dev/null; then
         case "${python_version}" in
             *)
-                pip_bootstrap_url="https://ci-files.testing.ansible.com/ansible-test/get-pip-23.1.2.py"
+                pip_bootstrap_url="https://ci-files.testing.ansible.com/ansible-test/get-pip-24.0.py"
                 ;;
         esac
 
@@ -176,10 +176,10 @@ bootstrap_remote_freebsd()
                 cryptography_pkg=""  # not available
                 pyyaml_pkg=""  # not available
                 ;;
-            14.0/3.9)
+            14.1/3.9)
                 # defaults above 'just work'TM
                 ;;
-            14.0/3.11)
+            14.1/3.11)
                 cryptography_pkg=""  # not available
                 jinja2_pkg=""  # not available
                 pyyaml_pkg=""  # not available
@@ -268,19 +268,12 @@ bootstrap_remote_rhel_9()
     packages="
         gcc
         ${py_pkg_prefix}-devel
+        ${py_pkg_prefix}-pip
         "
 
-    # pip is not included in the Python devel package under Python 3.11
-    if [ "${python_version}" != "3.9" ]; then
-        packages="
-            ${packages}
-            ${py_pkg_prefix}-pip
-        "
-    fi
-
     # Jinja2 is not installed with an OS package since the provided version is too old.
     # Instead, ansible-test will install it using pip.
-    # packaging and resolvelib are missing for Python 3.11 (and possible later) so we just
+    # packaging and resolvelib are missing for controller supported Python versions, so we just
     # skip them and let ansible-test install them from PyPI.
     if [ "${controller}" ]; then
         packages="
@@ -329,10 +322,6 @@ bootstrap_remote_ubuntu()
         # For these ansible-test will use pip to install the requirements instead.
         # Only the platform is checked since Ubuntu shares Python packages across Python versions.
         case "${platform_version}" in
-            "20.04")
-                jinja2_pkg=""  # too old
-                resolvelib_pkg=""  # not available
-                ;;
         esac
 
         packages="

ansible_test/_util/target/setup/requirements.py

@@ -22,27 +22,13 @@ import errno
 import io
 import json
 import os
+import shlex
 import shutil
 import subprocess
 import sys
 import tempfile
-
-try:
-    import typing as t
-except ImportError:
-    t = None
-
-try:
-    from shlex import quote as cmd_quote
-except ImportError:
-    # noinspection PyProtectedMember
-    from pipes import quote as cmd_quote
-
-try:
-    from urllib.request import urlopen
-except ImportError:
-    # noinspection PyCompatibility,PyUnresolvedReferences
-    from urllib2 import urlopen  # pylint: disable=ansible-bad-import-from
+import typing as t
+import urllib.request
 
 ENCODING = 'utf-8'
 
@@ -80,6 +66,8 @@ def bootstrap(pip, options):  # type: (str, t.Dict[str, t.Any]) -> None
     """Bootstrap pip and related packages in an empty virtual environment."""
     pip_version = options['pip_version']
     packages = options['packages']
+    setuptools = options['setuptools']
+    wheel = options['wheel']
 
     url = 'https://ci-files.testing.ansible.com/ansible-test/get-pip-%s.py' % pip_version
     cache_path = os.path.expanduser('~/.ansible/test/cache/get_pip_%s.py' % pip_version.replace(".", "_"))
@@ -115,6 +103,12 @@ https://github.com/ansible/ansible/issues/77304
     options = common_pip_options()
     options.extend(packages)
 
+    if not setuptools:
+        options.append('--no-setuptools')
+
+    if not wheel:
+        options.append('--no-wheel')
+
     command = [sys.executable, pip] + options
 
     execute_command(command, env=env)
@@ -280,7 +274,7 @@ def devnull():  # type: () -> t.IO[bytes]
 def download_file(url, path):  # type: (str, str) -> None
     """Download the given URL to the specified file path."""
     with open(to_bytes(path), 'wb') as saved_file:
-        with contextlib.closing(urlopen(url)) as download:
+        with contextlib.closing(urllib.request.urlopen(url)) as download:
             shutil.copyfileobj(download, saved_file)
 
 
@@ -291,7 +285,7 @@ class ApplicationError(Exception):
 class SubprocessError(ApplicationError):
     """A command returned a non-zero status."""
     def __init__(self, cmd, status, stdout, stderr):  # type: (t.List[str], int, str, str) -> None
-        message = 'A command failed with status %d: %s' % (status, ' '.join(cmd_quote(c) for c in cmd))
+        message = 'A command failed with status %d: %s' % (status, shlex.join(cmd))
 
         if stderr:
             message += '\n>>> Standard Error\n%s' % stderr.strip()
@@ -313,7 +307,7 @@ def log(message, verbosity=0):  # type: (str, int) -> None
 
 def execute_command(cmd, cwd=None, capture=False, env=None):  # type: (t.List[str], t.Optional[str], bool, t.Optional[t.Dict[str, str]]) -> None
     """Execute the specified command."""
-    log('Execute command: %s' % ' '.join(cmd_quote(c) for c in cmd), verbosity=1)
+    log('Execute command: %s' % shlex.join(cmd), verbosity=1)
 
     cmd_bytes = [to_bytes(c) for c in cmd]
 
@@ -369,17 +363,17 @@ def open_binary_file(path, mode='rb'):  # type: (str, str) -> t.IO[bytes]
     return io.open(to_bytes(path), mode)  # pylint: disable=consider-using-with,unspecified-encoding
 
 
-def to_optional_bytes(value, errors='strict'):  # type: (t.Optional[t.AnyStr], str) -> t.Optional[bytes]
+def to_optional_bytes(value, errors='strict'):  # type: (t.Optional[str | bytes], str) -> t.Optional[bytes]
     """Return the given value as bytes encoded using UTF-8 if not already bytes, or None if the value is None."""
     return None if value is None else to_bytes(value, errors)
 
 
-def to_optional_text(value, errors='strict'):  # type: (t.Optional[t.AnyStr], str) -> t.Optional[t.Text]
+def to_optional_text(value, errors='strict'):  # type: (t.Optional[str | bytes], str) -> t.Optional[t.Text]
     """Return the given value as text decoded using UTF-8 if not already text, or None if the value is None."""
     return None if value is None else to_text(value, errors)
 
 
-def to_bytes(value, errors='strict'):  # type: (t.AnyStr, str) -> bytes
+def to_bytes(value, errors='strict'):  # type: (str | bytes, str) -> bytes
     """Return the given value as bytes encoded using UTF-8 if not already bytes."""
     if isinstance(value, bytes):
         return value
@@ -390,7 +384,7 @@ def to_bytes(value, errors='strict'):  # type: (t.AnyStr, str) -> bytes
     raise Exception('value is not bytes or text: %s' % type(value))
 
 
-def to_text(value, errors='strict'):  # type: (t.AnyStr, str) -> t.Text
+def to_text(value, errors='strict'):  # type: (str | bytes, str) -> t.Text
     """Return the given value as text decoded using UTF-8 if not already text."""
     if isinstance(value, bytes):
         return value.decode(ENCODING, errors)

ansible_test/config/config.yml

@@ -17,7 +17,7 @@ modules:
   #                   This is the default value if no configuration is provided.
   #  - 'controller' - All Python versions supported by the Ansible controller.
   #                   This indicates the modules/module_utils can only run on the controller.
-  #                   Intended for use only with modules/module_utils that depend on ansible-connection, which only runs on the controller.
+  #                   Intended for use only with modules/module_utils that depend on the Ansible persistent connection helper, which only runs on the controller.
   #                   Unit tests for modules/module_utils will be permitted to import any Ansible code, instead of only module_utils.
   #  - SpecifierSet - A PEP 440 specifier set indicating the supported Python versions.
   #                   This is only needed when modules/module_utils do not support all Python versions supported by Ansible.

ansible_core-2.17.6.data/scripts/ansible-test

@@ -1,44 +0,0 @@
-#!python
-# PYTHON_ARGCOMPLETE_OK
-"""Command line entry point for ansible-test."""
-
-# NOTE: This file resides in the _util/target directory to ensure compatibility with all supported Python versions.
-
-from __future__ import annotations
-
-import os
-import sys
-
-
-def main(args=None):
-    """Main program entry point."""
-    ansible_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
-    source_root = os.path.join(ansible_root, 'test', 'lib')
-
-    if os.path.exists(os.path.join(source_root, 'ansible_test', '_internal', '__init__.py')):
-        # running from source, use that version of ansible-test instead of any version that may already be installed
-        sys.path.insert(0, source_root)
-
-    # noinspection PyProtectedMember
-    from ansible_test._util.target.common.constants import CONTROLLER_PYTHON_VERSIONS
-
-    if version_to_str(sys.version_info[:2]) not in CONTROLLER_PYTHON_VERSIONS:
-        raise SystemExit('This version of ansible-test cannot be executed with Python version %s. Supported Python versions are: %s' % (
-            version_to_str(sys.version_info[:3]), ', '.join(CONTROLLER_PYTHON_VERSIONS)))
-
-    if any(not os.get_blocking(handle.fileno()) for handle in (sys.stdin, sys.stdout, sys.stderr)):
-        raise SystemExit('Standard input, output and error file handles must be blocking to run ansible-test.')
-
-    # noinspection PyProtectedMember
-    from ansible_test._internal import main as cli_main
-
-    cli_main(args)
-
-
-def version_to_str(version):
-    """Return a version string from a version tuple."""
-    return '.'.join(str(n) for n in version)
-
-
-if __name__ == '__main__':
-    main()

ansible_test/_data/requirements/sanity.mypy.in

@@ -1,10 +0,0 @@
-mypy
-cryptography  # type stubs not published separately
-jinja2  # type stubs not published separately
-packaging  # type stubs not published separately
-types-backports
-types-paramiko
-types-pyyaml
-types-requests
-types-setuptools
-types-toml

ansible_test/_data/requirements/sanity.mypy.txt

@@ -1,18 +0,0 @@
-# edit "sanity.mypy.in" and generate with: hacking/update-sanity-requirements.py --test mypy
-cffi==1.16.0
-cryptography==42.0.5
-Jinja2==3.1.3
-MarkupSafe==2.1.5
-mypy==1.9.0
-mypy-extensions==1.0.0
-packaging==24.0
-pycparser==2.21
-tomli==2.0.1
-types-backports==0.1.3
-types-paramiko==3.4.0.20240311
-types-PyYAML==6.0.12.20240311
-types-requests==2.31.0.20240311
-types-setuptools==69.2.0.20240317
-types-toml==0.10.8.20240310
-typing_extensions==4.10.0
-urllib3==2.2.1