[PATCH 2/7] docs: convert 'python' page to rst
Peter Krempa
pkrempa at redhat.com
Mon Apr 4 15:04:19 UTC 2022
From: Pavel Hrdina <phrdina at redhat.com>
Signed-off-by: Pavel Hrdina <phrdina at redhat.com>
Signed-off-by: Peter Krempa <pkrempa at redhat.com>
---
docs/meson.build | 2 +-
docs/python.html.in | 72 -----------------------------------------
docs/python.rst | 79 +++++++++++++++++++++++++++++++++++++++++++++
3 files changed, 80 insertions(+), 73 deletions(-)
delete mode 100644 docs/python.html.in
create mode 100644 docs/python.rst
diff --git a/docs/meson.build b/docs/meson.build
index e73cb3c6cd..9022e761ca 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -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',
diff --git a/docs/python.html.in b/docs/python.html.in
deleted file mode 100644
index 0f804da8c3..0000000000
--- a/docs/python.html.in
+++ /dev/null
@@ -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>
diff --git a/docs/python.rst b/docs/python.rst
new file mode 100644
index 0000000000..aa1bddc4e1
--- /dev/null
+++ b/docs/python.rst
@@ -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.
--
2.35.1
More information about the libvir-list
mailing list