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

ansible/modules/apt_repository.py

@@ -41,13 +41,13 @@ options:
         default: "present"
     mode:
         description:
-            - The octal mode for newly created files in sources.list.d.
+            - The octal mode for newly created files in C(sources.list.d).
             - Default is what system uses (probably 0644).
         type: raw
         version_added: "1.6"
     update_cache:
         description:
-            - Run the equivalent of C(apt-get update) when a change occurs.  Cache updates are run after making changes.
+            - Run the equivalent of C(apt-get update) when a change occurs. Cache updates are run after making changes.
         type: bool
         default: "yes"
         aliases: [ update-cache ]
@@ -72,9 +72,9 @@ options:
         version_added: '1.8'
     filename:
         description:
-            - Sets the name of the source list file in sources.list.d.
+            - Sets the name of the source list file in C(sources.list.d).
               Defaults to a file name based on the repository source url.
-              The .list extension will be automatically added.
+              The C(.list) extension will be automatically added.
         type: str
         version_added: '2.1'
     codename:
@@ -90,8 +90,8 @@ options:
               Without this library, the module does not work.
             - Runs C(apt-get install python-apt) for Python 2, and C(apt-get install python3-apt) for Python 3.
             - Only works with the system Python 2 or Python 3. If you are using a Python on the remote that is not
-               the system Python, set O(install_python_apt=false) and ensure that the Python apt library
-               for your Python version is installed some other way.
+              the system Python, set O(install_python_apt=false) and ensure that the Python apt library
+              for your Python version is installed some other way.
         type: bool
         default: true
 author:
@@ -174,9 +174,9 @@ import glob
 import json
 import os
 import re
+import secrets
 import sys
 import tempfile
-import random
 import time
 
 from ansible.module_utils.basic import AnsibleModule
@@ -504,7 +504,7 @@ class UbuntuSourcesList(SourcesList):
 
         if self.apt_key_bin:
             locale = get_best_parsable_locale(self.module)
-            APT_ENV = dict(LANG=locale, LC_ALL=locale, LC_MESSAGES=locale, LC_CTYPE=locale)
+            APT_ENV = dict(LANG=locale, LC_ALL=locale, LC_MESSAGES=locale, LC_CTYPE=locale, LANGUAGE=locale)
             self.module.run_command_environ_update = APT_ENV
             rc, out, err = self.module.run_command([self.apt_key_bin, 'export', key_fingerprint], check_rc=True)
             found = bool(not err or 'nothing exported' not in err)
@@ -738,29 +738,38 @@ def main():
 
     if changed and not module.check_mode:
         try:
+            err = ''
             sourceslist.save()
             if update_cache:
-                err = ''
                 update_cache_retries = module.params.get('update_cache_retries')
                 update_cache_retry_max_delay = module.params.get('update_cache_retry_max_delay')
-                randomize = random.randint(0, 1000) / 1000.0
+                randomize = secrets.randbelow(1000) / 1000.0
 
+                cache = apt.Cache()
                 for retry in range(update_cache_retries):
                     try:
-                        cache = apt.Cache()
                         cache.update()
                         break
-                    except apt.cache.FetchFailedException as e:
-                        err = to_native(e)
+                    except apt.cache.FetchFailedException as fetch_failed_exc:
+                        err = fetch_failed_exc
+                        module.warn(
+                            f"Failed to update cache after {retry + 1} due "
+                            f"to {to_native(fetch_failed_exc)} retry, retrying"
+                        )
 
                     # Use exponential backoff with a max fail count, plus a little bit of randomness
                     delay = 2 ** retry + randomize
                     if delay > update_cache_retry_max_delay:
                         delay = update_cache_retry_max_delay + randomize
                     time.sleep(delay)
+                    module.warn(f"Sleeping for {int(round(delay))} seconds, before attempting to update the cache again")
                 else:
                     revert_sources_list(sources_before, sources_after, sourceslist_before)
-                    module.fail_json(msg='Failed to update apt cache: %s' % (err if err else 'unknown reason'))
+                    msg = (
+                        f"Failed to update apt cache after {update_cache_retries} retries: "
+                        f"{err if err else 'unknown reason'}"
+                    )
+                    module.fail_json(msg=msg)
 
         except (OSError, IOError) as ex:
             revert_sources_list(sources_before, sources_after, sourceslist_before)

ansible/modules/assemble.py

@@ -61,14 +61,14 @@ options:
     type: str
   ignore_hidden:
     description:
-    - A boolean that controls if files that start with a '.' will be included or not.
+    - A boolean that controls if files that start with a C(.) will be included or not.
     type: bool
     default: no
     version_added: '2.0'
   validate:
     description:
     - The validation command to run before copying into place.
-    - The path to the file to validate is passed in via '%s' which must be present as in the sshd example below.
+    - The path to the file to validate is passed in by C(%s) which must be present as in the sshd example below.
     - The command is passed securely so shell features like expansion and pipes won't work.
     type: str
     version_added: '2.0'
@@ -205,6 +205,11 @@ def main():
             regexp=dict(type='str'),
             ignore_hidden=dict(type='bool', default=False),
             validate=dict(type='str'),
+
+            # Options that are for the action plugin, but ignored by the module itself.
+            # We have them here so that the tests pass without ignores, which
+            # reduces the likelihood of further bugs added.
+            decrypt=dict(type='bool', default=True),
         ),
         add_file_common_args=True,
     )

ansible/modules/assert.py

@@ -17,14 +17,14 @@ version_added: "1.5"
 options:
   that:
     description:
-      - A list of string expressions of the same form that can be passed to the 'when' statement.
+      - A list of string expressions of the same form that can be passed to the C(when) statement.
     type: list
     elements: str
     required: true
   fail_msg:
     description:
       - The customized message used for a failing assertion.
-      - This argument was called 'msg' before Ansible 2.7, now it is renamed to 'fail_msg' with alias 'msg'.
+      - This argument was called O(msg) before Ansible 2.7, now it is renamed to O(fail_msg) with alias O(msg).
     type: str
     aliases: [ msg ]
     version_added: "2.7"
@@ -85,7 +85,7 @@ EXAMPLES = r'''
       - >
         "reject" not in some_command_result.stderr
 
-- name: After version 2.7 both 'msg' and 'fail_msg' can customize failing assertion message
+- name: After version 2.7 both O(msg) and O(fail_msg) can customize failing assertion message
   ansible.builtin.assert:
     that:
       - my_param <= 100
@@ -93,7 +93,7 @@ EXAMPLES = r'''
     fail_msg: "'my_param' must be between 0 and 100"
     success_msg: "'my_param' is between 0 and 100"
 
-- name: Please use 'msg' when ansible version is smaller than 2.7
+- name: Please use O(msg) when ansible version is smaller than 2.7
   ansible.builtin.assert:
     that:
       - my_param <= 100

ansible/modules/blockinfile.py

@@ -33,7 +33,7 @@ options:
   marker:
     description:
     - The marker line template.
-    - C({mark}) will be replaced with the values in O(marker_begin) (default="BEGIN") and O(marker_end) (default="END").
+    - C({mark}) will be replaced with the values in O(marker_begin) (default=C(BEGIN)) and O(marker_end) (default=C(END)).
     - Using a custom marker without the C({mark}) variable may result in the block being repeatedly inserted on subsequent playbook runs.
     - Multi-line markers are not supported and will result in the block being repeatedly inserted on subsequent playbook runs.
     - A newline is automatically appended by the module to O(marker_begin) and O(marker_end).
@@ -50,12 +50,10 @@ options:
     description:
     - If specified and no begin/ending O(marker) lines are found, the block will be inserted after the last match of specified regular expression.
     - A special value is available; V(EOF) for inserting the block at the end of the file.
-    - If specified regular expression has no matches, V(EOF) will be used instead.
+    - If specified regular expression has no matches or no value is passed, V(EOF) will be used instead.
     - The presence of the multiline flag (?m) in the regular expression controls whether the match is done line by line or with multiple lines.
       This behaviour was added in ansible-core 2.14.
     type: str
-    choices: [ EOF, '*regex*' ]
-    default: EOF
   insertbefore:
     description:
     - If specified and no begin/ending O(marker) lines are found, the block will be inserted before the last match of specified regular expression.
@@ -64,7 +62,6 @@ options:
     - The presence of the multiline flag (?m) in the regular expression controls whether the match is done line by line or with multiple lines.
       This behaviour was added in ansible-core 2.14.
     type: str
-    choices: [ BOF, '*regex*' ]
   create:
     description:
     - Create a new file if it does not exist.
@@ -106,7 +103,7 @@ options:
     default: no
     version_added: '2.16'
 notes:
-  - When using 'with_*' loops be aware that if you do not set a unique mark the block will be overwritten on each iteration.
+  - When using C(with_*) loops be aware that if you do not set a unique mark the block will be overwritten on each iteration.
   - As of Ansible 2.3, the O(dest) option has been changed to O(path) as default, but O(dest) still works as well.
   - Option O(ignore:follow) has been removed in Ansible 2.5, because this module modifies the contents of the file
     so O(ignore:follow=no) does not make sense.

ansible/modules/command.py

@@ -50,7 +50,7 @@ options:
   free_form:
     description:
       - The command module takes a free form string as a command to run.
-      - There is no actual parameter named 'free form'.
+      - There is no actual parameter named C(free_form).
   cmd:
     type: str
     description:

ansible/modules/copy.py

@@ -28,8 +28,8 @@ options:
     - Local path to a file to copy to the remote server.
     - This can be absolute or relative.
     - If path is a directory, it is copied recursively. In this case, if path ends
-      with "/", only inside contents of that directory are copied to destination.
-      Otherwise, if it does not end with "/", the directory itself with all contents
+      with C(/), only inside contents of that directory are copied to destination.
+      Otherwise, if it does not end with C(/), the directory itself with all contents
       is copied. This behavior is similar to the C(rsync) command line tool.
     type: path
   content:
@@ -44,7 +44,7 @@ options:
     description:
     - Remote absolute path where the file should be copied to.
     - If O(src) is a directory, this must be a directory too.
-    - If O(dest) is a non-existent path and if either O(dest) ends with "/" or O(src) is a directory, O(dest) is created.
+    - If O(dest) is a non-existent path and if either O(dest) ends with C(/) or O(src) is a directory, O(dest) is created.
     - If O(dest) is a relative path, the starting directory is determined by the remote host.
     - If O(src) and O(dest) are files, the parent directory of O(dest) is not created and the task fails if it does not already exist.
     type: path
@@ -92,7 +92,7 @@ options:
     description:
     - Influence whether O(src) needs to be transferred or already is present remotely.
     - If V(false), it will search for O(src) on the controller node.
-    - If V(true) it will search for O(src) on the managed (remote) node.
+    - If V(true), it will search for O(src) on the managed (remote) node.
     - O(remote_src) supports recursive copying as of version 2.8.
     - O(remote_src) only works with O(mode=preserve) as of version 2.6.
     - Auto-decryption of files does not work when O(remote_src=yes).

ansible/modules/cron.py

@@ -18,19 +18,19 @@ description:
   - Use this module to manage crontab and environment variables entries. This module allows
     you to create environment variables and named crontab entries, update, or delete them.
   - 'When crontab jobs are managed: the module includes one line with the description of the
-    crontab entry C("#Ansible: <name>") corresponding to the "name" passed to the module,
-    which is used by future ansible/module calls to find/check the state. The "name"
-    parameter should be unique, and changing the "name" value will result in a new cron
+    crontab entry C("#Ansible: <name>") corresponding to the O(name) passed to the module,
+    which is used by future ansible/module calls to find/check the state. The O(name)
+    parameter should be unique, and changing the O(name) value will result in a new cron
     task being created (or a different one being removed).'
   - When environment variables are managed, no comment line is added, but, when the module
-    needs to find/check the state, it uses the "name" parameter to find the environment
+    needs to find/check the state, it uses the O(name) parameter to find the environment
     variable definition line.
-  - When using symbols such as %, they must be properly escaped.
+  - When using symbols such as C(%), they must be properly escaped.
 version_added: "0.9"
 options:
   name:
     description:
-      - Description of a crontab entry or, if env is set, the name of environment variable.
+      - Description of a crontab entry or, if O(env) is set, the name of environment variable.
       - This parameter is always required as of ansible-core 2.12.
     type: str
     required: yes
@@ -41,7 +41,7 @@ options:
     type: str
   job:
     description:
-      - The command to execute or, if env is set, the value of environment variable.
+      - The command to execute or, if O(env) is set, the value of environment variable.
       - The command should not contain line breaks.
       - Required if O(state=present).
     type: str
@@ -58,10 +58,10 @@ options:
         The assumption is that this file is exclusively managed by the module,
         do not use if the file contains multiple entries, NEVER use for /etc/crontab.
       - If this is a relative path, it is interpreted with respect to C(/etc/cron.d).
-      - Many linux distros expect (and some require) the filename portion to consist solely
+      - Many Linux distros expect (and some require) the filename portion to consist solely
         of upper- and lower-case letters, digits, underscores, and hyphens.
-      - Using this parameter requires you to specify the O(user) as well, unless O(state) is not V(present).
-      - Either this parameter or O(name) is required
+      - Using this parameter requires you to specify the O(user) as well, unless O(state=absent).
+      - Either this parameter or O(name) is required.
     type: path
   backup:
     description:
@@ -131,6 +131,9 @@ options:
     version_added: "2.1"
 requirements:
   - cron (any 'vixie cron' conformant variant, like cronie)
+notes:
+  - If you are experiencing permissions issues with cron and MacOS,
+    you should see the official MacOS documentation for further information.
 author:
   - Dane Summers (@dsummersl)
   - Mike Grozak (@rhaido)

ansible/modules/deb822_repository.py

@@ -8,28 +8,28 @@ DOCUMENTATION = '''
 author: 'Ansible Core Team (@ansible)'
 short_description: 'Add and remove deb822 formatted repositories'
 description:
-- 'Add and remove deb822 formatted repositories in Debian based distributions'
+- 'Add and remove deb822 formatted repositories in Debian based distributions.'
 module: deb822_repository
 notes:
-- This module will not automatically update caches, call the apt module based
+- This module will not automatically update caches, call the M(ansible.builtin.apt) module based
   on the changed state.
 options:
     allow_downgrade_to_insecure:
         description:
         - Allow downgrading a package that was previously authenticated but
-          is no longer authenticated
+          is no longer authenticated.
         type: bool
     allow_insecure:
         description:
-        - Allow insecure repositories
+        - Allow insecure repositories.
         type: bool
     allow_weak:
         description:
-        - Allow repositories signed with a key using a weak digest algorithm
+        - Allow repositories signed with a key using a weak digest algorithm.
         type: bool
     architectures:
         description:
-        - 'Architectures to search within repository'
+        - Architectures to search within repository.
         type: list
         elements: str
     by_hash:
@@ -51,7 +51,7 @@ options:
     components:
         description:
         - Components specify different sections of one distribution version
-          present in a Suite.
+          present in a C(Suite).
         type: list
         elements: str
     date_max_future:
@@ -64,8 +64,8 @@ options:
         type: bool
     inrelease_path:
         description:
-        - Determines the path to the InRelease file, relative to the normal
-          position of an InRelease file.
+        - Determines the path to the C(InRelease) file, relative to the normal
+          position of an C(InRelease) file.
         type: str
     languages:
         description:
@@ -81,8 +81,8 @@ options:
         type: str
     pdiffs:
         description:
-        - Controls if APT should try to use PDiffs to update old indexes
-          instead of downloading the new indexes entirely
+        - Controls if APT should try to use C(PDiffs) to update old indexes
+          instead of downloading the new indexes entirely.
         type: bool
     signed_by:
         description:
@@ -97,21 +97,20 @@ options:
           Suite can specify an exact path in relation to the URI(s) provided,
           in which case the Components: must be omitted and suite must end
           with a slash (C(/)). Alternatively, it may take the form of a
-          distribution version (e.g. a version codename like disco or artful).
+          distribution version (for example a version codename like C(disco) or C(artful)).
           If the suite does not specify a path, at least one component must
           be present.
         type: list
         elements: str
     targets:
         description:
-        - Defines which download targets apt will try to acquire from this
-          source.
+        - Defines which download targets apt will try to acquire from this source.
         type: list
         elements: str
     trusted:
         description:
         - Decides if a source is considered trusted or if warnings should be
-          raised before e.g. packages are installed from this source.
+          raised before, for example packages are installed from this source.
         type: bool
     types:
         choices:
@@ -123,7 +122,7 @@ options:
         elements: str
         description:
         - Which types of packages to look for from a given source; either
-          binary V(deb) or source code V(deb-src)
+          binary V(deb) or source code V(deb-src).
     uris:
         description:
         - The URIs must specify the base of the Debian distribution archive,
@@ -132,7 +131,7 @@ options:
         elements: str
     mode:
         description:
-        - The octal mode for newly created files in sources.list.d.
+        - The octal mode for newly created files in C(sources.list.d).
         type: raw
         default: '0644'
     state:

ansible/modules/debconf.py

@@ -29,24 +29,24 @@ notes:
     - Several questions have to be answered (depending on the package).
       Use 'debconf-show <package>' on any Debian or derivative with the package
       installed to see questions/settings available.
-    - Some distros will always record tasks involving the setting of passwords as changed. This is due to debconf-get-selections masking passwords.
+    - Some distros will always record tasks involving the setting of passwords as changed. This is due to C(debconf-get-selections) masking passwords.
     - It is highly recommended to add C(no_log=True) to the task while handling sensitive information using this module.
-    - The debconf module does not reconfigure packages, it just updates the debconf database.
+    - The M(ansible.builtin.debconf) module does not reconfigure packages, it just updates the debconf database.
       An additional step is needed (typically with C(notify) if debconf makes a change)
       to reconfigure the package and apply the changes.
-      debconf is extensively used for pre-seeding configuration prior to installation
+      C(debconf) is extensively used for pre-seeding configuration prior to installation
       rather than modifying configurations.
-      So, while dpkg-reconfigure does use debconf data, it is not always authoritative
+      So, while C(dpkg-reconfigure) does use debconf data, it is not always authoritative
       and you may need to check how your package is handled.
-    - Also note dpkg-reconfigure is a 3-phase process. It invokes the
+    - Also note C(dpkg-reconfigure) is a 3-phase process. It invokes the
       control scripts from the C(/var/lib/dpkg/info) directory with the
       C(<package>.prerm  reconfigure <version>),
       C(<package>.config reconfigure <version>) and C(<package>.postinst control <version>) arguments.
     - The main issue is that the C(<package>.config reconfigure) step for many packages
       will first reset the debconf database (overriding changes made by this module) by
       checking the on-disk configuration. If this is the case for your package then
-      dpkg-reconfigure will effectively ignore changes made by debconf.
-    - However as dpkg-reconfigure only executes the C(<package>.config) step if the file
+      C(dpkg-reconfigure) will effectively ignore changes made by debconf.
+    - However as C(dpkg-reconfigure) only executes the C(<package>.config) step if the file
       exists, it is possible to rename it to C(/var/lib/dpkg/info/<package>.config.ignore)
       before executing C(dpkg-reconfigure -f noninteractive <package>) and then restore it.
       This seems to be compliant with Debian policy for the .config file.
@@ -76,12 +76,12 @@ options:
   value:
     description:
       - Value to set the configuration to.
-      - After Ansible 2.17, C(value) is of type 'raw'.
+      - After Ansible 2.17, C(value) is of type C(raw).
     type: raw
     aliases: [ answer ]
   unseen:
     description:
-      - Do not set 'seen' flag when pre-seeding.
+      - Do not set C(seen) flag when pre-seeding.
     type: bool
     default: false
 author:

ansible/modules/debug.py

@@ -14,7 +14,7 @@ description:
 - This module prints statements during execution and can be useful
   for debugging variables or expressions without necessarily halting
   the playbook.
-- Useful for debugging together with the 'when:' directive.
+- Useful for debugging together with the C(when:) directive.
 - This module is also supported for Windows targets.
 version_added: '0.8'
 options: