Reference ========= :mod:`rhev` -- API Access ------------------------- .. module:: rhev Exceptions ^^^^^^^^^^ Most errors in Python-RHEV are reported as exceptions. All exceptions derived from the :exc:`Error ` class. .. exception:: Error Base class for all errors. .. exception:: ParseError Could not parse a response generated by the API. .. exception:: ConnectionError Could not connect to the API. .. exception:: IllegalMethod The operation is not available for the specified resource or collection. .. exception:: NotFound The resource or collection was not found. .. exception:: IllegalAction The action is not available for the specified resource. .. exception:: ResponseError The response is not what was excpected. .. exception:: Fault A fault was returned. .. exception:: ActionError An action failed. Logging ^^^^^^^ Python-RHEV uses the standard Python :mod:`logging` facility to output diagnostic messages. To enable debugging output, you can use the following example code:: import logging logging.basicConfig() logger = logging.getLogger('rhev') logger.setLevel(logging.DEBUG) The :class:`Connection ` class ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The connection class is the main class in the Python-RHEV. All interactions with the RESTful API go through instances of this class. .. class:: Connection .. attribute:: retries Class attribute that defines the number of times a request is retried in case of a transient error. The default value is 5. .. attribute:: verbosity Class attribute that sets the verbosity by which debug messages are logged. The default value is 1. A value of 10 means be maximally verbose. .. attribute:: url Instance attribute that contains the current URL. .. attribute:: username Instance attribute containing the current user name. .. attribute:: password Instance attribute containing the current password. .. attribute:: scheme Instance attribute containing the URL scheme that is currently in use. Possible values are "http" or "https". This value is available after :meth:`connect()` has been called. .. attribute:: entrypoint Instance attribute containing the relative path of the entry point URL. This value is available after :meth:`connect()` has been called. .. method:: __init__(url=None, username=None, password=None) Create a new connection object. If the *url*, *username* or *password* arguments are provided, this will set the default connection details. The constructor only prepares the connection. No connection will be made. .. method:: connect(url=None, username=None, password=None) Open a TCP/IP connection to the API. This call does not yet authenticate or retrieve a resource. The *url*, *username* and *password* arguments specify the connection details. If they are not provided, the default connection details are used. Calling ``connect()`` is not mandatory. If a connection is needed, a connection will be made automatically. .. method:: close() Close the connection to the API. .. method:: ping() Test the connection by retrieving the API entry point. .. method:: getall(typ, base=None, detail=None, filter=None, \*\*query) Get resources from a collection. The result is returned as a collection instance. The *typ* argument specifies which collection to fetch. It must be a resource instance or a string identifying the relationship name. In case of sub-collections, *base* must be a resource instance that specifies the resource relative to which the collection exists. The *detail* parameter, if specified, must contain a string specifying the detail level of the response. If the *\*\*query* keyword arguments are provided, then instead of simply returning all resources from the collection, a search operation is performed. The keyword arguments are interpreted as follows. If a keyword argument corresponds to a URL template variable, then it provides the value for that template variable. For example, the query for a search is normally specified by a "search" URL template variable. If, after URL template variable expansion, variables remain, and if no "search" keyword argument was provided, then an AND query is constructed that is passed into the "search" URL template variable, if available. This allows a very tight specification e.g. when searching by name using ``getall(schema.VM, name='myvm'). The *filter* keyword argument specifies an optional filter. This must contain a dictionary of the form {'foo.bar': 'value'}, where "foo.bar" is the full attribute name to filter on and "value" is the value to filter for. Value can contain the "*" and "?" wild cards. The difference between filtering and searching is that search is implemented by the API itself, while filtering is done afterwards on the client. This means that for searching is more efficient than filtering. Filters are still useful because searching is not available for all collections, and even if searching is available, not all attributes can be searched on. .. method:: get(typ, id=None, base=None, detail=None, filter=None, \*\*query) Return a single resource from a collection. The *typ* argument specifies the type to return, see :meth:`getall()` for a description. The *id* argument, if specified, contains the ID of the object to retrieve. The *base*, *detail*, *filter* and *\*\*query* arguments are as described for :meth:`getall()`. .. method:: reload(resource, detail=None) Reloads *resource*, which must be a resource instance. If *detail* is specified, the resource is reloaded at that detail level. This updates the resource in place, in other words, *resource* itself is modified. This call also return the resource. .. method:: create(resource, base=None) Create a new resource. The *resource* argument specifies the resource to create, and must be a resource instance. The *base* argument, if provided, specifies the resource relative to which the collection exists in which the resource is to be created. By default, resources are created relative to the API entry point. .. method:: update(resource) Update the resource specified in *resource*. .. method:: delete(resource, base=None, data=None) Delete the resource specified by *resource*. If *base* is provided, it specifies a resource relative to which the collection exists from which the resource is to be deleted. If *data* is provided, it must be a resource instance of the same type as *resource*, that specifies optional parameters for the delete operation. .. method:: action(resource, action, data=None) Execute an action. The action named *action* is executed on the resource indicated by *resource*. If *data* is provided, it must be an instance of :class:`Action ` that is used to provide parameters for the action. .. method:: api() Returns the API entry point. This is a short hand for ``get(schema.API)``. .. method:: capabilities() Return the Capabilities resource. This is a short hand for ``get(schema.Capabilities)``. .. method:: wait_for_status(resource, status, timeout=None) Wait until *resource* enters a certain state. The state of a resource is the value of the ``state.status`` attribute. The *status* argument can be a string or a sequence of strings. In the latter case, any of the provides statuses will match. If *timeout* is specified, wait for no longer than this amount of seconds. The default is to wait indefinitely. As a special case, a *status* of None can be provided to wait until the resource has been deleted. .. method:: get_methods(obj, base=None) Return a list of methods (HTTP methods) that are available for the resource or collection *obj*. The *obj* parameter can be a resource instance, a resource class, or a collection class. In the latter two cases, *base* can be provided to specify a base. .. method:: get_actions(obj) Return a list of actions that are available for the resource or collection *obj*, which must be a resource or collection instance. .. method:: get_links(obj): Return a list of links that are available for the resource or collection *obj*, which must be a resource or collection instance. :mod:`rhev.schema` -- Binding Types ----------------------------------- The :py:mod:`rhev.schema` module contains functionality to query, create and modify binding types. Binding types are Python classes that correspond to the collections or resources in the Red Hat Enterprise Virtualization RESTful API. The table below lists the available top-level types. Top-level types correspond directly with either a resource or a collection in the RESTful API. Technically these are auto-generated from "complexType" definitions that are defined in the XMLSchema that describes the API. ============= =============== ======================================= Resource Type Collection Type Description ============= =============== ======================================= API N/A The API entry point Capabilities N/A The capilities resource DataCenter DataCenters A data center Cluster Clusters A cluster within a data center StorageDomain StorageDomains A storage domain Network Networks A virtual network Host Hosts A physical host HostNIC HostNics A physical NIC on a physical host Storage HostStorage Available block storage on a host VM VMs A virtual machine NIC Nics A virtual NIC of a virtual machine Disk Disks A virtual disk of a virtual machine CdRom CdRoms A virtual CD-ROM of a virtual machine Floppy Floppies A virtual floppy of a virtual machine Snapshot Snapshots A snapshot of a virtual disk File Files A file available from a storage domain Statistic Statistics Statistics Template Templates A virtual machine template VmPool VmPools A pool of virtual machines User Users A user Role Roles A user role Event Events An event Tag Tags A tag Action Actions Used to provide input to actions ============= =============== ======================================= All resource types are derived from the BaseResource class, while collections are derived from BaseCollection. Functions ^^^^^^^^^ The following functions are avaialble. .. function:: type_info(key, base=None) This function returns type information for a type identified by *key*. The *key* argument must be either a resource type, a collection type, or a relatioship name. The return value is tuple containing (resourcetype, collectiontype, singular, plural). The resource and collection types are the types corresponding to the type's resource and collection. The singular and plural elements are strings referring to a singular and a plural name for the type. The plural name is identical to the relationship name. .. function:: get_xml_schema() Return a parsed elementtree of the API's XMLSchema definition. This uses a version of the schema that was included at build time as part of the Python bindings, and may therefore be out of date. .. function:: new(type, \*args, \*\*kwargs) Create a new instance of a binding type. .. function:: ref(obj) Create a reference to the object in *obj*. This creates a copy of the object, and then only sets the "id" attribute. This copy can be used in certain operations that expect only a reference to an object instead of a full representation. .. function:: href(obj): The same as :func:`ref()` but also sets "href". .. function:: update(obj, upd) Update the object *obj* with all attributes of *upd* that are not None. The parameters *obj* and *upd* need to be instances of the same binding type. .. function:: copy(obj) Return a shallow copy of the object *obj*. The attributes are shared between the old and the new instance. .. function:: create_from_xml(s) Parse an XML string and return an instance of a binding type. This will raise a ParseError in case the XML cannot be parsed, or in case it corresponds to an unknown or illegal binding type. .. function:: attributes(obj) Return an interator that enumerates all attributes of the object *obj*. .. function:: subtype(prop) Return the correct binding type for an object attribute. The parameter *prop* must be an attribute of a binding class. Object Interface ^^^^^^^^^^^^^^^^ Certain utility methods are provided on the :class:`BaseResource` and :class:`BaseCollection` classes. These methods are available to all resource and collection instances, respectively. This allows the user to work with resources and collections a more object oriented way. .. class:: BaseResource .. method:: __getattr__(name) Augments basic attribute access. Users can use the standard dot ('.') attribute access operator to get acccess to actions and related sub-collections, in addition to the data attributes. For example, if a VM instance "vm" has a "start" action, then the following will work:: vm.start() .. method:: reload() Reload the object. This re-fetches all information from the API. .. method:: create(resource) Create a dependent resource to this resource. .. method:: update() Sync back the object to the API. This makes all attribute modifications that were made on the object persistent. .. method:: delete(data=None) Deletes the object. If the DELETE operation takes input, then that can be passed in as *data*. .. method:: wait_for_status(status, timeout=None) Wait for this object to enter *status*. This uses an exponential backoff polling loop. The *timeout* parameter specifies the number of seconds to wait at most. If no timeout is specified, this waits indefinitely. .. class:: BaseCollection .. method:: __getitem__(i) Returns the i'th element of the collection. .. method:: __len__() Return the number of resources in the collection. .. method:: __iter__() Iterate over all resources in the collection.