ansible-core 2.15.4rc1__py3-none-any.whl → 2.16.0b2__py3-none-any.whl

ansible/modules/command.py

@@ -14,7 +14,7 @@ module: command
 short_description: Execute commands on targets
 version_added: historical
 description:
-     - The C(command) module takes the command name followed by a list of space-delimited arguments.
+     - The M(ansible.builtin.command) module takes the command name followed by a list of space-delimited arguments.
      - The given command will be executed on all selected nodes.
      - The command(s) will not be
        processed through the shell, so variables like C($HOSTNAME) and operations
@@ -22,15 +22,15 @@ description:
        Use the M(ansible.builtin.shell) module if you need these features.
      - To create C(command) tasks that are easier to read than the ones using space-delimited
        arguments, pass parameters using the C(args) L(task keyword,https://docs.ansible.com/ansible/latest/reference_appendices/playbooks_keywords.html#task)
-       or use C(cmd) parameter.
-     - Either a free form command or C(cmd) parameter is required, see the examples.
+       or use O(cmd) parameter.
+     - Either a free form command or O(cmd) parameter is required, see the examples.
      - For Windows targets, use the M(ansible.windows.win_command) module instead.
 extends_documentation_fragment:
     - action_common_attributes
     - action_common_attributes.raw
 attributes:
     check_mode:
-        details: while the command itself is arbitrary and cannot be subject to the check mode semantics it adds C(creates)/C(removes) options as a workaround
+        details: while the command itself is arbitrary and cannot be subject to the check mode semantics it adds O(creates)/O(removes) options as a workaround
         support: partial
     diff_mode:
         support: none
@@ -40,6 +40,14 @@ attributes:
     raw:
       support: full
 options:
+  expand_argument_vars:
+    description:
+      - Expands the arguments that are variables, for example C($HOME) will be expanded before being passed to the
+        command to run.
+      - Set to V(false) to disable expansion and treat the value as a literal argument.
+    type: bool
+    default: true
+    version_added: "2.16"
   free_form:
     description:
       - The command module takes a free form string as a command to run.
@@ -53,19 +61,19 @@ options:
     elements: str
     description:
       - Passes the command as a list rather than a string.
-      - Use C(argv) to avoid quoting values that would otherwise be interpreted incorrectly (for example "user name").
+      - Use O(argv) to avoid quoting values that would otherwise be interpreted incorrectly (for example "user name").
       - Only the string (free form) or the list (argv) form can be provided, not both.  One or the other must be provided.
     version_added: "2.6"
   creates:
     type: path
     description:
       - A filename or (since 2.0) glob pattern. If a matching file already exists, this step B(will not) be run.
-      - This is checked before I(removes) is checked.
+      - This is checked before O(removes) is checked.
   removes:
     type: path
     description:
       - A filename or (since 2.0) glob pattern. If a matching file exists, this step B(will) be run.
-      - This is checked after I(creates) is checked.
+      - This is checked after O(creates) is checked.
     version_added: "0.8"
   chdir:
     type: path
@@ -81,7 +89,7 @@ options:
     type: bool
     default: yes
     description:
-      - If set to C(true), append a newline to stdin data.
+      - If set to V(true), append a newline to stdin data.
     version_added: "2.8"
   strip_empty_ends:
     description:
@@ -93,12 +101,12 @@ notes:
     -  If you want to run a command through the shell (say you are using C(<), C(>), C(|), and so on),
        you actually want the M(ansible.builtin.shell) module instead.
        Parsing shell metacharacters can lead to unexpected commands being executed if quoting is not done correctly so it is more secure to
-       use the C(command) module when possible.
-    -  C(creates), C(removes), and C(chdir) can be specified after the command.
+       use the M(ansible.builtin.command) module when possible.
+    -  O(creates), O(removes), and O(chdir) can be specified after the command.
        For instance, if you only want to run a command if a certain file does not exist, use this.
-    -  Check mode is supported when passing C(creates) or C(removes). If running in check mode and either of these are specified, the module will
+    -  Check mode is supported when passing O(creates) or O(removes). If running in check mode and either of these are specified, the module will
        check for the existence of the file and report the correct changed status. If these are not supplied, the task will be skipped.
-    -  The C(executable) parameter is removed since version 2.4. If you have a need for this parameter, use the M(ansible.builtin.shell) module instead.
+    -  The O(ignore:executable) parameter is removed since version 2.4. If you have a need for this parameter, use the M(ansible.builtin.shell) module instead.
     -  For Windows targets, use the M(ansible.windows.win_command) module instead.
     -  For rebooting systems, use the M(ansible.builtin.reboot) or M(ansible.windows.win_reboot) module.
     -  If the command returns non UTF-8 data, it must be encoded to avoid issues. This may necessitate using M(ansible.builtin.shell) so the output
@@ -153,6 +161,17 @@ EXAMPLES = r'''
       - dbname with whitespace
     creates: /path/to/database
 
+- name: Run command using argv with mixed argument formats
+  ansible.builtin.command:
+    argv:
+      - /path/to/binary
+      - -v
+      - --debug
+      - --longopt
+      - value for longopt
+      - --other-longopt=value for other longopt
+      - positional
+
 - name: Safely use templated variable to run command. Always use the quote filter to avoid injection issues
   ansible.builtin.command: cat {{ myfile|quote }}
   register: myoutput
@@ -219,7 +238,7 @@ import os
 import shlex
 
 from ansible.module_utils.basic import AnsibleModule
-from ansible.module_utils._text import to_native, to_bytes, to_text
+from ansible.module_utils.common.text.converters import to_native, to_bytes, to_text
 from ansible.module_utils.common.collections import is_iterable
 
 
@@ -235,6 +254,7 @@ def main():
             argv=dict(type='list', elements='str'),
             chdir=dict(type='path'),
             executable=dict(),
+            expand_argument_vars=dict(type='bool', default=True),
             creates=dict(type='path'),
             removes=dict(type='path'),
             # The default for this really comes from the action plugin
@@ -254,8 +274,9 @@ def main():
     stdin = module.params['stdin']
     stdin_add_newline = module.params['stdin_add_newline']
     strip = module.params['strip_empty_ends']
+    expand_argument_vars = module.params['expand_argument_vars']
 
-    # we promissed these in 'always' ( _lines get autoaded on action plugin)
+    # we promised these in 'always' ( _lines get auto-added on action plugin)
     r = {'changed': False, 'stdout': '', 'stderr': '', 'rc': None, 'cmd': None, 'start': None, 'end': None, 'delta': None, 'msg': ''}
 
     if not shell and executable:
@@ -321,7 +342,8 @@ def main():
     if not module.check_mode:
         r['start'] = datetime.datetime.now()
         r['rc'], r['stdout'], r['stderr'] = module.run_command(args, executable=executable, use_unsafe_shell=shell, encoding=None,
-                                                               data=stdin, binary_data=(not stdin_add_newline))
+                                                               data=stdin, binary_data=(not stdin_add_newline),
+                                                               expand_user_and_vars=expand_argument_vars)
         r['end'] = datetime.datetime.now()
     else:
         # this is partial check_mode support, since we end up skipping if we get here

ansible/modules/copy.py

@@ -14,10 +14,14 @@ module: copy
 version_added: historical
 short_description: Copy files to remote locations
 description:
-    - The C(copy) module copies a file from the local or remote machine to a location on the remote machine.
+    - The M(ansible.builtin.copy) module copies a file or a directory structure from the local or remote machine to a location on the remote machine.
+      File system meta-information (permissions, ownership, etc.) may be set, even when the file or directory already exists on the target system.
+      Some meta-information may be copied on request.
+    - Get meta-information with the M(ansible.builtin.stat) module.
+    - Set meta-information with the M(ansible.builtin.file) module.
     - Use the M(ansible.builtin.fetch) module to copy files from remote locations to the local box.
     - If you need variable interpolation in copied files, use the M(ansible.builtin.template) module.
-      Using a variable in the C(content) field will result in unpredictable output.
+      Using a variable with the O(content) parameter produces unpredictable results.
     - For Windows targets, use the M(ansible.windows.win_copy) module instead.
 options:
   src:
@@ -31,19 +35,19 @@ options:
     type: path
   content:
     description:
-    - When used instead of C(src), sets the contents of a file directly to the specified value.
-    - Works only when C(dest) is a file. Creates the file if it does not exist.
-    - For advanced formatting or if C(content) contains a variable, use the
+    - When used instead of O(src), sets the contents of a file directly to the specified value.
+    - Works only when O(dest) is a file. Creates the file if it does not exist.
+    - For advanced formatting or if O(content) contains a variable, use the
       M(ansible.builtin.template) module.
     type: str
     version_added: '1.1'
   dest:
     description:
     - Remote absolute path where the file should be copied to.
-    - If C(src) is a directory, this must be a directory too.
-    - If C(dest) is a non-existent path and if either C(dest) ends with "/" or C(src) is a directory, C(dest) is created.
-    - If I(dest) is a relative path, the starting directory is determined by the remote host.
-    - If C(src) and C(dest) are files, the parent directory of C(dest) is not created and the task fails if it does not already exist.
+    - 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 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
     required: yes
   backup:
@@ -55,8 +59,8 @@ options:
   force:
     description:
     - Influence whether the remote file must always be replaced.
-    - If C(true), the remote file will be replaced when contents are different than the source.
-    - If C(false), the file will only be transferred if the destination does not exist.
+    - If V(true), the remote file will be replaced when contents are different than the source.
+    - If V(false), the file will only be transferred if the destination does not exist.
     type: bool
     default: yes
     version_added: '1.1'
@@ -65,33 +69,34 @@ options:
     - The permissions of the destination file or directory.
     - For those used to C(/usr/bin/chmod) remember that modes are actually octal numbers.
       You must either add a leading zero so that Ansible's YAML parser knows it is an octal number
-      (like C(0644) or C(01777)) or quote it (like C('644') or C('1777')) so Ansible receives a string
+      (like V(0644) or V(01777)) or quote it (like V('644') or V('1777')) so Ansible receives a string
       and can do its own conversion from string into number. Giving Ansible a number without following
       one of these rules will end up with a decimal number which will have unexpected results.
-    - As of Ansible 1.8, the mode may be specified as a symbolic mode (for example, C(u+rwx) or C(u=rw,g=r,o=r)).
-    - As of Ansible 2.3, the mode may also be the special string C(preserve).
-    - C(preserve) means that the file will be given the same permissions as the source file.
-    - When doing a recursive copy, see also C(directory_mode).
-    - If C(mode) is not specified and the destination file B(does not) exist, the default C(umask) on the system will be used
+    - As of Ansible 1.8, the mode may be specified as a symbolic mode (for example, V(u+rwx) or V(u=rw,g=r,o=r)).
+    - As of Ansible 2.3, the mode may also be the special string V(preserve).
+    - V(preserve) means that the file will be given the same permissions as the source file.
+    - When doing a recursive copy, see also O(directory_mode).
+    - If O(mode) is not specified and the destination file B(does not) exist, the default C(umask) on the system will be used
       when setting the mode for the newly created file.
-    - If C(mode) is not specified and the destination file B(does) exist, the mode of the existing file will be used.
-    - Specifying C(mode) is the best way to ensure files are created with the correct permissions.
+    - If O(mode) is not specified and the destination file B(does) exist, the mode of the existing file will be used.
+    - Specifying O(mode) is the best way to ensure files are created with the correct permissions.
       See CVE-2020-1736 for further details.
   directory_mode:
     description:
-    - When doing a recursive copy set the mode for the directories.
-    - If this is not set we will use the system defaults.
-    - The mode is only set on directories which are newly created, and will not affect those that already existed.
+    - Set the access permissions of newly created directories to the given mode.
+      Permissions on existing directories do not change.
+    - See O(mode) for the syntax of accepted values.
+    - The target system's defaults determine permissions when this parameter is not set.
     type: raw
     version_added: '1.5'
   remote_src:
     description:
-    - Influence whether C(src) needs to be transferred or already is present remotely.
-    - If C(false), it will search for C(src) on the controller node.
-    - If C(true) it will search for C(src) on the managed (remote) node.
-    - C(remote_src) supports recursive copying as of version 2.8.
-    - C(remote_src) only works with C(mode=preserve) as of version 2.6.
-    - Autodecryption of files does not work when C(remote_src=yes).
+    - 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.
+    - 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.
+    - Autodecryption of files does not work when O(remote_src=yes).
     type: bool
     default: no
     version_added: '2.0'
@@ -293,7 +298,7 @@ import stat
 import tempfile
 import traceback
 
-from ansible.module_utils._text import to_bytes, to_native
+from ansible.module_utils.common.text.converters import to_bytes, to_native
 from ansible.module_utils.basic import AnsibleModule
 from ansible.module_utils.common.process import get_bin_path
 from ansible.module_utils.common.locale import get_best_parsable_locale
@@ -689,7 +694,7 @@ def main():
                 b_mysrc = b_src
                 if remote_src and os.path.isfile(b_src):
 
-                    _, b_mysrc = tempfile.mkstemp(dir=os.path.dirname(b_dest))
+                    dummy, b_mysrc = tempfile.mkstemp(dir=os.path.dirname(b_dest))
 
                     shutil.copyfile(b_src, b_mysrc)
                     try:

ansible/modules/cron.py

@@ -44,7 +44,7 @@ options:
     description:
       - The command to execute or, if env is set, the value of environment variable.
       - The command should not contain line breaks.
-      - Required if I(state=present).
+      - Required if O(state=present).
     type: str
     aliases: [ value ]
   state:
@@ -58,42 +58,42 @@ options:
       - If specified, uses this file instead of an individual user's crontab.
         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 I(/etc/cron.d).
+      - 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
         of upper- and lower-case letters, digits, underscores, and hyphens.
-      - Using this parameter requires you to specify the I(user) as well, unless I(state) is not I(present).
-      - Either this parameter or I(name) is required
+      - 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
     type: path
   backup:
     description:
       - If set, create a backup of the crontab before it is modified.
-        The location of the backup is returned in the C(backup_file) variable by this module.
+        The location of the backup is returned in the RV(ignore:backup_file) variable by this module.
     type: bool
     default: no
   minute:
     description:
-      - Minute when the job should run (C(0-59), C(*), C(*/2), and so on).
+      - Minute when the job should run (V(0-59), V(*), V(*/2), and so on).
     type: str
     default: "*"
   hour:
     description:
-      - Hour when the job should run (C(0-23), C(*), C(*/2), and so on).
+      - Hour when the job should run (V(0-23), V(*), V(*/2), and so on).
     type: str
     default: "*"
   day:
     description:
-      - Day of the month the job should run (C(1-31), C(*), C(*/2), and so on).
+      - Day of the month the job should run (V(1-31), V(*), V(*/2), and so on).
     type: str
     default: "*"
     aliases: [ dom ]
   month:
     description:
-      - Month of the year the job should run (C(1-12), C(*), C(*/2), and so on).
+      - Month of the year the job should run (V(1-12), V(*), V(*/2), and so on).
     type: str
     default: "*"
   weekday:
     description:
-      - Day of the week that the job should run (C(0-6) for Sunday-Saturday, C(*), and so on).
+      - Day of the week that the job should run (V(0-6) for Sunday-Saturday, V(*), and so on).
     type: str
     default: "*"
     aliases: [ dow ]
@@ -106,7 +106,7 @@ options:
   disabled:
     description:
       - If the job should be disabled (commented out) in the crontab.
-      - Only has effect if I(state=present).
+      - Only has effect if O(state=present).
     type: bool
     default: no
     version_added: "2.0"
@@ -114,19 +114,19 @@ options:
     description:
       - If set, manages a crontab's environment variable.
       - New variables are added on top of crontab.
-      - I(name) and I(value) parameters are the name and the value of environment variable.
+      - O(name) and O(value) parameters are the name and the value of environment variable.
     type: bool
     default: false
     version_added: "2.1"
   insertafter:
     description:
-      - Used with I(state=present) and I(env).
+      - Used with O(state=present) and O(env).
       - If specified, the environment variable will be inserted after the declaration of specified environment variable.
     type: str
     version_added: "2.1"
   insertbefore:
     description:
-      - Used with I(state=present) and I(env).
+      - Used with O(state=present) and O(env).
       - If specified, the environment variable will be inserted before the declaration of specified environment variable.
     type: str
     version_added: "2.1"

ansible/modules/deb822_repository.py

@@ -97,7 +97,7 @@ 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
+          with a slash (C(/)). Alternatively, it may take the form of a
           distribution version (e.g. a version codename like disco or artful).
           If the suite does not specify a path, at least one component must
           be present.
@@ -124,7 +124,7 @@ options:
         elements: str
         description:
         - Which types of packages to look for from a given source; either
-          binary C(deb) or source code C(deb-src)
+          binary V(deb) or source code V(deb-src)
     uris:
         description:
         - The URIs must specify the base of the Debian distribution archive,
@@ -242,6 +242,7 @@ from ansible.module_utils.common.text.converters import to_native
 from ansible.module_utils.six import raise_from  # type: ignore[attr-defined]
 from ansible.module_utils.urls import generic_urlparse
 from ansible.module_utils.urls import open_url
+from ansible.module_utils.urls import get_user_agent
 from ansible.module_utils.urls import urlparse
 
 HAS_DEBIAN = True
@@ -325,7 +326,7 @@ def write_signed_by_key(module, v, slug):
     parts = generic_urlparse(urlparse(v))
     if parts.scheme:
         try:
-            r = open_url(v, http_agent='ansible-httpget')
+            r = open_url(v, http_agent=get_user_agent())
         except Exception as exc:
             raise_from(RuntimeError(to_native(exc)), exc)
         else:

ansible/modules/debconf.py

@@ -27,13 +27,13 @@ attributes:
         platforms: debian
 notes:
     - This module requires the command line debconf tools.
-    - A number of questions have to be answered (depending on the package).
+    - 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.
-    - It is highly recommended to add I(no_log=True) to task while handling sensitive information using this module.
+    - 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.
-      An additional step is needed (typically with I(notify) if debconf makes a change)
+      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
       rather than modifying configurations.
@@ -46,7 +46,7 @@ notes:
     - 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.
+      dpkg-reconfigure will effectively ignore changes made by debconf.
     - However as 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.
@@ -69,8 +69,8 @@ options:
   vtype:
     description:
       - The type of the value supplied.
-      - It is highly recommended to add I(no_log=True) to task while specifying I(vtype=password).
-      - C(seen) was added in Ansible 2.2.
+      - It is highly recommended to add C(no_log=True) to task while specifying O(vtype=password).
+      - V(seen) was added in Ansible 2.2.
     type: str
     choices: [ boolean, error, multiselect, note, password, seen, select, string, text, title ]
   value:
@@ -124,10 +124,32 @@ EXAMPLES = r'''
 
 RETURN = r'''#'''
 
-from ansible.module_utils._text import to_text
+from ansible.module_utils.common.text.converters import to_text
 from ansible.module_utils.basic import AnsibleModule
 
 
+def get_password_value(module, pkg, question, vtype):
+    getsel = module.get_bin_path('debconf-get-selections', True)
+    cmd = [getsel]
+    rc, out, err = module.run_command(cmd)
+    if rc != 0:
+        module.fail_json(msg="Failed to get the value '%s' from '%s'" % (question, pkg))
+
+    desired_line = None
+    for line in out.split("\n"):
+        if line.startswith(pkg):
+            desired_line = line
+            break
+
+    if not desired_line:
+        module.fail_json(msg="Failed to find the value '%s' from '%s'" % (question, pkg))
+
+    (dpkg, dquestion, dvtype, dvalue) = desired_line.split()
+    if dquestion == question and dvtype == vtype:
+        return dvalue
+    return ''
+
+
 def get_selections(module, pkg):
     cmd = [module.get_bin_path('debconf-show', True), pkg]
     rc, out, err = module.run_command(' '.join(cmd))
@@ -151,10 +173,7 @@ def set_selection(module, pkg, question, vtype, value, unseen):
         cmd.append('-u')
 
     if vtype == 'boolean':
-        if value == 'True':
-            value = 'true'
-        elif value == 'False':
-            value = 'false'
+        value = value.lower()
     data = ' '.join([pkg, question, vtype, value])
 
     return module.run_command(cmd, data=data)
@@ -193,7 +212,6 @@ def main():
         if question not in prev:
             changed = True
         else:
-
             existing = prev[question]
 
             # ensure we compare booleans supplied to the way debconf sees them (true/false strings)
@@ -201,6 +219,9 @@ def main():
                 value = to_text(value).lower()
                 existing = to_text(prev[question]).lower()
 
+            if vtype == 'password':
+                existing = get_password_value(module, pkg, question, vtype)
+
             if value != existing:
                 changed = True
 
@@ -215,12 +236,12 @@ def main():
             prev = {question: prev[question]}
         else:
             prev[question] = ''
+
+        diff_dict = {}
         if module._diff:
             after = prev.copy()
             after.update(curr)
             diff_dict = {'before': prev, 'after': after}
-        else:
-            diff_dict = {}
 
         module.exit_json(changed=changed, msg=msg, current=curr, previous=prev, diff=diff_dict)
 

ansible/modules/debug.py

@@ -27,7 +27,7 @@ options:
   var:
     description:
     - A variable name to debug.
-    - Mutually exclusive with the C(msg) option.
+    - Mutually exclusive with the O(msg) option.
     - Be aware that this option already runs in Jinja2 context and has an implicit C({{ }}) wrapping,
       so you should not be using Jinja2 delimiters unless you are looking for double interpolation.
     type: str