Doc/faq/extending.rst

   1 =======================
   2 Extending/Embedding FAQ
   3 =======================
   4
   5 .. contents::
   6
   7 .. highlight:: c
   8
   9
  10 Can I create my own functions in C?
  11 -----------------------------------
  12
  13 Yes, you can create built-in modules containing functions, variables, exceptions
  14 and even new types in C.  This is explained in the document
  15 :ref:`extending-index`.
  16
  17 Most intermediate or advanced Python books will also cover this topic.
  18
  19
  20 Can I create my own functions in C++?
  21 -------------------------------------
  22
  23 Yes, using the C compatibility features found in C++.  Place ``extern "C" {
  24 ... }`` around the Python include files and put ``extern "C"`` before each
  25 function that is going to be called by the Python interpreter.  Global or static
  26 C++ objects with constructors are probably not a good idea.
  27
  28
  29 Writing C is hard; are there any alternatives?
  30 ----------------------------------------------
  31
  32 There are a number of alternatives to writing your own C extensions, depending
  33 on what you're trying to do.
  34
  35 .. XXX make sure these all work; mention Cython
  36
  37 If you need more speed, `Psyco <http://psyco.sourceforge.net/>`_ generates x86
  38 assembly code from Python bytecode.  You can use Psyco to compile the most
  39 time-critical functions in your code, and gain a significant improvement with
  40 very little effort, as long as you're running on a machine with an
  41 x86-compatible processor.
  42
  43 `Pyrex <http://www.cosc.canterbury.ac.nz/~greg/python/Pyrex/>`_ is a compiler
  44 that accepts a slightly modified form of Python and generates the corresponding
  45 C code.  Pyrex makes it possible to write an extension without having to learn
  46 Python's C API.
  47
  48 If you need to interface to some C or C++ library for which no Python extension
  49 currently exists, you can try wrapping the library's data types and functions
  50 with a tool such as `SWIG <http://www.swig.org>`_.  `SIP
  51 <http://www.riverbankcomputing.co.uk/software/sip/>`__, `CXX
  52 <http://cxx.sourceforge.net/>`_ `Boost
  53 <http://www.boost.org/libs/python/doc/index.html>`_, or `Weave
  54 <http://www.scipy.org/site_content/weave>`_ are also alternatives for wrapping
  55 C++ libraries.
  56
  57
  58 How can I execute arbitrary Python statements from C?
  59 -----------------------------------------------------
  60
  61 The highest-level function to do this is :cfunc:`PyRun_SimpleString` which takes
  62 a single string argument to be executed in the context of the module
  63 ``__main__`` and returns 0 for success and -1 when an exception occurred
  64 (including ``SyntaxError``).  If you want more control, use
  65 :cfunc:`PyRun_String`; see the source for :cfunc:`PyRun_SimpleString` in
  66 ``Python/pythonrun.c``.
  67
  68
  69 How can I evaluate an arbitrary Python expression from C?
  70 ---------------------------------------------------------
  71
  72 Call the function :cfunc:`PyRun_String` from the previous question with the
  73 start symbol :cdata:`Py_eval_input`; it parses an expression, evaluates it and
  74 returns its value.
  75
  76
  77 How do I extract C values from a Python object?
  78 -----------------------------------------------
  79
  80 That depends on the object's type.  If it's a tuple, :cfunc:`PyTuple_Size`
  81 returns its length and :cfunc:`PyTuple_GetItem` returns the item at a specified
  82 index.  Lists have similar functions, :cfunc:`PyListSize` and
  83 :cfunc:`PyList_GetItem`.
  84
  85 For strings, :cfunc:`PyString_Size` returns its length and
  86 :cfunc:`PyString_AsString` a pointer to its value.  Note that Python strings may
  87 contain null bytes so C's :cfunc:`strlen` should not be used.
  88
  89 To test the type of an object, first make sure it isn't *NULL*, and then use
  90 :cfunc:`PyString_Check`, :cfunc:`PyTuple_Check`, :cfunc:`PyList_Check`, etc.
  91
  92 There is also a high-level API to Python objects which is provided by the
  93 so-called 'abstract' interface -- read ``Include/abstract.h`` for further
  94 details.  It allows interfacing with any kind of Python sequence using calls
  95 like :cfunc:`PySequence_Length`, :cfunc:`PySequence_GetItem`, etc.)  as well as
  96 many other useful protocols.
  97
  98
  99 How do I use Py_BuildValue() to create a tuple of arbitrary length?
 100 -------------------------------------------------------------------
 101
 102 You can't.  Use ``t = PyTuple_New(n)`` instead, and fill it with objects using
 103 ``PyTuple_SetItem(t, i, o)`` -- note that this "eats" a reference count of
 104 ``o``, so you have to :cfunc:`Py_INCREF` it.  Lists have similar functions
 105 ``PyList_New(n)`` and ``PyList_SetItem(l, i, o)``.  Note that you *must* set all
 106 the tuple items to some value before you pass the tuple to Python code --
 107 ``PyTuple_New(n)`` initializes them to NULL, which isn't a valid Python value.
 108
 109
 110 How do I call an object's method from C?
 111 ----------------------------------------
 112
 113 The :cfunc:`PyObject_CallMethod` function can be used to call an arbitrary
 114 method of an object.  The parameters are the object, the name of the method to
 115 call, a format string like that used with :cfunc:`Py_BuildValue`, and the
 116 argument values::
 117
 118    PyObject *
 119    PyObject_CallMethod(PyObject *object, char *method_name,
 120                        char *arg_format, ...);
 121
 122 This works for any object that has methods -- whether built-in or user-defined.
 123 You are responsible for eventually :cfunc:`Py_DECREF`\ 'ing the return value.
 124
 125 To call, e.g., a file object's "seek" method with arguments 10, 0 (assuming the
 126 file object pointer is "f")::
 127
 128    res = PyObject_CallMethod(f, "seek", "(ii)", 10, 0);
 129    if (res == NULL) {
 130            ... an exception occurred ...
 131    }
 132    else {
 133            Py_DECREF(res);
 134    }
 135
 136 Note that since :cfunc:`PyObject_CallObject` *always* wants a tuple for the
 137 argument list, to call a function without arguments, pass "()" for the format,
 138 and to call a function with one argument, surround the argument in parentheses,
 139 e.g. "(i)".
 140
 141
 142 How do I catch the output from PyErr_Print() (or anything that prints to stdout/stderr)?
 143 ----------------------------------------------------------------------------------------
 144
 145 In Python code, define an object that supports the ``write()`` method.  Assign
 146 this object to :data:`sys.stdout` and :data:`sys.stderr`.  Call print_error, or
 147 just allow the standard traceback mechanism to work. Then, the output will go
 148 wherever your ``write()`` method sends it.
 149
 150 The easiest way to do this is to use the StringIO class in the standard library.
 151
 152 Sample code and use for catching stdout:
 153
 154    >>> class StdoutCatcher:
 155    ...     def __init__(self):
 156    ...         self.data = ''
 157    ...     def write(self, stuff):
 158    ...         self.data = self.data + stuff
 159    ...
 160    >>> import sys
 161    >>> sys.stdout = StdoutCatcher()
 162    >>> print 'foo'
 163    >>> print 'hello world!'
 164    >>> sys.stderr.write(sys.stdout.data)
 165    foo
 166    hello world!
 167
 168
 169 How do I access a module written in Python from C?
 170 --------------------------------------------------
 171
 172 You can get a pointer to the module object as follows::
 173
 174    module = PyImport_ImportModule("<modulename>");
 175
 176 If the module hasn't been imported yet (i.e. it is not yet present in
 177 :data:`sys.modules`), this initializes the module; otherwise it simply returns
 178 the value of ``sys.modules["<modulename>"]``.  Note that it doesn't enter the
 179 module into any namespace -- it only ensures it has been initialized and is
 180 stored in :data:`sys.modules`.
 181
 182 You can then access the module's attributes (i.e. any name defined in the
 183 module) as follows::
 184
 185    attr = PyObject_GetAttrString(module, "<attrname>");
 186
 187 Calling :cfunc:`PyObject_SetAttrString` to assign to variables in the module
 188 also works.
 189
 190
 191 How do I interface to C++ objects from Python?
 192 ----------------------------------------------
 193
 194 Depending on your requirements, there are many approaches.  To do this manually,
 195 begin by reading :ref:`the "Extending and Embedding" document
 196 <extending-index>`.  Realize that for the Python run-time system, there isn't a
 197 whole lot of difference between C and C++ -- so the strategy of building a new
 198 Python type around a C structure (pointer) type will also work for C++ objects.
 199
 200 For C++ libraries, you can look at `SIP
 201 <http://www.riverbankcomputing.co.uk/sip/>`_, `CXX
 202 <http://cxx.sourceforge.net/>`_, `Boost
 203 <http://www.boost.org/libs/python/doc/index.html>`_, `Weave
 204 <http://www.scipy.org/site_content/weave>`_ or `SWIG <http://www.swig.org>`_
 205
 206
 207 I added a module using the Setup file and the make fails; why?
 208 --------------------------------------------------------------
 209
 210 Setup must end in a newline, if there is no newline there, the build process
 211 fails.  (Fixing this requires some ugly shell script hackery, and this bug is so
 212 minor that it doesn't seem worth the effort.)
 213
 214
 215 How do I debug an extension?
 216 ----------------------------
 217
 218 When using GDB with dynamically loaded extensions, you can't set a breakpoint in
 219 your extension until your extension is loaded.
 220
 221 In your ``.gdbinit`` file (or interactively), add the command::
 222
 223    br _PyImport_LoadDynamicModule
 224
 225 Then, when you run GDB::
 226
 227    $ gdb /local/bin/python
 228    gdb) run myscript.py
 229    gdb) continue # repeat until your extension is loaded
 230    gdb) finish   # so that your extension is loaded
 231    gdb) br myfunction.c:50
 232    gdb) continue
 233
 234 I want to compile a Python module on my Linux system, but some files are missing. Why?
 235 --------------------------------------------------------------------------------------
 236
 237 Most packaged versions of Python don't include the
 238 :file:`/usr/lib/python2.{x}/config/` directory, which contains various files
 239 required for compiling Python extensions.
 240
 241 For Red Hat, install the python-devel RPM to get the necessary files.
 242
 243 For Debian, run ``apt-get install python-dev``.
 244
 245
 246 What does "SystemError: _PyImport_FixupExtension: module yourmodule not loaded" mean?
 247 -------------------------------------------------------------------------------------
 248
 249 This means that you have created an extension module named "yourmodule", but
 250 your module init function does not initialize with that name.
 251
 252 Every module init function will have a line similar to::
 253
 254    module = Py_InitModule("yourmodule", yourmodule_functions);
 255
 256 If the string passed to this function is not the same name as your extension
 257 module, the :exc:`SystemError` exception will be raised.
 258
 259
 260 How do I tell "incomplete input" from "invalid input"?
 261 ------------------------------------------------------
 262
 263 Sometimes you want to emulate the Python interactive interpreter's behavior,
 264 where it gives you a continuation prompt when the input is incomplete (e.g. you
 265 typed the start of an "if" statement or you didn't close your parentheses or
 266 triple string quotes), but it gives you a syntax error message immediately when
 267 the input is invalid.
 268
 269 In Python you can use the :mod:`codeop` module, which approximates the parser's
 270 behavior sufficiently.  IDLE uses this, for example.
 271
 272 The easiest way to do it in C is to call :cfunc:`PyRun_InteractiveLoop` (perhaps
 273 in a separate thread) and let the Python interpreter handle the input for
 274 you. You can also set the :cfunc:`PyOS_ReadlineFunctionPointer` to point at your
 275 custom input function. See ``Modules/readline.c`` and ``Parser/myreadline.c``
 276 for more hints.
 277
 278 However sometimes you have to run the embedded Python interpreter in the same
 279 thread as your rest application and you can't allow the
 280 :cfunc:`PyRun_InteractiveLoop` to stop while waiting for user input.  The one
 281 solution then is to call :cfunc:`PyParser_ParseString` and test for ``e.error``
 282 equal to ``E_EOF``, which means the input is incomplete).  Here's a sample code
 283 fragment, untested, inspired by code from Alex Farber::
 284
 285    #include <Python.h>
 286    #include <node.h>
 287    #include <errcode.h>
 288    #include <grammar.h>
 289    #include <parsetok.h>
 290    #include <compile.h>
 291
 292    int testcomplete(char *code)
 293      /* code should end in \n */
 294      /* return -1 for error, 0 for incomplete, 1 for complete */
 295    {
 296      node *n;
 297      perrdetail e;
 298
 299      n = PyParser_ParseString(code, &_PyParser_Grammar,
 300                               Py_file_input, &e);
 301      if (n == NULL) {
 302        if (e.error == E_EOF)
 303          return 0;
 304        return -1;
 305      }
 306
 307      PyNode_Free(n);
 308      return 1;
 309    }
 310
 311 Another solution is trying to compile the received string with
 312 :cfunc:`Py_CompileString`. If it compiles without errors, try to execute the
 313 returned code object by calling :cfunc:`PyEval_EvalCode`. Otherwise save the
 314 input for later. If the compilation fails, find out if it's an error or just
 315 more input is required - by extracting the message string from the exception
 316 tuple and comparing it to the string "unexpected EOF while parsing".  Here is a
 317 complete example using the GNU readline library (you may want to ignore
 318 **SIGINT** while calling readline())::
 319
 320    #include <stdio.h>
 321    #include <readline.h>
 322
 323    #include <Python.h>
 324    #include <object.h>
 325    #include <compile.h>
 326    #include <eval.h>
 327
 328    int main (int argc, char* argv[])
 329    {
 330      int i, j, done = 0;                          /* lengths of line, code */
 331      char ps1[] = ">>> ";
 332      char ps2[] = "... ";
 333      char *prompt = ps1;
 334      char *msg, *line, *code = NULL;
 335      PyObject *src, *glb, *loc;
 336      PyObject *exc, *val, *trb, *obj, *dum;
 337
 338      Py_Initialize ();
 339      loc = PyDict_New ();
 340      glb = PyDict_New ();
 341      PyDict_SetItemString (glb, "__builtins__", PyEval_GetBuiltins ());
 342
 343      while (!done)
 344      {
 345        line = readline (prompt);
 346
 347        if (NULL == line)                          /* CTRL-D pressed */
 348        {
 349          done = 1;
 350        }
 351        else
 352        {
 353          i = strlen (line);
 354
 355          if (i > 0)
 356            add_history (line);                    /* save non-empty lines */
 357
 358          if (NULL == code)                        /* nothing in code yet */
 359            j = 0;
 360          else
 361            j = strlen (code);
 362
 363          code = realloc (code, i + j + 2);
 364          if (NULL == code)                        /* out of memory */
 365            exit (1);
 366
 367          if (0 == j)                              /* code was empty, so */
 368            code[0] = '\0';                        /* keep strncat happy */
 369
 370          strncat (code, line, i);                 /* append line to code */
 371          code[i + j] = '\n';                      /* append '\n' to code */
 372          code[i + j + 1] = '\0';
 373
 374          src = Py_CompileString (code, "<stdin>", Py_single_input);
 375
 376          if (NULL != src)                         /* compiled just fine - */
 377          {
 378            if (ps1  == prompt ||                  /* ">>> " or */
 379                '\n' == code[i + j - 1])           /* "... " and double '\n' */
 380            {                                               /* so execute it */
 381              dum = PyEval_EvalCode ((PyCodeObject *)src, glb, loc);
 382              Py_XDECREF (dum);
 383              Py_XDECREF (src);
 384              free (code);
 385              code = NULL;
 386              if (PyErr_Occurred ())
 387                PyErr_Print ();
 388              prompt = ps1;
 389            }
 390          }                                        /* syntax error or E_EOF? */
 391          else if (PyErr_ExceptionMatches (PyExc_SyntaxError))
 392          {
 393            PyErr_Fetch (&exc, &val, &trb);        /* clears exception! */
 394
 395            if (PyArg_ParseTuple (val, "sO", &msg, &obj) &&
 396                !strcmp (msg, "unexpected EOF while parsing")) /* E_EOF */
 397            {
 398              Py_XDECREF (exc);
 399              Py_XDECREF (val);
 400              Py_XDECREF (trb);
 401              prompt = ps2;
 402            }
 403            else                                   /* some other syntax error */
 404            {
 405              PyErr_Restore (exc, val, trb);
 406              PyErr_Print ();
 407              free (code);
 408              code = NULL;
 409              prompt = ps1;
 410            }
 411          }
 412          else                                     /* some non-syntax error */
 413          {
 414            PyErr_Print ();
 415            free (code);
 416            code = NULL;
 417            prompt = ps1;
 418          }
 419
 420          free (line);
 421        }
 422      }
 423
 424      Py_XDECREF(glb);
 425      Py_XDECREF(loc);
 426      Py_Finalize();
 427      exit(0);
 428    }
 429
 430
 431 How do I find undefined g++ symbols __builtin_new or __pure_virtual?
 432 --------------------------------------------------------------------
 433
 434 To dynamically load g++ extension modules, you must recompile Python, relink it
 435 using g++ (change LINKCC in the python Modules Makefile), and link your
 436 extension module using g++ (e.g., ``g++ -shared -o mymodule.so mymodule.o``).
 437
 438
 439 Can I create an object class with some methods implemented in C and others in Python (e.g. through inheritance)?
 440 ----------------------------------------------------------------------------------------------------------------
 441
 442 In Python 2.2, you can inherit from builtin classes such as :class:`int`,
 443 :class:`list`, :class:`dict`, etc.
 444
 445 The Boost Python Library (BPL, http://www.boost.org/libs/python/doc/index.html)
 446 provides a way of doing this from C++ (i.e. you can inherit from an extension
 447 class written in C++ using the BPL).
 448
 449
 450 When importing module X, why do I get "undefined symbol: PyUnicodeUCS2*"?
 451 -------------------------------------------------------------------------
 452
 453 You are using a version of Python that uses a 4-byte representation for Unicode
 454 characters, but some C extension module you are importing was compiled using a
 455 Python that uses a 2-byte representation for Unicode characters (the default).
 456
 457 If instead the name of the undefined symbol starts with ``PyUnicodeUCS4``, the
 458 problem is the reverse: Python was built using 2-byte Unicode characters, and
 459 the extension module was compiled using a Python with 4-byte Unicode characters.
 460
 461 This can easily occur when using pre-built extension packages.  RedHat Linux
 462 7.x, in particular, provided a "python2" binary that is compiled with 4-byte
 463 Unicode.  This only causes the link failure if the extension uses any of the
 464 ``PyUnicode_*()`` functions.  It is also a problem if an extension uses any of
 465 the Unicode-related format specifiers for :cfunc:`Py_BuildValue` (or similar) or
 466 parameter specifications for :cfunc:`PyArg_ParseTuple`.
 467
 468 You can check the size of the Unicode character a Python interpreter is using by
 469 checking the value of sys.maxunicode:
 470
 471    >>> import sys
 472    >>> if sys.maxunicode > 65535:
 473    ...     print 'UCS4 build'
 474    ... else:
 475    ...     print 'UCS2 build'
 476
 477 The only way to solve this problem is to use extension modules compiled with a
 478 Python binary built using the same size for Unicode characters.
 479
 480
 481