Ignore:
Timestamp:
Mar 19, 2014, 11:31:01 PM (11 years ago)
Author:
dmik
Message:

python: Merge vendor 2.7.6 to trunk.

Location:
python/trunk
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • python/trunk

  • python/trunk/Doc/extending/extending.rst

    r2 r391  
    3636Let's create an extension module called ``spam`` (the favorite food of Monty
    3737Python fans...) and let's say we want to create a Python interface to the C
    38 library function :cfunc:`system`. [#]_ This function takes a null-terminated
     38library function :c:func:`system`. [#]_ This function takes a null-terminated
    3939character string as argument and returns an integer.  We want this function to
    4040be callable from Python as follows::
    … …  
    6666includes a few standard header files: ``<stdio.h>``, ``<string.h>``,
    6767``<errno.h>``, and ``<stdlib.h>``.  If the latter header file does not exist on
    68 your system, it declares the functions :cfunc:`malloc`, :cfunc:`free` and
    69 :cfunc:`realloc` directly.
     68your system, it declares the functions :c:func:`malloc`, :c:func:`free` and
     69:c:func:`realloc` directly.
    7070
    7171The next thing we add to our module file is the C function that will be called
    … …  
    9090and *args*.
    9191
    92 The *self* argument is only used when the C function implements a built-in
    93 method, not a function. In the example, *self* will always be a *NULL* pointer,
    94 since we are defining a function, not a method.  (This is done so that the
    95 interpreter doesn't have to understand two different types of C functions.)
     92The *self* argument points to the module object for module-level functions;
     93for a method it would point to the object instance.
    9694
    9795The *args* argument will be a pointer to a Python tuple object containing the
    … …  
    9997argument list.  The arguments are Python objects --- in order to do anything
    10098with them in our C function we have to convert them to C values.  The function
    101 :cfunc:`PyArg_ParseTuple` in the Python API checks the argument types and
     99:c:func:`PyArg_ParseTuple` in the Python API checks the argument types and
    102100converts them to C values.  It uses a template string to determine the required
    103101types of the arguments as well as the types of the C variables into which to
    104102store the converted values.  More about this later.
    105103
    106 :cfunc:`PyArg_ParseTuple` returns true (nonzero) if all arguments have the right
     104:c:func:`PyArg_ParseTuple` returns true (nonzero) if all arguments have the right
    107105type and its components have been stored in the variables whose addresses are
    108106passed.  It returns false (zero) if an invalid argument list was passed.  In the
    … …  
    130128The Python API defines a number of functions to set various types of exceptions.
    131129
    132 The most common one is :cfunc:`PyErr_SetString`.  Its arguments are an exception
     130The most common one is :c:func:`PyErr_SetString`.  Its arguments are an exception
    133131object and a C string.  The exception object is usually a predefined object like
    134 :cdata:`PyExc_ZeroDivisionError`.  The C string indicates the cause of the error
     132:c:data:`PyExc_ZeroDivisionError`.  The C string indicates the cause of the error
    135133and is converted to a Python string object and stored as the "associated value"
    136134of the exception.
    137135
    138 Another useful function is :cfunc:`PyErr_SetFromErrno`, which only takes an
     136Another useful function is :c:func:`PyErr_SetFromErrno`, which only takes an
    139137exception argument and constructs the associated value by inspection of the
    140 global variable :cdata:`errno`.  The most general function is
    141 :cfunc:`PyErr_SetObject`, which takes two object arguments, the exception and
    142 its associated value.  You don't need to :cfunc:`Py_INCREF` the objects passed
     138global variable :c:data:`errno`.  The most general function is
     139:c:func:`PyErr_SetObject`, which takes two object arguments, the exception and
     140its associated value.  You don't need to :c:func:`Py_INCREF` the objects passed
    143141to any of these functions.
    144142
    145143You can test non-destructively whether an exception has been set with
    146 :cfunc:`PyErr_Occurred`.  This returns the current exception object, or *NULL*
     144:c:func:`PyErr_Occurred`.  This returns the current exception object, or *NULL*
    147145if no exception has occurred.  You normally don't need to call
    148 :cfunc:`PyErr_Occurred` to see whether an error occurred in a function call,
     146:c:func:`PyErr_Occurred` to see whether an error occurred in a function call,
    149147since you should be able to tell from the return value.
    150148
    151149When a function *f* that calls another function *g* detects that the latter
    152150fails, *f* should itself return an error value (usually *NULL* or ``-1``).  It
    153 should *not* call one of the :cfunc:`PyErr_\*` functions --- one has already
     151should *not* call one of the :c:func:`PyErr_\*` functions --- one has already
    154152been called by *g*. *f*'s caller is then supposed to also return an error
    155 indication to *its* caller, again *without* calling :cfunc:`PyErr_\*`, and so on
     153indication to *its* caller, again *without* calling :c:func:`PyErr_\*`, and so on
    156154--- the most detailed cause of the error was already reported by the function
    157155that first detected it.  Once the error reaches the Python interpreter's main
    … …  
    160158
    161159(There are situations where a module can actually give a more detailed error
    162 message by calling another :cfunc:`PyErr_\*` function, and in such cases it is
     160message by calling another :c:func:`PyErr_\*` function, and in such cases it is
    163161fine to do so.  As a general rule, however, this is not necessary, and can cause
    164162information about the cause of the error to be lost: most operations can fail
    … …  
    166164
    167165To ignore an exception set by a function call that failed, the exception
    168 condition must be cleared explicitly by calling :cfunc:`PyErr_Clear`.  The only
    169 time C code should call :cfunc:`PyErr_Clear` is if it doesn't want to pass the
     166condition must be cleared explicitly by calling :c:func:`PyErr_Clear`.  The only
     167time C code should call :c:func:`PyErr_Clear` is if it doesn't want to pass the
    170168error on to the interpreter but wants to handle it completely by itself
    171169(possibly by trying something else, or pretending nothing went wrong).
    172170
    173 Every failing :cfunc:`malloc` call must be turned into an exception --- the
    174 direct caller of :cfunc:`malloc` (or :cfunc:`realloc`) must call
    175 :cfunc:`PyErr_NoMemory` and return a failure indicator itself.  All the
    176 object-creating functions (for example, :cfunc:`PyInt_FromLong`) already do
    177 this, so this note is only relevant to those who call :cfunc:`malloc` directly.
    178 
    179 Also note that, with the important exception of :cfunc:`PyArg_ParseTuple` and
     171Every failing :c:func:`malloc` call must be turned into an exception --- the
     172direct caller of :c:func:`malloc` (or :c:func:`realloc`) must call
     173:c:func:`PyErr_NoMemory` and return a failure indicator itself.  All the
     174object-creating functions (for example, :c:func:`PyInt_FromLong`) already do
     175this, so this note is only relevant to those who call :c:func:`malloc` directly.
     176
     177Also note that, with the important exception of :c:func:`PyArg_ParseTuple` and
    180178friends, functions that return an integer status usually return a positive value
    181179or zero for success and ``-1`` for failure, like Unix system calls.
    182180
    183 Finally, be careful to clean up garbage (by making :cfunc:`Py_XDECREF` or
    184 :cfunc:`Py_DECREF` calls for objects you have already created) when you return
     181Finally, be careful to clean up garbage (by making :c:func:`Py_XDECREF` or
     182:c:func:`Py_DECREF` calls for objects you have already created) when you return
    185183an error indicator!
    186184
    187185The choice of which exception to raise is entirely yours.  There are predeclared
    188186C objects corresponding to all built-in Python exceptions, such as
    189 :cdata:`PyExc_ZeroDivisionError`, which you can use directly. Of course, you
    190 should choose exceptions wisely --- don't use :cdata:`PyExc_TypeError` to mean
    191 that a file couldn't be opened (that should probably be :cdata:`PyExc_IOError`).
    192 If something's wrong with the argument list, the :cfunc:`PyArg_ParseTuple`
    193 function usually raises :cdata:`PyExc_TypeError`.  If you have an argument whose
     187:c:data:`PyExc_ZeroDivisionError`, which you can use directly. Of course, you
     188should choose exceptions wisely --- don't use :c:data:`PyExc_TypeError` to mean
     189that a file couldn't be opened (that should probably be :c:data:`PyExc_IOError`).
     190If something's wrong with the argument list, the :c:func:`PyArg_ParseTuple`
     191function usually raises :c:data:`PyExc_TypeError`.  If you have an argument whose
    194192value must be in a particular range or must satisfy other conditions,
    195 :cdata:`PyExc_ValueError` is appropriate.
     193:c:data:`PyExc_ValueError` is appropriate.
    196194
    197195You can also define a new exception that is unique to your module. For this, you
    … …  
    200198   static PyObject *SpamError;
    201199
    202 and initialize it in your module's initialization function (:cfunc:`initspam`)
     200and initialize it in your module's initialization function (:c:func:`initspam`)
    203201with an exception object (leaving out the error checking for now)::
    204202
    … …  
    218216
    219217Note that the Python name for the exception object is :exc:`spam.error`.  The
    220 :cfunc:`PyErr_NewException` function may create a class with the base class
     218:c:func:`PyErr_NewException` function may create a class with the base class
    221219being :exc:`Exception` (unless another class is passed in instead of *NULL*),
    222220described in :ref:`bltin-exceptions`.
    223221
    224 Note also that the :cdata:`SpamError` variable retains a reference to the newly
     222Note also that the :c:data:`SpamError` variable retains a reference to the newly
    225223created exception class; this is intentional!  Since the exception could be
    226224removed from the module by external code, an owned reference to the class is
    227 needed to ensure that it will not be discarded, causing :cdata:`SpamError` to
     225needed to ensure that it will not be discarded, causing :c:data:`SpamError` to
    228226become a dangling pointer. Should it become a dangling pointer, C code which
    229227raises the exception could cause a core dump or other unintended side effects.
    230228
    231 We discuss the use of PyMODINIT_FUNC as a function return type later in this
     229We discuss the use of ``PyMODINIT_FUNC`` as a function return type later in this
    232230sample.
     231
     232The :exc:`spam.error` exception can be raised in your extension module using a
     233call to :c:func:`PyErr_SetString` as shown below::
     234
     235   static PyObject *
     236   spam_system(PyObject *self, PyObject *args)
     237   {
     238       const char *command;
     239       int sts;
     240
     241       if (!PyArg_ParseTuple(args, "s", &command))
     242           return NULL;
     243       sts = system(command);
     244       if (sts < 0) {
     245           PyErr_SetString(SpamError, "System command failed");
     246           return NULL;
     247       }
     248       return PyLong_FromLong(sts);
     249   }
    233250
    234251
    … …  
    246263It returns *NULL* (the error indicator for functions returning object pointers)
    247264if an error is detected in the argument list, relying on the exception set by
    248 :cfunc:`PyArg_ParseTuple`.  Otherwise the string value of the argument has been
    249 copied to the local variable :cdata:`command`.  This is a pointer assignment and
     265:c:func:`PyArg_ParseTuple`.  Otherwise the string value of the argument has been
     266copied to the local variable :c:data:`command`.  This is a pointer assignment and
    250267you are not supposed to modify the string to which it points (so in Standard C,
    251 the variable :cdata:`command` should properly be declared as ``const char
     268the variable :c:data:`command` should properly be declared as ``const char
    252269*command``).
    253270
    254 The next statement is a call to the Unix function :cfunc:`system`, passing it
    255 the string we just got from :cfunc:`PyArg_ParseTuple`::
     271The next statement is a call to the Unix function :c:func:`system`, passing it
     272the string we just got from :c:func:`PyArg_ParseTuple`::
    256273
    257274   sts = system(command);
    258275
    259 Our :func:`spam.system` function must return the value of :cdata:`sts` as a
    260 Python object.  This is done using the function :cfunc:`Py_BuildValue`, which is
    261 something like the inverse of :cfunc:`PyArg_ParseTuple`: it takes a format
     276Our :func:`spam.system` function must return the value of :c:data:`sts` as a
     277Python object.  This is done using the function :c:func:`Py_BuildValue`, which is
     278something like the inverse of :c:func:`PyArg_ParseTuple`: it takes a format
    262279string and an arbitrary number of C values, and returns a new Python object.
    263 More info on :cfunc:`Py_BuildValue` is given later. ::
     280More info on :c:func:`Py_BuildValue` is given later. ::
    264281
    265282   return Py_BuildValue("i", sts);
    … …  
    269286
    270287If you have a C function that returns no useful argument (a function returning
    271 :ctype:`void`), the corresponding Python function must return ``None``.   You
    272 need this idiom to do so (which is implemented by the :cmacro:`Py_RETURN_NONE`
     288:c:type:`void`), the corresponding Python function must return ``None``.   You
     289need this idiom to do so (which is implemented by the :c:macro:`Py_RETURN_NONE`
    273290macro)::
    274291
    … …  
    276293   return Py_None;
    277294
    278 :cdata:`Py_None` is the C name for the special Python object ``None``.  It is a
     295:c:data:`Py_None` is the C name for the special Python object ``None``.  It is a
    279296genuine Python object rather than a *NULL* pointer, which means "error" in most
    280297contexts, as we have seen.
    … …  
    286303=====================================================
    287304
    288 I promised to show how :cfunc:`spam_system` is called from Python programs.
     305I promised to show how :c:func:`spam_system` is called from Python programs.
    289306First, we need to list its name and address in a "method table"::
    290307
    … …  
    300317the calling convention to be used for the C function.  It should normally always
    301318be ``METH_VARARGS`` or ``METH_VARARGS | METH_KEYWORDS``; a value of ``0`` means
    302 that an obsolete variant of :cfunc:`PyArg_ParseTuple` is used.
     319that an obsolete variant of :c:func:`PyArg_ParseTuple` is used.
    303320
    304321When using only ``METH_VARARGS``, the function should expect the Python-level
    305322parameters to be passed in as a tuple acceptable for parsing via
    306 :cfunc:`PyArg_ParseTuple`; more information on this function is provided below.
     323:c:func:`PyArg_ParseTuple`; more information on this function is provided below.
    307324
    308325The :const:`METH_KEYWORDS` bit may be set in the third field if keyword
    309326arguments should be passed to the function.  In this case, the C function should
    310327accept a third ``PyObject *`` parameter which will be a dictionary of keywords.
    311 Use :cfunc:`PyArg_ParseTupleAndKeywords` to parse the arguments to such a
     328Use :c:func:`PyArg_ParseTupleAndKeywords` to parse the arguments to such a
    312329function.
    313330
    314331The method table must be passed to the interpreter in the module's
    315332initialization function.  The initialization function must be named
    316 :cfunc:`initname`, where *name* is the name of the module, and should be the
     333:c:func:`initname`, where *name* is the name of the module, and should be the
    317334only non-\ ``static`` item defined in the module file::
    318335
    … …  
    328345
    329346When the Python program imports module :mod:`spam` for the first time,
    330 :cfunc:`initspam` is called. (See below for comments about embedding Python.)
    331 It calls :cfunc:`Py_InitModule`, which creates a "module object" (which is
     347:c:func:`initspam` is called. (See below for comments about embedding Python.)
     348It calls :c:func:`Py_InitModule`, which creates a "module object" (which is
    332349inserted in the dictionary ``sys.modules`` under the key ``"spam"``), and
    333350inserts built-in function objects into the newly created module based upon the
    334 table (an array of :ctype:`PyMethodDef` structures) that was passed as its
    335 second argument. :cfunc:`Py_InitModule` returns a pointer to the module object
     351table (an array of :c:type:`PyMethodDef` structures) that was passed as its
     352second argument. :c:func:`Py_InitModule` returns a pointer to the module object
    336353that it creates (which is unused here).  It may abort with a fatal error for
    337354certain errors, or return *NULL* if the module could not be initialized
    338355satisfactorily.
    339356
    340 When embedding Python, the :cfunc:`initspam` function is not called
    341 automatically unless there's an entry in the :cdata:`_PyImport_Inittab` table.
     357When embedding Python, the :c:func:`initspam` function is not called
     358automatically unless there's an entry in the :c:data:`_PyImport_Inittab` table.
    342359The easiest way to handle this is to statically initialize your
    343 statically-linked modules by directly calling :cfunc:`initspam` after the call
    344 to :cfunc:`Py_Initialize`::
     360statically-linked modules by directly calling :c:func:`initspam` after the call
     361to :c:func:`Py_Initialize`::
    345362
    346363   int
    … …  
    356373       initspam();
    357374
     375       ...
     376
    358377An example may be found in the file :file:`Demo/embed/demo.c` in the Python
    359378source distribution.
    … …  
    362381
    363382   Removing entries from ``sys.modules`` or importing compiled modules into
    364    multiple interpreters within a process (or following a :cfunc:`fork` without an
    365    intervening :cfunc:`exec`) can create problems for some extension modules.
     383   multiple interpreters within a process (or following a :c:func:`fork` without an
     384   intervening :c:func:`exec`) can create problems for some extension modules.
    366385   Extension module authors should exercise caution when initializing internal data
    367386   structures. Note also that the :func:`reload` function can be used with
    368387   extension modules, and will call the module initialization function
    369    (:cfunc:`initspam` in the example), but will not load the module again if it was
     388   (:c:func:`initspam` in the example), but will not load the module again if it was
    370389   loaded from a dynamically loadable object file (:file:`.so` on Unix,
    371390   :file:`.dll` on Windows).
    … …  
    373392A more substantial example module is included in the Python source distribution
    374393as :file:`Modules/xxmodule.c`.  This file may be used as a  template or simply
    375 read as an example.  The :program:`modulator.py` script included in the source
    376 distribution or Windows install provides  a simple graphical user interface for
    377 declaring the functions and objects which a module should implement, and can
    378 generate a template which can be filled in.  The script lives in the
    379 :file:`Tools/modulator/` directory; see the :file:`README` file there for more
    380 information.
     394read as an example.
    381395
    382396
    … …  
    436450you the Python function object.  You should provide a function (or some other
    437451interface) to do this.  When this function is called, save a pointer to the
    438 Python function object (be careful to :cfunc:`Py_INCREF` it!) in a global
     452Python function object (be careful to :c:func:`Py_INCREF` it!) in a global
    439453variable --- or wherever you see fit. For example, the following function might
    440454be part of a module definition::
    … …  
    465479This function must be registered with the interpreter using the
    466480:const:`METH_VARARGS` flag; this is described in section :ref:`methodtable`.  The
    467 :cfunc:`PyArg_ParseTuple` function and its arguments are documented in section
     481:c:func:`PyArg_ParseTuple` function and its arguments are documented in section
    468482:ref:`parsetuple`.
    469483
    470 The macros :cfunc:`Py_XINCREF` and :cfunc:`Py_XDECREF` increment/decrement the
     484The macros :c:func:`Py_XINCREF` and :c:func:`Py_XDECREF` increment/decrement the
    471485reference count of an object and are safe in the presence of *NULL* pointers
    472486(but note that *temp* will not be  *NULL* in this context).  More info on them
    … …  
    476490
    477491Later, when it is time to call the function, you call the C function
    478 :cfunc:`PyObject_CallObject`.  This function has two arguments, both pointers to
     492:c:func:`PyObject_CallObject`.  This function has two arguments, both pointers to
    479493arbitrary Python objects: the Python function, and the argument list.  The
    480494argument list must always be a tuple object, whose length is the number of
    481495arguments.  To call the Python function with no arguments, pass in NULL, or
    482496an empty tuple; to call it with one argument, pass a singleton tuple.
    483 :cfunc:`Py_BuildValue` returns a tuple when its format string consists of zero
     497:c:func:`Py_BuildValue` returns a tuple when its format string consists of zero
    484498or more format codes between parentheses.  For example::
    485499
    … …  
    495509   Py_DECREF(arglist);
    496510
    497 :cfunc:`PyObject_CallObject` returns a Python object pointer: this is the return
    498 value of the Python function.  :cfunc:`PyObject_CallObject` is
     511:c:func:`PyObject_CallObject` returns a Python object pointer: this is the return
     512value of the Python function.  :c:func:`PyObject_CallObject` is
    499513"reference-count-neutral" with respect to its arguments.  In the example a new
    500 tuple was created to serve as the argument list, which is :cfunc:`Py_DECREF`\
    501 -ed immediately after the call.
    502 
    503 The return value of :cfunc:`PyObject_CallObject` is "new": either it is a brand
     514tuple was created to serve as the argument list, which is :c:func:`Py_DECREF`\
     515-ed immediately after the :c:func:`PyObject_CallObject` call.
     516
     517The return value of :c:func:`PyObject_CallObject` is "new": either it is a brand
    504518new object, or it is an existing object whose reference count has been
    505519incremented.  So, unless you want to save it in a global variable, you should
    506 somehow :cfunc:`Py_DECREF` the result, even (especially!) if you are not
     520somehow :c:func:`Py_DECREF` the result, even (especially!) if you are not
    507521interested in its value.
    508522
    509523Before you do this, however, it is important to check that the return value
    510524isn't *NULL*.  If it is, the Python function terminated by raising an exception.
    511 If the C code that called :cfunc:`PyObject_CallObject` is called from Python, it
     525If the C code that called :c:func:`PyObject_CallObject` is called from Python, it
    512526should now return an error indication to its Python caller, so the interpreter
    513527can print a stack trace, or the calling Python code can handle the exception.
    514528If this is not possible or desirable, the exception should be cleared by calling
    515 :cfunc:`PyErr_Clear`.  For example::
     529:c:func:`PyErr_Clear`.  For example::
    516530
    517531   if (result == NULL)
    … …  
    521535
    522536Depending on the desired interface to the Python callback function, you may also
    523 have to provide an argument list to :cfunc:`PyObject_CallObject`.  In some cases
     537have to provide an argument list to :c:func:`PyObject_CallObject`.  In some cases
    524538the argument list is also provided by the Python program, through the same
    525539interface that specified the callback function.  It can then be saved and used
    526540in the same manner as the function object.  In other cases, you may have to
    527541construct a new tuple to pass as the argument list.  The simplest way to do this
    528 is to call :cfunc:`Py_BuildValue`.  For example, if you want to pass an integral
     542is to call :c:func:`Py_BuildValue`.  For example, if you want to pass an integral
    529543event code, you might use the following code::
    530544
    … …  
    541555Note the placement of ``Py_DECREF(arglist)`` immediately after the call, before
    542556the error check!  Also note that strictly speaking this code is not complete:
    543 :cfunc:`Py_BuildValue` may run out of memory, and this should be checked.
     557:c:func:`Py_BuildValue` may run out of memory, and this should be checked.
    544558
    545559You may also call a function with keyword arguments by using
    546 :cfunc:`PyObject_Call`, which supports arguments and keyword arguments.  As in
    547 the above example, we use :cfunc:`Py_BuildValue` to construct the dictionary. ::
     560:c:func:`PyObject_Call`, which supports arguments and keyword arguments.  As in
     561the above example, we use :c:func:`Py_BuildValue` to construct the dictionary. ::
    548562
    549563   PyObject *dict;
    … …  
    565579.. index:: single: PyArg_ParseTuple()
    566580
    567 The :cfunc:`PyArg_ParseTuple` function is declared as follows::
     581The :c:func:`PyArg_ParseTuple` function is declared as follows::
    568582
    569583   int PyArg_ParseTuple(PyObject *arg, char *format, ...);
    … …  
    575589determined by the format string.
    576590
    577 Note that while :cfunc:`PyArg_ParseTuple` checks that the Python arguments have
     591Note that while :c:func:`PyArg_ParseTuple` checks that the Python arguments have
    578592the required types, it cannot check the validity of the addresses of C variables
    579593passed to the call: if you make mistakes there, your code will probably crash or
    … …  
    652666.. index:: single: PyArg_ParseTupleAndKeywords()
    653667
    654 The :cfunc:`PyArg_ParseTupleAndKeywords` function is declared as follows::
     668The :c:func:`PyArg_ParseTupleAndKeywords` function is declared as follows::
    655669
    656670   int PyArg_ParseTupleAndKeywords(PyObject *arg, PyObject *kwdict,
    … …  
    658672
    659673The *arg* and *format* parameters are identical to those of the
    660 :cfunc:`PyArg_ParseTuple` function.  The *kwdict* parameter is the dictionary of
     674:c:func:`PyArg_ParseTuple` function.  The *kwdict* parameter is the dictionary of
    661675keywords received as the third parameter from the Python runtime.  The *kwlist*
    662676parameter is a *NULL*-terminated list of strings which identify the parameters;
    663677the names are matched with the type information from *format* from left to
    664 right.  On success, :cfunc:`PyArg_ParseTupleAndKeywords` returns true, otherwise
     678right.  On success, :c:func:`PyArg_ParseTupleAndKeywords` returns true, otherwise
    665679it returns false and raises an appropriate exception.
    666680
    … …  
    726740=========================
    727741
    728 This function is the counterpart to :cfunc:`PyArg_ParseTuple`.  It is declared
     742This function is the counterpart to :c:func:`PyArg_ParseTuple`.  It is declared
    729743as follows::
    730744
    … …  
    732746
    733747It recognizes a set of format units similar to the ones recognized by
    734 :cfunc:`PyArg_ParseTuple`, but the arguments (which are input to the function,
     748:c:func:`PyArg_ParseTuple`, but the arguments (which are input to the function,
    735749not output) must not be pointers, just values.  It returns a new Python object,
    736750suitable for returning from a C function called from Python.
    737751
    738 One difference with :cfunc:`PyArg_ParseTuple`: while the latter requires its
     752One difference with :c:func:`PyArg_ParseTuple`: while the latter requires its
    739753first argument to be a tuple (since Python argument lists are always represented
    740 as tuples internally), :cfunc:`Py_BuildValue` does not always build a tuple.  It
     754as tuples internally), :c:func:`Py_BuildValue` does not always build a tuple.  It
    741755builds a tuple only if its format string contains two or more format units. If
    742756the format string is empty, it returns ``None``; if it contains exactly one
    … …  
    770784In languages like C or C++, the programmer is responsible for dynamic allocation
    771785and deallocation of memory on the heap.  In C, this is done using the functions
    772 :cfunc:`malloc` and :cfunc:`free`.  In C++, the operators ``new`` and
     786:c:func:`malloc` and :c:func:`free`.  In C++, the operators ``new`` and
    773787``delete`` are used with essentially the same meaning and we'll restrict
    774788the following discussion to the C case.
    775789
    776 Every block of memory allocated with :cfunc:`malloc` should eventually be
    777 returned to the pool of available memory by exactly one call to :cfunc:`free`.
    778 It is important to call :cfunc:`free` at the right time.  If a block's address
    779 is forgotten but :cfunc:`free` is not called for it, the memory it occupies
     790Every block of memory allocated with :c:func:`malloc` should eventually be
     791returned to the pool of available memory by exactly one call to :c:func:`free`.
     792It is important to call :c:func:`free` at the right time.  If a block's address
     793is forgotten but :c:func:`free` is not called for it, the memory it occupies
    780794cannot be reused until the program terminates.  This is called a :dfn:`memory
    781 leak`.  On the other hand, if a program calls :cfunc:`free` for a block and then
     795leak`.  On the other hand, if a program calls :c:func:`free` for a block and then
    782796continues to use the block, it creates a conflict with re-use of the block
    783 through another :cfunc:`malloc` call.  This is called :dfn:`using freed memory`.
     797through another :c:func:`malloc` call.  This is called :dfn:`using freed memory`.
    784798It has the same bad consequences as referencing uninitialized data --- core
    785799dumps, wrong results, mysterious crashes.
    … …  
    798812strategy that minimizes this kind of errors.
    799813
    800 Since Python makes heavy use of :cfunc:`malloc` and :cfunc:`free`, it needs a
     814Since Python makes heavy use of :c:func:`malloc` and :c:func:`free`, it needs a
    801815strategy to avoid memory leaks as well as the use of freed memory.  The chosen
    802816method is called :dfn:`reference counting`.  The principle is simple: every
    … …  
    810824strategy, hence my use of "automatic" to distinguish the two.)  The big
    811825advantage of automatic garbage collection is that the user doesn't need to call
    812 :cfunc:`free` explicitly.  (Another claimed advantage is an improvement in speed
     826:c:func:`free` explicitly.  (Another claimed advantage is an improvement in speed
    813827or memory usage --- this is no hard fact however.)  The disadvantage is that for
    814828C, there is no truly portable automatic garbage collector, while reference
    815 counting can be implemented portably (as long as the functions :cfunc:`malloc`
    816 and :cfunc:`free` are available --- which the C Standard guarantees). Maybe some
     829counting can be implemented portably (as long as the functions :c:func:`malloc`
     830and :c:func:`free` are available --- which the C Standard guarantees). Maybe some
    817831day a sufficiently portable automatic garbage collector will be available for C.
    818832Until then, we'll have to live with reference counts.
    … …  
    832846as there are no finalizers implemented in Python (:meth:`__del__` methods).
    833847When there are such finalizers, the detector exposes the cycles through the
    834 :mod:`gc` module (specifically, the
    835 ``garbage`` variable in that module).  The :mod:`gc` module also exposes a way
    836 to run the detector (the :func:`collect` function), as well as configuration
     848:mod:`gc` module (specifically, the :attr:`~gc.garbage` variable in that module).
     849The :mod:`gc` module also exposes a way to run the detector (the
     850:func:`~gc.collect` function), as well as configuration
    837851interfaces and the ability to disable the detector at runtime.  The cycle
    838852detector is considered an optional component; though it is included by default,
    … …  
    850864
    851865There are two macros, ``Py_INCREF(x)`` and ``Py_DECREF(x)``, which handle the
    852 incrementing and decrementing of the reference count. :cfunc:`Py_DECREF` also
     866incrementing and decrementing of the reference count. :c:func:`Py_DECREF` also
    853867frees the object when the count reaches zero. For flexibility, it doesn't call
    854 :cfunc:`free` directly --- rather, it makes a call through a function pointer in
     868:c:func:`free` directly --- rather, it makes a call through a function pointer in
    855869the object's :dfn:`type object`.  For this purpose (and others), every object
    856870also contains a pointer to its type object.
    … …  
    860874:dfn:`own a reference` to an object.  An object's reference count is now defined
    861875as the number of owned references to it.  The owner of a reference is
    862 responsible for calling :cfunc:`Py_DECREF` when the reference is no longer
     876responsible for calling :c:func:`Py_DECREF` when the reference is no longer
    863877needed.  Ownership of a reference can be transferred.  There are three ways to
    864 dispose of an owned reference: pass it on, store it, or call :cfunc:`Py_DECREF`.
     878dispose of an owned reference: pass it on, store it, or call :c:func:`Py_DECREF`.
    865879Forgetting to dispose of an owned reference creates a memory leak.
    866880
    867881It is also possible to :dfn:`borrow` [#]_ a reference to an object.  The
    868 borrower of a reference should not call :cfunc:`Py_DECREF`.  The borrower must
     882borrower of a reference should not call :c:func:`Py_DECREF`.  The borrower must
    869883not hold on to the object longer than the owner from which it was borrowed.
    870884Using a borrowed reference after the owner has disposed of it risks using freed
    … …  
    880894
    881895A borrowed reference can be changed into an owned reference by calling
    882 :cfunc:`Py_INCREF`.  This does not affect the status of the owner from which the
     896:c:func:`Py_INCREF`.  This does not affect the status of the owner from which the
    883897reference was borrowed --- it creates a new owned reference, and gives full
    884898owner responsibilities (the new owner must dispose of the reference properly, as
    … …  
    897911Most functions that return a reference to an object pass on ownership with the
    898912reference.  In particular, all functions whose function it is to create a new
    899 object, such as :cfunc:`PyInt_FromLong` and :cfunc:`Py_BuildValue`, pass
     913object, such as :c:func:`PyInt_FromLong` and :c:func:`Py_BuildValue`, pass
    900914ownership to the receiver.  Even if the object is not actually new, you still
    901915receive ownership of a new reference to that object.  For instance,
    902 :cfunc:`PyInt_FromLong` maintains a cache of popular values and can return a
     916:c:func:`PyInt_FromLong` maintains a cache of popular values and can return a
    903917reference to a cached item.
    904918
    905919Many functions that extract objects from other objects also transfer ownership
    906 with the reference, for instance :cfunc:`PyObject_GetAttrString`.  The picture
     920with the reference, for instance :c:func:`PyObject_GetAttrString`.  The picture
    907921is less clear, here, however, since a few common routines are exceptions:
    908 :cfunc:`PyTuple_GetItem`, :cfunc:`PyList_GetItem`, :cfunc:`PyDict_GetItem`, and
    909 :cfunc:`PyDict_GetItemString` all return references that you borrow from the
     922:c:func:`PyTuple_GetItem`, :c:func:`PyList_GetItem`, :c:func:`PyDict_GetItem`, and
     923:c:func:`PyDict_GetItemString` all return references that you borrow from the
    910924tuple, list or dictionary.
    911925
    912 The function :cfunc:`PyImport_AddModule` also returns a borrowed reference, even
     926The function :c:func:`PyImport_AddModule` also returns a borrowed reference, even
    913927though it may actually create the object it returns: this is possible because an
    914928owned reference to the object is stored in ``sys.modules``.
    … …  
    916930When you pass an object reference into another function, in general, the
    917931function borrows the reference from you --- if it needs to store it, it will use
    918 :cfunc:`Py_INCREF` to become an independent owner.  There are exactly two
    919 important exceptions to this rule: :cfunc:`PyTuple_SetItem` and
    920 :cfunc:`PyList_SetItem`.  These functions take over ownership of the item passed
    921 to them --- even if they fail!  (Note that :cfunc:`PyDict_SetItem` and friends
     932:c:func:`Py_INCREF` to become an independent owner.  There are exactly two
     933important exceptions to this rule: :c:func:`PyTuple_SetItem` and
     934:c:func:`PyList_SetItem`.  These functions take over ownership of the item passed
     935to them --- even if they fail!  (Note that :c:func:`PyDict_SetItem` and friends
    922936don't take over ownership --- they are "normal.")
    923937
    … …  
    926940reference's lifetime is guaranteed until the function returns.  Only when such a
    927941borrowed reference must be stored or passed on, it must be turned into an owned
    928 reference by calling :cfunc:`Py_INCREF`.
     942reference by calling :c:func:`Py_INCREF`.
    929943
    930944The object reference returned from a C function that is called from Python must
    … …  
    942956interpreter, which can cause the owner of a reference to dispose of it.
    943957
    944 The first and most important case to know about is using :cfunc:`Py_DECREF` on
     958The first and most important case to know about is using :c:func:`Py_DECREF` on
    945959an unrelated object while borrowing a reference to a list item.  For instance::
    946960
    … …  
    958972Looks harmless, right?  But it's not!
    959973
    960 Let's follow the control flow into :cfunc:`PyList_SetItem`.  The list owns
     974Let's follow the control flow into :c:func:`PyList_SetItem`.  The list owns
    961975references to all its items, so when item 1 is replaced, it has to dispose of
    962976the original item 1.  Now let's suppose the original item 1 was an instance of a
    … …  
    967981Since it is written in Python, the :meth:`__del__` method can execute arbitrary
    968982Python code.  Could it perhaps do something to invalidate the reference to
    969 ``item`` in :cfunc:`bug`?  You bet!  Assuming that the list passed into
    970 :cfunc:`bug` is accessible to the :meth:`__del__` method, it could execute a
     983``item`` in :c:func:`bug`?  You bet!  Assuming that the list passed into
     984:c:func:`bug` is accessible to the :meth:`__del__` method, it could execute a
    971985statement to the effect of ``del list[0]``, and assuming this was the last
    972986reference to that object, it would free the memory associated with it, thereby
    … …  
    9951009other's way, because there is a global lock protecting Python's entire object
    9961010space.  However, it is possible to temporarily release this lock using the macro
    997 :cmacro:`Py_BEGIN_ALLOW_THREADS`, and to re-acquire it using
    998 :cmacro:`Py_END_ALLOW_THREADS`.  This is common around blocking I/O calls, to
     1011:c:macro:`Py_BEGIN_ALLOW_THREADS`, and to re-acquire it using
     1012:c:macro:`Py_END_ALLOW_THREADS`.  This is common around blocking I/O calls, to
    9991013let other threads use the processor while waiting for the I/O to complete.
    10001014Obviously, the following function has the same problem as the previous one::
    … …  
    10251039
    10261040It is better to test for *NULL* only at the "source:" when a pointer that may be
    1027 *NULL* is received, for example, from :cfunc:`malloc` or from a function that
     1041*NULL* is received, for example, from :c:func:`malloc` or from a function that
    10281042may raise an exception.
    10291043
    1030 The macros :cfunc:`Py_INCREF` and :cfunc:`Py_DECREF` do not check for *NULL*
    1031 pointers --- however, their variants :cfunc:`Py_XINCREF` and :cfunc:`Py_XDECREF`
     1044The macros :c:func:`Py_INCREF` and :c:func:`Py_DECREF` do not check for *NULL*
     1045pointers --- however, their variants :c:func:`Py_XINCREF` and :c:func:`Py_XDECREF`
    10321046do.
    10331047
    … …  
    10661080
    10671081
    1068 .. _using-cobjects:
     1082.. _using-capsules:
    10691083
    10701084Providing a C API for an Extension Module
    … …  
    11021116
    11031117Python provides a special mechanism to pass C-level information (pointers) from
    1104 one extension module to another one: CObjects. A CObject is a Python data type
    1105 which stores a pointer (:ctype:`void \*`).  CObjects can only be created and
     1118one extension module to another one: Capsules. A Capsule is a Python data type
     1119which stores a pointer (:c:type:`void \*`).  Capsules can only be created and
    11061120accessed via their C API, but they can be passed around like any other Python
    11071121object. In particular,  they can be assigned to a name in an extension module's
    11081122namespace. Other extension modules can then import this module, retrieve the
    1109 value of this name, and then retrieve the pointer from the CObject.
    1110 
    1111 There are many ways in which CObjects can be used to export the C API of an
    1112 extension module. Each name could get its own CObject, or all C API pointers
    1113 could be stored in an array whose address is published in a CObject. And the
     1123value of this name, and then retrieve the pointer from the Capsule.
     1124
     1125There are many ways in which Capsules can be used to export the C API of an
     1126extension module. Each function could get its own Capsule, or all C API pointers
     1127could be stored in an array whose address is published in a Capsule. And the
    11141128various tasks of storing and retrieving the pointers can be distributed in
    11151129different ways between the module providing the code and the client modules.
     1130
     1131Whichever method you choose, it's important to name your Capsules properly.
     1132The function :c:func:`PyCapsule_New` takes a name parameter
     1133(:c:type:`const char \*`); you're permitted to pass in a *NULL* name, but
     1134we strongly encourage you to specify a name.  Properly named Capsules provide
     1135a degree of runtime type-safety; there is no feasible way to tell one unnamed
     1136Capsule from another.
     1137
     1138In particular, Capsules used to expose C APIs should be given a name following
     1139this convention::
     1140
     1141    modulename.attributename
     1142
     1143The convenience function :c:func:`PyCapsule_Import` makes it easy to
     1144load a C API provided via a Capsule, but only if the Capsule's name
     1145matches this convention.  This behavior gives C API users a high degree
     1146of certainty that the Capsule they load contains the correct C API.
    11161147
    11171148The following example demonstrates an approach that puts most of the burden on
    11181149the writer of the exporting module, which is appropriate for commonly used
    11191150library modules. It stores all C API pointers (just one in the example!) in an
    1120 array of :ctype:`void` pointers which becomes the value of a CObject. The header
     1151array of :c:type:`void` pointers which becomes the value of a Capsule. The header
    11211152file corresponding to the module provides a macro that takes care of importing
    11221153the module and retrieving its C API pointers; client modules only have to call
    … …  
    11251156The exporting module is a modification of the :mod:`spam` module from section
    11261157:ref:`extending-simpleexample`. The function :func:`spam.system` does not call
    1127 the C library function :cfunc:`system` directly, but a function
    1128 :cfunc:`PySpam_System`, which would of course do something more complicated in
     1158the C library function :c:func:`system` directly, but a function
     1159:c:func:`PySpam_System`, which would of course do something more complicated in
    11291160reality (such as adding "spam" to every command). This function
    1130 :cfunc:`PySpam_System` is also exported to other extension modules.
    1131 
    1132 The function :cfunc:`PySpam_System` is a plain C function, declared
     1161:c:func:`PySpam_System` is also exported to other extension modules.
     1162
     1163The function :c:func:`PySpam_System` is a plain C function, declared
    11331164``static`` like everything else::
    11341165
    … …  
    11391170   }
    11401171
    1141 The function :cfunc:`spam_system` is modified in a trivial way::
     1172The function :c:func:`spam_system` is modified in a trivial way::
    11421173
    11431174   static PyObject *
    … …  
    11801211       PySpam_API[PySpam_System_NUM] = (void *)PySpam_System;
    11811212
    1182        /* Create a CObject containing the API pointer array's address */
    1183        c_api_object = PyCObject_FromVoidPtr((void *)PySpam_API, NULL);
     1213       /* Create a Capsule containing the API pointer array's address */
     1214       c_api_object = PyCapsule_New((void *)PySpam_API, "spam._C_API", NULL);
    11841215
    11851216       if (c_api_object != NULL)
    … …  
    12231254    (*(PySpam_System_RETURN (*)PySpam_System_PROTO) PySpam_API[PySpam_System_NUM])
    12241255
    1225    /* Return -1 and set exception on error, 0 on success. */
     1256   /* Return -1 on error, 0 on success.
     1257    * PyCapsule_Import will set an exception if there's an error.
     1258    */
    12261259   static int
    12271260   import_spam(void)
    12281261   {
    1229        PyObject *c_api_object;
    1230        PyObject *module;
    1231 
    1232        module = PyImport_ImportModule("spam");
    1233        if (module == NULL)
    1234            return -1;
    1235 
    1236        c_api_object = PyObject_GetAttrString(module, "_C_API");
    1237        if (c_api_object == NULL) {
    1238            Py_DECREF(module);
    1239            return -1;
    1240        }
    1241        if (PyCObject_Check(c_api_object))
    1242            PySpam_API = (void **)PyCObject_AsVoidPtr(c_api_object);
    1243 
    1244        Py_DECREF(c_api_object);
    1245        Py_DECREF(module);
    1246        return 0;
     1262       PySpam_API = (void **)PyCapsule_Import("spam._C_API", 0);
     1263       return (PySpam_API != NULL) ? 0 : -1;
    12471264   }
    12481265
    … …  
    12561273
    12571274All that a client module must do in order to have access to the function
    1258 :cfunc:`PySpam_System` is to call the function (or rather macro)
    1259 :cfunc:`import_spam` in its initialization function::
     1275:c:func:`PySpam_System` is to call the function (or rather macro)
     1276:c:func:`import_spam` in its initialization function::
    12601277
    12611278   PyMODINIT_FUNC
    … …  
    12761293that is exported, so it has to be learned only once.
    12771294
    1278 Finally it should be mentioned that CObjects offer additional functionality,
     1295Finally it should be mentioned that Capsules offer additional functionality,
    12791296which is especially useful for memory allocation and deallocation of the pointer
    1280 stored in a CObject. The details are described in the Python/C API Reference
    1281 Manual in the section :ref:`cobjects` and in the implementation of CObjects (files
    1282 :file:`Include/cobject.h` and :file:`Objects/cobject.c` in the Python source
     1297stored in a Capsule. The details are described in the Python/C API Reference
     1298Manual in the section :ref:`capsules` and in the implementation of Capsules (files
     1299:file:`Include/pycapsule.h` and :file:`Objects/pycapsule.c` in the Python source
    12831300code distribution).
    12841301
Note: See TracChangeset for help on using the changeset viewer.