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.

Added 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

Added 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

Added 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'}}

Added 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' : '***'"

Added 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

Added 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

Added 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

Added in version 3.33.

strutils

strutils¶

oslo.utils 9.2.0.dev6

Page Contents