tauthon/tauthon2.7
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Import Upstream version 2.7.18

Browse Source
This commit is contained in:
geos_one
2025-08-15 16:28:06 +02:00
commit ba1f69ab39
4521 changed files with 1778434 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
Doc/c-api/abstract.rst Normal file
View File

@@ -0,0 +1,26 @@
.. highlightlang:: c
.. _abstract:
**********************
Abstract Objects Layer
**********************
The functions in this chapter interact with Python objects regardless of their
type, or with wide classes of object types (e.g. all numerical types, or all
sequence types). When used on object types for which they do not apply, they
will raise a Python exception.
It is not possible to use these functions on objects that are not properly
initialized, such as a list object that has been created by :c:func:`PyList_New`,
but whose items have not been set to some non-\ ``NULL`` value yet.
.. toctree::
object.rst
number.rst
sequence.rst
mapping.rst
iter.rst
objbuffer.rst

122
Doc/c-api/allocation.rst Normal file
View File

@@ -0,0 +1,122 @@
.. highlightlang:: c
.. _allocating-objects:
Allocating Objects on the Heap
==============================
.. c:function:: PyObject* _PyObject_New(PyTypeObject *type)
.. c:function:: PyVarObject* _PyObject_NewVar(PyTypeObject *type, Py_ssize_t size)
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: void _PyObject_Del(PyObject *op)
.. c:function:: PyObject* PyObject_Init(PyObject *op, PyTypeObject *type)
Initialize a newly-allocated object *op* with its type and initial
reference. Returns the initialized object. If *type* indicates that the
object participates in the cyclic garbage detector, it is added to the
detector's set of observed objects. Other fields of the object are not
affected.
.. c:function:: PyVarObject* PyObject_InitVar(PyVarObject *op, PyTypeObject *type, Py_ssize_t size)
This does everything :c:func:`PyObject_Init` does, and also initializes the
length information for a variable-size object.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: TYPE* PyObject_New(TYPE, PyTypeObject *type)
Allocate a new Python object using the C structure type *TYPE* and the
Python type object *type*. Fields not defined by the Python object header
are not initialized; the object's reference count will be one. The size of
the memory allocation is determined from the :c:member:`~PyTypeObject.tp_basicsize` field of
the type object.
.. c:function:: TYPE* PyObject_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)
Allocate a new Python object using the C structure type *TYPE* and the
Python type object *type*. Fields not defined by the Python object header
are not initialized. The allocated memory allows for the *TYPE* structure
plus *size* fields of the size given by the :c:member:`~PyTypeObject.tp_itemsize` field of
*type*. This is useful for implementing objects like tuples, which are
able to determine their size at construction time. Embedding the array of
fields into the same allocation decreases the number of allocations,
improving the memory management efficiency.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: void PyObject_Del(PyObject *op)
Releases memory allocated to an object using :c:func:`PyObject_New` or
:c:func:`PyObject_NewVar`. This is normally called from the
:c:member:`~PyTypeObject.tp_dealloc` handler specified in the object's type. The fields of
the object should not be accessed after this call as the memory is no
longer a valid Python object.
.. c:function:: PyObject* Py_InitModule(char *name, PyMethodDef *methods)
Create a new module object based on a name and table of functions,
returning the new module object.
.. versionchanged:: 2.3
Older versions of Python did not support *NULL* as the value for the
*methods* argument.
.. c:function:: PyObject* Py_InitModule3(char *name, PyMethodDef *methods, char *doc)
Create a new module object based on a name and table of functions,
returning the new module object. If *doc* is non-*NULL*, it will be used
to define the docstring for the module.
.. versionchanged:: 2.3
Older versions of Python did not support *NULL* as the value for the
*methods* argument.
.. c:function:: PyObject* Py_InitModule4(char *name, PyMethodDef *methods, char *doc, PyObject *self, int apiver)
Create a new module object based on a name and table of functions,
returning the new module object. If *doc* is non-*NULL*, it will be used
to define the docstring for the module. If *self* is non-*NULL*, it will
be passed to the functions of the module as their (otherwise *NULL*) first
parameter. (This was added as an experimental feature, and there are no
known uses in the current version of Python.) For *apiver*, the only value
which should be passed is defined by the constant
:const:`PYTHON_API_VERSION`.
.. note::
Most uses of this function should probably be using the
:c:func:`Py_InitModule3` instead; only use this if you are sure you need
it.
.. versionchanged:: 2.3
Older versions of Python did not support *NULL* as the value for the
*methods* argument.
.. c:var:: PyObject _Py_NoneStruct
Object which is visible in Python as ``None``. This should only be
accessed using the ``Py_None`` macro, which evaluates to a pointer to this
object.

565
Doc/c-api/arg.rst Normal file
View File

@@ -0,0 +1,565 @@
.. highlightlang:: c
.. _arg-parsing:
Parsing arguments and building values
=====================================
These functions are useful when creating your own extensions functions and
methods. Additional information and examples are available in
:ref:`extending-index`.
The first three of these functions described, :c:func:`PyArg_ParseTuple`,
:c:func:`PyArg_ParseTupleAndKeywords`, and :c:func:`PyArg_Parse`, all use
*format strings* which are used to tell the function about the expected
arguments. The format strings use the same syntax for each of these
functions.
A format string consists of zero or more "format units." A format unit
describes one Python object; it is usually a single character or a
parenthesized sequence of format units. With a few exceptions, a format unit
that is not a parenthesized sequence normally corresponds to a single address
argument to these functions. In the following description, the quoted form is
the format unit; the entry in (round) parentheses is the Python object type
that matches the format unit; and the entry in [square] brackets is the type
of the C variable(s) whose address should be passed.
These formats allow accessing an object as a contiguous chunk of memory.
You don't have to provide raw storage for the returned unicode or bytes
area. Also, you won't have to release any memory yourself, except with the
``es``, ``es#``, ``et`` and ``et#`` formats.
``s`` (string or Unicode) [const char \*]
Convert a Python string or Unicode object to a C pointer to a character
string. You must not provide storage for the string itself; a pointer to
an existing string is stored into the character pointer variable whose
address you pass. The C string is NUL-terminated. The Python string must
not contain embedded NUL bytes; if it does, a :exc:`TypeError` exception is
raised. Unicode objects are converted to C strings using the default
encoding. If this conversion fails, a :exc:`UnicodeError` is raised.
``s#`` (string, Unicode or any read buffer compatible object) [const char \*, int (or :c:type:`Py_ssize_t`, see below)]
This variant on ``s`` stores into two C variables, the first one a pointer
to a character string, the second one its length. In this case the Python
string may contain embedded null bytes. Unicode objects pass back a
pointer to the default encoded string version of the object if such a
conversion is possible. All other read-buffer compatible objects pass back
a reference to the raw internal data representation.
Starting with Python 2.5 the type of the length argument can be controlled
by defining the macro :c:macro:`PY_SSIZE_T_CLEAN` before including
:file:`Python.h`. If the macro is defined, length is a :c:type:`Py_ssize_t`
rather than an int.
``s*`` (string, Unicode, or any buffer compatible object) [Py_buffer]
Similar to ``s#``, this code fills a Py_buffer structure provided by the
caller. The buffer gets locked, so that the caller can subsequently use
the buffer even inside a ``Py_BEGIN_ALLOW_THREADS`` block; the caller is
responsible for calling ``PyBuffer_Release`` with the structure after it
has processed the data.
.. versionadded:: 2.6
``z`` (string, Unicode or ``None``) [const char \*]
Like ``s``, but the Python object may also be ``None``, in which case the C
pointer is set to *NULL*.
``z#`` (string, Unicode, ``None`` or any read buffer compatible object) [const char \*, int]
This is to ``s#`` as ``z`` is to ``s``.
``z*`` (string, Unicode, ``None`` or any buffer compatible object) [Py_buffer]
This is to ``s*`` as ``z`` is to ``s``.
.. versionadded:: 2.6
``u`` (Unicode) [Py_UNICODE \*]
Convert a Python Unicode object to a C pointer to a NUL-terminated buffer
of 16-bit Unicode (UTF-16) data. As with ``s``, there is no need to
provide storage for the Unicode data buffer; a pointer to the existing
Unicode data is stored into the :c:type:`Py_UNICODE` pointer variable whose
address you pass.
``u#`` (Unicode) [Py_UNICODE \*, int]
This variant on ``u`` stores into two C variables, the first one a pointer
to a Unicode data buffer, the second one its length. Non-Unicode objects
are handled by interpreting their read-buffer pointer as pointer to a
:c:type:`Py_UNICODE` array.
``es`` (string, Unicode or character buffer compatible object) [const char \*encoding, char \*\*buffer]
This variant on ``s`` is used for encoding Unicode and objects convertible
to Unicode into a character buffer. It only works for encoded data without
embedded NUL bytes.
This format requires two arguments. The first is only used as input, and
must be a :c:type:`const char\*` which points to the name of an encoding as
a NUL-terminated string, or *NULL*, in which case the default encoding is
used. An exception is raised if the named encoding is not known to Python.
The second argument must be a :c:type:`char\*\*`; the value of the pointer
it references will be set to a buffer with the contents of the argument
text. The text will be encoded in the encoding specified by the first
argument.
:c:func:`PyArg_ParseTuple` will allocate a buffer of the needed size, copy
the encoded data into this buffer and adjust *\*buffer* to reference the
newly allocated storage. The caller is responsible for calling
:c:func:`PyMem_Free` to free the allocated buffer after use.
``et`` (string, Unicode or character buffer compatible object) [const char \*encoding, char \*\*buffer]
Same as ``es`` except that 8-bit string objects are passed through without
recoding them. Instead, the implementation assumes that the string object
uses the encoding passed in as parameter.
``es#`` (string, Unicode or character buffer compatible object) [const char \*encoding, char \*\*buffer, int \*buffer_length]
This variant on ``s#`` is used for encoding Unicode and objects convertible
to Unicode into a character buffer. Unlike the ``es`` format, this variant
allows input data which contains NUL characters.
It requires three arguments. The first is only used as input, and must be
a :c:type:`const char\*` which points to the name of an encoding as a
NUL-terminated string, or *NULL*, in which case the default encoding is
used. An exception is raised if the named encoding is not known to Python.
The second argument must be a :c:type:`char\*\*`; the value of the pointer
it references will be set to a buffer with the contents of the argument
text. The text will be encoded in the encoding specified by the first
argument. The third argument must be a pointer to an integer; the
referenced integer will be set to the number of bytes in the output buffer.
There are two modes of operation:
If *\*buffer* points a *NULL* pointer, the function will allocate a buffer
of the needed size, copy the encoded data into this buffer and set
*\*buffer* to reference the newly allocated storage. The caller is
responsible for calling :c:func:`PyMem_Free` to free the allocated buffer
after usage.
If *\*buffer* points to a non-*NULL* pointer (an already allocated buffer),
:c:func:`PyArg_ParseTuple` will use this location as the buffer and
interpret the initial value of *\*buffer_length* as the buffer size. It
will then copy the encoded data into the buffer and NUL-terminate it. If
the buffer is not large enough, a :exc:`TypeError` will be set.
Note: starting from Python 3.6 a :exc:`ValueError` will be set.
In both cases, *\*buffer_length* is set to the length of the encoded data
without the trailing NUL byte.
``et#`` (string, Unicode or character buffer compatible object) [const char \*encoding, char \*\*buffer, int \*buffer_length]
Same as ``es#`` except that string objects are passed through without
recoding them. Instead, the implementation assumes that the string object
uses the encoding passed in as parameter.
``b`` (integer) [unsigned char]
Convert a nonnegative Python integer to an unsigned tiny int, stored in a C
:c:type:`unsigned char`.
``B`` (integer) [unsigned char]
Convert a Python integer to a tiny int without overflow checking, stored in
a C :c:type:`unsigned char`.
.. versionadded:: 2.3
``h`` (integer) [short int]
Convert a Python integer to a C :c:type:`short int`.
``H`` (integer) [unsigned short int]
Convert a Python integer to a C :c:type:`unsigned short int`, without
overflow checking.
.. versionadded:: 2.3
``i`` (integer) [int]
Convert a Python integer to a plain C :c:type:`int`.
``I`` (integer) [unsigned int]
Convert a Python integer to a C :c:type:`unsigned int`, without overflow
checking.
.. versionadded:: 2.3
``l`` (integer) [long int]
Convert a Python integer to a C :c:type:`long int`.
``k`` (integer) [unsigned long]
Convert a Python integer or long integer to a C :c:type:`unsigned long`
without overflow checking.
.. versionadded:: 2.3
``L`` (integer) [PY_LONG_LONG]
Convert a Python integer to a C :c:type:`long long`. This format is only
available on platforms that support :c:type:`long long` (or :c:type:`_int64`
on Windows).
``K`` (integer) [unsigned PY_LONG_LONG]
Convert a Python integer or long integer to a C :c:type:`unsigned long long`
without overflow checking. This format is only available on platforms that
support :c:type:`unsigned long long` (or :c:type:`unsigned _int64` on
Windows).
.. versionadded:: 2.3
``n`` (integer) [Py_ssize_t]
Convert a Python integer or long integer to a C :c:type:`Py_ssize_t`.
.. versionadded:: 2.5
``c`` (string of length 1) [char]
Convert a Python character, represented as a string of length 1, to a C
:c:type:`char`.
``f`` (float) [float]
Convert a Python floating point number to a C :c:type:`float`.
``d`` (float) [double]
Convert a Python floating point number to a C :c:type:`double`.
``D`` (complex) [Py_complex]
Convert a Python complex number to a C :c:type:`Py_complex` structure.
``O`` (object) [PyObject \*]
Store a Python object (without any conversion) in a C object pointer. The
C program thus receives the actual object that was passed. The object's
reference count is not increased. The pointer stored is not *NULL*.
``O!`` (object) [*typeobject*, PyObject \*]
Store a Python object in a C object pointer. This is similar to ``O``, but
takes two C arguments: the first is the address of a Python type object,
the second is the address of the C variable (of type :c:type:`PyObject\*`)
into which the object pointer is stored. If the Python object does not
have the required type, :exc:`TypeError` is raised.
``O&`` (object) [*converter*, *anything*]
Convert a Python object to a C variable through a *converter* function.
This takes two arguments: the first is a function, the second is the
address of a C variable (of arbitrary type), converted to :c:type:`void \*`.
The *converter* function in turn is called as follows::
status = converter(object, address);
where *object* is the Python object to be converted and *address* is the
:c:type:`void\*` argument that was passed to the :c:func:`PyArg_Parse\*`
function. The returned *status* should be ``1`` for a successful
conversion and ``0`` if the conversion has failed. When the conversion
fails, the *converter* function should raise an exception and leave the
content of *address* unmodified.
``S`` (string) [PyStringObject \*]
Like ``O`` but requires that the Python object is a string object. Raises
:exc:`TypeError` if the object is not a string object. The C variable may
also be declared as :c:type:`PyObject\*`.
``U`` (Unicode string) [PyUnicodeObject \*]
Like ``O`` but requires that the Python object is a Unicode object. Raises
:exc:`TypeError` if the object is not a Unicode object. The C variable may
also be declared as :c:type:`PyObject\*`.
``t#`` (read-only character buffer) [char \*, int]
Like ``s#``, but accepts any object which implements the read-only buffer
interface. The :c:type:`char\*` variable is set to point to the first byte
of the buffer, and the :c:type:`int` is set to the length of the buffer.
Only single-segment buffer objects are accepted; :exc:`TypeError` is raised
for all others.
``w`` (read-write character buffer) [char \*]
Similar to ``s``, but accepts any object which implements the read-write
buffer interface. The caller must determine the length of the buffer by
other means, or use ``w#`` instead. Only single-segment buffer objects are
accepted; :exc:`TypeError` is raised for all others.
``w#`` (read-write character buffer) [char \*, Py_ssize_t]
Like ``s#``, but accepts any object which implements the read-write buffer
interface. The :c:type:`char \*` variable is set to point to the first byte
of the buffer, and the :c:type:`Py_ssize_t` is set to the length of the
buffer. Only single-segment buffer objects are accepted; :exc:`TypeError`
is raised for all others.
``w*`` (read-write byte-oriented buffer) [Py_buffer]
This is to ``w`` what ``s*`` is to ``s``.
.. versionadded:: 2.6
``(items)`` (tuple) [*matching-items*]
The object must be a Python sequence whose length is the number of format
units in *items*. The C arguments must correspond to the individual format
units in *items*. Format units for sequences may be nested.
.. note::
Prior to Python version 1.5.2, this format specifier only accepted a
tuple containing the individual parameters, not an arbitrary sequence.
Code which previously caused :exc:`TypeError` to be raised here may now
proceed without an exception. This is not expected to be a problem for
existing code.
It is possible to pass Python long integers where integers are requested;
however no proper range checking is done --- the most significant bits are
silently truncated when the receiving field is too small to receive the value
(actually, the semantics are inherited from downcasts in C --- your mileage
may vary).
A few other characters have a meaning in a format string. These may not occur
inside nested parentheses. They are:
``|``
Indicates that the remaining arguments in the Python argument list are
optional. The C variables corresponding to optional arguments should be
initialized to their default value --- when an optional argument is not
specified, :c:func:`PyArg_ParseTuple` does not touch the contents of the
corresponding C variable(s).
``:``
The list of format units ends here; the string after the colon is used as
the function name in error messages (the "associated value" of the
exception that :c:func:`PyArg_ParseTuple` raises).
``;``
The list of format units ends here; the string after the semicolon is used
as the error message *instead* of the default error message. ``:`` and
``;`` mutually exclude each other.
Note that any Python object references which are provided to the caller are
*borrowed* references; do not decrement their reference count!
Additional arguments passed to these functions must be addresses of variables
whose type is determined by the format string; these are used to store values
from the input tuple. There are a few cases, as described in the list of
format units above, where these parameters are used as input values; they
should match what is specified for the corresponding format unit in that case.
For the conversion to succeed, the *arg* object must match the format and the
format must be exhausted. On success, the :c:func:`PyArg_Parse\*` functions
return true, otherwise they return false and raise an appropriate exception.
When the :c:func:`PyArg_Parse\*` functions fail due to conversion failure in
one of the format units, the variables at the addresses corresponding to that
and the following format units are left untouched.
.. c:function:: int PyArg_ParseTuple(PyObject *args, const char *format, ...)
Parse the parameters of a function that takes only positional parameters
into local variables. Returns true on success; on failure, it returns
false and raises the appropriate exception.
.. c:function:: int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)
Identical to :c:func:`PyArg_ParseTuple`, except that it accepts a va_list
rather than a variable number of arguments.
.. c:function:: int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], ...)
Parse the parameters of a function that takes both positional and keyword
parameters into local variables. Returns true on success; on failure, it
returns false and raises the appropriate exception.
.. c:function:: int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], va_list vargs)
Identical to :c:func:`PyArg_ParseTupleAndKeywords`, except that it accepts a
va_list rather than a variable number of arguments.
.. c:function:: int PyArg_Parse(PyObject *args, const char *format, ...)
Function used to deconstruct the argument lists of "old-style" functions
--- these are functions which use the :const:`METH_OLDARGS` parameter
parsing method. This is not recommended for use in parameter parsing in
new code, and most code in the standard interpreter has been modified to no
longer use this for that purpose. It does remain a convenient way to
decompose other tuples, however, and may continue to be used for that
purpose.
.. c:function:: int PyArg_UnpackTuple(PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...)
A simpler form of parameter retrieval which does not use a format string to
specify the types of the arguments. Functions which use this method to
retrieve their parameters should be declared as :const:`METH_VARARGS` in
function or method tables. The tuple containing the actual parameters
should be passed as *args*; it must actually be a tuple. The length of the
tuple must be at least *min* and no more than *max*; *min* and *max* may be
equal. Additional arguments must be passed to the function, each of which
should be a pointer to a :c:type:`PyObject\*` variable; these will be filled
in with the values from *args*; they will contain borrowed references. The
variables which correspond to optional parameters not given by *args* will
not be filled in; these should be initialized by the caller. This function
returns true on success and false if *args* is not a tuple or contains the
wrong number of elements; an exception will be set if there was a failure.
This is an example of the use of this function, taken from the sources for
the :mod:`_weakref` helper module for weak references::
static PyObject *
weakref_ref(PyObject *self, PyObject *args)
{
PyObject *object;
PyObject *callback = NULL;
PyObject *result = NULL;
if (PyArg_UnpackTuple(args, "ref", 1, 2, &object, &callback)) {
result = PyWeakref_NewRef(object, callback);
}
return result;
}
The call to :c:func:`PyArg_UnpackTuple` in this example is entirely
equivalent to this call to :c:func:`PyArg_ParseTuple`::
PyArg_ParseTuple(args, "O|O:ref", &object, &callback)
.. versionadded:: 2.2
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *min* and *max*. This might
require changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* Py_BuildValue(const char *format, ...)
Create a new value based on a format string similar to those accepted by
the :c:func:`PyArg_Parse\*` family of functions and a sequence of values.
Returns the value or *NULL* in the case of an error; an exception will be
raised if *NULL* is returned.
:c:func:`Py_BuildValue` does not always build a tuple. It builds a tuple
only if its format string contains two or more format units. If the format
string is empty, it returns ``None``; if it contains exactly one format
unit, it returns whatever object is described by that format unit. To
force it to return a tuple of size ``0`` or one, parenthesize the format
string.
When memory buffers are passed as parameters to supply data to build
objects, as for the ``s`` and ``s#`` formats, the required data is copied.
Buffers provided by the caller are never referenced by the objects created
by :c:func:`Py_BuildValue`. In other words, if your code invokes
:c:func:`malloc` and passes the allocated memory to :c:func:`Py_BuildValue`,
your code is responsible for calling :c:func:`free` for that memory once
:c:func:`Py_BuildValue` returns.
In the following description, the quoted form is the format unit; the entry
in (round) parentheses is the Python object type that the format unit will
return; and the entry in [square] brackets is the type of the C value(s) to
be passed.
The characters space, tab, colon and comma are ignored in format strings
(but not within format units such as ``s#``). This can be used to make
long format strings a tad more readable.
``s`` (string) [char \*]
Convert a null-terminated C string to a Python object. If the C string
pointer is *NULL*, ``None`` is used.
``s#`` (string) [char \*, int]
Convert a C string and its length to a Python object. If the C string
pointer is *NULL*, the length is ignored and ``None`` is returned.
``z`` (string or ``None``) [char \*]
Same as ``s``.
``z#`` (string or ``None``) [char \*, int]
Same as ``s#``.
``u`` (Unicode string) [Py_UNICODE \*]
Convert a null-terminated buffer of Unicode (UCS-2 or UCS-4) data to a
Python Unicode object. If the Unicode buffer pointer is *NULL*,
``None`` is returned.
``u#`` (Unicode string) [Py_UNICODE \*, int]
Convert a Unicode (UCS-2 or UCS-4) data buffer and its length to a
Python Unicode object. If the Unicode buffer pointer is *NULL*, the
length is ignored and ``None`` is returned.
``i`` (integer) [int]
Convert a plain C :c:type:`int` to a Python integer object.
``b`` (integer) [char]
Convert a plain C :c:type:`char` to a Python integer object.
``h`` (integer) [short int]
Convert a plain C :c:type:`short int` to a Python integer object.
``l`` (integer) [long int]
Convert a C :c:type:`long int` to a Python integer object.
``B`` (integer) [unsigned char]
Convert a C :c:type:`unsigned char` to a Python integer object.
``H`` (integer) [unsigned short int]
Convert a C :c:type:`unsigned short int` to a Python integer object.
``I`` (integer/long) [unsigned int]
Convert a C :c:type:`unsigned int` to a Python integer object or a Python
long integer object, if it is larger than ``sys.maxint``.
``k`` (integer/long) [unsigned long]
Convert a C :c:type:`unsigned long` to a Python integer object or a
Python long integer object, if it is larger than ``sys.maxint``.
``L`` (long) [PY_LONG_LONG]
Convert a C :c:type:`long long` to a Python long integer object. Only
available on platforms that support :c:type:`long long`.
``K`` (long) [unsigned PY_LONG_LONG]
Convert a C :c:type:`unsigned long long` to a Python long integer object.
Only available on platforms that support :c:type:`unsigned long long`.
``n`` (int) [Py_ssize_t]
Convert a C :c:type:`Py_ssize_t` to a Python integer or long integer.
.. versionadded:: 2.5
``c`` (string of length 1) [char]
Convert a C :c:type:`int` representing a character to a Python string of
length 1.
``d`` (float) [double]
Convert a C :c:type:`double` to a Python floating point number.
``f`` (float) [float]
Same as ``d``.
``D`` (complex) [Py_complex \*]
Convert a C :c:type:`Py_complex` structure to a Python complex number.
``O`` (object) [PyObject \*]
Pass a Python object untouched (except for its reference count, which is
incremented by one). If the object passed in is a *NULL* pointer, it is
assumed that this was caused because the call producing the argument
found an error and set an exception. Therefore, :c:func:`Py_BuildValue`
will return *NULL* but won't raise an exception. If no exception has
been raised yet, :exc:`SystemError` is set.
``S`` (object) [PyObject \*]
Same as ``O``.
``N`` (object) [PyObject \*]
Same as ``O``, except it doesn't increment the reference count on the
object. Useful when the object is created by a call to an object
constructor in the argument list.
``O&`` (object) [*converter*, *anything*]
Convert *anything* to a Python object through a *converter* function.
The function is called with *anything* (which should be compatible with
:c:type:`void \*`) as its argument and should return a "new" Python
object, or *NULL* if an error occurred.
``(items)`` (tuple) [*matching-items*]
Convert a sequence of C values to a Python tuple with the same number of
items.
``[items]`` (list) [*matching-items*]
Convert a sequence of C values to a Python list with the same number of
items.
``{items}`` (dictionary) [*matching-items*]
Convert a sequence of C values to a Python dictionary. Each pair of
consecutive C values adds one item to the dictionary, serving as key and
value, respectively.
If there is an error in the format string, the :exc:`SystemError` exception
is set and *NULL* returned.
.. c:function:: PyObject* Py_VaBuildValue(const char *format, va_list vargs)
Identical to :c:func:`Py_BuildValue`, except that it accepts a va_list
rather than a variable number of arguments.

54
Doc/c-api/bool.rst Normal file
View File

@@ -0,0 +1,54 @@
.. highlightlang:: c
.. _boolobjects:
Boolean Objects
---------------
Booleans in Python are implemented as a subclass of integers. There are only
two booleans, :const:`Py_False` and :const:`Py_True`. As such, the normal
creation and deletion functions don't apply to booleans. The following macros
are available, however.
.. c:function:: int PyBool_Check(PyObject *o)
Return true if *o* is of type :c:data:`PyBool_Type`.
.. versionadded:: 2.3
.. c:var:: PyObject* Py_False
The Python ``False`` object. This object has no methods. It needs to be
treated just like any other object with respect to reference counts.
.. c:var:: PyObject* Py_True
The Python ``True`` object. This object has no methods. It needs to be treated
just like any other object with respect to reference counts.
.. c:macro:: Py_RETURN_FALSE
Return :const:`Py_False` from a function, properly incrementing its reference
count.
.. versionadded:: 2.4
.. c:macro:: Py_RETURN_TRUE
Return :const:`Py_True` from a function, properly incrementing its reference
count.
.. versionadded:: 2.4
.. c:function:: PyObject* PyBool_FromLong(long v)
Return a new reference to :const:`Py_True` or :const:`Py_False` depending on the
truth value of *v*.
.. versionadded:: 2.3

455
Doc/c-api/buffer.rst Normal file
View File

@@ -0,0 +1,455 @@
.. highlightlang:: c
.. _bufferobjects:
Buffers and Memoryview Objects
------------------------------
.. sectionauthor:: Greg Stein <gstein@lyra.org>
.. sectionauthor:: Benjamin Peterson
.. index::
object: buffer
single: buffer interface
Python objects implemented in C can export a group of functions called the
"buffer interface." These functions can be used by an object to expose its
data in a raw, byte-oriented format. Clients of the object can use the buffer
interface to access the object data directly, without needing to copy it
first.
Two examples of objects that support the buffer interface are strings and
arrays. The string object exposes the character contents in the buffer
interface's byte-oriented form. An array can only expose its contents via the
old-style buffer interface. This limitation does not apply to Python 3,
where :class:`memoryview` objects can be constructed from arrays, too.
Array elements may be multi-byte values.
An example user of the buffer interface is the file object's :meth:`write`
method. Any object that can export a series of bytes through the buffer
interface can be written to a file. There are a number of format codes to
:c:func:`PyArg_ParseTuple` that operate against an object's buffer interface,
returning data from the target object.
Starting from version 1.6, Python has been providing Python-level buffer
objects and a C-level buffer API so that any built-in or used-defined type can
expose its characteristics. Both, however, have been deprecated because of
various shortcomings, and have been officially removed in Python 3 in favour
of a new C-level buffer API and a new Python-level object named
:class:`memoryview`.
The new buffer API has been backported to Python 2.6, and the
:class:`memoryview` object has been backported to Python 2.7. It is strongly
advised to use them rather than the old APIs, unless you are blocked from
doing so for compatibility reasons.
The new-style Py_buffer struct
==============================
.. c:type:: Py_buffer
.. c:member:: void *buf
A pointer to the start of the memory for the object.
.. c:member:: Py_ssize_t len
:noindex:
The total length of the memory in bytes.
.. c:member:: int readonly
An indicator of whether the buffer is read only.
.. c:member:: const char *format
:noindex:
A *NULL* terminated string in :mod:`struct` module style syntax giving
the contents of the elements available through the buffer. If this is
*NULL*, ``"B"`` (unsigned bytes) is assumed.
.. c:member:: int ndim
The number of dimensions the memory represents as a multi-dimensional
array. If it is ``0``, :c:data:`strides` and :c:data:`suboffsets` must be
*NULL*.
.. c:member:: Py_ssize_t *shape
An array of :c:type:`Py_ssize_t`\s the length of :c:data:`ndim` giving the
shape of the memory as a multi-dimensional array. Note that
``((*shape)[0] * ... * (*shape)[ndims-1])*itemsize`` should be equal to
:c:data:`len`.
.. c:member:: Py_ssize_t *strides
An array of :c:type:`Py_ssize_t`\s the length of :c:data:`ndim` giving the
number of bytes to skip to get to a new element in each dimension.
.. c:member:: Py_ssize_t *suboffsets
An array of :c:type:`Py_ssize_t`\s the length of :c:data:`ndim`. If these
suboffset numbers are greater than or equal to 0, then the value stored
along the indicated dimension is a pointer and the suboffset value
dictates how many bytes to add to the pointer after de-referencing. A
suboffset value that it negative indicates that no de-referencing should
occur (striding in a contiguous memory block).
If all suboffsets are negative (i.e. no de-referencing is needed), then
this field must be NULL (the default value).
Here is a function that returns a pointer to the element in an N-D array
pointed to by an N-dimensional index when there are both non-NULL strides
and suboffsets::
void *get_item_pointer(int ndim, void *buf, Py_ssize_t *strides,
Py_ssize_t *suboffsets, Py_ssize_t *indices) {
char *pointer = (char*)buf;
int i;
for (i = 0; i < ndim; i++) {
pointer += strides[i] * indices[i];
if (suboffsets[i] >=0 ) {
pointer = *((char**)pointer) + suboffsets[i];
}
}
return (void*)pointer;
}
.. c:member:: Py_ssize_t itemsize
This is a storage for the itemsize (in bytes) of each element of the
shared memory. It is technically un-necessary as it can be obtained
using :c:func:`PyBuffer_SizeFromFormat`, however an exporter may know
this information without parsing the format string and it is necessary
to know the itemsize for proper interpretation of striding. Therefore,
storing it is more convenient and faster.
.. c:member:: void *internal
This is for use internally by the exporting object. For example, this
might be re-cast as an integer by the exporter and used to store flags
about whether or not the shape, strides, and suboffsets arrays must be
freed when the buffer is released. The consumer should never alter this
value.
Buffer related functions
========================
.. c:function:: int PyObject_CheckBuffer(PyObject *obj)
Return ``1`` if *obj* supports the buffer interface otherwise ``0``.
.. c:function:: int PyObject_GetBuffer(PyObject *obj, Py_buffer *view, int flags)
Export *obj* into a :c:type:`Py_buffer`, *view*. These arguments must
never be *NULL*. The *flags* argument is a bit field indicating what
kind of buffer the caller is prepared to deal with and therefore what
kind of buffer the exporter is allowed to return. The buffer interface
allows for complicated memory sharing possibilities, but some caller may
not be able to handle all the complexity but may want to see if the
exporter will let them take a simpler view to its memory.
Some exporters may not be able to share memory in every possible way and
may need to raise errors to signal to some consumers that something is
just not possible. These errors should be a :exc:`BufferError` unless
there is another error that is actually causing the problem. The
exporter can use flags information to simplify how much of the
:c:data:`Py_buffer` structure is filled in with non-default values and/or
raise an error if the object can't support a simpler view of its memory.
``0`` is returned on success and ``-1`` on error.
The following table gives possible values to the *flags* arguments.
+-------------------------------+---------------------------------------------------+
| Flag | Description |
+===============================+===================================================+
| :c:macro:`PyBUF_SIMPLE` | This is the default flag state. The returned |
| | buffer may or may not have writable memory. The |
| | format of the data will be assumed to be unsigned |
| | bytes. This is a "stand-alone" flag constant. It |
| | never needs to be '|'d to the others. The exporter|
| | will raise an error if it cannot provide such a |
| | contiguous buffer of bytes. |
| | |
+-------------------------------+---------------------------------------------------+
| :c:macro:`PyBUF_WRITABLE` | The returned buffer must be writable. If it is |
| | not writable, then raise an error. |
+-------------------------------+---------------------------------------------------+
| :c:macro:`PyBUF_STRIDES` | This implies :c:macro:`PyBUF_ND`. The returned |
| | buffer must provide strides information (i.e. the |
| | strides cannot be NULL). This would be used when |
| | the consumer can handle strided, discontiguous |
| | arrays. Handling strides automatically assumes |
| | you can handle shape. The exporter can raise an |
| | error if a strided representation of the data is |
| | not possible (i.e. without the suboffsets). |
| | |
+-------------------------------+---------------------------------------------------+
| :c:macro:`PyBUF_ND` | The returned buffer must provide shape |
| | information. The memory will be assumed C-style |
| | contiguous (last dimension varies the |
| | fastest). The exporter may raise an error if it |
| | cannot provide this kind of contiguous buffer. If |
| | this is not given then shape will be *NULL*. |
| | |
| | |
| | |
+-------------------------------+---------------------------------------------------+
|:c:macro:`PyBUF_C_CONTIGUOUS` | These flags indicate that the contiguity returned |
|:c:macro:`PyBUF_F_CONTIGUOUS` | buffer must be respectively, C-contiguous (last |
|:c:macro:`PyBUF_ANY_CONTIGUOUS`| dimension varies the fastest), Fortran contiguous |
| | (first dimension varies the fastest) or either |
| | one. All of these flags imply |
| | :c:macro:`PyBUF_STRIDES` and guarantee that the |
| | strides buffer info structure will be filled in |
| | correctly. |
| | |
+-------------------------------+---------------------------------------------------+
| :c:macro:`PyBUF_INDIRECT` | This flag indicates the returned buffer must have |
| | suboffsets information (which can be NULL if no |
| | suboffsets are needed). This can be used when |
| | the consumer can handle indirect array |
| | referencing implied by these suboffsets. This |
| | implies :c:macro:`PyBUF_STRIDES`. |
| | |
| | |
| | |
+-------------------------------+---------------------------------------------------+
| :c:macro:`PyBUF_FORMAT` | The returned buffer must have true format |
| | information if this flag is provided. This would |
| | be used when the consumer is going to be checking |
| | for what 'kind' of data is actually stored. An |
| | exporter should always be able to provide this |
| | information if requested. If format is not |
| | explicitly requested then the format must be |
| | returned as *NULL* (which means ``'B'``, or |
| | unsigned bytes) |
+-------------------------------+---------------------------------------------------+
| :c:macro:`PyBUF_STRIDED` | This is equivalent to ``(PyBUF_STRIDES | |
| | PyBUF_WRITABLE)``. |
+-------------------------------+---------------------------------------------------+
| :c:macro:`PyBUF_STRIDED_RO` | This is equivalent to ``(PyBUF_STRIDES)``. |
| | |
+-------------------------------+---------------------------------------------------+
| :c:macro:`PyBUF_RECORDS` | This is equivalent to ``(PyBUF_STRIDES | |
| | PyBUF_FORMAT | PyBUF_WRITABLE)``. |
+-------------------------------+---------------------------------------------------+
| :c:macro:`PyBUF_RECORDS_RO` | This is equivalent to ``(PyBUF_STRIDES | |
| | PyBUF_FORMAT)``. |
+-------------------------------+---------------------------------------------------+
| :c:macro:`PyBUF_FULL` | This is equivalent to ``(PyBUF_INDIRECT | |
| | PyBUF_FORMAT | PyBUF_WRITABLE)``. |
+-------------------------------+---------------------------------------------------+
| :c:macro:`PyBUF_FULL_RO` | This is equivalent to ``(PyBUF_INDIRECT | |
| | PyBUF_FORMAT)``. |
+-------------------------------+---------------------------------------------------+
| :c:macro:`PyBUF_CONTIG` | This is equivalent to ``(PyBUF_ND | |
| | PyBUF_WRITABLE)``. |
+-------------------------------+---------------------------------------------------+
| :c:macro:`PyBUF_CONTIG_RO` | This is equivalent to ``(PyBUF_ND)``. |
| | |
+-------------------------------+---------------------------------------------------+
.. c:function:: void PyBuffer_Release(Py_buffer *view)
Release the buffer *view*. This should be called when the buffer
is no longer being used as it may free memory from it.
.. c:function:: Py_ssize_t PyBuffer_SizeFromFormat(const char *)
Return the implied :c:data:`~Py_buffer.itemsize` from the struct-stype
:c:data:`~Py_buffer.format`.
.. c:function:: int PyBuffer_IsContiguous(Py_buffer *view, char fortran)
Return ``1`` if the memory defined by the *view* is C-style (*fortran* is
``'C'``) or Fortran-style (*fortran* is ``'F'``) contiguous or either one
(*fortran* is ``'A'``). Return ``0`` otherwise.
.. c:function:: void PyBuffer_FillContiguousStrides(int ndims, Py_ssize_t *shape, Py_ssize_t *strides, int itemsize, char fortran)
Fill the *strides* array with byte-strides of a contiguous (C-style if
*fortran* is ``'C'`` or Fortran-style if *fortran* is ``'F'``) array of the
given shape with the given number of bytes per element.
.. c:function:: int PyBuffer_FillInfo(Py_buffer *view, PyObject *obj, void *buf, Py_ssize_t len, int readonly, int infoflags)
Fill in a buffer-info structure, *view*, correctly for an exporter that can
only share a contiguous chunk of memory of "unsigned bytes" of the given
length. Return ``0`` on success and ``-1`` (with raising an error) on error.
MemoryView objects
==================
.. versionadded:: 2.7
A :class:`memoryview` object exposes the new C level buffer interface as a
Python object which can then be passed around like any other object.
.. c:function:: PyObject *PyMemoryView_FromObject(PyObject *obj)
Create a memoryview object from an object that defines the new buffer
interface.
.. c:function:: PyObject *PyMemoryView_FromBuffer(Py_buffer *view)
Create a memoryview object wrapping the given buffer-info structure *view*.
The memoryview object then owns the buffer, which means you shouldn't
try to release it yourself: it will be released on deallocation of the
memoryview object.
.. c:function:: PyObject *PyMemoryView_GetContiguous(PyObject *obj, int buffertype, char order)
Create a memoryview object to a contiguous chunk of memory (in either
'C' or 'F'ortran *order*) from an object that defines the buffer
interface. If memory is contiguous, the memoryview object points to the
original memory. Otherwise copy is made and the memoryview points to a
new bytes object.
.. c:function:: int PyMemoryView_Check(PyObject *obj)
Return true if the object *obj* is a memoryview object. It is not
currently allowed to create subclasses of :class:`memoryview`.
.. c:function:: Py_buffer *PyMemoryView_GET_BUFFER(PyObject *obj)
Return a pointer to the buffer-info structure wrapped by the given
object. The object **must** be a memoryview instance; this macro doesn't
check its type, you must do it yourself or you will risk crashes.
Old-style buffer objects
========================
.. index:: single: PyBufferProcs
More information on the old buffer interface is provided in the section
:ref:`buffer-structs`, under the description for :c:type:`PyBufferProcs`.
A "buffer object" is defined in the :file:`bufferobject.h` header (included by
:file:`Python.h`). These objects look very similar to string objects at the
Python programming level: they support slicing, indexing, concatenation, and
some other standard string operations. However, their data can come from one
of two sources: from a block of memory, or from another object which exports
the buffer interface.
Buffer objects are useful as a way to expose the data from another object's
buffer interface to the Python programmer. They can also be used as a
zero-copy slicing mechanism. Using their ability to reference a block of
memory, it is possible to expose any data to the Python programmer quite
easily. The memory could be a large, constant array in a C extension, it could
be a raw block of memory for manipulation before passing to an operating
system library, or it could be used to pass around structured data in its
native, in-memory format.
.. c:type:: PyBufferObject
This subtype of :c:type:`PyObject` represents a buffer object.
.. c:var:: PyTypeObject PyBuffer_Type
.. index:: single: BufferType (in module types)
The instance of :c:type:`PyTypeObject` which represents the Python buffer type;
it is the same object as ``buffer`` and ``types.BufferType`` in the Python
layer. .
.. c:var:: int Py_END_OF_BUFFER
This constant may be passed as the *size* parameter to
:c:func:`PyBuffer_FromObject` or :c:func:`PyBuffer_FromReadWriteObject`. It
indicates that the new :c:type:`PyBufferObject` should refer to *base*
object from the specified *offset* to the end of its exported buffer.
Using this enables the caller to avoid querying the *base* object for its
length.
.. c:function:: int PyBuffer_Check(PyObject *p)
Return true if the argument has type :c:data:`PyBuffer_Type`.
.. c:function:: PyObject* PyBuffer_FromObject(PyObject *base, Py_ssize_t offset, Py_ssize_t size)
Return a new read-only buffer object. This raises :exc:`TypeError` if
*base* doesn't support the read-only buffer protocol or doesn't provide
exactly one buffer segment, or it raises :exc:`ValueError` if *offset* is
less than zero. The buffer will hold a reference to the *base* object, and
the buffer's contents will refer to the *base* object's buffer interface,
starting as position *offset* and extending for *size* bytes. If *size* is
:const:`Py_END_OF_BUFFER`, then the new buffer's contents extend to the
length of the *base* object's exported buffer data.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *offset* and *size*. This
might require changes in your code for properly supporting 64-bit
systems.
.. c:function:: PyObject* PyBuffer_FromReadWriteObject(PyObject *base, Py_ssize_t offset, Py_ssize_t size)
Return a new writable buffer object. Parameters and exceptions are similar
to those for :c:func:`PyBuffer_FromObject`. If the *base* object does not
export the writeable buffer protocol, then :exc:`TypeError` is raised.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *offset* and *size*. This
might require changes in your code for properly supporting 64-bit
systems.
.. c:function:: PyObject* PyBuffer_FromMemory(void *ptr, Py_ssize_t size)
Return a new read-only buffer object that reads from a specified location
in memory, with a specified size. The caller is responsible for ensuring
that the memory buffer, passed in as *ptr*, is not deallocated while the
returned buffer object exists. Raises :exc:`ValueError` if *size* is less
than zero. Note that :const:`Py_END_OF_BUFFER` may *not* be passed for the
*size* parameter; :exc:`ValueError` will be raised in that case.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyBuffer_FromReadWriteMemory(void *ptr, Py_ssize_t size)
Similar to :c:func:`PyBuffer_FromMemory`, but the returned buffer is
writable.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyBuffer_New(Py_ssize_t size)
Return a new writable buffer object that maintains its own memory buffer of
*size* bytes. :exc:`ValueError` is returned if *size* is not zero or
positive. Note that the memory buffer (as returned by
:c:func:`PyObject_AsWriteBuffer`) is not specifically aligned.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.

87
Doc/c-api/bytearray.rst Normal file
View File

@@ -0,0 +1,87 @@
.. highlightlang:: c
.. _bytearrayobjects:
Byte Array Objects
------------------
.. index:: object: bytearray
.. versionadded:: 2.6
.. c:type:: PyByteArrayObject
This subtype of :c:type:`PyObject` represents a Python bytearray object.
.. c:var:: PyTypeObject PyByteArray_Type
This instance of :c:type:`PyTypeObject` represents the Python bytearray type;
it is the same object as ``bytearray`` in the Python layer.
Type check macros
^^^^^^^^^^^^^^^^^
.. c:function:: int PyByteArray_Check(PyObject *o)
Return true if the object *o* is a bytearray object or an instance of a
subtype of the bytearray type.
.. c:function:: int PyByteArray_CheckExact(PyObject *o)
Return true if the object *o* is a bytearray object, but not an instance of a
subtype of the bytearray type.
Direct API functions
^^^^^^^^^^^^^^^^^^^^
.. c:function:: PyObject* PyByteArray_FromObject(PyObject *o)
Return a new bytearray object from any object, *o*, that implements the
buffer protocol.
.. XXX expand about the buffer protocol, at least somewhere
.. c:function:: PyObject* PyByteArray_FromStringAndSize(const char *string, Py_ssize_t len)
Create a new bytearray object from *string* and its length, *len*. On
failure, *NULL* is returned.
.. c:function:: PyObject* PyByteArray_Concat(PyObject *a, PyObject *b)
Concat bytearrays *a* and *b* and return a new bytearray with the result.
.. c:function:: Py_ssize_t PyByteArray_Size(PyObject *bytearray)
Return the size of *bytearray* after checking for a *NULL* pointer.
.. c:function:: char* PyByteArray_AsString(PyObject *bytearray)
Return the contents of *bytearray* as a char array after checking for a
*NULL* pointer.
.. c:function:: int PyByteArray_Resize(PyObject *bytearray, Py_ssize_t len)
Resize the internal buffer of *bytearray* to *len*.
Macros
^^^^^^
These macros trade safety for speed and they don't check pointers.
.. c:function:: char* PyByteArray_AS_STRING(PyObject *bytearray)
Macro version of :c:func:`PyByteArray_AsString`.
.. c:function:: Py_ssize_t PyByteArray_GET_SIZE(PyObject *bytearray)
Macro version of :c:func:`PyByteArray_Size`.

157
Doc/c-api/capsule.rst Normal file
View File

@@ -0,0 +1,157 @@
.. highlightlang:: c
.. _capsules:
Capsules
--------
.. index:: object: Capsule
Refer to :ref:`using-capsules` for more information on using these objects.
.. versionadded:: 2.7
.. c:type:: PyCapsule
This subtype of :c:type:`PyObject` represents an opaque value, useful for C
extension modules who need to pass an opaque value (as a :c:type:`void\*`
pointer) through Python code to other C code. It is often used to make a C
function pointer defined in one module available to other modules, so the
regular import mechanism can be used to access C APIs defined in dynamically
loaded modules.
.. c:type:: PyCapsule_Destructor
The type of a destructor callback for a capsule. Defined as::
typedef void (*PyCapsule_Destructor)(PyObject *);
See :c:func:`PyCapsule_New` for the semantics of PyCapsule_Destructor
callbacks.
.. c:function:: int PyCapsule_CheckExact(PyObject *p)
Return true if its argument is a :c:type:`PyCapsule`.
.. c:function:: PyObject* PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)
Create a :c:type:`PyCapsule` encapsulating the *pointer*. The *pointer*
argument may not be *NULL*.
On failure, set an exception and return *NULL*.
The *name* string may either be *NULL* or a pointer to a valid C string. If
non-*NULL*, this string must outlive the capsule. (Though it is permitted to
free it inside the *destructor*.)
If the *destructor* argument is not *NULL*, it will be called with the
capsule as its argument when it is destroyed.
If this capsule will be stored as an attribute of a module, the *name* should
be specified as ``modulename.attributename``. This will enable other modules
to import the capsule using :c:func:`PyCapsule_Import`.
.. c:function:: void* PyCapsule_GetPointer(PyObject *capsule, const char *name)
Retrieve the *pointer* stored in the capsule. On failure, set an exception
and return *NULL*.
The *name* parameter must compare exactly to the name stored in the capsule.
If the name stored in the capsule is *NULL*, the *name* passed in must also
be *NULL*. Python uses the C function :c:func:`strcmp` to compare capsule
names.
.. c:function:: PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)
Return the current destructor stored in the capsule. On failure, set an
exception and return *NULL*.
It is legal for a capsule to have a *NULL* destructor. This makes a *NULL*
return code somewhat ambiguous; use :c:func:`PyCapsule_IsValid` or
:c:func:`PyErr_Occurred` to disambiguate.
.. c:function:: void* PyCapsule_GetContext(PyObject *capsule)
Return the current context stored in the capsule. On failure, set an
exception and return *NULL*.
It is legal for a capsule to have a *NULL* context. This makes a *NULL*
return code somewhat ambiguous; use :c:func:`PyCapsule_IsValid` or
:c:func:`PyErr_Occurred` to disambiguate.
.. c:function:: const char* PyCapsule_GetName(PyObject *capsule)
Return the current name stored in the capsule. On failure, set an exception
and return *NULL*.
It is legal for a capsule to have a *NULL* name. This makes a *NULL* return
code somewhat ambiguous; use :c:func:`PyCapsule_IsValid` or
:c:func:`PyErr_Occurred` to disambiguate.
.. c:function:: void* PyCapsule_Import(const char *name, int no_block)
Import a pointer to a C object from a capsule attribute in a module. The
*name* parameter should specify the full name to the attribute, as in
``module.attribute``. The *name* stored in the capsule must match this
string exactly. If *no_block* is true, import the module without blocking
(using :c:func:`PyImport_ImportModuleNoBlock`). If *no_block* is false,
import the module conventionally (using :c:func:`PyImport_ImportModule`).
Return the capsule's internal *pointer* on success. On failure, set an
exception and return *NULL*.
.. c:function:: int PyCapsule_IsValid(PyObject *capsule, const char *name)
Determines whether or not *capsule* is a valid capsule. A valid capsule is
non-*NULL*, passes :c:func:`PyCapsule_CheckExact`, has a non-*NULL* pointer
stored in it, and its internal name matches the *name* parameter. (See
:c:func:`PyCapsule_GetPointer` for information on how capsule names are
compared.)
In other words, if :c:func:`PyCapsule_IsValid` returns a true value, calls to
any of the accessors (any function starting with :c:func:`PyCapsule_Get`) are
guaranteed to succeed.
Return a nonzero value if the object is valid and matches the name passed in.
Return ``0`` otherwise. This function will not fail.
.. c:function:: int PyCapsule_SetContext(PyObject *capsule, void *context)
Set the context pointer inside *capsule* to *context*.
Return ``0`` on success. Return nonzero and set an exception on failure.
.. c:function:: int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)
Set the destructor inside *capsule* to *destructor*.
Return ``0`` on success. Return nonzero and set an exception on failure.
.. c:function:: int PyCapsule_SetName(PyObject *capsule, const char *name)
Set the name inside *capsule* to *name*. If non-*NULL*, the name must
outlive the capsule. If the previous *name* stored in the capsule was not
*NULL*, no attempt is made to free it.
Return ``0`` on success. Return nonzero and set an exception on failure.
.. c:function:: int PyCapsule_SetPointer(PyObject *capsule, void *pointer)
Set the void pointer inside *capsule* to *pointer*. The pointer may not be
*NULL*.
Return ``0`` on success. Return nonzero and set an exception on failure.

