Ravello Python SDK

Overview

The Ravello Python SDK is a small SDK for using the Ravello service from the Python programming language. The focus is on providing a small set of bindings that doesn’t have any external dependencies. Some features are:

  • Supports Python 2.6, 2.7 and 3.3+.
  • No dependencies outside the standard library.
  • A minimal binding without a client-side object model. Objects and represented as simple dictionaries.
  • Should work on POSIX, Windows and Mac OSX.

Because there is no client-side object model, you should also read the Ravello API Reference. All object fields are documented there.

API

The Ravello SDK is implemented by the module ravello_sdk. The module is safe to be imported into your namespace:

from ravello_sdk import *

The module has the following contents:

Exceptions

class RavelloError

Exception used by RavelloClient.

Functions

random_luid()

Return a new random local ID.

update_luids(obj)

Update the locally unique IDs in obj.

The object must be a dict, or a list of dicts.

This replaces all “id” keys (directly or indirectly) below obj with an new random ID generated by random_luid(). This function is useful when adding VMs images to a new or existing application. Every entity in an application’s design must have a unique local ID. When you’re adding multiple VMs based on the same image, the IDs are copied and you need to use this function to ensure the VMs have unique local IDs again.

application_state(app)

Return the consolidated state for application app.

The app parameter must be a dict as returned by get_application().

The consolidated state for an application is the set of distinct states for its VMs. As special cases, None is returned if there are no VMs, and the single state is returned if there is exactly one state.

new_name(existing, prefix)

Return a name that is not in existing.

The existing parameter must be a sequence of strings, or dicts with a “name” key. It the latter case, it is typically a list returned by one of the “get all” functions like RavelloClient.get_applications() or :meth:~RavelloClient.get_blueprints`.

The unique name is generated by appending a number to prefix.

Classes

class RavelloClient(username=None, password=None, url=None, timeout=None, retries=None)

A client for the Ravello API.

The client is a thin wrapper around the Ravello RESTful API. The client manages a single HTTPS connection, and implements login, redirect and retry functionality. A single generic request() method is provided to issue API requests.

On top of this, most existing RESTful API calls are mapped as methods on this class. These mapped methods are simple wrappers around the generic request() method. Some general comments on this mapping:

  • The calls are named “<method>_<resource>”, for example “create_keypair()” and “get_blueprints()”. A method is always an English verb, while a resource is can be a singular or plural Englush noun.
  • The standard methods are “get”, “create”, “update” and “delete”. Not all methods are defined for all resources, and some resources have additional methods.
  • The available resources are “application”, “blueprint”, “image”, “keypair” and “vm”. The plural versions of these exist as well.
  • There is no client-side object model. The return value from any API call is simply the parsed JSON response.
  • Resources are returned as a dict or a list of dicts. A dict always represents a single object, and its key/value pairs correspond to the object’s attributes. Lists always represents multiple objects.
  • Objects are identifed by a numeric ID, which is always the key “id”.
  • All methods that accept an object ID either accept this parameter as a simple Python int, or alternatively as a dict with an “id” key containing the ID. In the latter case, the dict is typically returned previsouly by another API call.
  • HTTP response codes in the 4xx or 5xx range are considered errors, and are turned into RavelloError exceptions (except for 404 which results in a response of None).
url

The parsed URL of the API endpoint, which is a urllib.parse.SplitResult instance.

connected

Whether or not the client is connected to the API.

have_credentials

Whether or not credentials are available.

logged_in

Whether or not the client is logged in.

user_info

Return information about the current logged-in user.

connect(url=None)

Connect to the API.

It is not mandatory to call this method. If this method is not called, the client will automatically connect when required.

login(username=None, password=None)

Login to the API.

This method performs a login to the API, and store the resulting authentication cookie in memory.

It is not mandatory to call this method. If this method is not called, the client will automatically login when required.

logout()

Logout from the API. This invalidates the authentication cookie.

close()

Close the connection to the API.

request(method, path, entity=None, headers=None)

Issues a request to the API.

The parsed entity is returned, or a RavelloError exception is raised on error.

This method can be used in case a certain API call has not yet been added as a method.

reload(obj)

Reload the object obj.

The object must have been returned by the API, and must be a dict with an "_href" key.

wait_for(obj, cond, timeout=None)

Wait for a condition on obj to become true.

The object obj must be reloadable. See reload() for more details.

The condition cond must be a dict or a callable. If it is a dict, it lists the keys and values that the object must have. If it is a callable, it will be called with the object as an argument, and it should return True or False.

The timeout argument specifies the total time to wait. If not specified, it will default to the system call timeout passed to the constructor.

If the condition does not become true before the timeout, a RavelloError exception is raised.

get_application(app)

Return the application with ID app, or None if it does not exist.

get_applications(filter=None)

Return a list with all applications.

The filter argument can be used to return only a subset of the applications. See the description of the cond argument to wait_for().

create_application(app)

Create a new application.

The app parameter must be a dict describing the application to create.

The new application is returned.

update_application(app)

Update an existing application.

The app parameter must be the updated application. The way to update an application (or any other resource) is to first retrieve it, make the updates client-side, and then use this method to make the update.

The updated application is returned.

delete_application(app)

Delete an application with ID app.

publish_application(app, req={})

Publish the application with ID app.

The req parameter, if provided, must be a dict with publish parameters.

start_application(app, req={})

Start the application with ID app.

The req parameter, if provided, must be a dict with start parameters.

stop_application(app, req={})

Stop the application with ID app.

The req parameter, if provided, must be a dict with stop parameters.

restart_application(app, req={})

Restart the application with ID app.

The req parameter, if provided, must be a dict with restart parameters.

publish_application_updates(app)

Publish updates for the application with ID app.

set_application_expiration(app, req)

Set the expiration for the application with ID app.

The req parameter must be a dict describing the new expiration.

start_vm(app, vm)

Start the VM with ID vm in the application with ID app.

stop_vm(app, vm)

Stop the VM with ID vm in the application with ID app.

restart_vm(app, vm)

Restart the VM with ID vm in the application with ID app.

get_vnc_url(app, vm)

Get the VNC URL for the VM with ID vm in the application with ID app.

get_blueprint(bp)

Return the blueprint with ID bp, or None if it does not exist.

get_blueprints(filter=None)

Return a list with all blueprints.

The filter argument can be used to return only a subset of the applications. See the description of the cond argument to wait_for().

create_blueprint(bp)

Create a new blueprint.

The bp parameter must be a dict describing the blueprint to create.

The new blueprint is returned.

delete_blueprint(bp)

Delete the blueprint with ID bp.

get_image(img)

Return the image with ID img, or None if it does not exist.

get_images(filter=None)

Return a list with all images.

The filter argument can be used to return only a subset of the images. See the description of the cond argument to wait_for().

update_image(img)

Update an existing image.

The img parameter must be the updated image. The updated image is returned.

delete_image(img)

Delete the image with ID img.

get_keypair(kp)

Return the keypair with ID kp, or None if it does not exist.

get_keypairs(filter=None)

Return a list with all keypairs.

The filter argument can be used to return only a subset of the keypairs. See the description of the cond argument to wait_for().

create_keypair(kp)

Create a new keypair.

The kp parameter must be a dict describing the keypair to create.

The new blueprint is returned.

update_keypair(kp)

Update an existing keypair.

The kp parameter must be the updated keypair. The updated keypair is returned.

delete_keypair(kp)

Delete the keypair with ID kp.

generate_keypair()

Generate a new keypair and return it.

Table Of Contents