From d3a15eb3031482616bf7c38dc92218c8ddfd80c0 Mon Sep 17 00:00:00 2001 From: Daniel Veillard Date: Tue, 21 Feb 2006 13:23:16 +0000 Subject: [PATCH] * 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 --- ChangeLog | 7 ++ TODO | 2 + docs/FAQ.html | 4 +- docs/architecture.html | 2 +- docs/bugs.html | 2 +- docs/downloads.html | 2 +- docs/format.html | 2 +- docs/index.html | 5 +- docs/intro.html | 2 +- docs/libvir.html | 85 ++++++++++++++++++++- docs/news.html | 2 +- docs/python.html | 50 +++++++++++++ docs/site.xsl | 157 +-------------------------------------- python/tests/Makefile.am | 2 +- 14 files changed, 159 insertions(+), 165 deletions(-) create mode 100644 docs/python.html diff --git a/ChangeLog b/ChangeLog index 774b83ee53..4148997882 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +Tue Feb 21 14:21:39 CET 2006 Daniel Veillard + + * 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 + Tue Feb 21 00:06:30 CET 2006 Daniel Veillard * src/libvirt.c src/xend_internal.c src/xend_internal.h: move the diff --git a/TODO b/TODO index e812b95869..9029a6b1af 100644 --- a/TODO +++ b/TODO @@ -11,6 +11,8 @@ TODO: - API for the Node: extracting informations, selecting scheduling policy - better resources allocation APIs (%CPU, set memory) - DTD/RNG/XSD schemas for the XML Domain descriptions +- in python bindings raise an exception if a lookup or connection fails + to return a non-None object Probable TODOs: - event on big domain state change (create, crashed, paused, shutdown, destroy) diff --git a/docs/FAQ.html b/docs/FAQ.html index 8718e94e31..cce0aa57c1 100644 --- a/docs/FAQ.html +++ b/docs/FAQ.html @@ -1,6 +1,6 @@ - FAQ diff --git a/docs/architecture.html b/docs/architecture.html index ecf3722c14..f55e11d1e9 100644 --- a/docs/architecture.html +++ b/docs/architecture.html @@ -24,4 +24,4 @@ connect to initialize the library. It will try to open the read-only socket /var/run/xenstored/socket_ro to connect to the Xen Store and also try to use the RPC to the Xen daemon. In this case use of hypervisor calls and write to the Xen Store will not be possible, restraining the amount -of APIs available and slowing down information gathering about domains.

main menu

related links

Graphics and design by Diana Fong

+of APIs available and slowing down information gathering about domains.

main menu

related links

Graphics and design by Diana Fong

diff --git a/docs/bugs.html b/docs/bugs.html index c0eef3e6be..fa84356bfb 100644 --- a/docs/bugs.html +++ b/docs/bugs.html @@ -7,4 +7,4 @@ page and follow the instructions. Patches with explanations and provided as attachments are really appreciated and will be discussed on the mailing list. If possible generate the patches by using cvs diff -u in a CVS checkout.

We expect to use Red Hat Bugzilla to track bugs for libvirt, though there isn't a libvirt software -module defined yet, in the meantime use the mailing-list, thanks !.

main menu

related links

Graphics and design by Diana Fong

+module defined yet, in the meantime use the mailing-list, thanks !.

main menu

related links

Graphics and design by Diana Fong

diff --git a/docs/downloads.html b/docs/downloads.html index 6701fe0973..4b6298e40a 100644 --- a/docs/downloads.html +++ b/docs/downloads.html @@ -7,4 +7,4 @@ available, first register onto the server:

cvs -d :pserver:anoncvs@l checkout the development tree with:

cvs -d :pserver:anoncvs@libvirt.org:2401/data/cvs co libvirt

Use ./autogen.sh to configure the local checkout, then make and make install, as usual. All normal cvs commands are now -available except commiting to the base.

main menu

related links

Graphics and design by Diana Fong

+available except commiting to the base.

main menu

related links

Graphics and design by Diana Fong

diff --git a/docs/format.html b/docs/format.html index fb55d0891d..a6d3d4ee52 100644 --- a/docs/format.html +++ b/docs/format.html @@ -65,4 +65,4 @@ children in no specific order:

  • source: indicating the bridge name
    • target: and optional target indicating the device name.

While the format may be extended in various ways as support for more hypervisor types and features are added, it is expected that this core subset -will remain functional in spite of the evolution of the library.

main menu

related links

Graphics and design by Diana Fong

+will remain functional in spite of the evolution of the library.

main menu

related links

Graphics and design by Diana Fong

diff --git a/docs/index.html b/docs/index.html index 82c4169498..e69f67c98f 100644 --- a/docs/index.html +++ b/docs/index.html @@ -50,7 +50,10 @@ mechanisms if needed.

XML Format
  • - FAQ + Binding for Python +
    • +
  • + FAQ
  • Reporting bugs and getting help diff --git a/docs/intro.html b/docs/intro.html index 5444c1777d..4d7530ea30 100644 --- a/docs/intro.html +++ b/docs/intro.html @@ -27,4 +27,4 @@ and for applications focusing on virtualization of a single node (the only exception being domain migration between node capabilities which may need to be added at the libvirt level). Where possible libvirt should be extendable to be able to provide the same API for remote nodes, however this is not the -case at the moment, the code currently handle only local node accesses.

    main menu

    related links

    Graphics and design by Diana Fong

    +case at the moment, the code currently handle only local node accesses.

    main menu

    related links

    Graphics and design by Diana Fong

    diff --git a/docs/libvir.html b/docs/libvir.html index e8ba435131..7d24c9094c 100644 --- a/docs/libvir.html +++ b/docs/libvir.html @@ -261,9 +261,90 @@ children in no specific order:

    While the format may be extended in various ways as support for more hypervisor types and features are added, it is expected that this core subset -will remain functional in spite of the evolution of the library.

    +will remain functional in spite of the evolution of the library.

    -

    FAQ

    +

    Binding for Python

    + +

    Libvirt comes with direct support for the Python language (just make sure +you installed the libvirt-python package if not compiling from sources). 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

    + +

    virConn::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 +
        +
      1. state: one of the state values (virDomainState)
        2. +
      2. maxMemory: the maximum memory used by the domain
        3. +
      3. memory: the current amount of memory used by the domain
        4. +
      4. nbVirtCPU: the number of virtual CPU
        5. +
      5. cpuTime: the time used by the domain in nanoseconds
        6. +
      +
      • +
    + +

    So let's look at a simple example inspired from the basic.py +test found in python/tests/ in the source tree:

    +
    import libvirt
+import sys
+
+conn = libvirt.openReadOnly(None)
+if conn == None:
+    print 'Failed to open connection to the hypervisor'
+    sys.exit(1)
+
+dom0 = conn.lookupByName("Domain-0")
+if dom0 == None:
+    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
      • +
    • extracting and printing some informations about the domain using + various methods + associated to the virDomain class.
      • +
    + +

    FAQ

    Table of Contents:

    main menu

    related links

    Graphics and design by Diana Fong

    diff --git a/docs/python.html b/docs/python.html new file mode 100644 index 0000000000..17ac54e098 --- /dev/null +++ b/docs/python.html @@ -0,0 +1,50 @@ + + +Binding for Python

    Binding for Python

    Libvirt comes with direct support for the Python language (just make sure +you installed the libvirt-python package if not compiling from sources). 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

    virConn::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 +
      1. state: one of the state values (virDomainState)
        2. +
      2. maxMemory: the maximum memory used by the domain
        3. +
      3. memory: the current amount of memory used by the domain
        4. +
      4. nbVirtCPU: the number of virtual CPU
        5. +
      5. cpuTime: the time used by the domain in nanoseconds
        6. +
      • +

    So let's look at a simple example inspired from the basic.py +test found in python/tests/ in the source tree:

    import libvirt
+import sys
+
+conn = libvirt.openReadOnly(None)
+if conn == None:
+    print 'Failed to open connection to the hypervisor'
+    sys.exit(1)
+
+dom0 = conn.lookupByName("Domain-0")
+if dom0 == None:
+    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
      • +
    • extracting and printing some informations about the domain using + various methods + associated to the virDomain class.
      • +

    main menu

    related links

    Graphics and design by Diana Fong

    diff --git a/docs/site.xsl b/docs/site.xsl index 453fdaedff..e2aecfac4b 100644 --- a/docs/site.xsl +++ b/docs/site.xsl @@ -9,104 +9,6 @@ - - - - - intro.html - - - docs.html - - - bugs.html - - - help.html - - - help.html - - - downloads.html - - - news.html - - - contribs.html - - - format.html - - - - - - XSLT.html - - - XMLinfo.html - - - xmldtd.html - - - - - - - - - - - - - - - - - - architecture.html - - - namespaces.html - - - - - - catalog.html - - - - - - encoding.html - - - - - - - - - - - - FAQ.html - - - - - - unknown.html - - - - - - @@ -137,66 +39,15 @@ format.html - - - - - XSLT.html - - - XMLinfo.html - - - xmldtd.html - - - - - - - - - - - - - - - - architecture.html - - namespaces.html - - - - - - catalog.html - - - - - - encoding.html - - - - - - - - - + + python.html FAQ.html - - - unknown.html @@ -221,7 +72,7 @@
  • Home
    • - + @@ -267,7 +118,7 @@
  • Home
    • - + diff --git a/python/tests/Makefile.am b/python/tests/Makefile.am index 2391bad81c..6b22d7781c 100644 --- a/python/tests/Makefile.am +++ b/python/tests/Makefile.am @@ -8,7 +8,7 @@ EXTRA_DIST = $(PYTESTS) if WITH_PYTHON tests: $(PYTESTS) @echo "## running Python regression tests" - -@(PYTHONPATH="..:../src/.libs:$(srcdir)/../src:$$PYTHONPATH" ; \ + -@(PYTHONPATH="..:../.libs:../src/.libs:$(srcdir)/../src:$$PYTHONPATH";\ export PYTHONPATH; \ LD_LIBRARY_PATH="$(top_builddir)/src/.libs:$$LD_LIBRARY_PATH" ; \ export LD_LIBRARY_PATH; \