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

ansible/modules/dpkg_selections.py

@@ -11,7 +11,7 @@ DOCUMENTATION = '''
 module: dpkg_selections
 short_description: Dpkg package selection selections
 description:
-    - Change dpkg package selection state via --get-selections and --set-selections.
+    - Change dpkg package selection state via C(--get-selections) and C(--set-selections).
 version_added: "2.0"
 author:
 - Brian Brazil (@brian-brazil)  <brian.brazil@boxever.com>
@@ -68,7 +68,7 @@ def main():
     dpkg = module.get_bin_path('dpkg', True)
 
     locale = get_best_parsable_locale(module)
-    DPKG_ENV = dict(LANG=locale, LC_ALL=locale, LC_MESSAGES=locale, LC_CTYPE=locale)
+    DPKG_ENV = dict(LANG=locale, LC_ALL=locale, LC_MESSAGES=locale, LC_CTYPE=locale, LANGUAGE=locale)
     module.run_command_environ_update = DPKG_ENV
 
     name = module.params['name']

ansible/modules/expect.py

@@ -70,10 +70,10 @@ notes:
   - If you want to run a command through the shell (say you are using C(<),
     C(>), C(|), and so on), you must specify a shell in the command such as
     C(/bin/bash -c "/path/to/something | grep else").
-  - Case insensitive searches are indicated with a prefix of C(?i).
+  - Case insensitive searches are indicated with a prefix of C((?i)).
   - The C(pexpect) library used by this module operates with a search window
     of 2000 bytes, and does not use a multiline regex match. To perform a
-    start of line bound match, use a pattern like ``(?m)^pattern``
+    start of line bound match, use a pattern like C((?m)^pattern).
   - The M(ansible.builtin.expect) module is designed for simple scenarios.
     For more complex needs, consider the use of expect code with the M(ansible.builtin.shell)
     or M(ansible.builtin.script) modules. (An example is part of the M(ansible.builtin.shell) module documentation).

ansible/modules/fetch.py

@@ -28,8 +28,8 @@ options:
   dest:
     description:
     - A directory to save the file into.
-    - For example, if the O(dest) directory is C(/backup) a O(src) file named C(/etc/profile) on host
-      C(host.example.com), would be saved into C(/backup/host.example.com/etc/profile).
+    - For example, if O(dest=/backup), then O(src=/etc/profile) on host
+      C(host.example.com), would save the file into C(/backup/host.example.com/etc/profile).
       The host name is based on the inventory name.
     required: yes
   fail_on_missing:

ansible/modules/file.py

@@ -63,9 +63,9 @@ options:
   force:
     description:
     - >
-      Force the creation of the symlinks in two cases: the source file does
+      Force the creation of the links in two cases: if the link type is symbolic and the source file does
       not exist (but will appear later); the destination exists and is a file (so, we need to unlink the
-      O(path) file and create a symlink to the O(src) file in place of it).
+      O(path) file and create a link to the O(src) file in place of it).
     type: bool
     default: no
   follow:
@@ -73,7 +73,7 @@ options:
     - This flag indicates that filesystem links, if they exist, should be followed.
     - O(follow=yes) and O(state=link) can modify O(src) when combined with parameters such as O(mode).
     - Previous to Ansible 2.5, this was V(false) by default.
-    - While creating a symlink with a non-existent destination, set O(follow) to V(false) to avoid a warning message related to permission issues.
+    - While creating a symlink with a non-existent destination, set O(follow=false) to avoid a warning message related to permission issues.
       The warning message is added to notify the user that we can not set permissions to the non-existent destination.
     type: bool
     default: yes
@@ -872,6 +872,8 @@ def ensure_hardlink(path, src, follow, force, timestamps):
                                                   'path': path})
         else:
             try:
+                if follow and os.path.islink(b_src):
+                    b_src = os.readlink(b_src)
                 os.link(b_src, b_path)
             except OSError as e:
                 raise AnsibleModuleError(results={'msg': 'Error while linking: %s'

ansible/modules/find.py

@@ -58,8 +58,8 @@ options:
     contains:
         description:
             - A regular expression or pattern which should be matched against the file content.
-            - If O(read_whole_file) is V(false) it matches against the beginning of the line (uses
-              V(re.match(\))). If O(read_whole_file) is V(true), it searches anywhere for that pattern
+            - If O(read_whole_file=false) it matches against the beginning of the line (uses
+              V(re.match(\))). If O(read_whole_file=true), it searches anywhere for that pattern
               (uses V(re.search(\))).
             - Works only when O(file_type) is V(file).
         type: str
@@ -75,14 +75,15 @@ options:
     paths:
         description:
             - List of paths of directories to search. All paths must be fully qualified.
+            - From ansible-core 2.18 and onwards, the data type has changed from C(str) to C(path).
         type: list
         required: true
         aliases: [ name, path ]
-        elements: str
+        elements: path
     file_type:
         description:
             - Type of file to select.
-            - The 'link' and 'any' choices were added in Ansible 2.3.
+            - The V(link) and V(any) choices were added in Ansible 2.3.
         type: str
         choices: [ any, directory, file, link ]
         default: file
@@ -116,7 +117,7 @@ options:
               restricted to modes that can be applied using the python
               C(os.chmod) function.
             - The mode can be provided as an octal such as V("0644") or
-              as symbolic such as V(u=rw,g=r,o=r)
+              as symbolic such as V(u=rw,g=r,o=r).
         type: raw
         version_added: '2.16'
     exact_mode:
@@ -145,15 +146,23 @@ options:
     depth:
         description:
             - Set the maximum number of levels to descend into.
-            - Setting recurse to V(false) will override this value, which is effectively depth 1.
+            - Setting O(recurse=false) will override this value, which is effectively depth 1.
             - Default is unlimited depth.
         type: int
         version_added: "2.6"
     encoding:
         description:
-            - When doing a C(contains) search, determine the encoding of the files to be searched.
+            - When doing a O(contains) search, determine the encoding of the files to be searched.
         type: str
         version_added: "2.17"
+    limit:
+        description:
+            - Limit the maximum number of matching paths returned. After finding this many, the find action will stop looking.
+            - Matches are made from the top, down (i.e. shallowest directory first).
+            - If not set, or set to v(null), it will do unlimited matches.
+            - Default is unlimited matches.
+        type: int
+        version_added: "2.18"
 extends_documentation_fragment: action_common_attributes
 attributes:
     check_mode:
@@ -227,6 +236,16 @@ EXAMPLES = r'''
       - '^_[0-9]{2,4}_.*.log$'
       - '^[a-z]{1,5}_.*log$'
 
