docs/python.html.in

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE html>
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4   <body>
   5     <h1>Python API bindings</h1>
   6
   7     <p>The Python binding should be complete and are mostly automatically
   8 generated from the formal description of the API in xml. The bindings are
   9 articulated around 2 classes <code>virConnect</code> and virDomain mapping to
  10 the C types. Functions in the C API taking either type as argument then
  11 becomes methods for the classes, their name is just stripped from the
  12 virConnect or virDomain(Get) prefix and the first letter gets converted to
  13 lower case, for example the C functions:</p>
  14     <p>
  15       <code>int <a href="html/libvirt-libvirt-domain.html#virConnectNumOfDomains">virConnectNumOfDomains</a>
  16 (virConnectPtr conn);</code>
  17     </p>
  18     <p>
  19       <code>int <a href="html/libvirt-libvirt-domain.html#virDomainSetMaxMemory">virDomainSetMaxMemory</a>
  20 (virDomainPtr domain, unsigned long memory);</code>
  21     </p>
  22     <p>become</p>
  23     <p>
  24       <code>virConnect::numOfDomains(self)</code>
  25     </p>
  26     <p>
  27       <code>virDomain::setMaxMemory(self, memory)</code>
  28     </p>
  29     <p>This process is fully automated, you can get a summary of the conversion
  30 in the file libvirtclass.txt present in the python dir or in the docs.There
  31 is a couple of function who don't map directly to their C counterparts due to
  32 specificities in their argument conversions:</p>
  33     <ul>
  34       <li><code><a href="html/libvirt-libvirt-domain.html#virConnectListDomains">virConnectListDomains</a></code>
  35     is replaced by <code>virDomain::listDomainsID(self)</code> which returns
  36     a list of the integer ID for the currently running domains</li>
  37       <li><code><a href="html/libvirt-libvirt-domain.html#virDomainGetInfo">virDomainGetInfo</a></code>
  38     is replaced by <code>virDomain::info()</code> which returns a list of
  39     <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>
  40     </ul>
  41     <p>So let's look at a simple example inspired from the <code>basic.py</code>
  42 test found in <code>python/tests/</code> in the source tree:</p>
  43     <pre>import <span style="color: #0071FF; background-color: #FFFFFF">libvirt</span>
  44 import sys
  45
  46 conn = <span style="color: #0071FF; background-color: #FFFFFF">libvirt</span>.openReadOnly(None)
  47 if conn == None:
  48     print 'Failed to open connection to the hypervisor'
  49     sys.exit(1)
  50
  51 try:
  52     dom0 = conn.<span style="color: #007F00; background-color: #FFFFFF">lookupByName</span>("Domain-0")
  53 except:
  54     print 'Failed to find the main domain'
  55     sys.exit(1)
  56
  57 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>())
  58 print dom0.<span style="color: #FF0080; background-color: #FFFFFF">info</span>()</pre>
  59     <p>There is not much to comment about it, it really is a straight mapping
  60 from the C API, the only points to notice are:</p>
  61     <ul>
  62       <li>the import of the module called <code><span style="color: #0071FF; background-color: #FFFFFF">libvirt</span></code></li>
  63       <li>getting a connection to the hypervisor, in that case using the
  64     openReadOnly function allows the code to execute as a normal user.</li>
  65       <li>getting an object representing the Domain 0 using <span style="color: #007F00; background-color: #FFFFFF">lookupByName</span></li>
  66       <li>if the domain is not found a libvirtError exception will be raised</li>
  67       <li>extracting and printing some information about the domain using
  68     various <span style="color: #E50073; background-color: #FFFFFF">methods</span>
  69     associated to the virDomain class.</li>
  70     </ul>
  71   </body>
  72 </html>