Split C API docs in Py3k branch.

Doc/c-api/allocation.rst

+.. highlightlang:: c
+
+.. _allocating-objects:
+
+Allocating Objects on the Heap
+==============================
+
+
+.. cfunction:: PyObject* _PyObject_New(PyTypeObject *type)
+
+
+.. cfunction:: PyVarObject* _PyObject_NewVar(PyTypeObject *type, Py_ssize_t size)
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: PyVarObject* PyObject_InitVar(PyVarObject *op, PyTypeObject *type, Py_ssize_t size)
+
+   This does everything :cfunc:`PyObject_Init` does, and also initializes the
+   length information for a variable-size object.
+
+
+.. cfunction:: 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 :attr:`tp_basicsize` field of the type object.
+
+
+.. cfunction:: 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 :attr:`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.
+
+
+.. cfunction:: void PyObject_Del(PyObject *op)
+
+   Releases memory allocated to an object using :cfunc:`PyObject_New` or
+   :cfunc:`PyObject_NewVar`.  This is normally called from the :attr:`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.
+
+
+.. cfunction:: 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; the *methods* argument can be *NULL* if no methods are
+   to be defined for the module.
+
+
+.. cfunction:: 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.  The *methods* argument can be *NULL* if no methods
+   are to be defined for the module.  If *doc* is non-*NULL*, it will be used to
+   define the docstring for the module.
+
+
+.. cfunction:: 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.  The *methods* argument can be *NULL* if no methods
+   are to be defined for the module.  If *doc* is non-*NULL*, it will be used to
+   define the docstring for the module.  If *self* is non-*NULL*, it will 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 :cfunc:`Py_InitModule3`
+      instead; only use this if you are sure you need it.
+
+
+.. cvar:: PyObject _Py_NoneStruct
+
+   Object which is visible in Python as ``None``.  This should only be accessed
+   using the :cmacro:`Py_None` macro, which evaluates to a pointer to this
+   object.

Doc/c-api/bool.rst

+.. 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.
+
+
+.. cfunction:: int PyBool_Check(PyObject *o)
+
+   Return true if *o* is of type :cdata:`PyBool_Type`.
+
+
+.. cvar:: 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.
+
+
+.. cvar:: 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.
+
+
+.. cmacro:: Py_RETURN_FALSE
+
+   Return :const:`Py_False` from a function, properly incrementing its reference
+   count.
+
+
+.. cmacro:: Py_RETURN_TRUE
+
+   Return :const:`Py_True` from a function, properly incrementing its reference
+   count.
+
+
+.. cfunction:: PyObject* PyBool_FromLong(long v)
+
+   Return a new reference to :const:`Py_True` or :const:`Py_False` depending on the
+   truth value of *v*.

Doc/c-api/buffer.rst

+.. highlightlang:: c
+
+.. _bufferobjects:
+
+Buffer Objects
+--------------
+
+.. sectionauthor:: Greg Stein <gstein@lyra.org>
+
+
+.. 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 also expose its contents, but it
+should be noted that 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
+:cfunc:`PyArg_ParseTuple` that operate against an object's buffer interface,
+returning data from the target object.
+
+.. index:: single: PyBufferProcs
+
+More information on the buffer interface is provided in the section 
+:ref:`buffer-structs`, under the description for :ctype:`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.
+
+
+.. ctype:: PyBufferObject
+
+   This subtype of :ctype:`PyObject` represents a buffer object.
+
+
+.. cvar:: PyTypeObject PyBuffer_Type
+
+   .. index:: single: BufferType (in module types)
+
+   The instance of :ctype:`PyTypeObject` which represents the Python buffer type;
+   it is the same object as ``buffer`` and  ``types.BufferType`` in the Python
+   layer. .
+
+
+.. cvar:: int Py_END_OF_BUFFER
+
+   This constant may be passed as the *size* parameter to
+   :cfunc:`PyBuffer_FromObject` or :cfunc:`PyBuffer_FromReadWriteObject`.  It
+   indicates that the new :ctype:`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.
+
+
+.. cfunction:: int PyBuffer_Check(PyObject *p)
+
+   Return true if the argument has type :cdata:`PyBuffer_Type`.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: 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 :cfunc:`PyBuffer_FromObject`.  If the *base* object does not export
+   the writable buffer protocol, then :exc:`TypeError` is raised.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: PyObject* PyBuffer_FromReadWriteMemory(void *ptr, Py_ssize_t size)
+
+   Similar to :cfunc:`PyBuffer_FromMemory`, but the returned buffer is writable.
+
+
+.. cfunction:: 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 :cfunc:`PyObject_AsWriteBuffer`) is
+   not specifically aligned.

Doc/c-api/cell.rst

+.. 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.
+
+
+.. ctype:: PyCellObject
+
+   The C structure used for cell objects.
+
+
+.. cvar:: PyTypeObject PyCell_Type
+
+   The type object corresponding to cell objects.
+
+
+.. cfunction:: int PyCell_Check(ob)
+
+   Return true if *ob* is a cell object; *ob* must not be *NULL*.
+
+
+.. cfunction:: PyObject* PyCell_New(PyObject *ob)
+
+   Create and return a new cell object containing the value *ob*. The parameter may
+   be *NULL*.
+
+
+.. cfunction:: PyObject* PyCell_Get(PyObject *cell)
+
+   Return the contents of the cell *cell*.
+
+
+.. cfunction:: PyObject* PyCell_GET(PyObject *cell)
+
+   Return the contents of the cell *cell*, but without checking that *cell* is
+   non-*NULL* and a cell object.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: 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.

Doc/c-api/cobject.rst