+- name: Find file containing "wally" without necessarily reading all files
+  ansible.builtin.find:
+    paths: /var/log
+    file_type: file
+    contains: wally
+    read_whole_file: true
+    patterns: "^.*\\.log$"
+    use_regex: true
+    recurse: true
+    limit: 1
 '''
 
 RETURN = r'''
@@ -450,7 +469,7 @@ def statinfo(st):
 def main():
     module = AnsibleModule(
         argument_spec=dict(
-            paths=dict(type='list', required=True, aliases=['name', 'path'], elements='str'),
+            paths=dict(type='list', required=True, aliases=['name', 'path'], elements='path'),
             patterns=dict(type='list', default=[], aliases=['pattern'], elements='str'),
             excludes=dict(type='list', aliases=['exclude'], elements='str'),
             contains=dict(type='str'),
@@ -467,7 +486,8 @@ def main():
             depth=dict(type='int'),
             mode=dict(type='raw'),
             exact_mode=dict(type='bool', default=True),
-            encoding=dict(type='str')
+            encoding=dict(type='str'),
+            limit=dict(type='int')
         ),
         supports_check_mode=True,
     )
@@ -520,17 +540,20 @@ def main():
         else:
             module.fail_json(size=params['size'], msg="failed to process size")
 
+    if params['limit'] is not None and params['limit'] <= 0:
+        module.fail_json(msg="limit cannot be %d (use None for unlimited)" % params['limit'])
+
     now = time.time()
     msg = 'All paths examined'
     looked = 0
     has_warnings = False
     for npath in params['paths']:
-        npath = os.path.expanduser(os.path.expandvars(npath))
         try:
             if not os.path.isdir(npath):
                 raise Exception("'%s' is not a directory" % to_native(npath))
 
