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
value – Text to slugify
incoming – Text’s current encoding
errors – Errors handling policy. See here for valid values http://docs.python.org/2/library/codecs.html
- 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.