+.. highlightlang:: c
+
+.. _cobjects:
+
+CObjects
+--------
+
+.. index:: object: CObject
+
+Refer to :ref:`using-cobjects` for more information on using these objects.
+
+
+.. ctype:: PyCObject
+
+   This subtype of :ctype:`PyObject` represents an opaque value, useful for C
+   extension modules who need to pass an opaque value (as a :ctype:`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.
+
+
+.. cfunction:: int PyCObject_Check(PyObject *p)
+
+   Return true if its argument is a :ctype:`PyCObject`.
+
+
+.. cfunction:: PyObject* PyCObject_FromVoidPtr(void* cobj, void (*destr)(void *))
+
+   Create a :ctype:`PyCObject` from the ``void *`` *cobj*.  The *destr* function
+   will be called when the object is reclaimed, unless it is *NULL*.
+
+
+.. cfunction:: PyObject* PyCObject_FromVoidPtrAndDesc(void* cobj, void* desc, void (*destr)(void *, void *))
+
+   Create a :ctype:`PyCObject` from the :ctype:`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.
+
+
+.. cfunction:: void* PyCObject_AsVoidPtr(PyObject* self)
+
+   Return the object :ctype:`void \*` that the :ctype:`PyCObject` *self* was
+   created with.
+
+
+.. cfunction:: void* PyCObject_GetDesc(PyObject* self)
+
+   Return the description :ctype:`void \*` that the :ctype:`PyCObject` *self* was
+   created with.
+
+
+.. cfunction:: int PyCObject_SetVoidPtr(PyObject* self, void* cobj)
+
+   Set the void pointer inside *self* to *cobj*. The :ctype:`PyCObject` must not
+   have an associated destructor. Return true on success, false on failure.

Doc/c-api/complex.rst

+.. 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.
+
+
+.. ctype:: 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;
+
+
+.. cfunction:: Py_complex _Py_c_sum(Py_complex left, Py_complex right)
+
+   Return the sum of two complex numbers, using the C :ctype:`Py_complex`
+   representation.
+
+
+.. cfunction:: Py_complex _Py_c_diff(Py_complex left, Py_complex right)
+
+   Return the difference between two complex numbers, using the C
+   :ctype:`Py_complex` representation.
+
+
+.. cfunction:: Py_complex _Py_c_neg(Py_complex complex)
+
+   Return the negation of the complex number *complex*, using the C
+   :ctype:`Py_complex` representation.
+
+
+.. cfunction:: Py_complex _Py_c_prod(Py_complex left, Py_complex right)
+
+   Return the product of two complex numbers, using the C :ctype:`Py_complex`
+   representation.
+
+
+.. cfunction:: Py_complex _Py_c_quot(Py_complex dividend, Py_complex divisor)
+
+   Return the quotient of two complex numbers, using the C :ctype:`Py_complex`
+   representation.
+
+
+.. cfunction:: Py_complex _Py_c_pow(Py_complex num, Py_complex exp)
+
+   Return the exponentiation of *num* by *exp*, using the C :ctype:`Py_complex`
+   representation.
+
+
+Complex Numbers as Python Objects
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+.. ctype:: PyComplexObject
+
+   This subtype of :ctype:`PyObject` represents a Python complex number object.
+
+
+.. cvar:: PyTypeObject PyComplex_Type
+
+   This instance of :ctype:`PyTypeObject` represents the Python complex number
+   type. It is the same object as ``complex`` and ``types.ComplexType``.
+
+
+.. cfunction:: int PyComplex_Check(PyObject *p)
+
+   Return true if its argument is a :ctype:`PyComplexObject` or a subtype of
+   :ctype:`PyComplexObject`.
+
+
+.. cfunction:: int PyComplex_CheckExact(PyObject *p)
+
+   Return true if its argument is a :ctype:`PyComplexObject`, but not a subtype of
+   :ctype:`PyComplexObject`.
+
+
+.. cfunction:: PyObject* PyComplex_FromCComplex(Py_complex v)
+
+   Create a new Python complex number object from a C :ctype:`Py_complex` value.
+
+
+.. cfunction:: PyObject* PyComplex_FromDoubles(double real, double imag)
+
+   Return a new :ctype:`PyComplexObject` object from *real* and *imag*.
+
+
+.. cfunction:: double PyComplex_RealAsDouble(PyObject *op)
+
+   Return the real part of *op* as a C :ctype:`double`.
+
+
+.. cfunction:: double PyComplex_ImagAsDouble(PyObject *op)
+
+   Return the imaginary part of *op* as a C :ctype:`double`.
+
+
+.. cfunction:: Py_complex PyComplex_AsCComplex(PyObject *op)
+
+   Return the :ctype:`Py_complex` value of the complex number *op*.
+
+   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.

Doc/c-api/conversion.rst

+.. highlightlang:: c
+
+.. _string-conversion:
+
+String conversion and formatting
+================================
+
+Functions for number conversion and formatted string output.
+
+
+.. cfunction:: 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)`.
+
+
+.. cfunction:: 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)`.
+
+:cfunc:`PyOS_snprintf` and :cfunc:`PyOS_vsnprintf` wrap the Standard C library
+functions :cfunc:`snprintf` and :cfunc:`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 :cfunc:`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.
+
+
+.. cfunction:: double PyOS_ascii_strtod(const char *nptr, char **endptr)
+
+   Convert a string to a :ctype:`double`. This function behaves like the Standard C
+   function :cfunc:`strtod` does in the C locale. It does this without changing the
+   current locale, since that would not be thread-safe.
+
+   :cfunc:`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.
+
+
+.. cfunction:: char * PyOS_ascii_formatd(char *buffer, size_t buf_len, const char *format, double d)
+
+   Convert a :ctype:`double` to a string using the ``'.'`` as the decimal
+   separator. *format* is a :cfunc:`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.
+
+
+.. cfunction:: double PyOS_ascii_atof(const char *nptr)
+
+   Convert a string to a :ctype:`double` in a locale-independent way.
+
+   See the Unix man page :manpage:`atof(2)` for details.
+
+   
+.. cfunction:: char * PyOS_stricmp(char *s1, char *s2)
+
+   Case insensitive comparsion of strings. The functions works almost
+   identical to :cfunc:`strcmp` except that it ignores the case.
+
+
+.. cfunction:: char * PyOS_strnicmp(char *s1, char *s2, Py_ssize_t  size)
+
+   Case insensitive comparsion of strings. The functions works almost
+   identical to :cfunc:`strncmp` except that it ignores the case.

Doc/c-api/datetime.rst

+.. 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 :cfunc:`PyDateTime_IMPORT` must be invoked.  The macro puts a
+pointer to a C structure into a static variable,  ``PyDateTimeAPI``, that is
+used by the following macros.
+
+Type-check macros:
+
+.. cfunction:: int PyDate_Check(PyObject *ob)
+
+   Return true if *ob* is of type :cdata:`PyDateTime_DateType` or a subtype of
+   :cdata:`PyDateTime_DateType`.  *ob* must not be *NULL*.
+
+
+.. cfunction:: int PyDate_CheckExact(PyObject *ob)
+
+   Return true if *ob* is of type :cdata:`PyDateTime_DateType`. *ob* must not be
+   *NULL*.
+
+
+.. cfunction:: int PyDateTime_Check(PyObject *ob)
+
+   Return true if *ob* is of type :cdata:`PyDateTime_DateTimeType` or a subtype of
+   :cdata:`PyDateTime_DateTimeType`.  *ob* must not be *NULL*.
+
+
+.. cfunction:: int PyDateTime_CheckExact(PyObject *ob)
+
+   Return true if *ob* is of type :cdata:`PyDateTime_DateTimeType`. *ob* must not
+   be *NULL*.
+
+
+.. cfunction:: int PyTime_Check(PyObject *ob)
+
+   Return true if *ob* is of type :cdata:`PyDateTime_TimeType` or a subtype of
+   :cdata:`PyDateTime_TimeType`.  *ob* must not be *NULL*.
+
+
+.. cfunction:: int PyTime_CheckExact(PyObject *ob)
+
+   Return true if *ob* is of type :cdata:`PyDateTime_TimeType`. *ob* must not be
+   *NULL*.
+
+
+.. cfunction:: int PyDelta_Check(PyObject *ob)
+
+   Return true if *ob* is of type :cdata:`PyDateTime_DeltaType` or a subtype of
+   :cdata:`PyDateTime_DeltaType`.  *ob* must not be *NULL*.
+
+
+.. cfunction:: int PyDelta_CheckExact(PyObject *ob)
+
+   Return true if *ob* is of type :cdata:`PyDateTime_DeltaType`. *ob* must not be
+   *NULL*.
+
+
+.. cfunction:: int PyTZInfo_Check(PyObject *ob)
+
+   Return true if *ob* is of type :cdata:`PyDateTime_TZInfoType` or a subtype of
+   :cdata:`PyDateTime_TZInfoType`.  *ob* must not be *NULL*.
+
+
+.. cfunction:: int PyTZInfo_CheckExact(PyObject *ob)
+
+   Return true if *ob* is of type :cdata:`PyDateTime_TZInfoType`. *ob* must not be
+   *NULL*.
+
+
+Macros to create objects:
+
+.. cfunction:: PyObject* PyDate_FromDate(int year, int month, int day)
+
+   Return a ``datetime.date`` object with the specified year, month and day.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: PyObject* PyTime_FromTime(int hour, int minute, int second, int usecond)
+
+   Return a ``datetime.time`` object with the specified hour, minute, second and
+   microsecond.
+
+
+.. cfunction:: 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.
+
+
+Macros to extract fields from date objects.  The argument must be an instance of
+:cdata:`PyDateTime_Date`, including subclasses (such as
+:cdata:`PyDateTime_DateTime`).  The argument must not be *NULL*, and the type is
+not checked:
+
+.. cfunction:: int PyDateTime_GET_YEAR(PyDateTime_Date *o)
+
+   Return the year, as a positive int.
+
+
+.. cfunction:: int PyDateTime_GET_MONTH(PyDateTime_Date *o)
+
+   Return the month, as an int from 1 through 12.
+
+
+.. cfunction:: int PyDateTime_GET_DAY(PyDateTime_Date *o)
+
+   Return the day, as an int from 1 through 31.
+
+
+Macros to extract fields from datetime objects.  The argument must be an
+instance of :cdata:`PyDateTime_DateTime`, including subclasses. The argument
+must not be *NULL*, and the type is not checked:
+
+.. cfunction:: int PyDateTime_DATE_GET_HOUR(PyDateTime_DateTime *o)
+
+   Return the hour, as an int from 0 through 23.
+
+
+.. cfunction:: int PyDateTime_DATE_GET_MINUTE(PyDateTime_DateTime *o)
+
+   Return the minute, as an int from 0 through 59.
+
+
+.. cfunction:: int PyDateTime_DATE_GET_SECOND(PyDateTime_DateTime *o)
+
+   Return the second, as an int from 0 through 59.
+
+
+.. cfunction:: int PyDateTime_DATE_GET_MICROSECOND(PyDateTime_DateTime *o)
+
+   Return the microsecond, as an int from 0 through 999999.
+
+
+Macros to extract fields from time objects.  The argument must be an instance of
+:cdata:`PyDateTime_Time`, including subclasses. The argument must not be *NULL*,
+and the type is not checked:
+
+.. cfunction:: int PyDateTime_TIME_GET_HOUR(PyDateTime_Time *o)
+
+   Return the hour, as an int from 0 through 23.
+
+
+.. cfunction:: int PyDateTime_TIME_GET_MINUTE(PyDateTime_Time *o)
+
+   Return the minute, as an int from 0 through 59.
+
+
+.. cfunction:: int PyDateTime_TIME_GET_SECOND(PyDateTime_Time *o)
+
+   Return the second, as an int from 0 through 59.
+
+
+.. cfunction:: int PyDateTime_TIME_GET_MICROSECOND(PyDateTime_Time *o)
+
+   Return the microsecond, as an int from 0 through 999999.
+
+
+Macros for the convenience of modules implementing the DB API:
+
+.. cfunction:: PyObject* PyDateTime_FromTimestamp(PyObject *args)
+
+   Create and return a new ``datetime.datetime`` object given an argument tuple
+   suitable for passing to ``datetime.datetime.fromtimestamp()``.
+
+
+.. cfunction:: PyObject* PyDate_FromTimestamp(PyObject *args)
+
+   Create and return a new ``datetime.date`` object given an argument tuple
+   suitable for passing to ``datetime.date.fromtimestamp()``.

Doc/c-api/descriptor.rst

+.. 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.
+
+.. XXX document these!
+
+.. cvar:: PyTypeObject PyProperty_Type
+
+   The type object for the built-in descriptor types.
+
+
+.. cfunction:: PyObject* PyDescr_NewGetSet(PyTypeObject *type, struct PyGetSetDef *getset)
+
+
+.. cfunction:: PyObject* PyDescr_NewMember(PyTypeObject *type, struct PyMemberDef *meth)
+
+
+.. cfunction:: PyObject* PyDescr_NewMethod(PyTypeObject *type, struct PyMethodDef *meth)
+
+
+.. cfunction:: PyObject* PyDescr_NewWrapper(PyTypeObject *type, struct wrapperbase *wrapper, void *wrapped)
+
+
+.. cfunction:: PyObject* PyDescr_NewClassMethod(PyTypeObject *type, PyMethodDef *method)
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: PyObject* PyWrapper_New(PyObject *, PyObject *)

Doc/c-api/dict.rst

+.. highlightlang:: c
+
+.. _dictobjects:
+
+Dictionary Objects
+------------------
+
+.. index:: object: dictionary
+
+
+.. ctype:: PyDictObject
+
+   This subtype of :ctype:`PyObject` represents a Python dictionary object.
+
+
+.. cvar:: PyTypeObject PyDict_Type
+
+   .. index::
+      single: DictType (in module types)
+      single: DictionaryType (in module types)
+
+   This instance of :ctype:`PyTypeObject` represents the Python dictionary type.
+   This is exposed to Python programs as ``dict`` and ``types.DictType``.
+
+
+.. cfunction:: int PyDict_Check(PyObject *p)
+
+   Return true if *p* is a dict object or an instance of a subtype of the dict
+   type.
+
+
+.. cfunction:: int PyDict_CheckExact(PyObject *p)
+
+   Return true if *p* is a dict object, but not an instance of a subtype of the
+   dict type.
+
+
+.. cfunction:: PyObject* PyDict_New()
+
+   Return a new empty dictionary, or *NULL* on failure.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: void PyDict_Clear(PyObject *p)
+
+   Empty an existing dictionary of all key-value pairs.
+
+
+.. cfunction:: 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``.
+
+
+.. cfunction:: PyObject* PyDict_Copy(PyObject *p)
+
+   Return a new dictionary that contains the same key-value pairs as *p*.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: 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
+   :ctype:`char\*`.  The key object is created using ``PyString_FromString(key)``.
+   Return ``0`` on success or ``-1`` on failure.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: PyObject* PyDict_GetItemString(PyObject *p, const char *key)
+
+   This is the same as :cfunc:`PyDict_GetItem`, but *key* is specified as a
+   :ctype:`char\*`, rather than a :ctype:`PyObject\*`.
+
+
+.. cfunction:: PyObject* PyDict_Items(PyObject *p)
+
+   Return a :ctype:`PyListObject` containing all the items from the dictionary, as
+   in the dictionary method :meth:`dict.items`.
+
+
+.. cfunction:: PyObject* PyDict_Keys(PyObject *p)
+
+   Return a :ctype:`PyListObject` containing all the keys from the dictionary, as
+   in the dictionary method :meth:`dict.keys`.
+
+
+.. cfunction:: PyObject* PyDict_Values(PyObject *p)
+
+   Return a :ctype:`PyListObject` containing all the values from the dictionary
+   *p*, as in the dictionary method :meth:`dict.values`.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)
+
+   Iterate over all key-value pairs in the dictionary *p*.  The :ctype:`int`
+   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 :ctype:`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)) {
+          long i = PyLong_AsLong(value);
+          if (i == -1 && PyErr_Occurred()) {
+              return -1;
+          }
+          PyObject *o = PyLong_FromLong(i + 1);
+          if (o == NULL)
+              return -1;
+          if (PyDict_SetItem(self->dict, key, o) < 0) {
+              Py_DECREF(o);
+              return -1;
+          }
+          Py_DECREF(o);
+      }
+
+
+.. cfunction:: 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 :func:`PyMapping_Keys` and
+   :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.
+
+
+.. cfunction:: int PyDict_Update(PyObject *a, PyObject *b)
+
+   This is the same as ``PyDict_Merge(a, b, 1)`` in C, or ``a.update(b)`` in
+   Python.  Return ``0`` on success or ``-1`` if an exception was raised.
+
+
+.. cfunction:: 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

Doc/c-api/file.rst

+.. highlightlang:: c
+
+.. _fileobjects:
+
+File Objects
+------------
+
+.. index:: object: file
+
+Python's built-in file objects are implemented entirely on the :ctype:`FILE\*`
+support from the C standard library.  This is an implementation detail and may
+change in future releases of Python.
+
+
+.. ctype:: PyFileObject
+
+   This subtype of :ctype:`PyObject` represents a Python file object.
+
+
+.. cvar:: PyTypeObject PyFile_Type
+
+   .. index:: single: FileType (in module types)
+
+   This instance of :ctype:`PyTypeObject` represents the Python file type.  This is
+   exposed to Python programs as ``file`` and ``types.FileType``.
+
+
+.. cfunction:: int PyFile_Check(PyObject *p)
+
+   Return true if its argument is a :ctype:`PyFileObject` or a subtype of
+   :ctype:`PyFileObject`.
+
+
+.. cfunction:: int PyFile_CheckExact(PyObject *p)
+
+   Return true if its argument is a :ctype:`PyFileObject`, but not a subtype of
+   :ctype:`PyFileObject`.
+
+
+.. cfunction:: PyFile_FromFd(int fd, char *name, char *mode, int buffering, char *encoding, char *newline, int closefd)
+
+   Create a new :ctype:`PyFileObject` from the file descriptor of an already
+   opened file *fd*. The arguments *name*, *encoding* and *newline* can be
+   *NULL* to use the defaults; *buffering* can be *-1* to use the default.
+   Return *NULL* on failure.
+
+   .. warning::
+
+     Take care when you are mixing streams and descriptors! For more 
+     information, see `the GNU C Library docs
+     <http://www.gnu.org/software/libc/manual/html_node/Stream_002fDescriptor-Precautions.html#Stream_002fDescriptor-Precautions>`_.
+
+
+.. cfunction:: int PyObject_AsFileDescriptor(PyObject *p)
+
+   Return the file descriptor associated with *p* as an :ctype:`int`.  If the
+   object is an integer, its value is returned.  If not, the
+   object's :meth:`fileno` method is called if it exists; the method must return
+   an integer, which is returned as the file descriptor value.  Sets an
+   exception and returns ``-1`` on failure.
+
+
+.. cfunction:: 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:`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.
+
+
+.. cfunction:: PyObject* PyFile_Name(PyObject *p)
+
+   Return the name of the file specified by *p* as a string object.
+
+
+.. cfunction:: void PyFile_SetBufSize(PyFileObject *p, int n)
+
+   .. index:: single: setvbuf()
+
+   Available on systems with :cfunc:`setvbuf` only.  This should only be called
+   immediately after file object creation.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: 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.

Doc/c-api/float.rst

+.. highlightlang:: c
+
+.. _floatobjects:
+
+Floating Point Objects
+----------------------
+
+.. index:: object: floating point
+
+
+.. ctype:: PyFloatObject
+
+   This subtype of :ctype:`PyObject` represents a Python floating point object.
+
+
+.. cvar:: PyTypeObject PyFloat_Type
+
+   .. index:: single: FloatType (in modules types)
+
+   This instance of :ctype:`PyTypeObject` represents the Python floating point
+   type.  This is the same object as ``float`` and ``types.FloatType``.
+
+
+.. cfunction:: int PyFloat_Check(PyObject *p)
+
+   Return true if its argument is a :ctype:`PyFloatObject` or a subtype of
+   :ctype:`PyFloatObject`.
+
+
+.. cfunction:: int PyFloat_CheckExact(PyObject *p)
+
+   Return true if its argument is a :ctype:`PyFloatObject`, but not a subtype of
+   :ctype:`PyFloatObject`.
+
+
+.. cfunction:: PyObject* PyFloat_FromString(PyObject *str)
+
+   Create a :ctype:`PyFloatObject` object based on the string value in *str*, or
+   *NULL* on failure.
+
+
+.. cfunction:: PyObject* PyFloat_FromDouble(double v)
+
+   Create a :ctype:`PyFloatObject` object from *v*, or *NULL* on failure.
+
+
+.. cfunction:: double PyFloat_AsDouble(PyObject *pyfloat)
+
+   Return a C :ctype:`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.
+
+
+.. cfunction:: double PyFloat_AS_DOUBLE(PyObject *pyfloat)
+
+   Return a C :ctype:`double` representation of the contents of *pyfloat*, but
+   without error checking.
+
+
+.. cfunction:: 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`.
+
+
+.. cfunction:: double PyFloat_GetMax(void)
+
+   Return the maximum representable finite float *DBL_MAX* as C :ctype:`double`.
+
+
+.. cfunction:: double PyFloat_GetMin(void)
+
+   Return the minimum normalized positive float *DBL_MIN* as C :ctype:`double`.

Doc/c-api/function.rst

+.. highlightlang:: c
+
+.. _function-objects:
+
+Function Objects
+----------------
+
+.. index:: object: function
+
+There are a few functions specific to Python functions.
+
+
+.. ctype:: PyFunctionObject
+
+   The C structure used for functions.
+
+
+.. cvar:: PyTypeObject PyFunction_Type
+
+   .. index:: single: MethodType (in module types)
+
+   This is an instance of :ctype:`PyTypeObject` and represents the Python function
+   type.  It is exposed to Python programmers as ``types.FunctionType``.
+
+
+.. cfunction:: int PyFunction_Check(PyObject *o)
+
+   Return true if *o* is a function object (has type :cdata:`PyFunction_Type`).
+   The parameter must not be *NULL*.
+
+
+.. cfunction:: 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*.
+
+
+.. cfunction:: PyObject* PyFunction_GetCode(PyObject *op)
+
+   Return the code object associated with the function object *op*.
+
+
+.. cfunction:: PyObject* PyFunction_GetGlobals(PyObject *op)
+
+   Return the globals dictionary associated with the function object *op*.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: PyObject* PyFunction_GetDefaults(PyObject *op)
+
+   Return the argument default values of the function object *op*. This can be a
+   tuple of arguments or *NULL*.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: PyObject* PyFunction_GetClosure(PyObject *op)
+
+   Return the closure associated with the function object *op*. This can be *NULL*
+   or a tuple of cell objects.
+
+
+.. cfunction:: 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.

Doc/c-api/gcsupport.rst

+.. 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.
+
+To create a container type, the :attr:`tp_flags` field of the type object must
+include the :const:`Py_TPFLAGS_HAVE_GC` and provide an implementation of the
+:attr:`tp_traverse` handler.  If instances of the type are mutable, a
+:attr:`tp_clear` implementation must also be provided.
+
+
+.. data:: Py_TPFLAGS_HAVE_GC
+
+   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 :cfunc:`PyObject_GC_New` or
+   :cfunc:`PyObject_GC_VarNew`.
+
+#. Once all the fields which may contain references to other containers are
+   initialized, it must call :cfunc:`PyObject_GC_Track`.
+
+
+.. cfunction:: TYPE* PyObject_GC_New(TYPE, PyTypeObject *type)
+
+   Analogous to :cfunc:`PyObject_New` but for container objects with the
+   :const:`Py_TPFLAGS_HAVE_GC` flag set.
+
+
+.. cfunction:: TYPE* PyObject_GC_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)
+
+   Analogous to :cfunc:`PyObject_NewVar` but for container objects with the
+   :const:`Py_TPFLAGS_HAVE_GC` flag set.
+
+
+.. cfunction:: PyVarObject * PyObject_GC_Resize(PyVarObject *op, Py_ssize_t)
+
+   Resize an object allocated by :cfunc:`PyObject_NewVar`.  Returns the resized
+   object or *NULL* on failure.
+
+
+.. cfunction:: 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
+   :attr:`tp_traverse` handler become valid, usually near the end of the
+   constructor.
+
+
+.. cfunction:: void _PyObject_GC_TRACK(PyObject *op)
+
+   A macro version of :cfunc:`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,
+   :cfunc:`PyObject_GC_UnTrack` must be called.
+
+#. The object's memory must be deallocated using :cfunc:`PyObject_GC_Del`.
+
+
+.. cfunction:: void PyObject_GC_Del(void *op)
+
+   Releases memory allocated to an object using :cfunc:`PyObject_GC_New` or
+   :cfunc:`PyObject_GC_NewVar`.
+
+
+.. cfunction:: void PyObject_GC_UnTrack(void *op)
+
+   Remove the object *op* from the set of container objects tracked by the
+   collector.  Note that :cfunc:`PyObject_GC_Track` can be called again on this
+   object to add it back to the set of tracked objects.  The deallocator
+   (:attr:`tp_dealloc` handler) should call this for the object before any of the
+   fields used by the :attr:`tp_traverse` handler become invalid.
+
+
+.. cfunction:: void _PyObject_GC_UNTRACK(PyObject *op)
+
+   A macro version of :cfunc:`PyObject_GC_UnTrack`.  It should not be used for
+   extension modules.
+
+The :attr:`tp_traverse` handler accepts a function parameter of this type:
+
+
+.. ctype:: int (*visitproc)(PyObject *object, void *arg)
+
+   Type of the visitor function passed to the :attr:`tp_traverse` handler.  The
+   function should be called with an object to traverse as *object* and the third
+   parameter to the :attr:`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 :attr:`tp_traverse` handler must have the following type:
+
+
+.. ctype:: 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 :attr:`tp_traverse` handlers, a :cfunc:`Py_VISIT` macro is
+provided.  In order to use this macro, the :attr:`tp_traverse` implementation
+must name its arguments exactly *visit* and *arg*:
+
+
+.. cfunction:: void Py_VISIT(PyObject *o)
+
+   Call the *visit* callback, with arguments *o* and *arg*. If *visit* returns a
+   non-zero value, then return it.  Using this macro, :attr:`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;
+      }
+
+The :attr:`tp_clear` handler must be of the :ctype:`inquiry` type, or *NULL* if
+the object is immutable.
+
+
+.. ctype:: 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 :cfunc:`Py_DECREF` on a reference).  The collector will call
+   this method if it detects that this object is involved in a reference cycle.

Doc/c-api/gen.rst

+.. 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 :cfunc:`PyGen_New`.
+
+
+.. ctype:: PyGenObject
+
+   The C structure used for generator objects.
+
+
+.. cvar:: PyTypeObject PyGen_Type
+
+   The type object corresponding to generator objects
+
+
+.. cfunction:: int PyGen_Check(ob)
+
+   Return true if *ob* is a generator object; *ob* must not be *NULL*.
+
+
+.. cfunction:: int PyGen_CheckExact(ob)
+
+   Return true if *ob*'s type is *PyGen_Type* is a generator object; *ob* must not
+   be *NULL*.
+
+
+.. cfunction:: 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*.

Doc/c-api/import.rst

+.. highlightlang:: c
+
+.. _importing:
+
+Importing Modules
+=================
+
+
+.. cfunction:: 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 :cfunc:`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``.
+
+
+.. cfunction:: PyObject* PyImport_ImportModuleNoBlock(const char *name)
+
+   This version of :cfunc:`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
+   :cfunc:`PyImport_ImportModuleNoBlock` never blocks. It first tries to fetch
+   the module from sys.modules and falls back to :cfunc:`PyImport_ImportModule`
+   unless the lock is held, in which case the function will raise an
+   :exc:`ImportError`.
+
+
+.. cfunction:: 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.
+
+   Failing imports remove incomplete module objects, like with
+   :cfunc:`PyImport_ImportModule`.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: PyObject* PyImport_Import(PyObject *name)
+
+   This is a higher-level interface that calls the current "import hook
+   function" (with an explicit *level* of 0, meaning absolute import).  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.
+
+
+.. cfunction:: PyObject* PyImport_ReloadModule(PyObject *m)
+
+   Reload a module.  Return a new reference to the reloaded module, or *NULL* with
+   an exception set on failure (the module still exists in this case).
+
+
+.. cfunction:: 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 :cfunc:`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.
+
+
+.. cfunction:: 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 :cfunc:`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.
+
+   This function will reload the module if it was already imported.  See
+   :cfunc:`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.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: PyObject* PyImport_GetModuleDict()
+
+   Return the dictionary used for the module administration (a.k.a.
+   ``sys.modules``).  Note that this is a per-interpreter variable.
+
+
+.. cfunction:: void _PyImport_Init()
+
+   Initialize the import mechanism.  For internal use only.
+
+
+.. cfunction:: void PyImport_Cleanup()
+
+   Empty the module table.  For internal use only.
+
+
+.. cfunction:: void _PyImport_Fini()
+
+   Finalize the import mechanism.  For internal use only.
+
+
+.. cfunction:: PyObject* _PyImport_FindExtension(char *, char *)
+
+   For internal use only.
+
+
+.. cfunction:: PyObject* _PyImport_FixupExtension(char *, char *)
+
+   For internal use only.
+
+
+.. cfunction:: 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
+   :cfunc:`PyImport_ImportModule`.  (Note the misnomer --- this function would
+   reload the module if it was already imported.)
+
+
+.. ctype:: 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;
+      };
+
+
+.. cvar:: struct _frozen* PyImport_FrozenModules
+
+   This pointer is initialized to point to an array of :ctype:`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.
+
+
+.. cfunction:: int PyImport_AppendInittab(char *name, void (*initfunc)(void))
+
+   Add a single module to the existing table of built-in modules.  This is a
+   convenience wrapper around :cfunc:`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
+   :cfunc:`Py_Initialize`.
+
+
+.. ctype:: 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 :cfunc:`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);
+      };
+
+
+.. cfunction:: 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 :cfunc:`Py_Initialize`.

