common Package

common Package

eventlet_backdoor Module

exception keystone.openstack.common.eventlet_backdoor.EventletBackdoorConfigValueError(port_range, help_msg, ex)[source]

Bases: exceptions.Exception

keystone.openstack.common.eventlet_backdoor.initialize_if_enabled()[source]

excutils Module

Exception related utilities.

keystone.openstack.common.excutils.forever_retry_uncaught_exceptions(infunc)[source]
class keystone.openstack.common.excutils.save_and_reraise_exception(reraise=True)[source]

Bases: object

Save current exception, run some code and then re-raise.

In some cases the exception context can be cleared, resulting in None being attempted to be re-raised after an exception handler is run. This can happen when eventlet switches greenthreads or when running an exception handler, code raises and catches an exception. In both cases the exception context will be cleared.

To work around this, we save the exception state, run handler code, and then re-raise the original exception. If another exception occurs, the saved exception is logged and the new exception is re-raised.

In some cases the caller may not want to re-raise the exception, and for those circumstances this context provides a reraise flag that can be used to suppress the exception. For example:

except Exception:
    with save_and_reraise_exception() as ctxt:
        decide_if_need_reraise()
        if not should_be_reraised:
            ctxt.reraise = False

If another exception occurs and reraise flag is False, the saved exception will not be logged.

If the caller wants to raise new exception during exception handling he/she sets reraise to False initially with an ability to set it back to True if needed:

except Exception:
    with save_and_reraise_exception(reraise=False) as ctxt:
        [if statements to determine whether to raise a new exception]
        # Not raising a new exception, so reraise
        ctxt.reraise = True

fileutils Module

keystone.openstack.common.fileutils.delete_cached_file(filename)[source]

Delete cached file if present.

Parameters:filename – filename to delete
keystone.openstack.common.fileutils.delete_if_exists(path, remove=<built-in function unlink>)[source]

Delete a file, but ignore file not found error.

Parameters:
  • path – File to delete
  • remove – Optional function to remove passed path
keystone.openstack.common.fileutils.ensure_tree(path)[source]

Create a directory (and any ancestor directories required)

Parameters:path – Directory to create
keystone.openstack.common.fileutils.file_open(*args, **kwargs)[source]

Open file

see built-in open() documentation for more details

Note: The reason this is kept in a separate module is to easily be able to provide a stub module that doesn’t alter system state at all (for unit tests)

keystone.openstack.common.fileutils.read_cached_file(filename, force_reload=False)[source]

Read from a file if it has been modified.

Parameters:force_reload – Whether to reload the file.
Returns:A tuple with a boolean specifying if the data is fresh or not.
keystone.openstack.common.fileutils.remove_path_on_error(*args, **kwds)[source]

Protect code that wants to operate on PATH atomically. Any exception will cause PATH to be removed.

Parameters:
  • path – File to work with
  • remove – Optional function to remove passed path
keystone.openstack.common.fileutils.write_to_tempfile(content, path=None, suffix='', prefix='tmp')[source]

Create temporary file or use existing file.

This util is needed for creating temporary file with specified content, suffix and prefix. If path is not None, it will be used for writing content. If the path doesn’t exist it’ll be created.

Parameters:
  • content – content for temporary file.
  • path – same as parameter ‘dir’ for mkstemp
  • suffix – same as parameter ‘suffix’ for mkstemp
  • prefix – same as parameter ‘prefix’ for mkstemp

For example: it can be used in database tests for creating configuration files.

gettextutils Module

gettext for openstack-common modules.

Usual usage in an openstack.common module:

from keystone.openstack.common.gettextutils import _
class keystone.openstack.common.gettextutils.Message[source]

Bases: unicode

A Message object is a unicode object that can be translated.

Translation of Message is done explicitly using the translate() method. For all non-translation intents and purposes, a Message is simply unicode, and can be treated as such.

translate(desired_locale=None)[source]

Translate this message to the desired locale.

Parameters:desired_locale – The desired locale to translate the message to, if no locale is provided the message will be translated to the system’s default locale.
Returns:the translated message in unicode
class keystone.openstack.common.gettextutils.TranslationHandler(locale=None, target=None)[source]

Bases: logging.handlers.MemoryHandler

Handler that translates records before logging them.

The TranslationHandler takes a locale and a target logging.Handler object to forward LogRecord objects to after translating them. This handler depends on Message objects being logged, instead of regular strings.

The handler can be configured declaratively in the logging.conf as follows:

[handlers] keys = translatedlog, translator

[handler_translatedlog] class = handlers.WatchedFileHandler args = (‘/var/log/api-localized.log’,) formatter = context

[handler_translator] class = openstack.common.log.TranslationHandler target = translatedlog args = (‘zh_CN’,)

If the specified locale is not available in the system, the handler will log in the default locale.

emit(record)[source]
setFormatter(fmt)[source]
class keystone.openstack.common.gettextutils.TranslatorFactory(domain, localedir=None)[source]

Bases: object

Create translator functions

log_critical[source]

Translate critical-level log messages.

log_error[source]

Translate error-level log messages.

log_info[source]

Translate info-level log messages.

log_warning[source]

Translate warning-level log messages.

primary[source]

The default translation function.

keystone.openstack.common.gettextutils.enable_lazy()[source]

Convenience function for configuring _() to use lazy gettext

Call this at the start of execution to enable the gettextutils._ function to use lazy gettext functionality. This is useful if your project is importing _ directly instead of using the gettextutils.install() way of importing the _ function.

keystone.openstack.common.gettextutils.get_available_languages(domain)[source]

Lists the available languages for the given translation domain.

Parameters:domain – the domain to get languages for
keystone.openstack.common.gettextutils.install(domain)[source]

Install a _() function using the given translation domain.

Given a translation domain, install a _() function using gettext’s install() function.

The main difference from gettext.install() is that we allow overriding the default localedir (e.g. /usr/share/locale) using a translation-domain-specific environment variable (e.g. NOVA_LOCALEDIR).

Note that to enable lazy translation, enable_lazy must be called.

Parameters:domain – the translation domain
keystone.openstack.common.gettextutils.translate(obj, desired_locale=None)[source]

Gets the translated unicode representation of the given object.

If the object is not translatable it is returned as-is. If the locale is None the object is translated to the system locale.

Parameters:
  • obj – the object to translate
  • desired_locale – the locale to translate the message to, if None the default system locale will be used
Returns:

the translated object in unicode, or the original object if it could not be translated

importutils Module

Import related utilities and helper functions.

keystone.openstack.common.importutils.import_class(import_str)[source]

Returns a class from a string including module and class.

keystone.openstack.common.importutils.import_module(import_str)[source]

Import a module.

keystone.openstack.common.importutils.import_object(import_str, *args, **kwargs)[source]

Import a class and return an instance of it.

keystone.openstack.common.importutils.import_object_ns(name_space, import_str, *args, **kwargs)[source]

Tries to import object from default namespace.

Imports a class and return an instance of it, first by trying to find the class in a default namespace, then failing back to a full path if not found in the default namespace.

keystone.openstack.common.importutils.import_versioned_module(version, submodule=None)[source]
keystone.openstack.common.importutils.try_import(import_str, default=None)[source]

Try to import a module and if it fails return default.

jsonutils Module

JSON related utilities.

This module provides a few things:

1) A handy function for getting an object down to something that can be JSON serialized. See to_primitive().

2) Wrappers around loads() and dumps(). The dumps() wrapper will automatically use to_primitive() for you if needed.

3) This sets up anyjson to use the loads() and dumps() wrappers if anyjson is available.

keystone.openstack.common.jsonutils.dump(obj, fp, *args, **kwargs)[source]
keystone.openstack.common.jsonutils.dumps(value, default=<function to_primitive at 0x269b6e0>, **kwargs)[source]
keystone.openstack.common.jsonutils.load(fp, encoding='utf-8', **kwargs)[source]
keystone.openstack.common.jsonutils.loads(s, encoding='utf-8', **kwargs)[source]
keystone.openstack.common.jsonutils.to_primitive(value, convert_instances=False, convert_datetime=True, level=0, max_depth=3)[source]

Convert a complex object into primitives.

Handy for JSON serialization. We can optionally handle instances, but since this is a recursive function, we could have cyclical data structures.

To handle cyclical data structures we could track the actual objects visited in a set, but not all objects are hashable. Instead we just track the depth of the object inspections and don’t go too deep.

Therefore, convert_instances=True is lossy ... be aware.

local Module

Local storage of variables using weak references

class keystone.openstack.common.local.WeakLocal[source]

