ansible-core 2.18.7__py3-none-any.whl → 2.19.0__py3-none-any.whl

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
@@ -27,6 +28,8 @@ options:
     type: str
     choices: [ cleanup, status ]
     default: status
+notes:
+  - The RV(started) and RV(finished) return values were updated to return V(True) or V(False) instead of V(1) or V(0) in ansible-core 2.19.
 extends_documentation_fragment:
 - action_common_attributes
 - action_common_attributes.flow
@@ -51,9 +54,9 @@ seealso:
 author:
 - Ansible Core Team
 - Michael DeHaan
-'''
+"""
 
-EXAMPLES = r'''
+EXAMPLES = r"""
 ---
 - name: Asynchronous dnf task
   ansible.builtin.dnf:
@@ -67,7 +70,7 @@ EXAMPLES = r'''
   ansible.builtin.async_status:
     jid: '{{ dnf_sleeper.ansible_job_id }}'
   register: job_result
-  until: job_result.finished
+  until: job_result is finished
   retries: 100
   delay: 10
 
@@ -75,24 +78,24 @@ 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
   type: str
   sample: '360874038559.4169'
 finished:
-  description: Whether the asynchronous job has finished (V(1)) or not (V(0))
+  description: Whether the asynchronous job has finished or not
   returned: always
-  type: int
-  sample: 1
+  type: bool
+  sample: true
 started:
-  description: Whether the asynchronous job has started (V(1)) or not (V(0))
+  description: Whether the asynchronous job has started or not
   returned: always
-  type: int
-  sample: 1
+  type: bool
+  sample: true
 stdout:
   description: Any output returned by async_wrapper
   returned: always
@@ -105,14 +108,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():
@@ -135,7 +136,7 @@ def main():
     log_path = os.path.join(async_dir, jid)
 
     if not os.path.exists(log_path):
-        module.fail_json(msg="could not find job", ansible_job_id=jid, started=1, finished=1)
+        module.fail_json(msg="could not find job", ansible_job_id=jid, started=True, finished=True)
 
     if mode == 'cleanup':
         os.unlink(log_path)
@@ -152,21 +153,20 @@ def main():
     except Exception:
         if not data:
             # file not written yet?  That means it is running
-            module.exit_json(results_file=log_path, ansible_job_id=jid, started=1, finished=0)
+            module.exit_json(results_file=log_path, ansible_job_id=jid, started=True, finished=False)
         else:
             module.fail_json(ansible_job_id=jid, results_file=log_path,
-                             msg="Could not parse job output: %s" % data, started=1, finished=1)
+                             msg="Could not parse job output: %s" % data, started=True, finished=True)
 
     if 'started' not in data:
-        data['finished'] = 1
+        data['finished'] = True
         data['ansible_job_id'] = jid
     elif 'finished' not in data:
-        data['finished'] = 0
+        data['finished'] = False
 
-    # 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

@@ -6,7 +6,6 @@
 from __future__ import annotations
 
 
-import errno
 import json
 import shlex
 import shutil
@@ -75,13 +74,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
@@ -122,24 +121,14 @@ def _get_interpreter(module_path):
         return head[2:head.index(b'\n')].strip().split(b' ')
 
 
-def _make_temp_dir(path):
-    # TODO: Add checks for permissions on path.
-    try:
-        os.makedirs(path)
-    except OSError as e:
-        if e.errno != errno.EEXIST:
-            raise
-
-
 def jwrite(info):
-
     jobfile = job_path + ".tmp"
     tjob = open(jobfile, "w")
     try:
         tjob.write(json.dumps(info))
-    except (IOError, OSError) as e:
-        notice('failed to write to %s: %s' % (jobfile, str(e)))
-        raise e
+    except OSError as ex:
+        notice(f'failed to write to {jobfile!r}: {ex}')
+        raise
     finally:
         tjob.close()
         os.rename(jobfile, job_path)
@@ -147,7 +136,9 @@ def jwrite(info):
 
 def _run_module(wrapped_cmd, jid):
 
-    jwrite({"started": 1, "finished": 0, "ansible_job_id": jid})
+    # DTFIX-FUTURE: needs rework for serialization profiles
+
+    jwrite({"started": True, "finished": False, "ansible_job_id": jid})
 
     result = {}
 
@@ -188,6 +179,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
 
@@ -195,10 +189,10 @@ def _run_module(wrapped_cmd, jid):
             result['stderr'] = stderr
         jwrite(result)
 
-    except (OSError, IOError):
+    except OSError:
         e = sys.exc_info()[1]
         result = {
-            "failed": 1,
+            "failed": True,
             "cmd": wrapped_cmd,
             "msg": to_text(e),
             "outdata": outdata,  # temporary notice only
@@ -207,9 +201,9 @@ def _run_module(wrapped_cmd, jid):
         result['ansible_job_id'] = jid
         jwrite(result)
 
-    except (ValueError, Exception):
+    except Exception:
         result = {
-            "failed": 1,
+            "failed": True,
             "cmd": wrapped_cmd,
             "data": outdata,  # temporary notice only
             "stderr": stderr,
@@ -252,12 +246,13 @@ def main():
     job_path = os.path.join(jobdir, jid)
 
     try:
-        _make_temp_dir(jobdir)
+        # TODO: Add checks for permissions on path.
+        os.makedirs(jobdir, exist_ok=True)
     except Exception as e:
         end({
-            "failed": 1,
+            "failed": True,
             "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
@@ -288,7 +283,7 @@ def main():
                     continue
 
             notice("Return async_wrapper task started.")
-            end({"failed": 0, "started": 1, "finished": 0, "ansible_job_id": jid, "results_file": job_path,
+            end({"failed": False, "started": True, "finished": False, "ansible_job_id": jid, "results_file": job_path,
                  "_ansible_suppress_tmpdir_delete": (not preserve_tmp)}, 0)
         else:
             # The actual wrapper 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

ansible/modules/command.py

@@ -7,7 +7,7 @@
 from __future__ import annotations
 
 
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
 ---
 module: command
 short_description: Execute commands on targets
@@ -117,9 +117,9 @@ seealso:
 author:
     - Ansible Core Team
     - Michael DeHaan
-'''
+"""
 
