ansible-core 2.16.7rc1__py3-none-any.whl → 2.17.0__py3-none-any.whl

ansible/module_utils/yumdnf.py

@@ -9,20 +9,16 @@
 #    - Abhijeet Kasurde (@Akasurde)
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
 
-import os
-import time
-import glob
 from abc import ABCMeta, abstractmethod
 
-from ansible.module_utils.six import with_metaclass
-
 yumdnf_argument_spec = dict(
     argument_spec=dict(
         allow_downgrade=dict(type='bool', default=False),
+        allowerasing=dict(default=False, type="bool"),
         autoremove=dict(type='bool', default=False),
+        best=dict(type="bool"),
         bugfix=dict(required=False, type='bool', default=False),
         cacheonly=dict(type='bool', default=False),
         conf_file=dict(type='str'),
@@ -36,10 +32,14 @@ yumdnf_argument_spec = dict(
         enablerepo=dict(type='list', elements='str', default=[]),
         exclude=dict(type='list', elements='str', default=[]),
         installroot=dict(type='str', default="/"),
-        install_repoquery=dict(type='bool', default=True),
+        install_repoquery=dict(
+            type='bool', default=True,
+            removed_in_version='2.20', removed_from_collection='ansible.builtin',
+        ),
         install_weak_deps=dict(type='bool', default=True),
         list=dict(type='str'),
         name=dict(type='list', elements='str', aliases=['pkg'], default=[]),
+        nobest=dict(type="bool"),
         releasever=dict(default=None),
         security=dict(type='bool', default=False),
         skip_broken=dict(type='bool', default=False),
@@ -52,12 +52,12 @@ yumdnf_argument_spec = dict(
         lock_timeout=dict(type='int', default=30),
     ),
     required_one_of=[['name', 'list', 'update_cache']],
-    mutually_exclusive=[['name', 'list']],
+    mutually_exclusive=[['name', 'list'], ['best', 'nobest']],
     supports_check_mode=True,
 )
 
 
-class YumDnf(with_metaclass(ABCMeta, object)):  # type: ignore[misc]
+class YumDnf(metaclass=ABCMeta):
     """
     Abstract class that handles the population of instance variables that should
     be identical between both YUM and DNF modules because of the feature parity
@@ -69,7 +69,9 @@ class YumDnf(with_metaclass(ABCMeta, object)):  # type: ignore[misc]
         self.module = module
 
         self.allow_downgrade = self.module.params['allow_downgrade']
+        self.allowerasing = self.module.params['allowerasing']
         self.autoremove = self.module.params['autoremove']
+        self.best = self.module.params['best']
         self.bugfix = self.module.params['bugfix']
         self.cacheonly = self.module.params['cacheonly']
         self.conf_file = self.module.params['conf_file']
@@ -87,6 +89,7 @@ class YumDnf(with_metaclass(ABCMeta, object)):  # type: ignore[misc]
         self.install_weak_deps = self.module.params['install_weak_deps']
         self.list = self.module.params['list']
         self.names = [p.strip() for p in self.module.params['name']]
+        self.nobest = self.module.params['nobest']
         self.releasever = self.module.params['releasever']
         self.security = self.module.params['security']
         self.skip_broken = self.module.params['skip_broken']
@@ -127,31 +130,6 @@ class YumDnf(with_metaclass(ABCMeta, object)):  # type: ignore[misc]
                 results=[],
             )
 
-        # This should really be redefined by both the yum and dnf module but a
-        # default isn't a bad idea
-        self.lockfile = '/var/run/yum.pid'
-
-    @abstractmethod
-    def is_lockfile_pid_valid(self):
-        return
-
-    def _is_lockfile_present(self):
-        return (os.path.isfile(self.lockfile) or glob.glob(self.lockfile)) and self.is_lockfile_pid_valid()
-
-    def wait_for_lock(self):
-        '''Poll until the lock is removed if timeout is a positive number'''
-
-        if not self._is_lockfile_present():
-            return
-
-        if self.lock_timeout > 0:
-            for iteration in range(0, self.lock_timeout):
-                time.sleep(1)
-                if not self._is_lockfile_present():
-                    return
-
-        self.module.fail_json(msg='{0} lockfile is held by another process'.format(self.pkg_mgr_name))
-
     def listify_comma_sep_strings_in_list(self, some_list):
         """
         method to accept a list of strings as the parameter, find any strings

ansible/modules/add_host.py

@@ -4,8 +4,7 @@
 # Copyright: Ansible Team
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = r'''

ansible/modules/apt.py

@@ -6,8 +6,7 @@
 
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = '''
@@ -206,14 +205,17 @@ attributes:
 notes:
    - Three of the upgrade modes (V(full), V(safe) and its alias V(true)) required C(aptitude) up to 2.3, since 2.4 C(apt-get) is used as a fall-back.
    - In most cases, packages installed with apt will start newly installed services by default. Most distributions have mechanisms to avoid this.
-     For example when installing Postgresql-9.5 in Debian 9, creating an excutable shell script (/usr/sbin/policy-rc.d) that throws
-     a return code of 101 will stop Postgresql 9.5 starting up after install. Remove the file or remove its execute permission afterwards.
+     For example when installing Postgresql-9.5 in Debian 9, creating an executable shell script (/usr/sbin/policy-rc.d) that throws
+     a return code of 101 will stop Postgresql 9.5 starting up after install. Remove the file or  its execute permission afterward.
    - The apt-get commandline supports implicit regex matches here but we do not because it can let typos through easier
      (If you typo C(foo) as C(fo) apt-get would install packages that have "fo" in their name with a warning and a prompt for the user.
-     Since we don't have warnings and prompts before installing we disallow this.Use an explicit fnmatch pattern if you want wildcarding)
+     Since we don't have warnings and prompts before installing, we disallow this.Use an explicit fnmatch pattern if you want wildcarding)
    - When used with a C(loop:) each package will be processed individually, it is much more efficient to pass the list directly to the O(name) option.
    - When O(default_release) is used, an implicit priority of 990 is used. This is the same behavior as C(apt-get -t).
    - When an exact version is specified, an implicit priority of 1001 is used.
+   - If the interpreter can't import ``python-apt``/``python3-apt`` the module will check for it in system-owned interpreters as well.
+     If the dependency can't be found, the module will attempt to install it.
+     If the dependency is found or installed, the module will be respawned under the correct interpreter.
 '''
 
 EXAMPLES = '''
@@ -322,7 +324,7 @@ EXAMPLES = '''
     purge: true
 
 - name: Run the equivalent of "apt-get clean" as a separate step
-  apt:
+  ansible.builtin.apt:
     clean: yes
 '''
 
@@ -370,10 +372,11 @@ import tempfile
 import time
 
 from ansible.module_utils.basic import AnsibleModule
+from ansible.module_utils.common.file import S_IRWXU_RXG_RXO
 from ansible.module_utils.common.locale import get_best_parsable_locale
 from ansible.module_utils.common.respawn import has_respawned, probe_interpreters_for_module, respawn_module
 from ansible.module_utils.common.text.converters import to_native, to_text
-from ansible.module_utils.six import PY3, string_types
+from ansible.module_utils.six import string_types
 from ansible.module_utils.urls import fetch_file
 
 DPKG_OPTIONS = 'force-confdef,force-confold'
@@ -446,7 +449,7 @@ class PolicyRcD(object):
             with open('/usr/sbin/policy-rc.d', 'w') as policy_rc_d:
                 policy_rc_d.write('#!/bin/sh\nexit %d\n' % self.m.params['policy_rc_d'])
 
-            os.chmod('/usr/sbin/policy-rc.d', 0o0755)
+            os.chmod('/usr/sbin/policy-rc.d', S_IRWXU_RXG_RXO)
         except Exception:
             self.m.fail_json(msg="Failed to create or chmod /usr/sbin/policy-rc.d")
 
@@ -883,6 +886,11 @@ def install_deb(
         except Exception as e:
             m.fail_json(msg="Unable to install package: %s" % to_native(e))
 
+        # Install 'Recommends' of this deb file
+        if install_recommends:
+            pkg_recommends = get_field_of_deb(m, deb_file, "Recommends")
+            deps_to_install.extend([pkg_name.strip() for pkg_name in pkg_recommends.split()])
+
         # and add this deb to the list of packages to install
         pkgs_to_install.append(deb_file)
 
@@ -1246,6 +1254,15 @@ def main():
     )
     module.run_command_environ_update = APT_ENV_VARS
 
+    global APTITUDE_CMD
+    APTITUDE_CMD = module.get_bin_path("aptitude", False)
+    global APT_GET_CMD
+    APT_GET_CMD = module.get_bin_path("apt-get")
+
+    p = module.params
+    install_recommends = p['install_recommends']
+    dpkg_options = expand_dpkg_options(p['dpkg_options'])
+
     if not HAS_PYTHON_APT:
         # This interpreter can't see the apt Python library- we'll do the following to try and fix that:
         # 1) look in common locations for system-owned interpreters that can see it; if we find one, respawn under it
@@ -1258,13 +1275,13 @@ def main():
         #    made any more complex than it already is to try and cover more, eg, custom interpreters taking over
         #    system locations)
 
-        apt_pkg_name = 'python3-apt' if PY3 else 'python-apt'
+        apt_pkg_name = 'python3-apt'
 
         if has_respawned():
             # this shouldn't be possible; short-circuit early if it happens...
             module.fail_json(msg="{0} must be installed and visible from {1}.".format(apt_pkg_name, sys.executable))
 
-        interpreters = ['/usr/bin/python3', '/usr/bin/python2', '/usr/bin/python']
+        interpreters = ['/usr/bin/python3', '/usr/bin/python']
 
         interpreter = probe_interpreters_for_module(interpreters, 'apt')
 
@@ -1284,10 +1301,18 @@ def main():
             module.warn("Auto-installing missing dependency without updating cache: %s" % apt_pkg_name)
         else:
             module.warn("Updating cache and auto-installing missing dependency: %s" % apt_pkg_name)
-            module.run_command(['apt-get', 'update'], check_rc=True)
+            module.run_command([APT_GET_CMD, 'update'], check_rc=True)
 
         # try to install the apt Python binding
-        module.run_command(['apt-get', 'install', '--no-install-recommends', apt_pkg_name, '-y', '-q'], check_rc=True)
+        apt_pkg_cmd = [APT_GET_CMD, 'install', apt_pkg_name, '-y', '-q', dpkg_options]
+
+        if install_recommends is False:
+            apt_pkg_cmd.extend(["-o", "APT::Install-Recommends=no"])
+        elif install_recommends is True:
+            apt_pkg_cmd.extend(["-o", "APT::Install-Recommends=yes"])
+        # install_recommends is None uses the OS default
+
+        module.run_command(apt_pkg_cmd, check_rc=True)
 
         # try again to find the bindings in common places
         interpreter = probe_interpreters_for_module(interpreters, 'apt')
@@ -1301,18 +1326,11 @@ def main():
             # we've done all we can do; just tell the user it's busted and get out
             module.fail_json(msg="{0} must be installed and visible from {1}.".format(apt_pkg_name, sys.executable))
 
-    global APTITUDE_CMD
-    APTITUDE_CMD = module.get_bin_path("aptitude", False)
-    global APT_GET_CMD
-    APT_GET_CMD = module.get_bin_path("apt-get")
-
-    p = module.params
-
     if p['clean'] is True:
         aptclean_stdout, aptclean_stderr, aptclean_diff = aptclean(module)
         # If there is nothing else to do exit. This will set state as
         #  changed based on if the cache was updated.
-        if not p['package'] and not p['upgrade'] and not p['deb']:
+        if not p['package'] and p['upgrade'] == 'no' and not p['deb']:
             module.exit_json(
                 changed=True,
                 msg=aptclean_stdout,
@@ -1331,11 +1349,9 @@ def main():
 
     updated_cache = False
     updated_cache_time = 0
-    install_recommends = p['install_recommends']
     allow_unauthenticated = p['allow_unauthenticated']
     allow_downgrade = p['allow_downgrade']
     allow_change_held_packages = p['allow_change_held_packages']
-    dpkg_options = expand_dpkg_options(p['dpkg_options'])
     autoremove = p['autoremove']
     fail_on_autoremove = p['fail_on_autoremove']
     autoclean = p['autoclean']

ansible/modules/apt_key.py

@@ -5,8 +5,7 @@
 
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = '''

ansible/modules/apt_repository.py

@@ -6,8 +6,7 @@
 
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = '''
@@ -181,9 +180,9 @@ import random
 import time
 
 from ansible.module_utils.basic import AnsibleModule
+from ansible.module_utils.common.file import S_IRWU_RG_RO as DEFAULT_SOURCES_PERM
 from ansible.module_utils.common.respawn import has_respawned, probe_interpreters_for_module, respawn_module
 from ansible.module_utils.common.text.converters import to_native
-from ansible.module_utils.six import PY3
 from ansible.module_utils.urls import fetch_url
 
 from ansible.module_utils.common.locale import get_best_parsable_locale
@@ -202,7 +201,6 @@ except ImportError:
     HAVE_PYTHON_APT = False
 
 APT_KEY_DIRS = ['/etc/apt/keyrings', '/etc/apt/trusted.gpg.d', '/usr/share/keyrings']
-DEFAULT_SOURCES_PERM = 0o0644
 VALID_SOURCE_TYPES = ('deb', 'deb-src')
 
 
@@ -231,6 +229,7 @@ class SourcesList(object):
     def __init__(self, module):
         self.module = module
         self.files = {}  # group sources by file
+        self.files_mapping = {}  # internal DS for tracking symlinks
         # Repositories that we're adding -- used to implement mode param
         self.new_repos = set()
         self.default_file = self._apt_cfg_file('Dir::Etc::sourcelist')
@@ -241,6 +240,8 @@ class SourcesList(object):
 
         # read sources.list.d
         for file in glob.iglob('%s/*.list' % self._apt_cfg_dir('Dir::Etc::sourceparts')):
+            if os.path.islink(file):
+                self.files_mapping[file] = os.readlink(file)
             self.load(file)
 
     def __iter__(self):
@@ -373,7 +374,11 @@ class SourcesList(object):
                         f.write(line)
                     except IOError as ex:
                         self.module.fail_json(msg="Failed to write to file %s: %s" % (tmp_path, to_native(ex)))
-                self.module.atomic_move(tmp_path, filename)
+                if filename in self.files_mapping:
+                    # Write to symlink target instead of replacing symlink as a normal file
+                    self.module.atomic_move(tmp_path, self.files_mapping[filename])
+                else:
+                    self.module.atomic_move(tmp_path, filename)
 
                 # allow the user to override the default mode
                 if filename in self.new_repos:
@@ -418,7 +423,7 @@ class SourcesList(object):
     def _add_valid_source(self, source_new, comment_new, file):
         # We'll try to reuse disabled source if we have it.
         # If we have more than one entry, we will enable them all - no advanced logic, remember.
-        self.module.log('ading source file: %s | %s | %s' % (source_new, comment_new, file))
+        self.module.log('adding source file: %s | %s | %s' % (source_new, comment_new, file))
         found = False
         for filename, n, enabled, source, comment in self:
             if source == source_new:
@@ -457,7 +462,10 @@ class SourcesList(object):
 
 class UbuntuSourcesList(SourcesList):
 
-    LP_API = 'https://launchpad.net/api/1.0/~%s/+archive/%s'
+    # prefer api.launchpad.net over launchpad.net/api
+    # see: https://github.com/ansible/ansible/pull/81978#issuecomment-1767062178
+    LP_API = 'https://api.launchpad.net/1.0/~%s/+archive/%s'
+    PPA_URI = 'https://ppa.launchpadcontent.net'
 
     def __init__(self, module):
         self.module = module
@@ -489,7 +497,7 @@ class UbuntuSourcesList(SourcesList):
         except IndexError:
             ppa_name = 'ppa'
 
-        line = 'deb http://ppa.launchpad.net/%s/%s/ubuntu %s main' % (ppa_owner, ppa_name, self.codename)
+        line = 'deb %s/%s/%s/ubuntu %s main' % (self.PPA_URI, ppa_owner, ppa_name, self.codename)
         return line, ppa_owner, ppa_name
 
     def _key_already_exists(self, key_fingerprint):
@@ -656,13 +664,13 @@ def main():
         #    made any more complex than it already is to try and cover more, eg, custom interpreters taking over
         #    system locations)
 
-        apt_pkg_name = 'python3-apt' if PY3 else 'python-apt'
+        apt_pkg_name = 'python3-apt'
 
         if has_respawned():
             # this shouldn't be possible; short-circuit early if it happens...
             module.fail_json(msg="{0} must be installed and visible from {1}.".format(apt_pkg_name, sys.executable))
 
-        interpreters = ['/usr/bin/python3', '/usr/bin/python2', '/usr/bin/python']
+        interpreters = ['/usr/bin/python3', '/usr/bin/python']
 
         interpreter = probe_interpreters_for_module(interpreters, 'apt')
 

ansible/modules/assemble.py

@@ -5,8 +5,7 @@
 # Copyright: (c) 2017, Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = r'''

ansible/modules/assert.py

@@ -3,8 +3,7 @@
 # Copyright: (c) 2012, Dag Wieers <dag@wieers.com>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = r'''
@@ -74,12 +73,17 @@ author:
 '''
 
 EXAMPLES = r'''
-- ansible.builtin.assert: { that: "ansible_os_family != 'RedHat'" }
+- name: A single condition can be supplied as string instead of list
+  ansible.builtin.assert:
+    that: "ansible_os_family != 'RedHat'"
 
-- ansible.builtin.assert:
+- name: Use yaml multiline strings to ease escaping
+  ansible.builtin.assert:
     that:
       - "'foo' in some_command_result.stdout"
       - number_of_the_counting == 3
+      - >
+        "reject" not in some_command_result.stderr
 
 - name: After version 2.7 both 'msg' and 'fail_msg' can customize failing assertion message
   ansible.builtin.assert:

ansible/modules/async_status.py

@@ -3,8 +3,7 @@
 # Copyright: (c) 2012, Michael DeHaan <michael.dehaan@gmail.com>, and others
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = r'''
@@ -37,7 +36,8 @@ attributes:
     async:
         support: none
     check_mode:
-        support: none
+        support: full
+        version_added: '2.17'
     diff_mode:
         support: none
     bypass_host_loop:
@@ -55,17 +55,17 @@ author:
 
 EXAMPLES = r'''
 ---
-- name: Asynchronous yum task
-  ansible.builtin.yum:
+- name: Asynchronous dnf task
+  ansible.builtin.dnf:
     name: docker-io
     state: present
   async: 1000
   poll: 0
-  register: yum_sleeper
+  register: dnf_sleeper
 
 - name: Wait for asynchronous job to end
   ansible.builtin.async_status:
-    jid: '{{ yum_sleeper.ansible_job_id }}'
+    jid: '{{ dnf_sleeper.ansible_job_id }}'
   register: job_result
   until: job_result.finished
   retries: 100
@@ -73,7 +73,7 @@ EXAMPLES = r'''
 
 - name: Clean up async file
   ansible.builtin.async_status:
-    jid: '{{ yum_sleeper.ansible_job_id }}'
+    jid: '{{ dnf_sleeper.ansible_job_id }}'
     mode: cleanup
 '''
 
@@ -117,12 +117,15 @@ from ansible.module_utils.common.text.converters import to_native
 
 def main():
 
-    module = AnsibleModule(argument_spec=dict(
-        jid=dict(type='str', required=True),
-        mode=dict(type='str', default='status', choices=['cleanup', 'status']),
-        # passed in from the async_status action plugin
-        _async_dir=dict(type='path', required=True),
-    ))
+    module = AnsibleModule(
+        argument_spec=dict(
+            jid=dict(type="str", required=True),
+            mode=dict(type="str", default="status", choices=["cleanup", "status"]),
+            # passed in from the async_status action plugin
+            _async_dir=dict(type="path", required=True),
+        ),
+        supports_check_mode=True,
+    )
 
     mode = module.params['mode']
     jid = module.params['jid']

ansible/modules/async_wrapper.py

@@ -3,8 +3,7 @@
 # Copyright: (c) 2012, Michael DeHaan <michael.dehaan@gmail.com>, and others
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 import errno
@@ -22,8 +21,6 @@ import multiprocessing
 
 from ansible.module_utils.common.text.converters import to_text, to_bytes
 
-PY3 = sys.version_info[0] == 3
-
 syslog.openlog('ansible-%s' % os.path.basename(__file__))
 syslog.syslog(syslog.LOG_NOTICE, 'Invoked with %s' % " ".join(sys.argv[1:]))
 
@@ -169,13 +166,18 @@ def _run_module(wrapped_cmd, jid):
         interpreter = _get_interpreter(cmd[0])
         if interpreter:
             cmd = interpreter + cmd
-        script = subprocess.Popen(cmd, shell=False, stdin=subprocess.PIPE, stdout=subprocess.PIPE,
-                                  stderr=subprocess.PIPE)
+        script = subprocess.Popen(
+            cmd,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            shell=False,
+            text=True,
+            encoding="utf-8",
+            errors="surrogateescape",
+        )
 
         (outdata, stderr) = script.communicate()
-        if PY3:
-            outdata = outdata.decode('utf-8', 'surrogateescape')
-            stderr = stderr.decode('utf-8', 'surrogateescape')
 
         (filtered_outdata, json_warnings) = _filter_non_json_lines(outdata)
 

ansible/modules/blockinfile.py

@@ -4,8 +4,7 @@
 # Copyright: (c) 2017, Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = r'''
@@ -111,7 +110,7 @@ notes:
   - 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.
-  - When more then one block should be handled in one file you must change the O(marker) per task.
+  - When more than one block should be handled in one file you must change the O(marker) per task.
 extends_documentation_fragment:
     - action_common_attributes
     - action_common_attributes.files

ansible/modules/command.py

@@ -4,8 +4,7 @@
 # Copyright: (c) 2016, Toshio Kuratomi <tkuratomi@ansible.com>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
 
 
 DOCUMENTATION = r'''