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

ansible/module_utils/facts/utils.py

@@ -20,7 +20,7 @@ import os
 
 
 def get_file_content(path, default=None, strip=True):
-    '''
+    """
         Return the contents of a given file path
 
         :args path: path to file to return contents from
@@ -28,7 +28,7 @@ def get_file_content(path, default=None, strip=True):
         :args strip: controls if we strip whitespace from the result or not
 
         :returns: String with file contents (optionally stripped) or 'default' value
-    '''
+    """
     data = default
     if os.path.exists(path) and os.access(path, os.R_OK):
         datafile = None
@@ -62,7 +62,7 @@ def get_file_content(path, default=None, strip=True):
 
 
 def get_file_lines(path, strip=True, line_sep=None):
-    '''get list of lines from file'''
+    """get list of lines from file"""
     data = get_file_content(path, strip=strip)
     if data:
         if line_sep is None:

ansible/module_utils/facts/virtual/base.py

@@ -18,7 +18,7 @@
 
 from __future__ import annotations
 
-import ansible.module_utils.compat.typing as t
+import typing as t
 
 from ansible.module_utils.facts.collector import BaseFactCollector
 

ansible/module_utils/facts/virtual/sunos.py

@@ -1,17 +1,5 @@
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+# Copyright: Contributors to the Ansible project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 from __future__ import annotations
 
@@ -77,7 +65,7 @@ class SunOSVirtual(Virtual):
         if virtinfo:
             # The output of virtinfo is different whether we are on a machine with logical
             # domains ('LDoms') on a T-series or domains ('Domains') on a M-series. Try LDoms first.
-            rc, out, err = self.module.run_command("/usr/sbin/virtinfo -p")
+            rc, out, err = self.module.run_command([virtinfo, '-p'])
             # The output contains multiple lines with different keys like this:
             #   DOMAINROLE|impl=LDoms|control=false|io=false|service=false|root=false
             # The output may also be not formatted and the returncode is set to 0 regardless of the error condition:

ansible/module_utils/facts/virtual/sysctl.py

@@ -1,24 +1,11 @@
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
-
+# Copyright: Contributors to the Ansible project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 from __future__ import annotations
 
 import re
 
 
-class VirtualSysctlDetectionMixin(object):
+class VirtualSysctlDetectionMixin:
     def detect_sysctl(self):
         self.sysctl_path = self.module.get_bin_path('sysctl')
 

ansible/module_utils/json_utils.py

@@ -32,13 +32,13 @@ import json  # pylint: disable=unused-import
 # NB: a copy of this function exists in ../../modules/core/async_wrapper.py. Ensure any
 # changes are propagated there.
 def _filter_non_json_lines(data, objects_only=False):
-    '''
+    """
     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 '{' or '[', and filter all
     trailing lines after matching close character (working from the bottom of output).
-    '''
+    """
     warnings = []
 
     # Filter initial junk

ansible/module_utils/parsing/convert_bool.py

@@ -25,4 +25,4 @@ def boolean(value, strict=True):
     elif normalized_value in BOOLEANS_FALSE or not strict:
         return False
 
-    raise TypeError("The value '%s' is not a valid boolean.  Valid booleans include: %s" % (to_text(value), ', '.join(repr(i) for i in BOOLEANS)))
+    raise TypeError("The value '%s' is not a valid boolean. Valid booleans include: %s" % (to_text(value), ', '.join(repr(i) for i in BOOLEANS)))

ansible/module_utils/service.py

@@ -35,20 +35,19 @@ import platform
 import select
 import shlex
 import subprocess
-import traceback
 
 from ansible.module_utils.six import PY2, b
 from ansible.module_utils.common.text.converters import to_bytes, to_text
 
 
 def sysv_is_enabled(name, runlevel=None):
-    '''
+    """
     This function will check if the service name supplied
     is enabled in any of the sysv runlevels
 
     :arg name: name of the service to test for
     :kw runlevel: runlevel to check (default: None)
-    '''
+    """
     if runlevel:
         if not os.path.isdir('/etc/rc0.d/'):
             return bool(glob.glob('/etc/init.d/rc%s.d/S??%s' % (runlevel, name)))