-            for root, dirs, files in os.walk(npath, onerror=handle_walk_errors, followlinks=params['follow']):
+            # Setting `topdown=True` to explicitly guarantee matches are made from the shallowest directory first
+            for root, dirs, files in os.walk(npath, onerror=handle_walk_errors, followlinks=params['follow'], topdown=True):
                 looked = looked + len(files) + len(dirs)
                 for fsobj in (files + dirs):
                     fsname = os.path.normpath(os.path.join(root, fsobj))
@@ -596,7 +619,12 @@ def main():
                             r.update(statinfo(st))
                             filelist.append(r)
 
-                if not params['recurse']:
+                    if len(filelist) == params["limit"]:
+                        # Breaks out of directory files loop only
+                        msg = "Limit of matches reached"
+                        break
+
+                if not params['recurse'] or len(filelist) == params["limit"]:
                     break
         except Exception as e:
             skipped[npath] = to_text(e)

ansible/modules/gather_facts.py

@@ -27,6 +27,8 @@ options:
             - By default it will be true if more than one fact module is used.
             - For low cost/delay fact modules parallelism overhead might end up meaning the whole process takes longer.
               Test your specific case to see if it is a speed improvement or not.
+            - The C(ansible_facts_parallel) variable can be used to set this option,
+              overriding the default, but not the direct assignment of the option in the task.
         type: bool
 attributes:
     action:
@@ -49,8 +51,8 @@ attributes:
 notes:
     - This is mostly a wrapper around other fact gathering modules.
     - Options passed into this action must be supported by all the underlying fact modules configured.
-    - If using C(gather_timeout) and parallel execution, it will limit the total execution time of
-      modules that do not accept C(gather_timeout) themselves.
+    - If using O(ignore:gather_timeout) and parallel execution, it will limit the total execution time of
+      modules that do not accept O(ignore:gather_timeout) themselves.
     - Facts returned by each module will be merged, conflicts will favor 'last merged'.
       Order is not guaranteed, when doing parallel gathering on multiple modules.
 author:

ansible/modules/get_url.py

@@ -13,7 +13,7 @@ short_description: Downloads files from HTTP, HTTPS, or FTP to node
 description:
      - Downloads files from HTTP, HTTPS, or FTP to the remote server. The remote
        server I(must) have direct access to the remote resource.
-     - By default, if an environment variable C(<protocol>_proxy) is set on
+     - By default, if an environment variable E(<protocol>_proxy) is set on
        the target host, requests will be sent through that proxy. This
        behaviour can be overridden by setting a variable for this task
        (see R(setting the environment,playbooks_environment)),
@@ -27,23 +27,23 @@ version_added: '0.6'
 options:
   ciphers:
     description:
