← Back to branch summary

~nova-coresec/ubuntu/maverick/libvirt/nova-ppa

« back to all changes in this revision

Viewing changes to docs/python.html

Tags: 0.4.4-3
* upload to unstable
* [96c6727] add /var/cache/libvirt needed by qemuDriver for temporary
  storage
* [794f95c] bump standards version to 3.8.0
* [05184af] add README.source

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/python.html
1
1
<?xml version="1.0" encoding="ISO-8859-1"?>
2
 
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3
 
<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
4
 
you installed the libvirt-python package if not compiling from sources). Also
5
 
note that Daniel Berrange provides <a href="http://search.cpan.org/~danberr/Sys-Virt-0.1.0/">bindings for Perl</a>
6
 
too.</p><p>The Python binding should be complete and are mostly automatically
 
2
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
 
3
<html xmlns="http://www.w3.org/1999/xhtml">
 
4
<!--
 
5
        This file is autogenerated from python.html.in
 
6
        Do not edit this file. Changes will be lost.
 
7
      -->
 
8
  <head>
 
9
    <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
 
10
    <link rel="stylesheet" type="text/css" href="main.css" />
 
11
    <link rel="SHORTCUT ICON" href="32favicon.png" />
 
12
    <title>libvirt: Python API bindings</title>
 
13
    <meta name="description" content="libvirt, virtualization, virtualization API" />
 
14
  </head>
 
15
  <body>
 
16
    <div id="header">
 
17
      <div id="headerLogo"></div>
 
18
      <div id="headerSearch">
 
19
        <form action="search.php" enctype="application/x-www-form-urlencoded" method="get">
 
20
          <div>
 
21
            <input id="query" name="query" type="text" size="12" value="" />
 
22
            <input id="submit" name="submit" type="submit" value="Search" />
 
23
          </div>
 
24
        </form>
 
25
      </div>
 
26
    </div>
 
27
    <div id="body">
 
28
      <div id="menu">
 
29
        <ul class="l0">
 
30
          <li>
 
31
            <div>
 
32
              <a title="Front page of the libvirt website" class="inactive" href="index.html">Home</a>
 
33
            </div>
 
34
          </li>
 
35
          <li>
 
36
            <div>
 
37
              <a title="Details of new features and bugs fixed in each release" class="inactive" href="news.html">News</a>
 
38
            </div>
 
39
          </li>
 
40
          <li>
 
41
            <div>
 
42
              <a title="Get the latest source releases, binary builds and get access to the source repository" class="inactive" href="downloads.html">Downloads</a>
 
43
            </div>
 
44
          </li>
 
45
          <li>
 
46
            <div>
 
47
              <a title="Information for users, administrators and developers" class="active" href="docs.html">Documentation</a>
 
48
              <ul class="l1">
 
49
                <li>
 
50
                  <div>
 
51
                    <a title="Information about deploying and using libvirt" class="inactive" href="deployment.html">Deployment</a>
 
52
                  </div>
 
53
                </li>
 
54
                <li>
 
55
                  <div>
 
56
                    <a title="Overview of the logical subsystems in the libvirt API" class="inactive" href="intro.html">Architecture</a>
 
57
                  </div>
 
58
                </li>
 
59
                <li>
 
60
                  <div>
 
61
                    <a title="Description of the XML formats used in libvirt" class="inactive" href="format.html">XML format</a>
 
62
                  </div>
 
63
                </li>
 
64
                <li>
 
65
                  <div>
 
66
                    <a title="Hypervisor specific driver information" class="inactive" href="drivers.html">Drivers</a>
 
67
                  </div>
 
68
                </li>
 
69
                <li>
 
70
                  <div>
 
71
                    <a title="Reference manual for the C public API" class="inactive" href="html/index.html">API reference</a>
 
72
                  </div>
 
73
                </li>
 
74
                <li>
 
75
                  <div>
 
76
                    <a title="Bindings of the libvirt API for other languages" class="active" href="bindings.html">Language bindings</a>
 
77
                    <ul class="l2">
 
78
                      <li>
 
79
                        <div>
 
80
                          <span class="active">Python</span>
 
81
                        </div>
 
82
                      </li>
 
83
                    </ul>
 
84
                  </div>
 
85
                </li>
 
86
              </ul>
 
87
            </div>
 
88
          </li>
 
89
          <li>
 
90
            <div>
 
91
              <a title="User contributed content" class="inactive" href="http://wiki.libvirt.org">Wiki</a>
 
92
            </div>
 
93
          </li>
 
94
          <li>
 
95
            <div>
 
96
              <a title="Frequently asked questions" class="inactive" href="FAQ.html">FAQ</a>
 
97
            </div>
 
98
          </li>
 
99
          <li>
 
100
            <div>
 
101
              <a title="How and where to report bugs and request features" class="inactive" href="bugs.html">Bug reports</a>
 
102
            </div>
 
103
          </li>
 
104
          <li>
 
105
            <div>
 
106
              <a title="How to contact the developers via email and IRC" class="inactive" href="contact.html">Contact</a>
 
107
            </div>
 
108
          </li>
 
109
          <li>
 
110
            <div>
 
111
              <a title="Miscellaneous links of interest related to libvirt" class="inactive" href="relatedlinks.html">Related Links</a>
 
112
            </div>
 
113
          </li>
 
114
          <li>
 
115
            <div>
 
116
              <a title="Overview of all content on the website" class="inactive" href="sitemap.html">Sitemap</a>
 
117
            </div>
 
118
          </li>
 
119
        </ul>
 
120
      </div>
 
121
      <div id="content">
 
122
        <h1>Python API bindings</h1>
 
123
        <p>The Python binding should be complete and are mostly automatically
7
124
generated from the formal description of the API in xml. The bindings are
8
125
articulated around 2 classes <code>virConnect</code> and virDomain mapping to
9
126
the C types. Functions in the C API taking either type as argument then
10
127
becomes methods for the classes, their name is just stripped from the
11
128
virConnect or virDomain(Get) prefix and the first letter gets converted to
12
 
lower case, for example the C functions:</p><p><code>int <a href="html/libvirt-libvirt.html#virConnectNumOfDomains">virConnectNumOfDomains</a>
13
 
(virConnectPtr conn);</code></p><p><code>int <a href="html/libvirt-libvirt.html#virDomainSetMaxMemory">virDomainSetMaxMemory</a>
14
 
(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
 
129
lower case, for example the C functions:</p>
 
130
        <p>
 
131
          <code>int <a href="html/libvirt-libvirt.html#virConnectNumOfDomains">virConnectNumOfDomains</a>
 
132
(virConnectPtr conn);</code>
 
133
        </p>
 
134
        <p>
 
135
          <code>int <a href="html/libvirt-libvirt.html#virDomainSetMaxMemory">virDomainSetMaxMemory</a>
 
136
(virDomainPtr domain, unsigned long memory);</code>
 
137
        </p>
 
138
        <p>become</p>
 
139
        <p>
 
140
          <code>virConn::numOfDomains(self)</code>
 
141
        </p>
 
142
        <p>
 
143
          <code>virDomain::setMaxMemory(self, memory)</code>
 
144
        </p>
 
145
        <p>This process is fully automated, you can get a summary of the conversion
15
146
in the file libvirtclass.txt present in the python dir or in the docs.There
16
147
is a couple of function who don't map directly to their C counterparts due to
17
 
specificities in their argument conversions:</p><ul><li><code><a href="html/libvirt-libvirt.html#virConnectListDomains">virConnectListDomains</a></code>
 
148
specificities in their argument conversions:</p>
 
149
        <ul>
 
150
          <li><code><a href="html/libvirt-libvirt.html#virConnectListDomains">virConnectListDomains</a></code>
18
151
    is replaced by <code>virDomain::listDomainsID(self)</code> which returns
19
152
    a list of the integer ID for the currently running domains</li>
20
 
  <li><code><a href="html/libvirt-libvirt.html#virDomainGetInfo">virDomainGetInfo</a></code>
 
153
          <li><code><a href="html/libvirt-libvirt.html#virDomainGetInfo">virDomainGetInfo</a></code>
21
154
    is replaced by <code>virDomain::info()</code> which returns a list of
22
 
    <ol><li>state: one of the state values (virDomainState)</li>
23
 
      <li>maxMemory: the maximum memory used by the domain</li>
24
 
      <li>memory: the current amount of memory used by the domain</li>
25
 
      <li>nbVirtCPU: the number of virtual CPU</li>
26
 
      <li>cpuTime: the time used by the domain in nanoseconds</li>
27
 
    </ol></li>
28
 
</ul><p>So let's look at a simple example inspired from the <code>basic.py</code>
29
 
test found in <code>python/tests/</code> in the source tree:</p><pre>import <span style="color: #0071FF; background-color: #FFFFFF">libvirt</span>
 
155
    <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>
 
156
        </ul>
 
157
        <p>So let's look at a simple example inspired from the <code>basic.py</code>
 
158
test found in <code>python/tests/</code> in the source tree:</p>
 
159
        <pre>import <span style="color: #0071FF; background-color: #FFFFFF">libvirt</span>
30
160
import sys
31
161
 
32
162
conn = <span style="color: #0071FF; background-color: #FFFFFF">libvirt</span>.openReadOnly(None)
41
171
    sys.exit(1)
42
172
 
43
173
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>())
44
 
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
45
 
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>
46
 
  <li>getting a connection to the hypervisor, in that case using the
 
174
print dom0.<span style="color: #FF0080; background-color: #FFFFFF">info</span>()</pre>
 
175
        <p>There is not much to comment about it, it really is a straight mapping
 
176
from the C API, the only points to notice are:</p>
 
177
        <ul>
 
178
          <li>the import of the module called <code><span style="color: #0071FF; background-color: #FFFFFF">libvirt</span></code></li>
 
179
          <li>getting a connection to the hypervisor, in that case using the
47
180
    openReadOnly function allows the code to execute as a normal user.</li>
48
 
  <li>getting an object representing the Domain 0 using <span style="color: #007F00; background-color: #FFFFFF">lookupByName</span></li>
49
 
  <li>if the domain is not found a libvirtError exception will be raised</li>
50
 
  <li>extracting and printing some informations about the domain using
 
181
          <li>getting an object representing the Domain 0 using <span style="color: #007F00; background-color: #FFFFFF">lookupByName</span></li>
 
182
          <li>if the domain is not found a libvirtError exception will be raised</li>
 
183
          <li>extracting and printing some information about the domain using
51
184
    various <span style="color: #E50073; background-color: #FFFFFF">methods</span>
52
185
    associated to the virDomain class.</li>
53
 
</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://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>
 
186
        </ul>
 
187
      </div>
 
188
    </div>
 
189
    <div id="footer">
 
190
      <p id="sponsor">
 
191
            Sponsored by:<br /><a href="http://et.redhat.com/"><img src="et.png" alt="Project sponsored by Red Hat Emerging Technology" /></a></p>
 
192
    </div>
 
193
  </body>
 
194
</html>