Table Of Contents

Previous topic

Fake Drivers

Next topic

Cloudpipe – Per Project Vpns

This Page

Psst... hey. You're reading the latest content, but it might be out of sync with code. You can read Nova 2011.1 docs or all OpenStack docs too.

Common and Misc Libraries

Libraries common throughout Nova or just ones that haven’t been categorized very well yet.

The nova.adminclient Module

The nova.context Module

RequestContext: context for requests that persist through all of nova.

class nova.context.RequestContext(user, project, is_admin=None, read_deleted=False, remote_address=None, timestamp=None, request_id=None)

Bases: object

RequestContext.elevated(read_deleted=False)

Return a version of this context with admin flag set.

classmethod RequestContext.from_dict(values)
RequestContext.project
RequestContext.to_dict()
RequestContext.user
nova.context.get_admin_context(read_deleted=False)

The nova.exception Module

Nova base exception handling, including decorator for re-raising Nova-type exceptions. SHOULD include dedicated exception logging.

exception nova.exception.ApiError(message='Unknown', code='ApiError')

Bases: nova.exception.Error

exception nova.exception.DBError(inner_exception)

Bases: nova.exception.Error

Wraps an implementation specific exception

exception nova.exception.Duplicate(message=None)

Bases: nova.exception.Error

exception nova.exception.Error(message=None)

Bases: exceptions.Exception

exception nova.exception.InstanceNotFound(message, instance_id)

Bases: nova.exception.NotFound

exception nova.exception.Invalid(message=None)

Bases: nova.exception.Error

exception nova.exception.InvalidContentType(message=None)

Bases: nova.exception.Error

exception nova.exception.InvalidInputException(message=None)

Bases: nova.exception.Error

exception nova.exception.NotAuthorized(message=None)

Bases: nova.exception.Error

exception nova.exception.NotEmpty(message=None)

Bases: nova.exception.Error

exception nova.exception.NotFound(message=None)

Bases: nova.exception.Error

exception nova.exception.ProcessExecutionError(stdout=None, stderr=None, exit_code=None, cmd=None, description=None)

Bases: exceptions.IOError

exception nova.exception.TimeoutException(message=None)

Bases: nova.exception.Error

exception nova.exception.VolumeNotFound(message, volume_id)

Bases: nova.exception.NotFound

nova.exception.wrap_db_error(f)
nova.exception.wrap_exception(f)

The nova.flags Module

Package-level global flags are defined here, the rest are defined where they’re used.

nova.flags.DECLARE(name, module_string, flag_values=<nova.flags.FlagValues instance at 0x863e6ac>)
nova.flags.DEFINE(*args, **kw)
nova.flags.DEFINE_bool(*args, **kw)
nova.flags.DEFINE_boolean(*args, **kw)
nova.flags.DEFINE_enum(*args, **kw)
nova.flags.DEFINE_flag(*args, **kw)
nova.flags.DEFINE_float(*args, **kw)
nova.flags.DEFINE_integer(*args, **kw)
nova.flags.DEFINE_list(*args, **kw)
nova.flags.DEFINE_multi_int(*args, **kw)
nova.flags.DEFINE_multistring(*args, **kw)
nova.flags.DEFINE_spaceseplist(*args, **kw)
nova.flags.DEFINE_string(*args, **kw)
class nova.flags.FlagValues(extra_context=None)

Bases: gflags.FlagValues

Extension of gflags.FlagValues that allows undefined and runtime flags.

Unknown flags will be ignored when parsing the command line, but the command line will be kept so that it can be replayed if new flags are defined after the initial parsing.

FlagValues.ClearDirty()
FlagValues.IsDirty(name)
FlagValues.ParseNewFlags()
FlagValues.Reset()
FlagValues.SetDirty(name)

Mark a flag as dirty so that accessing it will case a reparse.

FlagValues.WasAlreadyParsed()
class nova.flags.StrWrapper(context_objs)

Bases: object

Wrapper around FlagValues objects

Wraps FlagValues objects for string.Template so that we’re sure to return strings.

The nova.process Module

The nova.rpc Module

AMQP-based RPC. Queues have consumers and publishers. No fan-out support yet.

class nova.rpc.AdapterConsumer(connection=None, topic='broadcast', proxy=None)

Bases: nova.rpc.Consumer

Calls methods on a proxy object based on method and args

AdapterConsumer.receive(*args, **kwargs)
class nova.rpc.Connection(hostname=None, userid=None, password=None, virtual_host=None, port=None, pool=None, **kwargs)

Bases: carrot.connection.BrokerConnection

Connection instance object

classmethod Connection.instance(new=True)

Returns the instance

classmethod Connection.recreate()

Recreates the connection instance

This is necessary to recover from some network errors/disconnects

class nova.rpc.Consumer(*args, **kwargs)

Bases: carrot.messaging.Consumer

Consumer base class

Contains methods for connecting the fetch method to async loops

Consumer.attach_to_eventlet()

Only needed for unit tests!

Consumer.fetch(no_ack=None, auto_ack=None, enable_callbacks=False)

Wraps the parent fetch with some logic for failed connections

class nova.rpc.DirectConsumer(connection=None, msg_id=None)

Bases: nova.rpc.Consumer

Consumes messages directly on a channel specified by msg_id

class nova.rpc.DirectPublisher(connection=None, msg_id=None)

Bases: nova.rpc.Publisher

Publishes messages directly on a channel specified by msg_id

class nova.rpc.FanoutAdapterConsumer(connection=None, topic='broadcast', proxy=None)

Bases: nova.rpc.AdapterConsumer

Consumes messages from a fanout exchange

class nova.rpc.FanoutPublisher(topic, connection=None)

Bases: nova.rpc.Publisher

Publishes messages to a fanout exchange.

class nova.rpc.Publisher(connection, exchange=None, routing_key=None, **kwargs)

Bases: carrot.messaging.Publisher

Publisher base class

exception nova.rpc.RemoteError(exc_type, value, traceback)

Bases: nova.exception.Error

Signifies that a remote class has raised an exception

Containes a string representation of the type of the original exception, the value of the original exception, and the traceback. These are sent to the parent as a joined string so printing the exception contains all of the relevent info.

class nova.rpc.TopicAdapterConsumer(connection=None, topic='broadcast', proxy=None)

Bases: nova.rpc.AdapterConsumer

Consumes messages on a specific topic

class nova.rpc.TopicPublisher(connection=None, topic='broadcast')

Bases: nova.rpc.Publisher

Publishes messages on a specific topic

nova.rpc.call(context, topic, msg)

Sends a message on a topic and wait for a response

nova.rpc.cast(context, topic, msg)

Sends a message on a topic without waiting for a response

nova.rpc.fanout_cast(context, topic, msg)

Sends a message on a fanout exchange without waiting for a response

nova.rpc.generic_response(message_data, message)

Logs a result and exits

nova.rpc.msg_reply(msg_id, reply=None, failure=None)

Sends a reply or an error on the channel signified by msg_id

failure should be a sys.exc_info() tuple.

nova.rpc.send_message(topic, message, wait=True)

Sends a message for testing

The nova.server Module

The nova.test Module

Base classes for our unit tests. Allows overriding of flags for use of fakes, and some black magic for inline callbacks.

class nova.test.TestCase(methodName='runTest')

Bases: unittest.case.TestCase

Test case base class for all unit tests

TestCase.assertDictListMatch(L1, L2)

Assert a list of dicts are equivalent

TestCase.assertDictMatch(d1, d2)

Assert two dicts are equivalent.

This is a ‘deep’ match in the sense that it handles nested dictionaries appropriately.

NOTE:

If you don’t care (or don’t know) a given value, you can specify the string DONTCARE as the value. This will cause that dict-item to be skipped.
TestCase.flags(**kw)

Override flag variables for a test

TestCase.reset_flags()

Resets all flag variables for the test. Runs after each test

TestCase.setUp()

Run before each test method to initialize test environment

TestCase.start_service(name, host=None, **kwargs)
TestCase.tearDown()

Runs after each test method to finalize/tear down test environment.

nova.test.skip_if_fake(func)

Decorator that skips a test if running in fake mode

The nova.twistd Module

Twisted daemon helpers, specifically to parse out gFlags from twisted flags, manage pid files and support syslogging.

class nova.twistd.FlagParser(parser)

Bases: object

FlagParser.Parse(s)
class nova.twistd.TwistdServerOptions(*a, **kw)

Bases: twisted.scripts._twistd_unix.ServerOptions

TwistdServerOptions.parseArgs(*args)
nova.twistd.WrapTwistedOptions(wrapped)
nova.twistd.serve(filename)
nova.twistd.stop(pidfile)

Stop the daemon

The nova.utils Module

System-level utilities and helper functions.

class nova.utils.LazyPluggable(pivot, **backends)

Bases: object

A pluggable backend loaded lazily based on some value.

class nova.utils.LoopingCall(f=None, *args, **kw)

Bases: object

LoopingCall.start(interval, now=True)
LoopingCall.stop()
LoopingCall.wait()
exception nova.utils.LoopingCallDone(retvalue=True)

Bases: exceptions.Exception

The poll-function passed to LoopingCall 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 LoopingCall.wait()

nova.utils.abspath(s)
nova.utils.advance_time_delta(timedelta)

Advance overriden time using a datetime.timedelta.

nova.utils.advance_time_seconds(seconds)

Advance overriden time by seconds.

nova.utils.check_isinstance(obj, cls)

Checks that obj is of type cls, and lets PyLint infer types

nova.utils.clear_time_override()

Remove the overridden time.

nova.utils.debug(arg)
nova.utils.default_flagfile(filename='nova.conf')
nova.utils.dumps(value)
nova.utils.execute(*cmd, **kwargs)
nova.utils.fetchfile(url, target)
nova.utils.flatten_dict(dict_, flattened=None)

Recursively flatten a nested dictionary

nova.utils.generate_mac()
nova.utils.generate_password(length=20, symbols='23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz')

Generate a random password from the supplied symbols.

Believed to be reasonably secure (with a reasonable password length!)

nova.utils.generate_uid(topic, size=8)
nova.utils.get_from_path(items, path)

Returns a list of items matching the specified path. Takes an XPath-like expression e.g. prop1/prop2/prop3, and for each item in items, looks up items[prop1][prop2][prop3]. Like XPath, if any of the intermediate results are lists it will treat each list item individually. A ‘None’ in items or any child expressions will be ignored, this function will not throw because of None (anywhere) in items. The returned list will contain no None values.

nova.utils.get_my_linklocal(interface)
nova.utils.import_class(import_str)

Returns a class from a string including module and class

nova.utils.import_object(import_str)

Returns an object including a module or module and class

nova.utils.is_older_than(before, seconds)

Return True if before is older than seconds

nova.utils.isotime(at=None)

Returns iso formatted utcnow.

nova.utils.last_octet(address)
nova.utils.loads(s)
nova.utils.map_dict_keys(dict_, key_map)

Return a dictionary in which the dictionaries keys are mapped to new keys.

nova.utils.novadir()
nova.utils.parse_isotime(timestr)

Turn an iso formatted time back into a datetime

nova.utils.parse_mailmap(mailmap='.mailmap')
nova.utils.partition_dict(dict_, keys)

Return two dicts, one containing only keys the other containing everything but keys

nova.utils.runthis(prompt, *cmd, **kwargs)
nova.utils.set_time_override(override_time=datetime.datetime(2011, 10, 25, 15, 23, 9, 507613))

Override utils.utcnow to return a constant time.

nova.utils.ssh_execute(ssh, cmd, process_input=None, addl_env=None, check_exit_code=True)
nova.utils.str_dict_replace(s, mapping)
nova.utils.subset_dict(dict_, keys)

Return a dict that only contains a subset of keys

nova.utils.synchronized(name, external=False)

Synchronization decorator

Decorating a method like so: @synchronized(‘mylock’) def foo(self, *args):

...

ensures that only one thread will execute the bar method at a time.

Different methods can share the same lock: @synchronized(‘mylock’) def foo(self, *args):

...

@synchronized(‘mylock’) def bar(self, *args):

...

This way only one of either foo or bar can be executing at a time.

The external keyword argument denotes whether this lock should work across multiple processes. This means that if two different workers both run a a method decorated with @synchronized(‘mylock’, external=True), only one of them will execute at a time.

nova.utils.to_global_ipv6(prefix, mac)
nova.utils.to_mac(ipv6_address)
nova.utils.to_primitive(value)
nova.utils.utcnow()

Overridable version of datetime.datetime.utcnow.

nova.utils.utcnow_ts()

Timestamp version of our utcnow function.

nova.utils.utf8(value)

Try to turn a string into utf-8 if possible.

Code is directly from the utf8 function in http://github.com/facebook/tornado/blob/master/tornado/escape.py

