XEN Bridge

An object-oriented Xen API for python

Tested on XCP-ng, but should also work on XenServer

Install from pypi using pip install xen-bridge

Usage

from xenbridge import XenConnection

xen = XenConnection('http://XEN_HOSTNAME', 'root', 'password')

xoa_vm = xen.VM.get_by_uuid('UUID_OF_VM')
# Or by name-label:
# xoa_vm = xen.VM.get_by_name_label('XOA')[0]

print(f'{xoa_vm.name_label} ({xoa_vm.uuid})')
print(f'VM is a template: {xoa_vm.is_a_template}')
xoa_vm.name_description = 'This is a VM'
xoa_vm.start()      # Spin up the VM

Exceptions

While calling API methods, XEN might return an error. When this happens, a XenError is raised. When catching the exception, the error code can be accessed through the error_code attribute

# Assuming VM is already running:
try:
    xoa_vm.start()      # Should throw an error
except xenbridge.XenError as e:
    print(e.error_code)     # Prints 'VM_BAD_POWER_STATE'

How it works

Firstly, xenboject.py defines some helper functions and baseclasses for the endpoints that do the actual work of calling the XMLRPC API and casting the data to the corresponding types.

For each class, there is a file corresponding to that class - for example, vm.py. In here, a class that defines the methods and properties can be found. All methods are wrapped using the @XenMethod decorator that copies the function's signature and replaces its functionality.

class VM(XenObject):
    @XenMethod
    def start(self, start_paused: bool, force: bool) -> None:
        """Start the specified VM.  This function can only be called with the VM is in the
        Halted State."""
    power_state: VmPowerState = XenProperty(XenProperty.READONLY)

As the API responds with a string for numbers, enums and Xen objects, the return type annotations are used to cast the objects to the correct type.

The XenConnection class is the object that is used to interact with the API

Missing methods

All API methods are generated from the XenAPI documentation using docscraper.py. If there is a method that is missing, you can either:

• Add it to the corresponding class in the module yourself
• Call it using the class's call(methodname, *args) method and manually cast it to the correct data type