@@ -60,12 +59,12 @@ def sysv_is_enabled(name, runlevel=None):
 
 
 def get_sysv_script(name):
-    '''
+    """
     This function will return the expected path for an init script
     corresponding to the service name supplied.
 
     :arg name: name or path of the service to test for
-    '''
+    """
     if name.startswith('/'):
         result = name
     else:
@@ -75,19 +74,19 @@ def get_sysv_script(name):
 
 
 def sysv_exists(name):
-    '''
+    """
     This function will return True or False depending on
     the existence of an init script corresponding to the service name supplied.
 
     :arg name: name of the service to test for
-    '''
+    """
     return os.path.exists(get_sysv_script(name))
 
 
 def get_ps(module, pattern):
-    '''
+    """
     Last resort to find a service by trying to match pattern to programs in memory
-    '''
+    """
     found = False
     if platform.system() == 'SunOS':
         flags = '-ef'
@@ -106,7 +105,7 @@ def get_ps(module, pattern):
 
 
 def fail_if_missing(module, found, service, msg=''):
-    '''
+    """
     This function will return an error or exit gracefully depending on check mode status
     and if the service is missing or not.
 
@@ -114,16 +113,16 @@ def fail_if_missing(module, found, service, msg=''):
     :arg found: boolean indicating if services were found or not
     :arg service: name of service
     :kw msg: extra info to append to error/success msg when missing
-    '''
+    """
     if not found:
         module.fail_json(msg='Could not find the requested service %s: %s' % (service, msg))
 
 
 def fork_process():
-    '''
+    """
     This function performs the double fork process to detach from the
     parent process and execute.
-    '''
+    """
     pid = os.fork()
 
     if pid == 0:
@@ -147,9 +146,7 @@ def fork_process():
             os._exit(0)
 
         # get new process session and detach
-        sid = os.setsid()
-        if sid == -1:
-            raise Exception("Unable to detach session while daemonizing")
+        os.setsid()
 
         # avoid possible problems with cwd being removed
         os.chdir("/")
@@ -162,7 +159,7 @@ def fork_process():
 
 
 def daemonize(module, cmd):
-    '''
+    """
     Execute a command while detaching as a daemon, returns rc, stdout, and stderr.
 
     :arg module: is an AnsibleModule object, used for it's utility methods
@@ -171,7 +168,7 @@ def daemonize(module, cmd):
     This is complex because daemonization is hard for people.
     What we do is daemonize a part of this module, the daemon runs the command,
     picks up the return code and output, and returns it to the main process.
-    '''
+    """
 
     # init some vars
     chunk = 4096  # FIXME: pass in as arg?
@@ -181,10 +178,10 @@ def daemonize(module, cmd):
     try:
         pipe = os.pipe()
         pid = fork_process()
-    except OSError:
-        module.fail_json(msg="Error while attempting to fork: %s", exception=traceback.format_exc())
+    except (OSError, RuntimeError):
+        module.fail_json(msg="Error while attempting to fork.")
     except Exception as exc:
-        module.fail_json(msg=to_text(exc), exception=traceback.format_exc())
+        module.fail_json(msg=to_text(exc))
 
     # we don't do any locking as this should be a unique module/process
     if pid == 0:

ansible/module_utils/splitter.py

@@ -30,10 +30,10 @@ from __future__ import annotations
 
 
 def _get_quote_state(token, quote_char):
-    '''
+    """
     the goal of this block is to determine if the quoted string
     is unterminated in which case it needs to be put back together
-    '''
+    """
     # the char before the current one, used to see if
     # the current character is escaped
     prev_char = None
@@ -50,11 +50,11 @@ def _get_quote_state(token, quote_char):
 
 
 def _count_jinja2_blocks(token, cur_depth, open_token, close_token):
-    '''
+    """
     this function counts the number of opening/closing blocks for a
     given opening/closing type and adjusts the current depth for that
     block based on the difference
-    '''
+    """
     num_open = token.count(open_token)
     num_close = token.count(close_token)
     if num_open != num_close:
@@ -65,7 +65,7 @@ def _count_jinja2_blocks(token, cur_depth, open_token, close_token):
 
 
 def split_args(args):
-    '''
+    """
     Splits args on whitespace, but intelligently reassembles
     those that may have been split over a jinja2 block or quotes.
 
@@ -78,7 +78,7 @@ def split_args(args):
 
     Basically this is a variation shlex that has some more intelligence for
     how Ansible needs to use it.
-    '''
+    """
 
     # the list of params parsed out of the arg string
     # this is going to be the result value when we are done
@@ -212,7 +212,7 @@ def is_quoted(data):
 
 
 def unquote(data):
-    ''' removes first and last quotes from a string, if the string starts and ends with the same quotes '''
+    """ removes first and last quotes from a string, if the string starts and ends with the same quotes """
     if is_quoted(data):
         return data[1:-1]
     return data

ansible/module_utils/testing.py

@@ -0,0 +1,31 @@
+"""
+Utilities to support unit testing of Ansible Python modules.
+Not supported for use cases other than testing.
+"""
+
+from __future__ import annotations as _annotations
+
+import contextlib as _contextlib
+import json as _json
+import typing as _t
+
+from unittest import mock as _mock
+
+from ansible.module_utils.common import json as _common_json
+from . import basic as _basic
+
+
+@_contextlib.contextmanager
+def patch_module_args(args: dict[str, _t.Any] | None = None) -> _t.Iterator[None]:
+    """Expose the given module args to `AnsibleModule` instances created within this context."""
+    if not isinstance(args, (dict, type(None))):
+        raise TypeError("The `args` arg must be a dict or None.")
+
+    args = dict(ANSIBLE_MODULE_ARGS=args or {})
+    profile = 'legacy'  # this should be configurable in the future, once the profile feature is more fully baked
+
+    encoder = _common_json.get_module_encoder(profile, _common_json.Direction.CONTROLLER_TO_MODULE)
+    args = _json.dumps(args, cls=encoder).encode()
+
+    with _mock.patch.object(_basic, '_ANSIBLE_ARGS', args), _mock.patch.object(_basic, '_ANSIBLE_PROFILE', profile):
+        yield

ansible/module_utils/urls.py

@@ -12,7 +12,7 @@
 # Simplified BSD License (see licenses/simplified_bsd.txt or https://opensource.org/licenses/BSD-2-Clause)
 
 
-'''
+"""
 The **urls** utils module offers a replacement for the urllib python library.
 
 urllib is the python stdlib way to retrieve files from the Internet but it
@@ -25,11 +25,12 @@ to replace urllib with a more secure library. However, all third party libraries
 require that the library be installed on the managed machine. That is an extra step
 for users making use of a module. If possible, avoid third party libraries by using
 this code instead.
-'''
+"""
 
 from __future__ import annotations
 
 import base64
+import email.encoders
 import email.mime.application
 import email.mime.multipart
 import email.mime.nonmultipart
@@ -223,10 +224,10 @@ UnixHTTPSConnection = None
 if HAS_SSL:
     @contextmanager
     def unix_socket_patch_httpconnection_connect():
-        '''Monkey patch ``http.client.HTTPConnection.connect`` to be ``UnixHTTPConnection.connect``
+        """Monkey patch ``http.client.HTTPConnection.connect`` to be ``UnixHTTPConnection.connect``
         so that when calling ``super(UnixHTTPSConnection, self).connect()`` we get the
         correct behavior of creating self.sock for the unix socket
-        '''
+        """
         _connect = http.client.HTTPConnection.connect
         http.client.HTTPConnection.connect = UnixHTTPConnection.connect
         yield
@@ -270,7 +271,7 @@ if HAS_SSL:
 
 
 class UnixHTTPConnection(http.client.HTTPConnection):
-    '''Handles http requests to a unix socket file'''
+    """Handles http requests to a unix socket file"""
 
     def __init__(self, unix_socket):
         self._unix_socket = unix_socket
@@ -290,7 +291,7 @@ class UnixHTTPConnection(http.client.HTTPConnection):
 
 
 class UnixHTTPHandler(urllib.request.HTTPHandler):
-    '''Handler for Unix urls'''
+    """Handler for Unix urls"""
 
     def __init__(self, unix_socket, **kwargs):
         super().__init__(**kwargs)
@@ -301,29 +302,29 @@ class UnixHTTPHandler(urllib.request.HTTPHandler):
 
 
 class ParseResultDottedDict(dict):
-    '''
+    """
     A dict that acts similarly to the ParseResult named tuple from urllib
-    '''
+    """
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
         self.__dict__ = self
 
     def as_list(self):
-        '''
+        """
         Generate a list from this dict, that looks like the ParseResult named tuple
-        '''
+        """
         return [self.get(k, None) for k in ('scheme', 'netloc', 'path', 'params', 'query', 'fragment')]
 
 
 def generic_urlparse(parts):
-    '''
+    """
     Returns a dictionary of url parts as parsed by urlparse,
     but accounts for the fact that older versions of that
     library do not support named attributes (ie. .netloc)
 
     This method isn't of much use any longer, but is kept
     in a minimal state for backwards compat.
-    '''
+    """
     result = ParseResultDottedDict(parts._asdict())
     result.update({
         'username': parts.username,
@@ -340,13 +341,16 @@ def extract_pem_certs(data):
 
 
 def get_response_filename(response):
-    url = response.geturl()
-    path = urlparse(url)[2]
-    filename = os.path.basename(path.rstrip('/')) or None
-    if filename:
-        filename = unquote(filename)
+    if filename := response.headers.get_param('filename', header='content-disposition'):
+        filename = os.path.basename(filename)
+    else:
+        url = response.geturl()
+        path = urlparse(url)[2]
+        filename = os.path.basename(path.rstrip('/')) or None
+        if filename:
+            filename = unquote(filename)
 
-    return response.headers.get_param('filename', header='content-disposition') or filename
+    return filename
 
 
 def parse_content_type(response):
@@ -986,11 +990,11 @@ def open_url(url, data=None, headers=None, method=None, use_proxy=True,
              client_cert=None, client_key=None, cookies=None,
              use_gssapi=False, unix_socket=None, ca_path=None,
              unredirected_headers=None, decompress=True, ciphers=None, use_netrc=True):
-    '''
+    """
     Sends a request via HTTP(S) or FTP using urllib (Python3)
 
     Does not require the module environment
-    '''
+    """
     method = method or ('POST' if data else 'GET')
     return Request().open(method, url, data=data, headers=headers, use_proxy=use_proxy,
                           force=force, last_mod_time=last_mod_time, timeout=timeout, validate_certs=validate_certs,
@@ -1042,6 +1046,7 @@ def prepare_multipart(fields):
             filename = None
         elif isinstance(value, Mapping):
             filename = value.get('filename')
+            multipart_encoding_str = value.get('multipart_encoding') or 'base64'
             content = value.get('content')
             if not any((filename, content)):
                 raise ValueError('at least one of filename or content must be provided')
@@ -1053,14 +1058,16 @@ def prepare_multipart(fields):
                 except Exception:
                     mime = 'application/octet-stream'
             main_type, sep, sub_type = mime.partition('/')
+
         else:
             raise TypeError(
                 'value must be a string, or mapping, cannot be type %s' % value.__class__.__name__
             )
 
         if not content and filename:
+            multipart_encoding = set_multipart_encoding(multipart_encoding_str)
             with open(to_bytes(filename, errors='surrogate_or_strict'), 'rb') as f:
-                part = email.mime.application.MIMEApplication(f.read())
+                part = email.mime.application.MIMEApplication(f.read(), _encoder=multipart_encoding)
                 del part['Content-Type']
                 part.add_header('Content-Type', '%s/%s' % (main_type, sub_type))
         else:
@@ -1099,11 +1106,24 @@ def prepare_multipart(fields):
     )
 
 
+def set_multipart_encoding(encoding):
+    """Takes an string with specific encoding type for multipart data.
+    Will return reference to function from email.encoders library.
+    If given string key doesn't exist it will raise a ValueError"""
+    encoders_dict = {
+        "base64": email.encoders.encode_base64,
+        "7or8bit": email.encoders.encode_7or8bit
+    }
+    if encoders_dict.get(encoding):
+        return encoders_dict.get(encoding)
+    else:
+        raise ValueError("multipart_encoding must be one of %s." % repr(encoders_dict.keys()))
+
+
 #
 # Module-related functions
 #
 
-
 def basic_auth_header(username, password):
     """Takes a username and password and returns a byte string suitable for
     using as value of an Authorization header to do basic auth.
@@ -1114,10 +1134,10 @@ def basic_auth_header(username, password):
 
 
 def url_argument_spec():
-    '''
+    """
     Creates an argument spec that can be used with any module
     that will be requesting content via urllib/urllib2
-    '''
+    """
     return dict(
         url=dict(type='str'),
         force=dict(type='bool', default=False),
@@ -1133,6 +1153,16 @@ def url_argument_spec():
     )
 
 
+def url_redirect_argument_spec():
+    """
+    Creates an addition arugment spec to `url_argument_spec`
+    for  `follow_redirects` argument
+    """
+    return dict(
+        follow_redirects=dict(type='str', default='safe', choices=['all', 'no', 'none', 'safe', 'urllib2', 'yes']),
+    )
+
+
 def fetch_url(module, url, data=None, headers=None, method=None,
               use_proxy=None, force=False, last_mod_time=None, timeout=10,
               use_gssapi=False, unix_socket=None, ca_path=None, cookies=None, unredirected_headers=None,
@@ -1168,7 +1198,7 @@ def fetch_url(module, url, data=None, headers=None, method=None,
         data={...}
         resp, info = fetch_url(module,
                                "http://example.com",
-                               data=module.jsonify(data),
+                               data=json.dumps(data),
                                headers={'Content-type': 'application/json'},
                                method="POST")
         status_code = info["status"]
@@ -1246,7 +1276,7 @@ def fetch_url(module, url, data=None, headers=None, method=None,
     except (ConnectionError, ValueError) as e:
         module.fail_json(msg=to_native(e), **info)
     except MissingModuleError as e:
-        module.fail_json(msg=to_text(e), exception=e.import_traceback)
+        module.fail_json(msg=to_text(e))
     except urllib.error.HTTPError as e:
         r = e
         try:
@@ -1277,9 +1307,8 @@ def fetch_url(module, url, data=None, headers=None, method=None,
         info.update(dict(msg="Connection failure: %s" % to_native(e), status=-1))
     except http.client.BadStatusLine as e:
         info.update(dict(msg="Connection failure: connection was closed before a valid response was received: %s" % to_native(e.line), status=-1))
-    except Exception as e:
-        info.update(dict(msg="An unknown error occurred: %s" % to_native(e), status=-1),
-                    exception=traceback.format_exc())
+    except Exception as ex:
+        info.update(dict(msg="An unknown error occurred: %s" % to_native(ex), status=-1, exception=traceback.format_exc()))
     finally:
         tempfile.tempdir = old_tempdir
 
@@ -1330,7 +1359,7 @@ def _split_multiext(name, min=3, max=4, count=2):
 def fetch_file(module, url, data=None, headers=None, method=None,
                use_proxy=True, force=False, last_mod_time=None, timeout=10,
                unredirected_headers=None, decompress=True, ciphers=None):
-    '''Download and save a file via HTTP(S) or FTP (needs the module as parameter).
+    """Download and save a file via HTTP(S) or FTP (needs the module as parameter).
     This is basically a wrapper around fetch_url().
 
     :arg module: The AnsibleModule (used to get username, password etc. (s.b.).
@@ -1348,7 +1377,7 @@ def fetch_file(module, url, data=None, headers=None, method=None,
     :kwarg ciphers: (optional) List of ciphers to use
 
     :returns: A string, the path to the downloaded file.
-    '''
+    """
     # download file
     bufsize = 65536
     parts = urlparse(url)

ansible/modules/add_host.py

@@ -7,7 +7,7 @@
 from __future__ import annotations
 
 
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
 ---
 module: add_host
 short_description: Add a host (and alternatively a group) to the ansible-playbook in-memory inventory
@@ -69,9 +69,9 @@ seealso:
 author:
 - Ansible Core Team
 - Seth Vidal (@skvidal)
-'''
+"""
 
-EXAMPLES = r'''
+EXAMPLES = r"""
 - name: Add host to group 'just_created' with variable foo=42
   ansible.builtin.add_host:
     name: '{{ ip_from_ec2 }}'
@@ -111,4 +111,4 @@ EXAMPLES = r'''
     name: '{{ item }}'
     groups: done
   loop: "{{ ansible_play_hosts }}"
-'''
+"""