libvirt/docs/python.html

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /><link rel="stylesheet" type="text/css" href="libvirt.css" /><link rel="SHORTCUT ICON" href="/32favicon.png" /><title>Binding for Python</title></head><body><div id="container"><div id="intro"><div id="adjustments"></div><div id="pageHeader"></div><div id="content2"><h1 class="style1">Binding for Python</h1><p>Libvirt comes with direct support for the Python language (just make sure
you installed the libvirt-python package if not compiling from sources).
Also note that Daniel Berrange provides
<a href="http://hg.berrange.com/libraries/sys-virt">bindings for Perl</a>
too.</p><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.html#virConnectNumOfDomains">virConnectNumOfDomains</a>
(virConnectPtr conn);</code></p><p><code>int <a href="html/libvirt-libvirt.html#virDomainSetMaxMemory">virDomainSetMaxMemory</a>
(virDomainPtr domain, unsigned long memory);</code></p><p>become</p><p><code>virConn::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.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.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 inspired from the <code>basic.py</code>
test found in <code>python/tests/</code> in the source tree:</p><pre>import <span style="color: #0071FF; background-color: #FFFFFF">libvirt</span>
import sys

conn = <span style="color: #0071FF; background-color: #FFFFFF">libvirt</span>.openReadOnly(None)
if conn == None:
    print 'Failed to open connection to the hypervisor'
    sys.exit(1)

dom0 = conn.<span style="color: #007F00; background-color: #FFFFFF">lookupByName</span>("Domain-0")
if dom0 == None:
    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>extracting and printing some informations about the domain using
    various <span style="color: #E50073; background-color: #FFFFFF">methods</span>
    associated to the virDomain class.</li>
</ul></div></div><div class="linkList2"><div class="llinks2"><h3 class="links2"><span>main menu</span></h3><ul><li><a href="index.html">Home</a></li><li><a href="news.html">Releases</a></li><li><a href="intro.html">Introduction</a></li><li><a href="architecture.html">libvirt architecture</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="format.html">XML Format</a></li><li><a href="python.html">Binding for Python</a></li><li><a href="errors.html">Handling of errors</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a href="html/index.html">API Menu</a></li><li><a href="examples/index.html">C code examples</a></li><li><a href="ChangeLog.html">Recent Changes</a></li></ul></div><div class="llinks2"><h3 class="links2"><span>related links</span></h3><ul><li><a href="https://www.redhat.com/archives/libvir-list/">Mail archive</a></li><li><a href="https://bugzilla.redhat.com/bugzilla/buglist.cgi?product=Fedora+Core&amp;component=libvirt&amp;bug_status=NEW&amp;bug_status=ASSIGNED&amp;bug_status=REOPENED&amp;bug_status=MODIFIED&amp;short_desc_type=allwordssubstr&amp;short_desc=&amp;long_desc_type=allwordssubstr">Open bugs</a></li><li><a href="http://hg.berrange.com/libraries/sys-virt">Perl bindings</a></li><li><a href="http://www.cl.cam.ac.uk/Research/SRG/netos/xen/index.html">Xen project</a></li><li><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="12" value="Search..." /><input name="submit" type="submit" value="Go" /></form></li><li><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-90x34.gif" alt="Made with Libxml2 Logo" /></a></li></ul><p class="credits">Graphics and design by <a href="mail:dfong@redhat.com">Diana Fong</a></p></div></div><div id="bottom"><p class="p1"></p></div></div></body></html>
* TODO: updated * python/tests/Makefile.am: fix a small PYTHONPATH bug * docs//*: fixed the xsl a bit for toc names, added doc for the python bindings, regenerated Daniel 2006-02-21 13:23:16 +00:00			`<?xml version="1.0" encoding="ISO-8859-1"?>`
			`<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">`
			<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /><link rel="stylesheet" type="text/css" href="libvirt.css" /><link rel="SHORTCUT ICON" href="/32favicon.png" /><title>Binding for Python</title></head><body><div id="container"><div id="intro"><div id="adjustments"></div><div id="pageHeader"></div><div id="content2"><h1 class="style1">Binding for Python</h1><p>Libvirt comes with direct support for the Python language (just make sure
* doc/site.xsl doc/libvir.html doc/: added informations about the Perl bindings, regenerated python/libvirt_wrap.h: added a missing include. Daniel 2006-03-28 09:50:17 +00:00			`you installed the libvirt-python package if not compiling from sources).`
			`Also note that Daniel Berrange provides`
			`<a href="http://hg.berrange.com/libraries/sys-virt">bindings for Perl</a>`
			`too.</p><p> The Python binding should be complete and are mostly automatically generated from`
* TODO: updated * python/tests/Makefile.am: fix a small PYTHONPATH bug * docs//*: fixed the xsl a bit for toc names, added doc for the python bindings, regenerated Daniel 2006-02-21 13:23:16 +00:00			`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.html#virConnectNumOfDomains">virConnectNumOfDomains</a>`
			`(virConnectPtr conn);</code></p><p><code>int <a href="html/libvirt-libvirt.html#virDomainSetMaxMemory">virDomainSetMaxMemory</a>`
			`(virDomainPtr domain, unsigned long memory);</code></p><p>become</p><p><code>virConn::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.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.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 inspired from the <code>basic.py</code>`
			`test found in <code>python/tests/</code> in the source tree:</p><pre>import <span style="color: #0071FF; background-color: #FFFFFF">libvirt</span>`
			`import sys`

			`conn = <span style="color: #0071FF; background-color: #FFFFFF">libvirt</span>.openReadOnly(None)`
			`if conn == None:`
			`print 'Failed to open connection to the hypervisor'`
			`sys.exit(1)`

			`dom0 = conn.<span style="color: #007F00; background-color: #FFFFFF">lookupByName</span>("Domain-0")`
			`if dom0 == None:`
			`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>extracting and printing some informations about the domain using`
			`various <span style="color: #E50073; background-color: #FFFFFF">methods</span>`
			`associated to the virDomain class.</li>`
* doc/site.xsl doc/libvir.html doc/: added informations about the Perl bindings, regenerated python/libvirt_wrap.h: added a missing include. Daniel 2006-03-28 09:50:17 +00:00			</ul></div></div><div class="linkList2"><div class="llinks2"><h3 class="links2"><span>main menu</span></h3><ul><li><a href="index.html">Home</a></li><li><a href="news.html">Releases</a></li><li><a href="intro.html">Introduction</a></li><li><a href="architecture.html">libvirt architecture</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="format.html">XML Format</a></li><li><a href="python.html">Binding for Python</a></li><li><a href="errors.html">Handling of errors</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a href="html/index.html">API Menu</a></li><li><a href="examples/index.html">C code examples</a></li><li><a href="ChangeLog.html">Recent Changes</a></li></ul></div><div class="llinks2"><h3 class="links2"><span>related links</span></h3><ul><li><a href="https://www.redhat.com/archives/libvir-list/">Mail archive</a></li><li><a href="https://bugzilla.redhat.com/bugzilla/buglist.cgi?product=Fedora+Core&component=libvirt&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&bug_status=MODIFIED&short_desc_type=allwordssubstr&short_desc=&long_desc_type=allwordssubstr">Open bugs</a></li><li><a href="http://hg.berrange.com/libraries/sys-virt">Perl bindings</a></li><li><a href="http://www.cl.cam.ac.uk/Research/SRG/netos/xen/index.html">Xen project</a></li><li><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="12" value="Search..." /><input name="submit" type="submit" value="Go" /></form></li><li><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-90x34.gif" alt="Made with Libxml2 Logo" /></a></li></ul><p class="credits">Graphics and design by <a href="mail:dfong@redhat.com">Diana Fong</a></p></div></div><div id="bottom"><p class="p1"></p></div></div></body></html>