Bases: thread._local

log Module

OpenStack logging handler.

This module adds to logging functionality by adding the option to specify a context object when calling the various log methods. If the context object is not specified, default formatting is used. Additionally, an instance uuid may be passed as part of the log message, which is intended to make it easier for admins to find messages related to a specific instance.

It also allows setting of formatting information through conf.

class keystone.openstack.common.log.BaseLoggerAdapter(logger, extra)[source]

Bases: logging.LoggerAdapter

audit(msg, *args, **kwargs)[source]
isEnabledFor(level)[source]
class keystone.openstack.common.log.ColorHandler(strm=None)[source]

Bases: logging.StreamHandler

LEVEL_COLORS = {40: '\x1b[01;31m', 10: '\x1b[00;32m', 50: '\x1b[01;31m', 20: '\x1b[00;36m', 21: '\x1b[01;36m', 30: '\x1b[01;33m'}
format(record)[source]
class keystone.openstack.common.log.ContextAdapter(logger, project_name, version_string)[source]

Bases: keystone.openstack.common.log.BaseLoggerAdapter

deprecated(msg, *args, **kwargs)[source]

Call this method when a deprecated feature is used.

If the system is configured for fatal deprecations then the message is logged at the ‘critical’ level and DeprecatedConfig will be raised.

Otherwise, the message will be logged (once) at the ‘warn’ level.

Raises :DeprecatedConfig if the system is configured for fatal deprecations.
handlers[source]
process(msg, kwargs)[source]
warn(msg, *args, **kwargs)

Delegate a warning call to the underlying logger, after adding contextual information from this adapter instance.

class keystone.openstack.common.log.ContextFormatter(*args, **kwargs)[source]

Bases: logging.Formatter

A context.RequestContext aware formatter configured through flags.

The flags used to set format strings are: logging_context_format_string and logging_default_format_string. You can also specify logging_debug_format_suffix to append extra formatting if the log level is debug.

For information about what variables are available for the formatter see: http://docs.python.org/library/logging.html#formatter

If available, uses the context value stored in TLS - local.store.context

format(record)[source]

Uses contextstring if request_id is set, otherwise default.

formatException(exc_info, record=None)[source]

Format exception output with CONF.logging_exception_prefix.

exception keystone.openstack.common.log.DeprecatedConfig(msg)[source]

Bases: exceptions.Exception

message = u'Fatal call to deprecated config: %(msg)s'
class keystone.openstack.common.log.JSONFormatter(fmt=None, datefmt=None)[source]

Bases: logging.Formatter

format(record)[source]
formatException(ei, strip_newlines=True)[source]
class keystone.openstack.common.log.LazyAdapter(name='unknown', version='unknown')[source]

Bases: keystone.openstack.common.log.BaseLoggerAdapter

logger[source]
exception keystone.openstack.common.log.LogConfigError(log_config, err_msg)[source]

Bases: exceptions.Exception

message = u'Error loading logging config %(log_config)s: %(err_msg)s'
class keystone.openstack.common.log.NullHandler(level=0)[source]

Bases: logging.Handler

createLock()[source]
emit(record)[source]
handle(record)[source]
class keystone.openstack.common.log.RFCSysLogHandler(*args, **kwargs)[source]

Bases: logging.handlers.SysLogHandler

format(record)[source]
class keystone.openstack.common.log.WritableLogger(logger, level=20)[source]

Bases: object

A thin wrapper that responds to write and logs.

write(msg)[source]
keystone.openstack.common.log.getLazyLogger(name='unknown', version='unknown')[source]

Returns lazy logger.

Creates a pass-through logger that does not create the real logger until it is really needed and delegates all calls to the real logger once it is created.

keystone.openstack.common.log.getLogger(name='unknown', version='unknown')[source]
keystone.openstack.common.log.set_defaults(logging_context_format_string=None, default_log_levels=None)[source]
keystone.openstack.common.log.setup(product_name, version='unknown')[source]

Setup logging.

loopingcall Module

class keystone.openstack.common.loopingcall.DynamicLoopingCall(f=None, *args, **kw)[source]

Bases: keystone.openstack.common.loopingcall.LoopingCallBase

A looping call which sleeps until the next known event.

The function called should return how long to sleep for before being called again.

start(initial_delay=None, periodic_interval_max=None)[source]
class keystone.openstack.common.loopingcall.FixedIntervalLoopingCall(f=None, *args, **kw)[source]

Bases: keystone.openstack.common.loopingcall.LoopingCallBase

A fixed interval looping call.

start(interval, initial_delay=None)[source]
class keystone.openstack.common.loopingcall.LoopingCallBase(f=None, *args, **kw)[source]

Bases: object

stop()[source]
wait()[source]
exception keystone.openstack.common.loopingcall.LoopingCallDone(retvalue=True)[source]

Bases: exceptions.Exception

Exception to break out and stop a LoopingCallBase.

The poll-function passed to LoopingCallBase can raise this exception to break out of the loop normally. This is somewhat analogous to StopIteration.

An optional return-value can be included as the argument to the exception; this return-value will be returned by LoopingCallBase.wait()

policy Module

Common Policy Engine Implementation

Policies can be expressed in one of two forms: A list of lists, or a string written in the new policy language.

In the list-of-lists representation, each check inside the innermost list is combined as with an “and” conjunction–for that check to pass, all the specified checks must pass. These innermost lists are then combined as with an “or” conjunction. This is the original way of expressing policies, but there now exists a new way: the policy language.

In the policy language, each check is specified the same way as in the list-of-lists representation: a simple “a:b” pair that is matched to the correct code to perform that check. However, conjunction operators are available, allowing for more expressiveness in crafting policies.

As an example, take the following rule, expressed in the list-of-lists representation:

[["role:admin"], ["project_id:%(project_id)s", "role:projectadmin"]]

In the policy language, this becomes:

role:admin or (project_id:%(project_id)s and role:projectadmin)

The policy language also has the “not” operator, allowing a richer policy rule:

project_id:%(project_id)s and not role:dunce

It is possible to perform policy checks on the following user attributes (obtained through the token): user_id, domain_id or project_id:

domain_id:<some_value>

Attributes sent along with API calls can be used by the policy engine (on the right side of the expression), by using the following syntax:

<some_value>:user.id

Contextual attributes of objects identified by their IDs are loaded from the database. They are also available to the policy engine and can be checked through the target keyword:

<some_value>:target.role.name

All these attributes (related to users, API calls, and context) can be checked against each other or against constants, be it literals (True, <a_number>) or strings.

Finally, two special policy checks should be mentioned; the policy check “@” will always accept an access, and the policy check ”!” will always reject an access. (Note that if a rule is either the empty list (“[]”) or the empty string, this is equivalent to the “@” policy check.) Of these, the ”!” policy check is probably the most useful, as it allows particular rules to be explicitly disabled.

class keystone.openstack.common.policy.AndCheck(rules)[source]

Bases: keystone.openstack.common.policy.BaseCheck

Implements the “and” logical operator.

A policy check that requires that a list of other checks all return True.

add_check(rule)[source]

Adds rule to be tested.

Allows addition of another rule to the list of rules that will be tested. Returns the AndCheck object for convenience.

class keystone.openstack.common.policy.BaseCheck[source]

Bases: object

Abstract base class for Check classes.

class keystone.openstack.common.policy.Check(kind, match)[source]

Bases: keystone.openstack.common.policy.BaseCheck

A base class to allow for user-defined policy checks.

class keystone.openstack.common.policy.Enforcer(policy_file=None, rules=None, default_rule=None, use_conf=True)[source]

Bases: object

Responsible for loading and enforcing rules.

Parameters:
  • policy_file – Custom policy file to use, if none is specified, CONF.policy_file will be used.
  • rules – Default dictionary / Rules to use. It will be considered just in the first instantiation. If load_rules(True), clear() or set_rules(True) is called this will be overwritten.
  • default_rule – Default rule to use, CONF.default_rule will be used if none is specified.
  • use_conf – Whether to load rules from cache or config file.
clear()[source]

Clears Enforcer rules, policy’s cache and policy’s path.

enforce(rule, target, creds, do_raise=False, exc=None, *args, **kwargs)[source]

Checks authorization of a rule against the target and credentials.

Parameters:
  • rule – A string or BaseCheck instance specifying the rule to evaluate.
  • target – As much information about the object being operated on as possible, as a dictionary.
  • creds – As much information about the user performing the action as possible, as a dictionary.
  • do_raise – Whether to raise an exception or not if check fails.
  • exc – Class of the exception to raise if the check fails. Any remaining arguments passed to check() (both positional and keyword arguments) will be passed to the exception class. If not specified, PolicyNotAuthorized will be used.
Returns:

Returns False if the policy does not allow the action and exc is not provided; otherwise, returns a value that evaluates to True. Note: for rules using the “case” expression, this True value will be the specified string from the expression.

load_rules(force_reload=False)[source]

Loads policy_path’s rules.

Policy file is cached and will be reloaded if modified.

Parameters:force_reload – Whether to overwrite current rules.
set_rules(rules, overwrite=True, use_conf=False)[source]

Create a new Rules object based on the provided dict of rules.

Parameters:
  • rules – New rules to use. It should be an instance of dict.
  • overwrite – Whether to overwrite current rules or update them with the new rules.
  • use_conf – Whether to reload rules from cache or config file.
class keystone.openstack.common.policy.FalseCheck[source]

Bases: keystone.openstack.common.policy.BaseCheck

A policy check that always returns False (disallow).

class keystone.openstack.common.policy.GenericCheck(kind, match)[source]

Bases: keystone.openstack.common.policy.Check

class keystone.openstack.common.policy.HttpCheck(kind, match)[source]

Bases: keystone.openstack.common.policy.Check

class keystone.openstack.common.policy.NotCheck(rule)[source]

Bases: keystone.openstack.common.policy.BaseCheck

Implements the “not” logical operator.

A policy check that inverts the result of another policy check.

class keystone.openstack.common.policy.OrCheck(rules)[source]

Bases: keystone.openstack.common.policy.BaseCheck

Implements the “or” operator.

A policy check that requires that at least one of a list of other checks returns True.

add_check(rule)[source]

Adds rule to be tested.

Allows addition of another rule to the list of rules that will be tested. Returns the OrCheck object for convenience.

class keystone.openstack.common.policy.ParseState[source]

Bases: object

Implement the core of parsing the policy language.

Uses a greedy reduction algorithm to reduce a sequence of tokens into a single terminal, the value of which will be the root of the Check tree.

Note: error reporting is rather lacking. The best we can get with this parser formulation is an overall “parse failed” error. Fortunately, the policy language is simple enough that this shouldn’t be that big a problem.

reduce()[source]

Perform a greedy reduction of the token stream.

If a reducer method matches, it will be executed, then the reduce() method will be called recursively to search for any more possible reductions.

reducers = [(['check', 'or', 'check'], '_make_or_expr'), (['or_expr', 'or', 'check'], '_extend_or_expr'), (['not', 'check'], '_make_not_expr'), (['check', 'and', 'check'], '_make_and_expr'), (['and_expr', 'and', 'check'], '_extend_and_expr'), (['(', 'or_expr', ')'], '_wrap_check'), (['(', 'and_expr', ')'], '_wrap_check'), (['(', 'check', ')'], '_wrap_check')]
result[source]

Obtain the final result of the parse.

Raises ValueError if the parse failed to reduce to a single result.

shift(tok, value)[source]

Adds one more token to the state. Calls reduce().

class keystone.openstack.common.policy.ParseStateMeta[source]

Bases: type

Metaclass for the ParseState class.

Facilitates identifying reduction methods.

exception keystone.openstack.common.policy.PolicyNotAuthorized(rule)[source]

Bases: exceptions.Exception

class keystone.openstack.common.policy.RoleCheck(kind, match)[source]

Bases: keystone.openstack.common.policy.Check

class keystone.openstack.common.policy.RuleCheck(kind, match)[source]

Bases: keystone.openstack.common.policy.Check

class keystone.openstack.common.policy.Rules(rules=None, default_rule=None)[source]

Bases: dict

A store for rules. Handles the default_rule setting directly.

classmethod load_json(data, default_rule=None)[source]

Allow loading of JSON rule data.

class keystone.openstack.common.policy.TrueCheck[source]

Bases: keystone.openstack.common.policy.BaseCheck

A policy check that always returns True (allow).

keystone.openstack.common.policy.parse_rule(rule)[source]

Parses a policy rule into a tree of Check objects.

keystone.openstack.common.policy.reducer(*tokens)[source]

Decorator for reduction methods.

Arguments are a sequence of tokens, in order, which should trigger running this reduction method.

keystone.openstack.common.policy.register(name, func=None)[source]

Register a function or Check class as a policy check.

Parameters:
  • name – Gives the name of the check type, e.g., ‘rule’, ‘role’, etc. If name is None, a default check type will be registered.
  • func – If given, provides the function or class to register. If not given, returns a function taking one argument to specify the function or class to register, allowing use as a decorator.

processutils Module

System-level utilities and helper functions.

exception keystone.openstack.common.processutils.InvalidArgumentError(message=None)[source]

Bases: exceptions.Exception

exception keystone.openstack.common.processutils.NoRootWrapSpecified(message=None)[source]

Bases: exceptions.Exception

exception keystone.openstack.common.processutils.ProcessExecutionError(stdout=None, stderr=None, exit_code=None, cmd=None, description=None)[source]

Bases: exceptions.Exception

exception keystone.openstack.common.processutils.UnknownArgumentError(message=None)[source]

Bases: exceptions.Exception

keystone.openstack.common.processutils.execute(*cmd, **kwargs)[source]

Helper method to shell out and execute a command through subprocess.

Allows optional retry.

Parameters:
  • cmd (string) – Passed to subprocess.Popen.
  • process_input (string) – Send to opened process.
  • env_variables (dict) – Environment variables and their values that will be set for the process.
  • check_exit_code (boolean, int, or [int]) – Single bool, int, or list of allowed exit codes. Defaults to [0]. Raise ProcessExecutionError unless program exits with one of these code.
  • delay_on_retry (boolean) – True | False. Defaults to True. If set to True, wait a short amount of time before retrying.
  • attempts (int) – How many times to retry cmd.
  • run_as_root (boolean) – True | False. Defaults to False. If set to True, the command is prefixed by the command specified in the root_helper kwarg.
  • root_helper (string) – command to prefix to commands called with run_as_root=True
  • shell (boolean) – whether or not there should be a shell used to execute this command. Defaults to false.
  • loglevel (int. (Should be logging.DEBUG or logging.INFO)) – log level for execute commands.
Returns:

(stdout, stderr) from process execution

Raises :

UnknownArgumentError on receiving unknown arguments

Raises :

ProcessExecutionError

keystone.openstack.common.processutils.get_worker_count()[source]

Utility to get the default worker count.

@return: The number of CPUs if that can be determined, else a default
worker count of 1 is returned.
keystone.openstack.common.processutils.ssh_execute(ssh, cmd, process_input=None, addl_env=None, check_exit_code=True)[source]
keystone.openstack.common.processutils.trycmd(*args, **kwargs)[source]

A wrapper around execute() to more easily handle warnings and errors.

Returns an (out, err) tuple of strings containing the output of the command’s stdout and stderr. If ‘err’ is not empty then the command can be considered to have failed.

:discard_warnings True | False. Defaults to False. If set to True,
then for succeeding commands, stderr is cleared

service Module

Generic Node base class for all workers that run on hosts.

class keystone.openstack.common.service.Launcher[source]

Bases: object

Launch one or more services and wait for them to complete.

launch_service(service)[source]

Load and start the given service.

Parameters:service – The service you would like to start.
Returns:None
restart()[source]

Reload config files and restart service.

Returns:None
stop()[source]

Stop all services which are currently running.

Returns:None
wait()[source]

Waits until all services have been stopped, and then returns.

Returns:None
class keystone.openstack.common.service.ProcessLauncher(wait_interval=0.01)[source]

Bases: object

handle_signal()[source]
launch_service(service, workers=1)[source]
stop()[source]

Terminate child processes and wait on each.

wait()[source]

Loop waiting on children to die and respawning as necessary.

class keystone.openstack.common.service.Service(threads=1000)[source]

Bases: object

Service object for binaries running on hosts.

reset()[source]
start()[source]
stop()[source]
wait()[source]
class keystone.openstack.common.service.ServiceLauncher[source]

Bases: keystone.openstack.common.service.Launcher

handle_signal()[source]
wait(ready_callback=None)[source]
class keystone.openstack.common.service.ServiceWrapper(service, workers)[source]

Bases: object

class keystone.openstack.common.service.Services[source]

Bases: object

add(service)[source]
restart()[source]
static run_service(service, done)[source]

Service start wrapper.

Parameters:
  • service – service to run
  • done – event to wait on until a shutdown is triggered
Returns:

None

stop()[source]
wait()[source]
exception keystone.openstack.common.service.SignalExit(signo, exccode=1)[source]

Bases: exceptions.SystemExit

keystone.openstack.common.service.launch(service, workers=1)[source]

strutils Module

System-level utilities and helper functions.

keystone.openstack.common.strutils.bool_from_string(subject, strict=False, default=False)[source]

Interpret a string as a boolean.

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’.

keystone.openstack.common.strutils.int_from_bool_as_string(subject)[source]

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

keystone.openstack.common.strutils.mask_password(message, secret='***')[source]

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' : '***'"
>>> mask_password("u'original_password' :   u'aaaaa'")
"u'original_password' :   u'***'"
keystone.openstack.common.strutils.safe_decode(text, incoming=None, errors='strict')[source]

Decodes incoming text/bytes string using incoming if they’re not already unicode.

Parameters:
Returns:

text or a unicode incoming encoded representation of it.

Raises TypeError:
 

If text is not an instance of str

keystone.openstack.common.strutils.safe_encode(text, incoming=None, encoding='utf-8', errors='strict')[source]

Encodes incoming text/bytes string using encoding.

If incoming is not specified, text is expected to be encoded with current python’s default encoding. (sys.getdefaultencoding)

Parameters:
Returns:

text or a bytestring encoding encoded representation of it.

Raises TypeError:
 

If text is not an instance of str

keystone.openstack.common.strutils.string_to_bytes(text, unit_system='IEC', return_int=False)[source]

Converts a string into an float representation of bytes.

The units supported for IEC

Kb(it), Kib(it), Mb(it), Mib(it), Gb(it), Gib(it), Tb(it), Tib(it)
KB, KiB, MB, MiB, GB, GiB, TB, TiB

The units supported for SI

kb(it), Mb(it), Gb(it), Tb(it)
kB, MB, GB, TB

Note that the SI unit system does not support capital letter ‘K’

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.

keystone.openstack.common.strutils.to_slug(value, incoming=None, errors='strict')[source]

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

systemd Module

Helper module for systemd service readiness notification.

keystone.openstack.common.systemd.notify()[source]

Send notification to Systemd that service is ready.

For details see http://www.freedesktop.org/software/systemd/man/sd_notify.html

keystone.openstack.common.systemd.notify_once()[source]

Send notification once to Systemd that service is ready.

Systemd sets NOTIFY_SOCKET environment variable with the name of the socket listening for notifications from services. This method removes the NOTIFY_SOCKET environment variable to ensure notification is sent only once.

keystone.openstack.common.systemd.onready(notify_socket, timeout)[source]

Wait for systemd style notification on the socket.

Parameters:
  • notify_socket (string) – local socket address
  • timeout (float) – socket timeout
Returns:

0 service ready 1 service not ready 2 timeout occurred

threadgroup Module

class keystone.openstack.common.threadgroup.Thread(thread, group)[source]

Bases: object

Wrapper around a greenthread, that holds a reference to the ThreadGroup. The Thread will notify the ThreadGroup when it has done so it can be removed from the threads list.

stop()[source]
wait()[source]
class keystone.openstack.common.threadgroup.ThreadGroup(thread_pool_size=10)[source]

Bases: object

The point of the ThreadGroup class is to:

  • keep track of timers and greenthreads (making it easier to stop them when need be).
  • provide an easy API to add timers.
add_dynamic_timer(callback, initial_delay=None, periodic_interval_max=None, *args, **kwargs)[source]
add_thread(callback, *args, **kwargs)[source]
add_timer(interval, callback, initial_delay=None, *args, **kwargs)[source]
stop(graceful=False)[source]

stop function has the option of graceful=True/False.

  • In case of graceful=True, wait for all threads to be finished. Never kill threads.
  • In case of graceful=False, kill threads immediately.
stop_timers()[source]
thread_done(thread)[source]
wait()[source]

timeutils Module

Time related utilities and helper functions.

keystone.openstack.common.timeutils.advance_time_delta(timedelta)[source]

Advance overridden time using a datetime.timedelta.

keystone.openstack.common.timeutils.advance_time_seconds(seconds)[source]

Advance overridden time by seconds.

keystone.openstack.common.timeutils.clear_time_override()[source]

Remove the overridden time.

keystone.openstack.common.timeutils.delta_seconds(before, after)[source]

Return the difference between two timing objects.

Compute the difference in seconds between two date, time, or datetime objects (as a float, to microsecond resolution).

keystone.openstack.common.timeutils.is_newer_than(after, seconds)[source]

Return True if after is newer than seconds.

keystone.openstack.common.timeutils.is_older_than(before, seconds)[source]

Return True if before is older than seconds.

keystone.openstack.common.timeutils.is_soon(dt, window)[source]

Determines if time is going to happen in the next window seconds.

Parameters:
  • dt – the time
  • window – minimum seconds to remain to consider the time not soon
Returns:

True if expiration is within the given duration

keystone.openstack.common.timeutils.iso8601_from_timestamp(timestamp)[source]

Returns an iso8601 formatted date from timestamp.

keystone.openstack.common.timeutils.isotime(at=None, subsecond=False)[source]

Stringify time in ISO 8601 format.

keystone.openstack.common.timeutils.marshall_now(now=None)[source]

Make an rpc-safe datetime with microseconds.

Note: tzinfo is stripped, but not required for relative times.

keystone.openstack.common.timeutils.normalize_time(timestamp)[source]

Normalize time in arbitrary timezone to UTC naive object.

keystone.openstack.common.timeutils.parse_isotime(timestr)[source]

Parse time from ISO 8601 format.

keystone.openstack.common.timeutils.parse_strtime(timestr, fmt='%Y-%m-%dT%H:%M:%S.%f')[source]

Turn a formatted time back into a datetime.

keystone.openstack.common.timeutils.set_time_override(override_time=None)[source]

Overrides utils.utcnow.

Make it return a constant time or a list thereof, one at a time.

Parameters:override_time – datetime instance or list thereof. If not given, defaults to the current UTC time.
keystone.openstack.common.timeutils.strtime(at=None, fmt='%Y-%m-%dT%H:%M:%S.%f')[source]

Returns formatted utcnow.

keystone.openstack.common.timeutils.total_seconds(delta)[source]

Return the total seconds of datetime.timedelta object.

Compute total seconds of datetime.timedelta, datetime.timedelta doesn’t have method total_seconds in Python2.6, calculate it manually.

keystone.openstack.common.timeutils.unmarshall_time(tyme)[source]

Unmarshall a datetime dict.

keystone.openstack.common.timeutils.utcnow()[source]

Overridable version of utils.utcnow.

keystone.openstack.common.timeutils.utcnow_ts()[source]

Timestamp version of our utcnow function.

versionutils Module

Helpers for comparing version strings.

class keystone.openstack.common.versionutils.deprecated(as_of, in_favor_of=None, remove_in=2, what=None)[source]

Bases: object

A decorator to mark callables as deprecated.

This decorator logs a deprecation message when the callable it decorates is used. The message will include the release where the callable was deprecated, the release where it may be removed and possibly an optional replacement.

Examples:

  1. Specifying the required deprecated release
>>> @deprecated(as_of=deprecated.ICEHOUSE)
... def a(): pass
  1. Specifying a replacement:
>>> @deprecated(as_of=deprecated.ICEHOUSE, in_favor_of='f()')
... def b(): pass
  1. Specifying the release where the functionality may be removed:
>>> @deprecated(as_of=deprecated.ICEHOUSE, remove_in=+1)
... def c(): pass

4. Specifying the deprecated functionality will not be removed: >>> @deprecated(as_of=deprecated.ICEHOUSE, remove_in=0) ... def d(): pass

5. Specifying a replacement, deprecated functionality will not be removed: >>> @deprecated(as_of=deprecated.ICEHOUSE, in_favor_of=’f()’, remove_in=0) ... def e(): pass

BEXAR = 'B'
FOLSOM = 'F'
GRIZZLY = 'G'
HAVANA = 'H'
ICEHOUSE = 'I'
JUNO = 'J'
KILO = 'K'
keystone.openstack.common.versionutils.is_compatible(requested_version, current_version, same_major=True)[source]

Determine whether requested_version is satisfied by current_version; in other words, current_version is >= requested_version.

Parameters:
  • requested_version – version to check for compatibility
  • current_version – version to check against
  • same_major – if True, the major version must be identical between requested_version and current_version. This is used when a major-version difference indicates incompatibility between the two versions. Since this is the common-case in practice, the default is True.
Returns:

True if compatible, False if not