ansible-core 2.17.5rc1__py3-none-any.whl → 2.18.0rc1__py3-none-any.whl

ansible/plugins/connection/psrp.py

@@ -324,12 +324,11 @@ from ansible.utils.hashing import sha1
 HAS_PYPSRP = True
 PYPSRP_IMP_ERR = None
 try:
-    import pypsrp
     from pypsrp.complex_objects import GenericComplexObject, PSInvocationState, RunspacePoolState
     from pypsrp.exceptions import AuthenticationError, WinRMError
     from pypsrp.host import PSHost, PSHostUserInterface
     from pypsrp.powershell import PowerShell, RunspacePool
-    from pypsrp.wsman import WSMan, AUTH_KWARGS
+    from pypsrp.wsman import WSMan
     from requests.exceptions import ConnectionError, ConnectTimeout
 except ImportError as err:
     HAS_PYPSRP = False
@@ -344,9 +343,8 @@ class Connection(ConnectionBase):
     module_implementation_preferences = ('.ps1', '.exe', '')
     allow_executable = False
     has_pipelining = True
-    allow_extras = True
 
-    # Satifies mypy as this connection only ever runs with this plugin
+    # Satisfies mypy as this connection only ever runs with this plugin
     _shell: PowerShellPlugin
 
     def __init__(self, *args: t.Any, **kwargs: t.Any) -> None:
@@ -712,7 +710,6 @@ if ($read -gt 0) {
     def _build_kwargs(self) -> None:
         self._psrp_host = self.get_option('remote_addr')
         self._psrp_user = self.get_option('remote_user')
-        self._psrp_pass = self.get_option('remote_password')
 
         protocol = self.get_option('protocol')
         port = self.get_option('port')
@@ -724,95 +721,49 @@ if ($read -gt 0) {
         elif port is None:
             port = 5986 if protocol == 'https' else 5985
 
-        self._psrp_protocol = protocol
         self._psrp_port = int(port)
-
-        self._psrp_path = self.get_option('path')
         self._psrp_auth = self.get_option('auth')
+        self._psrp_configuration_name = self.get_option('configuration_name')
+
         # cert validation can either be a bool or a path to the cert
         cert_validation = self.get_option('cert_validation')
         cert_trust_path = self.get_option('ca_cert')
         if cert_validation == 'ignore':
-            self._psrp_cert_validation = False
+            psrp_cert_validation = False
         elif cert_trust_path is not None:
-            self._psrp_cert_validation = cert_trust_path
+            psrp_cert_validation = cert_trust_path
         else:
-            self._psrp_cert_validation = True
-
-        self._psrp_connection_timeout = self.get_option('connection_timeout')  # Can be None
-        self._psrp_read_timeout = self.get_option('read_timeout')  # Can be None
-        self._psrp_message_encryption = self.get_option('message_encryption')
-        self._psrp_proxy = self.get_option('proxy')
-        self._psrp_ignore_proxy = boolean(self.get_option('ignore_proxy'))
-        self._psrp_operation_timeout = int(self.get_option('operation_timeout'))
-        self._psrp_max_envelope_size = int(self.get_option('max_envelope_size'))
-        self._psrp_configuration_name = self.get_option('configuration_name')
-        self._psrp_reconnection_retries = int(self.get_option('reconnection_retries'))
-        self._psrp_reconnection_backoff = float(self.get_option('reconnection_backoff'))
-
-        self._psrp_certificate_key_pem = self.get_option('certificate_key_pem')
-        self._psrp_certificate_pem = self.get_option('certificate_pem')
-        self._psrp_credssp_auth_mechanism = self.get_option('credssp_auth_mechanism')
-        self._psrp_credssp_disable_tlsv1_2 = self.get_option('credssp_disable_tlsv1_2')
-        self._psrp_credssp_minimum_version = self.get_option('credssp_minimum_version')
-        self._psrp_negotiate_send_cbt = self.get_option('negotiate_send_cbt')
-        self._psrp_negotiate_delegate = self.get_option('negotiate_delegate')
-        self._psrp_negotiate_hostname_override = self.get_option('negotiate_hostname_override')
-        self._psrp_negotiate_service = self.get_option('negotiate_service')
-
-        supported_args = []
-        for auth_kwarg in AUTH_KWARGS.values():
-            supported_args.extend(auth_kwarg)
-        extra_args = {v.replace('ansible_psrp_', '') for v in self.get_option('_extras')}
-        unsupported_args = extra_args.difference(supported_args)
-
-        for arg in unsupported_args:
-            display.warning("ansible_psrp_%s is unsupported by the current "
-                            "psrp version installed" % arg)
+            psrp_cert_validation = True
 
         self._psrp_conn_kwargs = dict(
-            server=self._psrp_host, port=self._psrp_port,
-            username=self._psrp_user, password=self._psrp_pass,
-            ssl=self._psrp_protocol == 'https', path=self._psrp_path,
-            auth=self._psrp_auth, cert_validation=self._psrp_cert_validation,
-            connection_timeout=self._psrp_connection_timeout,
-            encryption=self._psrp_message_encryption, proxy=self._psrp_proxy,
-            no_proxy=self._psrp_ignore_proxy,
-            max_envelope_size=self._psrp_max_envelope_size,
-            operation_timeout=self._psrp_operation_timeout,
-            certificate_key_pem=self._psrp_certificate_key_pem,
-            certificate_pem=self._psrp_certificate_pem,
-            credssp_auth_mechanism=self._psrp_credssp_auth_mechanism,
-            credssp_disable_tlsv1_2=self._psrp_credssp_disable_tlsv1_2,
-            credssp_minimum_version=self._psrp_credssp_minimum_version,
-            negotiate_send_cbt=self._psrp_negotiate_send_cbt,
-            negotiate_delegate=self._psrp_negotiate_delegate,
-            negotiate_hostname_override=self._psrp_negotiate_hostname_override,
-            negotiate_service=self._psrp_negotiate_service,
+            server=self._psrp_host,
+            port=self._psrp_port,
+            username=self._psrp_user,
+            password=self.get_option('remote_password'),
+            ssl=protocol == 'https',
+            path=self.get_option('path'),
+            auth=self._psrp_auth,
+            cert_validation=psrp_cert_validation,
+            connection_timeout=self.get_option('connection_timeout'),
+            encryption=self.get_option('message_encryption'),
+            proxy=self.get_option('proxy'),
+            no_proxy=boolean(self.get_option('ignore_proxy')),
+            max_envelope_size=self.get_option('max_envelope_size'),
+            operation_timeout=self.get_option('operation_timeout'),
+            read_timeout=self.get_option('read_timeout'),
+            reconnection_retries=self.get_option('reconnection_retries'),
+            reconnection_backoff=float(self.get_option('reconnection_backoff')),
+            certificate_key_pem=self.get_option('certificate_key_pem'),
+            certificate_pem=self.get_option('certificate_pem'),
+            credssp_auth_mechanism=self.get_option('credssp_auth_mechanism'),
+            credssp_disable_tlsv1_2=self.get_option('credssp_disable_tlsv1_2'),
+            credssp_minimum_version=self.get_option('credssp_minimum_version'),
+            negotiate_send_cbt=self.get_option('negotiate_send_cbt'),
+            negotiate_delegate=self.get_option('negotiate_delegate'),
+            negotiate_hostname_override=self.get_option('negotiate_hostname_override'),
+            negotiate_service=self.get_option('negotiate_service'),
         )
 
-        # Check if PSRP version supports newer read_timeout argument (needs pypsrp 0.3.0+)
-        if hasattr(pypsrp, 'FEATURES') and 'wsman_read_timeout' in pypsrp.FEATURES:
-            self._psrp_conn_kwargs['read_timeout'] = self._psrp_read_timeout
-        elif self._psrp_read_timeout is not None:
-            display.warning("ansible_psrp_read_timeout is unsupported by the current psrp version installed, "
-                            "using ansible_psrp_connection_timeout value for read_timeout instead.")
-
-        # Check if PSRP version supports newer reconnection_retries argument (needs pypsrp 0.3.0+)
-        if hasattr(pypsrp, 'FEATURES') and 'wsman_reconnections' in pypsrp.FEATURES:
-            self._psrp_conn_kwargs['reconnection_retries'] = self._psrp_reconnection_retries
-            self._psrp_conn_kwargs['reconnection_backoff'] = self._psrp_reconnection_backoff
-        else:
-            if self._psrp_reconnection_retries is not None:
-                display.warning("ansible_psrp_reconnection_retries is unsupported by the current psrp version installed.")
-            if self._psrp_reconnection_backoff is not None:
-                display.warning("ansible_psrp_reconnection_backoff is unsupported by the current psrp version installed.")
-
-        # add in the extra args that were set
-        for arg in extra_args.intersection(supported_args):
-            option = self.get_option('_extras')['ansible_psrp_%s' % arg]
-            self._psrp_conn_kwargs[arg] = option
-
     def _exec_psrp_script(
         self,
         script: str,

ansible/plugins/connection/ssh.py

@@ -1306,14 +1306,6 @@ class Connection(ConnectionBase):
             # prompt that will not occur
             sudoable = False
 
-            # Make sure our first command is to set the console encoding to
-            # utf-8, this must be done via chcp to get utf-8 (65001)
-            # union-attr ignores rely on internal powershell shell plugin details,
-            # this should be fixed at a future point in time.
-            cmd_parts = ["chcp.com", "65001", self._shell._SHELL_REDIRECT_ALLNULL, self._shell._SHELL_AND]  # type: ignore[union-attr]
-            cmd_parts.extend(self._shell._encode_script(cmd, as_list=True, strict_mode=False, preserve_rc=False))  # type: ignore[union-attr]
-            cmd = ' '.join(cmd_parts)
-
         # we can only use tty when we are not pipelining the modules. piping
         # data into /usr/bin/python inside a tty automatically invokes the
         # python interactive-mode but the modules are not compatible with the

ansible/plugins/connection/winrm.py

@@ -207,6 +207,14 @@ except ImportError as e:
     HAS_WINRM = False
     WINRM_IMPORT_ERR = e
 
+try:
+    from winrm.exceptions import WSManFaultError
+except ImportError:
+    # This was added in pywinrm 0.5.0, we just use our no-op exception for
+    # older versions which won't be able to handle this scenario.
+    class WSManFaultError(Exception):  # type: ignore[no-redef]
+        pass
+
 try:
     import xmltodict
     HAS_XMLTODICT = True
@@ -633,7 +641,11 @@ class Connection(ConnectionBase):
         command_id = None
         try:
             stdin_push_failed = False
-            command_id = self.protocol.run_command(self.shell_id, to_bytes(command), map(to_bytes, args), console_mode_stdin=(stdin_iterator is None))
+            command_id = self._winrm_run_command(
+                to_bytes(command),
+                tuple(map(to_bytes, args)),
+                console_mode_stdin=(stdin_iterator is None),
+            )
 
             try:
                 if stdin_iterator:
@@ -697,6 +709,39 @@ class Connection(ConnectionBase):
 
                     display.warning("Failed to cleanup running WinRM command, resources might still be in use on the target server")
 
+    def _winrm_run_command(
+        self,
+        command: bytes,
+        args: tuple[bytes, ...],
+        console_mode_stdin: bool = False,
+    ) -> str:
+        """Starts a command with handling when the WSMan quota is exceeded."""
+        try:
+            return self.protocol.run_command(
+                self.shell_id,
+                command,
+                args,
+                console_mode_stdin=console_mode_stdin,
+            )
+        except WSManFaultError as fault_error:
+            if fault_error.wmierror_code != 0x803381A6:
+                raise
+
+            # 0x803381A6 == ERROR_WSMAN_QUOTA_MAX_OPERATIONS
+            # WinRS does not decrement the operation count for commands,
+            # only way to avoid this is to re-create the shell. This is
+            # important for action plugins that might be running multiple
+            # processes in the same connection.
+            display.vvvvv("Shell operation quota exceeded, re-creating shell", host=self._winrm_host)
+            self.close()
+            self._connect()
+            return self.protocol.run_command(
+                self.shell_id,
+                command,
+                args,
+                console_mode_stdin=console_mode_stdin,
+            )
+
     def _connect(self) -> Connection:
 
         if not HAS_WINRM:

ansible/plugins/doc_fragments/connection_pipelining.py

@@ -14,8 +14,8 @@ options:
             - Pipelining reduces the number of connection operations required to execute a module on the remote server,
               by executing many Ansible modules without actual file transfers.
             - This can result in a very significant performance improvement when enabled.
-            - However this can conflict with privilege escalation (become).
-              For example, when using sudo operations you must first disable 'requiretty' in the sudoers file for the target hosts,
+            - However this can conflict with privilege escalation (C(become)).
+              For example, when using sudo operations you must first disable C(requiretty) in the sudoers file for the target hosts,
               which is why this feature is disabled by default.
           env:
             - name: ANSIBLE_PIPELINING

ansible/plugins/doc_fragments/constructed.py

@@ -32,19 +32,19 @@ options:
     suboptions:
       parent_group:
         type: str
-        description: parent group for keyed group
+        description: parent group for keyed group.
       prefix:
         type: str
-        description: A keyed group name will start with this prefix
+        description: A keyed group name will start with this prefix.
         default: ''
       separator:
         type: str
-        description: separator used to build the keyed group name
+        description: separator used to build the keyed group name.
         default: "_"
       key:
         type: str
         description:
-        - The key from input dictionary used to generate groups
+        - The key from input dictionary used to generate groups.
       default_value:
         description:
         - The default value when the host variable's value is an empty string.
@@ -53,16 +53,16 @@ options:
         version_added: '2.12'
       trailing_separator:
         description:
-        - Set this option to V(False) to omit the O(keyed_groups[].separator) after the host variable when the value is an empty string.
+        - Set this option to V(false) to omit the O(keyed_groups[].separator) after the host variable when the value is an empty string.
         - This option is mutually exclusive with O(keyed_groups[].default_value).
         type: bool
-        default: True
+        default: true
         version_added: '2.12'
   use_extra_vars:
     version_added: '2.11'
     description: Merge extra vars into the available variables for composition (highest precedence).
     type: bool
-    default: False
+    default: false
     ini:
       - section: inventory_plugins
         key: use_extra_vars
@@ -70,10 +70,10 @@ options:
       - name: ANSIBLE_INVENTORY_USE_EXTRA_VARS
   leading_separator:
     description:
-      - Use in conjunction with keyed_groups.
+      - Use in conjunction with O(keyed_groups).
       - By default, a keyed group that does not have a prefix or a separator provided will have a name that starts with an underscore.
-      - This is because the default prefix is "" and the default separator is "_".
-      - Set this option to False to omit the leading underscore (or other separator) if no prefix is given.
+      - This is because the default prefix is V("") and the default separator is V("_").
+      - Set this option to V(false) to omit the leading underscore (or other separator) if no prefix is given.
       - If the group name is derived from a mapping the separator is still used to concatenate the items.
       - To not use a separator in the group name at all, set the separator for the keyed group to an empty string instead.
     type: boolean

ansible/plugins/doc_fragments/default_callback.py

@@ -11,7 +11,7 @@ class ModuleDocFragment(object):
     options:
       display_skipped_hosts:
         name: Show skipped hosts
-        description: "Toggle to control displaying skipped task/host results in a task"
+        description: "Toggle to control displaying skipped task/host results in a task."
         type: bool
         default: yes
         env:
@@ -21,7 +21,7 @@ class ModuleDocFragment(object):
             section: defaults
       display_ok_hosts:
         name: Show 'ok' hosts
-        description: "Toggle to control displaying 'ok' task/host results in a task"
+        description: "Toggle to control displaying 'ok' task/host results in a task."
         type: bool
         default: yes
         env:
@@ -32,7 +32,7 @@ class ModuleDocFragment(object):
         version_added: '2.7'
       display_failed_stderr:
         name: Use STDERR for failed and unreachable tasks
-        description: "Toggle to control whether failed and unreachable tasks are displayed to STDERR (vs. STDOUT)"
+        description: "Toggle to control whether failed and unreachable tasks are displayed to STDERR rather than STDOUT."
         type: bool
         default: no
         env:
@@ -43,7 +43,7 @@ class ModuleDocFragment(object):
         version_added: '2.7'
       show_custom_stats:
         name: Show custom stats
-        description: 'This adds the custom stats set via the set_stats plugin to the play recap'
+        description: 'This adds the custom stats set via the set_stats plugin to the play recap.'
         type: bool
         default: no
         env:
@@ -53,7 +53,7 @@ class ModuleDocFragment(object):
             section: defaults
       show_per_host_start:
         name: Show per host task start
-        description: 'This adds output that shows when a task is started to execute for each host'
+        description: 'This adds output that shows when a task starts to execute for each host.'
         type: bool
         default: no
         env:
@@ -67,7 +67,7 @@ class ModuleDocFragment(object):
         description:
         - Toggle to control displaying markers when running in check mode.
         - "The markers are C(DRY RUN) at the beginning and ending of playbook execution (when calling C(ansible-playbook --check))
-        and C(CHECK MODE) as a suffix at every play and task that is run in check mode."
+          and C(CHECK MODE) as a suffix at every play and task that is run in check mode."
         type: bool
         default: no
         version_added: '2.9'
@@ -79,8 +79,8 @@ class ModuleDocFragment(object):
       show_task_path_on_failure:
         name: Show file path on failed tasks
         description:
-          When a task fails, display the path to the file containing the failed task and the line number.
-          This information is displayed automatically for every task when running with C(-vv) or greater verbosity.
+          - When a task fails, display the path to the file containing the failed task and the line number.
+            This information is displayed automatically for every task when running with C(-vv) or greater verbosity.
         type: bool
         default: no
         env:

ansible/plugins/doc_fragments/files.py

@@ -16,7 +16,7 @@ options:
   mode:
     description:
     - The permissions the resulting filesystem object should have.
-    - For those used to I(/usr/bin/chmod) remember that modes are actually octal numbers.
+    - For those used to C(/usr/bin/chmod) remember that modes are actually octal numbers.
       You must give Ansible enough information to parse them correctly.
       For consistent results, quote octal numbers (for example, V('644') or V('1777')) so Ansible receives
       a string and can do its own conversion from string into number.
@@ -33,7 +33,7 @@ options:
     type: raw
   owner:
     description:
-    - Name of the user that should own the filesystem object, as would be fed to I(chown).
+    - Name of the user that should own the filesystem object, as would be fed to C(chown).
     - When left unspecified, it uses the current user unless you are root, in which
       case it can preserve the previous ownership.
     - Specifying a numeric username will be assumed to be a user ID and not a username. Avoid numeric usernames to avoid this confusion.
@@ -41,7 +41,7 @@ options:
     type: str
   group:
     description:
-    - Name of the group that should own the filesystem object, as would be fed to I(chown).
+    - Name of the group that should own the filesystem object, as would be fed to C(chown).
     - When left unspecified, it uses the current group of the current user unless you are root,
       in which case it can preserve the previous ownership.
     type: str
@@ -82,8 +82,8 @@ options:
   attributes:
     description:
     - The attributes the resulting filesystem object should have.
-    - To get supported flags look at the man page for I(chattr) on the target system.
-    - This string should contain the attributes in the same order as the one displayed by I(lsattr).
+    - To get supported flags look at the man page for C(chattr) on the target system.
+    - This string should contain the attributes in the same order as the one displayed by C(lsattr).
     - The C(=) operator is assumed as default, otherwise C(+) or C(-) operators need to be included in the string.
     type: str
     aliases: [ attr ]

ansible/plugins/doc_fragments/inventory_cache.py

@@ -35,7 +35,7 @@ options:
         key: cache_plugin
   cache_timeout:
     description:
-      - Cache duration in seconds
+      - Cache duration in seconds.
     default: 3600
     type: int
     env:
@@ -60,7 +60,7 @@ options:
         key: cache_connection
   cache_prefix:
     description:
-      - Prefix to use for cache plugin files/tables
+      - Prefix to use for cache plugin files/tables.
     default: ansible_inventory_
     env:
       - name: ANSIBLE_CACHE_PLUGIN_PREFIX

ansible/plugins/doc_fragments/result_format_callback.py

@@ -29,15 +29,15 @@ class ModuleDocFragment(object):
       pretty_results:
         name: Configure output for readability
         description:
-          - Configure the result format to be more readable
-          - When O(result_format) is set to V(yaml) this option defaults to V(True), and defaults
-            to V(False) when configured to V(json).
-          - Setting this option to V(True) will force V(json) and V(yaml) results to always be pretty
+          - Configure the result format to be more readable.
+          - When O(result_format) is set to V(yaml) this option defaults to V(true), and defaults
+            to V(false) when configured to V(json).
+          - Setting this option to V(true) will force V(json) and V(yaml) results to always be pretty
             printed regardless of verbosity.
-          - When set to V(True) and used with the V(yaml) result format, this option will
+          - When set to V(true) and used with the V(yaml) result format, this option will
             modify module responses in an attempt to produce a more human friendly output at the expense
             of correctness, and should not be relied upon to aid in writing variable manipulations
-            or conditionals. For correctness, set this option to V(False) or set O(result_format) to V(json).
+            or conditionals. For correctness, set this option to V(false) or set O(result_format) to V(json).
         type: bool
         default: null
         env:

ansible/plugins/doc_fragments/return_common.py

@@ -29,7 +29,7 @@ skipped:
   type: bool
   sample: false
 results:
-  description: List of module results,
+  description: List of module results.
   returned: when using a loop.
   type: list
   sample: [{changed: True, msg: 'first item changed'}, {changed: False, msg: 'second item ok'}]

ansible/plugins/doc_fragments/shell_common.py

@@ -34,7 +34,7 @@ options:
   system_tmpdirs:
     description:
        - "List of valid system temporary directories on the managed machine for Ansible to validate
-         O(remote_tmp) against, when specific permissions are needed.  These must be world
+         O(remote_tmp) against, when specific permissions are needed. These must be world
          readable, writable, and executable. This list should only contain directories which the
          system administrator has pre-created with the proper ownership and permissions otherwise
          security issues can arise."
@@ -51,7 +51,7 @@ options:
       - name: ansible_system_tmpdirs
   async_dir:
     description:
-       - Directory in which ansible will keep async job information
+       - Directory in which ansible will keep async job information.
     default: '~/.ansible_async'
     env: [{name: ANSIBLE_ASYNC_DIR}]
     ini:
@@ -59,14 +59,6 @@ options:
         key: async_dir
     vars:
       - name: ansible_async_dir
-  environment:
-    type: list
-    elements: dictionary
-    default: [{}]
-    description:
-      - List of dictionaries of environment variables and their values to use when executing commands.
-    keyword:
-      - name: environment
   admin_users:
     type: list
     elements: string

ansible/plugins/doc_fragments/shell_windows.py

@@ -38,13 +38,4 @@ options:
     type: bool
     default: 'no'
     choices: ['no', False]
-  environment:
-    description:
-    - List of dictionaries of environment variables and their values to use when
-      executing commands.
-    keyword:
-      - name: environment
-    type: list
-    elements: dictionary
-    default: [{}]
 """

ansible/plugins/doc_fragments/url.py

@@ -38,7 +38,7 @@ options:
   url_username:
     description:
       - The username for use in HTTP basic authentication.
-      - This parameter can be used without O(url_password) for sites that allow empty passwords
+      - This parameter can be used without O(url_password) for sites that allow empty passwords.
     type: str
   url_password:
     description:
@@ -66,7 +66,7 @@ options:
         authentication.
       - Requires the Python library L(gssapi,https://github.com/pythongssapi/python-gssapi) to be installed.
       - Credentials for GSSAPI can be specified with O(url_username)/O(url_password) or with the GSSAPI env var
-        C(KRB5CCNAME) that specified a custom Kerberos credential cache.
+        E(KRB5CCNAME) that specified a custom Kerberos credential cache.
       - NTLM authentication is B(not) supported even if the GSSAPI mech for NTLM has been installed.
     type: bool
     default: no

ansible/plugins/doc_fragments/url_windows.py

@@ -47,7 +47,7 @@ options:
     description:
     - Specify how many times the module will redirect a connection to an
       alternative URI before the connection fails.
-    - If set to V(0) or O(follow_redirects) is set to V(none), or V(safe) when
+    - If set to V(0) or O(follow_redirects) is set to V(null), or V(safe) when
       not doing a C(GET) or C(HEAD) it prevents all redirection.
     default: 50
     type: int
@@ -67,8 +67,8 @@ options:
     type: bool
   client_cert:
     description:
-    - The path to the client certificate (.pfx) that is used for X509
-      authentication. This path can either be the path to the C(pfx) on the
+    - The path to the client certificate C(.pfx) that is used for X509
+      authentication. This path can either be the path to the C(.pfx) on the
       filesystem or the PowerShell certificate path
       C(Cert:\CurrentUser\My\<thumbprint>).
     - The WinRM connection must be authenticated with C(CredSSP) or C(become)
@@ -119,8 +119,7 @@ options:
   proxy_url:
     description:
     - An explicit proxy to use for the request.
-    - By default, the request will use the IE defined proxy unless O(use_proxy)
-      is set to V(no).
+    - By default, the request will use the IE defined proxy unless O(use_proxy=no).
     type: str
   proxy_username:
     description:

ansible/plugins/doc_fragments/validate.py

@@ -12,7 +12,7 @@ options:
   validate:
     description:
     - The validation command to run before copying the updated file into the final destination.
-    - A temporary file path is used to validate, passed in through '%s' which must be present as in the examples below.
+    - A temporary file path is used to validate, passed in through C(%s) which must be present as in the examples below.
     - Also, the command is passed securely so shell features such as expansion and pipes will not work.
     - For an example on how to handle more complex validation than what this
       option provides, see R(handling complex validation,complex_configuration_validation).

ansible/plugins/filter/core.py

@@ -76,6 +76,8 @@ def to_json(a, *args, **kw):
 
 def to_nice_json(a, indent=4, sort_keys=True, *args, **kw):
     '''Make verbose, human-readable JSON'''
+    # TODO separators can be potentially exposed to the user as well
+    kw.pop('separators', None)
     return to_json(a, indent=indent, sort_keys=sort_keys, separators=(',', ': '), *args, **kw)
 
 

ansible/plugins/filter/human_to_bytes.yml

@@ -27,6 +27,15 @@ EXAMPLES: |
 
   # this is an error, wants bits, got bytes
   ERROR: '{{ "1.15 GB" | human_to_bytes(isbits=true) }}'
+  
+  # size => 2684354560
+  size: '{{ "2.5 gigabyte" | human_to_bytes }}'
+  
+  # size => 1234803098
+  size: '{{ "1 Gigabyte" | human_to_bytes }}'
+
+  # this is an error, because gigggabyte is not a valid unit
+  size: '{{ "1 gigggabyte" | human_to_bytes }}'
 
 RETURN:
   _value:

ansible/plugins/filter/password_hash.yml

@@ -17,7 +17,7 @@ DOCUMENTATION:
       description: Hashing algorithm to use.
       type: string
       default: sha512
-      choices: [ md5, blowfish, sha256, sha512 ]
+      choices: [ md5, blowfish, sha256, sha512, bcrypt ]
     salt:
       description: Secret string used for the hashing. If none is provided a random one can be generated. Use only numbers and letters (characters matching V([./0-9A-Za-z]+)).
       type: string

ansible/plugins/filter/strftime.yml

@@ -3,7 +3,7 @@ DOCUMENTATION:
   version_added: "2.4"
   short_description: date formating
   description:
-    - Using Python's C(strftime) function, take a data formating string and a date/time to create a formated date.
+    - Using Python's C(strftime) function, take a data formating string and a date/time to create a formatted date.
   notes:
     - This is a passthrough to Python's C(stftime), for a complete set of formatting options go to https://strftime.org/.
   positional: _input, second, utc

ansible/plugins/filter/to_nice_json.yml

@@ -40,12 +40,16 @@ DOCUMENTATION:
       default: False
       type: bool
     sort_keys:
-      description: Affects sorting of dictionary keys.
+      description: Affects sorting of dictionary keys. Passed to an underlying C(json.dumps) call.
       default: True
-      type: bool      
+      type: bool
+    indent:
+      description: Specifies an indentation level. Passed to an underlying C(json.dumps) call.
+      default: 4
+      type: int
   notes:
     - Both O(vault_to_text) and O(preprocess_unsafe) defaulted to V(False) between Ansible 2.9 and 2.12.
-    - 'These parameters to C(json.dumps) will be ignored, they are overridden for internal use: I(cls), I(default), I(indent), I(separators), I(sort_keys).'
+    - 'These parameters to C(json.dumps) will be ignored, they are overridden for internal use: I(cls), I(default), I(separators).'
 
 EXAMPLES: |
   # dump variable in a template to create a nicely formatted JSON document

ansible/plugins/filter/to_uuid.yml

@@ -3,7 +3,7 @@ DOCUMENTATION:
   version_added: "2.9"
   short_description: namespaced UUID generator
   description:
-    - Use to generate namespeced Universal Unique ID.
+    - Use to generate namespaced Universal Unique ID.
   positional: _input, namespace
   options:
     _input: