mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-07-06 09:55:46 +00:00
a7f0a3a272
Convert the simple example to Python 3 syntax:
- print() is a function
- do not use bare except
- libvirt.open*() does not return None but raises an exception
The referenced source for the example was removed with
5bb2a245ab
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: Philipp Hahn <hahn@univention.de>
73 lines
3.9 KiB
XML
73 lines
3.9 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE html>
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<body>
|
|
<h1>Python API bindings</h1>
|
|
|
|
<p>The Python binding should be complete and are mostly automatically
|
|
generated from the formal description of the API in xml. The bindings are
|
|
articulated around 2 classes <code>virConnect</code> and virDomain mapping to
|
|
the C types. Functions in the C API taking either type as argument then
|
|
becomes methods for the classes, their name is just stripped from the
|
|
virConnect or virDomain(Get) prefix and the first letter gets converted to
|
|
lower case, for example the C functions:</p>
|
|
<p>
|
|
<code>int <a href="html/libvirt-libvirt-domain.html#virConnectNumOfDomains">virConnectNumOfDomains</a>
|
|
(virConnectPtr conn);</code>
|
|
</p>
|
|
<p>
|
|
<code>int <a href="html/libvirt-libvirt-domain.html#virDomainSetMaxMemory">virDomainSetMaxMemory</a>
|
|
(virDomainPtr domain, unsigned long memory);</code>
|
|
</p>
|
|
<p>become</p>
|
|
<p>
|
|
<code>virConnect::numOfDomains(self)</code>
|
|
</p>
|
|
<p>
|
|
<code>virDomain::setMaxMemory(self, memory)</code>
|
|
</p>
|
|
<p>This process is fully automated, you can get a summary of the conversion
|
|
in the file libvirtclass.txt present in the python dir or in the docs.There
|
|
is a couple of function who don't map directly to their C counterparts due to
|
|
specificities in their argument conversions:</p>
|
|
<ul>
|
|
<li><code><a href="html/libvirt-libvirt-domain.html#virConnectListDomains">virConnectListDomains</a></code>
|
|
is replaced by <code>virDomain::listDomainsID(self)</code> which returns
|
|
a list of the integer ID for the currently running domains</li>
|
|
<li><code><a href="html/libvirt-libvirt-domain.html#virDomainGetInfo">virDomainGetInfo</a></code>
|
|
is replaced by <code>virDomain::info()</code> which returns a list of
|
|
<ol><li>state: one of the state values (virDomainState)</li><li>maxMemory: the maximum memory used by the domain</li><li>memory: the current amount of memory used by the domain</li><li>nbVirtCPU: the number of virtual CPU</li><li>cpuTime: the time used by the domain in nanoseconds</li></ol></li>
|
|
</ul>
|
|
<p>So let's look at a simple example:</p>
|
|
<pre>import <span style="color: #0071FF; background-color: #FFFFFF">libvirt</span>
|
|
import sys
|
|
|
|
try:
|
|
conn = <span style="color: #0071FF; background-color: #FFFFFF">libvirt</span>.openReadOnly(None)
|
|
except <span style="color: #0071FF; background-color: #FFFFFF">libvirt</span>.libvirtError:
|
|
print('Failed to open connection to the hypervisor')
|
|
sys.exit(1)
|
|
|
|
try:
|
|
dom0 = conn.<span style="color: #007F00; background-color: #FFFFFF">lookupByName</span>("Domain-0")
|
|
except <span style="color: #0071FF; background-color: #FFFFFF">libvirt</span>.libvirtError:
|
|
print('Failed to find the main domain')
|
|
sys.exit(1)
|
|
|
|
print("Domain 0: id %d running %s" % (dom0.<span style="color: #FF0080; background-color: #FFFFFF">ID</span>(), dom0.<span style="color: #FF0080; background-color: #FFFFFF">OSType</span>()))
|
|
print(dom0.<span style="color: #FF0080; background-color: #FFFFFF">info</span>())</pre>
|
|
<p>There is not much to comment about it, it really is a straight mapping
|
|
from the C API, the only points to notice are:</p>
|
|
<ul>
|
|
<li>the import of the module called <code><span style="color: #0071FF; background-color: #FFFFFF">libvirt</span></code></li>
|
|
<li>getting a connection to the hypervisor, in that case using the
|
|
openReadOnly function allows the code to execute as a normal user.</li>
|
|
<li>getting an object representing the Domain 0 using <span style="color: #007F00; background-color: #FFFFFF">lookupByName</span></li>
|
|
<li>if the domain is not found a libvirtError exception will be raised</li>
|
|
<li>extracting and printing some information about the domain using
|
|
various <span style="color: #E50073; background-color: #FFFFFF">methods</span>
|
|
associated to the virDomain class.</li>
|
|
</ul>
|
|
</body>
|
|
</html>
|