-EXAMPLES = r'''
+EXAMPLES = r"""
 - name: Return motd to registered var
   ansible.builtin.command: cat /etc/motd
   register: mymotd
@@ -173,9 +173,9 @@ EXAMPLES = r'''
 - 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
-'''
+"""
 
-RETURN = r'''
+RETURN = r"""
 msg:
   description: changed
   returned: always
@@ -228,7 +228,7 @@ stderr_lines:
   returned: always
   type: list
   sample: [u'ls cannot access foo: No such file or directory', u'ls …']
-'''
+"""
 
 import datetime
 import glob
@@ -249,6 +249,7 @@ def main():
         argument_spec=dict(
             _raw_params=dict(),
             _uses_shell=dict(type='bool', default=False),
+            cmd=dict(),
             argv=dict(type='list', elements='str'),
             chdir=dict(type='path'),
             executable=dict(),
@@ -260,12 +261,14 @@ def main():
             stdin_add_newline=dict(type='bool', default=True),
             strip_empty_ends=dict(type='bool', default=True),
         ),
+        required_one_of=[['_raw_params', 'cmd', 'argv']],
+        mutually_exclusive=[['_raw_params', 'cmd', 'argv']],
         supports_check_mode=True,
     )
     shell = module.params['_uses_shell']
     chdir = module.params['chdir']
     executable = module.params['executable']
-    args = module.params['_raw_params']
+    args = module.params['_raw_params'] or module.params['cmd']
     argv = module.params['argv']
     creates = module.params['creates']
     removes = module.params['removes']
@@ -281,16 +284,6 @@ def main():
         module.warn("As of Ansible 2.4, the parameter 'executable' is no longer supported with the 'command' module. Not using '%s'." % executable)
         executable = None
 
-    if (not args or args.strip() == '') and not argv:
-        r['rc'] = 256
-        r['msg'] = "no command given"
-        module.fail_json(**r)
-
-    if args and argv:
-        r['rc'] = 256
-        r['msg'] = "only command or argv can be given, not both"
-        module.fail_json(**r)
-
     if not shell and args:
         args = shlex.split(args)
 
@@ -306,9 +299,9 @@ def main():
 
         try:
             os.chdir(chdir)
-        except (IOError, OSError) as e:
-            r['msg'] = 'Unable to change directory before execution: %s' % to_text(e)
-            module.fail_json(**r)
+        except OSError as ex:
+            r['msg'] = 'Unable to change directory before execution.'
+            module.fail_json(**r, exception=ex)
 
     # check_mode partial support, since it only really works in checking creates/removes
     if module.check_mode: