python: Translate C examples into Python and include documentation.

11 files changed, 241 insertions, 7 deletions

diff --git a/.gitignore b/.gitignore
index 76351e3d..1f97d7b6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -117,6 +117,7 @@ html/guestfish.1.html
 html/guestfs.3.html
 html/guestfs-examples.3.html
 html/guestfs-ocaml.3.html
+html/guestfs-python.3.html
 html/guestmount.1.html
 html/recipes.html
 html/virt-cat.1.html
@@ -267,6 +268,8 @@ po-docs/*/*.1
 po-docs/*/*.3
 podwrapper.sh
 python/bindtests.py
+python/examples/guestfs-python.3
+python/examples/stamp-guestfs-python.pod
 python/guestfs.py
 python/guestfs-py.c
 python/guestfs.pyc
diff --git a/Makefile.am b/Makefile.am
index 77f01c6e..83719844 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -46,7 +46,7 @@ if HAVE_OCAML
 SUBDIRS += ocaml ocaml/examples
 endif
 if HAVE_PYTHON
-SUBDIRS += python
+SUBDIRS += python python/examples
 endif
 if HAVE_RUBY
 SUBDIRS += ruby
@@ -104,6 +104,7 @@ HTMLFILES = \
 	html/guestfs.3.html \
 	html/guestfs-examples.3.html \
 	html/guestfs-ocaml.3.html \
+	html/guestfs-python.3.html \
 	html/guestfish.1.html \
 	html/guestmount.1.html \
 	html/virt-cat.1.html \
diff --git a/configure.ac b/configure.ac
index 352bfe86..f3235c37 100644
--- a/configure.ac
+++ b/configure.ac
@@ -853,7 +853,7 @@ AC_CONFIG_FILES([Makefile
                  test-tool/Makefile
                  ocaml/Makefile ocaml/examples/Makefile
                  perl/Makefile
-                 python/Makefile
+                 python/Makefile python/examples/Makefile
                  ruby/Makefile ruby/Rakefile
                  java/Makefile
                  haskell/Makefile
diff --git a/examples/guestfs-examples.pod b/examples/guestfs-examples.pod
index 858ac61e..aa81e8a9 100644
--- a/examples/guestfs-examples.pod
+++ b/examples/guestfs-examples.pod
@@ -34,6 +34,7 @@ libguestfs, you also need to read L<guestfs(3)>.
 
 L<guestfs(3)>,
 L<guestfs-ocaml(3)>,
+L<guestfs-python(3)>,
 L<http://libguestfs.org/>,
 L<http://caml.inria.fr/>.
 
diff --git a/ocaml/examples/guestfs-ocaml.pod b/ocaml/examples/guestfs-ocaml.pod
index 9f289f02..da091359 100644
--- a/ocaml/examples/guestfs-ocaml.pod
+++ b/ocaml/examples/guestfs-ocaml.pod
@@ -79,6 +79,7 @@ function that you called.
 
 L<guestfs(3)>,
 L<guestfs-examples(3)>,
+L<guestfs-python(3)>,
 L<http://libguestfs.org/>,
 L<http://caml.inria.fr/>.
 
diff --git a/python/examples/LICENSE b/python/examples/LICENSE
new file mode 100644
index 00000000..111ee481
--- /dev/null
+++ b/python/examples/LICENSE
@@ -0,0 +1,2 @@
+All the examples in the 'python/examples' subdirectory may be freely
+copied, modified and distributed without any restrictions.
diff --git a/python/examples/Makefile.am b/python/examples/Makefile.am
new file mode 100644
index 00000000..208fecd8
--- /dev/null
+++ b/python/examples/Makefile.am
@@ -0,0 +1,39 @@
+# libguestfs Python examples
+# Copyright (C) 2010 Red Hat Inc.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+
+EXTRA_DIST = \
+	LICENSE \
+	create_disk.py \
+	inspect_vm.py \
+	guestfs-python.pod
+
+CLEANFILES = *.pyc *.pyo stamp-guestfs-python.pod
+
+man_MANS = guestfs-python.3
+noinst_DATA = $(top_builddir)/html/guestfs-python.3.html
+
+guestfs-python.3 $(top_builddir)/html/guestfs-python.3.html: stamp-guestfs-python.pod
+
+stamp-guestfs-python.pod: guestfs-python.pod create_disk.py inspect_vm.py
+	$(top_srcdir)/podwrapper.sh \
+	  --section 3 \
+	  --man guestfs-python.3 \
+	  --html $(top_builddir)/html/guestfs-python.3.html \
+	  --verbatim create_disk.py:@EXAMPLE1@ \
+	  --verbatim inspect_vm.py:@EXAMPLE2@ \
+	  $<
+	touch $@
diff --git a/python/examples/create_disk.py b/python/examples/create_disk.py
new file mode 100644
index 00000000..9d4e8d9b
--- /dev/null
+++ b/python/examples/create_disk.py
@@ -0,0 +1,61 @@
+# Example showing how to create a disk image.
+
+import os
+import guestfs
+
+output = "disk.img"
+
+g = guestfs.GuestFS ()
+
+# Create a raw-format sparse disk image, 512 MB in size.
+f = open (output, "w")
+f.truncate (512 * 1024 * 1024)
+f.close ()
+
+# Set the trace flag so that we can see each libguestfs call.
+g.set_trace (1)
+
+# Set the autosync flag so that the disk will be synchronized
+# automatically when the libguestfs handle is closed.
+g.set_autosync (1)
+
+# Attach the disk image to libguestfs.
+g.add_drive_opts (output, format = "raw", readonly = 0)
+
+# Run the libguestfs back-end.
+g.launch ()
+
+# Get the list of devices.  Because we only added one drive
+# above, we expect that this list should contain a single
+# element.
+devices = g.list_devices ()
+assert (len (devices) == 1)
+
+# Partition the disk as one single MBR partition.
+g.part_disk (devices[0], "mbr")
+
+# Get the list of partitions.  We expect a single element, which
+# is the partition we have just created.
+partitions = g.list_partitions ()
+assert (len (partitions) == 1)
+
+# Create a filesystem on the partition.
+g.mkfs ("ext4", partitions[0])
+
+# Now mount the filesystem so that we can add files.
+g.mount_options ("", partitions[0], "/")
+
+# Create some files and directories.
+g.touch ("/empty")
+message = "Hello, world\n"
+g.write ("/hello", message)
+g.mkdir ("/foo")
+
+# This one uploads the local file /etc/resolv.conf into
+# the disk image.
+g.upload ("/etc/resolv.conf", "/foo/resolv.conf")
+
+# Because 'autosync' was set (above) we can just close the handle
+# and the disk contents will be synchronized.  You can also do
+# this manually by calling g.umount_all and g.sync.
+del g
diff --git a/python/examples/guestfs-python.pod b/python/examples/guestfs-python.pod
new file mode 100644
index 00000000..49ff7878
--- /dev/null
+++ b/python/examples/guestfs-python.pod
@@ -0,0 +1,72 @@
+=encoding utf8
+
+=head1 NAME
+
+guestfs-python - How to use libguestfs from Python
+
+=head1 SYNOPSIS
+
+ import guestfs
+ g = guestfs.GuestFS ()
+ g.add_drive_opts ("disk.img", format="raw", readonly=1)
+ g.launch
+
+=head1 DESCRIPTION
+
+This manual page documents how to call libguestfs from the Python
+programming language.  This page just documents the differences from
+the C API and gives some examples.  If you are not familiar with using
+libguestfs, you also need to read L<guestfs(3)>.
+
+=head2 EXCEPTIONS
+
+Errors from libguestfs functions are mapped into C<RuntimeException>
+with a single string argument which is the error message.
+
+=head2 MORE DOCUMENTATION
+
+Type:
+
+ $ python
+ >>> import guestfs
+ >>> help (guestfs)
+
+=head1 EXAMPLE 1: CREATE A DISK IMAGE
+
+@EXAMPLE1@
+
+=head1 EXAMPLE 2: INSPECT A VIRTUAL MACHINE DISK IMAGE
+
+@EXAMPLE2@
+
+=head1 SEE ALSO
+
+L<guestfs(3)>,
+L<guestfs-examples(3)>,
+L<guestfs-ocaml(3)>,
+L<http://libguestfs.org/>.
+
+=head1 AUTHORS
+
+Richard W.M. Jones (C<rjones at redhat dot com>)
+
+=head1 COPYRIGHT
+
+Copyright (C) 2010 Red Hat Inc. L<http://libguestfs.org/>
+
+The examples in this manual page may be freely copied, modified and
+distributed without any restrictions.
+
+This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2 of the License, or (at your option) any later version.
+
+This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
diff --git a/python/examples/inspect_vm.py b/python/examples/inspect_vm.py
new file mode 100644
index 00000000..0ba6e3e9
--- /dev/null
+++ b/python/examples/inspect_vm.py
@@ -0,0 +1,57 @@
+# Example showing how to inspect a virtual machine disk.
+
+import sys
+import guestfs
+
+assert (len (sys.argv) == 2)
+disk = sys.argv[1]
+
+g = guestfs.GuestFS ()
+
+# Attach the disk image read-only to libguestfs.
+g.add_drive_opts (disk, readonly=1)
+
+# Run the libguestfs back-end.
+g.launch ()
+
+# Ask libguestfs to inspect for operating systems.
+roots = g.inspect_os ()
+if len (roots) == 0:
+    raise (Error ("inspect_vm: no operating systems found"))
+
+for root in roots:
+    print "Root device: %s" % root
+
+    # Print basic information about the operating system.
+    print "  Product name: %s" % (g.inspect_get_product_name (root))
+    print "  Version:      %d.%d" % \
+        (g.inspect_get_major_version (root),
+         g.inspect_get_minor_version (root))
+    print "  Type:         %s" % (g.inspect_get_type (root))
+    print "  Distro:       %s" % (g.inspect_get_distro (root))
+
+    # Mount up the disks, like guestfish -i.
+    #
+    # Sort keys by length, shortest first, so that we end up
+    # mounting the filesystems in the correct order.
+    mps = g.inspect_get_mountpoints (root)
+    def compare (a, b):
+        if len(a[0]) > len(b[0]):
+            return 1
+        elif len(a[0]) == len(b[0]):
+            return 0
+        else:
+            return -1
+    mps.sort (compare)
+    for mp_dev in mps:
+        g.mount_ro (mp_dev[1], mp_dev[0])
+
+    # If /etc/issue.net file exists, print up to 3 lines.
+    filename = "/etc/issue.net"
+    if g.is_file (filename):
+        print "--- %s ---" % filename
+        lines = g.head_n (3, filename)
+        for line in lines: print line
+
+    # Unmount everything.
+    g.umount_all ()
diff --git a/src/guestfs.pod b/src/guestfs.pod
index 3f40d765..a8e530f0 100644
--- a/src/guestfs.pod
+++ b/src/guestfs.pod
@@ -672,11 +672,7 @@ The PHP binding only works correctly on 64 bit machines.
 
 =item B<Python>
 
-For documentation do:
-
- $ python
- >>> import guestfs
- >>> help (guestfs)
+For documentation see L<guestfs-python(3)>.
 
 =item B<Ruby>
 
@@ -2088,6 +2084,7 @@ enough.
 
 L<guestfs-examples(3)>,
 L<guestfs-ocaml(3)>,
+L<guestfs-python(3)>,
 L<guestfish(1)>,
 L<guestmount(1)>,
 L<virt-cat(1)>,