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',
|
||||
'index',
|
||||
'internals',
|
||||
'python',
|
||||
'remote',
|
||||
'storage',
|
||||
'tlscerts',
|
||||
@ -102,6 +101,7 @@ docs_rst_files = [
|
||||
'php',
|
||||
'platforms',
|
||||
'programming-languages',
|
||||
'python',
|
||||
'securityprocess',
|
||||
'strategy',
|
||||
'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