From: Richard W.M. Jones Date: Wed, 24 Nov 2010 18:10:50 +0000 (+0000) Subject: python: Translate C examples into Python and include documentation. X-Git-Tag: 1.7.13~3 X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=commitdiff_plain;h=472722a72df89895bb11a1244eafa7915b1af116 python: Translate C examples into Python and include documentation. --- diff --git a/.gitignore b/.gitignore index 76351e3..1f97d7b 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 77f01c6..8371984 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 352bfe8..f3235c3 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 858ac61..aa81e8a 100644 --- a/examples/guestfs-examples.pod +++ b/examples/guestfs-examples.pod @@ -34,6 +34,7 @@ libguestfs, you also need to read L. L, L, +L, L, L. diff --git a/ocaml/examples/guestfs-ocaml.pod b/ocaml/examples/guestfs-ocaml.pod index 9f289f0..da09135 100644 --- a/ocaml/examples/guestfs-ocaml.pod +++ b/ocaml/examples/guestfs-ocaml.pod @@ -79,6 +79,7 @@ function that you called. L, L, +L, L, L. diff --git a/python/examples/LICENSE b/python/examples/LICENSE new file mode 100644 index 0000000..111ee48 --- /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 0000000..208fecd --- /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 0000000..9d4e8d9 --- /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 0000000..49ff787 --- /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. + +=head2 EXCEPTIONS + +Errors from libguestfs functions are mapped into C +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, +L, +L, +L. + +=head1 AUTHORS + +Richard W.M. Jones (C) + +=head1 COPYRIGHT + +Copyright (C) 2010 Red Hat Inc. L + +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 0000000..0ba6e3e --- /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 3f40d76..a8e530f 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 -For documentation do: - - $ python - >>> import guestfs - >>> help (guestfs) +For documentation see L. =item B @@ -2088,6 +2084,7 @@ enough. L, L, +L, L, L, L,