62
Doc/c-api/cell.rst Normal file
View File

@@ -0,0 +1,62 @@
.. highlightlang:: c
.. _cell-objects:
Cell Objects
------------
"Cell" objects are used to implement variables referenced by multiple scopes.
For each such variable, a cell object is created to store the value; the local
variables of each stack frame that references the value contains a reference to
the cells from outer scopes which also use that variable. When the value is
accessed, the value contained in the cell is used instead of the cell object
itself. This de-referencing of the cell object requires support from the
generated byte-code; these are not automatically de-referenced when accessed.
Cell objects are not likely to be useful elsewhere.
.. c:type:: PyCellObject
The C structure used for cell objects.
.. c:var:: PyTypeObject PyCell_Type
The type object corresponding to cell objects.
.. c:function:: int PyCell_Check(ob)
Return true if *ob* is a cell object; *ob* must not be *NULL*.
.. c:function:: PyObject* PyCell_New(PyObject *ob)
Create and return a new cell object containing the value *ob*. The parameter may
be *NULL*.
.. c:function:: PyObject* PyCell_Get(PyObject *cell)
Return the contents of the cell *cell*.
.. c:function:: PyObject* PyCell_GET(PyObject *cell)
Return the contents of the cell *cell*, but without checking that *cell* is
non-*NULL* and a cell object.
.. c:function:: int PyCell_Set(PyObject *cell, PyObject *value)
Set the contents of the cell object *cell* to *value*. This releases the
reference to any current content of the cell. *value* may be *NULL*. *cell*
must be non-*NULL*; if it is not a cell object, ``-1`` will be returned. On
success, ``0`` will be returned.
.. c:function:: void PyCell_SET(PyObject *cell, PyObject *value)
Sets the value of the cell object *cell* to *value*. No reference counts are
adjusted, and no checks are made for safety; *cell* must be non-*NULL* and must
be a cell object.

65
Doc/c-api/class.rst Normal file
View File

@@ -0,0 +1,65 @@
.. highlightlang:: c
.. _classobjects:
Class and Instance Objects
--------------------------
.. index:: object: class
Note that the class objects described here represent old-style classes, which
will go away in Python 3. When creating new types for extension modules, you
will want to work with type objects (section :ref:`typeobjects`).
.. c:type:: PyClassObject
The C structure of the objects used to describe built-in classes.
.. c:var:: PyObject* PyClass_Type
.. index:: single: ClassType (in module types)
This is the type object for class objects; it is the same object as
``types.ClassType`` in the Python layer.
.. c:function:: int PyClass_Check(PyObject *o)
Return true if the object *o* is a class object, including instances of types
derived from the standard class object. Return false in all other cases.
.. c:function:: int PyClass_IsSubclass(PyObject *klass, PyObject *base)
Return true if *klass* is a subclass of *base*. Return false in all other cases.
.. index:: object: instance
There are very few functions specific to instance objects.
.. c:var:: PyTypeObject PyInstance_Type
Type object for class instances.
.. c:function:: int PyInstance_Check(PyObject *obj)
Return true if *obj* is an instance.
.. c:function:: PyObject* PyInstance_New(PyObject *class, PyObject *arg, PyObject *kw)
Create a new instance of a specific class. The parameters *arg* and *kw* are
used as the positional and keyword parameters to the object's constructor.
.. c:function:: PyObject* PyInstance_NewRaw(PyObject *class, PyObject *dict)
Create a new instance of a specific class without calling its constructor.
*class* is the class of new object. The *dict* parameter will be used as the
object's :attr:`~object.__dict__`; if *NULL*, a new dictionary will be created for the
instance.

59
Doc/c-api/cobject.rst Normal file
View File

@@ -0,0 +1,59 @@
.. highlightlang:: c
.. _cobjects:
CObjects
--------
.. index:: object: CObject
.. warning::
The CObject API is deprecated as of Python 2.7. Please switch to the new
:ref:`capsules` API.
.. c:type:: PyCObject
This subtype of :c:type:`PyObject` represents an opaque value, useful for C
extension modules who need to pass an opaque value (as a :c:type:`void\*`
pointer) through Python code to other C code. It is often used to make a C
function pointer defined in one module available to other modules, so the
regular import mechanism can be used to access C APIs defined in dynamically
loaded modules.
.. c:function:: int PyCObject_Check(PyObject *p)
Return true if its argument is a :c:type:`PyCObject`.
.. c:function:: PyObject* PyCObject_FromVoidPtr(void* cobj, void (*destr)(void *))
Create a :c:type:`PyCObject` from the ``void *`` *cobj*. The *destr* function
will be called when the object is reclaimed, unless it is *NULL*.
.. c:function:: PyObject* PyCObject_FromVoidPtrAndDesc(void* cobj, void* desc, void (*destr)(void *, void *))
Create a :c:type:`PyCObject` from the :c:type:`void \*` *cobj*. The *destr*
function will be called when the object is reclaimed. The *desc* argument can
be used to pass extra callback data for the destructor function.
.. c:function:: void* PyCObject_AsVoidPtr(PyObject* self)
Return the object :c:type:`void \*` that the :c:type:`PyCObject` *self* was
created with.
.. c:function:: void* PyCObject_GetDesc(PyObject* self)
Return the description :c:type:`void \*` that the :c:type:`PyCObject` *self* was
created with.
.. c:function:: int PyCObject_SetVoidPtr(PyObject* self, void* cobj)
Set the void pointer inside *self* to *cobj*. The :c:type:`PyCObject` must not
have an associated destructor. Return true on success, false on failure.

48
Doc/c-api/code.rst Normal file
View File

@@ -0,0 +1,48 @@
.. highlightlang:: c
.. _codeobjects:
.. index:: object; code, code object
Code Objects
------------
.. sectionauthor:: Jeffrey Yasskin <jyasskin@gmail.com>
Code objects are a low-level detail of the CPython implementation.
Each one represents a chunk of executable code that hasn't yet been
bound into a function.
.. c:type:: PyCodeObject
The C structure of the objects used to describe code objects. The
fields of this type are subject to change at any time.
.. c:var:: PyTypeObject PyCode_Type
This is an instance of :c:type:`PyTypeObject` representing the Python
:class:`code` type.
.. c:function:: int PyCode_Check(PyObject *co)
Return true if *co* is a :class:`code` object.
.. c:function:: int PyCode_GetNumFree(PyObject *co)
Return the number of free variables in *co*.
.. c:function:: PyCodeObject *PyCode_New(int argcount, int nlocals, int stacksize, int flags, PyObject *code, PyObject *consts, PyObject *names, PyObject *varnames, PyObject *freevars, PyObject *cellvars, PyObject *filename, PyObject *name, int firstlineno, PyObject *lnotab)
Return a new code object. If you need a dummy code object to
create a frame, use :c:func:`PyCode_NewEmpty` instead. Calling
:c:func:`PyCode_New` directly can bind you to a precise Python
version since the definition of the bytecode changes often.
.. c:function:: int PyCode_NewEmpty(const char *filename, const char *funcname, int firstlineno)
Return a new empty code object with the specified filename,
function name, and first line number. It is illegal to
:keyword:`exec` or :func:`eval` the resulting code object.

118
Doc/c-api/codec.rst Normal file
View File

@@ -0,0 +1,118 @@
.. _codec-registry:
Codec registry and support functions
====================================
.. c:function:: int PyCodec_Register(PyObject *search_function)
Register a new codec search function.
As side effect, this tries to load the :mod:`encodings` package, if not yet
done, to make sure that it is always first in the list of search functions.
.. c:function:: int PyCodec_KnownEncoding(const char *encoding)
Return ``1`` or ``0`` depending on whether there is a registered codec for
the given *encoding*.
.. c:function:: PyObject* PyCodec_Encode(PyObject *object, const char *encoding, const char *errors)
Generic codec based encoding API.
*object* is passed through the encoder function found for the given
*encoding* using the error handling method defined by *errors*. *errors* may
be *NULL* to use the default method defined for the codec. Raises a
:exc:`LookupError` if no encoder can be found.
.. c:function:: PyObject* PyCodec_Decode(PyObject *object, const char *encoding, const char *errors)
Generic codec based decoding API.
*object* is passed through the decoder function found for the given
*encoding* using the error handling method defined by *errors*. *errors* may
be *NULL* to use the default method defined for the codec. Raises a
:exc:`LookupError` if no encoder can be found.
Codec lookup API
----------------
In the following functions, the *encoding* string is looked up converted to all
lower-case characters, which makes encodings looked up through this mechanism
effectively case-insensitive. If no codec is found, a :exc:`KeyError` is set
and *NULL* returned.
.. c:function:: PyObject* PyCodec_Encoder(const char *encoding)
Get an encoder function for the given *encoding*.
.. c:function:: PyObject* PyCodec_Decoder(const char *encoding)
Get a decoder function for the given *encoding*.
.. c:function:: PyObject* PyCodec_IncrementalEncoder(const char *encoding, const char *errors)
Get an :class:`~codecs.IncrementalEncoder` object for the given *encoding*.
.. c:function:: PyObject* PyCodec_IncrementalDecoder(const char *encoding, const char *errors)
Get an :class:`~codecs.IncrementalDecoder` object for the given *encoding*.
.. c:function:: PyObject* PyCodec_StreamReader(const char *encoding, PyObject *stream, const char *errors)
Get a :class:`~codecs.StreamReader` factory function for the given *encoding*.
.. c:function:: PyObject* PyCodec_StreamWriter(const char *encoding, PyObject *stream, const char *errors)
Get a :class:`~codecs.StreamWriter` factory function for the given *encoding*.
Registry API for Unicode encoding error handlers
------------------------------------------------
.. c:function:: int PyCodec_RegisterError(const char *name, PyObject *error)
Register the error handling callback function *error* under the given *name*.
This callback function will be called by a codec when it encounters
unencodable characters/undecodable bytes and *name* is specified as the error
parameter in the call to the encode/decode function.
The callback gets a single argument, an instance of
:exc:`UnicodeEncodeError`, :exc:`UnicodeDecodeError` or
:exc:`UnicodeTranslateError` that holds information about the problematic
sequence of characters or bytes and their offset in the original string (see
:ref:`unicodeexceptions` for functions to extract this information). The
callback must either raise the given exception, or return a two-item tuple
containing the replacement for the problematic sequence, and an integer
giving the offset in the original string at which encoding/decoding should be
resumed.
Return ``0`` on success, ``-1`` on error.
.. c:function:: PyObject* PyCodec_LookupError(const char *name)
Lookup the error handling callback function registered under *name*. As a
special case *NULL* can be passed, in which case the error handling callback
for "strict" will be returned.
.. c:function:: PyObject* PyCodec_StrictErrors(PyObject *exc)
Raise *exc* as an exception.
.. c:function:: PyObject* PyCodec_IgnoreErrors(PyObject *exc)
Ignore the unicode error, skipping the faulty input.
.. c:function:: PyObject* PyCodec_ReplaceErrors(PyObject *exc)
Replace the unicode encode error with ``?`` or ``U+FFFD``.
.. c:function:: PyObject* PyCodec_XMLCharRefReplaceErrors(PyObject *exc)
Replace the unicode encode error with XML character references.
.. c:function:: PyObject* PyCodec_BackslashReplaceErrors(PyObject *exc)
Replace the unicode encode error with backslash escapes (``\x``, ``\u`` and
``\U``).

139
Doc/c-api/complex.rst Normal file
View File

@@ -0,0 +1,139 @@
.. highlightlang:: c
.. _complexobjects:
Complex Number Objects
----------------------
.. index:: object: complex number
Python's complex number objects are implemented as two distinct types when
viewed from the C API: one is the Python object exposed to Python programs, and
the other is a C structure which represents the actual complex number value.
The API provides functions for working with both.
Complex Numbers as C Structures
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Note that the functions which accept these structures as parameters and return
them as results do so *by value* rather than dereferencing them through
pointers. This is consistent throughout the API.
.. c:type:: Py_complex
The C structure which corresponds to the value portion of a Python complex
number object. Most of the functions for dealing with complex number objects
use structures of this type as input or output values, as appropriate. It is
defined as::
typedef struct {
double real;
double imag;
} Py_complex;
.. c:function:: Py_complex _Py_c_sum(Py_complex left, Py_complex right)
Return the sum of two complex numbers, using the C :c:type:`Py_complex`
representation.
.. c:function:: Py_complex _Py_c_diff(Py_complex left, Py_complex right)
Return the difference between two complex numbers, using the C
:c:type:`Py_complex` representation.
.. c:function:: Py_complex _Py_c_neg(Py_complex complex)
Return the negation of the complex number *complex*, using the C
:c:type:`Py_complex` representation.
.. c:function:: Py_complex _Py_c_prod(Py_complex left, Py_complex right)
Return the product of two complex numbers, using the C :c:type:`Py_complex`
representation.
.. c:function:: Py_complex _Py_c_quot(Py_complex dividend, Py_complex divisor)
Return the quotient of two complex numbers, using the C :c:type:`Py_complex`
representation.
If *divisor* is null, this method returns zero and sets
:c:data:`errno` to :c:data:`EDOM`.
.. c:function:: Py_complex _Py_c_pow(Py_complex num, Py_complex exp)
Return the exponentiation of *num* by *exp*, using the C :c:type:`Py_complex`
representation.
If *num* is null and *exp* is not a positive real number,
this method returns zero and sets :c:data:`errno` to :c:data:`EDOM`.
Complex Numbers as Python Objects
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. c:type:: PyComplexObject
This subtype of :c:type:`PyObject` represents a Python complex number object.
.. c:var:: PyTypeObject PyComplex_Type
This instance of :c:type:`PyTypeObject` represents the Python complex number
type. It is the same object as ``complex`` and ``types.ComplexType``.
.. c:function:: int PyComplex_Check(PyObject *p)
Return true if its argument is a :c:type:`PyComplexObject` or a subtype of
:c:type:`PyComplexObject`.
.. versionchanged:: 2.2
Allowed subtypes to be accepted.
.. c:function:: int PyComplex_CheckExact(PyObject *p)
Return true if its argument is a :c:type:`PyComplexObject`, but not a subtype of
:c:type:`PyComplexObject`.
.. versionadded:: 2.2
.. c:function:: PyObject* PyComplex_FromCComplex(Py_complex v)
Create a new Python complex number object from a C :c:type:`Py_complex` value.
.. c:function:: PyObject* PyComplex_FromDoubles(double real, double imag)
Return a new :c:type:`PyComplexObject` object from *real* and *imag*.
.. c:function:: double PyComplex_RealAsDouble(PyObject *op)
Return the real part of *op* as a C :c:type:`double`.
.. c:function:: double PyComplex_ImagAsDouble(PyObject *op)
Return the imaginary part of *op* as a C :c:type:`double`.
.. c:function:: Py_complex PyComplex_AsCComplex(PyObject *op)
Return the :c:type:`Py_complex` value of the complex number *op*.
Upon failure, this method returns ``-1.0`` as a real value.
.. versionchanged:: 2.6
If *op* is not a Python complex number object but has a :meth:`__complex__`
method, this method will first be called to convert *op* to a Python complex
number object.

109
Doc/c-api/concrete.rst Normal file
View File

@@ -0,0 +1,109 @@
.. highlightlang:: c
.. _concrete:
**********************
Concrete Objects Layer
**********************
The functions in this chapter are specific to certain Python object types.
Passing them an object of the wrong type is not a good idea; if you receive an
object from a Python program and you are not sure that it has the right type,
you must perform a type check first; for example, to check that an object is a
dictionary, use :c:func:`PyDict_Check`. The chapter is structured like the
"family tree" of Python object types.
.. warning::
While the functions described in this chapter carefully check the type of the
objects which are passed in, many of them do not check for *NULL* being passed
instead of a valid object. Allowing *NULL* to be passed in can cause memory
access violations and immediate termination of the interpreter.
.. _fundamental:
Fundamental Objects
===================
This section describes Python type objects and the singleton object ``None``.
.. toctree::
type.rst
none.rst
.. _numericobjects:
Numeric Objects
===============
.. index:: object: numeric
.. toctree::
int.rst
bool.rst
long.rst
float.rst
complex.rst
.. _sequenceobjects:
Sequence Objects
================
.. index:: object: sequence
Generic operations on sequence objects were discussed in the previous chapter;
this section deals with the specific kinds of sequence objects that are
intrinsic to the Python language.
.. toctree::
bytearray.rst
string.rst
unicode.rst
buffer.rst
tuple.rst
list.rst
.. _mapobjects:
Mapping Objects
===============
.. index:: object: mapping
.. toctree::
dict.rst
.. _otherobjects:
Other Objects
=============
.. toctree::
class.rst
function.rst
method.rst
file.rst
module.rst
iterator.rst
descriptor.rst
slice.rst
weakref.rst
capsule.rst
cobject.rst
cell.rst
gen.rst
datetime.rst
set.rst
code.rst

181
Doc/c-api/conversion.rst Normal file
View File

