Python bindings¶

Introduction¶

minimega includes Python bindings for its CLI that interact with minimega using the domain socket. These bindings are automatically generated and allow the user to drive minimega with Python scripts.

General Usage¶

The pyapigen tool generates minimega.py which can be imported into scripts. The Python bindings include docstrings for every minimega command -- see help(minimega) or the generated Python API reference for a full listing. Here's a simple example of a script to launch 10 VMs, display their info, and then kill them:

import minimega

mm = minimega.connect(debug=True)

print 'launching vms'
mm.vm_launch_kvm(10)

print 'vm info:'
minimega.print_rows(mm.vm_info())

print 'starting vms'
mm.vm_start('all')

print 'vm info:'
minimega.print_rows(mm.vm_info())

print 'killing vms'
mm.vm_kill('all')

print 'flushing vms'
mm.vm_flush()

The connect method wraps minimega.minimega.__init__:

help(minimega.connect):

connect(path='/tmp/minimega/minimega', raise_errors=True, debug=False, namespace=None, timeout=60)
    Connect to the minimega instance with UNIX socket at <path> and return
    a new minimega API object. See help(minimega.minimega) for an
    explaination of the other parameters.

help(minimega.minimega.__init__):

__init__(self, path, raise_errors, debug, namespace, timeout) unbound minimega.minimega method
    Connects to the minimega instance with UNIX socket at <path>. If
    <raise_errors> is set, the Python APIs will raise an Exception whenever
    minimega returns a response with an error. If <debug> is set, debugging
    information will be printed. The <namespace> parameter allows you to
    "bind" the minimega object to a particular namespace (see
    help(minimega.minimega.namespace) for more info on namespaces). The
    <timeout> parameter allow you to set a command timeout.

By default, the domain socket is only read/writable by root so the Python script must run as root (or the domain socket can be chmod'd appropriately).

Running commands¶

As shown above, the Python bindings include a print_rows function that reads all the responses from a minimega command. Due to the serial nature of the minimega connection, all responses must be read before another command can be issued. By default, commands return the first response and set a flag if there are more responses to read (resp['More']). If More is true, users can call streamResponses on the minimega instance which returns a generator for additional responses. The helper, minimega.discard, can be used to discard these if no action is required in the Python script (and errors are checked via raise_errors).

All commands have arguments based on the underlying CLI which are checked by the Python bindings. If an argument is invalid, a ValueError will be raised with a description of the error.

namespaces¶

The Python bindings support namespaces in several ways. First, users may specify a namespace when connecting to minimega which runs all commands from that connection in that namespace. Second, users can use with statements to run commands in a particular namespace:

mm = minimega.connect()
with mm.namespace("foo") as mm:
    mm.vm_launch_kvm(1)

with mm.namespace("foo") as mm:
    with mm.namespace("bar") as mm2:
        for resp in mm.vm_info():
            for row in resp.get("Tabular", []) or []:
                mm2.vm_launch_kvm(row[1])