hvac.utils

Misc utility functions and constants

Functions:

`aliased_parameter`(name, *aliases, ...[, ...])	A decorator that can be used to define one or more aliases for a parameter, and optionally display a deprecation warning when aliases are used.
`comma_delimited_to_list`(list_param)	Convert comma-delimited list / string into a list of strings
`deprecated_method`(to_be_removed_in_version)	This is a decorator which can be used to mark methods as deprecated.
`format_url`(format_str, args, *kwargs)	Creates a URL using the specified format after escaping the provided arguments.
`generate_method_deprecation_message`(...[, ...])	Generate a message to be used when warning about the use of deprecated methods.
`generate_parameter_deprecation_message`(...)	Generate a message to be used when warning about the use of deprecated paramers.
`generate_property_deprecation_message`(...[, ...])	Generate a message to be used when warning about the use of deprecated properties.
`get_token_from_env`()	Get the token from env var, VAULT_TOKEN.
`getattr_with_deprecated_properties`(obj, ...)	Helper method to use in the getattr method of a class with deprecated properties.
`list_to_comma_delimited`(list_param)	Convert a list of strings into a comma-delimited list / string.
`raise_for_error`(method, url, status_code[, ...])	Helper method to raise exceptions based on the status code of a response received back from Vault.
`remove_nones`(params)	Removes None values from optional arguments in a parameter dictionary.
`validate_list_of_strings_param`(param_name, ...)	Validate that an argument is a list of strings.
`validate_pem_format`(param_name, param_argument)	Validate that an argument is a PEM-formatted public key or certificate

hvac.utils.aliased_parameter(name, *aliases, removed_in_version, position=None, raise_on_multiple=True)[source]

A decorator that can be used to define one or more aliases for a parameter, and optionally display a deprecation warning when aliases are used. It can also optionally raise an exception if a value is supplied via multiple names. LIMITATIONS: If the canonical parameter can be specified unnamed (positionally), then its position must be set to correctly detect multiple use and apply precedence. To set multiple aliases with different values for the optional parameters, use the decorator multiple times with the same name. This method will only work properly when the alias parameter is set as a keyword (named) arg, therefore the function in question should ensure that any aliases come after *args or bare * (marking keyword-only arguments: https://peps.python.org/pep-3102/). Note also that aliases do not have to appear in the original function’s argument list.

Parameters:

name (str) – The canonical name of the parameter.
aliases (str) – One or more alias names for the parameter.
removed_in_version (str | None) – The version in which the alias will be removed. This should typically have a value. In the rare case that an alias is not deprecated, set this to None.
position (int) – The 0-based position of the canonical argument if it could be specified positionally. Use None for a keyword-only (named) argument.
raise_on_multiple (bool) – When True (default), raise an exception if a value is supplied via multiple names.

hvac.utils.comma_delimited_to_list(list_param)[source]

Convert comma-delimited list / string into a list of strings

Parameters:: list_param (str | unicode) – Comma-delimited string
Returns:: A list of strings
Return type:: list

hvac.utils.deprecated_method(to_be_removed_in_version, new_method=None)[source]

This is a decorator which can be used to mark methods as deprecated. It will result in a warning being emitted when the function is used.

Parameters:

to_be_removed_in_version (str) – Version of this module the decorated method will be removed in.
new_method (function) – Method intended to replace the decorated method. This method’s docstrings are included in the decorated method’s docstring.

Returns:

Wrapped function that includes a deprecation warning and update docstrings from the replacement method.

Return type:

types.FunctionType

hvac.utils.format_url(format_str, *args, **kwargs)[source]

Creates a URL using the specified format after escaping the provided arguments.

Parameters:

format_str (str) – The URL containing replacement fields.
kwargs (dict) – Positional replacement field values.
kwargs – Named replacement field values.

Returns:

The formatted URL path with escaped replacement fields.

Return type:

str

hvac.utils.generate_method_deprecation_message(to_be_removed_in_version, old_method_name, method_name=None, module_name=None)[source]

Generate a message to be used when warning about the use of deprecated methods.

Parameters:

to_be_removed_in_version (str) – Version of this module the deprecated method will be removed in.
old_method_name (str) – Deprecated method name.
method_name (str) – Method intended to replace the deprecated method indicated. This method’s docstrings are included in the decorated method’s docstring.
module_name (str) – Name of the module containing the new method to use.

Returns:

Full deprecation warning message for the indicated method.

Return type:

str

hvac.utils.generate_parameter_deprecation_message(to_be_removed_in_version, old_parameter_name, new_parameter_name=None, extra_notes=None)[source]

Generate a message to be used when warning about the use of deprecated paramers.

Parameters:

to_be_removed_in_version (str) – Version of this module the deprecated parameter will be removed in.
old_parameter_name (str) – Deprecated parameter name.
new_parameter_name (str | None) – Parameter intended to replace the deprecated parameter, if applicable.
extra_notes (str | None) – Optional freeform text used to provide additional context, alternatives, or notes.

Returns:

Full deprecation warning message for the indicated parameter.

Return type:

str

hvac.utils.generate_property_deprecation_message(to_be_removed_in_version, old_name, new_name, new_attribute, module_name='Client')[source]

Generate a message to be used when warning about the use of deprecated properties.

Parameters:

to_be_removed_in_version (str) – Version of this module the deprecated property will be removed in.
old_name (str) – Deprecated property name.
new_name (str) – Name of the new property name to use.
new_attribute (str) – The new attribute where the new property can be found.
module_name (str) – Name of the module containing the new method to use.

Returns:

Full deprecation warning message for the indicated property.

Return type:

str

hvac.utils.get_token_from_env()[source]

Get the token from env var, VAULT_TOKEN. If not set, attempt to get the token from, ~/.vault-token

Returns:: The vault token if set, else None
Return type:: str | None

hvac.utils.getattr_with_deprecated_properties(obj, item, deprecated_properties)[source]

Helper method to use in the getattr method of a class with deprecated properties.

Parameters:

obj (object) – Instance of the Class containing the deprecated properties in question.
item (str) – Name of the attribute being requested.
deprecated_properties (Dict) – Dict of deprecated properties. Each key is the name of the old property. Each value is a dict with at least a “to_be_removed_in_version” and “client_property” key to be used in the displayed deprecation warning. An optional “new_property” key contains the name of the new property within the “client_property”, otherwise the original name is used.

Returns:

The new property indicated where available.

Return type:

object

hvac.utils.list_to_comma_delimited(list_param)[source]

Convert a list of strings into a comma-delimited list / string.

Parameters:: list_param (list) – A list of strings.
Returns:: Comma-delimited string.
Return type:: str

hvac.utils.raise_for_error(method, url, status_code, message=None, errors=None, text=None, json=None)[source]

Helper method to raise exceptions based on the status code of a response received back from Vault.

Parameters:

method (str) – HTTP method of a request to Vault.
url (str) – URL of the endpoint requested in Vault.
status_code (int) – Status code received in a response from Vault.
message (str) – Optional message to include in a resulting exception.
errors (list | str) – Optional errors to include in a resulting exception.
text (str) – Optional text of the response.
json (object) – Optional deserialized version of a JSON response (object)

Raises:

hvac.utils.remove_nones(params)[source]

Removes None values from optional arguments in a parameter dictionary.

Parameters:: params (dict) – The dictionary of parameters to be filtered.
Returns:: A filtered copy of the parameter dictionary.
Return type:: dict

hvac.utils.validate_list_of_strings_param(param_name, param_argument)[source]

Validate that an argument is a list of strings. Returns nothing if valid, raises ParamValidationException if invalid.

Parameters:

param_name (str | unicode) – The name of the parameter being validated. Used in any resulting exception messages.
param_argument (list) – The argument to validate.

hvac.utils.validate_pem_format(param_name, param_argument)[source]

Validate that an argument is a PEM-formatted public key or certificate

Parameters:

param_name (str | unicode) – The name of the parameter being validate. Used in any resulting exception messages.
param_argument (str | unicode) – The argument to validate

Returns:

True if the argument is validate False otherwise

Return type:

bool