@@ -0,0 +1,181 @@
.. highlightlang:: c
.. _string-conversion:
String conversion and formatting
================================
Functions for number conversion and formatted string output.
.. c:function:: int PyOS_snprintf(char *str, size_t size, const char *format, ...)
Output not more than *size* bytes to *str* according to the format string
*format* and the extra arguments. See the Unix man page :manpage:`snprintf(2)`.
.. c:function:: int PyOS_vsnprintf(char *str, size_t size, const char *format, va_list va)
Output not more than *size* bytes to *str* according to the format string
*format* and the variable argument list *va*. Unix man page
:manpage:`vsnprintf(2)`.
:c:func:`PyOS_snprintf` and :c:func:`PyOS_vsnprintf` wrap the Standard C library
functions :c:func:`snprintf` and :c:func:`vsnprintf`. Their purpose is to
guarantee consistent behavior in corner cases, which the Standard C functions do
not.
The wrappers ensure that *str*[*size*-1] is always ``'\0'`` upon return. They
never write more than *size* bytes (including the trailing ``'\0'`` into str.
Both functions require that ``str != NULL``, ``size > 0`` and ``format !=
NULL``.
If the platform doesn't have :c:func:`vsnprintf` and the buffer size needed to
avoid truncation exceeds *size* by more than 512 bytes, Python aborts with a
*Py_FatalError*.
The return value (*rv*) for these functions should be interpreted as follows:
* When ``0 <= rv < size``, the output conversion was successful and *rv*
characters were written to *str* (excluding the trailing ``'\0'`` byte at
*str*[*rv*]).
* When ``rv >= size``, the output conversion was truncated and a buffer with
``rv + 1`` bytes would have been needed to succeed. *str*[*size*-1] is ``'\0'``
in this case.
* When ``rv < 0``, "something bad happened." *str*[*size*-1] is ``'\0'`` in
this case too, but the rest of *str* is undefined. The exact cause of the error
depends on the underlying platform.
The following functions provide locale-independent string to number conversions.
.. c:function:: double PyOS_string_to_double(const char *s, char **endptr, PyObject *overflow_exception)
Convert a string ``s`` to a :c:type:`double`, raising a Python
exception on failure. The set of accepted strings corresponds to
the set of strings accepted by Python's :func:`float` constructor,
except that ``s`` must not have leading or trailing whitespace.
The conversion is independent of the current locale.
If ``endptr`` is ``NULL``, convert the whole string. Raise
ValueError and return ``-1.0`` if the string is not a valid
representation of a floating-point number.
If endptr is not ``NULL``, convert as much of the string as
possible and set ``*endptr`` to point to the first unconverted
character. If no initial segment of the string is the valid
representation of a floating-point number, set ``*endptr`` to point
to the beginning of the string, raise ValueError, and return
``-1.0``.
If ``s`` represents a value that is too large to store in a float
(for example, ``"1e500"`` is such a string on many platforms) then
if ``overflow_exception`` is ``NULL`` return ``Py_HUGE_VAL`` (with
an appropriate sign) and don't set any exception. Otherwise,
``overflow_exception`` must point to a Python exception object;
raise that exception and return ``-1.0``. In both cases, set
``*endptr`` to point to the first character after the converted value.
If any other error occurs during the conversion (for example an
out-of-memory error), set the appropriate Python exception and
return ``-1.0``.
.. versionadded:: 2.7
.. c:function:: double PyOS_ascii_strtod(const char *nptr, char **endptr)
Convert a string to a :c:type:`double`. This function behaves like the Standard C
function :c:func:`strtod` does in the C locale. It does this without changing the
current locale, since that would not be thread-safe.
:c:func:`PyOS_ascii_strtod` should typically be used for reading configuration
files or other non-user input that should be locale independent.
See the Unix man page :manpage:`strtod(2)` for details.
.. versionadded:: 2.4
.. deprecated:: 2.7
Use :c:func:`PyOS_string_to_double` instead.
.. c:function:: char* PyOS_ascii_formatd(char *buffer, size_t buf_len, const char *format, double d)
Convert a :c:type:`double` to a string using the ``'.'`` as the decimal
separator. *format* is a :c:func:`printf`\ -style format string specifying the
number format. Allowed conversion characters are ``'e'``, ``'E'``, ``'f'``,
``'F'``, ``'g'`` and ``'G'``.
The return value is a pointer to *buffer* with the converted string or NULL if
the conversion failed.
.. versionadded:: 2.4
.. deprecated:: 2.7
This function is removed in Python 2.7 and 3.1. Use :func:`PyOS_double_to_string`
instead.
.. c:function:: char* PyOS_double_to_string(double val, char format_code, int precision, int flags, int *ptype)
Convert a :c:type:`double` *val* to a string using supplied
*format_code*, *precision*, and *flags*.
*format_code* must be one of ``'e'``, ``'E'``, ``'f'``, ``'F'``,
``'g'``, ``'G'`` or ``'r'``. For ``'r'``, the supplied *precision*
must be ``0`` and is ignored. The ``'r'`` format code specifies the
standard :func:`repr` format.
*flags* can be zero or more of the values *Py_DTSF_SIGN*,
*Py_DTSF_ADD_DOT_0*, or *Py_DTSF_ALT*, or-ed together:
* *Py_DTSF_SIGN* means to always precede the returned string with a sign
character, even if *val* is non-negative.
* *Py_DTSF_ADD_DOT_0* means to ensure that the returned string will not look
like an integer.
* *Py_DTSF_ALT* means to apply "alternate" formatting rules. See the
documentation for the :c:func:`PyOS_snprintf` ``'#'`` specifier for
details.
If *ptype* is non-NULL, then the value it points to will be set to one of
*Py_DTST_FINITE*, *Py_DTST_INFINITE*, or *Py_DTST_NAN*, signifying that
*val* is a finite number, an infinite number, or not a number, respectively.
The return value is a pointer to *buffer* with the converted string or
*NULL* if the conversion failed. The caller is responsible for freeing the
returned string by calling :c:func:`PyMem_Free`.
.. versionadded:: 2.7
.. c:function:: double PyOS_ascii_atof(const char *nptr)
Convert a string to a :c:type:`double` in a locale-independent way.
See the Unix man page :manpage:`atof(2)` for details.
.. versionadded:: 2.4
.. deprecated:: 3.1
Use :c:func:`PyOS_string_to_double` instead.
.. c:function:: char* PyOS_stricmp(char *s1, char *s2)
Case insensitive comparison of strings. The function works almost
identically to :c:func:`strcmp` except that it ignores the case.
.. versionadded:: 2.6
.. c:function:: char* PyOS_strnicmp(char *s1, char *s2, Py_ssize_t size)
Case insensitive comparison of strings. The function works almost
identically to :c:func:`strncmp` except that it ignores the case.
.. versionadded:: 2.6

239
Doc/c-api/datetime.rst Normal file
View File

@@ -0,0 +1,239 @@
.. highlightlang:: c
.. _datetimeobjects:
DateTime Objects
----------------
Various date and time objects are supplied by the :mod:`datetime` module.
Before using any of these functions, the header file :file:`datetime.h` must be
included in your source (note that this is not included by :file:`Python.h`),
and the macro :c:macro:`PyDateTime_IMPORT` must be invoked, usually as part of
the module initialisation function. The macro puts a pointer to a C structure
into a static variable, :c:data:`PyDateTimeAPI`, that is used by the following
macros.
Type-check macros:
.. c:function:: int PyDate_Check(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_DateType` or a subtype of
:c:data:`PyDateTime_DateType`. *ob* must not be *NULL*.
.. versionadded:: 2.4
.. c:function:: int PyDate_CheckExact(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_DateType`. *ob* must not be
*NULL*.
.. versionadded:: 2.4
.. c:function:: int PyDateTime_Check(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_DateTimeType` or a subtype of
:c:data:`PyDateTime_DateTimeType`. *ob* must not be *NULL*.
.. versionadded:: 2.4
.. c:function:: int PyDateTime_CheckExact(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_DateTimeType`. *ob* must not
be *NULL*.
.. versionadded:: 2.4
.. c:function:: int PyTime_Check(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_TimeType` or a subtype of
:c:data:`PyDateTime_TimeType`. *ob* must not be *NULL*.
.. versionadded:: 2.4
.. c:function:: int PyTime_CheckExact(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_TimeType`. *ob* must not be
*NULL*.
.. versionadded:: 2.4
.. c:function:: int PyDelta_Check(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_DeltaType` or a subtype of
:c:data:`PyDateTime_DeltaType`. *ob* must not be *NULL*.
.. versionadded:: 2.4
.. c:function:: int PyDelta_CheckExact(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_DeltaType`. *ob* must not be
*NULL*.
.. versionadded:: 2.4
.. c:function:: int PyTZInfo_Check(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_TZInfoType` or a subtype of
:c:data:`PyDateTime_TZInfoType`. *ob* must not be *NULL*.
.. versionadded:: 2.4
.. c:function:: int PyTZInfo_CheckExact(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_TZInfoType`. *ob* must not be
*NULL*.
.. versionadded:: 2.4
Macros to create objects:
.. c:function:: PyObject* PyDate_FromDate(int year, int month, int day)
Return a ``datetime.date`` object with the specified year, month and day.
.. versionadded:: 2.4
.. c:function:: PyObject* PyDateTime_FromDateAndTime(int year, int month, int day, int hour, int minute, int second, int usecond)
Return a ``datetime.datetime`` object with the specified year, month, day, hour,
minute, second and microsecond.
.. versionadded:: 2.4
.. c:function:: PyObject* PyTime_FromTime(int hour, int minute, int second, int usecond)
Return a ``datetime.time`` object with the specified hour, minute, second and
microsecond.
.. versionadded:: 2.4
.. c:function:: PyObject* PyDelta_FromDSU(int days, int seconds, int useconds)
Return a ``datetime.timedelta`` object representing the given number of days,
seconds and microseconds. Normalization is performed so that the resulting
number of microseconds and seconds lie in the ranges documented for
``datetime.timedelta`` objects.
.. versionadded:: 2.4
Macros to extract fields from date objects. The argument must be an instance of
:c:data:`PyDateTime_Date`, including subclasses (such as
:c:data:`PyDateTime_DateTime`). The argument must not be *NULL*, and the type is
not checked:
.. c:function:: int PyDateTime_GET_YEAR(PyDateTime_Date *o)
Return the year, as a positive int.
.. versionadded:: 2.4
.. c:function:: int PyDateTime_GET_MONTH(PyDateTime_Date *o)
Return the month, as an int from 1 through 12.
.. versionadded:: 2.4
.. c:function:: int PyDateTime_GET_DAY(PyDateTime_Date *o)
Return the day, as an int from 1 through 31.
.. versionadded:: 2.4
Macros to extract fields from datetime objects. The argument must be an
instance of :c:data:`PyDateTime_DateTime`, including subclasses. The argument
must not be *NULL*, and the type is not checked:
.. c:function:: int PyDateTime_DATE_GET_HOUR(PyDateTime_DateTime *o)
Return the hour, as an int from 0 through 23.
.. versionadded:: 2.4
.. c:function:: int PyDateTime_DATE_GET_MINUTE(PyDateTime_DateTime *o)
Return the minute, as an int from 0 through 59.
.. versionadded:: 2.4
.. c:function:: int PyDateTime_DATE_GET_SECOND(PyDateTime_DateTime *o)
Return the second, as an int from 0 through 59.
.. versionadded:: 2.4
.. c:function:: int PyDateTime_DATE_GET_MICROSECOND(PyDateTime_DateTime *o)
Return the microsecond, as an int from 0 through 999999.
.. versionadded:: 2.4
Macros to extract fields from time objects. The argument must be an instance of
:c:data:`PyDateTime_Time`, including subclasses. The argument must not be *NULL*,
and the type is not checked:
.. c:function:: int PyDateTime_TIME_GET_HOUR(PyDateTime_Time *o)
Return the hour, as an int from 0 through 23.
.. versionadded:: 2.4
.. c:function:: int PyDateTime_TIME_GET_MINUTE(PyDateTime_Time *o)
Return the minute, as an int from 0 through 59.
.. versionadded:: 2.4
.. c:function:: int PyDateTime_TIME_GET_SECOND(PyDateTime_Time *o)
Return the second, as an int from 0 through 59.
.. versionadded:: 2.4
.. c:function:: int PyDateTime_TIME_GET_MICROSECOND(PyDateTime_Time *o)
Return the microsecond, as an int from 0 through 999999.
.. versionadded:: 2.4
Macros for the convenience of modules implementing the DB API:
.. c:function:: PyObject* PyDateTime_FromTimestamp(PyObject *args)
Create and return a new ``datetime.datetime`` object given an argument tuple
suitable for passing to ``datetime.datetime.fromtimestamp()``.
.. versionadded:: 2.4
.. c:function:: PyObject* PyDate_FromTimestamp(PyObject *args)
Create and return a new ``datetime.date`` object given an argument tuple
suitable for passing to ``datetime.date.fromtimestamp()``.
.. versionadded:: 2.4

55
Doc/c-api/descriptor.rst Normal file
View File

@@ -0,0 +1,55 @@
.. highlightlang:: c
.. _descriptor-objects:
Descriptor Objects
------------------
"Descriptors" are objects that describe some attribute of an object. They are
found in the dictionary of type objects.
.. c:var:: PyTypeObject PyProperty_Type
The type object for the built-in descriptor types.
.. versionadded:: 2.2
.. c:function:: PyObject* PyDescr_NewGetSet(PyTypeObject *type, struct PyGetSetDef *getset)
.. versionadded:: 2.2
.. c:function:: PyObject* PyDescr_NewMember(PyTypeObject *type, struct PyMemberDef *meth)
.. versionadded:: 2.2
.. c:function:: PyObject* PyDescr_NewMethod(PyTypeObject *type, struct PyMethodDef *meth)
.. versionadded:: 2.2
.. c:function:: PyObject* PyDescr_NewWrapper(PyTypeObject *type, struct wrapperbase *wrapper, void *wrapped)
.. versionadded:: 2.2
.. c:function:: PyObject* PyDescr_NewClassMethod(PyTypeObject *type, PyMethodDef *method)
.. versionadded:: 2.3
.. c:function:: int PyDescr_IsData(PyObject *descr)
Return true if the descriptor objects *descr* describes a data attribute, or
false if it describes a method. *descr* must be a descriptor object; there is
no error checking.
.. versionadded:: 2.2
.. c:function:: PyObject* PyWrapper_New(PyObject *, PyObject *)
.. versionadded:: 2.2

236
Doc/c-api/dict.rst Normal file
View File

@@ -0,0 +1,236 @@
.. highlightlang:: c
.. _dictobjects:
Dictionary Objects
------------------
.. index:: object: dictionary
.. c:type:: PyDictObject
This subtype of :c:type:`PyObject` represents a Python dictionary object.
.. c:var:: PyTypeObject PyDict_Type
.. index::
single: DictType (in module types)
single: DictionaryType (in module types)
This instance of :c:type:`PyTypeObject` represents the Python dictionary
type. This is exposed to Python programs as ``dict`` and
``types.DictType``.
.. c:function:: int PyDict_Check(PyObject *p)
Return true if *p* is a dict object or an instance of a subtype of the dict
type.
.. versionchanged:: 2.2
Allowed subtypes to be accepted.
.. c:function:: int PyDict_CheckExact(PyObject *p)
Return true if *p* is a dict object, but not an instance of a subtype of
the dict type.
.. versionadded:: 2.4
.. c:function:: PyObject* PyDict_New()
Return a new empty dictionary, or *NULL* on failure.
.. c:function:: PyObject* PyDictProxy_New(PyObject *dict)
Return a proxy object for a mapping which enforces read-only behavior.
This is normally used to create a proxy to prevent modification of the
dictionary for non-dynamic class types.
.. versionadded:: 2.2
.. c:function:: void PyDict_Clear(PyObject *p)
Empty an existing dictionary of all key-value pairs.
.. c:function:: int PyDict_Contains(PyObject *p, PyObject *key)
Determine if dictionary *p* contains *key*. If an item in *p* is matches
*key*, return ``1``, otherwise return ``0``. On error, return ``-1``.
This is equivalent to the Python expression ``key in p``.
.. versionadded:: 2.4
.. c:function:: PyObject* PyDict_Copy(PyObject *p)
Return a new dictionary that contains the same key-value pairs as *p*.
.. versionadded:: 1.6
.. c:function:: int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)
Insert *value* into the dictionary *p* with a key of *key*. *key* must be
:term:`hashable`; if it isn't, :exc:`TypeError` will be raised. Return
``0`` on success or ``-1`` on failure.
.. c:function:: int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)
.. index:: single: PyString_FromString()
Insert *value* into the dictionary *p* using *key* as a key. *key* should
be a :c:type:`char\*`. The key object is created using
``PyString_FromString(key)``. Return ``0`` on success or ``-1`` on
failure.
.. c:function:: int PyDict_DelItem(PyObject *p, PyObject *key)
Remove the entry in dictionary *p* with key *key*. *key* must be hashable;
if it isn't, :exc:`TypeError` is raised. Return ``0`` on success or ``-1``
on failure.
.. c:function:: int PyDict_DelItemString(PyObject *p, char *key)
Remove the entry in dictionary *p* which has a key specified by the string
*key*. Return ``0`` on success or ``-1`` on failure.
.. c:function:: PyObject* PyDict_GetItem(PyObject *p, PyObject *key)
Return the object from dictionary *p* which has a key *key*. Return *NULL*
if the key *key* is not present, but *without* setting an exception.
.. c:function:: PyObject* PyDict_GetItemString(PyObject *p, const char *key)
This is the same as :c:func:`PyDict_GetItem`, but *key* is specified as a
:c:type:`char\*`, rather than a :c:type:`PyObject\*`.
.. c:function:: PyObject* PyDict_Items(PyObject *p)
Return a :c:type:`PyListObject` containing all the items from the
dictionary, as in the dictionary method :meth:`dict.items`.
.. c:function:: PyObject* PyDict_Keys(PyObject *p)
Return a :c:type:`PyListObject` containing all the keys from the dictionary,
as in the dictionary method :meth:`dict.keys`.
.. c:function:: PyObject* PyDict_Values(PyObject *p)
Return a :c:type:`PyListObject` containing all the values from the
dictionary *p*, as in the dictionary method :meth:`dict.values`.
.. c:function:: Py_ssize_t PyDict_Size(PyObject *p)
.. index:: builtin: len
Return the number of items in the dictionary. This is equivalent to
``len(p)`` on a dictionary.
.. versionchanged:: 2.5
This function returned an :c:type:`int` type. This might require changes
in your code for properly supporting 64-bit systems.
.. c:function:: int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)
Iterate over all key-value pairs in the dictionary *p*. The
:c:type:`Py_ssize_t` referred to by *ppos* must be initialized to ``0``
prior to the first call to this function to start the iteration; the
function returns true for each pair in the dictionary, and false once all
pairs have been reported. The parameters *pkey* and *pvalue* should either
point to :c:type:`PyObject\*` variables that will be filled in with each key
and value, respectively, or may be *NULL*. Any references returned through
them are borrowed. *ppos* should not be altered during iteration. Its
value represents offsets within the internal dictionary structure, and
since the structure is sparse, the offsets are not consecutive.
For example::
PyObject *key, *value;
Py_ssize_t pos = 0;
while (PyDict_Next(self->dict, &pos, &key, &value)) {
/* do something interesting with the values... */
...
}
The dictionary *p* should not be mutated during iteration. It is safe
(since Python 2.1) to modify the values of the keys as you iterate over the
dictionary, but only so long as the set of keys does not change. For
example::
PyObject *key, *value;
Py_ssize_t pos = 0;
while (PyDict_Next(self->dict, &pos, &key, &value)) {
int i = PyInt_AS_LONG(value) + 1;
PyObject *o = PyInt_FromLong(i);
if (o == NULL)
return -1;
if (PyDict_SetItem(self->dict, key, o) < 0) {
Py_DECREF(o);
return -1;
}
Py_DECREF(o);
}
.. versionchanged:: 2.5
This function used an :c:type:`int *` type for *ppos*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: int PyDict_Merge(PyObject *a, PyObject *b, int override)
Iterate over mapping object *b* adding key-value pairs to dictionary *a*.
*b* may be a dictionary, or any object supporting :c:func:`PyMapping_Keys`
and :c:func:`PyObject_GetItem`. If *override* is true, existing pairs in *a*
will be replaced if a matching key is found in *b*, otherwise pairs will
only be added if there is not a matching key in *a*. Return ``0`` on
success or ``-1`` if an exception was raised.
.. versionadded:: 2.2
.. c:function:: int PyDict_Update(PyObject *a, PyObject *b)
This is the same as ``PyDict_Merge(a, b, 1)`` in C, and is similar to
``a.update(b)`` in Python except that :c:func:`PyDict_Update` doesn't fall
back to the iterating over a sequence of key value pairs if the second
argument has no "keys" attribute. Return ``0`` on success or ``-1`` if an
exception was raised.
.. versionadded:: 2.2
.. c:function:: int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override)
Update or merge into dictionary *a*, from the key-value pairs in *seq2*.
*seq2* must be an iterable object producing iterable objects of length 2,
viewed as key-value pairs. In case of duplicate keys, the last wins if
*override* is true, else the first wins. Return ``0`` on success or ``-1``
if an exception was raised. Equivalent Python (except for the return
value)::
def PyDict_MergeFromSeq2(a, seq2, override):
for key, value in seq2:
if override or key not in a:
a[key] = value
.. versionadded:: 2.2

728
Doc/c-api/exceptions.rst Normal file
View File

@@ -0,0 +1,728 @@
.. highlightlang:: c
.. _exceptionhandling:
******************
Exception Handling
******************
The functions described in this chapter will let you handle and raise Python
exceptions. It is important to understand some of the basics of Python
exception handling. It works somewhat like the Unix :c:data:`errno` variable:
there is a global indicator (per thread) of the last error that occurred. Most
functions don't clear this on success, but will set it to indicate the cause of
the error on failure. Most functions also return an error indicator, usually
*NULL* if they are supposed to return a pointer, or ``-1`` if they return an
integer (exception: the :c:func:`PyArg_\*` functions return ``1`` for success and
``0`` for failure).
When a function must fail because some function it called failed, it generally
doesn't set the error indicator; the function it called already set it. It is
responsible for either handling the error and clearing the exception or
returning after cleaning up any resources it holds (such as object references or
memory allocations); it should *not* continue normally if it is not prepared to
handle the error. If returning due to an error, it is important to indicate to
the caller that an error has been set. If the error is not handled or carefully
propagated, additional calls into the Python/C API may not behave as intended
and may fail in mysterious ways.
.. index::
single: exc_type (in module sys)
single: exc_value (in module sys)
single: exc_traceback (in module sys)
The error indicator consists of three Python objects corresponding to the
Python variables ``sys.exc_type``, ``sys.exc_value`` and ``sys.exc_traceback``.
API functions exist to interact with the error indicator in various ways. There
is a separate error indicator for each thread.
.. XXX Order of these should be more thoughtful.
Either alphabetical or some kind of structure.
.. c:function:: void PyErr_PrintEx(int set_sys_last_vars)
Print a standard traceback to ``sys.stderr`` and clear the error indicator.
**Unless** the error is a ``SystemExit``. In that case the no traceback
is printed and Python process will exit with the error code specified by
the ``SystemExit`` instance.
Call this function **only** when the error indicator is set. Otherwise it
will cause a fatal error!
If *set_sys_last_vars* is nonzero, the variables :data:`sys.last_type`,
:data:`sys.last_value` and :data:`sys.last_traceback` will be set to the
type, value and traceback of the printed exception, respectively.
.. c:function:: void PyErr_Print()
Alias for ``PyErr_PrintEx(1)``.
.. c:function:: PyObject* PyErr_Occurred()
Test whether the error indicator is set. If set, return the exception *type*
(the first argument to the last call to one of the :c:func:`PyErr_Set\*`
functions or to :c:func:`PyErr_Restore`). If not set, return *NULL*. You do not
own a reference to the return value, so you do not need to :c:func:`Py_DECREF`
it.
.. note::
Do not compare the return value to a specific exception; use
:c:func:`PyErr_ExceptionMatches` instead, shown below. (The comparison could
easily fail since the exception may be an instance instead of a class, in the
case of a class exception, or it may be a subclass of the expected exception.)
.. c:function:: int PyErr_ExceptionMatches(PyObject *exc)
Equivalent to ``PyErr_GivenExceptionMatches(PyErr_Occurred(), exc)``. This
should only be called when an exception is actually set; a memory access
violation will occur if no exception has been raised.
.. c:function:: int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc)
Return true if the *given* exception matches the exception in *exc*. If
*exc* is a class object, this also returns true when *given* is an instance
of a subclass. If *exc* is a tuple, all exceptions in the tuple (and
recursively in subtuples) are searched for a match.
.. c:function:: void PyErr_NormalizeException(PyObject**exc, PyObject**val, PyObject**tb)
Under certain circumstances, the values returned by :c:func:`PyErr_Fetch` below
can be "unnormalized", meaning that ``*exc`` is a class object but ``*val`` is
not an instance of the same class. This function can be used to instantiate
the class in that case. If the values are already normalized, nothing happens.
The delayed normalization is implemented to improve performance.
.. c:function:: void PyErr_Clear()
Clear the error indicator. If the error indicator is not set, there is no
effect.
.. c:function:: void PyErr_Fetch(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)
Retrieve the error indicator into three variables whose addresses are passed.
If the error indicator is not set, set all three variables to *NULL*. If it is
set, it will be cleared and you own a reference to each object retrieved. The
value and traceback object may be *NULL* even when the type object is not.
.. note::
This function is normally only used by code that needs to handle exceptions or
by code that needs to save and restore the error indicator temporarily.
.. c:function:: void PyErr_Restore(PyObject *type, PyObject *value, PyObject *traceback)
Set the error indicator from the three objects. If the error indicator is
already set, it is cleared first. If the objects are *NULL*, the error
indicator is cleared. Do not pass a *NULL* type and non-*NULL* value or
traceback. The exception type should be a class. Do not pass an invalid
exception type or value. (Violating these rules will cause subtle problems
later.) This call takes away a reference to each object: you must own a
reference to each object before the call and after the call you no longer own
these references. (If you don't understand this, don't use this function. I
warned you.)
.. note::
This function is normally only used by code that needs to save and restore the
error indicator temporarily; use :c:func:`PyErr_Fetch` to save the current
exception state.
.. c:function:: void PyErr_SetString(PyObject *type, const char *message)
This is the most common way to set the error indicator. The first argument
specifies the exception type; it is normally one of the standard exceptions,
e.g. :c:data:`PyExc_RuntimeError`. You need not increment its reference count.
The second argument is an error message; it is converted to a string object.
.. c:function:: void PyErr_SetObject(PyObject *type, PyObject *value)
This function is similar to :c:func:`PyErr_SetString` but lets you specify an
arbitrary Python object for the "value" of the exception.
.. c:function:: PyObject* PyErr_Format(PyObject *exception, const char *format, ...)
This function sets the error indicator and returns *NULL*. *exception*
should be a Python exception class. The *format* and subsequent
parameters help format the error message; they have the same meaning and
values as in :c:func:`PyString_FromFormat`.
.. c:function:: void PyErr_SetNone(PyObject *type)
This is a shorthand for ``PyErr_SetObject(type, Py_None)``.
.. c:function:: int PyErr_BadArgument()
This is a shorthand for ``PyErr_SetString(PyExc_TypeError, message)``, where
*message* indicates that a built-in operation was invoked with an illegal
argument. It is mostly for internal use.
.. c:function:: PyObject* PyErr_NoMemory()
This is a shorthand for ``PyErr_SetNone(PyExc_MemoryError)``; it returns *NULL*
so an object allocation function can write ``return PyErr_NoMemory();`` when it
runs out of memory.
.. c:function:: PyObject* PyErr_SetFromErrno(PyObject *type)
.. index:: single: strerror()
This is a convenience function to raise an exception when a C library function
has returned an error and set the C variable :c:data:`errno`. It constructs a
tuple object whose first item is the integer :c:data:`errno` value and whose
second item is the corresponding error message (gotten from :c:func:`strerror`),
and then calls ``PyErr_SetObject(type, object)``. On Unix, when the
:c:data:`errno` value is :const:`EINTR`, indicating an interrupted system call,
this calls :c:func:`PyErr_CheckSignals`, and if that set the error indicator,
leaves it set to that. The function always returns *NULL*, so a wrapper
function around a system call can write ``return PyErr_SetFromErrno(type);``
when the system call returns an error.
.. c:function:: PyObject* PyErr_SetFromErrnoWithFilenameObject(PyObject *type, PyObject *filenameObject)
Similar to :c:func:`PyErr_SetFromErrno`, with the additional behavior that if
*filenameObject* is not *NULL*, it is passed to the constructor of *type* as
a third parameter. In the case of exceptions such as :exc:`IOError` and
:exc:`OSError`, this is used to define the :attr:`filename` attribute of the
exception instance.
.. c:function:: PyObject* PyErr_SetFromErrnoWithFilename(PyObject *type, const char *filename)
Similar to :c:func:`PyErr_SetFromErrnoWithFilenameObject`, but the filename
is given as a C string.
.. c:function:: PyObject* PyErr_SetFromWindowsErr(int ierr)
This is a convenience function to raise :exc:`WindowsError`. If called with
*ierr* of :c:data:`0`, the error code returned by a call to :c:func:`GetLastError`
is used instead. It calls the Win32 function :c:func:`FormatMessage` to retrieve
the Windows description of error code given by *ierr* or :c:func:`GetLastError`,
then it constructs a tuple object whose first item is the *ierr* value and whose
second item is the corresponding error message (gotten from
:c:func:`FormatMessage`), and then calls ``PyErr_SetObject(PyExc_WindowsError,
object)``. This function always returns *NULL*. Availability: Windows.
.. c:function:: PyObject* PyErr_SetExcFromWindowsErr(PyObject *type, int ierr)
Similar to :c:func:`PyErr_SetFromWindowsErr`, with an additional parameter
specifying the exception type to be raised. Availability: Windows.
.. versionadded:: 2.3
.. c:function:: PyObject* PyErr_SetFromWindowsErrWithFilenameObject(int ierr, PyObject *filenameObject)
Similar to :c:func:`PyErr_SetFromWindowsErr`, with the additional behavior that
if *filenameObject* is not *NULL*, it is passed to the constructor of
:exc:`WindowsError` as a third parameter. Availability: Windows.
.. c:function:: PyObject* PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)
Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, but the
filename is given as a C string. Availability: Windows.
.. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilenameObject(PyObject *type, int ierr, PyObject *filename)
Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, with an
additional parameter specifying the exception type to be raised.
Availability: Windows.
.. versionadded:: 2.3
.. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, const char *filename)
Similar to :c:func:`PyErr_SetFromWindowsErrWithFilename`, with an additional
parameter specifying the exception type to be raised. Availability: Windows.
.. versionadded:: 2.3
.. c:function:: void PyErr_BadInternalCall()
This is a shorthand for ``PyErr_SetString(PyExc_SystemError, message)``,
where *message* indicates that an internal operation (e.g. a Python/C API
function) was invoked with an illegal argument. It is mostly for internal
use.
.. c:function:: int PyErr_WarnEx(PyObject *category, char *message, int stacklevel)
Issue a warning message. The *category* argument is a warning category (see
below) or *NULL*; the *message* argument is a message string. *stacklevel* is a
positive number giving a number of stack frames; the warning will be issued from
the currently executing line of code in that stack frame. A *stacklevel* of 1
is the function calling :c:func:`PyErr_WarnEx`, 2 is the function above that,
and so forth.
This function normally prints a warning message to *sys.stderr*; however, it is
also possible that the user has specified that warnings are to be turned into
errors, and in that case this will raise an exception. It is also possible that
the function raises an exception because of a problem with the warning machinery
(the implementation imports the :mod:`warnings` module to do the heavy lifting).
The return value is ``0`` if no exception is raised, or ``-1`` if an exception
is raised. (It is not possible to determine whether a warning message is
actually printed, nor what the reason is for the exception; this is
intentional.) If an exception is raised, the caller should do its normal
exception handling (for example, :c:func:`Py_DECREF` owned references and return
an error value).
Warning categories must be subclasses of :c:data:`PyExc_Warning`;
:c:data:`PyExc_Warning` is a subclass of :c:data:`PyExc_Exception`;
the default warning category is :c:data:`PyExc_RuntimeWarning`. The standard
Python warning categories are available as global variables whose names are
enumerated at :ref:`standardwarningcategories`.
For information about warning control, see the documentation for the
:mod:`warnings` module and the :option:`-W` option in the command line
documentation. There is no C API for warning control.
.. c:function:: int PyErr_Warn(PyObject *category, char *message)
Issue a warning message. The *category* argument is a warning category (see
below) or *NULL*; the *message* argument is a message string. The warning will
appear to be issued from the function calling :c:func:`PyErr_Warn`, equivalent to
calling :c:func:`PyErr_WarnEx` with a *stacklevel* of 1.
Deprecated; use :c:func:`PyErr_WarnEx` instead.
.. c:function:: int PyErr_WarnExplicit(PyObject *category, const char *message, const char *filename, int lineno, const char *module, PyObject *registry)
Issue a warning message with explicit control over all warning attributes. This
is a straightforward wrapper around the Python function
:func:`warnings.warn_explicit`, see there for more information. The *module*
and *registry* arguments may be set to *NULL* to get the default effect
described there.
.. c:function:: int PyErr_WarnPy3k(char *message, int stacklevel)
Issue a :exc:`DeprecationWarning` with the given *message* and *stacklevel*
if the :c:data:`Py_Py3kWarningFlag` flag is enabled.
.. versionadded:: 2.6
.. c:function:: int PyErr_CheckSignals()
.. index::
module: signal
single: SIGINT
single: KeyboardInterrupt (built-in exception)
This function interacts with Python's signal handling. It checks whether a
signal has been sent to the processes and if so, invokes the corresponding
signal handler. If the :mod:`signal` module is supported, this can invoke a
signal handler written in Python. In all cases, the default effect for
:const:`SIGINT` is to raise the :exc:`KeyboardInterrupt` exception. If an
exception is raised the error indicator is set and the function returns ``-1``;
otherwise the function returns ``0``. The error indicator may or may not be
cleared if it was previously set.
.. c:function:: void PyErr_SetInterrupt()
.. index::
single: SIGINT
single: KeyboardInterrupt (built-in exception)
This function simulates the effect of a :const:`SIGINT` signal arriving --- the
next time :c:func:`PyErr_CheckSignals` is called, :exc:`KeyboardInterrupt` will
be raised. It may be called without holding the interpreter lock.
.. % XXX This was described as obsolete, but is used in
.. % thread.interrupt_main() (used from IDLE), so it's still needed.
.. c:function:: int PySignal_SetWakeupFd(int fd)
This utility function specifies a file descriptor to which a ``'\0'`` byte will
be written whenever a signal is received. It returns the previous such file
descriptor. The value ``-1`` disables the feature; this is the initial state.
This is equivalent to :func:`signal.set_wakeup_fd` in Python, but without any
error checking. *fd* should be a valid file descriptor. The function should
only be called from the main thread.
.. versionadded:: 2.6
.. c:function:: PyObject* PyErr_NewException(char *name, PyObject *base, PyObject *dict)
This utility function creates and returns a new exception class. The *name*
argument must be the name of the new exception, a C string of the form
``module.classname``. The *base* and *dict* arguments are normally *NULL*.
This creates a class object derived from :exc:`Exception` (accessible in C as
:c:data:`PyExc_Exception`).
The :attr:`__module__` attribute of the new class is set to the first part (up
to the last dot) of the *name* argument, and the class name is set to the last
part (after the last dot). The *base* argument can be used to specify alternate
base classes; it can either be only one class or a tuple of classes. The *dict*
argument can be used to specify a dictionary of class variables and methods.
.. c:function:: PyObject* PyErr_NewExceptionWithDoc(char *name, char *doc, PyObject *base, PyObject *dict)
Same as :c:func:`PyErr_NewException`, except that the new exception class can
easily be given a docstring: If *doc* is non-*NULL*, it will be used as the
docstring for the exception class.
.. versionadded:: 2.7
.. c:function:: void PyErr_WriteUnraisable(PyObject *obj)
This utility function prints a warning message to ``sys.stderr`` when an
exception has been set but it is impossible for the interpreter to actually
raise the exception. It is used, for example, when an exception occurs in an
:meth:`__del__` method.
The function is called with a single argument *obj* that identifies the context
in which the unraisable exception occurred. If possible,
the repr of *obj* will be printed in the warning message.
.. _unicodeexceptions:
Unicode Exception Objects
=========================
The following functions are used to create and modify Unicode exceptions from C.
.. c:function:: PyObject* PyUnicodeDecodeError_Create(const char *encoding, const char *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
Create a :class:`UnicodeDecodeError` object with the attributes *encoding*,
*object*, *length*, *start*, *end* and *reason*.
.. c:function:: PyObject* PyUnicodeEncodeError_Create(const char *encoding, const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
Create a :class:`UnicodeEncodeError` object with the attributes *encoding*,
*object*, *length*, *start*, *end* and *reason*.
.. c:function:: PyObject* PyUnicodeTranslateError_Create(const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
Create a :class:`UnicodeTranslateError` object with the attributes *object*,
*length*, *start*, *end* and *reason*.
.. c:function:: PyObject* PyUnicodeDecodeError_GetEncoding(PyObject *exc)
PyObject* PyUnicodeEncodeError_GetEncoding(PyObject *exc)
Return the *encoding* attribute of the given exception object.
.. c:function:: PyObject* PyUnicodeDecodeError_GetObject(PyObject *exc)
PyObject* PyUnicodeEncodeError_GetObject(PyObject *exc)
PyObject* PyUnicodeTranslateError_GetObject(PyObject *exc)
Return the *object* attribute of the given exception object.
.. c:function:: int PyUnicodeDecodeError_GetStart(PyObject *exc, Py_ssize_t *start)
int PyUnicodeEncodeError_GetStart(PyObject *exc, Py_ssize_t *start)
int PyUnicodeTranslateError_GetStart(PyObject *exc, Py_ssize_t *start)
Get the *start* attribute of the given exception object and place it into
*\*start*. *start* must not be *NULL*. Return ``0`` on success, ``-1`` on
failure.
.. c:function:: int PyUnicodeDecodeError_SetStart(PyObject *exc, Py_ssize_t start)
int PyUnicodeEncodeError_SetStart(PyObject *exc, Py_ssize_t start)
int PyUnicodeTranslateError_SetStart(PyObject *exc, Py_ssize_t start)
Set the *start* attribute of the given exception object to *start*. Return
``0`` on success, ``-1`` on failure.
.. c:function:: int PyUnicodeDecodeError_GetEnd(PyObject *exc, Py_ssize_t *end)
int PyUnicodeEncodeError_GetEnd(PyObject *exc, Py_ssize_t *end)
int PyUnicodeTranslateError_GetEnd(PyObject *exc, Py_ssize_t *end)
Get the *end* attribute of the given exception object and place it into
*\*end*. *end* must not be *NULL*. Return ``0`` on success, ``-1`` on
failure.
.. c:function:: int PyUnicodeDecodeError_SetEnd(PyObject *exc, Py_ssize_t end)
int PyUnicodeEncodeError_SetEnd(PyObject *exc, Py_ssize_t end)
int PyUnicodeTranslateError_SetEnd(PyObject *exc, Py_ssize_t end)
Set the *end* attribute of the given exception object to *end*. Return ``0``
on success, ``-1`` on failure.
.. c:function:: PyObject* PyUnicodeDecodeError_GetReason(PyObject *exc)
PyObject* PyUnicodeEncodeError_GetReason(PyObject *exc)
PyObject* PyUnicodeTranslateError_GetReason(PyObject *exc)
Return the *reason* attribute of the given exception object.
.. c:function:: int PyUnicodeDecodeError_SetReason(PyObject *exc, const char *reason)
int PyUnicodeEncodeError_SetReason(PyObject *exc, const char *reason)
int PyUnicodeTranslateError_SetReason(PyObject *exc, const char *reason)
Set the *reason* attribute of the given exception object to *reason*. Return
``0`` on success, ``-1`` on failure.
Recursion Control
=================
These two functions provide a way to perform safe recursive calls at the C
level, both in the core and in extension modules. They are needed if the
recursive code does not necessarily invoke Python code (which tracks its
recursion depth automatically).
.. c:function:: int Py_EnterRecursiveCall(const char *where)
Marks a point where a recursive C-level call is about to be performed.
If :const:`USE_STACKCHECK` is defined, this function checks if the OS
stack overflowed using :c:func:`PyOS_CheckStack`. In this is the case, it
sets a :exc:`MemoryError` and returns a nonzero value.
The function then checks if the recursion limit is reached. If this is the
case, a :exc:`RuntimeError` is set and a nonzero value is returned.
Otherwise, zero is returned.
*where* should be a string such as ``" in instance check"`` to be
concatenated to the :exc:`RuntimeError` message caused by the recursion depth
limit.
.. c:function:: void Py_LeaveRecursiveCall()
Ends a :c:func:`Py_EnterRecursiveCall`. Must be called once for each
*successful* invocation of :c:func:`Py_EnterRecursiveCall`.
.. _standardexceptions:
Standard Exceptions
===================
All standard Python exceptions are available as global variables whose names are
``PyExc_`` followed by the Python exception name. These have the type
:c:type:`PyObject\*`; they are all class objects. For completeness, here are all
the variables:
.. index::
single: PyExc_BaseException
single: PyExc_Exception
single: PyExc_StandardError
single: PyExc_ArithmeticError
single: PyExc_AssertionError
single: PyExc_AttributeError
single: PyExc_BufferError
single: PyExc_EnvironmentError
single: PyExc_EOFError
single: PyExc_FloatingPointError
single: PyExc_GeneratorExit
single: PyExc_ImportError
single: PyExc_IndentationError
single: PyExc_IndexError
single: PyExc_IOError
single: PyExc_KeyError
single: PyExc_KeyboardInterrupt
single: PyExc_LookupError
single: PyExc_MemoryError
single: PyExc_NameError
single: PyExc_NotImplementedError
single: PyExc_OSError
single: PyExc_OverflowError
single: PyExc_ReferenceError
single: PyExc_RuntimeError
single: PyExc_StopIteration
single: PyExc_SyntaxError
single: PyExc_SystemError
single: PyExc_SystemExit
single: PyExc_TabError
single: PyExc_TypeError
single: PyExc_UnboundLocalError
single: PyExc_UnicodeDecodeError
single: PyExc_UnicodeEncodeError
single: PyExc_UnicodeError
single: PyExc_UnicodeTranslateError
single: PyExc_VMSError
single: PyExc_ValueError
single: PyExc_WindowsError
single: PyExc_ZeroDivisionError
+-----------------------------------------+---------------------------------+----------+
| C Name | Python Name | Notes |
+=========================================+=================================+==========+
| :c:data:`PyExc_BaseException` | :exc:`BaseException` | (1), (4) |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_Exception` | :exc:`Exception` | \(1) |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_StandardError` | :exc:`StandardError` | \(1) |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_ArithmeticError` | :exc:`ArithmeticError` | \(1) |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_AssertionError` | :exc:`AssertionError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_AttributeError` | :exc:`AttributeError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_BufferError` | :exc:`BufferError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_EnvironmentError` | :exc:`EnvironmentError` | \(1) |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_EOFError` | :exc:`EOFError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_FloatingPointError` | :exc:`FloatingPointError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_GeneratorExit` | :exc:`GeneratorExit` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_ImportError` | :exc:`ImportError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_IndentationError` | :exc:`IndentationError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_IndexError` | :exc:`IndexError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_IOError` | :exc:`IOError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_KeyError` | :exc:`KeyError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_KeyboardInterrupt` | :exc:`KeyboardInterrupt` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_LookupError` | :exc:`LookupError` | \(1) |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_MemoryError` | :exc:`MemoryError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_NameError` | :exc:`NameError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_NotImplementedError` | :exc:`NotImplementedError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_OSError` | :exc:`OSError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_OverflowError` | :exc:`OverflowError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_ReferenceError` | :exc:`ReferenceError` | \(2) |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_RuntimeError` | :exc:`RuntimeError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_StopIteration` | :exc:`StopIteration` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_SyntaxError` | :exc:`SyntaxError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_SystemError` | :exc:`SystemError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_SystemExit` | :exc:`SystemExit` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_TabError` | :exc:`TabError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_TypeError` | :exc:`TypeError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_UnboundLocalError` | :exc:`UnboundLocalError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_UnicodeDecodeError` | :exc:`UnicodeDecodeError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_UnicodeEncodeError` | :exc:`UnicodeEncodeError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_UnicodeError` | :exc:`UnicodeError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_UnicodeTranslateError` | :exc:`UnicodeTranslateError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_VMSError` | :exc:`VMSError` | \(5) |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_ValueError` | :exc:`ValueError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_WindowsError` | :exc:`WindowsError` | \(3) |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_ZeroDivisionError` | :exc:`ZeroDivisionError` | |
+-----------------------------------------+---------------------------------+----------+
Notes:
(1)
This is a base class for other standard exceptions.
(2)
This is the same as :exc:`weakref.ReferenceError`.
(3)
Only defined on Windows; protect code that uses this by testing that the
preprocessor macro ``MS_WINDOWS`` is defined.
(4)
.. versionadded:: 2.5
(5)
Only defined on VMS; protect code that uses this by testing that the
preprocessor macro ``__VMS`` is defined.
.. _standardwarningcategories:
Standard Warning Categories
===========================
All standard Python warning categories are available as global variables whose
names are ``PyExc_`` followed by the Python exception name. These have the type
:c:type:`PyObject\*`; they are all class objects. For completeness, here are all
the variables:
.. index::
single: PyExc_Warning
single: PyExc_BytesWarning
single: PyExc_DeprecationWarning
single: PyExc_FutureWarning
single: PyExc_ImportWarning
single: PyExc_PendingDeprecationWarning
single: PyExc_RuntimeWarning
single: PyExc_SyntaxWarning
single: PyExc_UnicodeWarning
single: PyExc_UserWarning
+------------------------------------------+---------------------------------+----------+
| C Name | Python Name | Notes |
+==========================================+=================================+==========+
| :c:data:`PyExc_Warning` | :exc:`Warning` | \(1) |
+------------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_BytesWarning` | :exc:`BytesWarning` | |
+------------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_DeprecationWarning` | :exc:`DeprecationWarning` | |
+------------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_FutureWarning` | :exc:`FutureWarning` | |
+------------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_ImportWarning` | :exc:`ImportWarning` | |
+------------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_PendingDeprecationWarning`| :exc:`PendingDeprecationWarning`| |
+------------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_RuntimeWarning` | :exc:`RuntimeWarning` | |
+------------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_SyntaxWarning` | :exc:`SyntaxWarning` | |
+------------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_UnicodeWarning` | :exc:`UnicodeWarning` | |
+------------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_UserWarning` | :exc:`UserWarning` | |
+------------------------------------------+---------------------------------+----------+
Notes:
(1)
This is a base class for other standard warning categories.
String Exceptions
=================
.. versionchanged:: 2.6
All exceptions to be raised or caught must be derived from :exc:`BaseException`.
Trying to raise a string exception now raises :exc:`TypeError`.

180
Doc/c-api/file.rst Normal file
View File

@@ -0,0 +1,180 @@
.. highlightlang:: c
.. _fileobjects:
File Objects
------------
.. index:: object: file
Python's built-in file objects are implemented entirely on the :c:type:`FILE\*`
support from the C standard library. This is an implementation detail and may
change in future releases of Python.
.. c:type:: PyFileObject
This subtype of :c:type:`PyObject` represents a Python file object.
.. c:var:: PyTypeObject PyFile_Type
.. index:: single: FileType (in module types)
This instance of :c:type:`PyTypeObject` represents the Python file type. This is
exposed to Python programs as ``file`` and ``types.FileType``.
.. c:function:: int PyFile_Check(PyObject *p)
Return true if its argument is a :c:type:`PyFileObject` or a subtype of
:c:type:`PyFileObject`.
.. versionchanged:: 2.2
Allowed subtypes to be accepted.
.. c:function:: int PyFile_CheckExact(PyObject *p)
Return true if its argument is a :c:type:`PyFileObject`, but not a subtype of
:c:type:`PyFileObject`.
.. versionadded:: 2.2
.. c:function:: PyObject* PyFile_FromString(char *filename, char *mode)
.. index:: single: fopen()
On success, return a new file object that is opened on the file given by
*filename*, with a file mode given by *mode*, where *mode* has the same
semantics as the standard C routine :c:func:`fopen`. On failure, return *NULL*.
.. c:function:: PyObject* PyFile_FromFile(FILE *fp, char *name, char *mode, int (*close)(FILE*))
Create a new :c:type:`PyFileObject` from the already-open standard C file
pointer, *fp*. The function *close* will be called when the file should be
closed. Return *NULL* and close the file using *close* on failure.
*close* is optional and can be set to *NULL*.
.. c:function:: FILE* PyFile_AsFile(PyObject \*p)
Return the file object associated with *p* as a :c:type:`FILE\*`.
If the caller will ever use the returned :c:type:`FILE\*` object while
the :term:`GIL` is released it must also call the :c:func:`PyFile_IncUseCount` and
:c:func:`PyFile_DecUseCount` functions described below as appropriate.
.. c:function:: void PyFile_IncUseCount(PyFileObject \*p)
Increments the PyFileObject's internal use count to indicate
that the underlying :c:type:`FILE\*` is being used.
This prevents Python from calling f_close() on it from another thread.
Callers of this must call :c:func:`PyFile_DecUseCount` when they are
finished with the :c:type:`FILE\*`. Otherwise the file object will
never be closed by Python.
The :term:`GIL` must be held while calling this function.
The suggested use is to call this after :c:func:`PyFile_AsFile` and before
you release the GIL::
FILE *fp = PyFile_AsFile(p);
PyFile_IncUseCount(p);
/* ... */
Py_BEGIN_ALLOW_THREADS
do_something(fp);
Py_END_ALLOW_THREADS
/* ... */
PyFile_DecUseCount(p);
.. versionadded:: 2.6
.. c:function:: void PyFile_DecUseCount(PyFileObject \*p)
Decrements the PyFileObject's internal unlocked_count member to
indicate that the caller is done with its own use of the :c:type:`FILE\*`.
This may only be called to undo a prior call to :c:func:`PyFile_IncUseCount`.
The :term:`GIL` must be held while calling this function (see the example
above).
.. versionadded:: 2.6
.. c:function:: PyObject* PyFile_GetLine(PyObject *p, int n)
.. index:: single: EOFError (built-in exception)
Equivalent to ``p.readline([n])``, this function reads one line from the
object *p*. *p* may be a file object or any object with a
:meth:`~io.IOBase.readline`
method. If *n* is ``0``, exactly one line is read, regardless of the length of
the line. If *n* is greater than ``0``, no more than *n* bytes will be read
from the file; a partial line can be returned. In both cases, an empty string
is returned if the end of the file is reached immediately. If *n* is less than
``0``, however, one line is read regardless of length, but :exc:`EOFError` is
raised if the end of the file is reached immediately.
.. c:function:: PyObject* PyFile_Name(PyObject *p)
Return the name of the file specified by *p* as a string object.
.. c:function:: void PyFile_SetBufSize(PyFileObject *p, int n)
.. index:: single: setvbuf()
Available on systems with :c:func:`setvbuf` only. This should only be called
immediately after file object creation.
.. c:function:: int PyFile_SetEncoding(PyFileObject *p, const char *enc)
Set the file's encoding for Unicode output to *enc*. Return ``1`` on success and ``0``
on failure.
.. versionadded:: 2.3
.. c:function:: int PyFile_SetEncodingAndErrors(PyFileObject *p, const char *enc, *errors)
Set the file's encoding for Unicode output to *enc*, and its error
mode to *err*. Return ``1`` on success and ``0`` on failure.
.. versionadded:: 2.6
.. c:function:: int PyFile_SoftSpace(PyObject *p, int newflag)
.. index:: single: softspace (file attribute)
This function exists for internal use by the interpreter. Set the
:attr:`softspace` attribute of *p* to *newflag* and return the previous value.
*p* does not have to be a file object for this function to work properly; any
object is supported (thought its only interesting if the :attr:`softspace`
attribute can be set). This function clears any errors, and will return ``0``
as the previous value if the attribute either does not exist or if there were
errors in retrieving it. There is no way to detect errors from this function,
but doing so should not be needed.
.. c:function:: int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags)
.. index:: single: Py_PRINT_RAW
Write object *obj* to file object *p*. The only supported flag for *flags* is
:const:`Py_PRINT_RAW`; if given, the :func:`str` of the object is written
instead of the :func:`repr`. Return ``0`` on success or ``-1`` on failure; the
appropriate exception will be set.
.. c:function:: int PyFile_WriteString(const char *s, PyObject *p)
Write string *s* to file object *p*. Return ``0`` on success or ``-1`` on
failure; the appropriate exception will be set.

120
Doc/c-api/float.rst Normal file
View File

@@ -0,0 +1,120 @@
.. highlightlang:: c
.. _floatobjects:
Floating Point Objects
----------------------
.. index:: object: floating point
.. c:type:: PyFloatObject
This subtype of :c:type:`PyObject` represents a Python floating point object.
.. c:var:: PyTypeObject PyFloat_Type
.. index:: single: FloatType (in modules types)
This instance of :c:type:`PyTypeObject` represents the Python floating point
type. This is the same object as ``float`` and ``types.FloatType``.
.. c:function:: int PyFloat_Check(PyObject *p)
Return true if its argument is a :c:type:`PyFloatObject` or a subtype of
:c:type:`PyFloatObject`.
.. versionchanged:: 2.2
Allowed subtypes to be accepted.
.. c:function:: int PyFloat_CheckExact(PyObject *p)
Return true if its argument is a :c:type:`PyFloatObject`, but not a subtype of
:c:type:`PyFloatObject`.
.. versionadded:: 2.2
.. c:function:: PyObject* PyFloat_FromString(PyObject *str, char **pend)
Create a :c:type:`PyFloatObject` object based on the string value in *str*, or
*NULL* on failure. The *pend* argument is ignored. It remains only for
backward compatibility.
.. c:function:: PyObject* PyFloat_FromDouble(double v)
Create a :c:type:`PyFloatObject` object from *v*, or *NULL* on failure.
.. c:function:: double PyFloat_AsDouble(PyObject *pyfloat)
Return a C :c:type:`double` representation of the contents of *pyfloat*. If
*pyfloat* is not a Python floating point object but has a :meth:`__float__`
method, this method will first be called to convert *pyfloat* into a float.
This method returns ``-1.0`` upon failure, so one should call
:c:func:`PyErr_Occurred` to check for errors.
.. c:function:: double PyFloat_AS_DOUBLE(PyObject *pyfloat)
Return a C :c:type:`double` representation of the contents of *pyfloat*, but
without error checking.
.. c:function:: PyObject* PyFloat_GetInfo(void)
Return a structseq instance which contains information about the
precision, minimum and maximum values of a float. It's a thin wrapper
around the header file :file:`float.h`.
.. versionadded:: 2.6
.. c:function:: double PyFloat_GetMax()
Return the maximum representable finite float *DBL_MAX* as C :c:type:`double`.
.. versionadded:: 2.6
.. c:function:: double PyFloat_GetMin()
Return the minimum normalized positive float *DBL_MIN* as C :c:type:`double`.
.. versionadded:: 2.6
.. c:function:: int PyFloat_ClearFreeList()
Clear the float free list. Return the number of items that could not
be freed.
.. versionadded:: 2.6
.. c:function:: void PyFloat_AsString(char *buf, PyFloatObject *v)
Convert the argument *v* to a string, using the same rules as
:func:`str`. The length of *buf* should be at least 100.
This function is unsafe to call because it writes to a buffer whose
length it does not know.
.. deprecated:: 2.7
Use :func:`PyObject_Str` or :func:`PyOS_double_to_string` instead.
.. c:function:: void PyFloat_AsReprString(char *buf, PyFloatObject *v)
Same as PyFloat_AsString, except uses the same rules as
:func:`repr`. The length of *buf* should be at least 100.
This function is unsafe to call because it writes to a buffer whose
length it does not know.
.. deprecated:: 2.7
Use :func:`PyObject_Repr` or :func:`PyOS_double_to_string` instead.

83
Doc/c-api/function.rst Normal file
View File

@@ -0,0 +1,83 @@
.. highlightlang:: c
.. _function-objects:
Function Objects
----------------
.. index:: object: function
There are a few functions specific to Python functions.
.. c:type:: PyFunctionObject
The C structure used for functions.
.. c:var:: PyTypeObject PyFunction_Type
.. index:: single: MethodType (in module types)
This is an instance of :c:type:`PyTypeObject` and represents the Python function
type. It is exposed to Python programmers as ``types.FunctionType``.
.. c:function:: int PyFunction_Check(PyObject *o)
Return true if *o* is a function object (has type :c:data:`PyFunction_Type`).
The parameter must not be *NULL*.
.. c:function:: PyObject* PyFunction_New(PyObject *code, PyObject *globals)
Return a new function object associated with the code object *code*. *globals*
must be a dictionary with the global variables accessible to the function.
The function's docstring, name and *__module__* are retrieved from the code
object, the argument defaults and closure are set to *NULL*.
.. c:function:: PyObject* PyFunction_GetCode(PyObject *op)
Return the code object associated with the function object *op*.
.. c:function:: PyObject* PyFunction_GetGlobals(PyObject *op)
Return the globals dictionary associated with the function object *op*.
.. c:function:: PyObject* PyFunction_GetModule(PyObject *op)
Return the *__module__* attribute of the function object *op*. This is normally
a string containing the module name, but can be set to any other object by
Python code.
.. c:function:: PyObject* PyFunction_GetDefaults(PyObject *op)
Return the argument default values of the function object *op*. This can be a
tuple of arguments or *NULL*.
.. c:function:: int PyFunction_SetDefaults(PyObject *op, PyObject *defaults)
Set the argument default values for the function object *op*. *defaults* must be
*Py_None* or a tuple.
Raises :exc:`SystemError` and returns ``-1`` on failure.
.. c:function:: PyObject* PyFunction_GetClosure(PyObject *op)
Return the closure associated with the function object *op*. This can be *NULL*
or a tuple of cell objects.
.. c:function:: int PyFunction_SetClosure(PyObject *op, PyObject *closure)
Set the closure associated with the function object *op*. *closure* must be
*Py_None* or a tuple of cell objects.
Raises :exc:`SystemError` and returns ``-1`` on failure.

166
Doc/c-api/gcsupport.rst Normal file
View File

@@ -0,0 +1,166 @@
.. highlightlang:: c
.. _supporting-cycle-detection:
Supporting Cyclic Garbage Collection
====================================
Python's support for detecting and collecting garbage which involves circular
references requires support from object types which are "containers" for other
objects which may also be containers. Types which do not store references to
other objects, or which only store references to atomic types (such as numbers
or strings), do not need to provide any explicit support for garbage
collection.
.. An example showing the use of these interfaces can be found in "Supporting the
.. Cycle Collector (XXX not found: ../ext/example-cycle-support.html)".
To create a container type, the :c:member:`~PyTypeObject.tp_flags` field of the type object must
include the :const:`Py_TPFLAGS_HAVE_GC` and provide an implementation of the
:c:member:`~PyTypeObject.tp_traverse` handler. If instances of the type are mutable, a
:c:member:`~PyTypeObject.tp_clear` implementation must also be provided.
.. data:: Py_TPFLAGS_HAVE_GC
:noindex:
Objects with a type with this flag set must conform with the rules
documented here. For convenience these objects will be referred to as
container objects.
Constructors for container types must conform to two rules:
#. The memory for the object must be allocated using :c:func:`PyObject_GC_New`
or :c:func:`PyObject_GC_NewVar`.
#. Once all the fields which may contain references to other containers are
initialized, it must call :c:func:`PyObject_GC_Track`.
.. c:function:: TYPE* PyObject_GC_New(TYPE, PyTypeObject *type)
Analogous to :c:func:`PyObject_New` but for container objects with the
:const:`Py_TPFLAGS_HAVE_GC` flag set.
.. c:function:: TYPE* PyObject_GC_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)
Analogous to :c:func:`PyObject_NewVar` but for container objects with the
:const:`Py_TPFLAGS_HAVE_GC` flag set.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: TYPE* PyObject_GC_Resize(TYPE, PyVarObject *op, Py_ssize_t newsize)
Resize an object allocated by :c:func:`PyObject_NewVar`. Returns the
resized object or *NULL* on failure. *op* must not be tracked by the collector yet.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *newsize*. This might
require changes in your code for properly supporting 64-bit systems.
.. c:function:: void PyObject_GC_Track(PyObject *op)
Adds the object *op* to the set of container objects tracked by the
collector. The collector can run at unexpected times so objects must be
valid while being tracked. This should be called once all the fields
followed by the :c:member:`~PyTypeObject.tp_traverse` handler become valid, usually near the
end of the constructor.
.. c:function:: void _PyObject_GC_TRACK(PyObject *op)
A macro version of :c:func:`PyObject_GC_Track`. It should not be used for
extension modules.
Similarly, the deallocator for the object must conform to a similar pair of
rules:
#. Before fields which refer to other containers are invalidated,
:c:func:`PyObject_GC_UnTrack` must be called.
#. The object's memory must be deallocated using :c:func:`PyObject_GC_Del`.
.. c:function:: void PyObject_GC_Del(void *op)
Releases memory allocated to an object using :c:func:`PyObject_GC_New` or
:c:func:`PyObject_GC_NewVar`.
.. c:function:: void PyObject_GC_UnTrack(void *op)
Remove the object *op* from the set of container objects tracked by the
collector. Note that :c:func:`PyObject_GC_Track` can be called again on
this object to add it back to the set of tracked objects. The deallocator
(:c:member:`~PyTypeObject.tp_dealloc` handler) should call this for the object before any of
the fields used by the :c:member:`~PyTypeObject.tp_traverse` handler become invalid.
.. c:function:: void _PyObject_GC_UNTRACK(PyObject *op)
A macro version of :c:func:`PyObject_GC_UnTrack`. It should not be used for
extension modules.
The :c:member:`~PyTypeObject.tp_traverse` handler accepts a function parameter of this type:
.. c:type:: int (*visitproc)(PyObject *object, void *arg)
Type of the visitor function passed to the :c:member:`~PyTypeObject.tp_traverse` handler.
The function should be called with an object to traverse as *object* and
the third parameter to the :c:member:`~PyTypeObject.tp_traverse` handler as *arg*. The
Python core uses several visitor functions to implement cyclic garbage
detection; it's not expected that users will need to write their own
visitor functions.
The :c:member:`~PyTypeObject.tp_traverse` handler must have the following type:
.. c:type:: int (*traverseproc)(PyObject *self, visitproc visit, void *arg)
Traversal function for a container object. Implementations must call the
*visit* function for each object directly contained by *self*, with the
parameters to *visit* being the contained object and the *arg* value passed
to the handler. The *visit* function must not be called with a *NULL*
object argument. If *visit* returns a non-zero value that value should be
returned immediately.
To simplify writing :c:member:`~PyTypeObject.tp_traverse` handlers, a :c:func:`Py_VISIT` macro is
provided. In order to use this macro, the :c:member:`~PyTypeObject.tp_traverse` implementation
must name its arguments exactly *visit* and *arg*:
.. c:function:: void Py_VISIT(PyObject *o)
If *o* is not *NULL*, call the *visit* callback, with arguments *o*
and *arg*. If *visit* returns a non-zero value, then return it.
Using this macro, :c:member:`~PyTypeObject.tp_traverse` handlers
look like::
static int
my_traverse(Noddy *self, visitproc visit, void *arg)
{
Py_VISIT(self->foo);
Py_VISIT(self->bar);
return 0;
}
.. versionadded:: 2.4
The :c:member:`~PyTypeObject.tp_clear` handler must be of the :c:type:`inquiry` type, or *NULL*
if the object is immutable.
.. c:type:: int (*inquiry)(PyObject *self)
Drop references that may have created reference cycles. Immutable objects
do not have to define this method since they can never directly create
reference cycles. Note that the object must still be valid after calling
this method (don't just call :c:func:`Py_DECREF` on a reference). The
collector will call this method if it detects that this object is involved
in a reference cycle.

38
Doc/c-api/gen.rst Normal file
View File

@@ -0,0 +1,38 @@
.. highlightlang:: c
.. _gen-objects:
Generator Objects
-----------------
Generator objects are what Python uses to implement generator iterators. They
are normally created by iterating over a function that yields values, rather
than explicitly calling :c:func:`PyGen_New`.
.. c:type:: PyGenObject
The C structure used for generator objects.
.. c:var:: PyTypeObject PyGen_Type
The type object corresponding to generator objects.
.. c:function:: int PyGen_Check(ob)
Return true if *ob* is a generator object; *ob* must not be *NULL*.
.. c:function:: int PyGen_CheckExact(ob)
Return true if *ob*'s type is *PyGen_Type* is a generator object; *ob* must not
be *NULL*.
.. c:function:: PyObject* PyGen_New(PyFrameObject *frame)
Create and return a new generator object based on the *frame* object. A
reference to *frame* is stolen by this function. The parameter must not be
*NULL*.

276
Doc/c-api/import.rst Normal file
View File

@@ -0,0 +1,276 @@
.. highlightlang:: c
.. _importing:
Importing Modules
=================
.. c:function:: PyObject* PyImport_ImportModule(const char *name)
.. index::
single: package variable; __all__
single: __all__ (package variable)
single: modules (in module sys)
This is a simplified interface to :c:func:`PyImport_ImportModuleEx` below,
leaving the *globals* and *locals* arguments set to *NULL* and *level* set
to 0. When the *name*
argument contains a dot (when it specifies a submodule of a package), the
*fromlist* argument is set to the list ``['*']`` so that the return value is the
named module rather than the top-level package containing it as would otherwise
be the case. (Unfortunately, this has an additional side effect when *name* in
fact specifies a subpackage instead of a submodule: the submodules specified in
the package's ``__all__`` variable are loaded.) Return a new reference to the
imported module, or *NULL* with an exception set on failure. Before Python 2.4,
the module may still be created in the failure case --- examine ``sys.modules``
to find out. Starting with Python 2.4, a failing import of a module no longer
leaves the module in ``sys.modules``.
.. versionchanged:: 2.4
Failing imports remove incomplete module objects.
.. versionchanged:: 2.6
Always uses absolute imports.
.. c:function:: PyObject* PyImport_ImportModuleNoBlock(const char *name)
This version of :c:func:`PyImport_ImportModule` does not block. It's intended
to be used in C functions that import other modules to execute a function.
The import may block if another thread holds the import lock. The function
:c:func:`PyImport_ImportModuleNoBlock` never blocks. It first tries to fetch
the module from sys.modules and falls back to :c:func:`PyImport_ImportModule`
unless the lock is held, in which case the function will raise an
:exc:`ImportError`.
.. versionadded:: 2.6
.. c:function:: PyObject* PyImport_ImportModuleEx(char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)
.. index:: builtin: __import__
Import a module. This is best described by referring to the built-in Python
function :func:`__import__`, as the standard :func:`__import__` function calls
this function directly.
The return value is a new reference to the imported module or top-level package,
or *NULL* with an exception set on failure (before Python 2.4, the module may
still be created in this case). Like for :func:`__import__`, the return value
when a submodule of a package was requested is normally the top-level package,
unless a non-empty *fromlist* was given.
.. versionchanged:: 2.4
Failing imports remove incomplete module objects.
.. versionchanged:: 2.6
The function is an alias for :c:func:`PyImport_ImportModuleLevel` with
``-1`` as level, meaning relative import.
.. c:function:: PyObject* PyImport_ImportModuleLevel(char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)
Import a module. This is best described by referring to the built-in Python
function :func:`__import__`, as the standard :func:`__import__` function calls
this function directly.
The return value is a new reference to the imported module or top-level package,
or *NULL* with an exception set on failure. Like for :func:`__import__`,
the return value when a submodule of a package was requested is normally the
top-level package, unless a non-empty *fromlist* was given.
.. versionadded:: 2.5
.. c:function:: PyObject* PyImport_Import(PyObject *name)
.. index::
module: rexec
module: ihooks
This is a higher-level interface that calls the current "import hook function".
It invokes the :func:`__import__` function from the ``__builtins__`` of the
current globals. This means that the import is done using whatever import hooks
are installed in the current environment, e.g. by :mod:`rexec` or :mod:`ihooks`.
.. versionchanged:: 2.6
Always uses absolute imports.
.. c:function:: PyObject* PyImport_ReloadModule(PyObject *m)
.. index:: builtin: reload
Reload a module. This is best described by referring to the built-in Python
function :func:`reload`, as the standard :func:`reload` function calls this
function directly. Return a new reference to the reloaded module, or *NULL*
with an exception set on failure (the module still exists in this case).
.. c:function:: PyObject* PyImport_AddModule(const char *name)
Return the module object corresponding to a module name. The *name* argument
may be of the form ``package.module``. First check the modules dictionary if
there's one there, and if not, create a new one and insert it in the modules
dictionary. Return *NULL* with an exception set on failure.
.. note::
This function does not load or import the module; if the module wasn't already
loaded, you will get an empty module object. Use :c:func:`PyImport_ImportModule`
or one of its variants to import a module. Package structures implied by a
dotted name for *name* are not created if not already present.
.. c:function:: PyObject* PyImport_ExecCodeModule(char *name, PyObject *co)
.. index:: builtin: compile
Given a module name (possibly of the form ``package.module``) and a code object
read from a Python bytecode file or obtained from the built-in function
:func:`compile`, load the module. Return a new reference to the module object,
or *NULL* with an exception set if an error occurred. Before Python 2.4, the
module could still be created in error cases. Starting with Python 2.4, *name*
is removed from :attr:`sys.modules` in error cases, and even if *name* was already
in :attr:`sys.modules` on entry to :c:func:`PyImport_ExecCodeModule`. Leaving
incompletely initialized modules in :attr:`sys.modules` is dangerous, as imports of
such modules have no way to know that the module object is an unknown (and
probably damaged with respect to the module author's intents) state.
The module's :attr:`__file__` attribute will be set to the code object's
:c:member:`co_filename`.
This function will reload the module if it was already imported. See
:c:func:`PyImport_ReloadModule` for the intended way to reload a module.
If *name* points to a dotted name of the form ``package.module``, any package
structures not already created will still not be created.
.. versionchanged:: 2.4
*name* is removed from :attr:`sys.modules` in error cases.
.. c:function:: PyObject* PyImport_ExecCodeModuleEx(char *name, PyObject *co, char *pathname)
Like :c:func:`PyImport_ExecCodeModule`, but the :attr:`__file__` attribute of
the module object is set to *pathname* if it is non-``NULL``.
.. c:function:: long PyImport_GetMagicNumber()
Return the magic number for Python bytecode files (a.k.a. :file:`.pyc` and
:file:`.pyo` files). The magic number should be present in the first four bytes
of the bytecode file, in little-endian byte order.
.. c:function:: PyObject* PyImport_GetModuleDict()
Return the dictionary used for the module administration (a.k.a.
``sys.modules``). Note that this is a per-interpreter variable.
.. c:function:: PyObject* PyImport_GetImporter(PyObject *path)
Return an importer object for a :data:`sys.path`/:attr:`pkg.__path__` item
*path*, possibly by fetching it from the :data:`sys.path_importer_cache`
dict. If it wasn't yet cached, traverse :data:`sys.path_hooks` until a hook
is found that can handle the path item. Return ``None`` if no hook could;
this tells our caller it should fall back to the built-in import mechanism.
Cache the result in :data:`sys.path_importer_cache`. Return a new reference
to the importer object.
.. versionadded:: 2.6
.. c:function:: void _PyImport_Init()
Initialize the import mechanism. For internal use only.
.. c:function:: void PyImport_Cleanup()
Empty the module table. For internal use only.
.. c:function:: void _PyImport_Fini()
Finalize the import mechanism. For internal use only.
.. c:function:: PyObject* _PyImport_FindExtension(char *, char *)
For internal use only.
.. c:function:: PyObject* _PyImport_FixupExtension(char *, char *)
For internal use only.
.. c:function:: int PyImport_ImportFrozenModule(char *name)
Load a frozen module named *name*. Return ``1`` for success, ``0`` if the
module is not found, and ``-1`` with an exception set if the initialization
failed. To access the imported module on a successful load, use
:c:func:`PyImport_ImportModule`. (Note the misnomer --- this function would
reload the module if it was already imported.)
.. c:type:: struct _frozen
.. index:: single: freeze utility
This is the structure type definition for frozen module descriptors, as
generated by the :program:`freeze` utility (see :file:`Tools/freeze/` in the
Python source distribution). Its definition, found in :file:`Include/import.h`,
is::
struct _frozen {
char *name;
unsigned char *code;
int size;
};
.. c:var:: struct _frozen* PyImport_FrozenModules
This pointer is initialized to point to an array of :c:type:`struct _frozen`
records, terminated by one whose members are all *NULL* or zero. When a frozen
module is imported, it is searched in this table. Third-party code could play
tricks with this to provide a dynamically created collection of frozen modules.
.. c:function:: int PyImport_AppendInittab(const char *name, void (*initfunc)(void))
Add a single module to the existing table of built-in modules. This is a
convenience wrapper around :c:func:`PyImport_ExtendInittab`, returning ``-1`` if
the table could not be extended. The new module can be imported by the name
*name*, and uses the function *initfunc* as the initialization function called
on the first attempted import. This should be called before
:c:func:`Py_Initialize`.
.. c:type:: struct _inittab
Structure describing a single entry in the list of built-in modules. Each of
these structures gives the name and initialization function for a module built
into the interpreter. Programs which embed Python may use an array of these
structures in conjunction with :c:func:`PyImport_ExtendInittab` to provide
additional built-in modules. The structure is defined in
:file:`Include/import.h` as::
struct _inittab {
char *name;
void (*initfunc)(void);
};
.. c:function:: int PyImport_ExtendInittab(struct _inittab *newtab)
Add a collection of modules to the table of built-in modules. The *newtab*
array must end with a sentinel entry which contains *NULL* for the :attr:`name`
field; failure to provide the sentinel value can result in a memory fault.
Returns ``0`` on success or ``-1`` if insufficient memory could be allocated to
extend the internal table. In the event of failure, no modules are added to the
internal table. This should be called before :c:func:`Py_Initialize`.

24
Doc/c-api/index.rst Normal file
View File

@@ -0,0 +1,24 @@
.. _c-api-index:
##################################
Python/C API Reference Manual
##################################
This manual documents the API used by C and C++ programmers who want to write
extension modules or embed Python. It is a companion to :ref:`extending-index`,
which describes the general principles of extension writing but does not
document the API functions in detail.
.. toctree::
:maxdepth: 2
intro.rst
veryhigh.rst
refcounting.rst
exceptions.rst
utilities.rst
abstract.rst
concrete.rst
init.rst
memory.rst
objimpl.rst

1155
Doc/c-api/init.rst Normal file
View File

File diff suppressed because it is too large Load Diff

139
Doc/c-api/int.rst Normal file
View File

@@ -0,0 +1,139 @@
.. highlightlang:: c
.. _intobjects:
Plain Integer Objects
---------------------
.. index:: object: integer
.. c:type:: PyIntObject
This subtype of :c:type:`PyObject` represents a Python integer object.
.. c:var:: PyTypeObject PyInt_Type
.. index:: single: IntType (in modules types)
This instance of :c:type:`PyTypeObject` represents the Python plain integer type.
This is the same object as ``int`` and ``types.IntType``.
.. c:function:: int PyInt_Check(PyObject *o)
Return true if *o* is of type :c:data:`PyInt_Type` or a subtype of
:c:data:`PyInt_Type`.
.. versionchanged:: 2.2
Allowed subtypes to be accepted.
.. c:function:: int PyInt_CheckExact(PyObject *o)
Return true if *o* is of type :c:data:`PyInt_Type`, but not a subtype of
:c:data:`PyInt_Type`.
.. versionadded:: 2.2
.. c:function:: PyObject* PyInt_FromString(char *str, char **pend, int base)
Return a new :c:type:`PyIntObject` or :c:type:`PyLongObject` based on the string
value in *str*, which is interpreted according to the radix in *base*. If
*pend* is non-*NULL*, ``*pend`` will point to the first character in *str* which
follows the representation of the number. If *base* is ``0``, the radix will be
determined based on the leading characters of *str*: if *str* starts with
``'0x'`` or ``'0X'``, radix 16 will be used; if *str* starts with ``'0'``, radix
8 will be used; otherwise radix 10 will be used. If *base* is not ``0``, it
must be between ``2`` and ``36``, inclusive. Leading spaces are ignored. If
there are no digits, :exc:`ValueError` will be raised. If the string represents
a number too large to be contained within the machine's :c:type:`long int` type
and overflow warnings are being suppressed, a :c:type:`PyLongObject` will be
returned. If overflow warnings are not being suppressed, *NULL* will be
returned in this case.
.. c:function:: PyObject* PyInt_FromLong(long ival)
Create a new integer object with a value of *ival*.
The current implementation keeps an array of integer objects for all integers
between ``-5`` and ``256``, when you create an int in that range you actually
just get back a reference to the existing object. So it should be possible to
change the value of ``1``. I suspect the behaviour of Python in this case is
undefined. :-)
.. c:function:: PyObject* PyInt_FromSsize_t(Py_ssize_t ival)
Create a new integer object with a value of *ival*. If the value is larger
than ``LONG_MAX`` or smaller than ``LONG_MIN``, a long integer object is
returned.
.. versionadded:: 2.5
.. c:function:: PyObject* PyInt_FromSize_t(size_t ival)
Create a new integer object with a value of *ival*. If the value exceeds
``LONG_MAX``, a long integer object is returned.
.. versionadded:: 2.5
.. c:function:: long PyInt_AsLong(PyObject *io)
Will first attempt to cast the object to a :c:type:`PyIntObject`, if it is not
already one, and then return its value. If there is an error, ``-1`` is
returned, and the caller should check ``PyErr_Occurred()`` to find out whether
there was an error, or whether the value just happened to be ``-1``.
.. c:function:: long PyInt_AS_LONG(PyObject *io)
Return the value of the object *io*. No error checking is performed.
.. c:function:: unsigned long PyInt_AsUnsignedLongMask(PyObject *io)
Will first attempt to cast the object to a :c:type:`PyIntObject` or
:c:type:`PyLongObject`, if it is not already one, and then return its value as
unsigned long. This function does not check for overflow.
.. versionadded:: 2.3
.. c:function:: unsigned PY_LONG_LONG PyInt_AsUnsignedLongLongMask(PyObject *io)
Will first attempt to cast the object to a :c:type:`PyIntObject` or
:c:type:`PyLongObject`, if it is not already one, and then return its value as
unsigned long long, without checking for overflow.
.. versionadded:: 2.3
.. c:function:: Py_ssize_t PyInt_AsSsize_t(PyObject *io)
Will first attempt to cast the object to a :c:type:`PyIntObject` or
:c:type:`PyLongObject`, if it is not already one, and then return its value as
:c:type:`Py_ssize_t`.
.. versionadded:: 2.5
.. c:function:: long PyInt_GetMax()
.. index:: single: LONG_MAX
Return the system's idea of the largest integer it can handle
(:const:`LONG_MAX`, as defined in the system header files).
.. c:function:: int PyInt_ClearFreeList()
Clear the integer free list. Return the number of items that could not
be freed.
.. versionadded:: 2.6

638
Doc/c-api/intro.rst Normal file
View File

@@ -0,0 +1,638 @@
.. highlightlang:: c
.. _api-intro:
************
Introduction
************
The Application Programmer's Interface to Python gives C and C++ programmers
access to the Python interpreter at a variety of levels. The API is equally
usable from C++, but for brevity it is generally referred to as the Python/C
API. There are two fundamentally different reasons for using the Python/C API.
The first reason is to write *extension modules* for specific purposes; these
are C modules that extend the Python interpreter. This is probably the most
common use. The second reason is to use Python as a component in a larger
application; this technique is generally referred to as :dfn:`embedding` Python
in an application.
Writing an extension module is a relatively well-understood process, where a
"cookbook" approach works well. There are several tools that automate the
process to some extent. While people have embedded Python in other
applications since its early existence, the process of embedding Python is less
straightforward than writing an extension.
Many API functions are useful independent of whether you're embedding or
extending Python; moreover, most applications that embed Python will need to
provide a custom extension as well, so it's probably a good idea to become
familiar with writing an extension before attempting to embed Python in a real
application.
.. _api-includes:
Include Files
=============
All function, type and macro definitions needed to use the Python/C API are
included in your code by the following line::
#include "Python.h"
This implies inclusion of the following standard headers: ``<stdio.h>``,
``<string.h>``, ``<errno.h>``, ``<limits.h>``, ``<assert.h>`` and ``<stdlib.h>``
(if available).
.. note::
Since Python may define some pre-processor definitions which affect the standard
headers on some systems, you *must* include :file:`Python.h` before any standard
headers are included.
All user visible names defined by Python.h (except those defined by the included
standard headers) have one of the prefixes ``Py`` or ``_Py``. Names beginning
with ``_Py`` are for internal use by the Python implementation and should not be
used by extension writers. Structure member names do not have a reserved prefix.
**Important:** user code should never define names that begin with ``Py`` or
``_Py``. This confuses the reader, and jeopardizes the portability of the user
code to future Python versions, which may define additional names beginning with
one of these prefixes.
The header files are typically installed with Python. On Unix, these are
located in the directories :file:`{prefix}/include/pythonversion/` and
:file:`{exec_prefix}/include/pythonversion/`, where :envvar:`prefix` and
:envvar:`exec_prefix` are defined by the corresponding parameters to Python's
:program:`configure` script and *version* is ``sys.version[:3]``. On Windows,
the headers are installed in :file:`{prefix}/include`, where :envvar:`prefix` is
the installation directory specified to the installer.
To include the headers, place both directories (if different) on your compiler's
search path for includes. Do *not* place the parent directories on the search
path and then use ``#include <pythonX.Y/Python.h>``; this will break on
multi-platform builds since the platform independent headers under
:envvar:`prefix` include the platform specific headers from
:envvar:`exec_prefix`.
C++ users should note that though the API is defined entirely using C, the
header files do properly declare the entry points to be ``extern "C"``, so there
is no need to do anything special to use the API from C++.
.. _api-objects:
Objects, Types and Reference Counts
===================================
.. index:: object: type
Most Python/C API functions have one or more arguments as well as a return value
of type :c:type:`PyObject\*`. This type is a pointer to an opaque data type
representing an arbitrary Python object. Since all Python object types are
treated the same way by the Python language in most situations (e.g.,
assignments, scope rules, and argument passing), it is only fitting that they
should be represented by a single C type. Almost all Python objects live on the
heap: you never declare an automatic or static variable of type
:c:type:`PyObject`, only pointer variables of type :c:type:`PyObject\*` can be
declared. The sole exception are the type objects; since these must never be
deallocated, they are typically static :c:type:`PyTypeObject` objects.
All Python objects (even Python integers) have a :dfn:`type` and a
:dfn:`reference count`. An object's type determines what kind of object it is
(e.g., an integer, a list, or a user-defined function; there are many more as
explained in :ref:`types`). For each of the well-known types there is a macro
to check whether an object is of that type; for instance, ``PyList_Check(a)`` is
true if (and only if) the object pointed to by *a* is a Python list.
.. _api-refcounts:
Reference Counts
----------------
The reference count is important because today's computers have a finite (and
often severely limited) memory size; it counts how many different places there
are that have a reference to an object. Such a place could be another object,
or a global (or static) C variable, or a local variable in some C function.
When an object's reference count becomes zero, the object is deallocated. If
it contains references to other objects, their reference count is decremented.
Those other objects may be deallocated in turn, if this decrement makes their
reference count become zero, and so on. (There's an obvious problem with
objects that reference each other here; for now, the solution is "don't do
that.")
.. index::
single: Py_INCREF()
single: Py_DECREF()
Reference counts are always manipulated explicitly. The normal way is to use
the macro :c:func:`Py_INCREF` to increment an object's reference count by one,
and :c:func:`Py_DECREF` to decrement it by one. The :c:func:`Py_DECREF` macro
is considerably more complex than the incref one, since it must check whether
the reference count becomes zero and then cause the object's deallocator to be
called. The deallocator is a function pointer contained in the object's type
structure. The type-specific deallocator takes care of decrementing the
reference counts for other objects contained in the object if this is a compound
object type, such as a list, as well as performing any additional finalization
that's needed. There's no chance that the reference count can overflow; at
least as many bits are used to hold the reference count as there are distinct
memory locations in virtual memory (assuming ``sizeof(Py_ssize_t) >= sizeof(void*)``).
Thus, the reference count increment is a simple operation.
It is not necessary to increment an object's reference count for every local
variable that contains a pointer to an object. In theory, the object's
reference count goes up by one when the variable is made to point to it and it
goes down by one when the variable goes out of scope. However, these two
cancel each other out, so at the end the reference count hasn't changed. The
only real reason to use the reference count is to prevent the object from being
deallocated as long as our variable is pointing to it. If we know that there
is at least one other reference to the object that lives at least as long as
our variable, there is no need to increment the reference count temporarily.
An important situation where this arises is in objects that are passed as
arguments to C functions in an extension module that are called from Python;
the call mechanism guarantees to hold a reference to every argument for the
duration of the call.
However, a common pitfall is to extract an object from a list and hold on to it
for a while without incrementing its reference count. Some other operation might
conceivably remove the object from the list, decrementing its reference count
and possible deallocating it. The real danger is that innocent-looking
operations may invoke arbitrary Python code which could do this; there is a code
path which allows control to flow back to the user from a :c:func:`Py_DECREF`, so
almost any operation is potentially dangerous.
A safe approach is to always use the generic operations (functions whose name
begins with ``PyObject_``, ``PyNumber_``, ``PySequence_`` or ``PyMapping_``).
These operations always increment the reference count of the object they return.
This leaves the caller with the responsibility to call :c:func:`Py_DECREF` when
they are done with the result; this soon becomes second nature.
.. _api-refcountdetails:
Reference Count Details
^^^^^^^^^^^^^^^^^^^^^^^
The reference count behavior of functions in the Python/C API is best explained
in terms of *ownership of references*. Ownership pertains to references, never
to objects (objects are not owned: they are always shared). "Owning a
reference" means being responsible for calling Py_DECREF on it when the
reference is no longer needed. Ownership can also be transferred, meaning that
the code that receives ownership of the reference then becomes responsible for
eventually decref'ing it by calling :c:func:`Py_DECREF` or :c:func:`Py_XDECREF`
when it's no longer needed---or passing on this responsibility (usually to its
caller). When a function passes ownership of a reference on to its caller, the
caller is said to receive a *new* reference. When no ownership is transferred,
the caller is said to *borrow* the reference. Nothing needs to be done for a
borrowed reference.
Conversely, when a calling function passes in a reference to an object, there
are two possibilities: the function *steals* a reference to the object, or it
does not. *Stealing a reference* means that when you pass a reference to a
function, that function assumes that it now owns that reference, and you are not
responsible for it any longer.
.. index::
single: PyList_SetItem()
single: PyTuple_SetItem()
Few functions steal references; the two notable exceptions are
:c:func:`PyList_SetItem` and :c:func:`PyTuple_SetItem`, which steal a reference
to the item (but not to the tuple or list into which the item is put!). These
functions were designed to steal a reference because of a common idiom for
populating a tuple or list with newly created objects; for example, the code to
create the tuple ``(1, 2, "three")`` could look like this (forgetting about
error handling for the moment; a better way to code this is shown below)::
PyObject *t;
t = PyTuple_New(3);
PyTuple_SetItem(t, 0, PyInt_FromLong(1L));
PyTuple_SetItem(t, 1, PyInt_FromLong(2L));
PyTuple_SetItem(t, 2, PyString_FromString("three"));
Here, :c:func:`PyInt_FromLong` returns a new reference which is immediately
stolen by :c:func:`PyTuple_SetItem`. When you want to keep using an object
although the reference to it will be stolen, use :c:func:`Py_INCREF` to grab
another reference before calling the reference-stealing function.
Incidentally, :c:func:`PyTuple_SetItem` is the *only* way to set tuple items;
:c:func:`PySequence_SetItem` and :c:func:`PyObject_SetItem` refuse to do this
since tuples are an immutable data type. You should only use
:c:func:`PyTuple_SetItem` for tuples that you are creating yourself.
Equivalent code for populating a list can be written using :c:func:`PyList_New`
and :c:func:`PyList_SetItem`.
However, in practice, you will rarely use these ways of creating and populating
a tuple or list. There's a generic function, :c:func:`Py_BuildValue`, that can
create most common objects from C values, directed by a :dfn:`format string`.
For example, the above two blocks of code could be replaced by the following
(which also takes care of the error checking)::
PyObject *tuple, *list;
tuple = Py_BuildValue("(iis)", 1, 2, "three");
list = Py_BuildValue("[iis]", 1, 2, "three");
It is much more common to use :c:func:`PyObject_SetItem` and friends with items
whose references you are only borrowing, like arguments that were passed in to
the function you are writing. In that case, their behaviour regarding reference
counts is much saner, since you don't have to increment a reference count so you
can give a reference away ("have it be stolen"). For example, this function
sets all items of a list (actually, any mutable sequence) to a given item::
int
set_all(PyObject *target, PyObject *item)
{
int i, n;
n = PyObject_Length(target);
if (n < 0)
return -1;
for (i = 0; i < n; i++) {
PyObject *index = PyInt_FromLong(i);
if (!index)
return -1;
if (PyObject_SetItem(target, index, item) < 0) {
Py_DECREF(index);
return -1;
}
Py_DECREF(index);
}
return 0;
}
.. index:: single: set_all()
The situation is slightly different for function return values. While passing
a reference to most functions does not change your ownership responsibilities
for that reference, many functions that return a reference to an object give
you ownership of the reference. The reason is simple: in many cases, the
returned object is created on the fly, and the reference you get is the only
reference to the object. Therefore, the generic functions that return object
references, like :c:func:`PyObject_GetItem` and :c:func:`PySequence_GetItem`,
always return a new reference (the caller becomes the owner of the reference).
It is important to realize that whether you own a reference returned by a
function depends on which function you call only --- *the plumage* (the type of
the object passed as an argument to the function) *doesn't enter into it!*
Thus, if you extract an item from a list using :c:func:`PyList_GetItem`, you
don't own the reference --- but if you obtain the same item from the same list
using :c:func:`PySequence_GetItem` (which happens to take exactly the same
arguments), you do own a reference to the returned object.
.. index::
single: PyList_GetItem()
single: PySequence_GetItem()
Here is an example of how you could write a function that computes the sum of
the items in a list of integers; once using :c:func:`PyList_GetItem`, and once
using :c:func:`PySequence_GetItem`. ::
long
sum_list(PyObject *list)
{
int i, n;
long total = 0;
PyObject *item;
n = PyList_Size(list);
if (n < 0)
return -1; /* Not a list */
for (i = 0; i < n; i++) {
item = PyList_GetItem(list, i); /* Can't fail */
if (!PyInt_Check(item)) continue; /* Skip non-integers */
total += PyInt_AsLong(item);
}
return total;
}
.. index:: single: sum_list()
::
long
sum_sequence(PyObject *sequence)
{
int i, n;
long total = 0;
PyObject *item;
n = PySequence_Length(sequence);
if (n < 0)
return -1; /* Has no length */
for (i = 0; i < n; i++) {
item = PySequence_GetItem(sequence, i);
if (item == NULL)
return -1; /* Not a sequence, or other failure */
if (PyInt_Check(item))
total += PyInt_AsLong(item);
Py_DECREF(item); /* Discard reference ownership */
}
return total;
}
.. index:: single: sum_sequence()
.. _api-types:
Types
-----
There are few other data types that play a significant role in the Python/C
API; most are simple C types such as :c:type:`int`, :c:type:`long`,
:c:type:`double` and :c:type:`char\*`. A few structure types are used to
describe static tables used to list the functions exported by a module or the
data attributes of a new object type, and another is used to describe the value
of a complex number. These will be discussed together with the functions that
use them.
.. _api-exceptions:
Exceptions
==========
The Python programmer only needs to deal with exceptions if specific error
handling is required; unhandled exceptions are automatically propagated to the
caller, then to the caller's caller, and so on, until they reach the top-level
interpreter, where they are reported to the user accompanied by a stack
traceback.
.. index:: single: PyErr_Occurred()
For C programmers, however, error checking always has to be explicit. All
functions in the Python/C API can raise exceptions, unless an explicit claim is
made otherwise in a function's documentation. In general, when a function
encounters an error, it sets an exception, discards any object references that
it owns, and returns an error indicator. If not documented otherwise, this
indicator is either *NULL* or ``-1``, depending on the function's return type.
A few functions return a Boolean true/false result, with false indicating an
error. Very few functions return no explicit error indicator or have an
ambiguous return value, and require explicit testing for errors with
:c:func:`PyErr_Occurred`. These exceptions are always explicitly documented.
.. index::
single: PyErr_SetString()
single: PyErr_Clear()
Exception state is maintained in per-thread storage (this is equivalent to
using global storage in an unthreaded application). A thread can be in one of
two states: an exception has occurred, or not. The function
:c:func:`PyErr_Occurred` can be used to check for this: it returns a borrowed
reference to the exception type object when an exception has occurred, and
*NULL* otherwise. There are a number of functions to set the exception state:
:c:func:`PyErr_SetString` is the most common (though not the most general)
function to set the exception state, and :c:func:`PyErr_Clear` clears the
exception state.
.. index::
single: exc_type (in module sys)
single: exc_value (in module sys)
single: exc_traceback (in module sys)
The full exception state consists of three objects (all of which can be
*NULL*): the exception type, the corresponding exception value, and the
traceback. These have the same meanings as the Python objects
``sys.exc_type``, ``sys.exc_value``, and ``sys.exc_traceback``; however, they
are not the same: the Python objects represent the last exception being handled
by a Python :keyword:`try` ... :keyword:`except` statement, while the C level
exception state only exists while an exception is being passed on between C
functions until it reaches the Python bytecode interpreter's main loop, which
takes care of transferring it to ``sys.exc_type`` and friends.
.. index:: single: exc_info() (in module sys)
Note that starting with Python 1.5, the preferred, thread-safe way to access the
exception state from Python code is to call the function :func:`sys.exc_info`,
which returns the per-thread exception state for Python code. Also, the
semantics of both ways to access the exception state have changed so that a
function which catches an exception will save and restore its thread's exception
state so as to preserve the exception state of its caller. This prevents common
bugs in exception handling code caused by an innocent-looking function
overwriting the exception being handled; it also reduces the often unwanted
lifetime extension for objects that are referenced by the stack frames in the
traceback.
As a general principle, a function that calls another function to perform some
task should check whether the called function raised an exception, and if so,
pass the exception state on to its caller. It should discard any object
references that it owns, and return an error indicator, but it should *not* set
another exception --- that would overwrite the exception that was just raised,
and lose important information about the exact cause of the error.
.. index:: single: sum_sequence()
A simple example of detecting exceptions and passing them on is shown in the
:c:func:`sum_sequence` example above. It so happens that this example doesn't
need to clean up any owned references when it detects an error. The following
example function shows some error cleanup. First, to remind you why you like
Python, we show the equivalent Python code::
def incr_item(dict, key):
try:
item = dict[key]
except KeyError:
item = 0
dict[key] = item + 1
.. index:: single: incr_item()
Here is the corresponding C code, in all its glory::
int
incr_item(PyObject *dict, PyObject *key)
{
/* Objects all initialized to NULL for Py_XDECREF */
PyObject *item = NULL, *const_one = NULL, *incremented_item = NULL;
int rv = -1; /* Return value initialized to -1 (failure) */
item = PyObject_GetItem(dict, key);
if (item == NULL) {
/* Handle KeyError only: */
if (!PyErr_ExceptionMatches(PyExc_KeyError))
goto error;
/* Clear the error and use zero: */
PyErr_Clear();
item = PyInt_FromLong(0L);
if (item == NULL)
goto error;
}
const_one = PyInt_FromLong(1L);
if (const_one == NULL)
goto error;
incremented_item = PyNumber_Add(item, const_one);
if (incremented_item == NULL)
goto error;
if (PyObject_SetItem(dict, key, incremented_item) < 0)
goto error;
rv = 0; /* Success */
/* Continue with cleanup code */
error:
/* Cleanup code, shared by success and failure path */
/* Use Py_XDECREF() to ignore NULL references */
Py_XDECREF(item);
Py_XDECREF(const_one);
Py_XDECREF(incremented_item);
return rv; /* -1 for error, 0 for success */
}
.. index:: single: incr_item()
.. index::
single: PyErr_ExceptionMatches()
single: PyErr_Clear()
single: Py_XDECREF()
This example represents an endorsed use of the ``goto`` statement in C!
It illustrates the use of :c:func:`PyErr_ExceptionMatches` and
:c:func:`PyErr_Clear` to handle specific exceptions, and the use of
:c:func:`Py_XDECREF` to dispose of owned references that may be *NULL* (note the
``'X'`` in the name; :c:func:`Py_DECREF` would crash when confronted with a
*NULL* reference). It is important that the variables used to hold owned
references are initialized to *NULL* for this to work; likewise, the proposed
return value is initialized to ``-1`` (failure) and only set to success after
the final call made is successful.
.. _api-embedding:
Embedding Python
================
The one important task that only embedders (as opposed to extension writers) of
the Python interpreter have to worry about is the initialization, and possibly
the finalization, of the Python interpreter. Most functionality of the
interpreter can only be used after the interpreter has been initialized.
.. index::
single: Py_Initialize()
module: __builtin__
module: __main__
module: sys
module: exceptions
triple: module; search; path
single: path (in module sys)
The basic initialization function is :c:func:`Py_Initialize`. This initializes
the table of loaded modules, and creates the fundamental modules
:mod:`__builtin__`, :mod:`__main__`, :mod:`sys`, and :mod:`exceptions`. It also
initializes the module search path (``sys.path``).
.. index:: single: PySys_SetArgvEx()
:c:func:`Py_Initialize` does not set the "script argument list" (``sys.argv``).
If this variable is needed by Python code that will be executed later, it must
be set explicitly with a call to ``PySys_SetArgvEx(argc, argv, updatepath)``
after the call to :c:func:`Py_Initialize`.
On most systems (in particular, on Unix and Windows, although the details are
slightly different), :c:func:`Py_Initialize` calculates the module search path
based upon its best guess for the location of the standard Python interpreter
executable, assuming that the Python library is found in a fixed location
relative to the Python interpreter executable. In particular, it looks for a
directory named :file:`lib/python{X.Y}` relative to the parent directory
where the executable named :file:`python` is found on the shell command search
path (the environment variable :envvar:`PATH`).
For instance, if the Python executable is found in
:file:`/usr/local/bin/python`, it will assume that the libraries are in
:file:`/usr/local/lib/python{X.Y}`. (In fact, this particular path is also
the "fallback" location, used when no executable file named :file:`python` is
found along :envvar:`PATH`.) The user can override this behavior by setting the
environment variable :envvar:`PYTHONHOME`, or insert additional directories in
front of the standard path by setting :envvar:`PYTHONPATH`.
.. index::
single: Py_SetProgramName()
single: Py_GetPath()
single: Py_GetPrefix()
single: Py_GetExecPrefix()
single: Py_GetProgramFullPath()
The embedding application can steer the search by calling
``Py_SetProgramName(file)`` *before* calling :c:func:`Py_Initialize`. Note that
:envvar:`PYTHONHOME` still overrides this and :envvar:`PYTHONPATH` is still
inserted in front of the standard path. An application that requires total
control has to provide its own implementation of :c:func:`Py_GetPath`,
:c:func:`Py_GetPrefix`, :c:func:`Py_GetExecPrefix`, and
:c:func:`Py_GetProgramFullPath` (all defined in :file:`Modules/getpath.c`).
.. index:: single: Py_IsInitialized()
Sometimes, it is desirable to "uninitialize" Python. For instance, the
application may want to start over (make another call to
:c:func:`Py_Initialize`) or the application is simply done with its use of
Python and wants to free memory allocated by Python. This can be accomplished
by calling :c:func:`Py_Finalize`. The function :c:func:`Py_IsInitialized` returns
true if Python is currently in the initialized state. More information about
these functions is given in a later chapter. Notice that :c:func:`Py_Finalize`
does *not* free all memory allocated by the Python interpreter, e.g. memory
allocated by extension modules currently cannot be released.
.. _api-debugging:
Debugging Builds
================
Python can be built with several macros to enable extra checks of the
interpreter and extension modules. These checks tend to add a large amount of
overhead to the runtime so they are not enabled by default.
A full list of the various types of debugging builds is in the file
:file:`Misc/SpecialBuilds.txt` in the Python source distribution. Builds are
available that support tracing of reference counts, debugging the memory
allocator, or low-level profiling of the main interpreter loop. Only the most
frequently-used builds will be described in the remainder of this section.
Compiling the interpreter with the :c:macro:`Py_DEBUG` macro defined produces
what is generally meant by "a debug build" of Python. :c:macro:`Py_DEBUG` is
enabled in the Unix build by adding ``--with-pydebug`` to the
:file:`./configure` command. It is also implied by the presence of the
not-Python-specific :c:macro:`_DEBUG` macro. When :c:macro:`Py_DEBUG` is enabled
in the Unix build, compiler optimization is disabled.
In addition to the reference count debugging described below, the following
extra checks are performed:
* Extra checks are added to the object allocator.
* Extra checks are added to the parser and compiler.
* Downcasts from wide types to narrow types are checked for loss of information.
* A number of assertions are added to the dictionary and set implementations.
In addition, the set object acquires a :meth:`test_c_api` method.
* Sanity checks of the input arguments are added to frame creation.
* The storage for long ints is initialized with a known invalid pattern to catch
reference to uninitialized digits.
* Low-level tracing and extra exception checking are added to the runtime
virtual machine.
* Extra checks are added to the memory arena implementation.
* Extra debugging is added to the thread module.
There may be additional checks not mentioned here.
Defining :c:macro:`Py_TRACE_REFS` enables reference tracing. When defined, a
circular doubly linked list of active objects is maintained by adding two extra
fields to every :c:type:`PyObject`. Total allocations are tracked as well. Upon
exit, all existing references are printed. (In interactive mode this happens
after every statement run by the interpreter.) Implied by :c:macro:`Py_DEBUG`.
Please refer to :file:`Misc/SpecialBuilds.txt` in the Python source distribution
for more detailed information.

53
Doc/c-api/iter.rst Normal file
View File

@@ -0,0 +1,53 @@
.. highlightlang:: c
.. _iterator:
Iterator Protocol
=================
.. versionadded:: 2.2
There are two functions specifically for working with iterators.
.. c:function:: int PyIter_Check(PyObject *o)
Return true if the object *o* supports the iterator protocol.
This function can return a false positive in the case of old-style
classes because those classes always define a :c:member:`tp_iternext`
slot with logic that either invokes a :meth:`next` method or raises
a :exc:`TypeError`.
.. c:function:: PyObject* PyIter_Next(PyObject *o)
Return the next value from the iteration *o*. The object must be an iterator
(it is up to the caller to check this). If there are no remaining values,
returns *NULL* with no exception set. If an error occurs while retrieving
the item, returns *NULL* and passes along the exception.
To write a loop which iterates over an iterator, the C code should look
something like this::
PyObject *iterator = PyObject_GetIter(obj);
PyObject *item;
if (iterator == NULL) {
/* propagate error */
}
while ((item = PyIter_Next(iterator))) {
/* do something with item */
...
/* release reference when done */
Py_DECREF(item);
}
Py_DECREF(iterator);
if (PyErr_Occurred()) {
/* propagate error */
}
else {
/* continue doing useful work */
}

62
Doc/c-api/iterator.rst Normal file
View File

@@ -0,0 +1,62 @@
.. highlightlang:: c
.. _iterator-objects:
Iterator Objects
----------------
Python provides two general-purpose iterator objects. The first, a sequence
iterator, works with an arbitrary sequence supporting the :meth:`__getitem__`
method. The second works with a callable object and a sentinel value, calling
the callable for each item in the sequence, and ending the iteration when the
sentinel value is returned.
.. c:var:: PyTypeObject PySeqIter_Type
Type object for iterator objects returned by :c:func:`PySeqIter_New` and the
one-argument form of the :func:`iter` built-in function for built-in sequence
types.
.. versionadded:: 2.2
.. c:function:: int PySeqIter_Check(op)
Return true if the type of *op* is :c:data:`PySeqIter_Type`.
.. versionadded:: 2.2
.. c:function:: PyObject* PySeqIter_New(PyObject *seq)
Return an iterator that works with a general sequence object, *seq*. The
iteration ends when the sequence raises :exc:`IndexError` for the subscripting
operation.
.. versionadded:: 2.2
.. c:var:: PyTypeObject PyCallIter_Type
Type object for iterator objects returned by :c:func:`PyCallIter_New` and the
two-argument form of the :func:`iter` built-in function.
.. versionadded:: 2.2
.. c:function:: int PyCallIter_Check(op)
Return true if the type of *op* is :c:data:`PyCallIter_Type`.
.. versionadded:: 2.2
.. c:function:: PyObject* PyCallIter_New(PyObject *callable, PyObject *sentinel)
Return a new iterator. The first parameter, *callable*, can be any Python
callable object that can be called with no parameters; each call to it should
return the next item in the iteration. When *callable* returns a value equal to
*sentinel*, the iteration will be terminated.
.. versionadded:: 2.2

189
Doc/c-api/list.rst Normal file
View File

@@ -0,0 +1,189 @@
.. highlightlang:: c
.. _listobjects:
List Objects
------------
.. index:: object: list
.. c:type:: PyListObject
This subtype of :c:type:`PyObject` represents a Python list object.
.. c:var:: PyTypeObject PyList_Type
This instance of :c:type:`PyTypeObject` represents the Python list type. This
is the same object as ``list`` in the Python layer.
.. c:function:: int PyList_Check(PyObject *p)
Return true if *p* is a list object or an instance of a subtype of the list
type.
.. versionchanged:: 2.2
Allowed subtypes to be accepted.
.. c:function:: int PyList_CheckExact(PyObject *p)
Return true if *p* is a list object, but not an instance of a subtype of
the list type.
.. versionadded:: 2.2
.. c:function:: PyObject* PyList_New(Py_ssize_t len)
Return a new list of length *len* on success, or *NULL* on failure.
.. note::
If *len* is greater than zero, the returned list object's items are
set to ``NULL``. Thus you cannot use abstract API functions such as
:c:func:`PySequence_SetItem` or expose the object to Python code before
setting all items to a real object with :c:func:`PyList_SetItem`.
.. versionchanged:: 2.5
This function used an :c:type:`int` for *size*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: Py_ssize_t PyList_Size(PyObject *list)
.. index:: builtin: len
Return the length of the list object in *list*; this is equivalent to
``len(list)`` on a list object.
.. versionchanged:: 2.5
This function returned an :c:type:`int`. This might require changes in
your code for properly supporting 64-bit systems.
.. c:function:: Py_ssize_t PyList_GET_SIZE(PyObject *list)
Macro form of :c:func:`PyList_Size` without error checking.
.. versionchanged:: 2.5
This macro returned an :c:type:`int`. This might require changes in your
code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyList_GetItem(PyObject *list, Py_ssize_t index)
Return the object at position *index* in the list pointed to by *list*. The
position must be non-negative; indexing from the end of the list is not
supported. If *index* is out of bounds (<0 or >=len(list)),
return *NULL* and set an :exc:`IndexError` exception.
.. versionchanged:: 2.5
This function used an :c:type:`int` for *index*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyList_GET_ITEM(PyObject *list, Py_ssize_t i)
Macro form of :c:func:`PyList_GetItem` without error checking.
.. versionchanged:: 2.5
This macro used an :c:type:`int` for *i*. This might require changes in
your code for properly supporting 64-bit systems.
.. c:function:: int PyList_SetItem(PyObject *list, Py_ssize_t index, PyObject *item)
Set the item at index *index* in list to *item*. Return ``0`` on success.
If *index* is out of bounds, return ``-1`` and set an :exc:`IndexError`
exception.
.. note::
This function "steals" a reference to *item* and discards a reference to
an item already in the list at the affected position.
.. versionchanged:: 2.5
This function used an :c:type:`int` for *index*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: void PyList_SET_ITEM(PyObject *list, Py_ssize_t i, PyObject *o)
Macro form of :c:func:`PyList_SetItem` without error checking. This is
normally only used to fill in new lists where there is no previous content.
.. note::
This macro "steals" a reference to *item*, and, unlike
:c:func:`PyList_SetItem`, does *not* discard a reference to any item that
it being replaced; any reference in *list* at position *i* will be
leaked.
.. versionchanged:: 2.5
This macro used an :c:type:`int` for *i*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: int PyList_Insert(PyObject *list, Py_ssize_t index, PyObject *item)
Insert the item *item* into list *list* in front of index *index*. Return
``0`` if successful; return ``-1`` and set an exception if unsuccessful.
Analogous to ``list.insert(index, item)``.
.. versionchanged:: 2.5
This function used an :c:type:`int` for *index*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: int PyList_Append(PyObject *list, PyObject *item)
Append the object *item* at the end of list *list*. Return ``0`` if
successful; return ``-1`` and set an exception if unsuccessful. Analogous
to ``list.append(item)``.
.. c:function:: PyObject* PyList_GetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high)
Return a list of the objects in *list* containing the objects *between* *low*
and *high*. Return *NULL* and set an exception if unsuccessful. Analogous
to ``list[low:high]``. Indexing from the end of the list is not supported.
.. versionchanged:: 2.5
This function used an :c:type:`int` for *low* and *high*. This might
require changes in your code for properly supporting 64-bit systems.
.. c:function:: int PyList_SetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist)
Set the slice of *list* between *low* and *high* to the contents of
*itemlist*. Analogous to ``list[low:high] = itemlist``. The *itemlist* may
be *NULL*, indicating the assignment of an empty list (slice deletion).
Return ``0`` on success, ``-1`` on failure. Indexing from the end of the
list is not supported.
.. versionchanged:: 2.5
This function used an :c:type:`int` for *low* and *high*. This might
require changes in your code for properly supporting 64-bit systems.
.. c:function:: int PyList_Sort(PyObject *list)
Sort the items of *list* in place. Return ``0`` on success, ``-1`` on
failure. This is equivalent to ``list.sort()``.
.. c:function:: int PyList_Reverse(PyObject *list)
Reverse the items of *list* in place. Return ``0`` on success, ``-1`` on
failure. This is the equivalent of ``list.reverse()``.
.. c:function:: PyObject* PyList_AsTuple(PyObject *list)
.. index:: builtin: tuple
Return a new tuple object containing the contents of *list*; equivalent to
``tuple(list)``.

256
Doc/c-api/long.rst Normal file
View File

@@ -0,0 +1,256 @@
.. highlightlang:: c
.. _longobjects:
Long Integer Objects
--------------------
.. index:: object: long integer
.. c:type:: PyLongObject
This subtype of :c:type:`PyObject` represents a Python long integer object.
.. c:var:: PyTypeObject PyLong_Type
.. index:: single: LongType (in modules types)
This instance of :c:type:`PyTypeObject` represents the Python long integer type.
This is the same object as ``long`` and ``types.LongType``.
.. c:function:: int PyLong_Check(PyObject *p)
Return true if its argument is a :c:type:`PyLongObject` or a subtype of
:c:type:`PyLongObject`.
.. versionchanged:: 2.2
Allowed subtypes to be accepted.
.. c:function:: int PyLong_CheckExact(PyObject *p)
Return true if its argument is a :c:type:`PyLongObject`, but not a subtype of
:c:type:`PyLongObject`.
.. versionadded:: 2.2
.. c:function:: PyObject* PyLong_FromLong(long v)
Return a new :c:type:`PyLongObject` object from *v*, or *NULL* on failure.
.. c:function:: PyObject* PyLong_FromUnsignedLong(unsigned long v)
Return a new :c:type:`PyLongObject` object from a C :c:type:`unsigned long`, or
*NULL* on failure.
.. c:function:: PyObject* PyLong_FromSsize_t(Py_ssize_t v)
Return a new :c:type:`PyLongObject` object from a C :c:type:`Py_ssize_t`, or
*NULL* on failure.
.. versionadded:: 2.6
.. c:function:: PyObject* PyLong_FromSize_t(size_t v)
Return a new :c:type:`PyLongObject` object from a C :c:type:`size_t`, or
*NULL* on failure.
.. versionadded:: 2.6
.. c:function:: PyObject* PyLong_FromLongLong(PY_LONG_LONG v)
Return a new :c:type:`PyLongObject` object from a C :c:type:`long long`, or *NULL*
on failure.
.. c:function:: PyObject* PyLong_FromUnsignedLongLong(unsigned PY_LONG_LONG v)
Return a new :c:type:`PyLongObject` object from a C :c:type:`unsigned long long`,
or *NULL* on failure.
.. c:function:: PyObject* PyLong_FromDouble(double v)
Return a new :c:type:`PyLongObject` object from the integer part of *v*, or
*NULL* on failure.
.. c:function:: PyObject* PyLong_FromString(char *str, char **pend, int base)
Return a new :c:type:`PyLongObject` based on the string value in *str*, which is
interpreted according to the radix in *base*. If *pend* is non-*NULL*,
*\*pend* will point to the first character in *str* which follows the
representation of the number. If *base* is ``0``, the radix will be determined
based on the leading characters of *str*: if *str* starts with ``'0x'`` or
``'0X'``, radix 16 will be used; if *str* starts with ``'0'``, radix 8 will be
used; otherwise radix 10 will be used. If *base* is not ``0``, it must be
between ``2`` and ``36``, inclusive. Leading spaces are ignored. If there are
no digits, :exc:`ValueError` will be raised.
.. c:function:: PyObject* PyLong_FromUnicode(Py_UNICODE *u, Py_ssize_t length, int base)
Convert a sequence of Unicode digits to a Python long integer value. The first
parameter, *u*, points to the first character of the Unicode string, *length*
gives the number of characters, and *base* is the radix for the conversion. The
radix must be in the range [2, 36]; if it is out of range, :exc:`ValueError`
will be raised.
.. versionadded:: 1.6
.. versionchanged:: 2.5
This function used an :c:type:`int` for *length*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyLong_FromVoidPtr(void *p)
Create a Python integer or long integer from the pointer *p*. The pointer value
can be retrieved from the resulting value using :c:func:`PyLong_AsVoidPtr`.
.. versionadded:: 1.5.2
.. versionchanged:: 2.5
If the integer is larger than LONG_MAX, a positive long integer is returned.
.. c:function:: long PyLong_AsLong(PyObject *pylong)
.. index::
single: LONG_MAX
single: OverflowError (built-in exception)
Return a C :c:type:`long` representation of the contents of *pylong*. If
*pylong* is greater than :const:`LONG_MAX`, an :exc:`OverflowError` is raised
and ``-1`` will be returned.
.. c:function:: long PyLong_AsLongAndOverflow(PyObject *pylong, int *overflow)
Return a C :c:type:`long` representation of the contents of
*pylong*. If *pylong* is greater than :const:`LONG_MAX` or less
than :const:`LONG_MIN`, set *\*overflow* to ``1`` or ``-1``,
respectively, and return ``-1``; otherwise, set *\*overflow* to
``0``. If any other exception occurs (for example a TypeError or
MemoryError), then ``-1`` will be returned and *\*overflow* will
be ``0``.
.. versionadded:: 2.7
.. c:function:: PY_LONG_LONG PyLong_AsLongLongAndOverflow(PyObject *pylong, int *overflow)
Return a C :c:type:`long long` representation of the contents of
*pylong*. If *pylong* is greater than :const:`PY_LLONG_MAX` or less
than :const:`PY_LLONG_MIN`, set *\*overflow* to ``1`` or ``-1``,
respectively, and return ``-1``; otherwise, set *\*overflow* to
``0``. If any other exception occurs (for example a TypeError or
MemoryError), then ``-1`` will be returned and *\*overflow* will
be ``0``.
.. versionadded:: 2.7
.. c:function:: Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)
.. index::
single: PY_SSIZE_T_MAX
single: OverflowError (built-in exception)
Return a C :c:type:`Py_ssize_t` representation of the contents of *pylong*. If
*pylong* is greater than :const:`PY_SSIZE_T_MAX`, an :exc:`OverflowError` is raised
and ``-1`` will be returned.
.. versionadded:: 2.6
.. c:function:: unsigned long PyLong_AsUnsignedLong(PyObject *pylong)
.. index::
single: ULONG_MAX
single: OverflowError (built-in exception)
Return a C :c:type:`unsigned long` representation of the contents of *pylong*.
If *pylong* is greater than :const:`ULONG_MAX`, an :exc:`OverflowError` is
raised.
.. c:function:: PY_LONG_LONG PyLong_AsLongLong(PyObject *pylong)
.. index::
single: OverflowError (built-in exception)
Return a C :c:type:`long long` from a Python long integer. If
*pylong* cannot be represented as a :c:type:`long long`, an
:exc:`OverflowError` is raised and ``-1`` is returned.
.. versionadded:: 2.2
.. c:function:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLong(PyObject *pylong)
.. index::
single: OverflowError (built-in exception)
Return a C :c:type:`unsigned long long` from a Python long integer. If
*pylong* cannot be represented as an :c:type:`unsigned long long`, an
:exc:`OverflowError` is raised and ``(unsigned long long)-1`` is
returned.
.. versionadded:: 2.2
.. versionchanged:: 2.7
A negative *pylong* now raises :exc:`OverflowError`, not
:exc:`TypeError`.
.. c:function:: unsigned long PyLong_AsUnsignedLongMask(PyObject *io)
Return a C :c:type:`unsigned long` from a Python long integer, without checking
for overflow.
Returns ``(unsigned long)-1`` on error. Use :c:func:`PyErr_Occurred` to
disambiguate.
.. versionadded:: 2.3
.. c:function:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLongMask(PyObject *io)
Return a C :c:type:`unsigned long long` from a Python long integer, without
checking for overflow.
Returns ``(unsigned PY_LONG_LONG)-1`` on error. Use
:c:func:`PyErr_Occurred` to disambiguate.
.. versionadded:: 2.3
.. c:function:: double PyLong_AsDouble(PyObject *pylong)
Return a C :c:type:`double` representation of the contents of *pylong*. If
*pylong* cannot be approximately represented as a :c:type:`double`, an
:exc:`OverflowError` exception is raised and ``-1.0`` will be returned.
.. c:function:: void* PyLong_AsVoidPtr(PyObject *pylong)
Convert a Python integer or long integer *pylong* to a C :c:type:`void` pointer.
If *pylong* cannot be converted, an :exc:`OverflowError` will be raised. This
is only assured to produce a usable :c:type:`void` pointer for values created
with :c:func:`PyLong_FromVoidPtr`.
.. versionadded:: 1.5.2
.. versionchanged:: 2.5
For values outside 0..LONG_MAX, both signed and unsigned integers are accepted.

83
Doc/c-api/mapping.rst Normal file
View File

@@ -0,0 +1,83 @@
.. highlightlang:: c
.. _mapping:
Mapping Protocol
================
.. c:function:: int PyMapping_Check(PyObject *o)
Return ``1`` if the object provides mapping protocol, and ``0`` otherwise. This
function always succeeds.
.. c:function:: Py_ssize_t PyMapping_Size(PyObject *o)
Py_ssize_t PyMapping_Length(PyObject *o)
.. index:: builtin: len
Returns the number of keys in object *o* on success, and ``-1`` on failure. For
objects that do not provide mapping protocol, this is equivalent to the Python
expression ``len(o)``.
.. versionchanged:: 2.5
These functions returned an :c:type:`int` type. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: int PyMapping_DelItemString(PyObject *o, char *key)
Remove the mapping for object *key* from the object *o*. Return ``-1`` on
failure. This is equivalent to the Python statement ``del o[key]``.
.. c:function:: int PyMapping_DelItem(PyObject *o, PyObject *key)
Remove the mapping for object *key* from the object *o*. Return ``-1`` on
failure. This is equivalent to the Python statement ``del o[key]``.
.. c:function:: int PyMapping_HasKeyString(PyObject *o, char *key)
On success, return ``1`` if the mapping object has the key *key* and ``0``
otherwise. This is equivalent to ``o[key]``, returning ``True`` on success
and ``False`` on an exception. This function always succeeds.
.. c:function:: int PyMapping_HasKey(PyObject *o, PyObject *key)
Return ``1`` if the mapping object has the key *key* and ``0`` otherwise.
This is equivalent to ``o[key]``, returning ``True`` on success and ``False``
on an exception. This function always succeeds.
.. c:function:: PyObject* PyMapping_Keys(PyObject *o)
On success, return a list of the keys in object *o*. On failure, return *NULL*.
This is equivalent to the Python expression ``o.keys()``.
.. c:function:: PyObject* PyMapping_Values(PyObject *o)
On success, return a list of the values in object *o*. On failure, return
*NULL*. This is equivalent to the Python expression ``o.values()``.
.. c:function:: PyObject* PyMapping_Items(PyObject *o)
On success, return a list of the items in object *o*, where each item is a tuple
containing a key-value pair. On failure, return *NULL*. This is equivalent to
the Python expression ``o.items()``.
.. c:function:: PyObject* PyMapping_GetItemString(PyObject *o, char *key)
Return element of *o* corresponding to the object *key* or *NULL* on failure.
This is the equivalent of the Python expression ``o[key]``.
.. c:function:: int PyMapping_SetItemString(PyObject *o, char *key, PyObject *v)
Map the object *key* to the value *v* in object *o*. Returns ``-1`` on failure.
This is the equivalent of the Python statement ``o[key] = v``.

100
Doc/c-api/marshal.rst Normal file
View File

@@ -0,0 +1,100 @@
.. highlightlang:: c
.. _marshalling-utils:
Data marshalling support
========================
These routines allow C code to work with serialized objects using the same
data format as the :mod:`marshal` module. There are functions to write data
into the serialization format, and additional functions that can be used to
read the data back. Files used to store marshalled data must be opened in
binary mode.
Numeric values are stored with the least significant byte first.
The module supports two versions of the data format: version ``0`` is the
historical version, version ``1`` (new in Python 2.4) shares interned strings in
the file, and upon unmarshalling. Version 2 (new in Python 2.5) uses a binary
format for floating point numbers. *Py_MARSHAL_VERSION* indicates the current
file format (currently 2).
.. c:function:: void PyMarshal_WriteLongToFile(long value, FILE *file, int version)
Marshal a :c:type:`long` integer, *value*, to *file*. This will only write
the least-significant 32 bits of *value*; regardless of the size of the
native :c:type:`long` type.
.. versionchanged:: 2.4
*version* indicates the file format.
.. c:function:: void PyMarshal_WriteObjectToFile(PyObject *value, FILE *file, int version)
Marshal a Python object, *value*, to *file*.
.. versionchanged:: 2.4
*version* indicates the file format.
.. c:function:: PyObject* PyMarshal_WriteObjectToString(PyObject *value, int version)
Return a string object containing the marshalled representation of *value*.
.. versionchanged:: 2.4
*version* indicates the file format.
The following functions allow marshalled values to be read back in.
XXX What about error detection? It appears that reading past the end of the
file will always result in a negative numeric value (where that's relevant),
but it's not clear that negative values won't be handled properly when there's
no error. What's the right way to tell? Should only non-negative values be
written using these routines?
.. c:function:: long PyMarshal_ReadLongFromFile(FILE *file)
Return a C :c:type:`long` from the data stream in a :c:type:`FILE\*` opened
for reading. Only a 32-bit value can be read in using this function,
regardless of the native size of :c:type:`long`.
.. c:function:: int PyMarshal_ReadShortFromFile(FILE *file)
Return a C :c:type:`short` from the data stream in a :c:type:`FILE\*` opened
for reading. Only a 16-bit value can be read in using this function,
regardless of the native size of :c:type:`short`.
.. c:function:: PyObject* PyMarshal_ReadObjectFromFile(FILE *file)
Return a Python object from the data stream in a :c:type:`FILE\*` opened for
reading. On error, sets the appropriate exception (:exc:`EOFError` or
:exc:`TypeError`) and returns *NULL*.
.. c:function:: PyObject* PyMarshal_ReadLastObjectFromFile(FILE *file)
Return a Python object from the data stream in a :c:type:`FILE\*` opened for
reading. Unlike :c:func:`PyMarshal_ReadObjectFromFile`, this function
assumes that no further objects will be read from the file, allowing it to
aggressively load file data into memory so that the de-serialization can
operate from data in memory rather than reading a byte at a time from the
file. Only use these variant if you are certain that you won't be reading
anything else from the file. On error, sets the appropriate exception
(:exc:`EOFError` or :exc:`TypeError`) and returns *NULL*.
.. c:function:: PyObject* PyMarshal_ReadObjectFromString(char *string, Py_ssize_t len)
Return a Python object from the data stream in a character buffer
containing *len* bytes pointed to by *string*. On error, sets the
appropriate exception (:exc:`EOFError` or :exc:`TypeError`) and returns
*NULL*.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *len*. This might require
changes in your code for properly supporting 64-bit systems.

291
Doc/c-api/memory.rst Normal file
View File

@@ -0,0 +1,291 @@
.. highlightlang:: c
.. _memory:
*****************
Memory Management
*****************
.. sectionauthor:: Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>
.. _memoryoverview:
Overview
========
Memory management in Python involves a private heap containing all Python
objects and data structures. The management of this private heap is ensured
internally by the *Python memory manager*. The Python memory manager has
different components which deal with various dynamic storage management aspects,
like sharing, segmentation, preallocation or caching.
At the lowest level, a raw memory allocator ensures that there is enough room in
the private heap for storing all Python-related data by interacting with the
memory manager of the operating system. On top of the raw memory allocator,
several object-specific allocators operate on the same heap and implement
distinct memory management policies adapted to the peculiarities of every object
type. For example, integer objects are managed differently within the heap than
strings, tuples or dictionaries because integers imply different storage
requirements and speed/space tradeoffs. The Python memory manager thus delegates
some of the work to the object-specific allocators, but ensures that the latter
operate within the bounds of the private heap.
It is important to understand that the management of the Python heap is
performed by the interpreter itself and that the user has no control over it,
even if they regularly manipulate object pointers to memory blocks inside that
heap. The allocation of heap space for Python objects and other internal
buffers is performed on demand by the Python memory manager through the Python/C
API functions listed in this document.
.. index::
single: malloc()
single: calloc()
single: realloc()
single: free()
To avoid memory corruption, extension writers should never try to operate on
Python objects with the functions exported by the C library: :c:func:`malloc`,
:c:func:`calloc`, :c:func:`realloc` and :c:func:`free`. This will result in mixed
calls between the C allocator and the Python memory manager with fatal
consequences, because they implement different algorithms and operate on
different heaps. However, one may safely allocate and release memory blocks
with the C library allocator for individual purposes, as shown in the following
example::
PyObject *res;
char *buf = (char *) malloc(BUFSIZ); /* for I/O */
if (buf == NULL)
return PyErr_NoMemory();
...Do some I/O operation involving buf...
res = PyString_FromString(buf);
free(buf); /* malloc'ed */
return res;
In this example, the memory request for the I/O buffer is handled by the C
library allocator. The Python memory manager is involved only in the allocation
of the string object returned as a result.
In most situations, however, it is recommended to allocate memory from the
Python heap specifically because the latter is under control of the Python
memory manager. For example, this is required when the interpreter is extended
with new object types written in C. Another reason for using the Python heap is
the desire to *inform* the Python memory manager about the memory needs of the
extension module. Even when the requested memory is used exclusively for
internal, highly-specific purposes, delegating all memory requests to the Python
memory manager causes the interpreter to have a more accurate image of its
memory footprint as a whole. Consequently, under certain circumstances, the
Python memory manager may or may not trigger appropriate actions, like garbage
collection, memory compaction or other preventive procedures. Note that by using
the C library allocator as shown in the previous example, the allocated memory
for the I/O buffer escapes completely the Python memory manager.
.. _memoryinterface:
Memory Interface
================
The following function sets, modeled after the ANSI C standard, but specifying
behavior when requesting zero bytes, are available for allocating and releasing
memory from the Python heap:
.. c:function:: void* PyMem_Malloc(size_t n)
Allocates *n* bytes and returns a pointer of type :c:type:`void\*` to the
allocated memory, or *NULL* if the request fails. Requesting zero bytes returns
a distinct non-*NULL* pointer if possible, as if ``PyMem_Malloc(1)`` had
been called instead. The memory will not have been initialized in any way.
.. c:function:: void* PyMem_Realloc(void *p, size_t n)
Resizes the memory block pointed to by *p* to *n* bytes. The contents will be
unchanged to the minimum of the old and the new sizes. If *p* is *NULL*, the
call is equivalent to ``PyMem_Malloc(n)``; else if *n* is equal to zero,
the memory block is resized but is not freed, and the returned pointer is
non-*NULL*. Unless *p* is *NULL*, it must have been returned by a previous call
to :c:func:`PyMem_Malloc` or :c:func:`PyMem_Realloc`. If the request fails,
:c:func:`PyMem_Realloc` returns *NULL* and *p* remains a valid pointer to the
previous memory area.
.. c:function:: void PyMem_Free(void *p)
Frees the memory block pointed to by *p*, which must have been returned by a
previous call to :c:func:`PyMem_Malloc` or :c:func:`PyMem_Realloc`. Otherwise, or
if ``PyMem_Free(p)`` has been called before, undefined behavior occurs. If
*p* is *NULL*, no operation is performed.
The following type-oriented macros are provided for convenience. Note that
*TYPE* refers to any C type.
.. c:function:: TYPE* PyMem_New(TYPE, size_t n)
Same as :c:func:`PyMem_Malloc`, but allocates ``(n * sizeof(TYPE))`` bytes of
memory. Returns a pointer cast to :c:type:`TYPE\*`. The memory will not have
been initialized in any way.
.. c:function:: TYPE* PyMem_Resize(void *p, TYPE, size_t n)
Same as :c:func:`PyMem_Realloc`, but the memory block is resized to ``(n *
sizeof(TYPE))`` bytes. Returns a pointer cast to :c:type:`TYPE\*`. On return,
*p* will be a pointer to the new memory area, or *NULL* in the event of
failure. This is a C preprocessor macro; p is always reassigned. Save
the original value of p to avoid losing memory when handling errors.
.. c:function:: void PyMem_Del(void *p)
Same as :c:func:`PyMem_Free`.
In addition, the following macro sets are provided for calling the Python memory
allocator directly, without involving the C API functions listed above. However,
note that their use does not preserve binary compatibility across Python
versions and is therefore deprecated in extension modules.
:c:func:`PyMem_MALLOC`, :c:func:`PyMem_REALLOC`, :c:func:`PyMem_FREE`.
:c:func:`PyMem_NEW`, :c:func:`PyMem_RESIZE`, :c:func:`PyMem_DEL`.
Object allocators
=================
The following function sets, modeled after the ANSI C standard, but specifying
behavior when requesting zero bytes, are available for allocating and releasing
memory from the Python heap.
By default, these functions use :ref:`pymalloc memory allocator <pymalloc>`.
.. warning::
The :term:`GIL <global interpreter lock>` must be held when using these
functions.
.. c:function:: void* PyObject_Malloc(size_t n)
Allocates *n* bytes and returns a pointer of type :c:type:`void\*` to the
allocated memory, or *NULL* if the request fails.
Requesting zero bytes returns a distinct non-*NULL* pointer if possible, as
if ``PyObject_Malloc(1)`` had been called instead. The memory will not have
been initialized in any way.
.. c:function:: void* PyObject_Realloc(void *p, size_t n)
Resizes the memory block pointed to by *p* to *n* bytes. The contents will be
unchanged to the minimum of the old and the new sizes.
If *p* is *NULL*, the call is equivalent to ``PyObject_Malloc(n)``; else if *n*
is equal to zero, the memory block is resized but is not freed, and the
returned pointer is non-*NULL*.
Unless *p* is *NULL*, it must have been returned by a previous call to
:c:func:`PyObject_Malloc`, :c:func:`PyObject_Realloc` or :c:func:`PyObject_Calloc`.
If the request fails, :c:func:`PyObject_Realloc` returns *NULL* and *p* remains
a valid pointer to the previous memory area.
.. c:function:: void PyObject_Free(void *p)
Frees the memory block pointed to by *p*, which must have been returned by a
previous call to :c:func:`PyObject_Malloc`, :c:func:`PyObject_Realloc` or
:c:func:`PyObject_Calloc`. Otherwise, or if ``PyObject_Free(p)`` has been called
before, undefined behavior occurs.
If *p* is *NULL*, no operation is performed.
In addition, the following macro sets are provided:
* :c:func:`PyObject_MALLOC`: alias to :c:func:`PyObject_Malloc`
* :c:func:`PyObject_REALLOC`: alias to :c:func:`PyObject_Realloc`
* :c:func:`PyObject_FREE`: alias to :c:func:`PyObject_Free`
* :c:func:`PyObject_Del`: alias to :c:func:`PyObject_Free`
* :c:func:`PyObject_DEL`: alias to :c:func:`PyObject_FREE` (so finally an alias
to :c:func:`PyObject_Free`)
.. _pymalloc:
The pymalloc allocator
======================
Python has a *pymalloc* allocator optimized for small objects (smaller or equal
to 512 bytes) with a short lifetime. It uses memory mappings called "arenas"
with a fixed size of 256 KiB. It falls back to :c:func:`malloc` and
:c:func:`realloc` for allocations larger than 512 bytes.
*pymalloc* is the default allocator of :c:func:`PyObject_Malloc`.
The arena allocator uses the following functions:
* :c:func:`mmap` and :c:func:`munmap` if available,
* :c:func:`malloc` and :c:func:`free` otherwise.
.. versionchanged:: 2.7.7
The threshold changed from 256 to 512 bytes. The arena allocator now
uses :c:func:`mmap` if available.
.. _memoryexamples:
Examples
========
Here is the example from section :ref:`memoryoverview`, rewritten so that the
I/O buffer is allocated from the Python heap by using the first function set::
PyObject *res;
char *buf = (char *) PyMem_Malloc(BUFSIZ); /* for I/O */
if (buf == NULL)
return PyErr_NoMemory();
/* ...Do some I/O operation involving buf... */
res = PyString_FromString(buf);
PyMem_Free(buf); /* allocated with PyMem_Malloc */
return res;
The same code using the type-oriented function set::
PyObject *res;
char *buf = PyMem_New(char, BUFSIZ); /* for I/O */
if (buf == NULL)
return PyErr_NoMemory();
/* ...Do some I/O operation involving buf... */
res = PyString_FromString(buf);
PyMem_Del(buf); /* allocated with PyMem_New */
return res;
Note that in the two examples above, the buffer is always manipulated via
functions belonging to the same set. Indeed, it is required to use the same
memory API family for a given memory block, so that the risk of mixing different
allocators is reduced to a minimum. The following code sequence contains two
errors, one of which is labeled as *fatal* because it mixes two different
allocators operating on different heaps. ::
char *buf1 = PyMem_New(char, BUFSIZ);
char *buf2 = (char *) malloc(BUFSIZ);
char *buf3 = (char *) PyMem_Malloc(BUFSIZ);
...
PyMem_Del(buf3); /* Wrong -- should be PyMem_Free() */
free(buf2); /* Right -- allocated via malloc() */
free(buf1); /* Fatal -- should be PyMem_Del() */
In addition to the functions aimed at handling raw memory blocks from the Python
heap, objects in Python are allocated and released with :c:func:`PyObject_New`,
:c:func:`PyObject_NewVar` and :c:func:`PyObject_Del`.
These will be explained in the next chapter on defining and implementing new
object types in C.

72
Doc/c-api/method.rst Normal file
View File

@@ -0,0 +1,72 @@
.. highlightlang:: c
.. _method-objects:
Method Objects
--------------
.. index:: object: method
There are some useful functions that are useful for working with method objects.
.. c:var:: PyTypeObject PyMethod_Type
.. index:: single: MethodType (in module types)
This instance of :c:type:`PyTypeObject` represents the Python method type. This
is exposed to Python programs as ``types.MethodType``.
.. c:function:: int PyMethod_Check(PyObject *o)
Return true if *o* is a method object (has type :c:data:`PyMethod_Type`). The
parameter must not be *NULL*.
.. c:function:: PyObject* PyMethod_New(PyObject *func, PyObject *self, PyObject *class)
Return a new method object, with *func* being any callable object; this is the
function that will be called when the method is called. If this method should
be bound to an instance, *self* should be the instance and *class* should be the
class of *self*, otherwise *self* should be *NULL* and *class* should be the
class which provides the unbound method..
.. c:function:: PyObject* PyMethod_Class(PyObject *meth)
Return the class object from which the method *meth* was created; if this was
created from an instance, it will be the class of the instance.
.. c:function:: PyObject* PyMethod_GET_CLASS(PyObject *meth)
Macro version of :c:func:`PyMethod_Class` which avoids error checking.
.. c:function:: PyObject* PyMethod_Function(PyObject *meth)
Return the function object associated with the method *meth*.
.. c:function:: PyObject* PyMethod_GET_FUNCTION(PyObject *meth)
Macro version of :c:func:`PyMethod_Function` which avoids error checking.
.. c:function:: PyObject* PyMethod_Self(PyObject *meth)
Return the instance associated with the method *meth* if it is bound, otherwise
return *NULL*.
.. c:function:: PyObject* PyMethod_GET_SELF(PyObject *meth)
Macro version of :c:func:`PyMethod_Self` which avoids error checking.
.. c:function:: int PyMethod_ClearFreeList()
Clear the free list. Return the total number of freed items.
.. versionadded:: 2.6

121
Doc/c-api/module.rst Normal file
View File

@@ -0,0 +1,121 @@
.. highlightlang:: c
.. _moduleobjects:
Module Objects
--------------
.. index:: object: module
There are only a few functions special to module objects.
.. c:var:: PyTypeObject PyModule_Type
.. index:: single: ModuleType (in module types)
This instance of :c:type:`PyTypeObject` represents the Python module type. This
is exposed to Python programs as ``types.ModuleType``.
.. c:function:: int PyModule_Check(PyObject *p)
Return true if *p* is a module object, or a subtype of a module object.
.. versionchanged:: 2.2
Allowed subtypes to be accepted.
.. c:function:: int PyModule_CheckExact(PyObject *p)
Return true if *p* is a module object, but not a subtype of
:c:data:`PyModule_Type`.
.. versionadded:: 2.2
.. c:function:: PyObject* PyModule_New(const char *name)
.. index::
single: __name__ (module attribute)
single: __doc__ (module attribute)
single: __file__ (module attribute)
Return a new module object with the :attr:`__name__` attribute set to *name*.
Only the module's :attr:`__doc__` and :attr:`__name__` attributes are filled in;
the caller is responsible for providing a :attr:`__file__` attribute.
.. c:function:: PyObject* PyModule_GetDict(PyObject *module)
.. index:: single: __dict__ (module attribute)
Return the dictionary object that implements *module*'s namespace; this object
is the same as the :attr:`~object.__dict__` attribute of the module object. This
function never fails. It is recommended extensions use other
:c:func:`PyModule_\*` and :c:func:`PyObject_\*` functions rather than directly
manipulate a module's :attr:`~object.__dict__`.
.. c:function:: char* PyModule_GetName(PyObject *module)
.. index::
single: __name__ (module attribute)
single: SystemError (built-in exception)
Return *module*'s :attr:`__name__` value. If the module does not provide one,
or if it is not a string, :exc:`SystemError` is raised and *NULL* is returned.
.. c:function:: char* PyModule_GetFilename(PyObject *module)
.. index::
single: __file__ (module attribute)
single: SystemError (built-in exception)
Return the name of the file from which *module* was loaded using *module*'s
:attr:`__file__` attribute. If this is not defined, or if it is not a string,
raise :exc:`SystemError` and return *NULL*.
.. c:function:: int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)
Add an object to *module* as *name*. This is a convenience function which can
be used from the module's initialization function. This steals a reference to
*value*. Return ``-1`` on error, ``0`` on success.
.. versionadded:: 2.0
.. c:function:: int PyModule_AddIntConstant(PyObject *module, const char *name, long value)
Add an integer constant to *module* as *name*. This convenience function can be
used from the module's initialization function. Return ``-1`` on error, ``0`` on
success.
.. versionadded:: 2.0
.. c:function:: int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value)
Add a string constant to *module* as *name*. This convenience function can be
used from the module's initialization function. The string *value* must be
null-terminated. Return ``-1`` on error, ``0`` on success.
.. versionadded:: 2.0
.. c:function:: int PyModule_AddIntMacro(PyObject *module, macro)
Add an int constant to *module*. The name and the value are taken from
*macro*. For example ``PyModule_AddIntMacro(module, AF_INET)`` adds the int
constant *AF_INET* with the value of *AF_INET* to *module*.
Return ``-1`` on error, ``0`` on success.
.. versionadded:: 2.6
.. c:function:: int PyModule_AddStringMacro(PyObject *module, macro)
Add a string constant to *module*.
.. versionadded:: 2.6

28
Doc/c-api/none.rst Normal file
View File

@@ -0,0 +1,28 @@
.. highlightlang:: c
.. _noneobject:
The ``None`` Object
-------------------
.. index:: object: None
Note that the :c:type:`PyTypeObject` for ``None`` is not directly exposed in the
Python/C API. Since ``None`` is a singleton, testing for object identity (using
``==`` in C) is sufficient. There is no :c:func:`PyNone_Check` function for the
same reason.
.. c:var:: PyObject* Py_None
The Python ``None`` object, denoting lack of value. This object has no methods.
It needs to be treated just like any other object with respect to reference
counts.
.. c:macro:: Py_RETURN_NONE
Properly handle returning :c:data:`Py_None` from within a C function.
.. versionadded:: 2.4

322
Doc/c-api/number.rst Normal file
View File

@@ -0,0 +1,322 @@
.. highlightlang:: c
.. _number:
Number Protocol
===============
.. c:function:: int PyNumber_Check(PyObject *o)
Returns ``1`` if the object *o* provides numeric protocols, and false otherwise.
This function always succeeds.
.. c:function:: PyObject* PyNumber_Add(PyObject *o1, PyObject *o2)
Returns the result of adding *o1* and *o2*, or *NULL* on failure. This is the
equivalent of the Python expression ``o1 + o2``.
.. c:function:: PyObject* PyNumber_Subtract(PyObject *o1, PyObject *o2)
Returns the result of subtracting *o2* from *o1*, or *NULL* on failure. This is
the equivalent of the Python expression ``o1 - o2``.
.. c:function:: PyObject* PyNumber_Multiply(PyObject *o1, PyObject *o2)
Returns the result of multiplying *o1* and *o2*, or *NULL* on failure. This is
the equivalent of the Python expression ``o1 * o2``.
.. c:function:: PyObject* PyNumber_Divide(PyObject *o1, PyObject *o2)
Returns the result of dividing *o1* by *o2*, or *NULL* on failure. This is the
equivalent of the Python expression ``o1 / o2``.
.. c:function:: PyObject* PyNumber_FloorDivide(PyObject *o1, PyObject *o2)
Return the floor of *o1* divided by *o2*, or *NULL* on failure. This is
equivalent to the "classic" division of integers.
.. versionadded:: 2.2
.. c:function:: PyObject* PyNumber_TrueDivide(PyObject *o1, PyObject *o2)
Return a reasonable approximation for the mathematical value of *o1* divided by
*o2*, or *NULL* on failure. The return value is "approximate" because binary
floating point numbers are approximate; it is not possible to represent all real
numbers in base two. This function can return a floating point value when
passed two integers.
.. versionadded:: 2.2
.. c:function:: PyObject* PyNumber_Remainder(PyObject *o1, PyObject *o2)
Returns the remainder of dividing *o1* by *o2*, or *NULL* on failure. This is
the equivalent of the Python expression ``o1 % o2``.
.. c:function:: PyObject* PyNumber_Divmod(PyObject *o1, PyObject *o2)
.. index:: builtin: divmod
See the built-in function :func:`divmod`. Returns *NULL* on failure. This is
the equivalent of the Python expression ``divmod(o1, o2)``.
.. c:function:: PyObject* PyNumber_Power(PyObject *o1, PyObject *o2, PyObject *o3)
.. index:: builtin: pow
See the built-in function :func:`pow`. Returns *NULL* on failure. This is the
equivalent of the Python expression ``pow(o1, o2, o3)``, where *o3* is optional.
If *o3* is to be ignored, pass :c:data:`Py_None` in its place (passing *NULL* for
*o3* would cause an illegal memory access).
.. c:function:: PyObject* PyNumber_Negative(PyObject *o)
Returns the negation of *o* on success, or *NULL* on failure. This is the
equivalent of the Python expression ``-o``.
.. c:function:: PyObject* PyNumber_Positive(PyObject *o)
Returns *o* on success, or *NULL* on failure. This is the equivalent of the
Python expression ``+o``.
.. c:function:: PyObject* PyNumber_Absolute(PyObject *o)
.. index:: builtin: abs
Returns the absolute value of *o*, or *NULL* on failure. This is the equivalent
of the Python expression ``abs(o)``.
.. c:function:: PyObject* PyNumber_Invert(PyObject *o)
Returns the bitwise negation of *o* on success, or *NULL* on failure. This is
the equivalent of the Python expression ``~o``.
.. c:function:: PyObject* PyNumber_Lshift(PyObject *o1, PyObject *o2)
Returns the result of left shifting *o1* by *o2* on success, or *NULL* on
failure. This is the equivalent of the Python expression ``o1 << o2``.
.. c:function:: PyObject* PyNumber_Rshift(PyObject *o1, PyObject *o2)
Returns the result of right shifting *o1* by *o2* on success, or *NULL* on
failure. This is the equivalent of the Python expression ``o1 >> o2``.
.. c:function:: PyObject* PyNumber_And(PyObject *o1, PyObject *o2)
Returns the "bitwise and" of *o1* and *o2* on success and *NULL* on failure.
This is the equivalent of the Python expression ``o1 & o2``.
.. c:function:: PyObject* PyNumber_Xor(PyObject *o1, PyObject *o2)
Returns the "bitwise exclusive or" of *o1* by *o2* on success, or *NULL* on
failure. This is the equivalent of the Python expression ``o1 ^ o2``.
.. c:function:: PyObject* PyNumber_Or(PyObject *o1, PyObject *o2)
Returns the "bitwise or" of *o1* and *o2* on success, or *NULL* on failure.
This is the equivalent of the Python expression ``o1 | o2``.
.. c:function:: PyObject* PyNumber_InPlaceAdd(PyObject *o1, PyObject *o2)
Returns the result of adding *o1* and *o2*, or *NULL* on failure. The operation
is done *in-place* when *o1* supports it. This is the equivalent of the Python
statement ``o1 += o2``.
.. c:function:: PyObject* PyNumber_InPlaceSubtract(PyObject *o1, PyObject *o2)
Returns the result of subtracting *o2* from *o1*, or *NULL* on failure. The
operation is done *in-place* when *o1* supports it. This is the equivalent of
the Python statement ``o1 -= o2``.
.. c:function:: PyObject* PyNumber_InPlaceMultiply(PyObject *o1, PyObject *o2)
Returns the result of multiplying *o1* and *o2*, or *NULL* on failure. The
operation is done *in-place* when *o1* supports it. This is the equivalent of
the Python statement ``o1 *= o2``.
.. c:function:: PyObject* PyNumber_InPlaceDivide(PyObject *o1, PyObject *o2)
Returns the result of dividing *o1* by *o2*, or *NULL* on failure. The
operation is done *in-place* when *o1* supports it. This is the equivalent of
the Python statement ``o1 /= o2``.
.. c:function:: PyObject* PyNumber_InPlaceFloorDivide(PyObject *o1, PyObject *o2)
Returns the mathematical floor of dividing *o1* by *o2*, or *NULL* on failure.
The operation is done *in-place* when *o1* supports it. This is the equivalent
of the Python statement ``o1 //= o2``.
.. versionadded:: 2.2
.. c:function:: PyObject* PyNumber_InPlaceTrueDivide(PyObject *o1, PyObject *o2)
Return a reasonable approximation for the mathematical value of *o1* divided by
*o2*, or *NULL* on failure. The return value is "approximate" because binary
floating point numbers are approximate; it is not possible to represent all real
numbers in base two. This function can return a floating point value when
passed two integers. The operation is done *in-place* when *o1* supports it.
.. versionadded:: 2.2
.. c:function:: PyObject* PyNumber_InPlaceRemainder(PyObject *o1, PyObject *o2)
Returns the remainder of dividing *o1* by *o2*, or *NULL* on failure. The
operation is done *in-place* when *o1* supports it. This is the equivalent of
the Python statement ``o1 %= o2``.
.. c:function:: PyObject* PyNumber_InPlacePower(PyObject *o1, PyObject *o2, PyObject *o3)
.. index:: builtin: pow
See the built-in function :func:`pow`. Returns *NULL* on failure. The operation
is done *in-place* when *o1* supports it. This is the equivalent of the Python
statement ``o1 **= o2`` when o3 is :c:data:`Py_None`, or an in-place variant of
``pow(o1, o2, o3)`` otherwise. If *o3* is to be ignored, pass :c:data:`Py_None`
in its place (passing *NULL* for *o3* would cause an illegal memory access).
.. c:function:: PyObject* PyNumber_InPlaceLshift(PyObject *o1, PyObject *o2)
Returns the result of left shifting *o1* by *o2* on success, or *NULL* on
failure. The operation is done *in-place* when *o1* supports it. This is the
equivalent of the Python statement ``o1 <<= o2``.
.. c:function:: PyObject* PyNumber_InPlaceRshift(PyObject *o1, PyObject *o2)
Returns the result of right shifting *o1* by *o2* on success, or *NULL* on
failure. The operation is done *in-place* when *o1* supports it. This is the
equivalent of the Python statement ``o1 >>= o2``.
.. c:function:: PyObject* PyNumber_InPlaceAnd(PyObject *o1, PyObject *o2)
Returns the "bitwise and" of *o1* and *o2* on success and *NULL* on failure. The
operation is done *in-place* when *o1* supports it. This is the equivalent of
the Python statement ``o1 &= o2``.
.. c:function:: PyObject* PyNumber_InPlaceXor(PyObject *o1, PyObject *o2)
Returns the "bitwise exclusive or" of *o1* by *o2* on success, or *NULL* on
failure. The operation is done *in-place* when *o1* supports it. This is the
equivalent of the Python statement ``o1 ^= o2``.
.. c:function:: PyObject* PyNumber_InPlaceOr(PyObject *o1, PyObject *o2)
Returns the "bitwise or" of *o1* and *o2* on success, or *NULL* on failure. The
operation is done *in-place* when *o1* supports it. This is the equivalent of
the Python statement ``o1 |= o2``.
.. c:function:: int PyNumber_Coerce(PyObject **p1, PyObject **p2)
.. index:: builtin: coerce
This function takes the addresses of two variables of type :c:type:`PyObject\*`.
If the objects pointed to by ``*p1`` and ``*p2`` have the same type, increment
their reference count and return ``0`` (success). If the objects can be
converted to a common numeric type, replace ``*p1`` and ``*p2`` by their
converted value (with 'new' reference counts), and return ``0``. If no
conversion is possible, or if some other error occurs, return ``-1`` (failure)
and don't increment the reference counts. The call ``PyNumber_Coerce(&o1,
&o2)`` is equivalent to the Python statement ``o1, o2 = coerce(o1, o2)``.
.. c:function:: int PyNumber_CoerceEx(PyObject **p1, PyObject **p2)
This function is similar to :c:func:`PyNumber_Coerce`, except that it returns
``1`` when the conversion is not possible and when no error is raised.
Reference counts are still not increased in this case.
.. c:function:: PyObject* PyNumber_Int(PyObject *o)
.. index:: builtin: int
Returns the *o* converted to an integer object on success, or *NULL* on failure.
If the argument is outside the integer range a long object will be returned
instead. This is the equivalent of the Python expression ``int(o)``.
.. c:function:: PyObject* PyNumber_Long(PyObject *o)
.. index:: builtin: long
Returns the *o* converted to a long integer object on success, or *NULL* on
failure. This is the equivalent of the Python expression ``long(o)``.
.. c:function:: PyObject* PyNumber_Float(PyObject *o)
.. index:: builtin: float
Returns the *o* converted to a float object on success, or *NULL* on failure.
This is the equivalent of the Python expression ``float(o)``.
.. c:function:: PyObject* PyNumber_Index(PyObject *o)
Returns the *o* converted to a Python int or long on success or *NULL* with a
:exc:`TypeError` exception raised on failure.
.. versionadded:: 2.5
.. c:function:: PyObject* PyNumber_ToBase(PyObject *n, int base)
Returns the integer *n* converted to *base* as a string with a base
marker of ``'0b'``, ``'0o'``, or ``'0x'`` if applicable. When
*base* is not 2, 8, 10, or 16, the format is ``'x#num'`` where x is the
base. If *n* is not an int object, it is converted with
:c:func:`PyNumber_Index` first.
.. versionadded:: 2.6
.. c:function:: Py_ssize_t PyNumber_AsSsize_t(PyObject *o, PyObject *exc)
Returns *o* converted to a Py_ssize_t value if *o* can be interpreted as an
integer. If *o* can be converted to a Python int or long but the attempt to
convert to a Py_ssize_t value would raise an :exc:`OverflowError`, then the
*exc* argument is the type of exception that will be raised (usually
:exc:`IndexError` or :exc:`OverflowError`). If *exc* is *NULL*, then the
exception is cleared and the value is clipped to *PY_SSIZE_T_MIN* for a negative
integer or *PY_SSIZE_T_MAX* for a positive integer.
.. versionadded:: 2.5
.. c:function:: int PyIndex_Check(PyObject *o)
Returns ``1`` if *o* is an index integer (has the nb_index slot of the
tp_as_number structure filled in), and ``0`` otherwise.
.. versionadded:: 2.5

66
Doc/c-api/objbuffer.rst Normal file
View File

@@ -0,0 +1,66 @@
.. highlightlang:: c
.. _abstract-buffer:
Old Buffer Protocol
===================
This section describes the legacy buffer protocol, which has been introduced
in Python 1.6. It is still supported but deprecated in the Python 2.x series.
Python 3 introduces a new buffer protocol which fixes weaknesses and
shortcomings of the protocol, and has been backported to Python 2.6. See
:ref:`bufferobjects` for more information.
.. c:function:: int PyObject_AsCharBuffer(PyObject *obj, const char **buffer, Py_ssize_t *buffer_len)
Returns a pointer to a read-only memory location usable as character-based
input. The *obj* argument must support the single-segment character buffer
interface. On success, returns ``0``, sets *buffer* to the memory location
and *buffer_len* to the buffer length. Returns ``-1`` and sets a
:exc:`TypeError` on error.
.. versionadded:: 1.6
.. versionchanged:: 2.5
This function used an :c:type:`int *` type for *buffer_len*. This might
require changes in your code for properly supporting 64-bit systems.
.. c:function:: int PyObject_AsReadBuffer(PyObject *obj, const void **buffer, Py_ssize_t *buffer_len)
Returns a pointer to a read-only memory location containing arbitrary data.
The *obj* argument must support the single-segment readable buffer
interface. On success, returns ``0``, sets *buffer* to the memory location
and *buffer_len* to the buffer length. Returns ``-1`` and sets a
:exc:`TypeError` on error.
.. versionadded:: 1.6
.. versionchanged:: 2.5
This function used an :c:type:`int *` type for *buffer_len*. This might
require changes in your code for properly supporting 64-bit systems.
.. c:function:: int PyObject_CheckReadBuffer(PyObject *o)
Returns ``1`` if *o* supports the single-segment readable buffer interface.
Otherwise returns ``0``.
.. versionadded:: 2.2
.. c:function:: int PyObject_AsWriteBuffer(PyObject *obj, void **buffer, Py_ssize_t *buffer_len)
Returns a pointer to a writeable memory location. The *obj* argument must
support the single-segment, character buffer interface. On success,
returns ``0``, sets *buffer* to the memory location and *buffer_len* to the
buffer length. Returns ``-1`` and sets a :exc:`TypeError` on error.
.. versionadded:: 1.6
.. versionchanged:: 2.5
This function used an :c:type:`int *` type for *buffer_len*. This might
require changes in your code for properly supporting 64-bit systems.

413
Doc/c-api/object.rst Normal file
View File

@@ -0,0 +1,413 @@
.. highlightlang:: c
.. _object:
Object Protocol
===============
.. c:function:: int PyObject_Print(PyObject *o, FILE *fp, int flags)
Print an object *o*, on file *fp*. Returns ``-1`` on error. The flags argument
is used to enable certain printing options. The only option currently supported
is :const:`Py_PRINT_RAW`; if given, the :func:`str` of the object is written
instead of the :func:`repr`.
.. c:function:: int PyObject_HasAttr(PyObject *o, PyObject *attr_name)
Returns ``1`` if *o* has the attribute *attr_name*, and ``0`` otherwise. This
is equivalent to the Python expression ``hasattr(o, attr_name)``. This function
always succeeds.
.. c:function:: int PyObject_HasAttrString(PyObject *o, const char *attr_name)
Returns ``1`` if *o* has the attribute *attr_name*, and ``0`` otherwise. This
is equivalent to the Python expression ``hasattr(o, attr_name)``. This function
always succeeds.
.. c:function:: PyObject* PyObject_GetAttr(PyObject *o, PyObject *attr_name)
Retrieve an attribute named *attr_name* from object *o*. Returns the attribute
value on success, or *NULL* on failure. This is the equivalent of the Python
expression ``o.attr_name``.
.. c:function:: PyObject* PyObject_GetAttrString(PyObject *o, const char *attr_name)
Retrieve an attribute named *attr_name* from object *o*. Returns the attribute
value on success, or *NULL* on failure. This is the equivalent of the Python
expression ``o.attr_name``.
.. c:function:: PyObject* PyObject_GenericGetAttr(PyObject *o, PyObject *name)
Generic attribute getter function that is meant to be put into a type
object's ``tp_getattro`` slot. It looks for a descriptor in the dictionary
of classes in the object's MRO as well as an attribute in the object's
:attr:`~object.__dict__` (if present). As outlined in :ref:`descriptors`,
data descriptors take preference over instance attributes, while non-data
descriptors don't. Otherwise, an :exc:`AttributeError` is raised.
.. c:function:: int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v)
Set the value of the attribute named *attr_name*, for object *o*, to the value
*v*. Raise an exception and return ``-1`` on failure;
return ``0`` on success. This is the equivalent of the Python statement
``o.attr_name = v``.
If *v* is *NULL*, the attribute is deleted, however this feature is
deprecated in favour of using :c:func:`PyObject_DelAttr`.
.. c:function:: int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v)
Set the value of the attribute named *attr_name*, for object *o*, to the value
*v*. Raise an exception and return ``-1`` on failure;
return ``0`` on success. This is the equivalent of the Python statement
``o.attr_name = v``.
If *v* is *NULL*, the attribute is deleted, however this feature is
deprecated in favour of using :c:func:`PyObject_DelAttrString`.
.. c:function:: int PyObject_GenericSetAttr(PyObject *o, PyObject *name, PyObject *value)
Generic attribute setter and deleter function that is meant
to be put into a type object's :c:member:`~PyTypeObject.tp_setattro`
slot. It looks for a data descriptor in the
dictionary of classes in the object's MRO, and if found it takes preference
over setting or deleting the attribute in the instance dictionary. Otherwise, the
attribute is set or deleted in the object's :attr:`~object.__dict__` (if present).
On success, ``0`` is returned, otherwise an :exc:`AttributeError`
is raised and ``-1`` is returned.
.. c:function:: int PyObject_DelAttr(PyObject *o, PyObject *attr_name)
Delete attribute named *attr_name*, for object *o*. Returns ``-1`` on failure.
This is the equivalent of the Python statement ``del o.attr_name``.
.. c:function:: int PyObject_DelAttrString(PyObject *o, const char *attr_name)
Delete attribute named *attr_name*, for object *o*. Returns ``-1`` on failure.
This is the equivalent of the Python statement ``del o.attr_name``.
.. c:function:: PyObject* PyObject_RichCompare(PyObject *o1, PyObject *o2, int opid)
Compare the values of *o1* and *o2* using the operation specified by *opid*,
which must be one of :const:`Py_LT`, :const:`Py_LE`, :const:`Py_EQ`,
:const:`Py_NE`, :const:`Py_GT`, or :const:`Py_GE`, corresponding to ``<``,
``<=``, ``==``, ``!=``, ``>``, or ``>=`` respectively. This is the equivalent of
the Python expression ``o1 op o2``, where ``op`` is the operator corresponding
to *opid*. Returns the value of the comparison on success, or *NULL* on failure.
.. c:function:: int PyObject_RichCompareBool(PyObject *o1, PyObject *o2, int opid)
Compare the values of *o1* and *o2* using the operation specified by *opid*,
which must be one of :const:`Py_LT`, :const:`Py_LE`, :const:`Py_EQ`,
:const:`Py_NE`, :const:`Py_GT`, or :const:`Py_GE`, corresponding to ``<``,
``<=``, ``==``, ``!=``, ``>``, or ``>=`` respectively. Returns ``-1`` on error,
``0`` if the result is false, ``1`` otherwise. This is the equivalent of the
Python expression ``o1 op o2``, where ``op`` is the operator corresponding to
*opid*.
.. note::
If *o1* and *o2* are the same object, :c:func:`PyObject_RichCompareBool`
will always return ``1`` for :const:`Py_EQ` and ``0`` for :const:`Py_NE`.
.. c:function:: int PyObject_Cmp(PyObject *o1, PyObject *o2, int *result)
.. index:: builtin: cmp
Compare the values of *o1* and *o2* using a routine provided by *o1*, if one
exists, otherwise with a routine provided by *o2*. The result of the comparison
is returned in *result*. Returns ``-1`` on failure. This is the equivalent of
the Python statement ``result = cmp(o1, o2)``.
.. c:function:: int PyObject_Compare(PyObject *o1, PyObject *o2)
.. index:: builtin: cmp
Compare the values of *o1* and *o2* using a routine provided by *o1*, if one
exists, otherwise with a routine provided by *o2*. Returns the result of the
comparison on success. On error, the value returned is undefined; use
:c:func:`PyErr_Occurred` to detect an error. This is equivalent to the Python
expression ``cmp(o1, o2)``.
.. c:function:: PyObject* PyObject_Repr(PyObject *o)
.. index:: builtin: repr
Compute a string representation of object *o*. Returns the string
representation on success, *NULL* on failure. This is the equivalent of the
Python expression ``repr(o)``. Called by the :func:`repr` built-in function and
by reverse quotes.
.. c:function:: PyObject* PyObject_Str(PyObject *o)
.. index:: builtin: str
Compute a string representation of object *o*. Returns the string
representation on success, *NULL* on failure. This is the equivalent of the
Python expression ``str(o)``. Called by the :func:`str` built-in function and
by the :keyword:`print` statement.
.. c:function:: PyObject* PyObject_Bytes(PyObject *o)
.. index:: builtin: bytes
Compute a bytes representation of object *o*. In 2.x, this is just an alias
for :c:func:`PyObject_Str`.
.. c:function:: PyObject* PyObject_Unicode(PyObject *o)
.. index:: builtin: unicode
Compute a Unicode string representation of object *o*. Returns the Unicode
string representation on success, *NULL* on failure. This is the equivalent of
the Python expression ``unicode(o)``. Called by the :func:`unicode` built-in
function.
.. c:function:: int PyObject_IsInstance(PyObject *inst, PyObject *cls)
Returns ``1`` if *inst* is an instance of the class *cls* or a subclass of
*cls*, or ``0`` if not. On error, returns ``-1`` and sets an exception. If
*cls* is a type object rather than a class object, :c:func:`PyObject_IsInstance`
returns ``1`` if *inst* is of type *cls*. If *cls* is a tuple, the check will
be done against every entry in *cls*. The result will be ``1`` when at least one
of the checks returns ``1``, otherwise it will be ``0``. If *inst* is not a
class instance and *cls* is neither a type object, nor a class object, nor a
tuple, *inst* must have a :attr:`~instance.__class__` attribute --- the
class relationship of the value of that attribute with *cls* will be used
to determine the result of this function.
.. versionadded:: 2.1
.. versionchanged:: 2.2
Support for a tuple as the second argument added.
Subclass determination is done in a fairly straightforward way, but includes a
wrinkle that implementors of extensions to the class system may want to be aware
of. If :class:`A` and :class:`B` are class objects, :class:`B` is a subclass of
:class:`A` if it inherits from :class:`A` either directly or indirectly. If
either is not a class object, a more general mechanism is used to determine the
class relationship of the two objects. When testing if *B* is a subclass of
*A*, if *A* is *B*, :c:func:`PyObject_IsSubclass` returns true. If *A* and *B*
are different objects, *B*'s :attr:`~class.__bases__` attribute is searched in
a depth-first fashion for *A* --- the presence of the :attr:`~class.__bases__`
attribute is considered sufficient for this determination.
.. c:function:: int PyObject_IsSubclass(PyObject *derived, PyObject *cls)
Returns ``1`` if the class *derived* is identical to or derived from the class
*cls*, otherwise returns ``0``. In case of an error, returns ``-1``. If *cls*
is a tuple, the check will be done against every entry in *cls*. The result will
be ``1`` when at least one of the checks returns ``1``, otherwise it will be
``0``. If either *derived* or *cls* is not an actual class object (or tuple),
this function uses the generic algorithm described above.
.. versionadded:: 2.1
.. versionchanged:: 2.3
Older versions of Python did not support a tuple as the second argument.
.. c:function:: int PyCallable_Check(PyObject *o)
Determine if the object *o* is callable. Return ``1`` if the object is callable
and ``0`` otherwise. This function always succeeds.
.. c:function:: PyObject* PyObject_Call(PyObject *callable_object, PyObject *args, PyObject *kw)
.. index:: builtin: apply
Call a callable Python object *callable_object*, with arguments given by the
tuple *args*, and named arguments given by the dictionary *kw*. If no named
arguments are needed, *kw* may be *NULL*. *args* must not be *NULL*, use an
empty tuple if no arguments are needed. Returns the result of the call on
success, or *NULL* on failure. This is the equivalent of the Python expression
``apply(callable_object, args, kw)`` or ``callable_object(*args, **kw)``.
.. versionadded:: 2.2
.. c:function:: PyObject* PyObject_CallObject(PyObject *callable_object, PyObject *args)
.. index:: builtin: apply
Call a callable Python object *callable_object*, with arguments given by the
tuple *args*. If no arguments are needed, then *args* may be *NULL*. Returns
the result of the call on success, or *NULL* on failure. This is the equivalent
of the Python expression ``apply(callable_object, args)`` or
``callable_object(*args)``.
.. c:function:: PyObject* PyObject_CallFunction(PyObject *callable, char *format, ...)
.. index:: builtin: apply
Call a callable Python object *callable*, with a variable number of C arguments.
The C arguments are described using a :c:func:`Py_BuildValue` style format
string. The format may be *NULL*, indicating that no arguments are provided.
Returns the result of the call on success, or *NULL* on failure. This is the
equivalent of the Python expression ``apply(callable, args)`` or
``callable(*args)``. Note that if you only pass :c:type:`PyObject \*` args,
:c:func:`PyObject_CallFunctionObjArgs` is a faster alternative.
.. c:function:: PyObject* PyObject_CallMethod(PyObject *o, char *method, char *format, ...)
Call the method named *method* of object *o* with a variable number of C
arguments. The C arguments are described by a :c:func:`Py_BuildValue` format
string that should produce a tuple. The format may be *NULL*, indicating that
no arguments are provided. Returns the result of the call on success, or *NULL*
on failure. This is the equivalent of the Python expression ``o.method(args)``.
Note that if you only pass :c:type:`PyObject \*` args,
:c:func:`PyObject_CallMethodObjArgs` is a faster alternative.
.. c:function:: PyObject* PyObject_CallFunctionObjArgs(PyObject *callable, ..., NULL)
Call a callable Python object *callable*, with a variable number of
:c:type:`PyObject\*` arguments. The arguments are provided as a variable number
of parameters followed by *NULL*. Returns the result of the call on success, or
*NULL* on failure.
.. versionadded:: 2.2
.. c:function:: PyObject* PyObject_CallMethodObjArgs(PyObject *o, PyObject *name, ..., NULL)
Calls a method of the object *o*, where the name of the method is given as a
Python string object in *name*. It is called with a variable number of
:c:type:`PyObject\*` arguments. The arguments are provided as a variable number
of parameters followed by *NULL*. Returns the result of the call on success, or
*NULL* on failure.
.. versionadded:: 2.2
.. c:function:: long PyObject_Hash(PyObject *o)
.. index:: builtin: hash
Compute and return the hash value of an object *o*. On failure, return ``-1``.
This is the equivalent of the Python expression ``hash(o)``.
.. c:function:: long PyObject_HashNotImplemented(PyObject *o)
Set a :exc:`TypeError` indicating that ``type(o)`` is not hashable and return ``-1``.
This function receives special treatment when stored in a ``tp_hash`` slot,
allowing a type to explicitly indicate to the interpreter that it is not
hashable.
.. versionadded:: 2.6
.. c:function:: int PyObject_IsTrue(PyObject *o)
Returns ``1`` if the object *o* is considered to be true, and ``0`` otherwise.
This is equivalent to the Python expression ``not not o``. On failure, return
``-1``.
.. c:function:: int PyObject_Not(PyObject *o)
Returns ``0`` if the object *o* is considered to be true, and ``1`` otherwise.
This is equivalent to the Python expression ``not o``. On failure, return
``-1``.
.. c:function:: PyObject* PyObject_Type(PyObject *o)
.. index:: builtin: type
When *o* is non-*NULL*, returns a type object corresponding to the object type
of object *o*. On failure, raises :exc:`SystemError` and returns *NULL*. This
is equivalent to the Python expression ``type(o)``. This function increments the
reference count of the return value. There's really no reason to use this
function instead of the common expression ``o->ob_type``, which returns a
pointer of type :c:type:`PyTypeObject\*`, except when the incremented reference
count is needed.
.. c:function:: int PyObject_TypeCheck(PyObject *o, PyTypeObject *type)
Return true if the object *o* is of type *type* or a subtype of *type*. Both
parameters must be non-*NULL*.
.. versionadded:: 2.2
.. c:function:: Py_ssize_t PyObject_Length(PyObject *o)
Py_ssize_t PyObject_Size(PyObject *o)
.. index:: builtin: len
Return the length of object *o*. If the object *o* provides either the sequence
and mapping protocols, the sequence length is returned. On error, ``-1`` is
returned. This is the equivalent to the Python expression ``len(o)``.
.. versionchanged:: 2.5
These functions returned an :c:type:`int` type. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyObject_GetItem(PyObject *o, PyObject *key)
Return element of *o* corresponding to the object *key* or *NULL* on failure.
This is the equivalent of the Python expression ``o[key]``.
.. c:function:: int PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v)
Map the object *key* to the value *v*. Raise an exception and
return ``-1`` on failure; return ``0`` on success. This is the
equivalent of the Python statement ``o[key] = v``.
.. c:function:: int PyObject_DelItem(PyObject *o, PyObject *key)
Delete the mapping for *key* from *o*. Returns ``-1`` on failure. This is the
equivalent of the Python statement ``del o[key]``.
.. c:function:: int PyObject_AsFileDescriptor(PyObject *o)
Derives a file descriptor from a Python object. If the object is an integer or
long integer, its value is returned. If not, the object's :meth:`fileno` method
is called if it exists; the method must return an integer or long integer, which
is returned as the file descriptor value. Returns ``-1`` on failure.
.. c:function:: PyObject* PyObject_Dir(PyObject *o)
This is equivalent to the Python expression ``dir(o)``, returning a (possibly
empty) list of strings appropriate for the object argument, or *NULL* if there
was an error. If the argument is *NULL*, this is like the Python ``dir()``,
returning the names of the current locals; in this case, if no execution frame
is active then *NULL* is returned but :c:func:`PyErr_Occurred` will return false.
.. c:function:: PyObject* PyObject_GetIter(PyObject *o)
This is equivalent to the Python expression ``iter(o)``. It returns a new
iterator for the object argument, or the object itself if the object is already
an iterator. Raises :exc:`TypeError` and returns *NULL* if the object cannot be
iterated.

18
Doc/c-api/objimpl.rst Normal file
View File

@@ -0,0 +1,18 @@
.. highlightlang:: c
.. _newtypes:
*****************************
Object Implementation Support
*****************************
This chapter describes the functions, types, and macros used when defining new
object types.
.. toctree::
allocation.rst
structures.rst
typeobj.rst
gcsupport.rst

74
Doc/c-api/refcounting.rst Normal file
View File

@@ -0,0 +1,74 @@
.. highlightlang:: c
.. _countingrefs:
******************
Reference Counting
******************
The macros in this section are used for managing reference counts of Python
objects.
.. c:function:: void Py_INCREF(PyObject *o)
Increment the reference count for object *o*. The object must not be *NULL*; if
you aren't sure that it isn't *NULL*, use :c:func:`Py_XINCREF`.
.. c:function:: void Py_XINCREF(PyObject *o)
Increment the reference count for object *o*. The object may be *NULL*, in
which case the macro has no effect.
.. c:function:: void Py_DECREF(PyObject *o)
Decrement the reference count for object *o*. The object must not be *NULL*; if
you aren't sure that it isn't *NULL*, use :c:func:`Py_XDECREF`. If the reference
count reaches zero, the object's type's deallocation function (which must not be
*NULL*) is invoked.
.. warning::
The deallocation function can cause arbitrary Python code to be invoked (e.g.
when a class instance with a :meth:`__del__` method is deallocated). While
exceptions in such code are not propagated, the executed code has free access to
all Python global variables. This means that any object that is reachable from
a global variable should be in a consistent state before :c:func:`Py_DECREF` is
invoked. For example, code to delete an object from a list should copy a
reference to the deleted object in a temporary variable, update the list data
structure, and then call :c:func:`Py_DECREF` for the temporary variable.
.. c:function:: void Py_XDECREF(PyObject *o)
Decrement the reference count for object *o*. The object may be *NULL*, in
which case the macro has no effect; otherwise the effect is the same as for
:c:func:`Py_DECREF`, and the same warning applies.
.. c:function:: void Py_CLEAR(PyObject *o)
Decrement the reference count for object *o*. The object may be *NULL*, in
which case the macro has no effect; otherwise the effect is the same as for
:c:func:`Py_DECREF`, except that the argument is also set to *NULL*. The warning
for :c:func:`Py_DECREF` does not apply with respect to the object passed because
the macro carefully uses a temporary variable and sets the argument to *NULL*
before decrementing its reference count.
It is a good idea to use this macro whenever decrementing the value of a
variable that might be traversed during garbage collection.
.. versionadded:: 2.4
The following functions are for runtime dynamic embedding of Python:
``Py_IncRef(PyObject *o)``, ``Py_DecRef(PyObject *o)``. They are
simply exported function versions of :c:func:`Py_XINCREF` and
:c:func:`Py_XDECREF`, respectively.
The following functions or macros are only for use within the interpreter core:
:c:func:`_Py_Dealloc`, :c:func:`_Py_ForgetReference`, :c:func:`_Py_NewReference`,
as well as the global variable :c:data:`_Py_RefTotal`.

55
Doc/c-api/reflection.rst Normal file
View File

@@ -0,0 +1,55 @@
.. highlightlang:: c
.. _reflection:
Reflection
==========
.. c:function:: PyObject* PyEval_GetBuiltins()
Return a dictionary of the builtins in the current execution frame,
or the interpreter of the thread state if no frame is currently executing.
.. c:function:: PyObject* PyEval_GetLocals()
Return a dictionary of the local variables in the current execution frame,
or *NULL* if no frame is currently executing.
.. c:function:: PyObject* PyEval_GetGlobals()
Return a dictionary of the global variables in the current execution frame,
or *NULL* if no frame is currently executing.
.. c:function:: PyFrameObject* PyEval_GetFrame()
Return the current thread state's frame, which is *NULL* if no frame is
currently executing.
.. c:function:: int PyFrame_GetLineNumber(PyFrameObject *frame)
Return the line number that *frame* is currently executing.
.. c:function:: int PyEval_GetRestricted()
If there is a current frame and it is executing in restricted mode, return true,
otherwise false.
.. c:function:: const char* PyEval_GetFuncName(PyObject *func)
Return the name of *func* if it is a function, class or instance object, else the
name of *func*\s type.
.. c:function:: const char* PyEval_GetFuncDesc(PyObject *func)
Return a description string, depending on the type of *func*.
Return values include "()" for functions and methods, " constructor",
" instance", and " object". Concatenated with the result of
:c:func:`PyEval_GetFuncName`, the result will be a description of
*func*.

225
Doc/c-api/sequence.rst Normal file
View File

@@ -0,0 +1,225 @@
.. highlightlang:: c
.. _sequence:
Sequence Protocol
=================
.. c:function:: int PySequence_Check(PyObject *o)
Return ``1`` if the object provides sequence protocol, and ``0`` otherwise.
This function always succeeds.
.. c:function:: Py_ssize_t PySequence_Size(PyObject *o)
Py_ssize_t PySequence_Length(PyObject *o)
.. index:: builtin: len
Returns the number of objects in sequence *o* on success, and ``-1`` on
failure. This is equivalent to the Python expression ``len(o)``.
.. versionchanged:: 2.5
These functions returned an :c:type:`int` type. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PySequence_Concat(PyObject *o1, PyObject *o2)
Return the concatenation of *o1* and *o2* on success, and *NULL* on failure.
This is the equivalent of the Python expression ``o1 + o2``.
.. c:function:: PyObject* PySequence_Repeat(PyObject *o, Py_ssize_t count)
Return the result of repeating sequence object *o* *count* times, or *NULL* on
failure. This is the equivalent of the Python expression ``o * count``.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *count*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PySequence_InPlaceConcat(PyObject *o1, PyObject *o2)
Return the concatenation of *o1* and *o2* on success, and *NULL* on failure.
The operation is done *in-place* when *o1* supports it. This is the equivalent
of the Python expression ``o1 += o2``.
.. c:function:: PyObject* PySequence_InPlaceRepeat(PyObject *o, Py_ssize_t count)
Return the result of repeating sequence object *o* *count* times, or *NULL* on
failure. The operation is done *in-place* when *o* supports it. This is the
equivalent of the Python expression ``o *= count``.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *count*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PySequence_GetItem(PyObject *o, Py_ssize_t i)
Return the *i*\ th element of *o*, or *NULL* on failure. This is the equivalent of
the Python expression ``o[i]``.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *i*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PySequence_GetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2)
Return the slice of sequence object *o* between *i1* and *i2*, or *NULL* on
failure. This is the equivalent of the Python expression ``o[i1:i2]``.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *i1* and *i2*. This might
require changes in your code for properly supporting 64-bit systems.
.. c:function:: int PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v)
Assign object *v* to the *i*\ th element of *o*. Raise an exception
and return ``-1`` on failure; return ``0`` on success. This
is the equivalent of the Python statement ``o[i] = v``. This function *does
not* steal a reference to *v*.
If *v* is *NULL*, the element is deleted, however this feature is
deprecated in favour of using :c:func:`PySequence_DelItem`.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *i*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: int PySequence_DelItem(PyObject *o, Py_ssize_t i)
Delete the *i*\ th element of object *o*. Returns ``-1`` on failure. This is the
equivalent of the Python statement ``del o[i]``.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *i*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: int PySequence_SetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2, PyObject *v)
Assign the sequence object *v* to the slice in sequence object *o* from *i1* to
*i2*. Raise an exception and return ``-1`` on failure; return ``0`` on success.
This is the equivalent of the Python statement ``o[i1:i2] = v``.
If *v* is *NULL*, the slice is deleted, however this feature is
deprecated in favour of using :c:func:`PySequence_DelSlice`.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *i1* and *i2*. This might
require changes in your code for properly supporting 64-bit systems.
.. c:function:: int PySequence_DelSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2)
Delete the slice in sequence object *o* from *i1* to *i2*. Returns ``-1`` on
failure. This is the equivalent of the Python statement ``del o[i1:i2]``.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *i1* and *i2*. This might
require changes in your code for properly supporting 64-bit systems.
.. c:function:: Py_ssize_t PySequence_Count(PyObject *o, PyObject *value)
Return the number of occurrences of *value* in *o*, that is, return the number
of keys for which ``o[key] == value``. On failure, return ``-1``. This is
equivalent to the Python expression ``o.count(value)``.
.. versionchanged:: 2.5
This function returned an :c:type:`int` type. This might require changes
in your code for properly supporting 64-bit systems.
.. c:function:: int PySequence_Contains(PyObject *o, PyObject *value)
Determine if *o* contains *value*. If an item in *o* is equal to *value*,
return ``1``, otherwise return ``0``. On error, return ``-1``. This is
equivalent to the Python expression ``value in o``.
.. c:function:: Py_ssize_t PySequence_Index(PyObject *o, PyObject *value)
Return the first index *i* for which ``o[i] == value``. On error, return
``-1``. This is equivalent to the Python expression ``o.index(value)``.
.. versionchanged:: 2.5
This function returned an :c:type:`int` type. This might require changes
in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PySequence_List(PyObject *o)
Return a list object with the same contents as the arbitrary sequence *o*. The
returned list is guaranteed to be new.
.. c:function:: PyObject* PySequence_Tuple(PyObject *o)
.. index:: builtin: tuple
Return a tuple object with the same contents as the arbitrary sequence *o* or
*NULL* on failure. If *o* is a tuple, a new reference will be returned,
otherwise a tuple will be constructed with the appropriate contents. This is
equivalent to the Python expression ``tuple(o)``.
.. c:function:: PyObject* PySequence_Fast(PyObject *o, const char *m)
Return the sequence *o* as a list, unless it is already a tuple or list, in
which case *o* is returned. Use :c:func:`PySequence_Fast_GET_ITEM` to access
the members of the result. Returns *NULL* on failure. If the object is not
a sequence, raises :exc:`TypeError` with *m* as the message text.
.. c:function:: PyObject* PySequence_Fast_GET_ITEM(PyObject *o, Py_ssize_t i)
Return the *i*\ th element of *o*, assuming that *o* was returned by
:c:func:`PySequence_Fast`, *o* is not *NULL*, and that *i* is within bounds.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *i*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject** PySequence_Fast_ITEMS(PyObject *o)
Return the underlying array of PyObject pointers. Assumes that *o* was returned
by :c:func:`PySequence_Fast` and *o* is not *NULL*.
Note, if a list gets resized, the reallocation may relocate the items array.
So, only use the underlying array pointer in contexts where the sequence
cannot change.
.. versionadded:: 2.4
.. c:function:: PyObject* PySequence_ITEM(PyObject *o, Py_ssize_t i)
Return the *i*\ th element of *o* or *NULL* on failure. Macro form of
:c:func:`PySequence_GetItem` but without checking that
:c:func:`PySequence_Check` on *o* is true and without adjustment for negative
indices.
.. versionadded:: 2.3
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *i*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: Py_ssize_t PySequence_Fast_GET_SIZE(PyObject *o)
Returns the length of *o*, assuming that *o* was returned by
:c:func:`PySequence_Fast` and that *o* is not *NULL*. The size can also be
gotten by calling :c:func:`PySequence_Size` on *o*, but
:c:func:`PySequence_Fast_GET_SIZE` is faster because it can assume *o* is a list
or tuple.

175
Doc/c-api/set.rst Normal file
View File

@@ -0,0 +1,175 @@
.. highlightlang:: c
.. _setobjects:
Set Objects
-----------
.. sectionauthor:: Raymond D. Hettinger <python@rcn.com>
.. index::
object: set
object: frozenset
.. versionadded:: 2.5
This section details the public API for :class:`set` and :class:`frozenset`
objects. Any functionality not listed below is best accessed using the either
the abstract object protocol (including :c:func:`PyObject_CallMethod`,
:c:func:`PyObject_RichCompareBool`, :c:func:`PyObject_Hash`,
:c:func:`PyObject_Repr`, :c:func:`PyObject_IsTrue`, :c:func:`PyObject_Print`, and
:c:func:`PyObject_GetIter`) or the abstract number protocol (including
:c:func:`PyNumber_And`, :c:func:`PyNumber_Subtract`, :c:func:`PyNumber_Or`,
:c:func:`PyNumber_Xor`, :c:func:`PyNumber_InPlaceAnd`,
:c:func:`PyNumber_InPlaceSubtract`, :c:func:`PyNumber_InPlaceOr`, and
:c:func:`PyNumber_InPlaceXor`).
.. c:type:: PySetObject
This subtype of :c:type:`PyObject` is used to hold the internal data for both
:class:`set` and :class:`frozenset` objects. It is like a :c:type:`PyDictObject`
in that it is a fixed size for small sets (much like tuple storage) and will
point to a separate, variable sized block of memory for medium and large sized
sets (much like list storage). None of the fields of this structure should be
considered public and are subject to change. All access should be done through
the documented API rather than by manipulating the values in the structure.
.. c:var:: PyTypeObject PySet_Type
This is an instance of :c:type:`PyTypeObject` representing the Python
:class:`set` type.
.. c:var:: PyTypeObject PyFrozenSet_Type
This is an instance of :c:type:`PyTypeObject` representing the Python
:class:`frozenset` type.
The following type check macros work on pointers to any Python object. Likewise,
the constructor functions work with any iterable Python object.
.. c:function:: int PySet_Check(PyObject *p)
Return true if *p* is a :class:`set` object or an instance of a subtype.
.. versionadded:: 2.6
.. c:function:: int PyFrozenSet_Check(PyObject *p)
Return true if *p* is a :class:`frozenset` object or an instance of a
subtype.
.. versionadded:: 2.6
.. c:function:: int PyAnySet_Check(PyObject *p)
Return true if *p* is a :class:`set` object, a :class:`frozenset` object, or an
instance of a subtype.
.. c:function:: int PyAnySet_CheckExact(PyObject *p)
Return true if *p* is a :class:`set` object or a :class:`frozenset` object but
not an instance of a subtype.
.. c:function:: int PyFrozenSet_CheckExact(PyObject *p)
Return true if *p* is a :class:`frozenset` object but not an instance of a
subtype.
.. c:function:: PyObject* PySet_New(PyObject *iterable)
Return a new :class:`set` containing objects returned by the *iterable*. The
*iterable* may be *NULL* to create a new empty set. Return the new set on
success or *NULL* on failure. Raise :exc:`TypeError` if *iterable* is not
actually iterable. The constructor is also useful for copying a set
(``c=set(s)``).
.. c:function:: PyObject* PyFrozenSet_New(PyObject *iterable)
Return a new :class:`frozenset` containing objects returned by the *iterable*.
The *iterable* may be *NULL* to create a new empty frozenset. Return the new
set on success or *NULL* on failure. Raise :exc:`TypeError` if *iterable* is
not actually iterable.
.. versionchanged:: 2.6
Now guaranteed to return a brand-new :class:`frozenset`. Formerly,
frozensets of zero-length were a singleton. This got in the way of
building-up new frozensets with :meth:`PySet_Add`.
The following functions and macros are available for instances of :class:`set`
or :class:`frozenset` or instances of their subtypes.
.. c:function:: Py_ssize_t PySet_Size(PyObject *anyset)
.. index:: builtin: len
Return the length of a :class:`set` or :class:`frozenset` object. Equivalent to
``len(anyset)``. Raises a :exc:`PyExc_SystemError` if *anyset* is not a
:class:`set`, :class:`frozenset`, or an instance of a subtype.
.. versionchanged:: 2.5
This function returned an :c:type:`int`. This might require changes in
your code for properly supporting 64-bit systems.
.. c:function:: Py_ssize_t PySet_GET_SIZE(PyObject *anyset)
Macro form of :c:func:`PySet_Size` without error checking.
.. c:function:: int PySet_Contains(PyObject *anyset, PyObject *key)
Return ``1`` if found, ``0`` if not found, and ``-1`` if an error is encountered. Unlike
the Python :meth:`__contains__` method, this function does not automatically
convert unhashable sets into temporary frozensets. Raise a :exc:`TypeError` if
the *key* is unhashable. Raise :exc:`PyExc_SystemError` if *anyset* is not a
:class:`set`, :class:`frozenset`, or an instance of a subtype.
.. c:function:: int PySet_Add(PyObject *set, PyObject *key)
Add *key* to a :class:`set` instance. Does not apply to :class:`frozenset`
instances. Return ``0`` on success or ``-1`` on failure. Raise a :exc:`TypeError` if
the *key* is unhashable. Raise a :exc:`MemoryError` if there is no room to grow.
Raise a :exc:`SystemError` if *set* is not an instance of :class:`set` or its
subtype.
.. versionchanged:: 2.6
Now works with instances of :class:`frozenset` or its subtypes.
Like :c:func:`PyTuple_SetItem` in that it can be used to fill-in the
values of brand new frozensets before they are exposed to other code.
The following functions are available for instances of :class:`set` or its
subtypes but not for instances of :class:`frozenset` or its subtypes.
.. c:function:: int PySet_Discard(PyObject *set, PyObject *key)
Return ``1`` if found and removed, ``0`` if not found (no action taken), and ``-1`` if an
error is encountered. Does not raise :exc:`KeyError` for missing keys. Raise a
:exc:`TypeError` if the *key* is unhashable. Unlike the Python :meth:`~set.discard`
method, this function does not automatically convert unhashable sets into
temporary frozensets. Raise :exc:`PyExc_SystemError` if *set* is not an
instance of :class:`set` or its subtype.
.. c:function:: PyObject* PySet_Pop(PyObject *set)
Return a new reference to an arbitrary object in the *set*, and removes the
object from the *set*. Return *NULL* on failure. Raise :exc:`KeyError` if the
set is empty. Raise a :exc:`SystemError` if *set* is not an instance of
:class:`set` or its subtype.
.. c:function:: int PySet_Clear(PyObject *set)
Empty an existing set of all elements.

79
Doc/c-api/slice.rst Normal file
View File

@@ -0,0 +1,79 @@
.. highlightlang:: c
.. _slice-objects:
Slice Objects
-------------
.. c:var:: PyTypeObject PySlice_Type
.. index:: single: SliceType (in module types)
The type object for slice objects. This is the same as ``slice`` and
``types.SliceType``.
.. c:function:: int PySlice_Check(PyObject *ob)
Return true if *ob* is a slice object; *ob* must not be *NULL*.
.. c:function:: PyObject* PySlice_New(PyObject *start, PyObject *stop, PyObject *step)
Return a new slice object with the given values. The *start*, *stop*, and
*step* parameters are used as the values of the slice object attributes of
the same names. Any of the values may be *NULL*, in which case the
``None`` will be used for the corresponding attribute. Return *NULL* if
the new object could not be allocated.
.. c:function:: int PySlice_GetIndices(PySliceObject *slice, Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step)
Retrieve the start, stop and step indices from the slice object *slice*,
assuming a sequence of length *length*. Treats indices greater than
*length* as errors.
Returns ``0`` on success and ``-1`` on error with no exception set (unless one of
the indices was not :const:`None` and failed to be converted to an integer,
in which case ``-1`` is returned with an exception set).
You probably do not want to use this function. If you want to use slice
objects in versions of Python prior to 2.3, you would probably do well to
incorporate the source of :c:func:`PySlice_GetIndicesEx`, suitably renamed,
in the source of your extension.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *length* and an
:c:type:`int *` type for *start*, *stop*, and *step*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: int PySlice_GetIndicesEx(PySliceObject *slice, Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step, Py_ssize_t *slicelength)
Usable replacement for :c:func:`PySlice_GetIndices`. Retrieve the start,
stop, and step indices from the slice object *slice* assuming a sequence of
length *length*, and store the length of the slice in *slicelength*. Out
of bounds indices are clipped in a manner consistent with the handling of
normal slices.
Returns ``0`` on success and ``-1`` on error with exception set.
.. versionadded:: 2.3
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *length* and an
:c:type:`int *` type for *start*, *stop*, *step*, and *slicelength*. This
might require changes in your code for properly supporting 64-bit
systems.
Ellipsis Object
---------------
.. c:var:: PyObject *Py_Ellipsis
The Python ``Ellipsis`` object. This object has no methods. It needs to be
treated just like any other object with respect to reference counts. Like
:c:data:`Py_None` it is a singleton object.

333
Doc/c-api/string.rst Normal file
View File

@@ -0,0 +1,333 @@
.. highlightlang:: c
.. _stringobjects:
String/Bytes Objects
--------------------
These functions raise :exc:`TypeError` when expecting a string parameter and are
called with a non-string parameter.
.. note::
These functions have been renamed to PyBytes_* in Python 3.x. Unless
otherwise noted, the PyBytes functions available in 3.x are aliased to their
PyString_* equivalents to help porting.
.. index:: object: string
.. c:type:: PyStringObject
This subtype of :c:type:`PyObject` represents a Python string object.
.. c:var:: PyTypeObject PyString_Type
.. index:: single: StringType (in module types)
This instance of :c:type:`PyTypeObject` represents the Python string type; it is
the same object as ``str`` and ``types.StringType`` in the Python layer. .
.. c:function:: int PyString_Check(PyObject *o)
Return true if the object *o* is a string object or an instance of a subtype of
the string type.
.. versionchanged:: 2.2
Allowed subtypes to be accepted.
.. c:function:: int PyString_CheckExact(PyObject *o)
Return true if the object *o* is a string object, but not an instance of a
subtype of the string type.
.. versionadded:: 2.2
.. c:function:: PyObject* PyString_FromString(const char *v)
Return a new string object with a copy of the string *v* as value on success,
and *NULL* on failure. The parameter *v* must not be *NULL*; it will not be
checked.
.. c:function:: PyObject* PyString_FromStringAndSize(const char *v, Py_ssize_t len)
Return a new string object with a copy of the string *v* as value and length
*len* on success, and *NULL* on failure. If *v* is *NULL*, the contents of the
string are uninitialized.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *len*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyString_FromFormat(const char *format, ...)
Take a C :c:func:`printf`\ -style *format* string and a variable number of
arguments, calculate the size of the resulting Python string and return a string
with the values formatted into it. The variable arguments must be C types and
must correspond exactly to the format characters in the *format* string. The
following format characters are allowed:
.. % This should be exactly the same as the table in PyErr_Format.
.. % One should just refer to the other.
.. % The descriptions for %zd and %zu are wrong, but the truth is complicated
.. % because not all compilers support the %z width modifier -- we fake it
.. % when necessary via interpolating PY_FORMAT_SIZE_T.
.. % Similar comments apply to the %ll width modifier and
.. % PY_FORMAT_LONG_LONG.
.. % %u, %lu, %zu should have "new in Python 2.5" blurbs.
+-------------------+---------------+--------------------------------+
| Format Characters | Type | Comment |
+===================+===============+================================+
| :attr:`%%` | *n/a* | The literal % character. |
+-------------------+---------------+--------------------------------+
| :attr:`%c` | int | A single character, |
| | | represented as a C int. |
+-------------------+---------------+--------------------------------+
| :attr:`%d` | int | Exactly equivalent to |
| | | ``printf("%d")``. |
+-------------------+---------------+--------------------------------+
| :attr:`%u` | unsigned int | Exactly equivalent to |
| | | ``printf("%u")``. |
+-------------------+---------------+--------------------------------+
| :attr:`%ld` | long | Exactly equivalent to |
| | | ``printf("%ld")``. |
+-------------------+---------------+--------------------------------+
| :attr:`%lu` | unsigned long | Exactly equivalent to |
| | | ``printf("%lu")``. |
+-------------------+---------------+--------------------------------+
| :attr:`%lld` | long long | Exactly equivalent to |
| | | ``printf("%lld")``. |
+-------------------+---------------+--------------------------------+
| :attr:`%llu` | unsigned | Exactly equivalent to |
| | long long | ``printf("%llu")``. |
+-------------------+---------------+--------------------------------+
| :attr:`%zd` | Py_ssize_t | Exactly equivalent to |
| | | ``printf("%zd")``. |
+-------------------+---------------+--------------------------------+
| :attr:`%zu` | size_t | Exactly equivalent to |
| | | ``printf("%zu")``. |
+-------------------+---------------+--------------------------------+
| :attr:`%i` | int | Exactly equivalent to |
| | | ``printf("%i")``. |
+-------------------+---------------+--------------------------------+
| :attr:`%x` | int | Exactly equivalent to |
| | | ``printf("%x")``. |
+-------------------+---------------+--------------------------------+
| :attr:`%s` | char\* | A null-terminated C character |
| | | array. |
+-------------------+---------------+--------------------------------+
| :attr:`%p` | void\* | The hex representation of a C |
| | | pointer. Mostly equivalent to |
| | | ``printf("%p")`` except that |
| | | it is guaranteed to start with |
| | | the literal ``0x`` regardless |
| | | of what the platform's |
| | | ``printf`` yields. |
+-------------------+---------------+--------------------------------+
An unrecognized format character causes all the rest of the format string to be
copied as-is to the result string, and any extra arguments discarded.
.. note::
The `"%lld"` and `"%llu"` format specifiers are only available
when :const:`HAVE_LONG_LONG` is defined.
.. versionchanged:: 2.7
Support for `"%lld"` and `"%llu"` added.
.. c:function:: PyObject* PyString_FromFormatV(const char *format, va_list vargs)
Identical to :c:func:`PyString_FromFormat` except that it takes exactly two
arguments.
.. c:function:: Py_ssize_t PyString_Size(PyObject *string)
Return the length of the string in string object *string*.
.. versionchanged:: 2.5
This function returned an :c:type:`int` type. This might require changes
in your code for properly supporting 64-bit systems.
.. c:function:: Py_ssize_t PyString_GET_SIZE(PyObject *string)
Macro form of :c:func:`PyString_Size` but without error checking.
.. versionchanged:: 2.5
This macro returned an :c:type:`int` type. This might require changes in
your code for properly supporting 64-bit systems.
.. c:function:: char* PyString_AsString(PyObject *string)
Return a NUL-terminated representation of the contents of *string*. The pointer
refers to the internal buffer of *string*, not a copy. The data must not be
modified in any way, unless the string was just created using
``PyString_FromStringAndSize(NULL, size)``. It must not be deallocated. If
*string* is a Unicode object, this function computes the default encoding of
*string* and operates on that. If *string* is not a string object at all,
:c:func:`PyString_AsString` returns *NULL* and raises :exc:`TypeError`.
.. c:function:: char* PyString_AS_STRING(PyObject *string)
Macro form of :c:func:`PyString_AsString` but without error checking. Only
string objects are supported; no Unicode objects should be passed.
.. c:function:: int PyString_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)
Return a NUL-terminated representation of the contents of the object *obj*
through the output variables *buffer* and *length*.
The function accepts both string and Unicode objects as input. For Unicode
objects it returns the default encoded version of the object. If *length* is
*NULL*, the resulting buffer may not contain NUL characters; if it does, the
function returns ``-1`` and a :exc:`TypeError` is raised.
The buffer refers to an internal string buffer of *obj*, not a copy. The data
must not be modified in any way, unless the string was just created using
``PyString_FromStringAndSize(NULL, size)``. It must not be deallocated. If
*string* is a Unicode object, this function computes the default encoding of
*string* and operates on that. If *string* is not a string object at all,
:c:func:`PyString_AsStringAndSize` returns ``-1`` and raises :exc:`TypeError`.
.. versionchanged:: 2.5
This function used an :c:type:`int *` type for *length*. This might
require changes in your code for properly supporting 64-bit systems.
.. c:function:: void PyString_Concat(PyObject **string, PyObject *newpart)
Create a new string object in *\*string* containing the contents of *newpart*
appended to *string*; the caller will own the new reference. The reference to
the old value of *string* will be stolen. If the new string cannot be created,
the old reference to *string* will still be discarded and the value of
*\*string* will be set to *NULL*; the appropriate exception will be set.
.. c:function:: void PyString_ConcatAndDel(PyObject **string, PyObject *newpart)
Create a new string object in *\*string* containing the contents of *newpart*
appended to *string*. This version decrements the reference count of *newpart*.
.. c:function:: int _PyString_Resize(PyObject **string, Py_ssize_t newsize)
A way to resize a string object even though it is "immutable". Only use this to
build up a brand new string object; don't use this if the string may already be
known in other parts of the code. It is an error to call this function if the
refcount on the input string object is not one. Pass the address of an existing
string object as an lvalue (it may be written into), and the new size desired.
On success, *\*string* holds the resized string object and ``0`` is returned;
the address in *\*string* may differ from its input value. If the reallocation
fails, the original string object at *\*string* is deallocated, *\*string* is
set to *NULL*, a memory exception is set, and ``-1`` is returned.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *newsize*. This might
require changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyString_Format(PyObject *format, PyObject *args)
Return a new string object from *format* and *args*. Analogous to ``format %
args``. The *args* argument must be a tuple or dict.
.. c:function:: void PyString_InternInPlace(PyObject **string)
Intern the argument *\*string* in place. The argument must be the address of a
pointer variable pointing to a Python string object. If there is an existing
interned string that is the same as *\*string*, it sets *\*string* to it
(decrementing the reference count of the old string object and incrementing the
reference count of the interned string object), otherwise it leaves *\*string*
alone and interns it (incrementing its reference count). (Clarification: even
though there is a lot of talk about reference counts, think of this function as
reference-count-neutral; you own the object after the call if and only if you
owned it before the call.)
.. note::
This function is not available in 3.x and does not have a PyBytes alias.
.. c:function:: PyObject* PyString_InternFromString(const char *v)
A combination of :c:func:`PyString_FromString` and
:c:func:`PyString_InternInPlace`, returning either a new string object that has
been interned, or a new ("owned") reference to an earlier interned string object
with the same value.
.. note::
This function is not available in 3.x and does not have a PyBytes alias.
.. c:function:: PyObject* PyString_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)
Create an object by decoding *size* bytes of the encoded buffer *s* using the
codec registered for *encoding*. *encoding* and *errors* have the same meaning
as the parameters of the same name in the :func:`unicode` built-in function.
The codec to be used is looked up using the Python codec registry. Return
*NULL* if an exception was raised by the codec.
.. note::
This function is not available in 3.x and does not have a PyBytes alias.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyString_AsDecodedObject(PyObject *str, const char *encoding, const char *errors)
Decode a string object by passing it to the codec registered for *encoding* and
return the result as Python object. *encoding* and *errors* have the same
meaning as the parameters of the same name in the string :meth:`encode` method.
The codec to be used is looked up using the Python codec registry. Return *NULL*
if an exception was raised by the codec.
.. note::
This function is not available in 3.x and does not have a PyBytes alias.
.. c:function:: PyObject* PyString_Encode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)
Encode the :c:type:`char` buffer of the given size by passing it to the codec
registered for *encoding* and return a Python object. *encoding* and *errors*
have the same meaning as the parameters of the same name in the string
:meth:`encode` method. The codec to be used is looked up using the Python codec
registry. Return *NULL* if an exception was raised by the codec.
.. note::
This function is not available in 3.x and does not have a PyBytes alias.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyString_AsEncodedObject(PyObject *str, const char *encoding, const char *errors)
Encode a string object using the codec registered for *encoding* and return the
result as Python object. *encoding* and *errors* have the same meaning as the
parameters of the same name in the string :meth:`encode` method. The codec to be
used is looked up using the Python codec registry. Return *NULL* if an exception
was raised by the codec.
.. note::
This function is not available in 3.x and does not have a PyBytes alias.

368
Doc/c-api/structures.rst Normal file
View File

@@ -0,0 +1,368 @@
.. highlightlang:: c
.. _common-structs:
Common Object Structures
========================
There are a large number of structures which are used in the definition of
object types for Python. This section describes these structures and how they
are used.
All Python objects ultimately share a small number of fields at the beginning
of the object's representation in memory. These are represented by the
:c:type:`PyObject` and :c:type:`PyVarObject` types, which are defined, in turn,
by the expansions of some macros also used, whether directly or indirectly, in
the definition of all other Python objects.
.. c:type:: PyObject
All object types are extensions of this type. This is a type which
contains the information Python needs to treat a pointer to an object as an
object. In a normal "release" build, it contains only the object's
reference count and a pointer to the corresponding type object. It
corresponds to the fields defined by the expansion of the ``PyObject_HEAD``
macro.
.. c:type:: PyVarObject
This is an extension of :c:type:`PyObject` that adds the :attr:`ob_size`
field. This is only used for objects that have some notion of *length*.
This type does not often appear in the Python/C API. It corresponds to the
fields defined by the expansion of the ``PyObject_VAR_HEAD`` macro.
These macros are used in the definition of :c:type:`PyObject` and
:c:type:`PyVarObject`:
.. c:macro:: PyObject_HEAD
This is a macro which expands to the declarations of the fields of the
:c:type:`PyObject` type; it is used when declaring new types which represent
objects without a varying length. The specific fields it expands to depend
on the definition of :c:macro:`Py_TRACE_REFS`. By default, that macro is
not defined, and :c:macro:`PyObject_HEAD` expands to::
Py_ssize_t ob_refcnt;
PyTypeObject *ob_type;
When :c:macro:`Py_TRACE_REFS` is defined, it expands to::
PyObject *_ob_next, *_ob_prev;
Py_ssize_t ob_refcnt;
PyTypeObject *ob_type;
.. c:macro:: PyObject_VAR_HEAD
This is a macro which expands to the declarations of the fields of the
:c:type:`PyVarObject` type; it is used when declaring new types which
represent objects with a length that varies from instance to instance.
This macro always expands to::
PyObject_HEAD
Py_ssize_t ob_size;
Note that :c:macro:`PyObject_HEAD` is part of the expansion, and that its own
expansion varies depending on the definition of :c:macro:`Py_TRACE_REFS`.
.. c:macro:: Py_TYPE(o)
This macro is used to access the :attr:`ob_type` member of a Python object.
It expands to::
(((PyObject*)(o))->ob_type)
.. versionadded:: 2.6
.. c:macro:: Py_REFCNT(o)
This macro is used to access the :attr:`ob_refcnt` member of a Python
object.
It expands to::
(((PyObject*)(o))->ob_refcnt)
.. versionadded:: 2.6
.. c:macro:: Py_SIZE(o)
This macro is used to access the :attr:`ob_size` member of a Python object.
It expands to::
(((PyVarObject*)(o))->ob_size)
.. versionadded:: 2.6
.. c:macro:: PyObject_HEAD_INIT(type)
This is a macro which expands to initialization values for a new
:c:type:`PyObject` type. This macro expands to::
_PyObject_EXTRA_INIT
1, type,
.. c:macro:: PyVarObject_HEAD_INIT(type, size)
This is a macro which expands to initialization values for a new
:c:type:`PyVarObject` type, including the :attr:`ob_size` field.
This macro expands to::
_PyObject_EXTRA_INIT
1, type, size,
.. c:type:: PyCFunction
Type of the functions used to implement most Python callables in C.
Functions of this type take two :c:type:`PyObject\*` parameters and return
one such value. If the return value is *NULL*, an exception shall have
been set. If not *NULL*, the return value is interpreted as the return
value of the function as exposed in Python. The function must return a new
reference.
.. c:type:: PyMethodDef
Structure used to describe a method of an extension type. This structure has
four fields:
+------------------+-------------+-------------------------------+
| Field | C Type | Meaning |
+==================+=============+===============================+
| :attr:`ml_name` | char \* | name of the method |
+------------------+-------------+-------------------------------+
| :attr:`ml_meth` | PyCFunction | pointer to the C |
| | | implementation |
+------------------+-------------+-------------------------------+
| :attr:`ml_flags` | int | flag bits indicating how the |
| | | call should be constructed |
+------------------+-------------+-------------------------------+
| :attr:`ml_doc` | char \* | points to the contents of the |
| | | docstring |
+------------------+-------------+-------------------------------+
The :attr:`ml_meth` is a C function pointer. The functions may be of different
types, but they always return :c:type:`PyObject\*`. If the function is not of
the :c:type:`PyCFunction`, the compiler will require a cast in the method table.
Even though :c:type:`PyCFunction` defines the first parameter as
:c:type:`PyObject\*`, it is common that the method implementation uses the
specific C type of the *self* object.
The :attr:`ml_flags` field is a bitfield which can include the following flags.
The individual flags indicate either a calling convention or a binding
convention. Of the calling convention flags, only :const:`METH_VARARGS` and
:const:`METH_KEYWORDS` can be combined. Any of the calling convention flags
can be combined with a binding flag.
.. data:: METH_VARARGS
This is the typical calling convention, where the methods have the type
:c:type:`PyCFunction`. The function expects two :c:type:`PyObject\*` values.
The first one is the *self* object for methods; for module functions, it is
the module object. The second parameter (often called *args*) is a tuple
object representing all arguments. This parameter is typically processed
using :c:func:`PyArg_ParseTuple` or :c:func:`PyArg_UnpackTuple`.
.. data:: METH_KEYWORDS
Methods with these flags must be of type :c:type:`PyCFunctionWithKeywords`.
The function expects three parameters: *self*, *args*, and a dictionary of
all the keyword arguments. The flag is typically combined with
:const:`METH_VARARGS`, and the parameters are typically processed using
:c:func:`PyArg_ParseTupleAndKeywords`.
.. data:: METH_NOARGS
Methods without parameters don't need to check whether arguments are given if
they are listed with the :const:`METH_NOARGS` flag. They need to be of type
:c:type:`PyCFunction`. The first parameter is typically named ``self`` and
will hold a reference to the module or object instance. In all cases the
second parameter will be *NULL*.
.. data:: METH_O
Methods with a single object argument can be listed with the :const:`METH_O`
flag, instead of invoking :c:func:`PyArg_ParseTuple` with a ``"O"`` argument.
They have the type :c:type:`PyCFunction`, with the *self* parameter, and a
:c:type:`PyObject\*` parameter representing the single argument.
.. data:: METH_OLDARGS
This calling convention is deprecated. The method must be of type
:c:type:`PyCFunction`. The second argument is *NULL* if no arguments are
given, a single object if exactly one argument is given, and a tuple of
objects if more than one argument is given. There is no way for a function
using this convention to distinguish between a call with multiple arguments
and a call with a tuple as the only argument.
These two constants are not used to indicate the calling convention but the
binding when use with methods of classes. These may not be used for functions
defined for modules. At most one of these flags may be set for any given
method.
.. data:: METH_CLASS
.. index:: builtin: classmethod
The method will be passed the type object as the first parameter rather
than an instance of the type. This is used to create *class methods*,
similar to what is created when using the :func:`classmethod` built-in
function.
.. versionadded:: 2.3
.. data:: METH_STATIC
.. index:: builtin: staticmethod
The method will be passed *NULL* as the first parameter rather than an
instance of the type. This is used to create *static methods*, similar to
what is created when using the :func:`staticmethod` built-in function.
.. versionadded:: 2.3
One other constant controls whether a method is loaded in place of another
definition with the same method name.
.. data:: METH_COEXIST
The method will be loaded in place of existing definitions. Without
*METH_COEXIST*, the default is to skip repeated definitions. Since slot
wrappers are loaded before the method table, the existence of a
*sq_contains* slot, for example, would generate a wrapped method named
:meth:`__contains__` and preclude the loading of a corresponding
PyCFunction with the same name. With the flag defined, the PyCFunction
will be loaded in place of the wrapper object and will co-exist with the
slot. This is helpful because calls to PyCFunctions are optimized more
than wrapper object calls.
.. versionadded:: 2.4
.. c:type:: PyMemberDef
Structure which describes an attribute of a type which corresponds to a C
struct member. Its fields are:
+------------------+-------------+-------------------------------+
| Field | C Type | Meaning |
+==================+=============+===============================+
| :attr:`name` | char \* | name of the member |
+------------------+-------------+-------------------------------+
| :attr:`!type` | int | the type of the member in the |
| | | C struct |
+------------------+-------------+-------------------------------+
| :attr:`offset` | Py_ssize_t | the offset in bytes that the |
| | | member is located on the |
| | | type's object struct |
+------------------+-------------+-------------------------------+
| :attr:`flags` | int | flag bits indicating if the |
| | | field should be read-only or |
| | | writable |
+------------------+-------------+-------------------------------+
| :attr:`doc` | char \* | points to the contents of the |
| | | docstring |
+------------------+-------------+-------------------------------+
:attr:`!type` can be one of many ``T_`` macros corresponding to various C
types. When the member is accessed in Python, it will be converted to the
equivalent Python type.
=============== ==================
Macro name C type
=============== ==================
T_SHORT short
T_INT int
T_LONG long
T_FLOAT float
T_DOUBLE double
T_STRING char \*
T_OBJECT PyObject \*
T_OBJECT_EX PyObject \*
T_CHAR char
T_BYTE char
T_UBYTE unsigned char
T_UINT unsigned int
T_USHORT unsigned short
T_ULONG unsigned long
T_BOOL char
T_LONGLONG long long
T_ULONGLONG unsigned long long
T_PYSSIZET Py_ssize_t
=============== ==================
:c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX` differ in that
:c:macro:`T_OBJECT` returns ``None`` if the member is *NULL* and
:c:macro:`T_OBJECT_EX` raises an :exc:`AttributeError`. Try to use
:c:macro:`T_OBJECT_EX` over :c:macro:`T_OBJECT` because :c:macro:`T_OBJECT_EX`
handles use of the :keyword:`del` statement on that attribute more correctly
than :c:macro:`T_OBJECT`.
:attr:`flags` can be ``0`` for write and read access or :c:macro:`READONLY` for
read-only access. Using :c:macro:`T_STRING` for :attr:`type` implies
:c:macro:`READONLY`. Only :c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX`
members can be deleted. (They are set to *NULL*).
.. c:type:: PyGetSetDef
Structure to define property-like access for a type. See also description of
the :c:member:`PyTypeObject.tp_getset` slot.
+-------------+------------------+-----------------------------------+
| Field | C Type | Meaning |
+=============+==================+===================================+
| name | char \* | attribute name |
+-------------+------------------+-----------------------------------+
| get | getter | C Function to get the attribute |
+-------------+------------------+-----------------------------------+
| set | setter | optional C function to set or |
| | | delete the attribute, if omitted |
| | | the attribute is readonly |
+-------------+------------------+-----------------------------------+
| doc | char \* | optional docstring |
+-------------+------------------+-----------------------------------+
| closure | void \* | optional function pointer, |
| | | providing additional data for |
| | | getter and setter |
+-------------+------------------+-----------------------------------+
The ``get`` function takes one :c:type:`PyObject\*` parameter (the
instance) and a function pointer (the associated ``closure``)::
typedef PyObject *(*getter)(PyObject *, void *);
It should return a new reference on success or *NULL* with a set exception
on failure.
``set`` functions take two :c:type:`PyObject\*` parameters (the instance and
the value to be set) and a function pointer (the associated ``closure``)::
typedef int (*setter)(PyObject *, PyObject *, void *);
In case the attribute should be deleted the second parameter is *NULL*.
Should return ``0`` on success or ``-1`` with a set exception on failure.
.. c:function:: PyObject* Py_FindMethod(PyMethodDef table[], PyObject *ob, char *name)
Return a bound method object for an extension type implemented in C. This
can be useful in the implementation of a :c:member:`~PyTypeObject.tp_getattro` or
:c:member:`~PyTypeObject.tp_getattr` handler that does not use the
:c:func:`PyObject_GenericGetAttr` function.

151
Doc/c-api/sys.rst Normal file
View File

@@ -0,0 +1,151 @@
.. highlightlang:: c
.. _os:
Operating System Utilities
==========================
.. c:function:: int Py_FdIsInteractive(FILE *fp, const char *filename)
Return true (nonzero) if the standard I/O file *fp* with name *filename* is
deemed interactive. This is the case for files for which ``isatty(fileno(fp))``
is true. If the global flag :c:data:`Py_InteractiveFlag` is true, this function
also returns true if the *filename* pointer is *NULL* or if the name is equal to
one of the strings ``'<stdin>'`` or ``'???'``.
.. c:function:: void PyOS_AfterFork()
Function to update some internal state after a process fork; this should be
called in the new process if the Python interpreter will continue to be used.
If a new executable is loaded into the new process, this function does not need
to be called.
.. c:function:: int PyOS_CheckStack()
Return true when the interpreter runs out of stack space. This is a reliable
check, but is only available when :const:`USE_STACKCHECK` is defined (currently
on Windows using the Microsoft Visual C++ compiler). :const:`USE_STACKCHECK`
will be defined automatically; you should never change the definition in your
own code.
.. c:function:: PyOS_sighandler_t PyOS_getsig(int i)
Return the current signal handler for signal *i*. This is a thin wrapper around
either :c:func:`sigaction` or :c:func:`signal`. Do not call those functions
directly! :c:type:`PyOS_sighandler_t` is a typedef alias for :c:type:`void
(\*)(int)`.
.. c:function:: PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)
Set the signal handler for signal *i* to be *h*; return the old signal handler.
This is a thin wrapper around either :c:func:`sigaction` or :c:func:`signal`. Do
not call those functions directly! :c:type:`PyOS_sighandler_t` is a typedef
alias for :c:type:`void (\*)(int)`.
.. _systemfunctions:
System Functions
================
These are utility functions that make functionality from the :mod:`sys` module
accessible to C code. They all work with the current interpreter thread's
:mod:`sys` module's dict, which is contained in the internal thread state structure.
.. c:function:: PyObject *PySys_GetObject(char *name)
Return the object *name* from the :mod:`sys` module or *NULL* if it does
not exist, without setting an exception.
.. c:function:: FILE *PySys_GetFile(char *name, FILE *def)
Return the :c:type:`FILE*` associated with the object *name* in the
:mod:`sys` module, or *def* if *name* is not in the module or is not associated
with a :c:type:`FILE*`.
.. c:function:: int PySys_SetObject(char *name, PyObject *v)
Set *name* in the :mod:`sys` module to *v* unless *v* is *NULL*, in which
case *name* is deleted from the sys module. Returns ``0`` on success, ``-1``
on error.
.. c:function:: void PySys_ResetWarnOptions()
Reset :data:`sys.warnoptions` to an empty list.
.. c:function:: void PySys_AddWarnOption(char *s)
Append *s* to :data:`sys.warnoptions`.
.. c:function:: void PySys_SetPath(char *path)
Set :data:`sys.path` to a list object of paths found in *path* which should
be a list of paths separated with the platform's search path delimiter
(``:`` on Unix, ``;`` on Windows).
.. c:function:: void PySys_WriteStdout(const char *format, ...)
Write the output string described by *format* to :data:`sys.stdout`. No
exceptions are raised, even if truncation occurs (see below).
*format* should limit the total size of the formatted output string to
1000 bytes or less -- after 1000 bytes, the output string is truncated.
In particular, this means that no unrestricted "%s" formats should occur;
these should be limited using "%.<N>s" where <N> is a decimal number
calculated so that <N> plus the maximum size of other formatted text does not
exceed 1000 bytes. Also watch out for "%f", which can print hundreds of
digits for very large numbers.
If a problem occurs, or :data:`sys.stdout` is unset, the formatted message
is written to the real (C level) *stdout*.
.. c:function:: void PySys_WriteStderr(const char *format, ...)
As above, but write to :data:`sys.stderr` or *stderr* instead.
.. _processcontrol:
Process Control
===============
.. c:function:: void Py_FatalError(const char *message)
.. index:: single: abort()
Print a fatal error message and kill the process. No cleanup is performed.
This function should only be invoked when a condition is detected that would
make it dangerous to continue using the Python interpreter; e.g., when the
object administration appears to be corrupted. On Unix, the standard C library
function :c:func:`abort` is called which will attempt to produce a :file:`core`
file.
.. c:function:: void Py_Exit(int status)
.. index::
single: Py_Finalize()
single: exit()
Exit the current process. This calls :c:func:`Py_Finalize` and then calls the
standard C library function ``exit(status)``.
.. c:function:: int Py_AtExit(void (*func) ())
.. index::
single: Py_Finalize()
single: cleanup functions
Register a cleanup function to be called by :c:func:`Py_Finalize`. The cleanup
function will be called with no arguments and should return no value. At most
32 cleanup functions can be registered. When the registration is successful,
:c:func:`Py_AtExit` returns ``0``; on failure, it returns ``-1``. The cleanup
function registered last is called first. Each cleanup function will be called
at most once. Since Python's internal finalization will have completed before
the cleanup function, no Python APIs should be called by *func*.

170
Doc/c-api/tuple.rst Normal file
View File

@@ -0,0 +1,170 @@
.. highlightlang:: c
.. _tupleobjects:
Tuple Objects
-------------
.. index:: object: tuple
.. c:type:: PyTupleObject
This subtype of :c:type:`PyObject` represents a Python tuple object.
.. c:var:: PyTypeObject PyTuple_Type
.. index:: single: TupleType (in module types)
This instance of :c:type:`PyTypeObject` represents the Python tuple type; it is
the same object as ``tuple`` and ``types.TupleType`` in the Python layer..
.. c:function:: int PyTuple_Check(PyObject *p)
Return true if *p* is a tuple object or an instance of a subtype of the tuple
type.
.. versionchanged:: 2.2
Allowed subtypes to be accepted.
.. c:function:: int PyTuple_CheckExact(PyObject *p)
Return true if *p* is a tuple object, but not an instance of a subtype of the
tuple type.
.. versionadded:: 2.2
.. c:function:: PyObject* PyTuple_New(Py_ssize_t len)
Return a new tuple object of size *len*, or *NULL* on failure.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *len*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyTuple_Pack(Py_ssize_t n, ...)
Return a new tuple object of size *n*, or *NULL* on failure. The tuple values
are initialized to the subsequent *n* C arguments pointing to Python objects.
``PyTuple_Pack(2, a, b)`` is equivalent to ``Py_BuildValue("(OO)", a, b)``.
.. versionadded:: 2.4
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *n*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: Py_ssize_t PyTuple_Size(PyObject *p)
Take a pointer to a tuple object, and return the size of that tuple.
.. versionchanged:: 2.5
This function returned an :c:type:`int` type. This might require changes
in your code for properly supporting 64-bit systems.
.. c:function:: Py_ssize_t PyTuple_GET_SIZE(PyObject *p)
Return the size of the tuple *p*, which must be non-*NULL* and point to a tuple;
no error checking is performed.
.. versionchanged:: 2.5
This function returned an :c:type:`int` type. This might require changes
in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyTuple_GetItem(PyObject *p, Py_ssize_t pos)
Return the object at position *pos* in the tuple pointed to by *p*. If *pos* is
out of bounds, return *NULL* and set an :exc:`IndexError` exception.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *pos*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)
Like :c:func:`PyTuple_GetItem`, but does no checking of its arguments.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *pos*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high)
Return the slice of the tuple pointed to by *p* between *low* and *high*,
or *NULL* on failure. This is the equivalent of the Python expression
``p[low:high]``. Indexing from the end of the list is not supported.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *low* and *high*. This might
require changes in your code for properly supporting 64-bit systems.
.. c:function:: int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)
Insert a reference to object *o* at position *pos* of the tuple pointed to by
*p*. Return ``0`` on success. If *pos* is out of bounds, return ``-1``
and set an :exc:`IndexError` exception.
.. note::
This function "steals" a reference to *o* and discards a reference to
an item already in the tuple at the affected position.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *pos*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: void PyTuple_SET_ITEM(PyObject *p, Py_ssize_t pos, PyObject *o)
Like :c:func:`PyTuple_SetItem`, but does no error checking, and should *only* be
used to fill in brand new tuples.
.. note::
This macro "steals" a reference to *o*, and, unlike
:c:func:`PyTuple_SetItem`, does *not* discard a reference to any item that
is being replaced; any reference in the tuple at position *pos* will be
leaked.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *pos*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize)
Can be used to resize a tuple. *newsize* will be the new length of the tuple.
Because tuples are *supposed* to be immutable, this should only be used if there
is only one reference to the object. Do *not* use this if the tuple may already
be known to some other part of the code. The tuple will always grow or shrink
at the end. Think of this as destroying the old tuple and creating a new one,
only more efficiently. Returns ``0`` on success. Client code should never
assume that the resulting value of ``*p`` will be the same as before calling
this function. If the object referenced by ``*p`` is replaced, the original
``*p`` is destroyed. On failure, returns ``-1`` and sets ``*p`` to *NULL*, and
raises :exc:`MemoryError` or :exc:`SystemError`.
.. versionchanged:: 2.2
Removed unused third parameter, *last_is_sticky*.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *newsize*. This might
require changes in your code for properly supporting 64-bit systems.
.. c:function:: int PyTuple_ClearFreeList()
Clear the free list. Return the total number of freed items.
.. versionadded:: 2.6

101
Doc/c-api/type.rst Normal file
View File

@@ -0,0 +1,101 @@
.. highlightlang:: c
.. _typeobjects:
Type Objects
------------
.. index:: object: type
.. c:type:: PyTypeObject
The C structure of the objects used to describe built-in types.
.. c:var:: PyObject* PyType_Type
.. index:: single: TypeType (in module types)
This is the type object for type objects; it is the same object as ``type`` and
``types.TypeType`` in the Python layer.
.. c:function:: int PyType_Check(PyObject *o)
Return true if the object *o* is a type object, including instances of types
derived from the standard type object. Return false in all other cases.
.. c:function:: int PyType_CheckExact(PyObject *o)
Return true if the object *o* is a type object, but not a subtype of the
standard type object. Return false in all other cases.
.. versionadded:: 2.2
.. c:function:: unsigned int PyType_ClearCache()
Clear the internal lookup cache. Return the current version tag.
.. versionadded:: 2.6
.. c:function:: void PyType_Modified(PyTypeObject *type)
Invalidate the internal lookup cache for the type and all of its
subtypes. This function must be called after any manual
modification of the attributes or base classes of the type.
.. versionadded:: 2.6
.. c:function:: int PyType_HasFeature(PyObject *o, int feature)
Return true if the type object *o* sets the feature *feature*. Type features
are denoted by single bit flags.
.. c:function:: int PyType_IS_GC(PyObject *o)
Return true if the type object includes support for the cycle detector; this
tests the type flag :const:`Py_TPFLAGS_HAVE_GC`.
.. versionadded:: 2.0
.. c:function:: int PyType_IsSubtype(PyTypeObject *a, PyTypeObject *b)
Return true if *a* is a subtype of *b*.
.. versionadded:: 2.2
This function only checks for actual subtypes, which means that
:meth:`~class.__subclasscheck__` is not called on *b*. Call
:c:func:`PyObject_IsSubclass` to do the same check that :func:`issubclass`
would do.
.. c:function:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
.. versionadded:: 2.2
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *nitems*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyType_GenericNew(PyTypeObject *type, PyObject *args, PyObject *kwds)
.. versionadded:: 2.2
.. c:function:: int PyType_Ready(PyTypeObject *type)
Finalize a type object. This should be called on all type objects to finish
their initialization. This function is responsible for adding inherited slots
from a type's base class. Return ``0`` on success, or return ``-1`` and sets an
exception on error.
.. versionadded:: 2.2

1443
Doc/c-api/typeobj.rst Normal file
View File

File diff suppressed because it is too large Load Diff

1120
Doc/c-api/unicode.rst Normal file
View File

File diff suppressed because it is too large Load Diff

22
Doc/c-api/utilities.rst Normal file
View File

@@ -0,0 +1,22 @@
.. highlightlang:: c
.. _utilities:
*********
Utilities
*********
The functions in this chapter perform various utility tasks, ranging from
helping C code be more portable across platforms, using Python modules from C,
and parsing function arguments and constructing Python values from C values.
.. toctree::
sys.rst
import.rst
marshal.rst
arg.rst
conversion.rst
reflection.rst
codec.rst

323
Doc/c-api/veryhigh.rst Normal file
View File

@@ -0,0 +1,323 @@
.. highlightlang:: c
.. _veryhigh:
*************************
The Very High Level Layer
*************************
The functions in this chapter will let you execute Python source code given in a
file or a buffer, but they will not let you interact in a more detailed way with
the interpreter.
Several of these functions accept a start symbol from the grammar as a
parameter. The available start symbols are :const:`Py_eval_input`,
:const:`Py_file_input`, and :const:`Py_single_input`. These are described
following the functions which accept them as parameters.
Note also that several of these functions take :c:type:`FILE\*` parameters. One
particular issue which needs to be handled carefully is that the :c:type:`FILE`
structure for different C libraries can be different and incompatible. Under
Windows (at least), it is possible for dynamically linked extensions to actually
use different libraries, so care should be taken that :c:type:`FILE\*` parameters
are only passed to these functions if it is certain that they were created by
the same library that the Python runtime is using.
.. c:function:: int Py_Main(int argc, char **argv)
The main program for the standard interpreter. This is made available for
programs which embed Python. The *argc* and *argv* parameters should be
prepared exactly as those which are passed to a C program's :c:func:`main`
function. It is important to note that the argument list may be modified (but
the contents of the strings pointed to by the argument list are not). The return
value will be ``0`` if the interpreter exits normally (ie, without an
exception), ``1`` if the interpreter exits due to an exception, or ``2``
if the parameter list does not represent a valid Python command line.
Note that if an otherwise unhandled :exc:`SystemExit` is raised, this
function will not return ``1``, but exit the process, as long as
``Py_InspectFlag`` is not set.
.. c:function:: int PyRun_AnyFile(FILE *fp, const char *filename)
This is a simplified interface to :c:func:`PyRun_AnyFileExFlags` below, leaving
*closeit* set to ``0`` and *flags* set to *NULL*.
.. c:function:: int PyRun_AnyFileFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)
This is a simplified interface to :c:func:`PyRun_AnyFileExFlags` below, leaving
the *closeit* argument set to ``0``.
.. c:function:: int PyRun_AnyFileEx(FILE *fp, const char *filename, int closeit)
This is a simplified interface to :c:func:`PyRun_AnyFileExFlags` below, leaving
the *flags* argument set to *NULL*.
.. c:function:: int PyRun_AnyFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)
If *fp* refers to a file associated with an interactive device (console or
terminal input or Unix pseudo-terminal), return the value of
:c:func:`PyRun_InteractiveLoop`, otherwise return the result of
:c:func:`PyRun_SimpleFile`. If *filename* is *NULL*, this function uses
``"???"`` as the filename.
.. c:function:: int PyRun_SimpleString(const char *command)
This is a simplified interface to :c:func:`PyRun_SimpleStringFlags` below,
leaving the *PyCompilerFlags\** argument set to NULL.
.. c:function:: int PyRun_SimpleStringFlags(const char *command, PyCompilerFlags *flags)
Executes the Python source code from *command* in the :mod:`__main__` module
according to the *flags* argument. If :mod:`__main__` does not already exist, it
is created. Returns ``0`` on success or ``-1`` if an exception was raised. If
there was an error, there is no way to get the exception information. For the
meaning of *flags*, see below.
Note that if an otherwise unhandled :exc:`SystemExit` is raised, this
function will not return ``-1``, but exit the process, as long as
``Py_InspectFlag`` is not set.
.. c:function:: int PyRun_SimpleFile(FILE *fp, const char *filename)
This is a simplified interface to :c:func:`PyRun_SimpleFileExFlags` below,
leaving *closeit* set to ``0`` and *flags* set to *NULL*.
.. c:function:: int PyRun_SimpleFileFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)
This is a simplified interface to :c:func:`PyRun_SimpleFileExFlags` below,
leaving *closeit* set to ``0``.
.. c:function:: int PyRun_SimpleFileEx(FILE *fp, const char *filename, int closeit)
This is a simplified interface to :c:func:`PyRun_SimpleFileExFlags` below,
leaving *flags* set to *NULL*.
.. c:function:: int PyRun_SimpleFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)
Similar to :c:func:`PyRun_SimpleStringFlags`, but the Python source code is read
from *fp* instead of an in-memory string. *filename* should be the name of the
file. If *closeit* is true, the file is closed before PyRun_SimpleFileExFlags
returns.
.. c:function:: int PyRun_InteractiveOne(FILE *fp, const char *filename)
This is a simplified interface to :c:func:`PyRun_InteractiveOneFlags` below,
leaving *flags* set to *NULL*.
.. c:function:: int PyRun_InteractiveOneFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)
Read and execute a single statement from a file associated with an
interactive device according to the *flags* argument. The user will be
prompted using ``sys.ps1`` and ``sys.ps2``. Returns ``0`` when the input was
executed successfully, ``-1`` if there was an exception, or an error code
from the :file:`errcode.h` include file distributed as part of Python if
there was a parse error. (Note that :file:`errcode.h` is not included by
:file:`Python.h`, so must be included specifically if needed.)
.. c:function:: int PyRun_InteractiveLoop(FILE *fp, const char *filename)
This is a simplified interface to :c:func:`PyRun_InteractiveLoopFlags` below,
leaving *flags* set to *NULL*.
.. c:function:: int PyRun_InteractiveLoopFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)
Read and execute statements from a file associated with an interactive device
until EOF is reached. The user will be prompted using ``sys.ps1`` and
``sys.ps2``. Returns ``0`` at EOF.
.. c:function:: struct _node* PyParser_SimpleParseString(const char *str, int start)
This is a simplified interface to
:c:func:`PyParser_SimpleParseStringFlagsFilename` below, leaving *filename* set
to *NULL* and *flags* set to ``0``.
.. c:function:: struct _node* PyParser_SimpleParseStringFlags( const char *str, int start, int flags)
This is a simplified interface to
:c:func:`PyParser_SimpleParseStringFlagsFilename` below, leaving *filename* set
to *NULL*.
.. c:function:: struct _node* PyParser_SimpleParseStringFlagsFilename( const char *str, const char *filename, int start, int flags)
Parse Python source code from *str* using the start token *start* according to
the *flags* argument. The result can be used to create a code object which can
be evaluated efficiently. This is useful if a code fragment must be evaluated
many times.
.. c:function:: struct _node* PyParser_SimpleParseFile(FILE *fp, const char *filename, int start)
This is a simplified interface to :c:func:`PyParser_SimpleParseFileFlags` below,
leaving *flags* set to ``0``.
.. c:function:: struct _node* PyParser_SimpleParseFileFlags(FILE *fp, const char *filename, int start, int flags)
Similar to :c:func:`PyParser_SimpleParseStringFlagsFilename`, but the Python
source code is read from *fp* instead of an in-memory string.
.. c:function:: PyObject* PyRun_String(const char *str, int start, PyObject *globals, PyObject *locals)
This is a simplified interface to :c:func:`PyRun_StringFlags` below, leaving
*flags* set to *NULL*.
.. c:function:: PyObject* PyRun_StringFlags(const char *str, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)
Execute Python source code from *str* in the context specified by the
dictionaries *globals* and *locals* with the compiler flags specified by
*flags*. The parameter *start* specifies the start token that should be used to
parse the source code.
Returns the result of executing the code as a Python object, or *NULL* if an
exception was raised.
.. c:function:: PyObject* PyRun_File(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals)
This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving
*closeit* set to ``0`` and *flags* set to *NULL*.
.. c:function:: PyObject* PyRun_FileEx(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit)
This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving
*flags* set to *NULL*.
.. c:function:: PyObject* PyRun_FileFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)
This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving
*closeit* set to ``0``.
.. c:function:: PyObject* PyRun_FileExFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit, PyCompilerFlags *flags)
Similar to :c:func:`PyRun_StringFlags`, but the Python source code is read from
*fp* instead of an in-memory string. *filename* should be the name of the file.
If *closeit* is true, the file is closed before :c:func:`PyRun_FileExFlags`
returns.
.. c:function:: PyObject* Py_CompileString(const char *str, const char *filename, int start)
This is a simplified interface to :c:func:`Py_CompileStringFlags` below, leaving
*flags* set to *NULL*.
.. c:function:: PyObject* Py_CompileStringFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags)
Parse and compile the Python source code in *str*, returning the resulting code
object. The start token is given by *start*; this can be used to constrain the
code which can be compiled and should be :const:`Py_eval_input`,
:const:`Py_file_input`, or :const:`Py_single_input`. The filename specified by
*filename* is used to construct the code object and may appear in tracebacks or
:exc:`SyntaxError` exception messages. This returns *NULL* if the code cannot
be parsed or compiled.
.. c:function:: PyObject* PyEval_EvalCode(PyCodeObject *co, PyObject *globals, PyObject *locals)
This is a simplified interface to :c:func:`PyEval_EvalCodeEx`, with just
the code object, and the dictionaries of global and local variables.
The other arguments are set to *NULL*.
.. c:function:: PyObject* PyEval_EvalCodeEx(PyCodeObject *co, PyObject *globals, PyObject *locals, PyObject **args, int argcount, PyObject **kws, int kwcount, PyObject **defs, int defcount, PyObject *closure)
Evaluate a precompiled code object, given a particular environment for its
evaluation. This environment consists of dictionaries of global and local
variables, arrays of arguments, keywords and defaults, and a closure tuple of
cells.
.. c:function:: PyObject* PyEval_EvalFrame(PyFrameObject *f)
Evaluate an execution frame. This is a simplified interface to
PyEval_EvalFrameEx, for backward compatibility.
.. c:function:: PyObject* PyEval_EvalFrameEx(PyFrameObject *f, int throwflag)
This is the main, unvarnished function of Python interpretation. It is
literally 2000 lines long. The code object associated with the execution
frame *f* is executed, interpreting bytecode and executing calls as needed.
The additional *throwflag* parameter can mostly be ignored - if true, then
it causes an exception to immediately be thrown; this is used for the
:meth:`~generator.throw` methods of generator objects.
.. c:function:: int PyEval_MergeCompilerFlags(PyCompilerFlags *cf)
This function changes the flags of the current evaluation frame, and returns
true on success, false on failure.
.. c:var:: int Py_eval_input
.. index:: single: Py_CompileString()
The start symbol from the Python grammar for isolated expressions; for use with
:c:func:`Py_CompileString`.
.. c:var:: int Py_file_input
.. index:: single: Py_CompileString()
The start symbol from the Python grammar for sequences of statements as read
from a file or other source; for use with :c:func:`Py_CompileString`. This is
the symbol to use when compiling arbitrarily long Python source code.
.. c:var:: int Py_single_input
.. index:: single: Py_CompileString()
The start symbol from the Python grammar for a single statement; for use with
:c:func:`Py_CompileString`. This is the symbol used for the interactive
interpreter loop.
.. c:type:: struct PyCompilerFlags
This is the structure used to hold compiler flags. In cases where code is only
being compiled, it is passed as ``int flags``, and in cases where code is being
executed, it is passed as ``PyCompilerFlags *flags``. In this case, ``from
__future__ import`` can modify *flags*.
Whenever ``PyCompilerFlags *flags`` is *NULL*, :attr:`cf_flags` is treated as
equal to ``0``, and any modification due to ``from __future__ import`` is
discarded. ::
struct PyCompilerFlags {
int cf_flags;
}
.. c:var:: int CO_FUTURE_DIVISION
This bit can be set in *flags* to cause division operator ``/`` to be
interpreted as "true division" according to :pep:`238`.

83
Doc/c-api/weakref.rst Normal file
View File

@@ -0,0 +1,83 @@
.. highlightlang:: c
.. _weakrefobjects:
Weak Reference Objects
----------------------
Python supports *weak references* as first-class objects. There are two
specific object types which directly implement weak references. The first is a
simple reference object, and the second acts as a proxy for the original object
as much as it can.
.. c:function:: int PyWeakref_Check(ob)
Return true if *ob* is either a reference or proxy object.
.. versionadded:: 2.2
.. c:function:: int PyWeakref_CheckRef(ob)
Return true if *ob* is a reference object.
.. versionadded:: 2.2
.. c:function:: int PyWeakref_CheckProxy(ob)
Return true if *ob* is a proxy object.
.. versionadded:: 2.2
.. c:function:: PyObject* PyWeakref_NewRef(PyObject *ob, PyObject *callback)
Return a weak reference object for the object *ob*. This will always return
a new reference, but is not guaranteed to create a new object; an existing
reference object may be returned. The second parameter, *callback*, can be a
callable object that receives notification when *ob* is garbage collected; it
should accept a single parameter, which will be the weak reference object
itself. *callback* may also be ``None`` or *NULL*. If *ob* is not a
weakly-referencable object, or if *callback* is not callable, ``None``, or
*NULL*, this will return *NULL* and raise :exc:`TypeError`.
.. versionadded:: 2.2
.. c:function:: PyObject* PyWeakref_NewProxy(PyObject *ob, PyObject *callback)
Return a weak reference proxy object for the object *ob*. This will always
return a new reference, but is not guaranteed to create a new object; an
existing proxy object may be returned. The second parameter, *callback*, can
be a callable object that receives notification when *ob* is garbage
collected; it should accept a single parameter, which will be the weak
reference object itself. *callback* may also be ``None`` or *NULL*. If *ob*
is not a weakly-referencable object, or if *callback* is not callable,
``None``, or *NULL*, this will return *NULL* and raise :exc:`TypeError`.
.. versionadded:: 2.2
.. c:function:: PyObject* PyWeakref_GetObject(PyObject *ref)
Return the referenced object from a weak reference, *ref*. If the referent is
no longer live, returns :const:`Py_None`.
.. versionadded:: 2.2
.. warning::
This function returns a **borrowed reference** to the referenced object.
This means that you should always call :c:func:`Py_INCREF` on the object
except if you know that it cannot be destroyed while you are still
using it.
.. c:function:: PyObject* PyWeakref_GET_OBJECT(PyObject *ref)
Similar to :c:func:`PyWeakref_GetObject`, but implemented as a macro that does no
error checking.
.. versionadded:: 2.2