nova.utils.vpn_ping(address, port, timeout=0.05, session_id=None)

Sends a vpn negotiation packet and returns the server session.

Returns False on a failure. Basic packet structure is below.

Client packet (14 bytes)::
0 1 8 9 13
x cli_id  

x = packet identifier 0x38 cli_id = 64 bit identifier ? = unknown, probably flags/padding

Server packet (26 bytes)::
0 1 8 9 13 14 21 2225
x srv_id   cli_id  

x = packet identifier 0x40 cli_id = 64 bit identifier ? = unknown, probably flags/padding bit 9 was 1 and the rest were 0 in testing

nova.utils.xhtml_escape(value)

Escapes a string so it is valid within XML or XHTML.

Code is directly from the utf8 function in http://github.com/facebook/tornado/blob/master/tornado/escape.py

The nova.validate Module

The nova.wsgi Module

Utility methods for working with WSGI servers

class nova.wsgi.Application

Bases: object

Base WSGI application wrapper. Subclasses need to implement __call__.

classmethod Application.factory(global_config, **local_config)

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

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 nova.wsgi.Controller

Bases: object

WSGI app that reads routing information supplied by RoutesMiddleware and calls the requested action method upon itself. All action methods must, in addition to their normal parameters, accept a ‘req’ argument which is the incoming wsgi.Request. They raise a webob.exc exception, or return a dict which will be serialized by requested content type.

Controller.get_default_xmlns(req)

Provide the XML namespace to use if none is otherwise specified.

class nova.wsgi.Debug(application)

Bases: nova.wsgi.Middleware

Helper class that can be inserted into any WSGI application chain to get information about the request and response.

static Debug.print_generator(app_iter)

Iterator that prints the contents of a wrapper string iterator when iterated.

class nova.wsgi.Middleware(application)

Bases: nova.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 Middleware.factory(global_config, **local_config)

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

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.

Middleware.process_request(req)

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.

Middleware.process_response(response)

Do whatever you’d like to the response.

class nova.wsgi.Request(environ=None, environ_getter=None, charset=(No Default), unicode_errors=(No Default), decode_param_names=(No Default), **kw)

Bases: webob.request.Request

Request.best_match_content_type()

Determine the most acceptable content-type based on the query extension then the Accept header

Request.get_content_type()
class nova.wsgi.Router(mapper)

Bases: object

WSGI middleware that maps incoming requests to WSGI apps.

class nova.wsgi.Serializer(metadata=None, default_xmlns=None)

Bases: object

Serializes and deserializes dictionaries to certain MIME types.

Serializer.deserialize(datastring, content_type)

Deserialize a string to a dictionary.

The string must be in the format of a supported MIME type.

Serializer.get_deserialize_handler(content_type)
Serializer.serialize(data, content_type)

Serialize a dictionary into a string of the specified content type.

class nova.wsgi.Server(threads=1000)

Bases: object

Server class to manage multiple WSGI sockets and applications.

Server.start(application, port, host='0.0.0.0', backlog=128)

Run a WSGI server with the given application.

Server.wait()

Wait until all servers have completed running.

class nova.wsgi.WritableLogger(logger, level=10)

Bases: object

A thin wrapper that responds to write and logs.

WritableLogger.write(msg)
nova.wsgi.load_paste_app(filename, appname)

Builds a wsgi app from a paste config, None if app not configured.

nova.wsgi.load_paste_configuration(filename, appname)

Returns a paste configuration dict, or None.

nova.wsgi.paste_config_file(basename)

Find the best location in the system for a paste config file.

The search for a paste config file honors FLAGS.state_path, which in a version checked out from bzr will be the nova directory in the top level of the checkout, and in an installation for a package for your distribution will likely point to someplace like /etc/nova.

This method tries to load places likely to be used in development or experimentation before falling back to the system-wide configuration in /etc/nova/.

  • Current working directory
  • the etc directory under state_path, because when working on a checkout from bzr this will point to the default
  • top level of FLAGS.state_path, for distributions
  • /etc/nova, which may not be diffrerent from state_path on your distro

Tests

The declare_flags Module

The fake_flags Module

The flags_unittest Module

The process_unittest Module

The real_flags Module

The rpc_unittest Module

The runtime_flags Module

The twistd_unittest Module

The validator_unittest Module