Doc/c-api/iter.rst

+.. highlightlang:: c
+
+.. _iterator:
+
+Iterator Protocol
+=================
+
+There are only a couple of functions specifically for working with iterators.
+
+.. cfunction:: int PyIter_Check(PyObject *o)
+
+   Return true if the object *o* supports the iterator protocol.
+
+
+.. cfunction:: PyObject* PyIter_Next(PyObject *o)
+
+   Return the next value from the iteration *o*.  If the object is an iterator,
+   this retrieves the next value from the iteration, and returns *NULL* with no
+   exception set if there are no remaining items.  If the object is not an
+   iterator, :exc:`TypeError` is raised, or if there is an error in 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 */
+   }

Doc/c-api/iterator.rst

+.. 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.
+
+
+.. cvar:: PyTypeObject PySeqIter_Type
+
+   Type object for iterator objects returned by :cfunc:`PySeqIter_New` and the
+   one-argument form of the :func:`iter` built-in function for built-in sequence
+   types.
+
+
+.. cfunction:: int PySeqIter_Check(op)
+
+   Return true if the type of *op* is :cdata:`PySeqIter_Type`.
+
+
+.. cfunction:: 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.
+
+
+.. cvar:: PyTypeObject PyCallIter_Type
+
+   Type object for iterator objects returned by :cfunc:`PyCallIter_New` and the
+   two-argument form of the :func:`iter` built-in function.
+
+
+.. cfunction:: int PyCallIter_Check(op)
+
+   Return true if the type of *op* is :cdata:`PyCallIter_Type`.
+
+
+.. cfunction:: 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.

Doc/c-api/list.rst

+.. highlightlang:: c
+
+.. _listobjects:
+
+List Objects
+------------
+
+.. index:: object: list
+
+
+.. ctype:: PyListObject
+
+   This subtype of :ctype:`PyObject` represents a Python list object.
+
+
+.. cvar:: PyTypeObject PyList_Type
+
+   .. index:: single: ListType (in module types)
+
+   This instance of :ctype:`PyTypeObject` represents the Python list type.  This is
+   the same object as ``list`` and ``types.ListType`` in the Python layer.
+
+
+.. cfunction:: int PyList_Check(PyObject *p)
+
+   Return true if *p* is a list object or an instance of a subtype of the list
+   type.
+
+
+.. cfunction:: int PyList_CheckExact(PyObject *p)
+
+   Return true if *p* is a list object, but not an instance of a subtype of the
+   list type.
+
+
+.. cfunction:: PyObject* PyList_New(Py_ssize_t len)
+
+   Return a new list of length *len* on success, or *NULL* on failure.
+
+   .. note::
+
+      If *length* is greater than zero, the returned list object's items are set to
+      ``NULL``.  Thus you cannot use abstract API functions such as
+      :cfunc:`PySequence_SetItem`  or expose the object to Python code before setting
+      all items to a real object with :cfunc:`PyList_SetItem`.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: Py_ssize_t PyList_GET_SIZE(PyObject *list)
+
+   Macro form of :cfunc:`PyList_Size` without error checking.
+
+
+.. cfunction:: PyObject* PyList_GetItem(PyObject *list, Py_ssize_t index)
+
+   Return the object at position *pos* in the list pointed to by *p*.  The position
+   must be positive, indexing from the end of the list is not supported.  If *pos*
+   is out of bounds, return *NULL* and set an :exc:`IndexError` exception.
+
+
+.. cfunction:: PyObject* PyList_GET_ITEM(PyObject *list, Py_ssize_t i)
+
+   Macro form of :cfunc:`PyList_GetItem` without error checking.
+
+
+.. cfunction:: 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 or
+   ``-1`` on failure.
+
+   .. note::
+
+      This function "steals" a reference to *item* and discards a reference to an item
+      already in the list at the affected position.
+
+
+.. cfunction:: void PyList_SET_ITEM(PyObject *list, Py_ssize_t i, PyObject *o)
+
+   Macro form of :cfunc:`PyList_SetItem` without error checking. This is normally
+   only used to fill in new lists where there is no previous content.
+
+   .. note::
+
+      This function "steals" a reference to *item*, and, unlike
+      :cfunc:`PyList_SetItem`, does *not* discard a reference to any item that it
+      being replaced; any reference in *list* at position *i* will be leaked.
+
+
+.. cfunction:: 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)``.
+
+
+.. cfunction:: 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)``.
+
+
+.. cfunction:: 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]``.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: 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()``.
+
+
+.. cfunction:: 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()``.
+
+
+.. cfunction:: PyObject* PyList_AsTuple(PyObject *list)
+
+   .. index:: builtin: tuple
+
+   Return a new tuple object containing the contents of *list*; equivalent to
+   ``tuple(list)``.

