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) for a full listing. you can also use pip to install the python module minimega. 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
explanation 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])
Authors
The minimega authors
20 August 2018