mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-12-22 05:35:25 +00:00
docs: convert 'python' page to rst
Signed-off-by: Pavel Hrdina <phrdina@redhat.com> Signed-off-by: Peter Krempa <pkrempa@redhat.com> Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
This commit is contained in:
Pavel Hrdina
Peter Krempa
parent
6c5ee55c3d
commit
d2978caea7
@ -29,7 +29,6 @@ docs_html_in_files = [
|
|||||||
'formatstoragecaps',
|
'formatstoragecaps',
|
||||||
'index',
|
'index',
|
||||||
'internals',
|
'internals',
|
||||||
'python',
|
|
||||||
'remote',
|
'remote',
|
||||||
'storage',
|
'storage',
|
||||||
'tlscerts',
|
'tlscerts',
|
||||||
@ -102,6 +101,7 @@ docs_rst_files = [
|
|||||||
'php',
|
'php',
|
||||||
'platforms',
|
'platforms',
|
||||||
'programming-languages',
|
'programming-languages',
|
||||||
|
'python',
|
||||||
'securityprocess',
|
'securityprocess',
|
||||||
'strategy',
|
'strategy',
|
||||||
'styleguide',
|
'styleguide',
|
||||||
|
|||||||
@ -1,72 +0,0 @@
|
|||||||
<?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>
|
|
||||||
79
docs/python.rst
Normal file
79
docs/python.rst
Normal file
@ -0,0 +1,79 @@
|
|||||||
|
===================
|
||||||
|
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.
|
||||||
Loading…
Reference in New Issue
Block a user