Doc/c-api/long.rst

+.. highlightlang:: c
+
+.. _longobjects:
+
+Integer Objects
+---------------
+
+.. index:: object: long integer
+           object: integer
+
+All integers are implemented as "long" integer objects of arbitrary size.
+
+.. ctype:: PyLongObject
+
+   This subtype of :ctype:`PyObject` represents a Python integer object.
+
+
+.. cvar:: PyTypeObject PyLong_Type
+
+   This instance of :ctype:`PyTypeObject` represents the Python integer type.
+   This is the same object as ``int``.
+
+
+.. cfunction:: int PyLong_Check(PyObject *p)
+
+   Return true if its argument is a :ctype:`PyLongObject` or a subtype of
+   :ctype:`PyLongObject`.
+
+
+.. cfunction:: int PyLong_CheckExact(PyObject *p)
+
+   Return true if its argument is a :ctype:`PyLongObject`, but not a subtype of
+   :ctype:`PyLongObject`.
+
+
+.. cfunction:: PyObject* PyLong_FromLong(long v)
+
+   Return a new :ctype:`PyLongObject` object from *v*, or *NULL* on failure.
+
+   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. :-)
+
+
+.. cfunction:: PyObject* PyLong_FromUnsignedLong(unsigned long v)
+
+   Return a new :ctype:`PyLongObject` object from a C :ctype:`unsigned long`, or
+   *NULL* on failure.
+
+
+.. cfunction:: PyObject* PyLong_FromSsize_t(Py_ssize_t v)
+
+   Return a new :ctype:`PyLongObject` object with a value of *v*, or *NULL*
+   on failure.
+
+
+.. cfunction:: PyObject* PyLong_FromSize_t(size_t v)
+
+   Return a new :ctype:`PyLongObject` object with a value of *v*, or *NULL*
+   on failure.
+
+
+.. cfunction:: PyObject* PyLong_FromLongLong(PY_LONG_LONG v)
+
+   Return a new :ctype:`PyLongObject` object from a C :ctype:`long long`, or *NULL*
+   on failure.
+
+
+.. cfunction:: PyObject* PyLong_FromUnsignedLongLong(unsigned PY_LONG_LONG v)
+
+   Return a new :ctype:`PyLongObject` object from a C :ctype:`unsigned long long`,
+   or *NULL* on failure.
+
+
+.. cfunction:: PyObject* PyLong_FromDouble(double v)
+
+   Return a new :ctype:`PyLongObject` object from the integer part of *v*, or
+   *NULL* on failure.
+
+
+.. cfunction:: PyObject* PyLong_FromString(char *str, char **pend, int base)
+
+   Return a new :ctype:`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 ``'0o'`` or
+   ``'0O'``, radix 8 will be used; if *str* starts with ``'0b'`` or ``'0B'``,
+   radix 2 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.
+
+
+.. cfunction:: PyObject* PyLong_FromUnicode(Py_UNICODE *u, Py_ssize_t length, int base)
+
+   Convert a sequence of Unicode digits to a Python integer value.  The Unicode
+   string is first encoded to a byte string using :cfunc:`PyUnicode_EncodeDecimal`
+   and then converted using :cfunc:`PyLong_FromString`.
+
+
+.. cfunction:: PyObject* PyLong_FromVoidPtr(void *p)
+
+   Create a Python integer from the pointer *p*. The pointer value can be
+   retrieved from the resulting value using :cfunc:`PyLong_AsVoidPtr`.
+
+
+.. XXX alias PyLong_AS_LONG (for now) 
+.. cfunction:: long PyLong_AsLong(PyObject *pylong)
+
+   .. index::
+      single: LONG_MAX
+      single: OverflowError (built-in exception)
+
+   Return a C :ctype:`long` representation of the contents of *pylong*.  If
+   *pylong* is greater than :const:`LONG_MAX`, raise an :exc:`OverflowError`,
+   and return -1. Convert non-long objects automatically to long first,
+   and return -1 if that raises exceptions.
+
+.. cfunction:: long PyLong_AsLongAndOverflow(PyObject *pylong, int* overflow)
+
+   Return a C :ctype:`long` representation of the contents of *pylong*.  If
+   *pylong* is greater than :const:`LONG_MAX`, return -1 and
+   set `*overflow` to 1 (for overflow) or -1 (for underflow). 
+   If an exception is set because of type errors, also return -1.
+
+
+.. cfunction:: unsigned long PyLong_AsUnsignedLong(PyObject *pylong)
+
+   .. index::
+      single: ULONG_MAX
+      single: OverflowError (built-in exception)
+
+   Return a C :ctype:`unsigned long` representation of the contents of *pylong*.
+   If *pylong* is greater than :const:`ULONG_MAX`, an :exc:`OverflowError` is
+   raised.
+
+
+.. cfunction:: Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)
+
+   .. index::
+      single: PY_SSIZE_T_MAX
+
+   Return a :ctype:`Py_ssize_t` representation of the contents of *pylong*.  If
+   *pylong* is greater than :const:`PY_SSIZE_T_MAX`, an :exc:`OverflowError` is
+   raised.
+
+
+.. cfunction:: size_t PyLong_AsSize_t(PyObject *pylong)
+
+   Return a :ctype:`size_t` representation of the contents of *pylong*.  If
+   *pylong* is greater than the maximum value for a :ctype:`size_t`, an
+   :exc:`OverflowError` is raised.
+
+
+.. cfunction:: PY_LONG_LONG PyLong_AsLongLong(PyObject *pylong)
+
+   Return a C :ctype:`long long` from a Python integer.  If *pylong* cannot be
+   represented as a :ctype:`long long`, an :exc:`OverflowError` will be raised.
+
+
+.. cfunction:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLong(PyObject *pylong)
+
+   Return a C :ctype:`unsigned long long` from a Python integer. If *pylong*
+   cannot be represented as an :ctype:`unsigned long long`, an :exc:`OverflowError`
+   will be raised if the value is positive, or a :exc:`TypeError` will be raised if
+   the value is negative.
+
+
+.. cfunction:: unsigned long PyLong_AsUnsignedLongMask(PyObject *io)
+
+   Return a C :ctype:`unsigned long` from a Python integer, without checking for
+   overflow.
+
+
+.. cfunction:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLongMask(PyObject *io)
+
+   Return a C :ctype:`unsigned long long` from a Python integer, without
+   checking for overflow.
+
+
+.. cfunction:: double PyLong_AsDouble(PyObject *pylong)
+
+   Return a C :ctype:`double` representation of the contents of *pylong*.  If
+   *pylong* cannot be approximately represented as a :ctype:`double`, an
+   :exc:`OverflowError` exception is raised and ``-1.0`` will be returned.
+
+
+.. cfunction:: void* PyLong_AsVoidPtr(PyObject *pylong)
+
+   Convert a Python integer *pylong* to a C :ctype:`void` pointer.  If *pylong*
+   cannot be converted, an :exc:`OverflowError` will be raised.  This is only
+   assured to produce a usable :ctype:`void` pointer for values created with
+   :cfunc:`PyLong_FromVoidPtr`.

Doc/c-api/mapping.rst

+.. highlightlang:: c
+
+.. _mapping:
+
+Mapping Protocol
+================
+
+
+.. cfunction:: int PyMapping_Check(PyObject *o)
+
+   Return ``1`` if the object provides mapping protocol, and ``0`` otherwise.  This
+   function always succeeds.
+
+
+.. cfunction:: 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)``.
+
+
+.. cfunction:: 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]``.
+
+
+.. cfunction:: 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]``.
+
+
+.. cfunction:: 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 the Python expression ``key in o``.
+   This function always succeeds.
+
+
+.. cfunction:: int PyMapping_HasKey(PyObject *o, PyObject *key)
+
+   Return ``1`` if the mapping object has the key *key* and ``0`` otherwise.  This
+   is equivalent to the Python expression ``key in o``.  This function always
+   succeeds.
+
+
+.. cfunction:: 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()``.
+
+
+.. cfunction:: 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()``.
+
+
+.. cfunction:: 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()``.
+
+
+.. cfunction:: 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]``.
+
+
+.. cfunction:: 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``.

Doc/c-api/marshal.rst

+.. 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. *Py_MARSHAL_VERSION* indicates the current file format
+(currently 1).
+
+
+.. cfunction:: void PyMarshal_WriteLongToFile(long value, FILE *file, int version)
+
+   Marshal a :ctype:`long` integer, *value*, to *file*.  This will only write the
+   least-significant 32 bits of *value*; regardless of the size of the native
+   :ctype:`long` type.  *version* indicates the file format.
+
+
+.. cfunction:: void PyMarshal_WriteObjectToFile(PyObject *value, FILE *file, int version)
+
+   Marshal a Python object, *value*, to *file*.
+   *version* indicates the file format.
+
+
+.. cfunction:: PyObject* PyMarshal_WriteObjectToString(PyObject *value, int version)
+
+   Return a string object containing the marshalled representation of *value*.
+   *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?
+
+
+.. cfunction:: long PyMarshal_ReadLongFromFile(FILE *file)
+
+   Return a C :ctype:`long` from the data stream in a :ctype:`FILE\*` opened for
+   reading.  Only a 32-bit value can be read in using this function, regardless of
+   the native size of :ctype:`long`.
+
+
+.. cfunction:: int PyMarshal_ReadShortFromFile(FILE *file)
+
+   Return a C :ctype:`short` from the data stream in a :ctype:`FILE\*` opened for
+   reading.  Only a 16-bit value can be read in using this function, regardless of
+   the native size of :ctype:`short`.
+
+
+.. cfunction:: PyObject* PyMarshal_ReadObjectFromFile(FILE *file)
+
+   Return a Python object from the data stream in a :ctype:`FILE\*` opened for
+   reading.  On error, sets the appropriate exception (:exc:`EOFError` or
+   :exc:`TypeError`) and returns *NULL*.
+
+
+.. cfunction:: PyObject* PyMarshal_ReadLastObjectFromFile(FILE *file)
+
+   Return a Python object from the data stream in a :ctype:`FILE\*` opened for
+   reading.  Unlike :cfunc:`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*.
+
+
+.. cfunction:: 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*.

Doc/c-api/method.rst

+.. highlightlang:: c
+
+.. _instancemethod-objects:
+
+Instance Method Objects
+-----------------------
+
+.. index:: object: instancemethod
+
+An instance method is a wrapper for a :cdata:`PyCFunction` and the new way
+to bind a :cdata:`PyCFunction` to a class object. It replaces the former call
+``PyMethod_New(func, NULL, class)``.
+
+
+.. cvar:: PyTypeObject PyInstanceMethod_Type
+
+   This instance of :ctype:`PyTypeObject` represents the Python instance
+   method type. It is not exposed to Python programs.
+
+
+.. cfunction:: int PyInstanceMethod_Check(PyObject *o)
+
+   Return true if *o* is an instance method object (has type
+   :cdata:`PyInstanceMethod_Type`).  The parameter must not be *NULL*.
+
+
+.. cfunction:: PyObject* PyInstanceMethod_New(PyObject *func)
+
+   Return a new instance method object, with *func* being any callable object
+   *func* is is the function that will be called when the instance method is
+   called.
+
+
+.. cfunction:: PyObject* PyInstanceMethod_Function(PyObject *im)
+
+   Return the function object associated with the instance method *im*.
+
+
+.. cfunction:: PyObject* PyInstanceMethod_GET_FUNCTION(PyObject *im)
+
+   Macro version of :cfunc:`PyInstanceMethod_Function` which avoids error checking.
+
+
+.. _method-objects:
+
+Method Objects
+--------------
+
+.. index:: object: method
+
+Methods are bound function objects. Methods are always bound to an instance of
+an user-defined class. Unbound methods (methods bound to a class object) are
+no longer available.
+
+
+.. cvar:: PyTypeObject PyMethod_Type
+
+   .. index:: single: MethodType (in module types)
+
+   This instance of :ctype:`PyTypeObject` represents the Python method type.  This
+   is exposed to Python programs as ``types.MethodType``.
+
+
+.. cfunction:: int PyMethod_Check(PyObject *o)
+
+   Return true if *o* is a method object (has type :cdata:`PyMethod_Type`).  The
+   parameter must not be *NULL*.
+
+
+.. cfunction:: PyObject* PyMethod_New(PyObject *func, PyObject *self)
+
+   Return a new method object, with *func* being any callable object and *self*
+   the instance the method should be bound. *func* is is the function that will
+   be called when the method is called. *self* must not be *NULL*.
+
+
+.. cfunction:: PyObject* PyMethod_Function(PyObject *meth)
+
+   Return the function object associated with the method *meth*.
+
+
+.. cfunction:: PyObject* PyMethod_GET_FUNCTION(PyObject *meth)
+
+   Macro version of :cfunc:`PyMethod_Function` which avoids error checking.
+
+
+.. cfunction:: PyObject* PyMethod_Self(PyObject *meth)
+
+   Return the instance associated with the method *meth*.
+
+
+.. cfunction:: PyObject* PyMethod_GET_SELF(PyObject *meth)
+
+   Macro version of :cfunc:`PyMethod_Self` which avoids error checking.

Doc/c-api/module.rst

+.. highlightlang:: c
+
+.. _moduleobjects:
+
+Module Objects
+--------------
+
+.. index:: object: module
+
+There are only a few functions special to module objects.
+
+
+.. cvar:: PyTypeObject PyModule_Type
+
+   .. index:: single: ModuleType (in module types)
+
+   This instance of :ctype:`PyTypeObject` represents the Python module type.  This
+   is exposed to Python programs as ``types.ModuleType``.
+
+
+.. cfunction:: int PyModule_Check(PyObject *p)
+
+   Return true if *p* is a module object, or a subtype of a module object.
+
+
+.. cfunction:: int PyModule_CheckExact(PyObject *p)
+
+   Return true if *p* is a module object, but not a subtype of
+   :cdata:`PyModule_Type`.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: 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:`__dict__` attribute of the module object.  This
+   function never fails.  It is recommended extensions use other
+   :cfunc:`PyModule_\*` and :cfunc:`PyObject_\*` functions rather than directly
+   manipulate a module's :attr:`__dict__`.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: 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*.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: 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.

Doc/c-api/none.rst

+.. highlightlang:: c
+
+.. _noneobject:
+
+The None Object
+---------------
+
+.. index:: object: None
+
+Note that the :ctype:`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 :cfunc:`PyNone_Check` function for the
+same reason.
+
+
+.. cvar:: 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.
+
+
+.. cmacro:: Py_RETURN_NONE
+
+   Properly handle returning :cdata:`Py_None` from within a C function (that is,
+   increment the reference count of None and return it.)

Doc/c-api/objbuffer.rst

+.. highlightlang:: c
+
+.. _abstract-buffer:
+
+Buffer Protocol
+===============
+
+
+.. cfunction:: int PyObject_AsCharBuffer(PyObject *obj, const char **buffer, Py_ssize_t *buffer_len)
+
+   Returns a pointer to a read-only memory location useable 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.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: int PyObject_CheckReadBuffer(PyObject *o)
+
+   Returns ``1`` if *o* supports the single-segment readable buffer interface.
+   Otherwise returns ``0``.
+
+
+.. cfunction:: int PyObject_AsWriteBuffer(PyObject *obj, void **buffer, Py_ssize_t *buffer_len)
+
+   Returns a pointer to a writable 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.

Doc/c-api/objimpl.rst

+.. 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

Doc/c-api/reflection.rst

+.. highlightlang:: c
+
+.. _reflection:
+
+Reflection
+==========
+
+.. cfunction:: 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.
+
+
+.. cfunction:: PyObject* PyEval_GetLocals()
+
+   Return a dictionary of the local variables in the current execution frame,
+   or *NULL* if no frame is currently executing.
+   
+
+.. cfunction:: PyObject* PyEval_GetGlobals()
+
+   Return a dictionary of the global variables in the current execution frame,
+   or *NULL* if no frame is currently executing.
+
+
+.. cfunction:: PyFrameObject* PyEval_GetFrame()
+
+   Return the current thread state's frame, which is *NULL* if no frame is
+   currently executing.
+
+
+.. cfunction:: int PyEval_GetRestricted()
+
+   If there is a current frame and it is executing in restricted mode, return true,
+   otherwise false.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: 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
+   :cfunc:`PyEval_GetFuncName`, the result will be a description of
+   *func*.

Doc/c-api/sequence.rst

+.. highlightlang:: c
+
+.. _sequence:
+
+Sequence Protocol
+=================
+
+
+.. cfunction:: int PySequence_Check(PyObject *o)
+
+   Return ``1`` if the object provides sequence protocol, and ``0`` otherwise.
+   This function always succeeds.
+
+
+.. cfunction:: Py_ssize_t PySequence_Size(PyObject *o)
+
+   .. index:: builtin: len
+
+   Returns the number of objects in sequence *o* on success, and ``-1`` on failure.
+   For objects that do not provide sequence protocol, this is equivalent to the
+   Python expression ``len(o)``.
+
+
+.. cfunction:: Py_ssize_t PySequence_Length(PyObject *o)
+
+   Alternate name for :cfunc:`PySequence_Size`.
+
+
+.. cfunction:: 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``.
+
+
+.. cfunction:: 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``.
+
+
+.. cfunction:: 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``.
+
+
+.. cfunction:: 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``.
+
+
+.. cfunction:: 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]``.
+
+
+.. cfunction:: 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]``.
+
+
+.. cfunction:: int PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v)
+
+   Assign object *v* to the *i*th element of *o*.  Returns ``-1`` on failure.  This
+   is the equivalent of the Python statement ``o[i] = v``.  This function *does
+   not* steal a reference to *v*.
+
+
+.. cfunction:: 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]``.
+
+
+.. cfunction:: 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*.  This is the equivalent of the Python statement ``o[i1:i2] = v``.
+
+
+.. cfunction:: 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]``.
+
+
+.. cfunction:: 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)``.
+
+
+.. cfunction:: 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``.
+
+
+.. cfunction:: 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)``.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: 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)``.
+
+
+.. cfunction:: PyObject* PySequence_Fast(PyObject *o, const char *m)
+
+   Returns the sequence *o* as a tuple, unless it is already a tuple or list, in
+   which case *o* is returned.  Use :cfunc:`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.
+
+
+.. cfunction:: PyObject* PySequence_Fast_GET_ITEM(PyObject *o, Py_ssize_t i)
+
+   Return the *i*th element of *o*, assuming that *o* was returned by
+   :cfunc:`PySequence_Fast`, *o* is not *NULL*, and that *i* is within bounds.
+
+
+.. cfunction:: PyObject** PySequence_Fast_ITEMS(PyObject *o)
+
+   Return the underlying array of PyObject pointers.  Assumes that *o* was returned
+   by :cfunc:`PySequence_Fast` and *o* is not *NULL*.
+
+
+.. cfunction:: PyObject* PySequence_ITEM(PyObject *o, Py_ssize_t i)
+
+   Return the *i*th element of *o* or *NULL* on failure. Macro form of
+   :cfunc:`PySequence_GetItem` but without checking that
+   :cfunc:`PySequence_Check(o)` is true and without adjustment for negative
+   indices.
+
+
+.. cfunction:: Py_ssize_t PySequence_Fast_GET_SIZE(PyObject *o)
+
+   Returns the length of *o*, assuming that *o* was returned by
+   :cfunc:`PySequence_Fast` and that *o* is not *NULL*.  The size can also be
+   gotten by calling :cfunc:`PySequence_Size` on *o*, but
+   :cfunc:`PySequence_Fast_GET_SIZE` is faster because it can assume *o* is a list
+   or tuple.

Doc/c-api/set.rst

+.. highlightlang:: c
+
+.. _setobjects:
+
+Set Objects
+-----------
+
+.. sectionauthor:: Raymond D. Hettinger <python@rcn.com>
+
+
+.. index::
+   object: set
+   object: frozenset
+
+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 :cfunc:`PyObject_CallMethod`,
+:cfunc:`PyObject_RichCompareBool`, :cfunc:`PyObject_Hash`,
+:cfunc:`PyObject_Repr`, :cfunc:`PyObject_IsTrue`, :cfunc:`PyObject_Print`, and
+:cfunc:`PyObject_GetIter`) or the abstract number protocol (including
+:cfunc:`PyNumber_And`, :cfunc:`PyNumber_Subtract`, :cfunc:`PyNumber_Or`,
+:cfunc:`PyNumber_Xor`, :cfunc:`PyNumber_InPlaceAnd`,
+:cfunc:`PyNumber_InPlaceSubtract`, :cfunc:`PyNumber_InPlaceOr`, and
+:cfunc:`PyNumber_InPlaceXor`).
+
+
+.. ctype:: PySetObject
+
+   This subtype of :ctype:`PyObject` is used to hold the internal data for both
+   :class:`set` and :class:`frozenset` objects.  It is like a :ctype:`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.
+
+
+.. cvar:: PyTypeObject PySet_Type
+
+   This is an instance of :ctype:`PyTypeObject` representing the Python
+   :class:`set` type.
+
+
+.. cvar:: PyTypeObject PyFrozenSet_Type
+
+   This is an instance of :ctype:`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.
+
+
+.. cfunction:: int PyAnySet_Check(PyObject *p)
+
+   Return true if *p* is a :class:`set` object, a :class:`frozenset` object, or an
+   instance of a subtype.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: int PyFrozenSet_CheckExact(PyObject *p)
+
+   Return true if *p* is a :class:`frozenset` object but not an instance of a
+   subtype.
+
+
+.. cfunction:: 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)``).
+
+
+.. cfunction:: 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.
+
+The following functions and macros are available for instances of :class:`set`
+or :class:`frozenset` or instances of their subtypes.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: Py_ssize_t PySet_GET_SIZE(PyObject *anyset)
+
+   Macro form of :cfunc:`PySet_Size` without error checking.
+
+
+.. cfunction:: 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.
+
+The following functions are available for instances of :class:`set` or its
+subtypes but not for instances of :class:`frozenset` or its subtypes.
+
+
+.. cfunction:: 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 an not an instance of :class:`set` or its
+   subtype.
+
+
+.. cfunction:: 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:`discard`
+   method, this function does not automatically convert unhashable sets into
+   temporary frozensets. Raise :exc:`PyExc_SystemError` if *set* is an not an
+   instance of :class:`set` or its subtype.
+
+
+.. cfunction:: 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 an not an instance of
+   :class:`set` or its subtype.
+
+
+.. cfunction:: int PySet_Clear(PyObject *set)
+
+   Empty an existing set of all elements.