strutils

System-level utilities and helper functions.

oslo_utils.strutils.bool_from_string(subject, strict=False, default=False)

Interpret a subject as a boolean.

A subject can be a boolean, a string or an integer. Boolean type value will be returned directly, otherwise the subject will be converted to a string. A case-insensitive match is performed such that strings matching ‘t’,’true’, ‘on’, ‘y’, ‘yes’, or ‘1’ are considered True and, when strict=False, anything else returns the value specified by ‘default’.

Useful for JSON-decoded stuff and config file parsing.

If strict=True, unrecognized values, including None, will raise a ValueError which is useful when parsing values passed in from an API call. Strings yielding False are ‘f’, ‘false’, ‘off’, ‘n’, ‘no’, or ‘0’.

oslo_utils.strutils.check_string_length(value, name=None, min_length=0, max_length=None)

Check the length of specified string.

Parameters

  • value – the value of the string

  • name – the name of the string

  • min_length – the min_length of the string

  • max_length – the max_length of the string

Raises

TypeError, ValueError – For any invalid input.

New in version 3.7.

oslo_utils.strutils.int_from_bool_as_string(subject)

Interpret a string as a boolean and return either 1 or 0.

Any string value in:

(‘True’, ‘true’, ‘On’, ‘on’, ‘1’)

is interpreted as a boolean True.

Useful for JSON-decoded stuff and config file parsing

oslo_utils.strutils.is_int_like(val)

Check if a value looks like an integer with base 10.

Parameters

val (string) – Value to verify

Returns

bool

New in version 1.1.

oslo_utils.strutils.is_valid_boolstr(value)

Check if the provided string is a valid bool string or not.

Parameters

value (string) – value to verify

Returns

true if value is boolean string, false otherwise

New in version 3.17.

oslo_utils.strutils.mask_dict_password(dictionary, secret='***')

Replace password with secret in a dictionary recursively.

Parameters

  • dictionary – The dictionary which includes secret information.

  • secret – value with which to replace secret information.

Returns

The dictionary with string substitutions.

A dictionary (which may contain nested dictionaries) contains information (such as passwords) which should not be revealed, and this function helps detect and replace those with the ‘secret’ provided (or *** if none is provided).

Substitution is performed in one of three situations:

If the key is something that is considered to be indicative of a secret, then the corresponding value is replaced with the secret provided (or *** if none is provided).

If a value in the dictionary is a string, then it is masked using the mask_password() function.

Finally, if a value is a dictionary, this function will recursively mask that dictionary as well.

For example:

>>> mask_dict_password({'password': 'd81juxmEW_',
>>>                     'user': 'admin',
>>>                     'home-dir': '/home/admin'},
>>>                     '???')
{'password': '???', 'user': 'admin', 'home-dir': '/home/admin'}

For example (the value is masked using mask_password())

>>> mask_dict_password({'password': '--password d81juxmEW_',
>>>                     'user': 'admin',
>>>                     'home-dir': '/home/admin'},
>>>                     '???')
{'password': '--password ???', 'user': 'admin',
 'home-dir': '/home/admin'}

For example (a nested dictionary is masked):

>>> mask_dict_password({"nested": {'password': 'd81juxmEW_',
>>>                     'user': 'admin',
>>>                     'home': '/home/admin'}},
>>>                     '???')
{"nested": {'password': '???', 'user': 'admin', 'home': '/home/admin'}}

New in version 3.4.

oslo_utils.strutils.mask_password(message, secret='***')

Replace password with secret in message.

Parameters

  • message – The string which includes security information.

  • secret – value with which to replace passwords.

Returns

The unicode value of message with the password fields masked.

For example:

>>> mask_password("'adminPass' : 'aaaaa'")
"'adminPass' : '***'"
>>> mask_password("'admin_pass' : 'aaaaa'")
"'admin_pass' : '***'"
>>> mask_password('"password" : "aaaaa"')
'"password" : "***"'
>>> mask_password("'original_password' : 'aaaaa'")
"'original_password' : '***'"

New in version 0.2.

Changed in version 1.1: Replace also 'auth_token', 'new_pass' and 'auth_password' keys.

Changed in version 1.1.1: Replace also 'secret_uuid' key.

Changed in version 1.5: Replace also 'sys_pswd' key.

Changed in version 2.6: Replace also 'token' key.

Changed in version 2.7: Replace also 'secret' key.

Changed in version 3.4: Replace also 'configdrive' key.

Changed in version 3.8: Replace also 'CHAPPASSWORD' key.

oslo_utils.strutils.split_by_commas(value)

Split values by commas and quotes according to api-wg

Parameters

value – value to be split

New in version 3.17.

oslo_utils.strutils.split_path(path, minsegs=1, maxsegs=None, rest_with_last=False)

Validate and split the given HTTP request path.

Examples:

['a'] = _split_path('/a')
['a', None] = _split_path('/a', 1, 2)
['a', 'c'] = _split_path('/a/c', 1, 2)
['a', 'c', 'o/r'] = _split_path('/a/c/o/r', 1, 3, True)
Parameters

  • path – HTTP Request path to be split

  • minsegs – Minimum number of segments to be extracted

  • maxsegs – Maximum number of segments to be extracted

  • rest_with_last – If True, trailing data will be returned as part of last segment. If False, and there is trailing data, raises ValueError.

Returns

list of segments with a length of maxsegs (non-existent segments will return as None)

Raises

ValueError if given an invalid path

New in version 3.11.

oslo_utils.strutils.string_to_bytes(text, unit_system='IEC', return_int=False)

Converts a string into an float representation of bytes.

The units supported for IEC / mixed:

Kb(it), Kib(it), Mb(it), Mib(it), Gb(it), Gib(it), Tb(it), Tib(it)
KB, KiB, MB, MiB, GB, GiB, TB, TiB

The units supported for SI

kb(it), Mb(it), Gb(it), Tb(it)
kB, MB, GB, TB

SI units are interpreted as power-of-ten (e.g. 1kb = 1000b). Note that the SI unit system does not support capital letter ‘K’

IEC units are interpreted as power-of-two (e.g. 1MiB = 1MB = 1024b)

Mixed units interpret the “i” to mean IEC, and no “i” to mean SI (e.g. 1kb = 1000b, 1kib == 1024b). Additionaly, mixed units interpret ‘K’ as power-of-ten. This mode is not particuarly useful for new code, but can help with compatability for parsers such as GNU parted.

Parameters

  • text – String input for bytes size conversion.

  • unit_system – Unit system for byte size conversion.

  • return_int – If True, returns integer representation of text in bytes. (default: decimal)

Returns

Numerical representation of text in bytes.

Raises

ValueError – If text has an invalid value.

oslo_utils.strutils.to_slug(value, incoming=None, errors='strict')

Normalize string.

Convert to lowercase, remove non-word characters, and convert spaces to hyphens.

Inspired by Django’s slugify filter.

Parameters
Returns

slugified unicode representation of value

Raises

TypeError – If text is not an instance of str

oslo_utils.strutils.validate_integer(value, name, min_value=None, max_value=None)

Make sure that value is a valid integer, potentially within range.

Parameters

  • value – value of the integer

  • name – name of the integer

  • min_value – min_value of the integer

  • max_value – max_value of the integer

Returns

integer

Raises

ValueError if value is an invalid integer

New in version 3.33.