-      - SSL/TLS Ciphers to use for the request
-      - 'When a list is provided, all ciphers are joined in order with V(:)'
+      - SSL/TLS Ciphers to use for the request.
+      - 'When a list is provided, all ciphers are joined in order with C(:).'
       - See the L(OpenSSL Cipher List Format,https://www.openssl.org/docs/manmaster/man1/openssl-ciphers.html#CIPHER-LIST-FORMAT)
         for more details.
-      - The available ciphers is dependent on the Python and OpenSSL/LibreSSL versions
+      - The available ciphers is dependent on the Python and OpenSSL/LibreSSL versions.
     type: list
     elements: str
     version_added: '2.14'
   decompress:
     description:
-      - Whether to attempt to decompress gzip content-encoded responses
+      - Whether to attempt to decompress gzip content-encoded responses.
     type: bool
     default: true
     version_added: '2.14'
   url:
     description:
-      - HTTP, HTTPS, or FTP URL in the form (http|https|ftp)://[user[:pass]]@host.domain[:port]/path
+      - HTTP, HTTPS, or FTP URL in the form C((http|https|ftp)://[user[:pass]]@host.domain[:port]/path).
     type: str
     required: true
   dest:
@@ -60,9 +60,9 @@ options:
   tmp_dest:
     description:
       - Absolute path of where temporary file is downloaded to.
-      - When run on Ansible 2.5 or greater, path defaults to ansible's remote_tmp setting
+      - When run on Ansible 2.5 or greater, path defaults to ansible's C(remote_tmp) setting.
       - When run on Ansible prior to 2.5, it defaults to E(TMPDIR), E(TEMP) or E(TMP) env variables or a platform specific value.
-      - U(https://docs.python.org/3/library/tempfile.html#tempfile.tempdir)
+      - U(https://docs.python.org/3/library/tempfile.html#tempfile.tempdir).
     type: path
     version_added: '2.1'
   force:
@@ -87,18 +87,20 @@ options:
       - 'If a checksum is passed to this parameter, the digest of the
         destination file will be calculated after it is downloaded to ensure
         its integrity and verify that the transfer completed successfully.
-        Format: <algorithm>:<checksum|url>, e.g. checksum="sha256:D98291AC[...]B6DC7B97",
-        checksum="sha256:http://example.com/path/sha256sum.txt"'
+        Format: <algorithm>:<checksum|url>, for example C(checksum="sha256:D98291AC[...]B6DC7B97",
+        C(checksum="sha256:http://example.com/path/sha256sum.txt").'
       - If you worry about portability, only the sha1 algorithm is available
         on all platforms and python versions.
-      - The Python ``hashlib`` module is responsible for providing the available algorithms.
+      - The Python C(hashlib) module is responsible for providing the available algorithms.
         The choices vary based on Python version and OpenSSL version.
-      - On systems running in FIPS compliant mode, the ``md5`` algorithm may be unavailable.
+      - On systems running in FIPS compliant mode, the C(md5) algorithm may be unavailable.
       - Additionally, if a checksum is passed to this parameter, and the file exist under
         the O(dest) location, the C(destination_checksum) would be calculated, and if
         checksum equals C(destination_checksum), the file download would be skipped
-        (unless O(force) is V(true)). If the checksum does not equal C(destination_checksum),
+        (unless O(force=true)). If the checksum does not equal C(destination_checksum),
         the destination file is deleted.
+      - If the checksum URL requires username and password, O(url_username) and O(url_password) are used
+        to download the checksum file.
     type: str
     default: ''
     version_added: "2.0"
@@ -185,16 +187,16 @@ options:
         authentication.
       - Requires the Python library L(gssapi,https://github.com/pythongssapi/python-gssapi) to be installed.
       - Credentials for GSSAPI can be specified with O(url_username)/O(url_password) or with the GSSAPI env var
-        C(KRB5CCNAME) that specified a custom Kerberos credential cache.
+        E(KRB5CCNAME) that specified a custom Kerberos credential cache.
       - NTLM authentication is I(not) supported even if the GSSAPI mech for NTLM has been installed.
     type: bool
     default: no
     version_added: '2.11'
   use_netrc:
     description:
-      - Determining whether to use credentials from ``~/.netrc`` file
-      - By default .netrc is used with Basic authentication headers
-      - When set to False, .netrc credentials are ignored
+      - Determining whether to use credentials from C(~/.netrc) file.
+      - By default C(.netrc) is used with Basic authentication headers.
+      - When V(false), C(.netrc) credentials are ignored.
     type: bool
     default: true
     version_added: '2.14'
@@ -661,6 +663,16 @@ def main():
                              result['checksum_src'] != result['checksum_dest'])
         module.exit_json(msg=info.get('msg', ''), **result)
 
+    # If a checksum was provided, ensure that the temporary file matches this checksum
+    # before moving it to the destination.
+    if checksum != '':
+        tmpsrc_checksum = module.digest_from_file(tmpsrc, algorithm)
+
+        if checksum != tmpsrc_checksum:
+            os.remove(tmpsrc)
+            module.fail_json(msg=f"The checksum for {tmpsrc} did not match {checksum}; it was {tmpsrc_checksum}.", **result)
+
+    # Copy temporary file to destination if necessary
     backup_file = None
     if result['checksum_src'] != result['checksum_dest']:
         try:
@@ -679,13 +691,6 @@ def main():
         if os.path.exists(tmpsrc):
             os.remove(tmpsrc)
 
-    if checksum != '':
-        destination_checksum = module.digest_from_file(dest, algorithm)
-
-        if checksum != destination_checksum:
-            os.remove(dest)
-            module.fail_json(msg="The checksum for %s did not match %s; it was %s." % (dest, checksum, destination_checksum), **result)
-
     # allow file attribute changes
     file_args = module.load_file_common_arguments(module.params, path=dest)
     result['changed'] = module.set_fs_attributes_if_different(file_args, result['changed'])

ansible/modules/git.py

@@ -42,19 +42,19 @@ options:
         default: "HEAD"
     accept_hostkey:
         description:
-            - Will ensure or not that "-o StrictHostKeyChecking=no" is present as an ssh option.
+            - Will ensure or not that C(-o StrictHostKeyChecking=no) is present as an ssh option.
             - Be aware that this disables a protection against MITM attacks.
-            - Those using OpenSSH >= 7.5 might want to set O(ssh_opts) to V(StrictHostKeyChecking=accept-new)
+            - Those using OpenSSH >= 7.5 might want to use O(accept_newhostkey) or set O(ssh_opts) to V(StrictHostKeyChecking=accept-new)
               instead, it does not remove the MITM issue but it does restrict it to the first attempt.
         type: bool
         default: 'no'
         version_added: "1.5"
     accept_newhostkey:
         description:
-            - As of OpenSSH 7.5, "-o StrictHostKeyChecking=accept-new" can be
+            - As of OpenSSH 7.5, C(-o StrictHostKeyChecking=accept-new) can be
               used which is safer and will only accepts host keys which are
-              not present or are the same. if V(true), ensure that
-              "-o StrictHostKeyChecking=accept-new" is present as an ssh option.
+              not present or are the same. If V(true), ensure that
+              C(-o StrictHostKeyChecking=accept-new) is present as an ssh option.
         type: bool
         default: 'no'
         version_added: "2.12"
@@ -65,21 +65,21 @@ options:
             - For older versions it appends E(GIT_SSH_OPTS) (specific to this module) to the
               variables above or via a wrapper script.
             - Other options can add to this list, like O(key_file) and O(accept_hostkey).
-            - An example value could be "-o StrictHostKeyChecking=no" (although this particular
+            - An example value could be C(-o StrictHostKeyChecking=no) (although this particular
               option is better set by O(accept_hostkey)).
-            - The module ensures that 'BatchMode=yes' is always present to avoid prompts.
+            - The module ensures that C(BatchMode=yes) is always present to avoid prompts.
         type: str
         version_added: "1.5"
 
     key_file:
         description:
             - Specify an optional private key file path, on the target host, to use for the checkout.
-            - This ensures 'IdentitiesOnly=yes' is present in O(ssh_opts).
+            - This ensures C(IdentitiesOnly=yes) is present in O(ssh_opts).
         type: path
         version_added: "1.5"
     reference:
         description:
-            - Reference repository (see "git clone --reference ...").
+            - Reference repository (see C(git clone --reference ...)).
         type: str
         version_added: "1.4"
     remote:
@@ -165,7 +165,7 @@ options:
     track_submodules:
         description:
             - If V(true), submodules will track the latest commit on their
-              master branch (or other branch specified in .gitmodules).  If
+              master branch (or other branch specified in C(.gitmodules)).  If
               V(false), submodules will be kept at the revision specified by the
               main project. This is equivalent to specifying the C(--remote) flag
               to git submodule update.
@@ -235,63 +235,63 @@ notes:
       SSH will prompt user to authorize the first contact with a remote host.  To avoid this prompt,
       one solution is to use the option accept_hostkey. Another solution is to
       add the remote host public key in C(/etc/ssh/ssh_known_hosts) before calling
-      the git module, with the following command: ssh-keyscan -H remote_host.com >> /etc/ssh/ssh_known_hosts."
+      the git module, with the following command: C(ssh-keyscan -H remote_host.com >> /etc/ssh/ssh_known_hosts)."
 '''
 
 EXAMPLES = '''
 - name: Git checkout
   ansible.builtin.git:
-    repo: 'https://foosball.example.org/path/to/repo.git'
-    dest: /srv/checkout
+    repo: 'https://github.com/ansible/ansible.git'
+    dest: /tmp/checkout
     version: release-0.22
 
 - name: Read-write git checkout from github
   ansible.builtin.git:
-    repo: git@github.com:mylogin/hello.git
-    dest: /home/mylogin/hello
+    repo: git@github.com:ansible/ansible.git
+    dest: /tmp/checkout
 
 - name: Just ensuring the repo checkout exists
   ansible.builtin.git:
-    repo: 'https://foosball.example.org/path/to/repo.git'
-    dest: /srv/checkout
+    repo: 'https://github.com/ansible/ansible.git'
+    dest: /tmp/checkout
     update: no
 
 - name: Just get information about the repository whether or not it has already been cloned locally
   ansible.builtin.git:
-    repo: 'https://foosball.example.org/path/to/repo.git'
-    dest: /srv/checkout
+    repo: git@github.com:ansible/ansible.git
+    dest: /tmp/checkout
     clone: no
     update: no
 
 - name: Checkout a github repo and use refspec to fetch all pull requests
   ansible.builtin.git:
-    repo: https://github.com/ansible/ansible-examples.git
-    dest: /src/ansible-examples
+    repo: 'https://github.com/ansible/ansible.git'
+    dest: /tmp/checkout
     refspec: '+refs/pull/*:refs/heads/*'
 
 - name: Create git archive from repo
   ansible.builtin.git:
-    repo: https://github.com/ansible/ansible-examples.git
-    dest: /src/ansible-examples
-    archive: /tmp/ansible-examples.zip
+    repo: git@github.com:ansible/ansible.git
+    dest: /tmp/checkout
+    archive: /tmp/ansible.zip
 
 - name: Clone a repo with separate git directory
   ansible.builtin.git:
-    repo: https://github.com/ansible/ansible-examples.git
-    dest: /src/ansible-examples
-    separate_git_dir: /src/ansible-examples.git
+    repo: 'https://github.com/ansible/ansible.git'
+    dest: /tmp/checkout
+    separate_git_dir: /tmp/repo
 
 - name: Example clone of a single branch
   ansible.builtin.git:
-    repo: https://github.com/ansible/ansible-examples.git
-    dest: /src/ansible-examples
+    repo: git@github.com:ansible/ansible.git
+    dest: /tmp/checkout
     single_branch: yes
     version: master
 
 - name: Avoid hanging when http(s) password is missing
   ansible.builtin.git:
-    repo: https://github.com/ansible/could-be-a-private-repo
-    dest: /src/from-private-repo
+    repo: 'https://github.com/ansible/ansible.git'
+    dest: /tmp/checkout
   environment:
     GIT_TERMINAL_PROMPT: 0 # reports "terminal prompts disabled" on missing password
     # or GIT_ASKPASS: /bin/true # for git before version 2.3.0, reports "Authentication failed" on missing password
@@ -468,7 +468,7 @@ def write_ssh_wrapper(module):
 def set_git_ssh_env(key_file, ssh_opts, git_version, module):
     '''
         use environment variables to configure git's ssh execution,
-        which varies by version but this functino should handle all.
+        which varies by version but this function should handle all.
     '''
 
     # initialise to existing ssh opts and/or append user provided
@@ -500,7 +500,7 @@ def set_git_ssh_env(key_file, ssh_opts, git_version, module):
     # older than 2.3 does not know how to use git_ssh_command,
     # so we force it into get_ssh var
     # https://github.com/gitster/git/commit/09d60d785c68c8fa65094ecbe46fbc2a38d0fc1f
-    if git_version < LooseVersion('2.3.0'):
+    if git_version is not None and git_version < LooseVersion('2.3.0'):
         # for use in wrapper
         os.environ["GIT_SSH_OPTS"] = ssh_opts
 
@@ -913,7 +913,7 @@ def fetch(git_path, module, repo, dest, version, remote, depth, bare, refspec, g
             refspecs = ['+refs/heads/*:refs/heads/*', '+refs/tags/*:refs/tags/*']
         else:
             # ensure all tags are fetched
-            if git_version_used >= LooseVersion('1.9'):
+            if git_version_used is not None and git_version_used >= LooseVersion('1.9'):
                 fetch_cmd.append('--tags')
             else:
                 # old git versions have a bug in --tags that prevents updating existing tags
@@ -1308,7 +1308,7 @@ def main():
     # GIT_SSH=<path> as an environment variable, might create sh wrapper script for older versions.
     set_git_ssh_env(key_file, ssh_opts, git_version_used, module)
 
-    if depth is not None and git_version_used < LooseVersion('1.9.1'):
+    if depth is not None and git_version_used is not None and git_version_used < LooseVersion('1.9.1'):
         module.warn("git version is too old to fully support the depth argument. Falling back to full checkouts.")
         depth = None