# keystone.common.utils module

class keystone.common.utils.SmarterEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

  Bases: `JSONEncoder`

  Help for JSON encoding dict-like objects.

  default(obj)

    Implement this method in a subclass such that it returns a serializable object for `o`, or calls the base implementation (to raise a `TypeError`).

    For example, to support arbitrary iterators, you could implement default like this:

        def default(self, o):
            try:
                iterable = iter(o)
            except TypeError:
                pass
            else:
                return list(iterable)
            # Let the base class default method raise the TypeError
            return super().default(o)

class keystone.common.utils.WhiteListedItemFilter(whitelist, data)

  Bases: `object`

keystone.common.utils.attr_as_boolean(val_attr)

  Return the boolean value, decoded from a string.

  We test explicitly for a value meaning False, which can be one of several formats as specified in oslo strutils.FALSE_STRINGS. All other string values (including an empty string) are treated as meaning True.

keystone.common.utils.auth_str_equal(provided, known)

  Constant-time string comparison.

  Params provided:

    the first string

  Params known:

    the second string

  Returns:

    True if the strings are equal.

  This function takes two strings and compares them. It is intended to be used when doing a comparison for authentication purposes to help guard against timing attacks. When using the function for this purpose, always provide the user-provided password as the first argument. The time this function will take is always a factor of the length of this string.

keystone.common.utils.check_endpoint_url(url)

  Check substitution of url.

  The invalid urls are as follows: urls with substitutions that is not in the whitelist

  Check the substitutions in the URL to make sure they are valid and on the whitelist.

  Parameters:

    url (str) – the URL to validate

  Return type:

    None

  Raises:

    keystone.exception.URLValidationError – if the URL is invalid

keystone.common.utils.create_directory(directory, keystone_user_id=None, keystone_group_id=None)

  Attempt to create a directory if it doesn’t exist.

  Parameters:

    - directory – string containing the path of the directory to create.

    - keystone_user_id – the system ID of the process running keystone.

    - keystone_group_id – the system ID of the group running keystone.

keystone.common.utils.flatten_dict(d, parent_key='')

  Flatten a nested dictionary.

  Converts a dictionary with nested values to a single level flat dictionary, with dotted notation for each key.

keystone.common.utils.format_url(url, substitutions, silent_keyerror_failures=None)

  Format a user-defined URL with the given substitutions.

  Parameters:

    - url (string) – the URL to be formatted

    - substitutions (dict) – the dictionary used for substitution

    - silent_keyerror_failures (list) – keys for which we should be silent if there is a KeyError exception on substitution attempt

  Returns:

    a formatted URL

keystone.common.utils.get_certificate_issuer_dn(cert_pem)

  Get issuer DN from the PEM certificate content.

  Parameters:

    cert_pem (str) – the PEM certificate content

  Return type:

    JSON data for issuer DN

  Raises:

    keystone.exception.ValidationError – if the PEM certificate content is invalid

keystone.common.utils.get_certificate_subject_dn(cert_pem)

  Get subject DN from the PEM certificate content.

  Parameters:

    cert_pem (str) – the PEM certificate content

  Return type:

    JSON data for subject DN

  Raises:

    keystone.exception.ValidationError – if the PEM certificate content is invalid

keystone.common.utils.get_certificate_thumbprint(cert_pem)

  Get certificate thumbprint from the PEM certificate content.

  Parameters:

    cert_pem (str) – the PEM certificate content

  Return type:

    certificate thumbprint

keystone.common.utils.get_unix_group(group=None)

  Get the gid and group name.

  This is a convenience utility which accepts a variety of input which might represent a unix group. If successful it returns the gid and name. Valid input is:

  string

    A string is first considered to be a group name and a lookup is attempted under that name. If no name is found then an attempt is made to convert the string to an integer and perform a lookup as a gid.

  int

    An integer is interpreted as a gid.

  None

    None is interpreted to mean use the current process’s effective group.

  If the input is a valid type but no group is found a KeyError is raised. If the input is not a valid type a TypeError is raised.

  Parameters:

    group (object) – string, int or None specifying the group to lookup.

  Returns:

    tuple of (gid, name)

keystone.common.utils.get_unix_user(user=None)

  Get the uid and user name.

  This is a convenience utility which accepts a variety of input which might represent a unix user. If successful it returns the uid and name. Valid input is:

  string

    A string is first considered to be a user name and a lookup is attempted under that name. If no name is found then an attempt is made to convert the string to an integer and perform a lookup as a uid.

  int

    An integer is interpreted as a uid.

  None

    None is interpreted to mean use the current process’s effective user.

  If the input is a valid type but no user is found a KeyError is raised. If the input is not a valid type a TypeError is raised.

  Parameters:

    user (object) – string, int or None specifying the user to lookup.

  Returns:

    tuple of (uid, name)

keystone.common.utils.hash_access_key(access)

keystone.common.utils.is_not_url_safe(name)

  Check if a string contains any url reserved characters.

keystone.common.utils.isotime(at=None, subsecond=False)

  Stringify time in ISO 8601 format.

  Python provides a similar instance method for datetime.datetime objects called isoformat(). The format of the strings generated by isoformat() has a couple of problems:

  1) The strings generated by isotime() are used in tokens and other public APIs that we can’t change without a deprecation period. The strings generated by isoformat() are not the same format, so we can’t just change to it.

  2) The strings generated by isoformat() do not include the microseconds if the value happens to be 0. This will likely show up as random failures as parsers may be written to always expect microseconds, and it will parse correctly most of the time.

  Parameters:

    - at (datetime.datetime) – Optional datetime object to return at a string. If not provided, the time when the function was called will be used.

    - subsecond (bool) – If true, the returned string will represent microsecond precision, but only precise to the second. For example, a datetime.datetime(2016, 9, 14, 14, 1, 13, 970223) will be returned as 2016-09-14T14:01:13.000000Z.

  Returns:

    A time string represented in ISO 8601 format.

  Return type:

    str

keystone.common.utils.list_url_unsafe_chars(name)

  Return a list of the reserved characters.

keystone.common.utils.lower_case_hostname(url)

  Change the URL’s hostname to lowercase.

keystone.common.utils.nested_contexts(*contexts)

keystone.common.utils.parse_expiration_date(expiration_date)

keystone.common.utils.remove_standard_port(url)

keystone.common.utils.resource_uuid(value)

  Convert input to valid UUID hex digits.

keystone.common.utils.setup_remote_pydev_debug()

this page last updated: 2026-08-17 12:45:24

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

found an error? report a bug