ansible-core 2.18.5rc1__py3-none-any.whl → 2.19.0b1__py3-none-any.whl

ansible/modules/apt.py

@@ -9,7 +9,7 @@
 from __future__ import annotations
 
 
-DOCUMENTATION = '''
+DOCUMENTATION = """
 ---
 module: apt
 short_description: Manages apt-packages
@@ -17,6 +17,12 @@ description:
   - Manages I(apt) packages (such as for Debian/Ubuntu).
 version_added: "0.0.2"
 options:
+  auto_install_module_deps:
+    description:
+      - Automatically install dependencies required to run this module.
+    type: bool
+    default: yes
+    version_added: 2.19
   name:
     description:
       - A list of package names, like V(foo), or package specifier with version, like V(foo=1.0) or V(foo>=1.0).
@@ -191,8 +197,7 @@ options:
     default: 60
     version_added: "2.12"
 requirements:
-   - python-apt (python 2)
-   - python3-apt (python 3)
+   - python3-apt
    - aptitude (before 2.4)
 author: "Matthew Williams (@mgwilliams)"
 extends_documentation_fragment: action_common_attributes
@@ -214,12 +219,12 @@ notes:
    - When used with a C(loop:) each package will be processed individually, it is much more efficient to pass the list directly to the O(name) option.
    - When O(default_release) is used, an implicit priority of 990 is used. This is the same behavior as C(apt-get -t).
    - When an exact version is specified, an implicit priority of 1001 is used.
-   - If the interpreter can't import C(python-apt)/C(python3-apt) the module will check for it in system-owned interpreters as well.
-     If the dependency can't be found, the module will attempt to install it.
+   - If the interpreter can't import C(python3-apt) the module will check for it in system-owned interpreters as well.
+     If the dependency can't be found, depending on the value of O(auto_install_module_deps) the module will attempt to install it.
      If the dependency is found or installed, the module will be respawned under the correct interpreter.
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = """
 - name: Install apache httpd (state=present is optional)
   ansible.builtin.apt:
     name: apache2
@@ -327,9 +332,9 @@ EXAMPLES = '''
 - name: Run the equivalent of "apt-get clean" as a separate step
   ansible.builtin.apt:
     clean: yes
-'''
+"""
 
-RETURN = '''
+RETURN = """
 cache_updated:
     description: if the cache was updated or not
     returned: success, in some cases
@@ -355,7 +360,7 @@ stderr:
     returned: success, when needed
     type: str
     sample: "AH00558: apache2: Could not reliably determine the server's fully qualified domain name, using 127.0.1.1. Set the 'ServerName' directive globally to ..."
-'''  # NOQA
+"""  # NOQA
 
 # added to stave off future warnings about apt api
 import warnings
@@ -483,7 +488,7 @@ class PolicyRcD(object):
 
 
 def package_split(pkgspec):
-    parts = re.split(r'(>?=)', pkgspec, 1)
+    parts = re.split(r'(>?=)', pkgspec, maxsplit=1)
     if len(parts) > 1:
         return parts
     return parts[0], None, None
@@ -1184,7 +1189,7 @@ def get_updated_cache_time():
 
 # https://github.com/ansible/ansible-modules-core/issues/2951
 def get_cache(module):
-    '''Attempt to get the cache object and update till it works'''
+    """Attempt to get the cache object and update till it works"""
     cache = None
     try:
         cache = apt.Cache()
@@ -1233,6 +1238,7 @@ def main():
             allow_downgrade=dict(type='bool', default=False, aliases=['allow-downgrade', 'allow_downgrades', 'allow-downgrades']),
             allow_change_held_packages=dict(type='bool', default=False),
             lock_timeout=dict(type='int', default=60),
+            auto_install_module_deps=dict(type='bool', default=True),
         ),
         mutually_exclusive=[['deb', 'package', 'upgrade']],
         required_one_of=[['autoremove', 'deb', 'package', 'update_cache', 'upgrade']],
@@ -1268,7 +1274,7 @@ def main():
     if not HAS_PYTHON_APT:
         # This interpreter can't see the apt Python library- we'll do the following to try and fix that:
         # 1) look in common locations for system-owned interpreters that can see it; if we find one, respawn under it
-        # 2) finding none, try to install a matching python-apt package for the current interpreter version;
+        # 2) finding none, try to install a matching python3-apt package for the current interpreter version;
         #    we limit to the current interpreter version to try and avoid installing a whole other Python just
         #    for apt support
         # 3) if we installed a support package, try to respawn under what we think is the right interpreter (could be
@@ -1294,39 +1300,47 @@ def main():
 
         # don't make changes if we're in check_mode
         if module.check_mode:
-            module.fail_json(msg="%s must be installed to use check mode. "
-                                 "If run normally this module can auto-install it." % apt_pkg_name)
-
-        # We skip cache update in auto install the dependency if the
-        # user explicitly declared it with update_cache=no.
-        if module.params.get('update_cache') is False:
-            module.warn("Auto-installing missing dependency without updating cache: %s" % apt_pkg_name)
-        else:
-            module.warn("Updating cache and auto-installing missing dependency: %s" % apt_pkg_name)
-            module.run_command([APT_GET_CMD, 'update'], check_rc=True)
-
-        # try to install the apt Python binding
-        apt_pkg_cmd = [APT_GET_CMD, 'install', apt_pkg_name, '-y', '-q', dpkg_options]
-
-        if install_recommends is False:
-            apt_pkg_cmd.extend(["-o", "APT::Install-Recommends=no"])
-        elif install_recommends is True:
-            apt_pkg_cmd.extend(["-o", "APT::Install-Recommends=yes"])
-        # install_recommends is None uses the OS default
-
-        module.run_command(apt_pkg_cmd, check_rc=True)
-
-        # try again to find the bindings in common places
-        interpreter = probe_interpreters_for_module(interpreters, 'apt')
-
-        if interpreter:
-            # found the Python bindings; respawn this module under the interpreter where we found them
-            # NB: respawn is somewhat wasteful if it's this interpreter, but simplifies the code
-            respawn_module(interpreter)
-            # this is the end of the line for this process, it will exit here once the respawned module has completed
-        else:
-            # we've done all we can do; just tell the user it's busted and get out
-            module.fail_json(msg="{0} must be installed and visible from {1}.".format(apt_pkg_name, sys.executable))
+            module.fail_json(
+                msg=f"{apt_pkg_name} must be installed to use check mode. "
+                    "If run normally this module can auto-install it, "
+                    "see the auto_install_module_deps option.",
+            )
+        elif p['auto_install_module_deps']:
+            # We skip cache update in auto install the dependency if the
+            # user explicitly declared it with update_cache=no.
+            if module.params.get('update_cache') is False:
+                module.warn("Auto-installing missing dependency without updating cache: %s" % apt_pkg_name)
+            else:
+                module.warn("Updating cache and auto-installing missing dependency: %s" % apt_pkg_name)
+                module.run_command([APT_GET_CMD, 'update'], check_rc=True)
+
+            # try to install the apt Python binding
+            apt_pkg_cmd = [APT_GET_CMD, 'install', apt_pkg_name, '-y', '-q', dpkg_options]
+
+            if install_recommends is False:
+                apt_pkg_cmd.extend(["-o", "APT::Install-Recommends=no"])
+            elif install_recommends is True:
+                apt_pkg_cmd.extend(["-o", "APT::Install-Recommends=yes"])
+            # install_recommends is None uses the OS default
+
+            module.run_command(apt_pkg_cmd, check_rc=True)
+
+            # try again to find the bindings in common places
+            interpreter = probe_interpreters_for_module(interpreters, 'apt')
+
+            if interpreter:
+                # found the Python bindings; respawn this module under the interpreter where we found them
+                # NB: respawn is somewhat wasteful if it's this interpreter, but simplifies the code
+                respawn_module(interpreter)
+                # this is the end of the line for this process, it will exit here once the respawned module has completed
+
+        # we've done all we can do; just tell the user it's busted and get out
+        py_version = sys.version.replace("\n", "")
+        module.fail_json(
+            msg=f"Could not import the {apt_pkg_name} module using {sys.executable} ({py_version}). "
+            f"Ensure {apt_pkg_name} package is installed (either manually or via the auto_install_module_deps option) "
+            f"or that you have specified the correct ansible_python_interpreter. (attempted {interpreters}).",
+        )
 
     if p['clean'] is True:
         aptclean_stdout, aptclean_stderr, aptclean_diff = aptclean(module)

ansible/modules/apt_key.py

@@ -8,7 +8,7 @@
 from __future__ import annotations
 
 
-DOCUMENTATION = '''
+DOCUMENTATION = """
 ---
 module: apt_key
 author:
@@ -33,6 +33,8 @@ notes:
       To generate a full-fingerprint imported key: C(apt-key adv --list-public-keys --with-fingerprint --with-colons)."
     - If you specify both the key O(id) and the O(url) with O(state=present), the task can verify or add the key as needed.
     - Adding a new key requires an apt cache update (e.g. using the M(ansible.builtin.apt) module's C(update_cache) option).
+    - The C(apt-key) utility has been deprecated and removed in modern debian versions, use M(ansible.builtin.deb822_repository) as an alternative
+      to M(ansible.builtin.apt_repository) + apt_key combinations.
 requirements:
     - gpg
 seealso:
@@ -79,9 +81,9 @@ options:
               on personally controlled sites using self-signed certificates.
         type: bool
         default: 'yes'
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = """
 - name: One way to avoid apt_key once it is removed from your distro, armored keys should use .asc extension, binary should use .gpg
   block:
     - name: somerepo | no apt key
@@ -133,9 +135,9 @@ EXAMPLES = '''
     id: 9FED2BCBDCD29CDF762678CBAED4B06F473041FA
     file: /tmp/apt.gpg
     state: present
-'''
+"""
 
-RETURN = '''
+RETURN = """
 after:
     description: List of apt key ids or fingerprints after any modification
     returned: on change
@@ -166,13 +168,10 @@ short_id:
     returned: always
     type: str
     sample: "A88D21E9"
-'''
+"""
 
 import os
 
-# FIXME: standardize into module_common
-from traceback import format_exc
-
 from ansible.module_utils.common.text.converters import to_native
 from ansible.module_utils.basic import AnsibleModule
 from ansible.module_utils.common.locale import get_best_parsable_locale
@@ -196,8 +195,16 @@ def lang_env(module):
 def find_needed_binaries(module):
     global apt_key_bin
     global gpg_bin
-    apt_key_bin = module.get_bin_path('apt-key', required=True)
-    gpg_bin = module.get_bin_path('gpg', required=True)
+
+    try:
+        apt_key_bin = module.get_bin_path('apt-key', required=True)
+    except ValueError as e:
+        module.exit_json(f'{to_native(e)}. Apt-key has been deprecated. See the deb822_repository as an alternative.')
+
+    try:
+        gpg_bin = module.get_bin_path('gpg', required=True)
+    except ValueError as e:
+        module.exit_json(msg=to_native(e))
 
 
 def add_http_proxy(cmd):
@@ -310,7 +317,7 @@ def download_key(module, url):
 
         return rsp.read()
     except Exception:
-        module.fail_json(msg="error getting key id from url: %s" % url, traceback=format_exc())
+        module.fail_json(msg=f"Error getting key id from url: {url}")
 
 
 def get_key_id_from_file(module, filename, data=None):

ansible/modules/apt_repository.py

@@ -9,7 +9,7 @@
 from __future__ import annotations
 
 
-DOCUMENTATION = '''
+DOCUMENTATION = """
 ---
 module: apt_repository
 short_description: Add and remove APT repositories
@@ -101,9 +101,9 @@ requirements:
    - python-apt (python 2)
    - python3-apt (python 3)
    - apt-key or gpg
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = """
 - name: Add specified repository into sources list
   ansible.builtin.apt_repository:
     repo: deb http://archive.canonical.com/ubuntu hardy partner
@@ -143,11 +143,11 @@ EXAMPLES = '''
 
     - name: somerepo | apt source
       ansible.builtin.apt_repository:
-        repo: "deb [arch=amd64 signed-by=/etc/apt/keyrings/myrepo.asc] https://download.example.com/linux/ubuntu {{ ansible_distribution_release }} stable"
+        repo: "deb [arch=amd64 signed-by=/etc/apt/keyrings/somerepo.asc] https://download.example.com/linux/ubuntu {{ ansible_distribution_release }} stable"
         state: present
-'''
+"""
 
-RETURN = '''
+RETURN = """
 repo:
   description: A source string for the repository
   returned: always
@@ -167,7 +167,7 @@ sources_removed:
   type: list
   sample: ["/etc/apt/sources.list.d/artifacts_elastic_co_packages_6_x_apt.list"]
   version_added: "2.15"
-'''
+"""
 
 import copy
 import glob
@@ -245,7 +245,7 @@ class SourcesList(object):
             self.load(file)
 
     def __iter__(self):
-        '''Simple iterator to go over all sources. Empty, non-source, and other not valid lines will be skipped.'''
+        """Simple iterator to go over all sources. Empty, non-source, and other not valid lines will be skipped."""
         for file, sources in self.files.items():
             for n, valid, enabled, source, comment in sources:
                 if valid:
@@ -315,9 +315,9 @@ class SourcesList(object):
 
     @staticmethod
     def _apt_cfg_file(filespec):
-        '''
+        """
         Wrapper for `apt_pkg` module for running with Python 2.5
-        '''
+        """
         try:
             result = apt_pkg.config.find_file(filespec)
         except AttributeError:
@@ -326,9 +326,9 @@ class SourcesList(object):
 
     @staticmethod
     def _apt_cfg_dir(dirspec):
-        '''
+        """
         Wrapper for `apt_pkg` module for running with Python 2.5
-        '''
+        """
         try:
             result = apt_pkg.config.find_dir(dirspec)
         except AttributeError:
@@ -413,10 +413,10 @@ class SourcesList(object):
         return new
 
     def modify(self, file, n, enabled=None, source=None, comment=None):
-        '''
+        """
         This function to be used with iterator, so we don't care of invalid sources.
         If source, enabled, or comment is None, original value from line ``n`` will be preserved.
-        '''
+        """
         valid, enabled_old, source_old, comment_old = self.files[file][n][1:]
         self.files[file][n] = (n, valid, self._choice(enabled, enabled_old), self._choice(source, source_old), self._choice(comment, comment_old))
 
@@ -475,7 +475,10 @@ class UbuntuSourcesList(SourcesList):
         self.apt_key_bin = self.module.get_bin_path('apt-key', required=False)
         self.gpg_bin = self.module.get_bin_path('gpg', required=False)
         if not self.apt_key_bin and not self.gpg_bin:
-            self.module.fail_json(msg='Either apt-key or gpg binary is required, but neither could be found')
+            msg = 'Either apt-key or gpg binary is required, but neither could be found.' \
+                  'The apt-key CLI has been deprecated and removed in modern Debian and derivatives, ' \
+                  'you might want to use "deb822_repository" instead.'
+            self.module.fail_json(msg)
 
     def __deepcopy__(self, memo=None):
         return UbuntuSourcesList(self.module)
@@ -616,7 +619,7 @@ class UbuntuSourcesList(SourcesList):
 
 
 def revert_sources_list(sources_before, sources_after, sourceslist_before):
-    '''Revert the sourcelist files to their previous state.'''
+    """Revert the sourcelist files to their previous state."""
 
     # First remove any new files that were created:
     for filename in set(sources_after.keys()).difference(sources_before.keys()):

ansible/modules/assemble.py

@@ -8,7 +8,7 @@
 from __future__ import annotations
 
 
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
 ---
 module: assemble
 short_description: Assemble configuration files from fragments
@@ -102,9 +102,9 @@ extends_documentation_fragment:
     - action_common_attributes.files
     - decrypt
     - files
-'''
+"""
 
-EXAMPLES = r'''
+EXAMPLES = r"""
 - name: Assemble from fragments from a directory
   ansible.builtin.assemble:
     src: /etc/someapp/fragments
@@ -121,9 +121,9 @@ EXAMPLES = r'''
     src: /etc/ssh/conf.d/
     dest: /etc/ssh/sshd_config
     validate: /usr/sbin/sshd -t -f %s
-'''
+"""
 
-RETURN = r'''#'''
+RETURN = r"""#"""
 
 import codecs
 import os
@@ -136,7 +136,7 @@ from ansible.module_utils.common.text.converters import to_native
 
 
 def assemble_from_fragments(src_path, delimiter=None, compiled_regexp=None, ignore_hidden=False, tmpdir=None):
-    ''' assemble a file from a directory of fragments '''
+    """ assemble a file from a directory of fragments """
     tmpfd, temp_path = tempfile.mkstemp(dir=tmpdir)
     tmp = os.fdopen(tmpfd, 'wb')
     delimit_me = False

ansible/modules/assert.py

@@ -6,7 +6,7 @@
 from __future__ import annotations
 
 
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
 ---
 module: assert
 short_description: Asserts given expressions are true
@@ -70,9 +70,9 @@ seealso:
 author:
     - Ansible Core Team
     - Michael DeHaan
-'''
+"""
 
-EXAMPLES = r'''
+EXAMPLES = r"""
 - name: A single condition can be supplied as string instead of list
   ansible.builtin.assert:
     that: "ansible_os_family != 'RedHat'"
@@ -106,4 +106,4 @@ EXAMPLES = r'''
       - my_param <= 100
       - my_param >= 0
     quiet: true
-'''
+"""

ansible/modules/async_status.py

@@ -5,8 +5,9 @@
 
 from __future__ import annotations
 
+import sys
 
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
 ---
 module: async_status
 short_description: Obtain status of asynchronous task
@@ -51,9 +52,9 @@ seealso:
 author:
 - Ansible Core Team
 - Michael DeHaan
-'''
+"""
 
-EXAMPLES = r'''
+EXAMPLES = r"""
 ---
 - name: Asynchronous dnf task
   ansible.builtin.dnf:
@@ -75,9 +76,9 @@ EXAMPLES = r'''
   ansible.builtin.async_status:
     jid: '{{ dnf_sleeper.ansible_job_id }}'
     mode: cleanup
-'''
+"""
 
-RETURN = r'''
+RETURN = r"""
 ansible_job_id:
   description: The asynchronous job id
   returned: success
@@ -105,14 +106,12 @@ erased:
   description: Path to erased job file
   returned: when file is erased
   type: str
-'''
+"""
 
 import json
 import os
 
 from ansible.module_utils.basic import AnsibleModule
-from ansible.module_utils.six import iteritems
-from ansible.module_utils.common.text.converters import to_native
 
 
 def main():
@@ -163,10 +162,9 @@ def main():
     elif 'finished' not in data:
         data['finished'] = 0
 
-    # Fix error: TypeError: exit_json() keywords must be strings
-    data = {to_native(k): v for k, v in iteritems(data)}
-
-    module.exit_json(**data)
+    # just write the module output directly to stdout and exit; bypass other processing done by exit_json since it's already been done
+    print(f"\n{json.dumps(data)}")  # pylint: disable=ansible-bad-function
+    sys.exit(0)  # pylint: disable=ansible-bad-function
 
 
 if __name__ == '__main__':

ansible/modules/async_wrapper.py

@@ -75,13 +75,13 @@ def daemonize_self():
 # NB: this function copied from module_utils/json_utils.py. Ensure any changes are propagated there.
 # FUTURE: AnsibleModule-ify this module so it's Ansiballz-compatible and can use the module_utils copy of this function.
 def _filter_non_json_lines(data):
-    '''
+    """
     Used to filter unrelated output around module JSON output, like messages from
     tcagetattr, or where dropbear spews MOTD on every single command (which is nuts).
 
     Filters leading lines before first line-starting occurrence of '{', and filter all
     trailing lines after matching close character (working from the bottom of output).
-    '''
+    """
     warnings = []
 
     # Filter initial junk
@@ -147,6 +147,8 @@ def jwrite(info):
 
 def _run_module(wrapped_cmd, jid):
 
+    # DTFIX-FUTURE: needs rework for serialization profiles
+
     jwrite({"started": 1, "finished": 0, "ansible_job_id": jid})
 
     result = {}
@@ -188,6 +190,9 @@ def _run_module(wrapped_cmd, jid):
             module_warnings = result.get('warnings', [])
             if not isinstance(module_warnings, list):
                 module_warnings = [module_warnings]
+
+            # this relies on the controller's fallback conversion of string warnings to WarningMessageDetail instances, and assumes
+            # that the module result and warning collection are basic JSON datatypes (eg, no tags or other custom collections).
             module_warnings.extend(json_warnings)
             result['warnings'] = module_warnings
 
@@ -257,7 +262,7 @@ def main():
         end({
             "failed": 1,
             "msg": "could not create directory: %s - %s" % (jobdir, to_text(e)),
-            "exception": to_text(traceback.format_exc()),
+            "exception": to_text(traceback.format_exc()),  # NB: task executor compat will coerce to the correct dataclass type
         }, 1)
 
     # immediately exit this process, leaving an orphaned process

ansible/modules/blockinfile.py

@@ -7,7 +7,7 @@
 from __future__ import annotations
 
 
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
 ---
 module: blockinfile
 short_description: Insert/update/remove a text block surrounded by marker lines
@@ -125,9 +125,9 @@ attributes:
       platforms: posix
     vault:
       support: none
-'''
+"""
 
-EXAMPLES = r'''
+EXAMPLES = r"""
 # Before Ansible 2.3, option 'dest' or 'name' was used instead of 'path'
 - name: Insert/Update "Match User" configuration block in /etc/ssh/sshd_config prepending and appending a new line
   ansible.builtin.blockinfile:
@@ -187,7 +187,7 @@ EXAMPLES = r'''
     insertafter: '(?m)SID_LIST_LISTENER_DG =\n.*\(SID_LIST ='
     marker: "    <!-- {mark} ANSIBLE MANAGED BLOCK -->"
 
-'''
+"""
 
 import re
 import os
@@ -200,9 +200,8 @@ from ansible.module_utils.common.text.converters import to_bytes, to_native
 def write_changes(module, contents, path):
 
     tmpfd, tmpfile = tempfile.mkstemp(dir=module.tmpdir)
-    f = os.fdopen(tmpfd, 'wb')
-    f.write(contents)
-    f.close()
+    with os.fdopen(tmpfd, 'wb') as tf:
+        tf.write(contents)
 
     validate = module.params.get('validate', None)
     valid = not validate