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
sureyou installed the libvirt-python package if not compiling from sources).
Alsonote that Daniel Berrange provides <a href="http://search.cpan.org/~danberr/Sys-Virt-0.1.0/">bindings for
Perl</a>too.</p><p>The Python binding should be complete and are mostly
automaticallygenerated from the formal description of the API in xml. The
bindings arearticulated around 2 classes <code>virConnect</code>and virDomain
mapping tothe C types. Functions in the C API taking either type as argument
thenbecomes methods for the classes, their name is just stripped from
thevirConnect or virDomain(Get) prefix and the first letter gets converted
tolower 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 conversionin
the file libvirtclass.txt present in the python dir or in the docs.Thereis a
couple of function who don't map directly to their C counterparts due
tospecificities 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 returnsa
    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)

try:
    dom0 = conn.<span style="color: #007F00; background-color: #FFFFFF">lookupByName</span>("Domain-0")
except:
    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 mappingfrom
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
    theopenReadOnly 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 informations about the domain usingvarious
    <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 Formats</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://virt-manager.et.redhat.com/">virt-manager</a></li><li><a href="http://search.cpan.org/~danberr/Sys-Virt-0.1.0/">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">`
* include/libvirt/libvirt.h[.in] include/libvirt/virterror.h proxy/libvirt_proxy.c qemud/Makefile.am qemud/conf.c qemud/conf.h qemud/dispatch.c qemud/internal.h qemud/protocol.h src/driver.h src/internal.h src/libvirt.c src/libvirt_sym.version src/proxy_internal.c src/proxy_internal.h src/qemu_internal.c src/test.c src/virsh.c src/virterror.c src/xen_internal.c src/xen_internal.h src/xend_internal.c src/xm_internal.c src/xml.h src/xs_internal.c: applied patch from Richard Jones adding virConnectGetCapabilities(), plus various small little fixes * docs/*: fixed the api extractor script and regenerated Daniel 2007-03-15 17:24:56 +00:00			<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
			`sureyou installed the libvirt-python package if not compiling from sources).`
			`Alsonote that Daniel Berrange provides <a href="http://search.cpan.org/~danberr/Sys-Virt-0.1.0/">bindings for`
			`Perl</a>too.</p><p>The Python binding should be complete and are mostly`
			`automaticallygenerated from the formal description of the API in xml. The`
			`bindings arearticulated around 2 classes <code>virConnect</code>and virDomain`
			`mapping tothe C types. Functions in the C API taking either type as argument`
			`thenbecomes methods for the classes, their name is just stripped from`
			`thevirConnect or virDomain(Get) prefix and the first letter gets converted`
			`tolower 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 conversionin`
			`the file libvirtclass.txt present in the python dir or in the docs.Thereis a`
			`couple of function who don't map directly to their C counterparts due`
			`tospecificities 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 returnsa`
			`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`
* 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			`<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>`
* include/libvirt/libvirt.h[.in] include/libvirt/virterror.h proxy/libvirt_proxy.c qemud/Makefile.am qemud/conf.c qemud/conf.h qemud/dispatch.c qemud/internal.h qemud/protocol.h src/driver.h src/internal.h src/libvirt.c src/libvirt_sym.version src/proxy_internal.c src/proxy_internal.h src/qemu_internal.c src/test.c src/virsh.c src/virterror.c src/xen_internal.c src/xen_internal.h src/xend_internal.c src/xm_internal.c src/xml.h src/xs_internal.c: applied patch from Richard Jones adding virConnectGetCapabilities(), plus various small little fixes * docs/*: fixed the api extractor script and regenerated Daniel 2007-03-15 17:24:56 +00:00			`</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>`
* 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			`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)`

Fixing the python example, Daniel 2006-03-28 14:48:57 +00:00			`try:`
			`dom0 = conn.<span style="color: #007F00; background-color: #FFFFFF">lookupByName</span>("Domain-0")`
			`except:`
* 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			`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>())`
* include/libvirt/libvirt.h[.in] include/libvirt/virterror.h proxy/libvirt_proxy.c qemud/Makefile.am qemud/conf.c qemud/conf.h qemud/dispatch.c qemud/internal.h qemud/protocol.h src/driver.h src/internal.h src/libvirt.c src/libvirt_sym.version src/proxy_internal.c src/proxy_internal.h src/qemu_internal.c src/test.c src/virsh.c src/virterror.c src/xen_internal.c src/xen_internal.h src/xend_internal.c src/xm_internal.c src/xml.h src/xs_internal.c: applied patch from Richard Jones adding virConnectGetCapabilities(), plus various small little fixes * docs/*: fixed the api extractor script and regenerated Daniel 2007-03-15 17:24:56 +00:00			`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 mappingfrom`
			`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`
			`theopenReadOnly function allows the code to execute as a normal user.</li>`
* 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			`<li>getting an object representing the Domain 0 using <span style="color: #007F00; background-color: #FFFFFF">lookupByName</span></li>`
Fixing the python example, Daniel 2006-03-28 14:48:57 +00:00			`<li>if the domain is not found a libvirtError exception will be raised</li>`
* include/libvirt/libvirt.h[.in] include/libvirt/virterror.h proxy/libvirt_proxy.c qemud/Makefile.am qemud/conf.c qemud/conf.h qemud/dispatch.c qemud/internal.h qemud/protocol.h src/driver.h src/internal.h src/libvirt.c src/libvirt_sym.version src/proxy_internal.c src/proxy_internal.h src/qemu_internal.c src/test.c src/virsh.c src/virterror.c src/xen_internal.c src/xen_internal.h src/xend_internal.c src/xm_internal.c src/xml.h src/xs_internal.c: applied patch from Richard Jones adding virConnectGetCapabilities(), plus various small little fixes * docs/*: fixed the api extractor script and regenerated Daniel 2007-03-15 17:24:56 +00:00			`<li>extracting and printing some informations about the domain usingvarious`
			`<span style="color: #E50073; background-color: #FFFFFF">methods</span>associated`
			`to the virDomain class.</li>`
* docs/: updated the format section, augmented Networking with description provided by Daniel Berrange po/*: regenerated Daniel 2007-03-16 18:33:53 +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 Formats</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://virt-manager.et.redhat.com/">virt-manager</a></li><li><a href="http://search.cpan.org/~danberr/Sys-Virt-0.1.0/">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>