Table Of Contents

Previous topic

backends Package

Next topic

ldap Package

This Page

common Package

bufferedhttp Module

Monkey Patch httplib.HTTPResponse to buffer reads of headers. This can improve performance when making large numbers of small HTTP requests. This module also provides helper functions to make HTTP connections using BufferedHTTPResponse.

Warning

If you use this, be sure that the libraries you are using do not access the socket directly (xmlrpclib, I’m looking at you :/), and instead make all calls through httplib.

class keystone.common.bufferedhttp.BufferedHTTPConnection(host, port=None, strict=None, timeout=<object object at 0x40215668>, source_address=None)

Bases: httplib.HTTPConnection

HTTPConnection class that uses BufferedHTTPResponse

connect()
getexpect()
getresponse()
putrequest(method, url, skip_host=0, skip_accept_encoding=0)
response_class

alias of BufferedHTTPResponse

class keystone.common.bufferedhttp.BufferedHTTPResponse(sock, debuglevel=0, strict=0, method=None)

Bases: httplib.HTTPResponse

HTTPResponse class that buffers reading of headers

expect_response()
keystone.common.bufferedhttp.http_connect(ipaddr, port, device, partition, method, path, headers=None, query_string=None, ssl=False)

Helper function to create an HTTPConnection object. If ssl is set True, HTTPSConnection will be used. However, if ssl=False, BufferedHTTPConnection will be used, which is buffered for backend Swift services.

Parameters:
  • ipaddr – IPv4 address to connect to
  • port – port to connect to
  • device – device of the node to query
  • partition – partition on the device
  • method – HTTP method to request (‘GET’, ‘PUT’, ‘POST’, etc.)
  • path – request path
  • headers – dictionary of headers
  • query_string – request query string
  • ssl – set True if SSL should be used (default: False)
Returns:

HTTPConnection object

keystone.common.bufferedhttp.http_connect_raw(ipaddr, port, method, path, headers=None, query_string=None, ssl=False)

Helper function to create an HTTPConnection object. If ssl is set True, HTTPSConnection will be used. However, if ssl=False, BufferedHTTPConnection will be used, which is buffered for backend Swift services.

Parameters:
  • ipaddr – IPv4 address to connect to
  • port – port to connect to
  • method – HTTP method to request (‘GET’, ‘PUT’, ‘POST’, etc.)
  • path – request path
  • headers – dictionary of headers
  • query_string – request query string
  • ssl – set True if SSL should be used (default: False)
Returns:

HTTPConnection object

kvs Module

class keystone.common.kvs.Base(db=None)

Bases: object

class keystone.common.kvs.DictKvs

Bases: dict

delete(key)
set(key, value)

logging Module

Wrapper for built-in logging module.

keystone.common.logging.fail_gracefully(f)

Logs exceptions and aborts.

keystone.common.logging.log_debug(f)

manager Module

class keystone.common.manager.Manager(driver_name)

Bases: object

Base class for intermediary request layer.

The Manager layer exists to support additional logic that applies to all or some of the methods exposed by a service that are not specific to the HTTP interface.

It also provides a stable entry point to dynamic backends.

An example of a probable use case is logging all the calls.

policy Module

Common Policy Engine Implementation

class keystone.common.policy.Brain(rules=None, default_rule=None)

Bases: object

Implements policy checking.

add_rule(key, match)
check(match_list, target_dict, cred_dict)

Checks authorization of some rules against credentials.

Detailed description of the check with examples in policy.enforce().

Parameters:
  • match_list – nested tuples of data to match against
  • target_dict – dict of object properties
  • credentials_dict – dict of actor properties
Returns:

True if the check passes

classmethod load_json(data, default_rule=None)

Init a brain using json instead of a rules dictionary.

class keystone.common.policy.HttpBrain(rules=None, default_rule=None)

Bases: keystone.common.policy.Brain

A brain that can check external urls for policy.

Posts json blobs for target and credentials.

exception keystone.common.policy.NotAuthorized

Bases: exceptions.Exception

keystone.common.policy.enforce(match_list, target_dict, credentials_dict)

Enforces authorization of some rules against credentials.

Parameters:match_list – nested tuples of data to match against
The basic brain supports three types of match lists:
  1. rules

    looks like: (‘rule:compute:get_instance’,) Retrieves the named rule from the rules dict and recursively checks against the contents of the rule.

  2. roles

    looks like: (‘role:compute:admin’,) Matches if the specified role is in credentials_dict[‘roles’].

  3. generic

    (‘tenant_id:%(tenant_id)s’,) Substitutes values from the target dict into the match using the % operator and matches them against the creds dict.

Combining rules:

The brain returns True if any of the outer tuple of rules match and also True if all of the inner tuples match. You can use this to perform simple boolean logic. For example, the following rule would return True if the creds contain the role ‘admin’ OR the if the tenant_id matches the target dict AND the the creds contains the role ‘compute_sysadmin’:

{
    "rule:combined": (
        'role:admin',
        ('tenant_id:%(tenant_id)s', 'role:compute_sysadmin')
    )
}

Note that rule and role are reserved words in the credentials match, so you can’t match against properties with those names. Custom brains may also add new reserved words. For example, the HttpBrain adds http as a reserved word.

Parameters:target_dict – dict of object properties

Target dicts contain as much information as we can about the object being operated on.

Parameters:credentials_dict – dict of actor properties

Credentials dicts contain as much information as we can about the user performing the action.

:raises NotAuthorized if the check fails

keystone.common.policy.reset()

Clear the brain used by enforce().

keystone.common.policy.set_brain(brain)

Set the brain used by enforce().

Defaults use Brain() if not set.

serializer Module

Dict <–> XML de/serializer.

The identity API prefers attributes over elements, so we serialize that way by convention, with a few hardcoded exceptions.

class keystone.common.serializer.XmlDeserializer

Bases: object

walk_element(element)

Populates a dictionary by walking an etree element.

class keystone.common.serializer.XmlSerializer

Bases: object

populate_element(element, value)

Populates an etree with the given value.

keystone.common.serializer.from_xml(xml)

Deserialize XML to a dictionary.

keystone.common.serializer.to_xml(d, xmlns=None)

Serialize a dictionary to XML.

utils Module

class keystone.common.utils.Ec2Signer(secret_key)

Bases: object

Hacked up code from boto/connection.py

generate(credentials)

Generate auth string according to what SignatureVersion is given.

class keystone.common.utils.SmarterEncoder(skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, encoding='utf-8', default=None)

Bases: json.encoder.JSONEncoder

Help for JSON encoding dict-like objects.

default(obj)
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_output(*popenargs, **kwargs)

Run command with arguments and return its output as a byte string.

If the exit code was non-zero it raises a CalledProcessError. The CalledProcessError object will have the return code in the returncode attribute and output in the output attribute.

The arguments are the same as for the Popen constructor. Example:

>>> check_output(['ls', '-l', '/dev/null'])
'crw-rw-rw- 1 root root 1, 3 Oct 18  2007 /dev/null\n'

The stdout argument is not allowed as it is used internally. To capture standard error in the result, use stderr=STDOUT.

>>> check_output(['/bin/sh', '-c',
...               'ls -l non_existent_file ; exit 0'],
...              stderr=STDOUT)
'ls: non_existent_file: No such file or directory\n'
keystone.common.utils.check_password(password, hashed)

Check that a plaintext password matches hashed.

hashpw returns the salt value concatenated with the actual hash value. It extracts the actual salt if this value is then passed as the salt.

keystone.common.utils.find_config(config_path)

Find a configuration file using the given hint.

Parameters:config_path – Full or relative path to the config.
Returns:Full path of the config, if it exists.
keystone.common.utils.git(*args)
keystone.common.utils.hash_password(password)

Hash a password. Hard.

keystone.common.utils.import_class(import_str)

Returns a class from a string including module and class.

keystone.common.utils.import_object(import_str, *args, **kw)

Returns an object including a module or module and class.

keystone.common.utils.isotime(dt_obj)

Format datetime object as ISO compliant string.

Parameters:dt_obj – datetime.datetime object
Returns:string representation of datetime object
keystone.common.utils.ldap_check_password(password, hashed)
keystone.common.utils.ldap_hash_password(password)

Hash a password. Hard.

keystone.common.utils.read_cached_file(filename, cache_info, reload_func=None)

Read from a file if it has been modified.

Parameters:
  • cache_info – dictionary to hold opaque cache.
  • reload_func – optional function to be called with data when file is reloaded due to a modification.
Returns:

data from file

keystone.common.utils.trunc_password(password)

Truncate passwords to the MAX_PASSWORD_LENGTH.

keystone.common.utils.unixtime(dt_obj)

Format datetime object as unix timestamp

Parameters:dt_obj – datetime.datetime object
Returns:float

wsgi Module

Utility methods for working with WSGI servers.

class keystone.common.wsgi.Application

Bases: keystone.common.wsgi.BaseApplication

assert_admin(context)
class keystone.common.wsgi.BaseApplication

Bases: object

Base WSGI application wrapper. Subclasses need to implement __call__.

classmethod factory(global_config, **local_config)

Used for paste app factories in paste.deploy config files.

Any local configuration (that is, values under the [app:APPNAME] section of the paste config) will be passed into the __init__ method as kwargs.

A hypothetical configuration would look like:

[app:wadl] latest_version = 1.3 paste.app_factory = nova.api.fancy_api:Wadl.factory

which would result in a call to the Wadl class as

import nova.api.fancy_api fancy_api.Wadl(latest_version=‘1.3’)

You could of course re-implement the factory method in subclasses, but using the kwarg passing it shouldn’t be necessary.

class keystone.common.wsgi.ComposableRouter(mapper=None)

Bases: keystone.common.wsgi.Router

Router that supports use by ComposingRouter.

add_routes(mapper)

Add routes to given mapper.

class keystone.common.wsgi.ComposingRouter(mapper=None, routers=None)

Bases: keystone.common.wsgi.Router

class keystone.common.wsgi.Debug(application)

Bases: keystone.common.wsgi.Middleware

Helper class for debugging a WSGI application.

Can be inserted into any WSGI application chain to get information about the request and response.

static print_generator(app_iter)

Iterator that prints the contents of a wrapper string.

class keystone.common.wsgi.ExtensionRouter(application, mapper=None)

Bases: keystone.common.wsgi.Router

A router that allows extensions to supplement or overwrite routes.

Expects to be subclassed.

add_routes(mapper)
classmethod factory(global_config, **local_config)

Used for paste app factories in paste.deploy config files.

Any local configuration (that is, values under the [filter:APPNAME] section of the paste config) will be passed into the __init__ method as kwargs.

A hypothetical configuration would look like:

[filter:analytics] redis_host = 127.0.0.1 paste.filter_factory = nova.api.analytics:Analytics.factory

which would result in a call to the Analytics class as

import nova.api.analytics analytics.Analytics(app_from_paste, redis_host=‘127.0.0.1’)

You could of course re-implement the factory method in subclasses, but using the kwarg passing it shouldn’t be necessary.

class keystone.common.wsgi.Middleware(application)

Bases: keystone.common.wsgi.Application

Base WSGI middleware.

These classes require an application to be initialized that will be called next. By default the middleware will simply call its wrapped app, or you can override __call__ to customize its behavior.

classmethod factory(global_config, **local_config)

Used for paste app factories in paste.deploy config files.

Any local configuration (that is, values under the [filter:APPNAME] section of the paste config) will be passed into the __init__ method as kwargs.

A hypothetical configuration would look like:

[filter:analytics] redis_host = 127.0.0.1 paste.filter_factory = nova.api.analytics:Analytics.factory

which would result in a call to the Analytics class as

import nova.api.analytics analytics.Analytics(app_from_paste, redis_host=‘127.0.0.1’)

You could of course re-implement the factory method in subclasses, but using the kwarg passing it shouldn’t be necessary.

process_request(request)

Called on each request.

If this returns None, the next application down the stack will be executed. If it returns a response then that response will be returned and execution will stop here.

process_response(request, response)

Do whatever you’d like to the response, based on the request.

class keystone.common.wsgi.Request(environ, charset=(No Default), unicode_errors=(No Default), decode_param_names=(No Default), **kw)

Bases: webob.request.Request

class keystone.common.wsgi.Router(mapper)

Bases: object

WSGI middleware that maps incoming requests to WSGI apps.

class keystone.common.wsgi.Server(application, host=None, port=None, threads=1000)

Bases: object

Server class to manage multiple WSGI sockets and applications.

kill()
start(key=None, backlog=128)

Run a WSGI server with the given application.

wait()

Wait until all servers have completed running.

class keystone.common.wsgi.WritableLogger(logger, level=10)

Bases: object

A thin wrapper that responds to write and logs.

write(msg)
keystone.common.wsgi.render_exception(error)

Forms a WSGI response based on the current error.

keystone.common.wsgi.render_response(body=None, status=(200, 'OK'), headers=None)

Forms a WSGI response.