Use semantic markup for remaining plugins. (#81189)

also change  `ansible_psrp_protocol` for `protocol`  as what matters is the option itself, not what was used to set it
pull/81203/head
Felix Fontein 11 months ago committed by GitHub
parent c3af71a2c8
commit 7cf15d0732
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

@ -12,7 +12,7 @@ DOCUMENTATION = '''
short_description: oneline Ansible screen output
version_added: historical
description:
- This is the output callback used by the -o/--one-line command line option.
- This is the output callback used by the C(-o)/C(--one-line) command line option.
'''
from ansible.plugins.callback import CallbackBase

@ -7,9 +7,9 @@ __metaclass__ = type
DOCUMENTATION = """
author: Ansible Core Team
name: paramiko
short_description: Run tasks via python ssh (paramiko)
short_description: Run tasks via Python SSH (paramiko)
description:
- Use the python ssh implementation (Paramiko) to connect to targets
- Use the Python SSH implementation (Paramiko) to connect to targets
- The paramiko transport is provided because many distributions, in particular EL6 and before do not support ControlPersist
in their SSH implementations.
- This is needed on the Ansible control machine to be reasonably efficient with connections.
@ -86,7 +86,7 @@ DOCUMENTATION = """
description:
- Whether or not to enable RSA SHA2 algorithms for pubkeys and hostkeys
- On paramiko versions older than 2.9, this only affects hostkeys
- For behavior matching paramiko<2.9 set this to C(False)
- For behavior matching paramiko<2.9 set this to V(False)
vars:
- name: ansible_paramiko_use_rsa_sha2_algorithms
ini:

@ -10,7 +10,7 @@ name: psrp
short_description: Run tasks over Microsoft PowerShell Remoting Protocol
description:
- Run commands or put/fetch on a target via PSRP (WinRM plugin)
- This is similar to the I(winrm) connection plugin which uses the same
- This is similar to the P(ansible.builtin.winrm#connection) connection plugin which uses the same
underlying transport but instead runs in a PowerShell interpreter.
version_added: "2.7"
requirements:
@ -38,7 +38,7 @@ options:
keyword:
- name: remote_user
remote_password:
description: Authentication password for the C(remote_user). Can be supplied as CLI option.
description: Authentication password for the O(remote_user). Can be supplied as CLI option.
type: str
vars:
- name: ansible_password
@ -49,8 +49,8 @@ options:
port:
description:
- The port for PSRP to connect on the remote target.
- Default is C(5986) if I(protocol) is not defined or is C(https),
otherwise the port is C(5985).
- Default is V(5986) if O(protocol) is not defined or is V(https),
otherwise the port is V(5985).
type: int
vars:
- name: ansible_port
@ -60,7 +60,7 @@ options:
protocol:
description:
- Set the protocol to use for the connection.
- Default is C(https) if I(port) is not defined or I(port) is not C(5985).
- Default is V(https) if O(port) is not defined or O(port) is not V(5985).
choices:
- http
- https
@ -77,8 +77,8 @@ options:
auth:
description:
- The authentication protocol to use when authenticating the remote user.
- The default, C(negotiate), will attempt to use C(Kerberos) if it is
available and fall back to C(NTLM) if it isn't.
- The default, V(negotiate), will attempt to use Kerberos (V(kerberos)) if it is
available and fall back to NTLM (V(ntlm)) if it isn't.
type: str
vars:
- name: ansible_psrp_auth
@ -93,8 +93,8 @@ options:
cert_validation:
description:
- Whether to validate the remote server's certificate or not.
- Set to C(ignore) to not validate any certificates.
- I(ca_cert) can be set to the path of a PEM certificate chain to
- Set to V(ignore) to not validate any certificates.
- O(ca_cert) can be set to the path of a PEM certificate chain to
use in the validation.
choices:
- validate
@ -107,7 +107,7 @@ options:
description:
- The path to a PEM certificate chain to use when validating the server's
certificate.
- This value is ignored if I(cert_validation) is set to C(ignore).
- This value is ignored if O(cert_validation) is set to V(ignore).
type: path
vars:
- name: ansible_psrp_cert_trust_path
@ -124,7 +124,7 @@ options:
read_timeout:
description:
- The read timeout for receiving data from the remote host.
- This value must always be greater than I(operation_timeout).
- This value must always be greater than O(operation_timeout).
- This option requires pypsrp >= 0.3.
- This is measured in seconds.
type: int
@ -156,15 +156,15 @@ options:
message_encryption:
description:
- Controls the message encryption settings, this is different from TLS
encryption when I(ansible_psrp_protocol) is C(https).
- Only the auth protocols C(negotiate), C(kerberos), C(ntlm), and
C(credssp) can do message encryption. The other authentication protocols
only support encryption when C(protocol) is set to C(https).
- C(auto) means means message encryption is only used when not using
encryption when O(protocol) is V(https).
- Only the auth protocols V(negotiate), V(kerberos), V(ntlm), and
V(credssp) can do message encryption. The other authentication protocols
only support encryption when V(protocol) is set to V(https).
- V(auto) means means message encryption is only used when not using
TLS/HTTPS.
- C(always) is the same as C(auto) but message encryption is always used
- V(always) is the same as V(auto) but message encryption is always used
even when running over TLS/HTTPS.
- C(never) disables any encryption checks that are in place when running
- V(never) disables any encryption checks that are in place when running
over HTTP and disables any authentication encryption processes.
type: str
vars:
@ -184,7 +184,7 @@ options:
description:
- Will disable any environment proxy settings and connect directly to the
remote host.
- This option is ignored if C(proxy) is set.
- This option is ignored if O(proxy) is set.
vars:
- name: ansible_psrp_ignore_proxy
type: bool
@ -206,7 +206,7 @@ options:
credssp_auth_mechanism:
description:
- The sub authentication mechanism to use with CredSSP auth.
- When C(auto), both Kerberos and NTLM is attempted with kerberos being
- When V(auto), both Kerberos and NTLM is attempted with kerberos being
preferred.
type: str
choices:
@ -219,7 +219,7 @@ options:
credssp_disable_tlsv1_2:
description:
- Disables the use of TLSv1.2 on the CredSSP authentication channel.
- This should not be set to C(yes) unless dealing with a host that does not
- This should not be set to V(yes) unless dealing with a host that does not
have TLSv1.2.
default: false
type: bool
@ -228,7 +228,7 @@ options:
credssp_minimum_version:
description:
- The minimum CredSSP server authentication version that will be accepted.
- Set to C(5) to ensure the server has been patched and is not vulnerable
- Set to V(5) to ensure the server has been patched and is not vulnerable
to CVE 2018-0886.
default: 2
type: int
@ -282,7 +282,7 @@ options:
description:
- Sets the WSMan timeout for each operation.
- This is measured in seconds.
- This should not exceed the value for C(connection_timeout).
- This should not exceed the value for O(connection_timeout).
type: int
vars:
- name: ansible_psrp_operation_timeout

@ -20,7 +20,7 @@ DOCUMENTATION = '''
- connection_pipelining
version_added: historical
notes:
- Many options default to C(None) here but that only means we do not override the SSH tool's defaults and/or configuration.
- Many options default to V(None) here but that only means we do not override the SSH tool's defaults and/or configuration.
For example, if you specify the port in this plugin it will override any C(Port) entry in your C(.ssh/config).
- The ssh CLI tool uses return code 255 as a 'connection error', this can conflict with commands/tools that
also return 255 as an error code and will look like an 'unreachable' condition or 'connection error' to this plugin.
@ -55,7 +55,7 @@ DOCUMENTATION = '''
- name: ansible_ssh_host_key_checking
version_added: '2.5'
password:
description: Authentication password for the C(remote_user). Can be supplied as CLI option.
description: Authentication password for the O(remote_user). Can be supplied as CLI option.
type: string
vars:
- name: ansible_password
@ -105,7 +105,7 @@ DOCUMENTATION = '''
ssh_executable:
default: ssh
description:
- This defines the location of the SSH binary. It defaults to C(ssh) which will use the first SSH binary available in $PATH.
- This defines the location of the SSH binary. It defaults to V(ssh) which will use the first SSH binary available in $PATH.
- This option is usually not required, it might be useful when access to system SSH is restricted,
or when using SSH wrappers to connect to remote hosts.
type: string
@ -120,7 +120,7 @@ DOCUMENTATION = '''
sftp_executable:
default: sftp
description:
- This defines the location of the sftp binary. It defaults to C(sftp) which will use the first binary available in $PATH.
- This defines the location of the sftp binary. It defaults to V(sftp) which will use the first binary available in $PATH.
type: string
env: [{name: ANSIBLE_SFTP_EXECUTABLE}]
ini:
@ -132,7 +132,7 @@ DOCUMENTATION = '''
scp_executable:
default: scp
description:
- This defines the location of the scp binary. It defaults to C(scp) which will use the first binary available in $PATH.
- This defines the location of the scp binary. It defaults to V(scp) which will use the first binary available in $PATH.
type: string
env: [{name: ANSIBLE_SCP_EXECUTABLE}]
ini:
@ -319,16 +319,16 @@ DOCUMENTATION = '''
version_added: '2.12'
scp_if_ssh:
deprecated:
why: In favor of the "ssh_transfer_method" option.
why: In favor of the O(ssh_transfer_method) option.
version: "2.17"
alternatives: ssh_transfer_method
alternatives: O(ssh_transfer_method)
default: smart
description:
- "Preferred method to use when transferring files over SSH."
- When set to I(smart), Ansible will try them until one succeeds or they all fail.
- If set to I(True), it will force 'scp', if I(False) it will use 'sftp'.
- For OpenSSH >=9.0 you must add an additional option to enable scp (scp_extra_args="-O")
- This setting will overridden by ssh_transfer_method if set.
- When set to V(smart), Ansible will try them until one succeeds or they all fail.
- If set to V(True), it will force 'scp', if V(False) it will use 'sftp'.
- For OpenSSH >=9.0 you must add an additional option to enable scp (C(scp_extra_args="-O"))
- This setting will overridden by O(ssh_transfer_method) if set.
env: [{name: ANSIBLE_SCP_IF_SSH}]
ini:
- {key: scp_if_ssh, section: ssh_connection}

@ -39,7 +39,7 @@ DOCUMENTATION = """
- name: remote_user
type: str
remote_password:
description: Authentication password for the C(remote_user). Can be supplied as CLI option.
description: Authentication password for the O(remote_user). Can be supplied as CLI option.
vars:
- name: ansible_password
- name: ansible_winrm_pass
@ -61,8 +61,8 @@ DOCUMENTATION = """
scheme:
description:
- URI scheme to use
- If not set, then will default to C(https) or C(http) if I(port) is
C(5985).
- If not set, then will default to V(https) or V(http) if O(port) is
V(5985).
choices: [http, https]
vars:
- name: ansible_winrm_scheme
@ -119,7 +119,7 @@ DOCUMENTATION = """
- The managed option means Ansible will obtain kerberos ticket.
- While the manual one means a ticket must already have been obtained by the user.
- If having issues with Ansible freezing when trying to obtain the
Kerberos ticket, you can either set this to C(manual) and obtain
Kerberos ticket, you can either set this to V(manual) and obtain
it outside Ansible or install C(pexpect) through pip and try
again.
choices: [managed, manual]

@ -3,7 +3,7 @@ DOCUMENTATION:
version_added: "historical"
short_description: cast into a boolean
description:
- Attempt to cast the input into a boolean (C(True) or C(False)) value.
- Attempt to cast the input into a boolean (V(True) or V(False)) value.
positional: _input
options:
_input:
@ -24,5 +24,5 @@ EXAMPLES: |
RETURN:
_value:
description: The boolean resulting of casting the input expression into a C(True) or C(False) value.
description: The boolean resulting of casting the input expression into a V(True) or V(False) value.
type: bool

@ -16,7 +16,7 @@ DOCUMENTATION:
elements: dictionary
required: true
recursive:
description: If C(True), merge elements recursively.
description: If V(True), merge elements recursively.
type: bool
default: false
list_merge:

@ -14,7 +14,7 @@ DOCUMENTATION:
description: Number of recursive list depths to flatten.
type: int
skip_nulls:
description: Skip C(null)/C(None) elements when inserting into the top list.
description: Skip V(null)/V(None) elements when inserting into the top list.
type: bool
default: true

@ -24,5 +24,5 @@ EXAMPLES: |
RETURN:
_value:
description: The checksum of the input, as configured in I(hashtype).
description: The checksum of the input, as configured in O(hashtype).
type: string

@ -7,7 +7,7 @@ DOCUMENTATION:
positional: _input, isbits, unit
options:
_input:
description: Number of bytes, or bits. Depends on I(isbits).
description: Number of bytes, or bits. Depends on O(isbits).
type: int
required: true
isbits:

@ -15,7 +15,7 @@ DOCUMENTATION:
type: str
choices: ['Y', 'Z', 'E', 'P', 'T', 'G', 'M', 'K', 'B']
isbits:
description: If C(True), force to interpret only bit input; if C(False), force bytes. Otherwise use the notation to guess.
description: If V(True), force to interpret only bit input; if V(False), force bytes. Otherwise use the notation to guess.
type: bool
EXAMPLES: |

@ -14,11 +14,11 @@ DOCUMENTATION:
description: Regular expression string that defines the match.
type: str
multiline:
description: Search across line endings if C(True), do not if otherwise.
description: Search across line endings if V(True), do not if otherwise.
type: bool
default: no
ignorecase:
description: Force the search to be case insensitive if C(True), case sensitive otherwise.
description: Force the search to be case insensitive if V(True), case sensitive otherwise.
type: bool
default: no

@ -21,11 +21,11 @@ DOCUMENTATION:
type: int
required: true
multiline:
description: Search across line endings if C(True), do not if otherwise.
description: Search across line endings if V(True), do not if otherwise.
type: bool
default: no
ignorecase:
description: Force the search to be case insensitive if C(True), case sensitive otherwise.
description: Force the search to be case insensitive if V(True), case sensitive otherwise.
type: bool
default: no

@ -16,11 +16,11 @@ DOCUMENTATION:
description: Regular expression string that defines the match.
type: str
multiline:
description: Search across line endings if C(True), do not if otherwise.
description: Search across line endings if V(True), do not if otherwise.
type: bool
default: no
ignorecase:
description: Force the search to be case insensitive if C(True), case sensitive otherwise.
description: Force the search to be case insensitive if V(True), case sensitive otherwise.
type: bool
default: no

@ -5,8 +5,8 @@ DOCUMENTATION:
short_description: Make a path relative
positional: _input, start
description:
- Converts the given path to a relative path from the I(start),
or relative to the directory given in I(start).
- Converts the given path to a relative path from the O(start),
or relative to the directory given in O(start).
options:
_input:
description: A path.

@ -4,7 +4,7 @@ DOCUMENTATION:
short_description: returns a product of a list and its elements
positional: _input, _subelement, skip_missing
description:
- This produces a product of an object and the subelement values of that object, similar to the subelements lookup. This lets you specify individual subelements to use in a template I(_input).
- This produces a product of an object and the subelement values of that object, similar to the subelements lookup. This lets you specify individual subelements to use in a template O(_input).
options:
_input:
description: Original list.
@ -16,7 +16,7 @@ DOCUMENTATION:
type: str
required: yes
skip_missing:
description: If C(True), ignore missing subelements, otherwise missing subelements generate an error.
description: If V(True), ignore missing subelements, otherwise missing subelements generate an error.
type: bool
default: no

@ -4,22 +4,22 @@ DOCUMENTATION:
version_added: '1.9'
short_description: Ternary operation filter
description:
- Return the first value if the input is C(True), the second if C(False).
- Return the first value if the input is V(True), the second if V(False).
positional: true_val, false_val
options:
_input:
description: A boolean expression, must evaluate to C(True) or C(False).
description: A boolean expression, must evaluate to V(True) or V(False).
type: bool
required: true
true_val:
description: Value to return if the input is C(True).
description: Value to return if the input is V(True).
type: any
required: true
false_val:
description: Value to return if the input is C(False).
description: Value to return if the input is V(False).
type: any
none_val:
description: Value to return if the input is C(None). If not set, C(None) will be treated as C(False).
description: Value to return if the input is V(None). If not set, V(None) will be treated as V(False).
type: any
version_added: '2.8'
notes:

@ -23,8 +23,8 @@ DOCUMENTATION:
default: True
version_added: '2.9'
allow_nan:
description: When C(False), strict adherence to float value limits of the JSON specifications, so C(nan), C(inf) and C(-inf) values will produce errors.
When C(True), JavaScript equivalents will be used (C(NaN), C(Infinity), C(-Infinity)).
description: When V(False), strict adherence to float value limits of the JSON specifications, so C(nan), C(inf) and C(-inf) values will produce errors.
When V(True), JavaScript equivalents will be used (C(NaN), C(Infinity), C(-Infinity)).
default: True
type: bool
check_circular:
@ -41,11 +41,11 @@ DOCUMENTATION:
type: integer
separators:
description: The C(item) and C(key) separator to be used in the serialized output,
default may change depending on I(indent) and Python version.
default may change depending on O(indent) and Python version.
default: "(', ', ': ')"
type: tuple
skipkeys:
description: If C(True), keys that are not basic Python types will be skipped.
description: If V(True), keys that are not basic Python types will be skipped.
default: False
type: bool
sort_keys:
@ -53,7 +53,7 @@ DOCUMENTATION:
default: False
type: bool
notes:
- Both I(vault_to_text) and I(preprocess_unsafe) defaulted to C(False) between Ansible 2.9 and 2.12.
- 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, as they are overridden internally: I(cls), I(default)'
EXAMPLES: |

@ -23,8 +23,8 @@ DOCUMENTATION:
default: True
version_added: '2.9'
allow_nan:
description: When C(False), strict adherence to float value limits of the JSON specification, so C(nan), C(inf) and C(-inf) values will produce errors.
When C(True), JavaScript equivalents will be used (C(NaN), C(Infinity), C(-Infinity)).
description: When V(False), strict adherence to float value limits of the JSON specification, so C(nan), C(inf) and C(-inf) values will produce errors.
When V(True), JavaScript equivalents will be used (C(NaN), C(Infinity), C(-Infinity)).
default: True
type: bool
check_circular:
@ -36,11 +36,11 @@ DOCUMENTATION:
default: True
type: bool
skipkeys:
description: If C(True), keys that are not basic Python types will be skipped.
description: If V(True), keys that are not basic Python types will be skipped.
default: False
type: bool
notes:
- Both I(vault_to_text) and I(preprocess_unsafe) defaulted to C(False) between Ansible 2.9 and 2.12.
- 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).'
EXAMPLES: |

@ -16,5 +16,5 @@ EXAMPLES: |
RETURN:
_value:
description: The Python 'type' of the I(_input) provided.
description: The Python 'type' of the O(_input) provided.
type: string

@ -19,7 +19,7 @@ RETURN:
_value:
description:
- A dictionary with components as keyword and their value.
- If I(query) is provided, a string or integer will be returned instead, depending on I(query).
- If O(query) is provided, a string or integer will be returned instead, depending on O(query).
type: any
EXAMPLES: |

@ -53,7 +53,7 @@ RETURN = r'''
_value:
description:
- A dictionary with components as keyword and their value.
- If I(query) is provided, a string or integer will be returned instead, depending on I(query).
- If O(query) is provided, a string or integer will be returned instead, depending on O(query).
type: any
'''

@ -26,7 +26,7 @@ DOCUMENTATION:
default: 'filter_default'
wrap_object:
description:
- This toggle can force the return of an C(AnsibleVaultEncryptedUnicode) string object, when C(False), you get a simple string.
- This toggle can force the return of an C(AnsibleVaultEncryptedUnicode) 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

@ -18,7 +18,7 @@ DOCUMENTATION:
elements: any
required: yes
strict:
description: If C(True) return an error on mismatching list length, otherwise shortest list determines output.
description: If V(True) return an error on mismatching list length, otherwise shortest list determines output.
type: bool
default: no

@ -5,7 +5,7 @@ DOCUMENTATION:
positional: _input, _additional_lists
description:
- Make an iterator that aggregates elements from each of the iterables.
If the iterables are of uneven length, missing values are filled-in with I(fillvalue).
If the iterables are of uneven length, missing values are filled-in with O(fillvalue).
Iteration continues until the longest iterable is exhausted.
notes:
- This is mostly a passhtrough to Python's C(itertools.zip_longest) function

@ -13,7 +13,7 @@ DOCUMENTATION = '''
- The Jinja2 conditionals that qualify a host for membership.
- The Jinja2 expressions are calculated and assigned to the variables
- Only variables already available from previous inventories or the fact cache can be used for templating.
- When I(strict) is False, failed expressions will be ignored (assumes vars were missing).
- When O(strict) is False, failed expressions will be ignored (assumes vars were missing).
options:
plugin:
description: token that ensures this is a source file for the 'constructed' plugin.

@ -12,7 +12,7 @@ DOCUMENTATION = r"""
description:
- The csvfile lookup reads the contents of a file in CSV (comma-separated value) format.
The lookup looks for the row where the first column matches keyname (which can be multiple words)
and returns the value in the C(col) column (default 1, which indexed from 0 means the second column in the file).
and returns the value in the O(col) column (default 1, which indexed from 0 means the second column in the file).
options:
col:
description: column to return (0 indexed).
@ -20,7 +20,7 @@ DOCUMENTATION = r"""
default:
description: what to return if the value is not found in the file.
delimiter:
description: field separator in the file, for a tab you can specify C(TAB) or C(\t).
description: field separator in the file, for a tab you can specify V(TAB) or V(\\t).
default: TAB
file:
description: name of the CSV/TSV file to open.

@ -23,7 +23,7 @@ DOCUMENTATION = """
default: ''
version_added: '2.13'
notes:
- You can pass the C(Undefined) object as C(default) to force an undefined error
- You can pass the C(Undefined) object as O(default) to force an undefined error
"""
EXAMPLES = """

@ -21,7 +21,7 @@ DOCUMENTATION = """
- See R(Ansible task paths,playbook_task_paths) to understand how file lookup occurs with paths.
- Matching is against local system files on the Ansible controller.
To iterate a list of files on a remote node, use the M(ansible.builtin.find) module.
- Returns a string list of paths joined by commas, or an empty list if no files match. For a 'true list' pass C(wantlist=True) to the lookup.
- Returns a string list of paths joined by commas, or an empty list if no files match. For a 'true list' pass O(ignore:wantlist=True) to the lookup.
seealso:
- ref: playbook_task_paths
description: Search paths used for relative files.

@ -15,9 +15,9 @@ DOCUMENTATION = """
to the containing locations of role / play / include and so on.
- The list of files has precedence over the paths searched.
For example, A task in a role has a 'file1' in the play's relative path, this will be used, 'file2' in role's relative path will not.
- Either a list of files C(_terms) or a key C(files) with a list of files is required for this plugin to operate.
- Either a list of files O(_terms) or a key O(files) with a list of files is required for this plugin to operate.
notes:
- This lookup can be used in 'dual mode', either passing a list of file names or a dictionary that has C(files) and C(paths).
- This lookup can be used in 'dual mode', either passing a list of file names or a dictionary that has O(files) and O(paths).
options:
_terms:
description: A list of file names.
@ -35,16 +35,16 @@ DOCUMENTATION = """
type: boolean
default: False
description:
- When C(True), return an empty list when no files are matched.
- When V(True), return an empty list when no files are matched.
- This is useful when used with C(with_first_found), as an empty list return to C(with_) calls
causes the calling task to be skipped.
- When used as a template via C(lookup) or C(query), setting I(skip=True) will *not* cause the task to skip.
- When used as a template via C(lookup) or C(query), setting O(skip=True) will *not* cause the task to skip.
Tasks must handle the empty list return from the template.
- When C(False) and C(lookup) or C(query) specifies I(errors='ignore') all errors (including no file found,
- When V(False) and C(lookup) or C(query) specifies O(ignore:errors='ignore') all errors (including no file found,
but potentially others) return an empty string or an empty list respectively.
- When C(True) and C(lookup) or C(query) specifies I(errors='ignore'), no file found will return an empty
- When V(True) and C(lookup) or C(query) specifies O(ignore:errors='ignore'), no file found will return an empty
list and other potential errors return an empty string or empty list depending on the template call
(in other words return values of C(lookup) v C(query)).
(in other words return values of C(lookup) vs C(query)).
seealso:
- ref: playbook_task_paths
description: Search paths used for relative paths/files.

@ -39,7 +39,7 @@ DOCUMENTATION = """
default: ''
case_sensitive:
description:
Whether key names read from C(file) should be case sensitive. This prevents
Whether key names read from O(file) should be case sensitive. This prevents
duplicate key errors if keys only differ in case.
default: False
version_added: '2.12'

@ -28,17 +28,18 @@ DOCUMENTATION = """
required: True
encrypt:
description:
- Which hash scheme to encrypt the returning password, should be one hash scheme from C(passlib.hash; md5_crypt, bcrypt, sha256_crypt, sha512_crypt).
- Which hash scheme to encrypt the returning password, should be one hash scheme from C(passlib.hash);
V(md5_crypt), V(bcrypt), V(sha256_crypt), V(sha512_crypt).
- If not provided, the password will be returned in plain text.
- Note that the password is always stored as plain text, only the returning password is encrypted.
- Encrypt also forces saving the salt value for idempotence.
- Note that before 2.6 this option was incorrectly labeled as a boolean for a long time.
ident:
description:
- Specify version of Bcrypt algorithm to be used while using C(encrypt) as C(bcrypt).
- The parameter is only available for C(bcrypt) - U(https://passlib.readthedocs.io/en/stable/lib/passlib.hash.bcrypt.html#passlib.hash.bcrypt).
- Specify version of Bcrypt algorithm to be used while using O(encrypt) as V(bcrypt).
- The parameter is only available for V(bcrypt) - U(https://passlib.readthedocs.io/en/stable/lib/passlib.hash.bcrypt.html#passlib.hash.bcrypt).
- Other hash types will simply ignore this parameter.
- 'Valid values for this parameter are: C(2), C(2a), C(2y), C(2b).'
- 'Valid values for this parameter are: V(2), V(2a), V(2y), V(2b).'
type: string
version_added: "2.12"
chars:
@ -46,8 +47,7 @@ DOCUMENTATION = """
description:
- A list of names that compose a custom character set in the generated passwords.
- This parameter defines the possible character sets in the resulting password, not the required character sets.
If you want to require certain character sets for passwords, you can use the C(community.general.random_string lookup) plugin -
P(community.general.random_string#lookup).
If you want to require certain character sets for passwords, you can use the P(community.general.random_string#lookup) lookup plugin.
- 'By default generated passwords contain a random mix of upper and lowercase ASCII letters, the numbers 0-9, and punctuation (". , : - _").'
- "They can be either parts of Python's string module attributes or represented literally ( :, -)."
- "Though string modules can vary by Python version, valid values for both major releases include:

@ -19,8 +19,8 @@ DOCUMENTATION = """
default: False
description:
- Lookup accepts this flag from a dictionary as optional. See Example section for more information.
- If set to C(True), the lookup plugin will skip the lists items that do not contain the given subkey.
- If set to C(False), the plugin will yield an error and complain about the missing subkey.
- If set to V(True), the lookup plugin will skip the lists items that do not contain the given subkey.
- If set to V(False), the plugin will yield an error and complain about the missing subkey.
"""
EXAMPLES = """

@ -64,7 +64,7 @@ options:
- section: url_lookup
key: timeout
http_agent:
description: User-Agent to use in the request. The default was changed in 2.11 to C(ansible-httpget).
description: User-Agent to use in the request. The default was changed in 2.11 to V(ansible-httpget).
type: string
version_added: "2.10"
default: ansible-httpget
@ -102,7 +102,7 @@ options:
use_gssapi:
description:
- Use GSSAPI handler of requests
- As of Ansible 2.11, GSSAPI credentials can be specified with I(username) and I(password).
- As of Ansible 2.11, GSSAPI credentials can be specified with O(username) and O(password).
type: boolean
version_added: "2.10"
default: False

@ -19,5 +19,5 @@ EXAMPLES: |
RETURN:
_value:
description: Returns C(True) if the path is absolute, C(False) if it is relative.
description: Returns V(True) if the path is absolute, V(False) if it is relative.
type: boolean

@ -19,5 +19,5 @@ EXAMPLES: |
RETURN:
_value:
description: Returns C(True) if all elements of the list were True, C(False) otherwise.
description: Returns V(True) if all elements of the list were True, V(False) otherwise.
type: boolean

@ -19,5 +19,5 @@ EXAMPLES: |
RETURN:
_value:
description: Returns C(True) if any element of the list was true, C(False) otherwise.
description: Returns V(True) if any element of the list was true, V(False) otherwise.
type: boolean

@ -6,7 +6,7 @@ DOCUMENTATION:
aliases: [change]
description:
- Tests if task required changes to complete
- This test checks for the existance of a C(changed) key in the input dictionary and that it is C(True) if present
- This test checks for the existance of a C(changed) key in the input dictionary and that it is V(True) if present
options:
_input:
description: registered result from an Ansible task
@ -18,5 +18,5 @@ EXAMPLES: |
RETURN:
_value:
description: Returns C(True) if the task was required changes, C(False) otherwise.
description: Returns V(True) if the task was required changes, V(False) otherwise.
type: boolean

@ -45,5 +45,5 @@ EXAMPLES: |
- em4
RETURN:
_value:
description: Returns C(True) if the specified element is contained in the supplied sequence, C(False) otherwise.
description: Returns V(True) if the specified element is contained in the supplied sequence, V(False) otherwise.
type: boolean

@ -17,5 +17,5 @@ EXAMPLES: |
RETURN:
_value:
description: Returns C(True) if the path corresponds to an existing directory on the filesystem on the controller, c(False) if otherwise.
description: Returns V(True) if the path corresponds to an existing directory on the filesystem on the controller, V(False) if otherwise.
type: boolean

@ -5,7 +5,8 @@ DOCUMENTATION:
short_description: does the path exist, follow symlinks
description:
- Check if the provided path maps to an existing filesystem object on the controller (localhost).
- Follows symlinks and checks the target of the symlink instead of the link itself, use the C(link) or C(link_exists) tests to check on the link.
- Follows symlinks and checks the target of the symlink instead of the link itself, use the P(ansible.builtin.link#test)
or P(ansible.builtin.link_exists#test) tests to check on the link.
options:
_input:
description: a path
@ -18,5 +19,5 @@ EXAMPLES: |
RETURN:
_value:
description: Returns C(True) if the path corresponds to an existing filesystem object on the controller (after following symlinks), C(False) if otherwise.
description: Returns V(True) if the path corresponds to an existing filesystem object on the controller (after following symlinks), V(False) if otherwise.
type: boolean

@ -6,7 +6,7 @@ DOCUMENTATION:
aliases: [failure]
description:
- Tests if task finished in failure, opposite of C(succeeded).
- This test checks for the existance of a C(failed) key in the input dictionary and that it is C(True) if present.
- This test checks for the existance of a C(failed) key in the input dictionary and that it is V(True) if present.
- Tasks that get skipped or not executed due to other failures (syntax, templating, unreachable host, etc) do not return a 'failed' status.
options:
_input:
@ -19,5 +19,5 @@ EXAMPLES: |
RETURN:
_value:
description: Returns C(True) if the task was failed, C(False) otherwise.
description: Returns V(True) if the task was failed, V(False) otherwise.
type: boolean

@ -12,7 +12,7 @@ DOCUMENTATION:
type: string
required: True
convert_bool:
description: Attempts to convert the result to a strict Python boolean vs normally acceptable values (C(yes)/C(no), C(on)/C(off), C(0)/C(1), etc).
description: Attempts to convert the result to a strict Python boolean vs normally acceptable values (V(yes)/V(no), V(on)/V(off), V(0)/V(1), etc).
type: bool
default: false
EXAMPLES: |
@ -20,5 +20,5 @@ EXAMPLES: |
thisistrue: '{{ "" is falsy }}'
RETURN:
_value:
description: Returns C(False) if the condition is not "Python truthy", C(True) otherwise.
description: Returns V(False) if the condition is not "Python truthy", V(True) otherwise.
type: boolean

@ -18,5 +18,5 @@ EXAMPLES: |
RETURN:
_value:
description: Returns C(True) if the path corresponds to an existing file on the filesystem on the controller, C(False) if otherwise.
description: Returns V(True) if the path corresponds to an existing file on the filesystem on the controller, V(False) if otherwise.
type: boolean

@ -5,7 +5,7 @@ DOCUMENTATION:
short_description: Did async task finish
description:
- Used to test if an async task has finished, it will aslo work with normal tasks but will issue a warning.
- This test checks for the existance of a C(finished) key in the input dictionary and that it is C(1) if present
- This test checks for the existance of a C(finished) key in the input dictionary and that it is V(1) if present
options:
_input:
description: registered result from an Ansible task
@ -17,5 +17,5 @@ EXAMPLES: |
RETURN:
_value:
description: Returns C(True) if the aysnc task has finished, C(False) otherwise.
description: Returns V(True) if the aysnc task has finished, V(False) otherwise.
type: boolean

@ -17,5 +17,5 @@ EXAMPLES: |
RETURN:
_value:
description: Returns C(True) if the path corresponds to an existing symlink on the filesystem on the controller, C(False) if otherwise.
description: Returns V(True) if the path corresponds to an existing symlink on the filesystem on the controller, V(False) if otherwise.
type: boolean

@ -17,5 +17,5 @@ EXAMPLES: |
RETURN:
_value:
description: Returns C(True) if the path corresponds to an existing filesystem object on the controller, C(False) if otherwise.
description: Returns V(True) if the path corresponds to an existing filesystem object on the controller, V(False) if otherwise.
type: boolean

@ -28,5 +28,5 @@ EXAMPLES: |
nomatch: url is match("/users/.*/resources")
RETURN:
_value:
description: Returns C(True) if there is a match, C(False) otherwise.
description: Returns V(True) if there is a match, V(False) otherwise.
type: boolean

@ -18,5 +18,5 @@ EXAMPLES: |
RETURN:
_value:
description: Returns C(True) if the path corresponds to a mount point on the controller, C(False) if otherwise.
description: Returns V(True) if the path corresponds to a mount point on the controller, V(False) if otherwise.
type: boolean

@ -16,5 +16,5 @@ EXAMPLES: |
RETURN:
_value:
description: Returns C(True) if the input is NaN, C(False) if otherwise.
description: Returns V(True) if the input is NaN, V(False) if otherwise.
type: boolean

@ -5,7 +5,7 @@ DOCUMENTATION:
short_description: Task did not end due to unreachable host
description:
- Tests if task was able to reach the host for execution
- This test checks for the existance of a C(unreachable) key in the input dictionary and that it is C(False) if present
- This test checks for the existance of a C(unreachable) key in the input dictionary and that it is V(False) if present
options:
_input:
description: registered result from an Ansible task
@ -17,5 +17,5 @@ EXAMPLES: |
RETURN:
_value:
description: Returns C(True) if the task did not flag the host as unreachable, C(False) otherwise.
description: Returns V(True) if the task did not flag the host as unreachable, V(False) otherwise.
type: boolean

@ -33,5 +33,5 @@ EXAMPLES: |
RETURN:
_value:
description: Returns C(True) if there is a match, C(False) otherwise.
description: Returns V(True) if there is a match, V(False) otherwise.
type: boolean

@ -20,5 +20,5 @@ EXAMPLES: |
RETURN:
_value:
description: Returns C(True) if the paths correspond to the same location on the filesystem on the controller, C(False) if otherwise.
description: Returns V(True) if the paths correspond to the same location on the filesystem on the controller, V(False) if otherwise.
type: boolean

@ -29,5 +29,5 @@ EXAMPLES: |
RETURN:
_value:
description: Returns C(True) if there is a match, C(False) otherwise.
description: Returns V(True) if there is a match, V(False) otherwise.
type: boolean

@ -6,7 +6,7 @@ DOCUMENTATION:
aliases: [skip]
description:
- Tests if task was skipped
- This test checks for the existance of a C(skipped) key in the input dictionary and that it is C(True) if present
- This test checks for the existance of a C(skipped) key in the input dictionary and that it is V(True) if present
options:
_input:
description: registered result from an Ansible task
@ -18,5 +18,5 @@ EXAMPLES: |
RETURN:
_value:
description: Returns C(True) if the task was skipped, C(False) otherwise.
description: Returns V(True) if the task was skipped, V(False) otherwise.
type: boolean

@ -5,7 +5,7 @@ DOCUMENTATION:
short_description: Was async task started
description:
- Used to check if an async task has started, will also work with non async tasks but will issue a warning.
- This test checks for the existance of a C(started) key in the input dictionary and that it is C(1) if present
- This test checks for the existance of a C(started) key in the input dictionary and that it is V(1) if present
options:
_input:
description: registered result from an Ansible task
@ -17,5 +17,5 @@ EXAMPLES: |
RETURN:
_value:
description: Returns C(True) if the task has started, C(False) otherwise.
description: Returns V(True) if the task has started, V(False) otherwise.
type: boolean

@ -6,7 +6,6 @@ DOCUMENTATION:
short_description: is the list a subset of this other list
description:
- Validate if the first list is a sub set (is included) of the second list.
- Same as the C(all) Python function.
options:
_input:
description: List.
@ -24,5 +23,5 @@ EXAMPLES: |
issmallinbig: '{{ small is subset(big) }}'
RETURN:
_value:
description: Returns C(True) if the specified list is a subset of the provided list, C(False) otherwise.
description: Returns V(True) if the specified list is a subset of the provided list, V(False) otherwise.
type: boolean

@ -6,7 +6,7 @@ DOCUMENTATION:
aliases: [succeeded, successful]
description:
- Tests if task finished successfully, opposite of C(failed).
- This test checks for the existance of a C(failed) key in the input dictionary and that it is C(False) if present
- This test checks for the existance of a C(failed) key in the input dictionary and that it is V(False) if present
options:
_input:
description: registered result from an Ansible task
@ -18,5 +18,5 @@ EXAMPLES: |
RETURN:
_value:
description: Returns C(True) if the task was successfully completed, C(False) otherwise.
description: Returns V(True) if the task was successfully completed, V(False) otherwise.
type: boolean

@ -6,7 +6,6 @@ DOCUMENTATION:
aliases: [issuperset]
description:
- Validate if the first list is a super set (includes) the second list.
- Same as the C(all) Python function.
options:
_input:
description: List.
@ -24,5 +23,5 @@ EXAMPLES: |
issmallinbig: '{{ big is superset(small) }}'
RETURN:
_value:
description: Returns C(True) if the specified list is a superset of the provided list, C(False) otherwise.
description: Returns V(True) if the specified list is a superset of the provided list, V(False) otherwise.
type: boolean

@ -5,14 +5,14 @@ DOCUMENTATION:
short_description: Pythonic true
description:
- This check is a more Python version of what is 'true'.
- It is the opposite of C(falsy).
- It is the opposite of P(ansible.builtin.falsy#test).
options:
_input:
description: An expression that can be expressed in a boolean context.
type: string
required: True
convert_bool:
description: Attempts to convert to strict python boolean vs normally acceptable values (C(yes)/C(no), C(on)/C(off), C(0)/C(1), etc).
description: Attempts to convert to strict python boolean vs normally acceptable values (V(yes)/V(no), V(on)/V(off), V(0)/V(1), etc).
type: bool
default: false
EXAMPLES: |
@ -20,5 +20,5 @@ EXAMPLES: |
thisisfalse: '{{ "" is truthy }}'
RETURN:
_value:
description: Returns C(True) if the condition is not "Python truthy", C(False) otherwise.
description: Returns V(True) if the condition is not "Python truthy", V(False) otherwise.
type: boolean

@ -5,7 +5,7 @@ DOCUMENTATION:
short_description: Did task end due to the host was unreachable
description:
- Tests if task was not able to reach the host for execution
- This test checks for the existance of a C(unreachable) key in the input dictionary and that it's value is C(True)
- This test checks for the existance of a C(unreachable) key in the input dictionary and that it's value is V(True)
options:
_input:
description: registered result from an Ansible task
@ -17,5 +17,5 @@ EXAMPLES: |
RETURN:
_value:
description: Returns C(True) if the task flagged the host as unreachable, C(False) otherwise.
description: Returns V(True) if the task flagged the host as unreachable, V(False) otherwise.
type: boolean

@ -26,5 +26,5 @@ EXAMPLES: |
{{ 'http://nobody:secret@example.com' is uri(['ftp', 'ftps', 'http', 'https', 'ws', 'wss']) }}
RETURN:
_value:
description: Returns C(false) if the string is not a URI or the schema extracted does not match the supplied list.
description: Returns V(false) if the string is not a URI or the schema extracted does not match the supplied list.
type: boolean

@ -25,5 +25,5 @@ EXAMPLES: |
{{ 'ftp://admin:secret@example.com/path/to/myfile.yml' is url }}
RETURN:
_value:
description: Returns C(false) if the string is not a URL, C(true) otherwise.
description: Returns V(false) if the string is not a URL, V(true) otherwise.
type: boolean

@ -17,5 +17,5 @@ EXAMPLES: |
{{ 'mailto://nowone@example.com' is not urn }}
RETURN:
_value:
description: Returns C(true) if the string is a URN and C(false) if it is not.
description: Returns V(true) if the string is a URN and V(false) if it is not.
type: boolean

@ -15,5 +15,5 @@ EXAMPLES: |
thisistrue: '{{ "$ANSIBLE_VAULT;1.2;AES256;dev...." is ansible_vault }}'
RETURN:
_value:
description: Returns C(True) if the input is a valid ansible vault, C(False) otherwise.
description: Returns V(True) if the input is a valid ansible vault, V(False) otherwise.
type: boolean

@ -36,12 +36,12 @@ DOCUMENTATION:
- ne
default: eq
strict:
description: Whether to use strict version scheme. Mutually exclusive with C(version_type)
description: Whether to use strict version scheme. Mutually exclusive with O(version_type)
type: boolean
required: False
default: False
version_type:
description: Version scheme to use for comparison. Mutually exclusive with C(strict). See C(notes) for descriptions on the version types.
description: Version scheme to use for comparison. Mutually exclusive with O(strict). See C(notes) for descriptions on the version types.
type: string
required: False
choices:
@ -52,10 +52,10 @@ DOCUMENTATION:
- pep440
default: loose
notes:
- C(loose) - This type corresponds to the Python C(distutils.version.LooseVersion) class. All version formats are valid for this type. The rules for comparison are simple and predictable, but may not always give expected results.
- C(strict) - This type corresponds to the Python C(distutils.version.StrictVersion) class. A version number consists of two or three dot-separated numeric components, with an optional "pre-release" tag on the end. The pre-release tag consists of a single letter C(a) or C(b) followed by a number. If the numeric components of two version numbers are equal, then one with a pre-release tag will always be deemed earlier (lesser) than one without.
- C(semver)/C(semantic) - This type implements the L(Semantic Version,https://semver.org) scheme for version comparison.
- C(pep440) - This type implements the Python L(PEP-440,https://peps.python.org/pep-0440/) versioning rules for version comparison. Added in version 2.14.
- V(loose) - This type corresponds to the Python C(distutils.version.LooseVersion) class. All version formats are valid for this type. The rules for comparison are simple and predictable, but may not always give expected results.
- V(strict) - This type corresponds to the Python C(distutils.version.StrictVersion) class. A version number consists of two or three dot-separated numeric components, with an optional "pre-release" tag on the end. The pre-release tag consists of a single letter C(a) or C(b) followed by a number. If the numeric components of two version numbers are equal, then one with a pre-release tag will always be deemed earlier (lesser) than one without.
- V(semver)/V(semantic) - This type implements the L(Semantic Version,https://semver.org) scheme for version comparison.
- V(pep440) - This type implements the Python L(PEP-440,https://peps.python.org/pep-0440/) versioning rules for version comparison. Added in version 2.14.
EXAMPLES: |
- name: version test examples
assert:
@ -78,5 +78,5 @@ EXAMPLES: |
- "'2.14.0rc1' is version('2.14.0', 'lt', version_type='pep440')"
RETURN:
_value:
description: Returns C(True) or C(False) depending on the outcome of the comparison.
description: Returns V(True) or V(False) depending on the outcome of the comparison.
type: boolean

Loading…
Cancel
Save