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

ansible/plugins/filter/encryption.py

@@ -2,80 +2,80 @@
 
 from __future__ import annotations
 
-from jinja2.runtime import Undefined
-from jinja2.exceptions import UndefinedError
-
-from ansible.errors import AnsibleFilterError, AnsibleFilterTypeError
+from ansible.errors import AnsibleError
 from ansible.module_utils.common.text.converters import to_native, to_bytes
-from ansible.module_utils.six import string_types, binary_type
-from ansible.parsing.yaml.objects import AnsibleVaultEncryptedUnicode
-from ansible.parsing.vault import is_encrypted, VaultSecret, VaultLib
+from ansible.plugins import accept_args_markers
+from ansible._internal._templating._jinja_common import get_first_marker_arg, VaultExceptionMarker
+from ansible._internal._datatag._tags import VaultedValue
+from ansible.parsing.vault import is_encrypted, VaultSecret, VaultLib, VaultHelper
 from ansible.utils.display import Display
 
 display = Display()
 
 
 def do_vault(data, secret, salt=None, vault_id='filter_default', wrap_object=False, vaultid=None):
+    if not isinstance(secret, (str, bytes)):
+        raise TypeError(f"Secret passed is required to be a string, instead we got {type(secret)}.")
 
-    if not isinstance(secret, (string_types, binary_type, Undefined)):
-        raise AnsibleFilterTypeError("Secret passed is required to be a string, instead we got: %s" % type(secret))
-
-    if not isinstance(data, (string_types, binary_type, Undefined)):
-        raise AnsibleFilterTypeError("Can only vault strings, instead we got: %s" % type(data))
+    if not isinstance(data, (str, bytes)):
+        raise TypeError(f"Can only vault strings, instead we got {type(data)}.")
 
     if vaultid is not None:
         display.deprecated("Use of undocumented 'vaultid', use 'vault_id' instead", version='2.20')
+
         if vault_id == 'filter_default':
             vault_id = vaultid
         else:
             display.warning("Ignoring vaultid as vault_id is already set.")
 
-    vault = ''
     vs = VaultSecret(to_bytes(secret))
     vl = VaultLib()
     try:
         vault = vl.encrypt(to_bytes(data), vs, vault_id, salt)
-    except UndefinedError:
-        raise
-    except Exception as e:
-        raise AnsibleFilterError("Unable to encrypt: %s" % to_native(e), orig_exc=e)
+    except Exception as ex:
+        raise AnsibleError("Unable to encrypt.") from ex
 
     if wrap_object:
-        vault = AnsibleVaultEncryptedUnicode(vault)
+        vault = VaultedValue(ciphertext=str(vault)).tag(secret)
     else:
         vault = to_native(vault)
 
     return vault
 
 
+@accept_args_markers
 def do_unvault(vault, secret, vault_id='filter_default', vaultid=None):
+    if isinstance(vault, VaultExceptionMarker):
+        vault = vault._disarm()
+
+    if (first_marker := get_first_marker_arg((vault, secret, vault_id, vaultid), {})) is not None:
+        return first_marker
 
-    if not isinstance(secret, (string_types, binary_type, Undefined)):
-        raise AnsibleFilterTypeError("Secret passed is required to be as string, instead we got: %s" % type(secret))
+    if not isinstance(secret, (str, bytes)):
+        raise TypeError(f"Secret passed is required to be as string, instead we got {type(secret)}.")
 
-    if not isinstance(vault, (string_types, binary_type, AnsibleVaultEncryptedUnicode, Undefined)):
-        raise AnsibleFilterTypeError("Vault should be in the form of a string, instead we got: %s" % type(vault))
+    if not isinstance(vault, (str, bytes)):
+        raise TypeError(f"Vault should be in the form of a string, instead we got {type(vault)}.")
 
     if vaultid is not None:
         display.deprecated("Use of undocumented 'vaultid', use 'vault_id' instead", version='2.20')
+
         if vault_id == 'filter_default':
             vault_id = vaultid
         else:
             display.warning("Ignoring vaultid as vault_id is already set.")
 
-    data = ''
     vs = VaultSecret(to_bytes(secret))
     vl = VaultLib([(vault_id, vs)])
-    if isinstance(vault, AnsibleVaultEncryptedUnicode):
-        vault.vault = vl
-        data = vault.data
-    elif is_encrypted(vault):
+
+    if ciphertext := VaultHelper.get_ciphertext(vault, with_tags=True):
+        vault = ciphertext
+
+    if is_encrypted(vault):
         try:
             data = vl.decrypt(vault)
-        except UndefinedError:
-            raise
-        except Exception as e:
-            raise AnsibleFilterError("Unable to decrypt: %s" % to_native(e), orig_exc=e)
+        except Exception as ex:
+            raise AnsibleError("Unable to decrypt.") from ex
     else:
         data = vault
 
@@ -83,7 +83,7 @@ def do_unvault(vault, secret, vault_id='filter_default', vaultid=None):
 
 
 class FilterModule(object):
-    ''' Ansible vault jinja2 filters '''
+    """ Ansible vault jinja2 filters """
 
     def filters(self):
         filters = {

ansible/plugins/filter/flatten.yml

@@ -7,8 +7,9 @@ DOCUMENTATION:
   positional: _input, levels, skip_nulls
   options:
     _input:
-      description: First dictionary to combine.
-      type: dict
+      description: List to flatten.
+      type: list
+      elements: any
       required: true
     levels:
       description: Number of recursive list depths to flatten.

ansible/plugins/filter/human_to_bytes.yml

@@ -31,7 +31,7 @@ EXAMPLES: |
   # size => 2684354560
   size: '{{ "2.5 gigabyte" | human_to_bytes }}'
   
-  # size => 1234803098
+  # size => 1073741824
   size: '{{ "1 Gigabyte" | human_to_bytes }}'
 
   # this is an error, because gigggabyte is not a valid unit

ansible/plugins/filter/mathstuff.py

@@ -27,10 +27,9 @@ from collections.abc import Mapping, Iterable
 
 from jinja2.filters import pass_environment
 
-from ansible.errors import AnsibleFilterError, AnsibleFilterTypeError
+from ansible.errors import AnsibleError
 from ansible.module_utils.common.text import formatters
 from ansible.module_utils.six import binary_type, text_type
-from ansible.module_utils.common.text.converters import to_native, to_text
 from ansible.utils.display import Display
 
 try:
@@ -48,10 +47,11 @@ display = Display()
 # explicitly set and cannot be handle (by Jinja2 w/o 'unique' or fallback version)
 def unique(environment, a, case_sensitive=None, attribute=None):
 
-    def _do_fail(e):
+    def _do_fail(ex):
         if case_sensitive is False or attribute:
-            raise AnsibleFilterError("Jinja2's unique filter failed and we cannot fall back to Ansible's version "
-                                     "as it does not support the parameters supplied", orig_exc=e)
+            raise AnsibleError(
+                "Jinja2's unique filter failed and we cannot fall back to Ansible's version as it does not support the parameters supplied."
+            ) from ex
 
     error = e = None
     try:
@@ -63,14 +63,14 @@ def unique(environment, a, case_sensitive=None, attribute=None):
     except Exception as e:
         error = e
         _do_fail(e)
-        display.warning('Falling back to Ansible unique filter as Jinja2 one failed: %s' % to_text(e))
+        display.error_as_warning('Falling back to Ansible unique filter as Jinja2 one failed.', e)
 
     if not HAS_UNIQUE or error:
 
         # handle Jinja2 specific attributes when using Ansible's version
         if case_sensitive is False or attribute:
-            raise AnsibleFilterError("Ansible's unique filter does not support case_sensitive=False nor attribute parameters, "
-                                     "you need a newer version of Jinja2 that provides their version of the filter.")
+            raise AnsibleError("Ansible's unique filter does not support case_sensitive=False nor attribute parameters, "
+                               "you need a newer version of Jinja2 that provides their version of the filter.")
 
         c = []
         for x in a:
@@ -123,15 +123,15 @@ def logarithm(x, base=math.e):
             return math.log10(x)
         else:
             return math.log(x, base)
-    except TypeError as e:
-        raise AnsibleFilterTypeError('log() can only be used on numbers: %s' % to_native(e))
+    except TypeError as ex:
+        raise AnsibleError('log() can only be used on numbers') from ex
 
 
 def power(x, y):
     try:
         return math.pow(x, y)
-    except TypeError as e:
-        raise AnsibleFilterTypeError('pow() can only be used on numbers: %s' % to_native(e))
+    except TypeError as ex:
+        raise AnsibleError('pow() can only be used on numbers') from ex
 
 
 def inversepower(x, base=2):
@@ -140,28 +140,28 @@ def inversepower(x, base=2):
             return math.sqrt(x)
         else:
             return math.pow(x, 1.0 / float(base))
-    except (ValueError, TypeError) as e:
-        raise AnsibleFilterTypeError('root() can only be used on numbers: %s' % to_native(e))
+    except (ValueError, TypeError) as ex:
+        raise AnsibleError('root() can only be used on numbers') from ex
 
 
 def human_readable(size, isbits=False, unit=None):
-    ''' Return a human-readable string '''
+    """ Return a human-readable string """
     try:
         return formatters.bytes_to_human(size, isbits, unit)
-    except TypeError as e:
-        raise AnsibleFilterTypeError("human_readable() failed on bad input: %s" % to_native(e))
-    except Exception:
-        raise AnsibleFilterError("human_readable() can't interpret following string: %s" % size)
+    except TypeError as ex:
+        raise AnsibleError("human_readable() failed on bad input") from ex
+    except Exception as ex:
+        raise AnsibleError("human_readable() can't interpret the input") from ex
 
 
 def human_to_bytes(size, default_unit=None, isbits=False):
-    ''' Return bytes count from a human-readable string '''
+    """ Return bytes count from a human-readable string """
     try:
         return formatters.human_to_bytes(size, default_unit, isbits)
-    except TypeError as e:
-        raise AnsibleFilterTypeError("human_to_bytes() failed on bad input: %s" % to_native(e))
-    except Exception:
-        raise AnsibleFilterError("human_to_bytes() can't interpret following string: %s" % size)
+    except TypeError as ex:
+        raise AnsibleError("human_to_bytes() failed on bad input") from ex
+    except Exception as ex:
+        raise AnsibleError("human_to_bytes() can't interpret the input") from ex
 
 
 def rekey_on_member(data, key, duplicates='error'):
@@ -174,38 +174,31 @@ def rekey_on_member(data, key, duplicates='error'):
     value would be duplicated or to overwrite previous entries if that's the case.
     """
     if duplicates not in ('error', 'overwrite'):
-        raise AnsibleFilterError("duplicates parameter to rekey_on_member has unknown value: {0}".format(duplicates))
+        raise AnsibleError(f"duplicates parameter to rekey_on_member has unknown value {duplicates!r}")
 
     new_obj = {}
 
-    # Ensure the positional args are defined - raise jinja2.exceptions.UndefinedError if not
-    bool(data) and bool(key)
-
     if isinstance(data, Mapping):
         iterate_over = data.values()
     elif isinstance(data, Iterable) and not isinstance(data, (text_type, binary_type)):
         iterate_over = data
     else:
-        raise AnsibleFilterTypeError("Type is not a valid list, set, or dict")
+        raise AnsibleError("Type is not a valid list, set, or dict")
 
     for item in iterate_over:
         if not isinstance(item, Mapping):
-            raise AnsibleFilterTypeError("List item is not a valid dict")
+            raise AnsibleError("List item is not a valid dict")
 
         try:
             key_elem = item[key]
         except KeyError:
-            raise AnsibleFilterError("Key {0} was not found".format(key))
-        except TypeError as e:
-            raise AnsibleFilterTypeError(to_native(e))
-        except Exception as e:
-            raise AnsibleFilterError(to_native(e))
+            raise AnsibleError(f"Key {key!r} was not found.", obj=item) from None
 
         # Note: if new_obj[key_elem] exists it will always be a non-empty dict (it will at
         # minimum contain {key: key_elem}
         if new_obj.get(key_elem, None):
             if duplicates == 'error':
-                raise AnsibleFilterError("Key {0} is not unique, cannot correctly turn into dict".format(key_elem))
+                raise AnsibleError(f"Key {key_elem!r} is not unique, cannot convert to dict.")
             elif duplicates == 'overwrite':
                 new_obj[key_elem] = item
         else:
@@ -215,7 +208,7 @@ def rekey_on_member(data, key, duplicates='error'):
 
 
 class FilterModule(object):
-    ''' Ansible math jinja2 filters '''
+    """ Ansible math jinja2 filters """
 
     def filters(self):
         filters = {

ansible/plugins/filter/password_hash.yml

@@ -32,6 +32,14 @@ EXAMPLES: |
     # pwdhash => "$6$/bQCntzQ7VrgVcFa$VaMkmevkY1dqrx8neaenUDlVU.6L/.ojRbrnI4ID.yBHU6XON1cB422scCiXfUL5wRucMdLgJU0Fn38uoeBni/"
     pwdhash: "{{ 'testing' | password_hash }}"
 
+    # Using hash type
+    # wireguard_admin_password_hash => "$2b$12$ujYVRD9v9z87lpvLqeWNuOFDI4QzSSYHoRyYydW6XK4.kgqfwOXzO"
+    wireguard_admin_password_hash: "{{ 'vagrant-libvirt' | password_hash(hashtype='bcrypt') }}"
+
+    # Using salt value for idempotency
+    # wireguard_admin_password_hash => "$2b$12$abcdefghijklmnopqrstuuTEw8POU2MwwuYEM7WaKcjqZ948Hm7.W"
+    wireguard_admin_password_hash: "{{ 'vagrant-libvirt' | password_hash(hashtype='bcrypt', salt='abcdefghijklmnopqrstuv') }}"
+
 RETURN:
   _value:
     description: The resulting password hash.

ansible/plugins/filter/regex_search.yml

@@ -8,9 +8,6 @@ DOCUMENTATION:
     - Maps to Python's C(re.search).
     - 'The substring matched by the group is accessible via the symbolic group name or
       the ``\{number}`` special sequence. See examples section.'
-    - The return for no match will be C(None) in most cases, depending on whether it is used with other filters/tests or not.
-      It also depends on the Jinja version used and whether native is enabled.
-    - "For a more complete explanation see U(https://docs.ansible.com/ansible-core/devel/reference_appendices/faq.html#why-does-the-regex-search-filter-return-none-instead-of-an-empty-string)."
   positional: _input, _regex
   options:
     _input:
@@ -55,5 +52,5 @@ EXAMPLES: |
 
 RETURN:
   _value:
-    description: Matched string or if no match a C(None) or an empty string (see notes)
+    description: Matched string or C(None) if no match.
     type: str

ansible/plugins/filter/split.yml

@@ -22,7 +22,7 @@ EXAMPLES: |
     # listjojo => [ "jojo", "is", "a" ]
     listjojo: "{{ 'jojo is a' | split }}"
 
-    # listjojocomma => [ "jojo is", "a" ]
+    # listjojocomma => [ "jojo is", " a" ]
     listjojocomma: "{{ 'jojo is, a' | split(',') }}"
 
 RETURN:

ansible/plugins/filter/to_nice_yaml.yml

@@ -20,10 +20,6 @@ DOCUMENTATION:
       description: Affects sorting of dictionary keys.
       default: True
       type: bool
-    #allow_unicode:
-    #  description:
-    #  type: bool
-    #  default: true
     #default_style=None, canonical=None, width=None, line_break=None, encoding=None, explicit_start=None, explicit_end=None, version=None, tags=None
   notes:
     - More options may be available, see L(PyYAML documentation, https://pyyaml.org/wiki/PyYAMLDocumentation) for details.

ansible/plugins/filter/to_yaml.yml

@@ -24,10 +24,6 @@ DOCUMENTATION:
     - More options may be available, see L(PyYAML documentation, https://pyyaml.org/wiki/PyYAMLDocumentation) for details.
 
     # TODO: find docs for these
-    #allow_unicode:
-    #  description:
-    #  type: bool
-    #  default: true
     #default_flow_style
     #default_style
     #canonical=None,

ansible/plugins/filter/unvault.yml

@@ -8,7 +8,7 @@ DOCUMENTATION:
   positional: secret
   options:
     _input:
-      description: Vault string, or an C(AnsibleVaultEncryptedUnicode) string object.
+      description: Vault string.
       type: string
       required: true
     secret:

ansible/plugins/filter/urls.py

@@ -11,7 +11,7 @@ from urllib.parse import unquote_plus
 
 
 class FilterModule(object):
-    ''' Ansible core jinja2 filters '''
+    """ Ansible core jinja2 filters """
 
     def filters(self):
         return {

ansible/plugins/filter/urlsplit.py

@@ -4,7 +4,7 @@
 
 from __future__ import annotations
 
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
   name: urlsplit
   version_added: "2.4"
   short_description: get components from URL
@@ -20,9 +20,9 @@ DOCUMENTATION = r'''
       description: Specify a single component to return.
       type: str
       choices: ["fragment", "hostname", "netloc", "password",  "path",  "port",  "query", "scheme",  "username"]
-'''
+"""
 
-EXAMPLES = r'''
+EXAMPLES = r"""
 
     parts: '{{ "http://user:password@www.acme.com:9000/dir/index.html?query=term#fragment" | urlsplit }}'
     # =>
@@ -46,19 +46,18 @@ EXAMPLES = r'''
 
     path: '{{ "http://user:password@www.acme.com:9000/dir/index.html?query=term#fragment" | urlsplit("path") }}'
     # => '/dir/index.html'
-'''
+"""
 
-RETURN = r'''
+RETURN = r"""
   _value:
     description:
       - A dictionary with components as keyword and their value.
       - If O(query) is provided, a string or integer will be returned instead, depending on O(query).
     type: any
-'''
+"""
 
 from urllib.parse import urlsplit
 
-from ansible.errors import AnsibleFilterError
 from ansible.utils import helpers
 
 
@@ -70,7 +69,7 @@ def split_url(value, query='', alias='urlsplit'):
     # If no option is supplied, return the entire dictionary.
     if query:
         if query not in results:
-            raise AnsibleFilterError(alias + ': unknown URL component: %s' % query)
+            raise ValueError(alias + ': unknown URL component: %s' % query)
         return results[query]
     else:
         return results
@@ -78,7 +77,7 @@ def split_url(value, query='', alias='urlsplit'):
 
 # ---- Ansible filters ----
 class FilterModule(object):
-    ''' URI filter '''
+    """ URI filter """
 
     def filters(self):
         return {

ansible/plugins/filter/vault.yml

@@ -26,23 +26,28 @@ DOCUMENTATION:
       default: 'filter_default'
     wrap_object:
       description:
-        - This toggle can force the return of an C(AnsibleVaultEncryptedUnicode) string object, when V(False), you get a simple string.
+        - This toggle can force the return of a C(VaultedValue)-tagged string object, when V(False), you get a simple string.
         - Mostly useful when combining with the C(to_yaml) filter to output the 'inline vault' format.
       type: bool
       default: False
 
 EXAMPLES: |
-  # simply encrypt my key in a vault
+  # Encrypt a value using the vault filter
   vars:
-    myvaultedkey: "{{ keyrawdata|vault(passphrase) }} "
+    myvaultedkey: "{{ 'my_secret_key' | vault('my_vault_password') }}"
 
-  - name: save templated vaulted data
-    template: src=dump_template_data.j2 dest=/some/key/vault.txt
-    vars:
-      mysalt: '{{2**256|random(seed=inventory_hostname)}}'
-      template_data: '{{ secretdata|vault(vaultsecret, salt=mysalt) }}'
+  # Encrypt a value and save it to a file using the template module
+  vars:
+    template_data: "{{ 'my_sensitive_data' | vault('another_vault_password', salt=(2**256 | random(seed=inventory_hostname))) }}"
+
+  # The content of dump_template_data.j2 looks like
+  #     Encrypted secret: {{ template_data }}
+  - name: Save vaulted data
+    template:
+      src: dump_template_data.j2
+      dest: /some/key/vault.txt
 
 RETURN:
   _value:
-    description: The vault string that contains the secret data (or C(AnsibleVaultEncryptedUnicode) string object).
+    description: The vault string that contains the secret data (or C(VaultedValue)-tagged string object).
     type: string

ansible/plugins/filter/win_basename.yml

@@ -5,6 +5,7 @@ DOCUMENTATION:
   short_description: Get a Windows path's base name
   description:
     - Returns the last name component of a Windows path, what is left in the string that is not 'win_dirname'.
+    - While specifying an UNC (Universal Naming Convention) path, please make sure the path conforms to the UNC path syntax.
   options:
     _input:
       description: A Windows path.
@@ -16,7 +17,11 @@ DOCUMENTATION:
 EXAMPLES: |
 
   # To get the last name of a file Windows path, like 'foo.txt' out of 'C:\Users\asdf\foo.txt'
-  {{ mypath | win_basename }}
+  filename: "{{ mypath | win_basename }}"
+
+  # Get basename from the UNC path in the form of '\\<SERVER_NAME>\<SHARE_NAME>\<FILENAME.FILE_EXTENSION>'
+  # like '\\server1\test\foo.txt' returns 'foo.txt'
+  filename: "{{ mypath | win_basename }}"
 
 RETURN:
   _value:

ansible/plugins/filter/win_dirname.yml

@@ -5,6 +5,7 @@ DOCUMENTATION:
   short_description: Get a Windows path's directory
   description:
     - Returns the directory component of a Windows path, what is left in the string that is not 'win_basename'.
+    - While specifying an UNC (Universal Naming Convention) path, please make sure the path conforms to the UNC path syntax.
   options:
     _input:
       description: A Windows path.
@@ -18,6 +19,10 @@ EXAMPLES: |
   # To get the last name of a file Windows path, like 'C:\users\asdf' out of 'C:\Users\asdf\foo.txt'
   {{ mypath | win_dirname }}
 
+  # Get dirname from the UNC path in the form of '\\<SERVER_NAME>\<SHARE_NAME>\<FILENAME.FILE_EXTENSION>'
+  # like '\\server1\test\foo.txt' returns '\\\\server1\\test\\'
+  filename: "{{ mypath | win_dirname }}"
+
 RETURN:
   _value:
     description: The directory from the Windows path provided.