hvac.utilsΒΆ
Misc utility functions and constants
Functions
|
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. |
|
Convert comma-delimited list / string into a list of strings |
|
This is a decorator which can be used to mark methods as deprecated. |
|
Creates a URL using the specified format after escaping the provided arguments. |
|
Generate a message to be used when warning about the use of deprecated methods. |
Generate a message to be used when warning about the use of deprecated paramers. |
|
|
Generate a message to be used when warning about the use of deprecated properties. |
Get the token from env var, VAULT_TOKEN. |
|
|
Helper method to use in the getattr method of a class with deprecated properties. |
|
Convert a list of strings into a comma-delimited list / string. |
|
Helper method to raise exceptions based on the status code of a response received back from Vault. |
|
Removes None values from optional arguments in a parameter dictionary. |
|
Validate that an argument is a list of strings. |
|
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 (List[dict]) β List of deprecated properties. Each item in the list is a dict with at least a βto_be_removed_in_versionβ and βclient_propertyβ key to be used in the displayed deprecation warning.
- 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.exceptions.InvalidRequest | hvac.exceptions.Unauthorized | hvac.exceptions.Forbidden | hvac.exceptions.InvalidPath | hvac.exceptions.RateLimitExceeded | hvac.exceptions.InternalServerError | hvac.exceptions.VaultNotInitialized | hvac.exceptions.BadGateway | hvac.exceptions.VaultDown | hvac.exceptions.UnexpectedError
-
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.
- 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.
- Returns
True if the argument is validated, False otherwise.
- Return type
bool
-
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