2 * Copyright (C) 2009-2011 Red Hat Inc.
4 * This program is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU General Public License as published by
6 * the Free Software Foundation; either version 2 of the License, or
7 * (at your option) any later version.
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU General Public License for more details.
14 * You should have received a copy of the GNU General Public License
15 * along with this program; if not, write to the Free Software
16 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
19 (* Please read generator/README first. *)
26 open Generator_docstrings
27 open Generator_optgroups
28 open Generator_actions
29 open Generator_structs
33 (* Generate Python C module. *)
34 let rec generate_python_c () =
35 generate_header CStyle LGPLv2plus;
44 #include \"guestfs-py.h\"
46 /* This list should be freed (but not the strings) after use. */
48 get_string_list (PyObject *obj)
52 #ifndef HAVE_PYSTRING_ASSTRING
58 if (!PyList_Check (obj)) {
59 PyErr_SetString (PyExc_RuntimeError, \"expecting a list parameter\");
63 Py_ssize_t slen = PyList_Size (obj);
65 PyErr_SetString (PyExc_RuntimeError, \"get_string_list: PyList_Size failure\");
69 r = malloc (sizeof (char *) * (len+1));
71 PyErr_SetString (PyExc_RuntimeError, \"get_string_list: out of memory\");
75 for (i = 0; i < len; ++i) {
76 #ifdef HAVE_PYSTRING_ASSTRING
77 r[i] = PyString_AsString (PyList_GetItem (obj, i));
79 bytes = PyUnicode_AsUTF8String (PyList_GetItem (obj, i));
80 r[i] = PyBytes_AS_STRING (bytes);
89 put_string_list (char * const * const argv)
94 for (argc = 0; argv[argc] != NULL; ++argc)
97 list = PyList_New (argc);
98 for (i = 0; i < argc; ++i) {
99 #ifdef HAVE_PYSTRING_ASSTRING
100 PyList_SetItem (list, i, PyString_FromString (argv[i]));
102 PyList_SetItem (list, i, PyUnicode_FromString (argv[i]));
110 put_table (char * const * const argv)
112 PyObject *list, *item;
115 for (argc = 0; argv[argc] != NULL; ++argc)
118 list = PyList_New (argc >> 1);
119 for (i = 0; i < argc; i += 2) {
120 item = PyTuple_New (2);
121 #ifdef HAVE_PYSTRING_ASSTRING
122 PyTuple_SetItem (item, 0, PyString_FromString (argv[i]));
123 PyTuple_SetItem (item, 1, PyString_FromString (argv[i+1]));
125 PyTuple_SetItem (item, 0, PyUnicode_FromString (argv[i]));
126 PyTuple_SetItem (item, 1, PyUnicode_FromString (argv[i+1]));
128 PyList_SetItem (list, i >> 1, item);
135 free_strings (char **argv)
139 for (argc = 0; argv[argc] != NULL; ++argc)
146 let emit_put_list_function typ =
147 pr "static PyObject *\n";
148 pr "put_%s_list (struct guestfs_%s_list *%ss)\n" typ typ typ;
150 pr " PyObject *list;\n";
153 pr " list = PyList_New (%ss->len);\n" typ;
154 pr " for (i = 0; i < %ss->len; ++i)\n" typ;
155 pr " PyList_SetItem (list, i, put_%s (&%ss->val[i]));\n" typ typ;
156 pr " return list;\n";
161 (* Structures, turned into Python dictionaries. *)
164 pr "static PyObject *\n";
165 pr "put_%s (struct guestfs_%s *%s)\n" typ typ typ;
167 pr " PyObject *dict;\n";
169 pr " dict = PyDict_New ();\n";
173 pr " PyDict_SetItemString (dict, \"%s\",\n" name;
174 pr "#ifdef HAVE_PYSTRING_ASSTRING\n";
175 pr " PyString_FromString (%s->%s));\n"
178 pr " PyUnicode_FromString (%s->%s));\n"
182 pr " PyDict_SetItemString (dict, \"%s\",\n" name;
183 pr "#ifdef HAVE_PYSTRING_ASSTRING\n";
184 pr " PyString_FromStringAndSize (%s->%s, %s->%s_len));\n"
187 pr " PyBytes_FromStringAndSize (%s->%s, %s->%s_len));\n"
191 pr " PyDict_SetItemString (dict, \"%s\",\n" name;
192 pr "#ifdef HAVE_PYSTRING_ASSTRING\n";
193 pr " PyString_FromStringAndSize (%s->%s, 32));\n"
196 pr " PyBytes_FromStringAndSize (%s->%s, 32));\n"
199 | name, (FBytes|FUInt64) ->
200 pr " PyDict_SetItemString (dict, \"%s\",\n" name;
201 pr " PyLong_FromUnsignedLongLong (%s->%s));\n"
204 pr " PyDict_SetItemString (dict, \"%s\",\n" name;
205 pr " PyLong_FromLongLong (%s->%s));\n"
208 pr " PyDict_SetItemString (dict, \"%s\",\n" name;
209 pr " PyLong_FromUnsignedLong (%s->%s));\n"
212 pr " PyDict_SetItemString (dict, \"%s\",\n" name;
213 pr " PyLong_FromLong (%s->%s));\n"
215 | name, FOptPercent ->
216 pr " if (%s->%s >= 0)\n" typ name;
217 pr " PyDict_SetItemString (dict, \"%s\",\n" name;
218 pr " PyFloat_FromDouble ((double) %s->%s));\n"
221 pr " Py_INCREF (Py_None);\n";
222 pr " PyDict_SetItemString (dict, \"%s\", Py_None);\n" name;
225 pr "#ifdef HAVE_PYSTRING_ASSTRING\n";
226 pr " PyDict_SetItemString (dict, \"%s\",\n" name;
227 pr " PyString_FromStringAndSize (&dirent->%s, 1));\n" name;
229 pr " PyDict_SetItemString (dict, \"%s\",\n" name;
230 pr " PyUnicode_FromStringAndSize (&dirent->%s, 1));\n" name;
233 pr " return dict;\n";
239 (* Emit a put_TYPE_list function definition only if that function is used. *)
242 | typ, (RStructListOnly | RStructAndList) ->
243 (* generate the function for typ *)
244 emit_put_list_function typ
245 | typ, _ -> () (* empty *)
246 ) (rstructs_used_by all_functions);
248 (* Python wrapper functions. *)
250 fun (name, (ret, args, optargs as style), _, _, _, _, _) ->
251 pr "static PyObject *\n";
252 pr "py_guestfs_%s (PyObject *self, PyObject *args)\n" name;
255 pr " PyThreadState *py_save = NULL;\n";
256 pr " PyObject *py_g;\n";
257 pr " guestfs_h *g;\n";
258 pr " PyObject *py_r;\n";
260 if optargs <> [] then (
261 pr " struct guestfs_%s_argv optargs_s;\n" name;
262 pr " struct guestfs_%s_argv *optargs = &optargs_s;\n" name;
266 | RErr | RInt _ | RBool _ -> pr " int r;\n"
267 | RInt64 _ -> pr " int64_t r;\n"
268 | RConstString _ | RConstOptString _ ->
269 pr " const char *r;\n"
270 | RString _ -> pr " char *r;\n"
271 | RStringList _ | RHashtable _ -> pr " char **r;\n"
272 | RStruct (_, typ) -> pr " struct guestfs_%s *r;\n" typ
273 | RStructList (_, typ) ->
274 pr " struct guestfs_%s_list *r;\n" typ
282 | Pathname n | Device n | Dev_or_Path n | String n | Key n
283 | FileIn n | FileOut n ->
284 pr " const char *%s;\n" n
285 | OptString n -> pr " const char *%s;\n" n
287 pr " const char *%s;\n" n;
288 pr " Py_ssize_t %s_size;\n" n
289 | StringList n | DeviceList n ->
290 pr " PyObject *py_%s;\n" n;
292 | Bool n -> pr " int %s;\n" n
293 | Int n -> pr " int %s;\n" n
294 | Int64 n -> pr " long long %s;\n" n
296 pr " long long %s_int64;\n" n;
300 if optargs <> [] then (
301 (* XXX This is horrible. We have to use sentinel values on the
302 * Python side to denote values not set.
304 (* Since we don't know if Python types will exactly match
305 * structure types, declare some local variables here.
310 | OInt n -> pr " int optargs_t_%s = -1;\n" n
311 | OInt64 n -> pr " long long optargs_t_%s = -1;\n" n
312 | OString n -> pr " const char *optargs_t_%s = NULL;\n" n
318 if optargs <> [] then (
319 pr " optargs_s.bitmask = 0;\n";
323 (* Convert the required parameters. *)
324 pr " if (!PyArg_ParseTuple (args, (char *) \"O";
327 | Pathname _ | Device _ | Dev_or_Path _ | String _ | Key _
328 | FileIn _ | FileOut _ -> pr "s"
329 | OptString _ -> pr "z"
330 | StringList _ | DeviceList _ -> pr "O"
331 | Bool _ -> pr "i" (* XXX Python has booleans? *)
333 | Int64 _ | Pointer _ ->
334 (* XXX Whoever thought it was a good idea to
335 * emulate C's int/long/long long in Python?
338 | BufferIn _ -> pr "s#"
341 (* Optional parameters. *)
342 if optargs <> [] then (
345 | OBool _ | OInt _ -> pr "i"
347 | OString _ -> pr "z" (* because we use None to mean not set *)
351 pr ":guestfs_%s\",\n" name;
355 | Pathname n | Device n | Dev_or_Path n | String n | Key n
356 | FileIn n | FileOut n -> pr ", &%s" n
357 | OptString n -> pr ", &%s" n
358 | StringList n | DeviceList n -> pr ", &py_%s" n
359 | Bool n -> pr ", &%s" n
360 | Int n -> pr ", &%s" n
361 | Int64 n -> pr ", &%s" n
362 | Pointer (_, n) -> pr ", &%s_int64" n
363 | BufferIn n -> pr ", &%s, &%s_size" n n
368 | OBool n | OInt n | OInt64 n | OString n -> pr ", &optargs_t_%s" n
372 pr " return NULL;\n";
374 pr " g = get_handle (py_g);\n";
377 | Pathname _ | Device _ | Dev_or_Path _ | String _ | Key _
378 | FileIn _ | FileOut _ | OptString _ | Bool _ | Int _ | Int64 _
380 | StringList n | DeviceList n ->
381 pr " %s = get_string_list (py_%s);\n" n n;
382 pr " if (!%s) return NULL;\n" n
384 pr " %s = (%s) (intptr_t) %s_int64;\n" n t n
389 if optargs <> [] then (
390 let uc_name = String.uppercase name in
393 let n = name_of_optargt argt in
394 let uc_n = String.uppercase n in
395 pr " if (optargs_t_%s != " n;
397 | OBool _ | OInt _ | OInt64 _ -> pr "-1"
398 | OString _ -> pr "NULL"
401 pr " optargs_s.%s = optargs_t_%s;\n" n n;
402 pr " optargs_s.bitmask |= GUESTFS_%s_%s_BITMASK;\n" uc_name uc_n;
408 (* Release Python GIL while running. This code is from
409 * libvirt/python/typewrappers.h. Thanks to Dan Berrange for
410 * showing us how to do this properly.
412 pr " if (PyEval_ThreadsInitialized ())\n";
413 pr " py_save = PyEval_SaveThread ();\n";
417 pr " r = guestfs_%s " name
419 pr " r = guestfs_%s_argv " name;
420 generate_c_call_args ~handle:"g" style;
424 pr " if (PyEval_ThreadsInitialized ())\n";
425 pr " PyEval_RestoreThread (py_save);\n";
430 | Pathname _ | Device _ | Dev_or_Path _ | String _ | Key _
431 | FileIn _ | FileOut _ | OptString _ | Bool _ | Int _ | Int64 _
432 | BufferIn _ | Pointer _ -> ()
433 | StringList n | DeviceList n ->
437 (match errcode_of_ret ret with
438 | `CannotReturnError -> ()
439 | `ErrorIsMinusOne ->
440 pr " if (r == -1) {\n";
441 pr " PyErr_SetString (PyExc_RuntimeError, guestfs_last_error (g));\n";
442 pr " return NULL;\n";
445 pr " if (r == NULL) {\n";
446 pr " PyErr_SetString (PyExc_RuntimeError, guestfs_last_error (g));\n";
447 pr " return NULL;\n";
454 pr " Py_INCREF (Py_None);\n";
455 pr " py_r = Py_None;\n"
457 | RBool _ -> pr " py_r = PyLong_FromLong ((long) r);\n"
458 | RInt64 _ -> pr " py_r = PyLong_FromLongLong (r);\n"
460 pr "#ifdef HAVE_PYSTRING_ASSTRING\n";
461 pr " py_r = PyString_FromString (r);\n";
463 pr " py_r = PyUnicode_FromString (r);\n";
465 | RConstOptString _ ->
467 pr "#ifdef HAVE_PYSTRING_ASSTRING\n";
468 pr " py_r = PyString_FromString (r);\n";
470 pr " py_r = PyUnicode_FromString (r);\n";
473 pr " Py_INCREF (Py_None);\n";
474 pr " py_r = Py_None;\n";
477 pr "#ifdef HAVE_PYSTRING_ASSTRING\n";
478 pr " py_r = PyString_FromString (r);\n";
480 pr " py_r = PyUnicode_FromString (r);\n";
484 pr " py_r = put_string_list (r);\n";
485 pr " free_strings (r);\n"
486 | RStruct (_, typ) ->
487 pr " py_r = put_%s (r);\n" typ;
488 pr " guestfs_free_%s (r);\n" typ
489 | RStructList (_, typ) ->
490 pr " py_r = put_%s_list (r);\n" typ;
491 pr " guestfs_free_%s_list (r);\n" typ
493 pr " py_r = put_table (r);\n";
494 pr " free_strings (r);\n"
496 pr "#ifdef HAVE_PYSTRING_ASSTRING\n";
497 pr " py_r = PyString_FromStringAndSize (r, size);\n";
499 pr " py_r = PyBytes_FromStringAndSize (r, size);\n";
504 pr " return py_r;\n";
509 (* Table of functions. *)
510 pr "static PyMethodDef methods[] = {\n";
511 pr " { (char *) \"create\", py_guestfs_create, METH_VARARGS, NULL },\n";
512 pr " { (char *) \"close\", py_guestfs_close, METH_VARARGS, NULL },\n";
513 pr " { (char *) \"set_event_callback\",\n";
514 pr " py_guestfs_set_event_callback, METH_VARARGS, NULL },\n";
515 pr " { (char *) \"delete_event_callback\",\n";
516 pr " py_guestfs_delete_event_callback, METH_VARARGS, NULL },\n";
518 fun (name, _, _, _, _, _, _) ->
519 pr " { (char *) \"%s\", py_guestfs_%s, METH_VARARGS, NULL },\n"
522 pr " { NULL, NULL, 0, NULL }\n";
528 #if PY_MAJOR_VERSION >= 3
529 static struct PyModuleDef moduledef = {
530 PyModuleDef_HEAD_INIT,
531 \"libguestfsmod\", /* m_name */
532 \"libguestfs module\", /* m_doc */
534 methods, /* m_methods */
536 NULL, /* m_traverse */
547 #if PY_MAJOR_VERSION >= 3
548 m = PyModule_Create (&moduledef);
550 m = Py_InitModule ((char *) \"libguestfsmod\", methods);
553 return m; /* m might be NULL if module init failed */
556 #if PY_MAJOR_VERSION >= 3
558 PyInit_libguestfsmod (void)
560 return moduleinit ();
564 initlibguestfsmod (void)
566 (void) moduleinit ();
571 (* Generate Python module. *)
572 and generate_python_py () =
573 generate_header HashStyle LGPLv2plus;
576 \"\"\"Python bindings for libguestfs
579 g = guestfs.GuestFS ()
580 g.add_drive_opts (\"guest.img\", format=\"raw\")
582 parts = g.list_partitions ()
584 The guestfs module provides a Python binding to the libguestfs API
585 for examining and modifying virtual machine disk images.
587 Amongst the things this is good for: making batch configuration
588 changes to guests, getting disk used/free statistics (see also:
589 virt-df), migrating between virtualization systems (see also:
590 virt-p2v), performing partial backups, performing partial guest
591 clones, cloning guests and changing registry/UUID/hostname info, and
594 Libguestfs uses Linux kernel and qemu code, and can access any type of
595 guest filesystem that Linux and qemu can, including but not limited
596 to: ext2/3/4, btrfs, FAT and NTFS, LVM, many different disk partition
597 schemes, qcow, qcow2, vmdk.
599 Libguestfs provides ways to enumerate guest storage (eg. partitions,
600 LVs, what filesystem is in each LV, etc.). It can also run commands
601 in the context of the guest. Also you can access filesystems over
604 Errors which happen while using the API are turned into Python
605 RuntimeError exceptions.
607 To create a guestfs handle you usually have to perform the following
610 # Create the handle, call add_drive* at least once, and possibly
611 # several times if the guest has multiple block devices:
612 g = guestfs.GuestFS ()
613 g.add_drive_opts (\"guest.img\", format=\"raw\")
615 # Launch the qemu subprocess and wait for it to become ready:
618 # Now you can issue commands, for example:
628 fun (name, bitmask) ->
629 pr "EVENT_%s = 0x%x\n" (String.uppercase name) bitmask
634 class ClosedHandle(ValueError):
638 \"\"\"Instances of this class are libguestfs API handles.\"\"\"
641 \"\"\"Create a new libguestfs handle.\"\"\"
642 self._o = libguestfsmod.create ()
646 libguestfsmod.close (self._o)
648 def _check_not_closed (self):
650 raise ClosedHandle (\"GuestFS: method called on closed handle\")
653 \"\"\"Explicitly close the guestfs handle.
655 The handle is closed implicitly when its reference count goes
656 to zero (eg. when it goes out of scope or the program ends).
658 This call is only needed if you want to force the handle to
659 close now. After calling this, the program must not call
660 any method on the handle (except the implicit call to
661 __del__ which happens when the final reference is cleaned up).
663 self._check_not_closed ()
664 libguestfsmod.close (self._o)
667 def set_event_callback (self, cb, event_bitmask):
668 \"\"\"Register an event callback.
670 Register \"cb\" as a callback function for all of the
671 events in \"event_bitmask\". \"event_bitmask\" should be
672 one or more \"guestfs.EVENT_*\" flags logically or'd together.
674 This function returns an event handle which can be used
675 to delete the callback (see \"delete_event_callback\").
677 The callback function receives 4 parameters:
679 cb (event, event_handle, buf, array)
681 \"event\" is one of the \"EVENT_*\" flags. \"buf\" is a
682 message buffer (only for some types of events). \"array\"
683 is an array of integers (only for some types of events).
685 You should read the documentation for
686 \"guestfs_set_event_callback\" in guestfs(3) before using
689 self._check_not_closed ()
690 return libguestfsmod.set_event_callback (self._o, cb, event_bitmask)
692 def delete_event_callback (self, event_handle):
693 \"\"\"Delete an event callback.\"\"\"
694 self._check_not_closed ()
695 libguestfsmod.delete_event_callback (self._o, event_handle)
700 fun (name, (ret, args, optargs), _, flags, _, _, longdesc) ->
701 pr " def %s (self" name;
702 List.iter (fun arg -> pr ", %s" (name_of_argt arg)) args;
705 | OBool n | OInt n | OInt64 n -> pr ", %s=-1" n
706 | OString n -> pr ", %s=None" n
710 if not (List.mem NotInDocs flags) then (
711 let doc = replace_str longdesc "C<guestfs_" "C<g." in
714 | RErr | RInt _ | RInt64 _ | RBool _
715 | RConstOptString _ | RConstString _
716 | RString _ | RBufferOut _ -> doc
718 doc ^ "\n\nThis function returns a list of strings."
719 | RStruct (_, typ) ->
720 doc ^ sprintf "\n\nThis function returns a dictionary, with keys matching the various fields in the guestfs_%s structure." typ
721 | RStructList (_, typ) ->
722 doc ^ sprintf "\n\nThis function returns a list of %ss. Each %s is represented as a dictionary." typ typ
724 doc ^ "\n\nThis function returns a dictionary." in
726 if List.mem ProtocolLimitWarning flags then
727 doc ^ "\n\n" ^ protocol_limit_warning
730 match deprecation_notice flags with
732 | Some txt -> doc ^ "\n\n" ^ txt in
733 let doc = pod2text ~width:60 name doc in
734 let doc = List.map (fun line -> replace_str line "\\" "\\\\") doc in
735 let doc = String.concat "\n " doc in
736 pr " \"\"\"%s\"\"\"\n" doc;
738 (* Callers might pass in iterables instead of plain lists;
739 * convert those to plain lists because the C side of things
740 * cannot deal with iterables. (RHBZ#693306).
744 | Pathname _ | Device _ | Dev_or_Path _ | String _ | Key _
745 | FileIn _ | FileOut _ | OptString _ | Bool _ | Int _ | Int64 _
746 | BufferIn _ | Pointer _ -> ()
747 | StringList n | DeviceList n ->
748 pr " %s = list (%s)\n" n n
750 pr " self._check_not_closed ()\n";
751 pr " return libguestfsmod.%s (self._o" name;
752 List.iter (fun arg -> pr ", %s" (name_of_argt arg))
753 (args @ args_of_optargs optargs);