Lines Matching +full:python +full:- +full:format
4 .. _extending-intro:
7 Extending Python with C or C++
10 It is quite easy to add new built-in modules to Python, if you know how to
12 done directly in Python: they can implement new built-in object types, and they
15 To support extensions, the Python API (Application Programmers Interface)
17 aspects of the Python run-time system. The Python API is incorporated in a C
18 source file by including the header ``"Python.h"``.
26 not work on other Python implementations. In many cases, it is possible to
32 These modules let you write Python code to interface with C code and are more
33 portable between implementations of Python than writing and compiling a C
37 .. _extending-simpleexample:
43 Python fans...) and let's say we want to create a Python interface to the C
44 library function :c:func:`system` [#]_. This function takes a null-terminated
46 be callable from Python as follows:
48 .. code-block:: pycon
51 >>> status = spam.system("ls -l")
61 #include <Python.h>
63 which pulls in the Python API (you can add a comment describing the purpose of
68 Since Python may define some pre-processor definitions which affect the standard
69 headers on some systems, you *must* include :file:`Python.h` before any standard
73 ``Python.h``. See :ref:`parsetuple` for a description of this macro.
75 All user-visible symbols defined by :file:`Python.h` have a prefix of ``Py`` or
77 since they are used extensively by the Python interpreter, ``"Python.h"``
84 when the Python expression ``spam.system(string)`` is evaluated (we'll see
99 There is a straightforward translation from the argument list in Python (for
100 example, the single expression ``"ls -l"``) to the arguments passed to the C
104 The *self* argument points to the module object for module-level functions;
107 The *args* argument will be a pointer to a Python tuple object containing the
109 argument list. The arguments are Python objects --- in order to do anything
111 :c:func:`PyArg_ParseTuple` in the Python API checks the argument types and
123 .. _extending-errors:
128 An important convention throughout the Python interpreter is the following: when
130 (usually ``-1`` or a ``NULL`` pointer). Exception information is stored in
133 of the Python tuple returned by :meth:`sys.exc_info`. These are the
137 The Python API defines a number of functions to set various types of exceptions.
142 and is converted to a Python string object and stored as the "associated value"
152 You can test non-destructively whether an exception has been set with
159 fails, *f* should itself return an error value (usually ``NULL`` or ``-1``). It
160 should *not* call one of the ``PyErr_*`` functions --- one has already
163 --- the most detailed cause of the error was already reported by the function
164 that first detected it. Once the error reaches the Python interpreter's main
165 loop, this aborts the currently executing Python code and tries to find an
166 exception handler specified by the Python programmer.
180 Every failing :c:func:`malloc` call must be turned into an exception --- the
183 object-creating functions (for example, :c:func:`PyLong_FromLong`) already do
188 or zero for success and ``-1`` for failure, like Unix system calls.
195 C objects corresponding to all built-in Python exceptions, such as
197 should choose exceptions wisely --- don't use :c:data:`PyExc_TypeError` to mean
233 Note that the Python name for the exception object is :exc:`spam.error`. The
236 described in :ref:`bltin-exceptions`.
293 Python object. This is done using the function :c:func:`PyLong_FromLong`. ::
298 on the heap in Python!)
301 :c:expr:`void`), the corresponding Python function must return ``None``. You
308 :c:data:`Py_None` is the C name for the special Python object ``None``. It is a
309 genuine Python object rather than a ``NULL`` pointer, which means "error" in most
318 I promised to show how :c:func:`spam_system` is called from Python programs.
334 When using only ``METH_VARARGS``, the function should expect the Python-level
350 -1, /* size of per-interpreter state of the module,
351 or -1 if the module keeps state in global variables. */
358 only non-\ ``static`` item defined in the module file::
370 When the Python program imports module :mod:`spam` for the first time,
371 :c:func:`PyInit_spam` is called. (See below for comments about embedding Python.)
373 inserts built-in function objects into the newly created module based upon the
381 When embedding Python, the :c:func:`PyInit_spam` function is not called
395 /* Add a built-in module, before Py_Initialize */
396 if (PyImport_AppendInittab("spam", PyInit_spam) == -1) {
397 fprintf(stderr, "Error: could not extend in-built modules table\n");
401 /* Pass argv[0] to the Python interpreter */
404 /* Initialize the Python interpreter. Required.
431 A more substantial example module is included in the Python source distribution
437 Unlike our ``spam`` example, ``xxmodule`` uses *multi-phase initialization*
438 (new in Python 3.5), where a PyModuleDef structure is returned from
440 For details on multi-phase initialization, see :PEP:`489`.
449 and linking it with the Python system. If you use dynamic loading, the details
453 :ref:`building-on-windows`) for more information about this.
456 part of the Python interpreter, you will have to change the configuration setup
462 .. code-block:: sh
475 .. code-block:: sh
477 spam spammodule.o -lX11
482 Calling Python Functions from C
485 So far we have concentrated on making C functions callable from Python. The
486 reverse is also useful: calling Python functions from C. This is especially the
487 case for libraries that support so-called "callback" functions. If a C
488 interface makes use of callbacks, the equivalent Python often needs to provide a
489 callback mechanism to the Python programmer; the implementation will require
490 calling the Python callback functions from a C callback. Other uses are also
493 Fortunately, the Python interpreter is easily called recursively, and there is a
494 standard interface to call a Python function. (I won't dwell on how to call the
495 Python parser with a particular string as input --- if you're interested, have a
496 look at the implementation of the :option:`-c` command line option in
497 :file:`Modules/main.c` from the Python source code.)
499 Calling a Python function is easy. First, the Python program must somehow pass
500 you the Python function object. You should provide a function (or some other
502 Python function object (be careful to :c:func:`Py_INCREF` it!) in a global
503 variable --- or wherever you see fit. For example, the following function might
543 arbitrary Python objects: the Python function, and the argument list. The
545 arguments. To call the Python function with no arguments, pass in ``NULL``, or
547 :c:func:`Py_BuildValue` returns a tuple when its format string consists of zero
548 or more format codes between parentheses. For example::
561 :c:func:`PyObject_CallObject` returns a Python object pointer: this is the return
562 value of the Python function. :c:func:`PyObject_CallObject` is
563 "reference-count-neutral" with respect to its arguments. In the example a new
565 :c:func:`Py_DECREF`\ -ed immediately after the :c:func:`PyObject_CallObject`
575 isn't ``NULL``. If it is, the Python function terminated by raising an exception.
576 If the C code that called :c:func:`PyObject_CallObject` is called from Python, it
577 should now return an error indication to its Python caller, so the interpreter
578 can print a stack trace, or the calling Python code can handle the exception.
587 Depending on the desired interface to the Python callback function, you may also
589 the argument list is also provided by the Python program, through the same
634 int PyArg_ParseTuple(PyObject *arg, const char *format, ...);
637 from Python to a C function. The *format* argument must be a format string,
638 whose syntax is explained in :ref:`arg-parsing` in the Python/C API Reference
640 determined by the format string.
642 Note that while :c:func:`PyArg_ParseTuple` checks that the Python arguments have
647 Note that any Python object references which are provided to the caller are
653 #include <Python.h>
664 /* Python call: f() */
669 /* Possible Python call: f('whoops!') */
674 /* Possible Python call: f(1, 2, 'three') */
680 /* Possible Python call: f((1, 2), 'three') */
690 /* Possible Python calls:
703 /* Possible Python call:
713 /* Possible Python call: myfunction(1+2j) */
727 const char *format, char *kwlist[], ...);
729 The *arg* and *format* parameters are identical to those of the
731 keywords received as the third parameter from the Python runtime. The *kwlist*
732 parameter is a ``NULL``-terminated list of strings which identify the parameters;
733 the names are matched with the type information from *format* from left to
749 #include <Python.h>
765 printf("-- This parrot wouldn't %s if you put %i Volts through it.\n",
767 printf("-- Lovely plumage, the %s -- It's %s!\n", type, state);
786 -1,
805 PyObject *Py_BuildValue(const char *format, ...);
807 It recognizes a set of format units similar to the ones recognized by
809 not output) must not be pointers, just values. It returns a new Python object,
810 suitable for returning from a C function called from Python.
813 first argument to be a tuple (since Python argument lists are always represented
815 builds a tuple only if its format string contains two or more format units. If
816 the format string is empty, it returns ``None``; if it contains exactly one
817 format unit, it returns whatever object is described by that format unit. To
818 force it to return a tuple of size 0 or one, parenthesize the format string.
820 Examples (to the left the call, to the right the resulting Python value):
822 .. code-block:: none
860 continues to use the block, it creates a conflict with re-use of the block
862 It has the same bad consequences as referencing uninitialized data --- core
874 long-running process that uses the leaking function frequently. Therefore, it's
878 Since Python makes heavy use of :c:func:`malloc` and :c:func:`free`, it needs a
891 or memory usage --- this is no hard fact however.) The disadvantage is that for
894 and :c:func:`free` are available --- which the C Standard guarantees). Maybe some
898 While Python uses the traditional reference counting implementation, it also
904 which is non-zero. Typical reference counting implementations are not able to
917 Reference Counting in Python
918 ----------------------------
923 :c:func:`free` directly --- rather, it makes a call through a function pointer in
944 --- in other words, with a borrowed reference you don't run the risk of leaking
952 reference was borrowed --- it creates a new owned reference, and gives full
960 ---------------
986 function borrows the reference from you --- if it needs to store it, it will use
990 to them --- even if they fail! (Note that :c:func:`PyDict_SetItem` and friends
991 don't take over ownership --- they are "normal.")
993 When a C function is called from Python, it borrows references to its arguments
999 The object reference returned from a C function that is called from Python must
1000 be an owned reference --- ownership is transferred from the function to its
1007 --------
1032 user-defined class, and let's further suppose that the class defined a
1036 Since it is written in Python, the :meth:`__del__` method can execute arbitrary
1037 Python code. Could it perhaps do something to invalidate the reference to
1058 This is a true story. An older version of Python contained variants of this bug
1063 threads. Normally, multiple threads in the Python interpreter can't get in each
1064 other's way, because there is a global lock protecting Python's entire object
1066 :c:macro:`Py_BEGIN_ALLOW_THREADS`, and to re-acquire it using
1085 -------------
1092 function --- if each function were to test for ``NULL``, there would be a lot of
1100 pointers --- however, their variants :c:func:`Py_XINCREF` and :c:func:`Py_XDECREF`
1104 check for ``NULL`` pointers --- again, there is much code that calls several of
1110 functions (``args`` in the examples) is never ``NULL`` --- in fact it guarantees
1113 It is a severe error to ever let a ``NULL`` pointer "escape" to the Python user.
1117 be helpful here -- showing in more concrete terms what sort of actions could
1127 the main program (the Python interpreter) is compiled and linked by the C
1130 will be called by the Python interpreter (in particular, module initialization
1132 enclose the Python header files in ``extern "C" {...}`` --- they use this form
1137 .. _using-capsules:
1142 .. sectionauthor:: Konrad Hinsen <hinsen@cnrs-orleans.fr>
1146 Python, but sometimes the code in an extension module can be useful for other
1148 "collection" which works like lists without order. Just like the standard Python
1156 linked statically with the Python interpreter. When modules are used as shared
1159 systems use one global namespace for the Python interpreter and all extension
1172 Python provides a special mechanism to pass C-level information (pointers) from
1173 one extension module to another one: Capsules. A Capsule is a Python data type
1175 accessed via their C API, but they can be passed around like any other Python
1190 a degree of runtime type-safety; there is no feasible way to tell one unnamed
1212 :ref:`extending-simpleexample`. The function :func:`spam.system` does not call
1243 #include <Python.h>
1316 /* Return -1 on error, 0 on success.
1323 return (PySpam_API != NULL) ? 0 : -1;
1358 stored in a Capsule. The details are described in the Python/C API Reference
1360 :file:`Include/pycapsule.h` and :file:`Objects/pycapsule.c` in the Python source
1366 --- it was chosen as a simple and straightforward example.
1371 .. [#] Checking that the reference count is at least 1 **does not work** --- the
1375 .. [#] These guarantees don't hold when you use the "old" style calling convention ---