Commit d2978cae authored by Pavel Hrdina's avatar Pavel Hrdina Committed by Peter Krempa
Browse files

docs: convert 'python' page to rst



Signed-off-by: Pavel Hrdina's avatarPavel Hrdina <phrdina@redhat.com>
Signed-off-by: Peter Krempa's avatarPeter Krempa <pkrempa@redhat.com>
Reviewed-by: Pavel Hrdina's avatarPavel Hrdina <phrdina@redhat.com>
parent 6c5ee55c
......@@ -29,7 +29,6 @@ docs_html_in_files = [
'formatstoragecaps',
'index',
'internals',
'python',
'remote',
'storage',
'tlscerts',
......@@ -102,6 +101,7 @@ docs_rst_files = [
'php',
'platforms',
'programming-languages',
'python',
'securityprocess',
'strategy',
'styleguide',
......
<?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>
===================
Python API bindings
===================
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 ``virConnect`` 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:
``int virConnectNumOfDomains (virConnectPtr conn);``
``int virDomainSetMaxMemory (virDomainPtr domain, unsigned long memory);``
become
``virConnect::numOfDomains(self)``
``virDomain::setMaxMemory(self, memory)``
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:
- ``virConnectListDomains`` is replaced by ``virDomain::listDomainsID(self)``
which returns a list of the integer ID for the currently running domains
- ``virDomainGetInfo`` is replaced by ``virDomain::info()`` which returns a
list of
#. state: one of the state values (virDomainState)
#. maxMemory: the maximum memory used by the domain
#. memory: the current amount of memory used by the domain
#. nbVirtCPU: the number of virtual CPU
#. cpuTime: the time used by the domain in nanoseconds
So let's look at a simple example:
::
import libvirt
import sys
try:
conn = libvirt.openReadOnly(None)
except libvirt.libvirtError:
print('Failed to open connection to the hypervisor')
sys.exit(1)
try:
dom0 = conn.lookupByName("Domain-0")
except libvirt.libvirtError:
print('Failed to find the main domain')
sys.exit(1)
print("Domain 0: id %d running %s" % (dom0.ID(), dom0.OSType()))
print(dom0.info())
There is not much to comment about it, it really is a straight mapping from the
C API, the only points to notice are:
- the import of the module called ``libvirt``
- getting a connection to the hypervisor, in that case using the openReadOnly
function allows the code to execute as a normal user.
- getting an object representing the Domain 0 using lookupByName
- if the domain is not found a libvirtError exception will be raised
- extracting and printing some information about the domain using various
methods associated to the virDomain class.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment