The cinder.utils Module

Utilities and helper functions.

class ComparableMixin

Bases: object

DO_NOTHING

Class that literrally does nothing.

We inherit from str in case it’s called with json.dumps.

class DoNothing

Bases: str

Class that literrally does nothing.

We inherit from str in case it’s called with json.dumps.

class TraceWrapperMetaclass

Bases: type

Metaclass that wraps all methods of a class with trace_method.

This metaclass will cause every function inside of the class to be decorated with the trace_method decorator.

To use the metaclass you define a class like so: @six.add_metaclass(utils.TraceWrapperMetaclass) class MyClass(object):

class TraceWrapperWithABCMetaclass

Bases: abc.ABCMeta, cinder.utils.TraceWrapperMetaclass

Metaclass that wraps all methods of a class with trace.

add_visible_admin_metadata(volume)

Add user-visible admin metadata to regular metadata.

Extracts the admin metadata keys that are to be made visible to non-administrators, and adds them to the regular metadata structure for the passed-in volume.

as_int(obj, quiet=True)

brick_attach_volume_encryptor(context, attach_info, encryption)

Attach encryption layer.

brick_detach_volume_encryptor(attach_info, encryption)

Detach encryption layer.

brick_get_connector(protocol, driver=None, use_multipath=False, device_scan_attempts=3, *args, **kwargs)

Wrapper to get a brick connector object.

This automatically populates the required protocol as well as the root_helper needed to execute commands.

brick_get_connector_properties(multipath=False, enforce_multipath=False)

Wrapper to automatically set root_helper in brick calls.

Parameters:

• multipath – A boolean indicating whether the connector can support multipath.
• enforce_multipath – If True, it raises exception when multipath=True is specified but multipathd is not running. If False, it falls back to multipath=False when multipathd is not running.

brick_get_encryptor(connection_info, *args, **kwargs)

Wrapper to get a brick encryptor object.

build_or_str(elements, str_format=None)

Builds a string of elements joined by ‘or’.

Will join strings with the ‘or’ word and if a str_format is provided it will be used to format the resulted joined string. If there are no elements an empty string will be returned.

Parameters:

• elements (String or iterable of strings.) – Elements we want to join.
• str_format (String.) – String to use to format the response.

calculate_virtual_free_capacity(total_capacity, free_capacity, provisioned_capacity, thin_provisioning_support, max_over_subscription_ratio, reserved_percentage, thin)

Calculate the virtual free capacity based on thin provisioning support.

Parameters:

• total_capacity – total_capacity_gb of a host_state or pool.
• free_capacity – free_capacity_gb of a host_state or pool.
• provisioned_capacity – provisioned_capacity_gb of a host_state or pool.
• thin_provisioning_support – thin_provisioning_support of a host_state or a pool.
• max_over_subscription_ratio – max_over_subscription_ratio of a host_state or a pool
• reserved_percentage – reserved_percentage of a host_state or a pool.
• thin – whether volume to be provisioned is thin

Returns:

the calculated virtual free capacity.

check_exclusive_options(**kwargs)

Checks that only one of the provided options is actually not-none.

Iterates over all the kwargs passed in and checks that only one of said arguments is not-none, if more than one is not-none then an exception will be raised with the names of those arguments who were not-none.

check_metadata_properties(metadata=None)

Checks that the volume metadata properties are valid.

check_ssh_injection(cmd_list)

check_string_length(value, name, min_length=0, max_length=None, allow_all_spaces=True)

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

convert_str(text)

Convert to native string.

Convert bytes and Unicode strings to native strings:

• convert to bytes on Python 2: encode Unicode using encodeutils.safe_encode()
• convert to Unicode on Python 3: decode bytes from UTF-8

execute(*cmd, **kwargs)

Convenience wrapper around oslo’s execute() method.

get_blkdev_major_minor(path, lookup_for_file=True)

Get ‘major:minor’ number of block device.

Get the device’s ‘major:minor’ number of a block device to control I/O ratelimit of the specified path. If lookup_for_file is True and the path is a regular file, lookup a disk device which the file lies on and returns the result for the device.

get_bool_param(param_string, params)

get_file_gid(path)

This primarily exists to make unit testing easier.

get_file_mode(path)

This primarily exists to make unit testing easier.

get_file_size(path)

Returns the file size.

get_root_helper()

if_notifications_enabled(f)

Calls decorated method only if notifications are enabled.

is_blk_device(dev)

is_none_string(val)

Check if a string represents a None value.

last_completed_audit_period(unit=None)

This method gives you the most recently completed audit period.

arguments:

units: string, one of ‘hour’, ‘day’, ‘month’, ‘year’

Periods normally begin at the beginning (UTC) of the period unit (So a ‘day’ period begins at midnight UTC, a ‘month’ unit on the 1st, a ‘year’ on Jan, 1) unit string may be appended with an optional offset like so: 'day@18‘ This will begin the period at 18:00 UTC. 'month@15‘ starts a monthly period on the 15th, and year@3 begins a yearly one on March 1st.

returns: 2 tuple of datetimes (begin, end)

The begin timestamp of this audit period is the same as the end of the previous.

log_unsupported_driver_warning(driver)

Annoy the log about unsupported drivers.

make_dev_path(dev, partition=None, base='/dev')

Return a path to a particular device.

>>> make_dev_path('xvdc')
/dev/xvdc

>>> make_dev_path('xvdc', 1)
/dev/xvdc1

monkey_patch()

Patches decorators for all functions in a specified module.

If the CONF.monkey_patch set as True, this function patches a decorator for all functions in specified modules.

You can set decorators for each modules using CONF.monkey_patch_modules. The format is “Module path:Decorator function”. Example: ‘cinder.api.ec2.cloud:’ cinder.openstack.common.notifier.api.notify_decorator’

Parameters of the decorator is as follows. (See cinder.openstack.common.notifier.api.notify_decorator)

Parameters:

• name – name of the function
• function – object of the function

notifications_enabled(conf)

Check if oslo notifications are enabled.

read_file_as_root(file_path)

Secure helper to read file as root.

remove_invalid_filter_options(context, filters, allowed_search_options)

Remove search options that are not valid for non-admin API/context.

require_driver_initialized(driver)

Verifies if driver is initialized

If the driver is not initialized, an exception will be raised.

Params driver:The driver instance. Raises:exception.DriverNotInitialized

resolve_hostname(hostname)

Resolves host name to IP address.

Resolves a host name (my.data.point.com) to an IP address (10.12.143.11). This routine also works if the data passed in hostname is already an IP. In this case, the same IP address will be returned.

Parameters:hostname – Host name to resolve. Returns:IP Address for Host name.

retry(exceptions, interval=1, retries=3, backoff_rate=2, wait_random=False)

robust_file_write(directory, filename, data)

Robust file write.

Use “write to temp file and rename” model for writing the persistence file.

Parameters:

• directory – Target directory to create a file.
• filename – File name to store specified data.
• data – String data.

sanitize_hostname(hostname)

Return a hostname which conforms to RFC-952 and RFC-1123 specs.

service_expired_time(with_timezone=False)

setup_tracing(trace_flags)

Set global variables for each trace flag.

Sets variables TRACE_METHOD and TRACE_API, which represent whether to log method and api traces.

Parameters:trace_flags – a list of strings

tempdir(*args, **kwds)

temporary_chown(*args, **kwds)

Temporarily chown a path.

Params owner_uid:  UID of temporary owner (defaults to current user)

trace(f)

Trace calls to the decorated function.

This decorator should always be defined as the outermost decorator so it is defined last. This is important so it does not interfere with other decorators.

Using this decorator on a function will cause its execution to be logged at DEBUG level with arguments, return values, and exceptions.

Returns:a function decorator

trace_api(f)

Decorates a function if TRACE_API is true.

trace_method(f)

Decorates a function if TRACE_METHOD is true.

validate_dictionary_string_length(specs)

Check the length of each key and value of dictionary.

validate_integer(value, name, min_value=None, max_value=None)

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

Parameters:

• value – the value of the integer
• name – the name of the integer
• min_length – the min_length of the integer
• max_length – the max_length of the integer

Returns:

integer

walk_class_hierarchy(clazz, encountered=None)

Walk class hierarchy, yielding most derived classes first.