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),
Pb(it), Pib(it), Eb(it), Eib(it), Zb(it), Zib(it), Yb(it), Yib(it),
Rb(it), Rib(it), Qb(it), Qib(it)

KB, KiB, MB, MiB, GB, GiB, TB, TiB, PB, PiB, EB, EiB, ZB, ZiB,
YB, YiB, RB, RiB, QB, QiB

The units supported for SI

kb(it), Mb(it), Gb(it), Tb(it), Pb(it), Eb(it), Zb(it), Yb(it),
Rb(it), Qb(it)

kB, MB, GB, TB, PB, EB, ZB, YB, RB, QB

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.