NFC: Allow multiple config files in inspect_with_augeas in inspect_fs_unix.c
[libguestfs.git] / generator / generator_python.ml
1 (* libguestfs
2  * Copyright (C) 2009-2011 Red Hat Inc.
3  *
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.
8  *
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.
13  *
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
17  *)
18
19 (* Please read generator/README first. *)
20
21 open Printf
22
23 open Generator_types
24 open Generator_utils
25 open Generator_pr
26 open Generator_docstrings
27 open Generator_optgroups
28 open Generator_actions
29 open Generator_structs
30 open Generator_c
31 open Generator_events
32
33 (* Generate Python C module. *)
34 let rec generate_python_c () =
35   generate_header CStyle LGPLv2plus;
36
37   pr "\
38 #include <config.h>
39
40 #include <stdio.h>
41 #include <stdlib.h>
42 #include <assert.h>
43
44 #include \"guestfs-py.h\"
45
46 /* This list should be freed (but not the strings) after use. */
47 static char **
48 get_string_list (PyObject *obj)
49 {
50   size_t i, len;
51   char **r;
52 #ifndef HAVE_PYSTRING_ASSTRING
53   PyObject *bytes;
54 #endif
55
56   assert (obj);
57
58   if (!PyList_Check (obj)) {
59     PyErr_SetString (PyExc_RuntimeError, \"expecting a list parameter\");
60     return NULL;
61   }
62
63   Py_ssize_t slen = PyList_Size (obj);
64   if (slen == -1) {
65     PyErr_SetString (PyExc_RuntimeError, \"get_string_list: PyList_Size failure\");
66     return NULL;
67   }
68   len = (size_t) slen;
69   r = malloc (sizeof (char *) * (len+1));
70   if (r == NULL) {
71     PyErr_SetString (PyExc_RuntimeError, \"get_string_list: out of memory\");
72     return NULL;
73   }
74
75   for (i = 0; i < len; ++i) {
76 #ifdef HAVE_PYSTRING_ASSTRING
77     r[i] = PyString_AsString (PyList_GetItem (obj, i));
78 #else
79     bytes = PyUnicode_AsUTF8String (PyList_GetItem (obj, i));
80     r[i] = PyBytes_AS_STRING (bytes);
81 #endif
82   }
83   r[len] = NULL;
84
85   return r;
86 }
87
88 static PyObject *
89 put_string_list (char * const * const argv)
90 {
91   PyObject *list;
92   int argc, i;
93
94   for (argc = 0; argv[argc] != NULL; ++argc)
95     ;
96
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]));
101 #else
102     PyList_SetItem (list, i, PyUnicode_FromString (argv[i]));
103 #endif
104   }
105
106   return list;
107 }
108
109 static PyObject *
110 put_table (char * const * const argv)
111 {
112   PyObject *list, *item;
113   int argc, i;
114
115   for (argc = 0; argv[argc] != NULL; ++argc)
116     ;
117
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]));
124 #else
125     PyTuple_SetItem (item, 0, PyUnicode_FromString (argv[i]));
126     PyTuple_SetItem (item, 1, PyUnicode_FromString (argv[i+1]));
127 #endif
128     PyList_SetItem (list, i >> 1, item);
129   }
130
131   return list;
132 }
133
134 static void
135 free_strings (char **argv)
136 {
137   int argc;
138
139   for (argc = 0; argv[argc] != NULL; ++argc)
140     free (argv[argc]);
141   free (argv);
142 }
143
144 ";
145
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;
149     pr "{\n";
150     pr "  PyObject *list;\n";
151     pr "  size_t i;\n";
152     pr "\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";
157     pr "};\n";
158     pr "\n"
159   in
160
161   (* Structures, turned into Python dictionaries. *)
162   List.iter (
163     fun (typ, cols) ->
164       pr "static PyObject *\n";
165       pr "put_%s (struct guestfs_%s *%s)\n" typ typ typ;
166       pr "{\n";
167       pr "  PyObject *dict;\n";
168       pr "\n";
169       pr "  dict = PyDict_New ();\n";
170       List.iter (
171         function
172         | name, FString ->
173             pr "  PyDict_SetItemString (dict, \"%s\",\n" name;
174             pr "#ifdef HAVE_PYSTRING_ASSTRING\n";
175             pr "                        PyString_FromString (%s->%s));\n"
176               typ name;
177             pr "#else\n";
178             pr "                        PyUnicode_FromString (%s->%s));\n"
179               typ name;
180             pr "#endif\n"
181         | name, FBuffer ->
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"
185               typ name typ name;
186             pr "#else\n";
187             pr "                        PyBytes_FromStringAndSize (%s->%s, %s->%s_len));\n"
188               typ name typ name;
189             pr "#endif\n"
190         | name, FUUID ->
191             pr "  PyDict_SetItemString (dict, \"%s\",\n" name;
192             pr "#ifdef HAVE_PYSTRING_ASSTRING\n";
193             pr "                        PyString_FromStringAndSize (%s->%s, 32));\n"
194               typ name;
195             pr "#else\n";
196             pr "                        PyBytes_FromStringAndSize (%s->%s, 32));\n"
197               typ name;
198             pr "#endif\n"
199         | name, (FBytes|FUInt64) ->
200             pr "  PyDict_SetItemString (dict, \"%s\",\n" name;
201             pr "                        PyLong_FromUnsignedLongLong (%s->%s));\n"
202               typ name
203         | name, FInt64 ->
204             pr "  PyDict_SetItemString (dict, \"%s\",\n" name;
205             pr "                        PyLong_FromLongLong (%s->%s));\n"
206               typ name
207         | name, FUInt32 ->
208             pr "  PyDict_SetItemString (dict, \"%s\",\n" name;
209             pr "                        PyLong_FromUnsignedLong (%s->%s));\n"
210               typ name
211         | name, FInt32 ->
212             pr "  PyDict_SetItemString (dict, \"%s\",\n" name;
213             pr "                        PyLong_FromLong (%s->%s));\n"
214               typ name
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"
219               typ name;
220             pr "  else {\n";
221             pr "    Py_INCREF (Py_None);\n";
222             pr "    PyDict_SetItemString (dict, \"%s\", Py_None);\n" name;
223             pr "  }\n"
224         | name, FChar ->
225             pr "#ifdef HAVE_PYSTRING_ASSTRING\n";
226             pr "  PyDict_SetItemString (dict, \"%s\",\n" name;
227             pr "                        PyString_FromStringAndSize (&dirent->%s, 1));\n" name;
228             pr "#else\n";
229             pr "  PyDict_SetItemString (dict, \"%s\",\n" name;
230             pr "                        PyUnicode_FromStringAndSize (&dirent->%s, 1));\n" name;
231             pr "#endif\n"
232       ) cols;
233       pr "  return dict;\n";
234       pr "};\n";
235       pr "\n";
236
237   ) structs;
238
239   (* Emit a put_TYPE_list function definition only if that function is used. *)
240   List.iter (
241     function
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);
247
248   (* Python wrapper functions. *)
249   List.iter (
250     fun (name, (ret, args, optargs as style), _, _, _, _, _) ->
251       pr "static PyObject *\n";
252       pr "py_guestfs_%s (PyObject *self, PyObject *args)\n" name;
253       pr "{\n";
254
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";
259
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;
263       );
264
265       (match ret with
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
275        | RBufferOut _ ->
276            pr "  char *r;\n";
277            pr "  size_t size;\n"
278       );
279
280       List.iter (
281         function
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
286         | BufferIn 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;
291             pr "  char **%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
295         | Pointer (t, n) ->
296             pr "  long long %s_int64;\n" n;
297             pr "  %s %s;\n" t n
298       ) args;
299
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.
303          *)
304         (* Since we don't know if Python types will exactly match
305          * structure types, declare some local variables here.
306          *)
307         List.iter (
308           function
309           | Bool n
310           | Int n -> pr "  int optargs_t_%s = -1;\n" n
311           | Int64 n -> pr "  long long optargs_t_%s = -1;\n" n
312           | String n -> pr "  const char *optargs_t_%s = NULL;\n" n
313           | _ -> assert false
314         ) optargs
315       );
316
317       pr "\n";
318
319       if optargs <> [] then (
320         pr "  optargs_s.bitmask = 0;\n";
321         pr "\n"
322       );
323
324       (* Convert the required parameters. *)
325       pr "  if (!PyArg_ParseTuple (args, (char *) \"O";
326       List.iter (
327         function
328         | Pathname _ | Device _ | Dev_or_Path _ | String _ | Key _
329         | FileIn _ | FileOut _ -> pr "s"
330         | OptString _ -> pr "z"
331         | StringList _ | DeviceList _ -> pr "O"
332         | Bool _ -> pr "i" (* XXX Python has booleans? *)
333         | Int _ -> pr "i"
334         | Int64 _ | Pointer _ ->
335             (* XXX Whoever thought it was a good idea to
336              * emulate C's int/long/long long in Python?
337              *)
338             pr "L"
339         | BufferIn _ -> pr "s#"
340       ) args;
341
342       (* Optional parameters. *)
343       if optargs <> [] then (
344         List.iter (
345           function
346           | Bool _ | Int _ -> pr "i"
347           | Int64 _ -> pr "L"
348           | String _ -> pr "z" (* because we use None to mean not set *)
349           | _ -> assert false
350         ) optargs;
351       );
352
353       pr ":guestfs_%s\",\n" name;
354       pr "                         &py_g";
355       List.iter (
356         function
357         | Pathname n | Device n | Dev_or_Path n | String n | Key n
358         | FileIn n | FileOut n -> pr ", &%s" n
359         | OptString n -> pr ", &%s" n
360         | StringList n | DeviceList n -> pr ", &py_%s" n
361         | Bool n -> pr ", &%s" n
362         | Int n -> pr ", &%s" n
363         | Int64 n -> pr ", &%s" n
364         | Pointer (_, n) -> pr ", &%s_int64" n
365         | BufferIn n -> pr ", &%s, &%s_size" n n
366       ) args;
367
368       List.iter (
369         function
370         | Bool n | Int n | Int64 n | String n -> pr ", &optargs_t_%s" n
371         | _ -> assert false
372       ) optargs;
373
374       pr "))\n";
375       pr "    return NULL;\n";
376
377       pr "  g = get_handle (py_g);\n";
378       List.iter (
379         function
380         | Pathname _ | Device _ | Dev_or_Path _ | String _ | Key _
381         | FileIn _ | FileOut _ | OptString _ | Bool _ | Int _ | Int64 _
382         | BufferIn _ -> ()
383         | StringList n | DeviceList n ->
384             pr "  %s = get_string_list (py_%s);\n" n n;
385             pr "  if (!%s) return NULL;\n" n
386         | Pointer (t, n) ->
387             pr "  %s = (%s) (intptr_t) %s_int64;\n" n t n
388       ) args;
389
390       pr "\n";
391
392       if optargs <> [] then (
393         let uc_name = String.uppercase name in
394         List.iter (
395           fun argt ->
396             let n = name_of_argt argt in
397             let uc_n = String.uppercase n in
398             pr "  if (optargs_t_%s != " n;
399             (match argt with
400              | Bool _ | Int _ | Int64 _ -> pr "-1"
401              | String _ -> pr "NULL"
402              | _ -> assert false
403             );
404             pr ") {\n";
405             pr "    optargs_s.%s = optargs_t_%s;\n" n n;
406             pr "    optargs_s.bitmask |= GUESTFS_%s_%s_BITMASK;\n" uc_name uc_n;
407             pr "  }\n"
408         ) optargs;
409         pr "\n"
410       );
411
412       (* Release Python GIL while running.  This code is from
413        * libvirt/python/typewrappers.h.  Thanks to Dan Berrange for
414        * showing us how to do this properly.
415        *)
416       pr "  if (PyEval_ThreadsInitialized ())\n";
417       pr "    py_save = PyEval_SaveThread ();\n";
418       pr "\n";
419
420       if optargs = [] then
421         pr "  r = guestfs_%s " name
422       else
423         pr "  r = guestfs_%s_argv " name;
424       generate_c_call_args ~handle:"g" style;
425       pr ";\n";
426
427       pr "\n";
428       pr "  if (PyEval_ThreadsInitialized ())\n";
429       pr "    PyEval_RestoreThread (py_save);\n";
430       pr "\n";
431
432       List.iter (
433         function
434         | Pathname _ | Device _ | Dev_or_Path _ | String _ | Key _
435         | FileIn _ | FileOut _ | OptString _ | Bool _ | Int _ | Int64 _
436         | BufferIn _ | Pointer _ -> ()
437         | StringList n | DeviceList n ->
438             pr "  free (%s);\n" n
439       ) args;
440
441       (match errcode_of_ret ret with
442        | `CannotReturnError -> ()
443        | `ErrorIsMinusOne ->
444            pr "  if (r == -1) {\n";
445            pr "    PyErr_SetString (PyExc_RuntimeError, guestfs_last_error (g));\n";
446            pr "    return NULL;\n";
447            pr "  }\n"
448        | `ErrorIsNULL ->
449            pr "  if (r == NULL) {\n";
450            pr "    PyErr_SetString (PyExc_RuntimeError, guestfs_last_error (g));\n";
451            pr "    return NULL;\n";
452            pr "  }\n"
453       );
454       pr "\n";
455
456       (match ret with
457        | RErr ->
458            pr "  Py_INCREF (Py_None);\n";
459            pr "  py_r = Py_None;\n"
460        | RInt _
461        | RBool _ -> pr "  py_r = PyLong_FromLong ((long) r);\n"
462        | RInt64 _ -> pr "  py_r = PyLong_FromLongLong (r);\n"
463        | RConstString _ ->
464            pr "#ifdef HAVE_PYSTRING_ASSTRING\n";
465            pr "  py_r = PyString_FromString (r);\n";
466            pr "#else\n";
467            pr "  py_r = PyUnicode_FromString (r);\n";
468            pr "#endif\n"
469        | RConstOptString _ ->
470            pr "  if (r) {\n";
471            pr "#ifdef HAVE_PYSTRING_ASSTRING\n";
472            pr "    py_r = PyString_FromString (r);\n";
473            pr "#else\n";
474            pr "    py_r = PyUnicode_FromString (r);\n";
475            pr "#endif\n";
476            pr "  } else {\n";
477            pr "    Py_INCREF (Py_None);\n";
478            pr "    py_r = Py_None;\n";
479            pr "  }\n"
480        | RString _ ->
481            pr "#ifdef HAVE_PYSTRING_ASSTRING\n";
482            pr "  py_r = PyString_FromString (r);\n";
483            pr "#else\n";
484            pr "  py_r = PyUnicode_FromString (r);\n";
485            pr "#endif\n";
486            pr "  free (r);\n"
487        | RStringList _ ->
488            pr "  py_r = put_string_list (r);\n";
489            pr "  free_strings (r);\n"
490        | RStruct (_, typ) ->
491            pr "  py_r = put_%s (r);\n" typ;
492            pr "  guestfs_free_%s (r);\n" typ
493        | RStructList (_, typ) ->
494            pr "  py_r = put_%s_list (r);\n" typ;
495            pr "  guestfs_free_%s_list (r);\n" typ
496        | RHashtable n ->
497            pr "  py_r = put_table (r);\n";
498            pr "  free_strings (r);\n"
499        | RBufferOut _ ->
500            pr "#ifdef HAVE_PYSTRING_ASSTRING\n";
501            pr "  py_r = PyString_FromStringAndSize (r, size);\n";
502            pr "#else\n";
503            pr "  py_r = PyBytes_FromStringAndSize (r, size);\n";
504            pr "#endif\n";
505            pr "  free (r);\n"
506       );
507
508       pr "  return py_r;\n";
509       pr "}\n";
510       pr "\n"
511   ) all_functions;
512
513   (* Table of functions. *)
514   pr "static PyMethodDef methods[] = {\n";
515   pr "  { (char *) \"create\", py_guestfs_create, METH_VARARGS, NULL },\n";
516   pr "  { (char *) \"close\", py_guestfs_close, METH_VARARGS, NULL },\n";
517   pr "  { (char *) \"set_event_callback\",\n";
518   pr "    py_guestfs_set_event_callback, METH_VARARGS, NULL },\n";
519   pr "  { (char *) \"delete_event_callback\",\n";
520   pr "    py_guestfs_delete_event_callback, METH_VARARGS, NULL },\n";
521   List.iter (
522     fun (name, _, _, _, _, _, _) ->
523       pr "  { (char *) \"%s\", py_guestfs_%s, METH_VARARGS, NULL },\n"
524         name name
525   ) all_functions;
526   pr "  { NULL, NULL, 0, NULL }\n";
527   pr "};\n";
528   pr "\n";
529
530   (* Init function. *)
531   pr "\
532 #if PY_MAJOR_VERSION >= 3
533 static struct PyModuleDef moduledef = {
534   PyModuleDef_HEAD_INIT,
535   \"libguestfsmod\",     /* m_name */
536   \"libguestfs module\",   /* m_doc */
537   -1,                    /* m_size */
538   methods,               /* m_methods */
539   NULL,                  /* m_reload */
540   NULL,                  /* m_traverse */
541   NULL,                  /* m_clear */
542   NULL,                  /* m_free */
543 };
544 #endif
545
546 static PyObject *
547 moduleinit (void)
548 {
549   PyObject *m;
550
551 #if PY_MAJOR_VERSION >= 3
552   m = PyModule_Create (&moduledef);
553 #else
554   m = Py_InitModule ((char *) \"libguestfsmod\", methods);
555 #endif
556
557   return m; /* m might be NULL if module init failed */
558 }
559
560 #if PY_MAJOR_VERSION >= 3
561 PyMODINIT_FUNC
562 PyInit_libguestfsmod (void)
563 {
564   return moduleinit ();
565 }
566 #else
567 void
568 initlibguestfsmod (void)
569 {
570   (void) moduleinit ();
571 }
572 #endif
573 "
574
575 (* Generate Python module. *)
576 and generate_python_py () =
577   generate_header HashStyle LGPLv2plus;
578
579   pr "\
580 \"\"\"Python bindings for libguestfs
581
582 import guestfs
583 g = guestfs.GuestFS ()
584 g.add_drive_opts (\"guest.img\", format=\"raw\")
585 g.launch ()
586 parts = g.list_partitions ()
587
588 The guestfs module provides a Python binding to the libguestfs API
589 for examining and modifying virtual machine disk images.
590
591 Amongst the things this is good for: making batch configuration
592 changes to guests, getting disk used/free statistics (see also:
593 virt-df), migrating between virtualization systems (see also:
594 virt-p2v), performing partial backups, performing partial guest
595 clones, cloning guests and changing registry/UUID/hostname info, and
596 much else besides.
597
598 Libguestfs uses Linux kernel and qemu code, and can access any type of
599 guest filesystem that Linux and qemu can, including but not limited
600 to: ext2/3/4, btrfs, FAT and NTFS, LVM, many different disk partition
601 schemes, qcow, qcow2, vmdk.
602
603 Libguestfs provides ways to enumerate guest storage (eg. partitions,
604 LVs, what filesystem is in each LV, etc.).  It can also run commands
605 in the context of the guest.  Also you can access filesystems over
606 FUSE.
607
608 Errors which happen while using the API are turned into Python
609 RuntimeError exceptions.
610
611 To create a guestfs handle you usually have to perform the following
612 sequence of calls:
613
614 # Create the handle, call add_drive* at least once, and possibly
615 # several times if the guest has multiple block devices:
616 g = guestfs.GuestFS ()
617 g.add_drive_opts (\"guest.img\", format=\"raw\")
618
619 # Launch the qemu subprocess and wait for it to become ready:
620 g.launch ()
621
622 # Now you can issue commands, for example:
623 logvols = g.lvs ()
624
625 \"\"\"
626
627 import libguestfsmod
628
629 ";
630
631   List.iter (
632     fun (name, bitmask) ->
633       pr "EVENT_%s = 0x%x\n" (String.uppercase name) bitmask
634   ) events;
635   pr "\n";
636
637   pr "\
638 class ClosedHandle(ValueError):
639     pass
640
641 class GuestFS:
642     \"\"\"Instances of this class are libguestfs API handles.\"\"\"
643
644     def __init__ (self):
645         \"\"\"Create a new libguestfs handle.\"\"\"
646         self._o = libguestfsmod.create ()
647
648     def __del__ (self):
649         if self._o:
650             libguestfsmod.close (self._o)
651
652     def _check_not_closed (self):
653         if not self._o:
654             raise ClosedHandle (\"GuestFS: method called on closed handle\")
655
656     def close (self):
657         \"\"\"Explicitly close the guestfs handle.
658
659         The handle is closed implicitly when its reference count goes
660         to zero (eg. when it goes out of scope or the program ends).
661
662         This call is only needed if you want to force the handle to
663         close now.  After calling this, the program must not call
664         any method on the handle (except the implicit call to
665         __del__ which happens when the final reference is cleaned up).
666         \"\"\"
667         self._check_not_closed ()
668         libguestfsmod.close (self._o)
669         self._o = None
670
671     def set_event_callback (self, cb, event_bitmask):
672         \"\"\"Register an event callback.
673
674         Register \"cb\" as a callback function for all of the
675         events in \"event_bitmask\".  \"event_bitmask\" should be
676         one or more \"guestfs.EVENT_*\" flags logically or'd together.
677
678         This function returns an event handle which can be used
679         to delete the callback (see \"delete_event_callback\").
680
681         The callback function receives 4 parameters:
682
683         cb (event, event_handle, buf, array)
684
685         \"event\" is one of the \"EVENT_*\" flags.  \"buf\" is a
686         message buffer (only for some types of events).  \"array\"
687         is an array of integers (only for some types of events).
688
689         You should read the documentation for
690         \"guestfs_set_event_callback\" in guestfs(3) before using
691         this function.
692         \"\"\"
693         self._check_not_closed ()
694         return libguestfsmod.set_event_callback (self._o, cb, event_bitmask)
695
696     def delete_event_callback (self, event_handle):
697         \"\"\"Delete an event callback.\"\"\"
698         self._check_not_closed ()
699         libguestfsmod.delete_event_callback (self._o, event_handle)
700
701 ";
702
703   List.iter (
704     fun (name, (ret, args, optargs), _, flags, _, _, longdesc) ->
705       pr "    def %s (self" name;
706       List.iter (fun arg -> pr ", %s" (name_of_argt arg)) args;
707       List.iter (
708         function
709         | Bool n | Int n | Int64 n -> pr ", %s=-1" n
710         | String n -> pr ", %s=None" n
711         | _ -> assert false
712       ) optargs;
713       pr "):\n";
714
715       if not (List.mem NotInDocs flags) then (
716         let doc = replace_str longdesc "C<guestfs_" "C<g." in
717         let doc =
718           match ret with
719           | RErr | RInt _ | RInt64 _ | RBool _
720           | RConstOptString _ | RConstString _
721           | RString _ | RBufferOut _ -> doc
722           | RStringList _ ->
723               doc ^ "\n\nThis function returns a list of strings."
724           | RStruct (_, typ) ->
725               doc ^ sprintf "\n\nThis function returns a dictionary, with keys matching the various fields in the guestfs_%s structure." typ
726           | RStructList (_, typ) ->
727               doc ^ sprintf "\n\nThis function returns a list of %ss.  Each %s is represented as a dictionary." typ typ
728           | RHashtable _ ->
729               doc ^ "\n\nThis function returns a dictionary." in
730         let doc =
731           if List.mem ProtocolLimitWarning flags then
732             doc ^ "\n\n" ^ protocol_limit_warning
733           else doc in
734         let doc =
735           match deprecation_notice flags with
736           | None -> doc
737           | Some txt -> doc ^ "\n\n" ^ txt in
738         let doc = pod2text ~width:60 name doc in
739         let doc = List.map (fun line -> replace_str line "\\" "\\\\") doc in
740         let doc = String.concat "\n        " doc in
741         pr "        \"\"\"%s\"\"\"\n" doc;
742       );
743       (* Callers might pass in iterables instead of plain lists;
744        * convert those to plain lists because the C side of things
745        * cannot deal with iterables.  (RHBZ#693306).
746        *)
747       List.iter (
748         function
749         | Pathname _ | Device _ | Dev_or_Path _ | String _ | Key _
750         | FileIn _ | FileOut _ | OptString _ | Bool _ | Int _ | Int64 _
751         | BufferIn _ | Pointer _ -> ()
752         | StringList n | DeviceList n ->
753             pr "        %s = list (%s)\n" n n
754       ) args;
755       pr "        self._check_not_closed ()\n";
756       pr "        return libguestfsmod.%s (self._o" name;
757       List.iter (fun arg -> pr ", %s" (name_of_argt arg)) (args@optargs);
758       pr ")\n\n";
759   ) all_functions