Skip to content

C
cpython
Commit 60203b41 authored by Georg Brandl's avatar Georg Brandl
Browse files
Options

Migrate to Sphinx 1.0 C language constructs.

parent 64a41edb
Expand all Show whitespace changes
Inline Side-by-side
Showing with 2573 additions and 2569 deletions
Doc/c-api/allocation.rst
View file @ 60203b41
......@@ -6,13 +6,13 @@ Allocating Objects on the Heap
==============================
.. cfunction:: PyObject* _PyObject_New(PyTypeObject *type)
.. c:function:: PyObject* _PyObject_New(PyTypeObject *type)
.. cfunction:: PyVarObject* _PyObject_NewVar(PyTypeObject *type, Py_ssize_t size)
.. c:function:: PyVarObject* _PyObject_NewVar(PyTypeObject *type, Py_ssize_t size)
.. cfunction:: PyObject* PyObject_Init(PyObject *op, PyTypeObject *type)
.. c:function:: PyObject* PyObject_Init(PyObject *op, PyTypeObject *type)
Initialize a newly-allocated object *op* with its type and initial
reference. Returns the initialized object. If *type* indicates that the
......@@ -21,13 +21,13 @@ Allocating Objects on the Heap
affected.
.. cfunction:: PyVarObject* PyObject_InitVar(PyVarObject *op, PyTypeObject *type, Py_ssize_t size)
.. c:function:: PyVarObject* PyObject_InitVar(PyVarObject *op, PyTypeObject *type, Py_ssize_t size)
This does everything :cfunc:`PyObject_Init` does, and also initializes the
This does everything :c:func:`PyObject_Init` does, and also initializes the
length information for a variable-size object.
.. cfunction:: TYPE* PyObject_New(TYPE, PyTypeObject *type)
.. c:function:: TYPE* PyObject_New(TYPE, PyTypeObject *type)
Allocate a new Python object using the C structure type *TYPE* and the
Python type object *type*. Fields not defined by the Python object header
......@@ -36,7 +36,7 @@ Allocating Objects on the Heap
the type object.
.. cfunction:: TYPE* PyObject_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)
.. c:function:: TYPE* PyObject_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)
Allocate a new Python object using the C structure type *TYPE* and the
Python type object *type*. Fields not defined by the Python object header
......@@ -48,24 +48,24 @@ Allocating Objects on the Heap
improving the memory management efficiency.
.. cfunction:: void PyObject_Del(PyObject *op)
.. c:function:: 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
Releases memory allocated to an object using :c:func:`PyObject_New` or
:c:func:`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.
.. cvar:: PyObject _Py_NoneStruct
.. c:var:: 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
using the :c:macro:`Py_None` macro, which evaluates to a pointer to this
object.
.. seealso::
:cfunc:`PyModule_Create`
:c:func:`PyModule_Create`
To allocate and create extension modules.
Doc/c-api/arg.rst
View file @ 60203b41
This diff is collapsed.
Doc/c-api/bool.rst
View file @ 60203b41
......@@ -11,36 +11,36 @@ creation and deletion functions don't apply to booleans. The following macros
are available, however.
.. cfunction:: int PyBool_Check(PyObject *o)
.. c:function:: int PyBool_Check(PyObject *o)
Return true if *o* is of type :cdata:`PyBool_Type`.
Return true if *o* is of type :c:data:`PyBool_Type`.
.. cvar:: PyObject* Py_False
.. c:var:: PyObject* Py_False
The Python ``False`` object. This object has no methods. It needs to be
treated just like any other object with respect to reference counts.
.. cvar:: PyObject* Py_True
.. c:var:: PyObject* Py_True
The Python ``True`` object. This object has no methods. It needs to be treated
just like any other object with respect to reference counts.
.. cmacro:: Py_RETURN_FALSE
.. c:macro:: Py_RETURN_FALSE
Return :const:`Py_False` from a function, properly incrementing its reference
count.
.. cmacro:: Py_RETURN_TRUE
.. c:macro:: Py_RETURN_TRUE
Return :const:`Py_True` from a function, properly incrementing its reference
count.
.. cfunction:: PyObject* PyBool_FromLong(long v)
.. c:function:: PyObject* PyBool_FromLong(long v)
Return a new reference to :const:`Py_True` or :const:`Py_False` depending on the
truth value of *v*.
Doc/c-api/buffer.rst
View file @ 60203b41
This diff is collapsed.
Doc/c-api/bytearray.rst
View file @ 60203b41
......@@ -8,26 +8,26 @@ Byte Array Objects
.. index:: object: bytearray
.. ctype:: PyByteArrayObject
.. c:type:: PyByteArrayObject
This subtype of :ctype:`PyObject` represents a Python bytearray object.
This subtype of :c:type:`PyObject` represents a Python bytearray object.
.. cvar:: PyTypeObject PyByteArray_Type
.. c:var:: PyTypeObject PyByteArray_Type
This instance of :ctype:`PyTypeObject` represents the Python bytearray type;
This instance of :c:type:`PyTypeObject` represents the Python bytearray type;
it is the same object as ``bytearray`` in the Python layer.
Type check macros
^^^^^^^^^^^^^^^^^
.. cfunction:: int PyByteArray_Check(PyObject *o)
.. c:function:: int PyByteArray_Check(PyObject *o)
Return true if the object *o* is a bytearray object or an instance of a
subtype of the bytearray type.
.. cfunction:: int PyByteArray_CheckExact(PyObject *o)
.. c:function:: int PyByteArray_CheckExact(PyObject *o)
Return true if the object *o* is a bytearray object, but not an instance of a
subtype of the bytearray type.
......@@ -36,7 +36,7 @@ Type check macros
Direct API functions
^^^^^^^^^^^^^^^^^^^^
.. cfunction:: PyObject* PyByteArray_FromObject(PyObject *o)
.. c:function:: PyObject* PyByteArray_FromObject(PyObject *o)
Return a new bytearray object from any object, *o*, that implements the
buffer protocol.
......@@ -44,29 +44,29 @@ Direct API functions
.. XXX expand about the buffer protocol, at least somewhere
.. cfunction:: PyObject* PyByteArray_FromStringAndSize(const char *string, Py_ssize_t len)
.. c:function:: PyObject* PyByteArray_FromStringAndSize(const char *string, Py_ssize_t len)
Create a new bytearray object from *string* and its length, *len*. On
failure, *NULL* is returned.
.. cfunction:: PyObject* PyByteArray_Concat(PyObject *a, PyObject *b)
.. c:function:: PyObject* PyByteArray_Concat(PyObject *a, PyObject *b)
Concat bytearrays *a* and *b* and return a new bytearray with the result.
.. cfunction:: Py_ssize_t PyByteArray_Size(PyObject *bytearray)
.. c:function:: Py_ssize_t PyByteArray_Size(PyObject *bytearray)
Return the size of *bytearray* after checking for a *NULL* pointer.
.. cfunction:: char* PyByteArray_AsString(PyObject *bytearray)
.. c:function:: char* PyByteArray_AsString(PyObject *bytearray)
Return the contents of *bytearray* as a char array after checking for a
*NULL* pointer.
.. cfunction:: int PyByteArray_Resize(PyObject *bytearray, Py_ssize_t len)
.. c:function:: int PyByteArray_Resize(PyObject *bytearray, Py_ssize_t len)
Resize the internal buffer of *bytearray* to *len*.
......@@ -75,11 +75,11 @@ Macros
These macros trade safety for speed and they don't check pointers.
.. cfunction:: char* PyByteArray_AS_STRING(PyObject *bytearray)
.. c:function:: char* PyByteArray_AS_STRING(PyObject *bytearray)
Macro version of :cfunc:`PyByteArray_AsString`.
Macro version of :c:func:`PyByteArray_AsString`.
.. cfunction:: Py_ssize_t PyByteArray_GET_SIZE(PyObject *bytearray)
.. c:function:: Py_ssize_t PyByteArray_GET_SIZE(PyObject *bytearray)
Macro version of :cfunc:`PyByteArray_Size`.
Macro version of :c:func:`PyByteArray_Size`.
Doc/c-api/bytes.rst
View file @ 60203b41
......@@ -11,48 +11,48 @@ called with a non-bytes parameter.
.. index:: object: bytes
.. ctype:: PyBytesObject
.. c:type:: PyBytesObject
This subtype of :ctype:`PyObject` represents a Python bytes object.
This subtype of :c:type:`PyObject` represents a Python bytes object.
.. cvar:: PyTypeObject PyBytes_Type
.. c:var:: PyTypeObject PyBytes_Type
.. index:: single: BytesType (in module types)
This instance of :ctype:`PyTypeObject` represents the Python bytes type; it
This instance of :c:type:`PyTypeObject` represents the Python bytes type; it
is the same object as ``bytes`` in the Python layer. .
.. cfunction:: int PyBytes_Check(PyObject *o)
.. c:function:: int PyBytes_Check(PyObject *o)
Return true if the object *o* is a bytes object or an instance of a subtype
of the bytes type.
.. cfunction:: int PyBytes_CheckExact(PyObject *o)
.. c:function:: int PyBytes_CheckExact(PyObject *o)
Return true if the object *o* is a bytes object, but not an instance of a
subtype of the bytes type.
.. cfunction:: PyObject* PyBytes_FromString(const char *v)
.. c:function:: PyObject* PyBytes_FromString(const char *v)
Return a new bytes object with a copy of the string *v* as value on success,
and *NULL* on failure. The parameter *v* must not be *NULL*; it will not be
checked.
.. cfunction:: PyObject* PyBytes_FromStringAndSize(const char *v, Py_ssize_t len)
.. c:function:: PyObject* PyBytes_FromStringAndSize(const char *v, Py_ssize_t len)
Return a new bytes object with a copy of the string *v* as value and length
*len* on success, and *NULL* on failure. If *v* is *NULL*, the contents of
the bytes object are uninitialized.
.. cfunction:: PyObject* PyBytes_FromFormat(const char *format, ...)
.. c:function:: PyObject* PyBytes_FromFormat(const char *format, ...)
Take a C :cfunc:`printf`\ -style *format* string and a variable number of
Take a C :c:func:`printf`\ -style *format* string and a variable number of
arguments, calculate the size of the resulting Python bytes object and return
a bytes object with the values formatted into it. The variable arguments
must be C types and must correspond exactly to the format characters in the
......@@ -112,44 +112,44 @@ called with a non-bytes parameter.
copied as-is to the result string, and any extra arguments discarded.
.. cfunction:: PyObject* PyBytes_FromFormatV(const char *format, va_list vargs)
.. c:function:: PyObject* PyBytes_FromFormatV(const char *format, va_list vargs)
Identical to :cfunc:`PyBytes_FromFormat` except that it takes exactly two
Identical to :c:func:`PyBytes_FromFormat` except that it takes exactly two
arguments.
.. cfunction:: PyObject* PyBytes_FromObject(PyObject *o)
.. c:function:: PyObject* PyBytes_FromObject(PyObject *o)
Return the bytes representation of object *o* that implements the buffer
protocol.
.. cfunction:: Py_ssize_t PyBytes_Size(PyObject *o)
.. c:function:: Py_ssize_t PyBytes_Size(PyObject *o)
Return the length of the bytes in bytes object *o*.
.. cfunction:: Py_ssize_t PyBytes_GET_SIZE(PyObject *o)
.. c:function:: Py_ssize_t PyBytes_GET_SIZE(PyObject *o)
Macro form of :cfunc:`PyBytes_Size` but without error checking.
Macro form of :c:func:`PyBytes_Size` but without error checking.
.. cfunction:: char* PyBytes_AsString(PyObject *o)
.. c:function:: char* PyBytes_AsString(PyObject *o)
Return a NUL-terminated representation of the contents of *o*. The pointer
refers to the internal buffer of *o*, not a copy. The data must not be
modified in any way, unless the string was just created using
``PyBytes_FromStringAndSize(NULL, size)``. It must not be deallocated. If
*o* is not a string object at all, :cfunc:`PyBytes_AsString` returns *NULL*
*o* is not a string object at all, :c:func:`PyBytes_AsString` returns *NULL*
and raises :exc:`TypeError`.
.. cfunction:: char* PyBytes_AS_STRING(PyObject *string)
.. c:function:: char* PyBytes_AS_STRING(PyObject *string)
Macro form of :cfunc:`PyBytes_AsString` but without error checking.
Macro form of :c:func:`PyBytes_AsString` but without error checking.
.. cfunction:: int PyBytes_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)
.. c:function:: int PyBytes_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)
Return a NUL-terminated representation of the contents of the object *obj*
through the output variables *buffer* and *length*.
......@@ -160,11 +160,11 @@ called with a non-bytes parameter.
The buffer refers to an internal string buffer of *obj*, not a copy. The data
must not be modified in any way, unless the string was just created using
``PyBytes_FromStringAndSize(NULL, size)``. It must not be deallocated. If
*string* is not a string object at all, :cfunc:`PyBytes_AsStringAndSize`
*string* is not a string object at all, :c:func:`PyBytes_AsStringAndSize`
returns ``-1`` and raises :exc:`TypeError`.
.. cfunction:: void PyBytes_Concat(PyObject **bytes, PyObject *newpart)
.. c:function:: void PyBytes_Concat(PyObject **bytes, PyObject *newpart)
Create a new bytes object in *\*bytes* containing the contents of *newpart*
appended to *bytes*; the caller will own the new reference. The reference to
......@@ -173,14 +173,14 @@ called with a non-bytes parameter.
of *\*bytes* will be set to *NULL*; the appropriate exception will be set.
.. cfunction:: void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart)
.. c:function:: void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart)
Create a new string object in *\*bytes* containing the contents of *newpart*
appended to *bytes*. This version decrements the reference count of
*newpart*.
.. cfunction:: int _PyBytes_Resize(PyObject **bytes, Py_ssize_t newsize)
.. c:function:: int _PyBytes_Resize(PyObject **bytes, Py_ssize_t newsize)
A way to resize a bytes object even though it is "immutable". Only use this
to build up a brand new bytes object; don't use this if the bytes may already
......
Doc/c-api/capsule.rst
View file @ 60203b41
......@@ -10,33 +10,33 @@ Capsules
Refer to :ref:`using-capsules` for more information on using these objects.
.. ctype:: PyCapsule
.. c:type:: PyCapsule
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\*`
This subtype of :c:type:`PyObject` represents an opaque value, useful for C
extension modules who need to pass an opaque value (as a :c:type:`void\*`
pointer) through Python code to other C code. It is often used to make a C
function pointer defined in one module available to other modules, so the
regular import mechanism can be used to access C APIs defined in dynamically
loaded modules.
.. ctype:: PyCapsule_Destructor
.. c:type:: PyCapsule_Destructor
The type of a destructor callback for a capsule. Defined as::
typedef void (*PyCapsule_Destructor)(PyObject *);
See :cfunc:`PyCapsule_New` for the semantics of PyCapsule_Destructor
See :c:func:`PyCapsule_New` for the semantics of PyCapsule_Destructor
callbacks.
.. cfunction:: int PyCapsule_CheckExact(PyObject *p)
.. c:function:: int PyCapsule_CheckExact(PyObject *p)
Return true if its argument is a :ctype:`PyCapsule`.
Return true if its argument is a :c:type:`PyCapsule`.
.. cfunction:: PyObject* PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)
.. c:function:: PyObject* PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)
Create a :ctype:`PyCapsule` encapsulating the *pointer*. The *pointer*
Create a :c:type:`PyCapsule` encapsulating the *pointer*. The *pointer*
argument may not be *NULL*.
On failure, set an exception and return *NULL*.
......@@ -50,91 +50,91 @@ Refer to :ref:`using-capsules` for more information on using these objects.
If this capsule will be stored as an attribute of a module, the *name* should
be specified as ``modulename.attributename``. This will enable other modules
to import the capsule using :cfunc:`PyCapsule_Import`.
to import the capsule using :c:func:`PyCapsule_Import`.
.. cfunction:: void* PyCapsule_GetPointer(PyObject *capsule, const char *name)
.. c:function:: void* PyCapsule_GetPointer(PyObject *capsule, const char *name)
Retrieve the *pointer* stored in the capsule. On failure, set an exception
and return *NULL*.
The *name* parameter must compare exactly to the name stored in the capsule.
If the name stored in the capsule is *NULL*, the *name* passed in must also
be *NULL*. Python uses the C function :cfunc:`strcmp` to compare capsule
be *NULL*. Python uses the C function :c:func:`strcmp` to compare capsule
names.
.. cfunction:: PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)
.. c:function:: PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)
Return the current destructor stored in the capsule. On failure, set an
exception and return *NULL*.
It is legal for a capsule to have a *NULL* destructor. This makes a *NULL*
return code somewhat ambiguous; use :cfunc:`PyCapsule_IsValid` or
:cfunc:`PyErr_Occurred` to disambiguate.
return code somewhat ambiguous; use :c:func:`PyCapsule_IsValid` or
:c:func:`PyErr_Occurred` to disambiguate.
.. cfunction:: void* PyCapsule_GetContext(PyObject *capsule)
.. c:function:: void* PyCapsule_GetContext(PyObject *capsule)
Return the current context stored in the capsule. On failure, set an
exception and return *NULL*.
It is legal for a capsule to have a *NULL* context. This makes a *NULL*
return code somewhat ambiguous; use :cfunc:`PyCapsule_IsValid` or
:cfunc:`PyErr_Occurred` to disambiguate.
return code somewhat ambiguous; use :c:func:`PyCapsule_IsValid` or
:c:func:`PyErr_Occurred` to disambiguate.
.. cfunction:: const char* PyCapsule_GetName(PyObject *capsule)
.. c:function:: const char* PyCapsule_GetName(PyObject *capsule)
Return the current name stored in the capsule. On failure, set an exception
and return *NULL*.
It is legal for a capsule to have a *NULL* name. This makes a *NULL* return
code somewhat ambiguous; use :cfunc:`PyCapsule_IsValid` or
:cfunc:`PyErr_Occurred` to disambiguate.
code somewhat ambiguous; use :c:func:`PyCapsule_IsValid` or
:c:func:`PyErr_Occurred` to disambiguate.
.. cfunction:: void* PyCapsule_Import(const char *name, int no_block)
.. c:function:: void* PyCapsule_Import(const char *name, int no_block)
Import a pointer to a C object from a capsule attribute in a module. The
*name* parameter should specify the full name to the attribute, as in
``module.attribute``. The *name* stored in the capsule must match this
string exactly. If *no_block* is true, import the module without blocking
(using :cfunc:`PyImport_ImportModuleNoBlock`). If *no_block* is false,
import the module conventionally (using :cfunc:`PyImport_ImportModule`).
(using :c:func:`PyImport_ImportModuleNoBlock`). If *no_block* is false,
import the module conventionally (using :c:func:`PyImport_ImportModule`).
Return the capsule's internal *pointer* on success. On failure, set an
exception and return *NULL*. However, if :cfunc:`PyCapsule_Import` failed to
exception and return *NULL*. However, if :c:func:`PyCapsule_Import` failed to
import the module, and *no_block* was true, no exception is set.
.. cfunction:: int PyCapsule_IsValid(PyObject *capsule, const char *name)
.. c:function:: int PyCapsule_IsValid(PyObject *capsule, const char *name)
Determines whether or not *capsule* is a valid capsule. A valid capsule is
non-*NULL*, passes :cfunc:`PyCapsule_CheckExact`, has a non-*NULL* pointer
non-*NULL*, passes :c:func:`PyCapsule_CheckExact`, has a non-*NULL* pointer
stored in it, and its internal name matches the *name* parameter. (See
:cfunc:`PyCapsule_GetPointer` for information on how capsule names are
:c:func:`PyCapsule_GetPointer` for information on how capsule names are
compared.)
In other words, if :cfunc:`PyCapsule_IsValid` returns a true value, calls to
any of the accessors (any function starting with :cfunc:`PyCapsule_Get`) are
In other words, if :c:func:`PyCapsule_IsValid` returns a true value, calls to
any of the accessors (any function starting with :c:func:`PyCapsule_Get`) are
guaranteed to succeed.
Return a nonzero value if the object is valid and matches the name passed in.
Return 0 otherwise. This function will not fail.
.. cfunction:: int PyCapsule_SetContext(PyObject *capsule, void *context)
.. c:function:: int PyCapsule_SetContext(PyObject *capsule, void *context)
Set the context pointer inside *capsule* to *context*.
Return 0 on success. Return nonzero and set an exception on failure.
.. cfunction:: int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)
.. c:function:: int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)
Set the destructor inside *capsule* to *destructor*.
Return 0 on success. Return nonzero and set an exception on failure.
.. cfunction:: int PyCapsule_SetName(PyObject *capsule, const char *name)
.. c:function:: int PyCapsule_SetName(PyObject *capsule, const char *name)
Set the name inside *capsule* to *name*. If non-*NULL*, the name must
outlive the capsule. If the previous *name* stored in the capsule was not
......@@ -142,7 +142,7 @@ Refer to :ref:`using-capsules` for more information on using these objects.
Return 0 on success. Return nonzero and set an exception on failure.
.. cfunction:: int PyCapsule_SetPointer(PyObject *capsule, void *pointer)
.. c:function:: int PyCapsule_SetPointer(PyObject *capsule, void *pointer)
Set the void pointer inside *capsule* to *pointer*. The pointer may not be
*NULL*.
......
Doc/c-api/cell.rst
View file @ 60203b41
......@@ -15,39 +15,39 @@ generated byte-code; these are not automatically de-referenced when accessed.
Cell objects are not likely to be useful elsewhere.
.. ctype:: PyCellObject
.. c:type:: PyCellObject
The C structure used for cell objects.
.. cvar:: PyTypeObject PyCell_Type
.. c:var:: PyTypeObject PyCell_Type
The type object corresponding to cell objects.
.. cfunction:: int PyCell_Check(ob)
.. c:function:: int PyCell_Check(ob)
Return true if *ob* is a cell object; *ob* must not be *NULL*.
.. cfunction:: PyObject* PyCell_New(PyObject *ob)
.. c:function:: 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)
.. c:function:: PyObject* PyCell_Get(PyObject *cell)
Return the contents of the cell *cell*.
.. cfunction:: PyObject* PyCell_GET(PyObject *cell)
.. c:function:: PyObject* PyCell_GET(PyObject *cell)
Return the contents of the cell *cell*, but without checking that *cell* is
non-*NULL* and a cell object.
.. cfunction:: int PyCell_Set(PyObject *cell, PyObject *value)
.. c:function:: int PyCell_Set(PyObject *cell, PyObject *value)
Set the contents of the cell object *cell* to *value*. This releases the
reference to any current content of the cell. *value* may be *NULL*. *cell*
......@@ -55,7 +55,7 @@ Cell objects are not likely to be useful elsewhere.
success, ``0`` will be returned.
.. cfunction:: void PyCell_SET(PyObject *cell, PyObject *value)
.. c:function:: void PyCell_SET(PyObject *cell, PyObject *value)
Sets the value of the cell object *cell* to *value*. No reference counts are
adjusted, and no checks are made for safety; *cell* must be non-*NULL* and must
......
Doc/c-api/code.rst
View file @ 60203b41
......@@ -15,35 +15,35 @@ Code objects are a low-level detail of the CPython implementation.
Each one represents a chunk of executable code that hasn't yet been
bound into a function.
.. ctype:: PyCodeObject
.. c:type:: PyCodeObject
The C structure of the objects used to describe code objects. The
fields of this type are subject to change at any time.
.. cvar:: PyTypeObject PyCode_Type
.. c:var:: PyTypeObject PyCode_Type
This is an instance of :ctype:`PyTypeObject` representing the Python
This is an instance of :c:type:`PyTypeObject` representing the Python
:class:`code` type.
.. cfunction:: int PyCode_Check(PyObject *co)
.. c:function:: int PyCode_Check(PyObject *co)
Return true if *co* is a :class:`code` object
.. cfunction:: int PyCode_GetNumFree(PyObject *co)
.. c:function:: int PyCode_GetNumFree(PyObject *co)
Return the number of free variables in *co*.
.. cfunction:: PyCodeObject *PyCode_New(int argcount, int nlocals, int stacksize, int flags, PyObject *code, PyObject *consts, PyObject *names, PyObject *varnames, PyObject *freevars, PyObject *cellvars, PyObject *filename, PyObject *name, int firstlineno, PyObject *lnotab)
.. c:function:: PyCodeObject *PyCode_New(int argcount, int nlocals, int stacksize, int flags, PyObject *code, PyObject *consts, PyObject *names, PyObject *varnames, PyObject *freevars, PyObject *cellvars, PyObject *filename, PyObject *name, int firstlineno, PyObject *lnotab)
Return a new code object. If you need a dummy code object to
create a frame, use :cfunc:`PyCode_NewEmpty` instead. Calling
:cfunc:`PyCode_New` directly can bind you to a precise Python
create a frame, use :c:func:`PyCode_NewEmpty` instead. Calling
:c:func:`PyCode_New` directly can bind you to a precise Python
version since the definition of the bytecode changes often.
.. cfunction:: int PyCode_NewEmpty(const char *filename, const char *funcname, int firstlineno)
.. c:function:: int PyCode_NewEmpty(const char *filename, const char *funcname, int firstlineno)
Return a new empty code object with the specified filename,
function name, and first line number. It is illegal to
......
Doc/c-api/complex.rst
View file @ 60203b41
......@@ -21,7 +21,7 @@ them as results do so *by value* rather than dereferencing them through
pointers. This is consistent throughout the API.
.. ctype:: Py_complex
.. c:type:: Py_complex
The C structure which corresponds to the value portion of a Python complex
number object. Most of the functions for dealing with complex number objects
......@@ -34,39 +34,39 @@ pointers. This is consistent throughout the API.
} Py_complex;
.. cfunction:: Py_complex _Py_c_sum(Py_complex left, Py_complex right)
.. c:function:: Py_complex _Py_c_sum(Py_complex left, Py_complex right)
Return the sum of two complex numbers, using the C :ctype:`Py_complex`
Return the sum of two complex numbers, using the C :c:type:`Py_complex`
representation.
.. cfunction:: Py_complex _Py_c_diff(Py_complex left, Py_complex right)
.. c:function:: 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.
:c:type:`Py_complex` representation.
.. cfunction:: Py_complex _Py_c_neg(Py_complex complex)
.. c:function:: Py_complex _Py_c_neg(Py_complex complex)
Return the negation of the complex number *complex*, using the C
:ctype:`Py_complex` representation.
:c:type:`Py_complex` representation.
.. cfunction:: Py_complex _Py_c_prod(Py_complex left, Py_complex right)
.. c:function:: Py_complex _Py_c_prod(Py_complex left, Py_complex right)
Return the product of two complex numbers, using the C :ctype:`Py_complex`
Return the product of two complex numbers, using the C :c:type:`Py_complex`
representation.
.. cfunction:: Py_complex _Py_c_quot(Py_complex dividend, Py_complex divisor)
.. c:function:: Py_complex _Py_c_quot(Py_complex dividend, Py_complex divisor)
Return the quotient of two complex numbers, using the C :ctype:`Py_complex`
Return the quotient of two complex numbers, using the C :c:type:`Py_complex`
representation.
.. cfunction:: Py_complex _Py_c_pow(Py_complex num, Py_complex exp)
.. c:function:: Py_complex _Py_c_pow(Py_complex num, Py_complex exp)
Return the exponentiation of *num* by *exp*, using the C :ctype:`Py_complex`
Return the exponentiation of *num* by *exp*, using the C :c:type:`Py_complex`
representation.
......@@ -74,52 +74,52 @@ Complex Numbers as Python Objects
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. ctype:: PyComplexObject
.. c:type:: PyComplexObject
This subtype of :ctype:`PyObject` represents a Python complex number object.
This subtype of :c:type:`PyObject` represents a Python complex number object.
.. cvar:: PyTypeObject PyComplex_Type
.. c:var:: PyTypeObject PyComplex_Type
This instance of :ctype:`PyTypeObject` represents the Python complex number
This instance of :c:type:`PyTypeObject` represents the Python complex number
type. It is the same object as ``complex`` and ``types.ComplexType``.
.. cfunction:: int PyComplex_Check(PyObject *p)
.. c:function:: int PyComplex_Check(PyObject *p)
Return true if its argument is a :ctype:`PyComplexObject` or a subtype of
:ctype:`PyComplexObject`.
Return true if its argument is a :c:type:`PyComplexObject` or a subtype of
:c:type:`PyComplexObject`.
.. cfunction:: int PyComplex_CheckExact(PyObject *p)
.. c:function:: int PyComplex_CheckExact(PyObject *p)
Return true if its argument is a :ctype:`PyComplexObject`, but not a subtype of
:ctype:`PyComplexObject`.
Return true if its argument is a :c:type:`PyComplexObject`, but not a subtype of
:c:type:`PyComplexObject`.
.. cfunction:: PyObject* PyComplex_FromCComplex(Py_complex v)
.. c:function:: PyObject* PyComplex_FromCComplex(Py_complex v)
Create a new Python complex number object from a C :ctype:`Py_complex` value.
Create a new Python complex number object from a C :c:type:`Py_complex` value.
.. cfunction:: PyObject* PyComplex_FromDoubles(double real, double imag)
.. c:function:: PyObject* PyComplex_FromDoubles(double real, double imag)
Return a new :ctype:`PyComplexObject` object from *real* and *imag*.
Return a new :c:type:`PyComplexObject` object from *real* and *imag*.
.. cfunction:: double PyComplex_RealAsDouble(PyObject *op)
.. c:function:: double PyComplex_RealAsDouble(PyObject *op)
Return the real part of *op* as a C :ctype:`double`.
Return the real part of *op* as a C :c:type:`double`.
.. cfunction:: double PyComplex_ImagAsDouble(PyObject *op)
.. c:function:: double PyComplex_ImagAsDouble(PyObject *op)
Return the imaginary part of *op* as a C :ctype:`double`.
Return the imaginary part of *op* as a C :c:type:`double`.
.. cfunction:: Py_complex PyComplex_AsCComplex(PyObject *op)
.. c:function:: Py_complex PyComplex_AsCComplex(PyObject *op)
Return the :ctype:`Py_complex` value of the complex number *op*.
Return the :c:type:`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
......
Doc/c-api/concrete.rst
View file @ 60203b41
......@@ -11,7 +11,7 @@ The functions in this chapter are specific to certain Python object types.
Passing them an object of the wrong type is not a good idea; if you receive an
object from a Python program and you are not sure that it has the right type,
you must perform a type check first; for example, to check that an object is a
dictionary, use :cfunc:`PyDict_Check`. The chapter is structured like the
dictionary, use :c:func:`PyDict_Check`. The chapter is structured like the
"family tree" of Python object types.
.. warning::
......
Doc/c-api/conversion.rst
View file @ 60203b41
......@@ -8,20 +8,20 @@ String conversion and formatting
Functions for number conversion and formatted string output.
.. cfunction:: int PyOS_snprintf(char *str, size_t size, const char *format, ...)
.. c:function:: int PyOS_snprintf(char *str, size_t size, const char *format, ...)
Output not more than *size* bytes to *str* according to the format string
*format* and the extra arguments. See the Unix man page :manpage:`snprintf(2)`.
.. cfunction:: int PyOS_vsnprintf(char *str, size_t size, const char *format, va_list va)
.. c:function:: int PyOS_vsnprintf(char *str, size_t size, const char *format, va_list va)
Output not more than *size* bytes to *str* according to the format string
*format* and the variable argument list *va*. Unix man page
:manpage:`vsnprintf(2)`.
:cfunc:`PyOS_snprintf` and :cfunc:`PyOS_vsnprintf` wrap the Standard C library
functions :cfunc:`snprintf` and :cfunc:`vsnprintf`. Their purpose is to
:c:func:`PyOS_snprintf` and :c:func:`PyOS_vsnprintf` wrap the Standard C library
functions :c:func:`snprintf` and :c:func:`vsnprintf`. Their purpose is to
guarantee consistent behavior in corner cases, which the Standard C functions do
not.
......@@ -30,7 +30,7 @@ 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
If the platform doesn't have :c:func:`vsnprintf` and the buffer size needed to
avoid truncation exceeds *size* by more than 512 bytes, Python aborts with a
*Py_FatalError*.
......@@ -51,9 +51,9 @@ The return value (*rv*) for these functions should be interpreted as follows:
The following functions provide locale-independent string to number conversions.
.. cfunction:: double PyOS_string_to_double(const char *s, char **endptr, PyObject *overflow_exception)
.. c:function:: double PyOS_string_to_double(const char *s, char **endptr, PyObject *overflow_exception)
Convert a string ``s`` to a :ctype:`double`, raising a Python
Convert a string ``s`` to a :c:type:`double`, raising a Python
exception on failure. The set of accepted strings corresponds to
the set of strings accepted by Python's :func:`float` constructor,
except that ``s`` must not have leading or trailing whitespace.
......@@ -85,9 +85,9 @@ The following functions provide locale-independent string to number conversions.
.. versionadded:: 3.1
.. cfunction:: char* PyOS_double_to_string(double val, char format_code, int precision, int flags, int *ptype)
.. c:function:: char* PyOS_double_to_string(double val, char format_code, int precision, int flags, int *ptype)
Convert a :ctype:`double` *val* to a string using supplied
Convert a :c:type:`double` *val* to a string using supplied
*format_code*, *precision*, and *flags*.
*format_code* must be one of ``'e'``, ``'E'``, ``'f'``, ``'F'``,
......@@ -105,7 +105,7 @@ The following functions provide locale-independent string to number conversions.
like an integer.
* *Py_DTSF_ALT* means to apply "alternate" formatting rules. See the
documentation for the :cfunc:`PyOS_snprintf` ``'#'`` specifier for
documentation for the :c:func:`PyOS_snprintf` ``'#'`` specifier for
details.
If *ptype* is non-NULL, then the value it points to will be set to one of
......@@ -114,18 +114,18 @@ The following functions provide locale-independent string to number conversions.
The return value is a pointer to *buffer* with the converted string or
*NULL* if the conversion failed. The caller is responsible for freeing the
returned string by calling :cfunc:`PyMem_Free`.
returned string by calling :c:func:`PyMem_Free`.
.. versionadded:: 3.1
.. cfunction:: char* PyOS_stricmp(char *s1, char *s2)
.. c:function:: char* PyOS_stricmp(char *s1, char *s2)
Case insensitive comparison of strings. The function works almost
identically to :cfunc:`strcmp` except that it ignores the case.
identically to :c:func:`strcmp` except that it ignores the case.
.. cfunction:: char* PyOS_strnicmp(char *s1, char *s2, Py_ssize_t size)
.. c:function:: char* PyOS_strnicmp(char *s1, char *s2, Py_ssize_t size)
Case insensitive comparison of strings. The function works almost
identically to :cfunc:`strncmp` except that it ignores the case.
identically to :c:func:`strncmp` except that it ignores the case.
Doc/c-api/datetime.rst
View file @ 60203b41
......@@ -8,93 +8,93 @@ 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 :cmacro:`PyDateTime_IMPORT` must be invoked, usually as part of
and the macro :c:macro:`PyDateTime_IMPORT` must be invoked, usually as part of
the module initialisation function. The macro puts a pointer to a C structure
into a static variable, :cdata:`PyDateTimeAPI`, that is used by the following
into a static variable, :c:data:`PyDateTimeAPI`, that is used by the following
macros.
Type-check macros:
.. cfunction:: int PyDate_Check(PyObject *ob)
.. c:function:: 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*.
Return true if *ob* is of type :c:data:`PyDateTime_DateType` or a subtype of
:c:data:`PyDateTime_DateType`. *ob* must not be *NULL*.
.. cfunction:: int PyDate_CheckExact(PyObject *ob)
.. c:function:: int PyDate_CheckExact(PyObject *ob)
Return true if *ob* is of type :cdata:`PyDateTime_DateType`. *ob* must not be
Return true if *ob* is of type :c:data:`PyDateTime_DateType`. *ob* must not be
*NULL*.
.. cfunction:: int PyDateTime_Check(PyObject *ob)
.. c:function:: 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*.
Return true if *ob* is of type :c:data:`PyDateTime_DateTimeType` or a subtype of
:c:data:`PyDateTime_DateTimeType`. *ob* must not be *NULL*.
.. cfunction:: int PyDateTime_CheckExact(PyObject *ob)
.. c:function:: int PyDateTime_CheckExact(PyObject *ob)
Return true if *ob* is of type :cdata:`PyDateTime_DateTimeType`. *ob* must not
Return true if *ob* is of type :c:data:`PyDateTime_DateTimeType`. *ob* must not
be *NULL*.
.. cfunction:: int PyTime_Check(PyObject *ob)
.. c:function:: 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*.
Return true if *ob* is of type :c:data:`PyDateTime_TimeType` or a subtype of
:c:data:`PyDateTime_TimeType`. *ob* must not be *NULL*.
.. cfunction:: int PyTime_CheckExact(PyObject *ob)
.. c:function:: int PyTime_CheckExact(PyObject *ob)
Return true if *ob* is of type :cdata:`PyDateTime_TimeType`. *ob* must not be
Return true if *ob* is of type :c:data:`PyDateTime_TimeType`. *ob* must not be
*NULL*.
.. cfunction:: int PyDelta_Check(PyObject *ob)
.. c:function:: 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*.
Return true if *ob* is of type :c:data:`PyDateTime_DeltaType` or a subtype of
:c:data:`PyDateTime_DeltaType`. *ob* must not be *NULL*.
.. cfunction:: int PyDelta_CheckExact(PyObject *ob)
.. c:function:: int PyDelta_CheckExact(PyObject *ob)
Return true if *ob* is of type :cdata:`PyDateTime_DeltaType`. *ob* must not be
Return true if *ob* is of type :c:data:`PyDateTime_DeltaType`. *ob* must not be
*NULL*.
.. cfunction:: int PyTZInfo_Check(PyObject *ob)
.. c:function:: 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*.
Return true if *ob* is of type :c:data:`PyDateTime_TZInfoType` or a subtype of
:c:data:`PyDateTime_TZInfoType`. *ob* must not be *NULL*.
.. cfunction:: int PyTZInfo_CheckExact(PyObject *ob)
.. c:function:: int PyTZInfo_CheckExact(PyObject *ob)
Return true if *ob* is of type :cdata:`PyDateTime_TZInfoType`. *ob* must not be
Return true if *ob* is of type :c:data:`PyDateTime_TZInfoType`. *ob* must not be
*NULL*.
Macros to create objects:
.. cfunction:: PyObject* PyDate_FromDate(int year, int month, int day)
.. c:function:: 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)
.. c:function:: PyObject* PyDateTime_FromDateAndTime(int year, int month, int day, int hour, int minute, int second, int usecond)
Return a ``datetime.datetime`` object with the specified year, month, day, hour,
minute, second and microsecond.
.. cfunction:: PyObject* PyTime_FromTime(int hour, int minute, int second, int usecond)
.. c:function:: PyObject* PyTime_FromTime(int hour, int minute, int second, int usecond)
Return a ``datetime.time`` object with the specified hour, minute, second and
microsecond.
.. cfunction:: PyObject* PyDelta_FromDSU(int days, int seconds, int useconds)
.. c:function:: PyObject* PyDelta_FromDSU(int days, int seconds, int useconds)
Return a ``datetime.timedelta`` object representing the given number of days,
seconds and microseconds. Normalization is performed so that the resulting
......@@ -103,82 +103,82 @@ Macros to create 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
:c:data:`PyDateTime_Date`, including subclasses (such as
:c:data:`PyDateTime_DateTime`). The argument must not be *NULL*, and the type is
not checked:
.. cfunction:: int PyDateTime_GET_YEAR(PyDateTime_Date *o)
.. c:function:: int PyDateTime_GET_YEAR(PyDateTime_Date *o)
Return the year, as a positive int.
.. cfunction:: int PyDateTime_GET_MONTH(PyDateTime_Date *o)
.. c:function:: 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)
.. c:function:: 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
instance of :c:data:`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)
.. c:function:: 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)
.. c:function:: 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)
.. c:function:: 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)
.. c:function:: 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*,
:c:data:`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)
.. c:function:: 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)
.. c:function:: 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)
.. c:function:: 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)
.. c:function:: 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)
.. c:function:: PyObject* PyDateTime_FromTimestamp(PyObject *args)
Create and return a new ``datetime.datetime`` object given an argument tuple
suitable for passing to ``datetime.datetime.fromtimestamp()``.
.. cfunction:: PyObject* PyDate_FromTimestamp(PyObject *args)
.. c:function:: PyObject* PyDate_FromTimestamp(PyObject *args)
Create and return a new ``datetime.date`` object given an argument tuple
suitable for passing to ``datetime.date.fromtimestamp()``.
Doc/c-api/descriptor.rst
View file @ 60203b41
......@@ -10,31 +10,31 @@ found in the dictionary of type objects.
.. XXX document these!
.. cvar:: PyTypeObject PyProperty_Type
.. c:var:: PyTypeObject PyProperty_Type
The type object for the built-in descriptor types.
.. cfunction:: PyObject* PyDescr_NewGetSet(PyTypeObject *type, struct PyGetSetDef *getset)
.. c:function:: PyObject* PyDescr_NewGetSet(PyTypeObject *type, struct PyGetSetDef *getset)
.. cfunction:: PyObject* PyDescr_NewMember(PyTypeObject *type, struct PyMemberDef *meth)
.. c:function:: PyObject* PyDescr_NewMember(PyTypeObject *type, struct PyMemberDef *meth)
.. cfunction:: PyObject* PyDescr_NewMethod(PyTypeObject *type, struct PyMethodDef *meth)
.. c:function:: PyObject* PyDescr_NewMethod(PyTypeObject *type, struct PyMethodDef *meth)
.. cfunction:: PyObject* PyDescr_NewWrapper(PyTypeObject *type, struct wrapperbase *wrapper, void *wrapped)
.. c:function:: PyObject* PyDescr_NewWrapper(PyTypeObject *type, struct wrapperbase *wrapper, void *wrapped)
.. cfunction:: PyObject* PyDescr_NewClassMethod(PyTypeObject *type, PyMethodDef *method)
.. c:function:: PyObject* PyDescr_NewClassMethod(PyTypeObject *type, PyMethodDef *method)
.. cfunction:: int PyDescr_IsData(PyObject *descr)
.. c:function:: int PyDescr_IsData(PyObject *descr)
Return true if the descriptor objects *descr* describes a data attribute, or
false if it describes a method. *descr* must be a descriptor object; there is
no error checking.
.. cfunction:: PyObject* PyWrapper_New(PyObject *, PyObject *)
.. c:function:: PyObject* PyWrapper_New(PyObject *, PyObject *)
Doc/c-api/dict.rst
View file @ 60203b41
......@@ -8,132 +8,132 @@ Dictionary Objects
.. index:: object: dictionary
.. ctype:: PyDictObject
.. c:type:: PyDictObject
This subtype of :ctype:`PyObject` represents a Python dictionary object.
This subtype of :c:type:`PyObject` represents a Python dictionary object.
.. cvar:: PyTypeObject PyDict_Type
.. c:var:: PyTypeObject PyDict_Type
.. index::
single: DictType (in module types)
single: DictionaryType (in module types)
This instance of :ctype:`PyTypeObject` represents the Python dictionary
This instance of :c:type:`PyTypeObject` represents the Python dictionary
type. This is exposed to Python programs as ``dict`` and
``types.DictType``.
.. cfunction:: int PyDict_Check(PyObject *p)
.. c:function:: int PyDict_Check(PyObject *p)
Return true if *p* is a dict object or an instance of a subtype of the dict
type.
.. cfunction:: int PyDict_CheckExact(PyObject *p)
.. c:function:: int PyDict_CheckExact(PyObject *p)
Return true if *p* is a dict object, but not an instance of a subtype of
the dict type.
.. cfunction:: PyObject* PyDict_New()
.. c:function:: PyObject* PyDict_New()
Return a new empty dictionary, or *NULL* on failure.
.. cfunction:: PyObject* PyDictProxy_New(PyObject *dict)
.. c:function:: PyObject* PyDictProxy_New(PyObject *dict)
Return a proxy object for a mapping which enforces read-only behavior.
This is normally used to create a proxy to prevent modification of the
dictionary for non-dynamic class types.
.. cfunction:: void PyDict_Clear(PyObject *p)
.. c:function:: void PyDict_Clear(PyObject *p)
Empty an existing dictionary of all key-value pairs.
.. cfunction:: int PyDict_Contains(PyObject *p, PyObject *key)
.. c:function:: int PyDict_Contains(PyObject *p, PyObject *key)
Determine if dictionary *p* contains *key*. If an item in *p* is matches
*key*, return ``1``, otherwise return ``0``. On error, return ``-1``.
This is equivalent to the Python expression ``key in p``.
.. cfunction:: PyObject* PyDict_Copy(PyObject *p)
.. c:function:: 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)
.. c:function:: int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)
Insert *value* into the dictionary *p* with a key of *key*. *key* must be
:term:`hashable`; if it isn't, :exc:`TypeError` will be raised. Return
``0`` on success or ``-1`` on failure.
.. cfunction:: int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)
.. c:function:: int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)
.. index:: single: PyUnicode_FromString()
Insert *value* into the dictionary *p* using *key* as a key. *key* should
be a :ctype:`char\*`. The key object is created using
be a :c:type:`char\*`. The key object is created using
``PyUnicode_FromString(key)``. Return ``0`` on success or ``-1`` on
failure.
.. cfunction:: int PyDict_DelItem(PyObject *p, PyObject *key)
.. c:function:: int PyDict_DelItem(PyObject *p, PyObject *key)
Remove the entry in dictionary *p* with key *key*. *key* must be hashable;
if it isn't, :exc:`TypeError` is raised. Return ``0`` on success or ``-1``
on failure.
.. cfunction:: int PyDict_DelItemString(PyObject *p, char *key)
.. c:function:: int PyDict_DelItemString(PyObject *p, char *key)
Remove the entry in dictionary *p* which has a key specified by the string
*key*. Return ``0`` on success or ``-1`` on failure.
.. cfunction:: PyObject* PyDict_GetItem(PyObject *p, PyObject *key)
.. c:function:: PyObject* PyDict_GetItem(PyObject *p, PyObject *key)
Return the object from dictionary *p* which has a key *key*. Return *NULL*
if the key *key* is not present, but *without* setting an exception.
.. cfunction:: PyObject* PyDict_GetItemWithError(PyObject *p, PyObject *key)
.. c:function:: PyObject* PyDict_GetItemWithError(PyObject *p, PyObject *key)
Variant of :cfunc:`PyDict_GetItem` that does not suppress
Variant of :c:func:`PyDict_GetItem` that does not suppress
exceptions. Return *NULL* **with** an exception set if an exception
occurred. Return *NULL* **without** an exception set if the key
wasn't present.
.. cfunction:: PyObject* PyDict_GetItemString(PyObject *p, const char *key)
.. c:function:: 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\*`.
This is the same as :c:func:`PyDict_GetItem`, but *key* is specified as a
:c:type:`char\*`, rather than a :c:type:`PyObject\*`.
.. cfunction:: PyObject* PyDict_Items(PyObject *p)
.. c:function:: PyObject* PyDict_Items(PyObject *p)
Return a :ctype:`PyListObject` containing all the items from the
Return a :c:type:`PyListObject` containing all the items from the
dictionary, as in the dictionary method :meth:`dict.items`.
.. cfunction:: PyObject* PyDict_Keys(PyObject *p)
.. c:function:: PyObject* PyDict_Keys(PyObject *p)
Return a :ctype:`PyListObject` containing all the keys from the dictionary,
Return a :c:type:`PyListObject` containing all the keys from the dictionary,
as in the dictionary method :meth:`dict.keys`.
.. cfunction:: PyObject* PyDict_Values(PyObject *p)
.. c:function:: PyObject* PyDict_Values(PyObject *p)
Return a :ctype:`PyListObject` containing all the values from the
Return a :c:type:`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)
.. c:function:: Py_ssize_t PyDict_Size(PyObject *p)
.. index:: builtin: len
......@@ -141,14 +141,14 @@ Dictionary Objects
``len(p)`` on a dictionary.
.. cfunction:: int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)
.. c:function:: int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)
Iterate over all key-value pairs in the dictionary *p*. The
:ctype:`Py_ssize_t` referred to by *ppos* must be initialized to ``0``
:c:type:`Py_ssize_t` referred to by *ppos* must be initialized to ``0``
prior to the first call to this function to start the iteration; the
function returns true for each pair in the dictionary, and false once all
pairs have been reported. The parameters *pkey* and *pvalue* should either
point to :ctype:`PyObject\*` variables that will be filled in with each key
point to :c:type:`PyObject\*` variables that will be filled in with each key
and value, respectively, or may be *NULL*. Any references returned through
them are borrowed. *ppos* should not be altered during iteration. Its
value represents offsets within the internal dictionary structure, and
......@@ -187,23 +187,23 @@ Dictionary Objects
}
.. cfunction:: int PyDict_Merge(PyObject *a, PyObject *b, int override)
.. c:function:: int PyDict_Merge(PyObject *a, PyObject *b, int override)
Iterate over mapping object *b* adding key-value pairs to dictionary *a*.
*b* may be a dictionary, or any object supporting :cfunc:`PyMapping_Keys`
and :cfunc:`PyObject_GetItem`. If *override* is true, existing pairs in *a*
*b* may be a dictionary, or any object supporting :c:func:`PyMapping_Keys`
and :c:func:`PyObject_GetItem`. If *override* is true, existing pairs in *a*
will be replaced if a matching key is found in *b*, otherwise pairs will
only be added if there is not a matching key in *a*. Return ``0`` on
success or ``-1`` if an exception was raised.
.. cfunction:: int PyDict_Update(PyObject *a, PyObject *b)
.. c:function:: 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)
.. c:function:: int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override)
Update or merge into dictionary *a*, from the key-value pairs in *seq2*.
*seq2* must be an iterable object producing iterable objects of length 2,
......
Doc/c-api/exceptions.rst
View file @ 60203b41
This diff is collapsed.
Doc/c-api/file.rst
View file @ 60203b41
......@@ -8,7 +8,7 @@ File Objects
.. index:: object: file
These APIs are a minimal emulation of the Python 2 C API for built-in file
objects, which used to rely on the buffered I/O (:ctype:`FILE\*`) support
objects, which used to rely on the buffered I/O (:c:type:`FILE\*`) support
from the C standard library. In Python 3, files and streams use the new
:mod:`io` module, which defines several layers over the low-level unbuffered
I/O of the operating system. The functions described below are
......@@ -17,7 +17,7 @@ error reporting in the interpreter; third-party code is advised to access
the :mod:`io` APIs instead.
.. cfunction:: PyFile_FromFd(int fd, char *name, char *mode, int buffering, char *encoding, char *errors, char *newline, int closefd)
.. c:function:: PyFile_FromFd(int fd, char *name, char *mode, int buffering, char *encoding, char *errors, char *newline, int closefd)
Create a Python file object from the file descriptor of an already
opened file *fd*. The arguments *name*, *encoding*, *errors* and *newline*
......@@ -36,16 +36,16 @@ the :mod:`io` APIs instead.
Ignore *name* attribute.
.. cfunction:: int PyObject_AsFileDescriptor(PyObject *p)
.. c:function:: int PyObject_AsFileDescriptor(PyObject *p)
Return the file descriptor associated with *p* as an :ctype:`int`. If the
Return the file descriptor associated with *p* as an :c:type:`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)
.. c:function:: PyObject* PyFile_GetLine(PyObject *p, int n)
.. index:: single: EOFError (built-in exception)
......@@ -59,7 +59,7 @@ the :mod:`io` APIs instead.
raised if the end of the file is reached immediately.
.. cfunction:: int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags)
.. c:function:: int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags)
.. index:: single: Py_PRINT_RAW
......@@ -69,7 +69,7 @@ the :mod:`io` APIs instead.
appropriate exception will be set.
.. cfunction:: int PyFile_WriteString(const char *s, PyObject *p)
.. c:function:: int PyFile_WriteString(const char *s, PyObject *p)
Write string *s* to file object *p*. Return ``0`` on success or ``-1`` on
failure; the appropriate exception will be set.
Doc/c-api/float.rst
View file @ 60203b41
......@@ -8,72 +8,72 @@ Floating Point Objects
.. index:: object: floating point
.. ctype:: PyFloatObject
.. c:type:: PyFloatObject
This subtype of :ctype:`PyObject` represents a Python floating point object.
This subtype of :c:type:`PyObject` represents a Python floating point object.
.. cvar:: PyTypeObject PyFloat_Type
.. c:var:: PyTypeObject PyFloat_Type
.. index:: single: FloatType (in modules types)
This instance of :ctype:`PyTypeObject` represents the Python floating point
This instance of :c:type:`PyTypeObject` represents the Python floating point
type. This is the same object as ``float`` and ``types.FloatType``.
.. cfunction:: int PyFloat_Check(PyObject *p)
.. c:function:: int PyFloat_Check(PyObject *p)
Return true if its argument is a :ctype:`PyFloatObject` or a subtype of
:ctype:`PyFloatObject`.
Return true if its argument is a :c:type:`PyFloatObject` or a subtype of
:c:type:`PyFloatObject`.
.. cfunction:: int PyFloat_CheckExact(PyObject *p)
.. c:function:: int PyFloat_CheckExact(PyObject *p)
Return true if its argument is a :ctype:`PyFloatObject`, but not a subtype of
:ctype:`PyFloatObject`.
Return true if its argument is a :c:type:`PyFloatObject`, but not a subtype of
:c:type:`PyFloatObject`.
.. cfunction:: PyObject* PyFloat_FromString(PyObject *str)
.. c:function:: PyObject* PyFloat_FromString(PyObject *str)
Create a :ctype:`PyFloatObject` object based on the string value in *str*, or
Create a :c:type:`PyFloatObject` object based on the string value in *str*, or
*NULL* on failure.
.. cfunction:: PyObject* PyFloat_FromDouble(double v)
.. c:function:: PyObject* PyFloat_FromDouble(double v)
Create a :ctype:`PyFloatObject` object from *v*, or *NULL* on failure.
Create a :c:type:`PyFloatObject` object from *v*, or *NULL* on failure.
.. cfunction:: double PyFloat_AsDouble(PyObject *pyfloat)
.. c:function:: double PyFloat_AsDouble(PyObject *pyfloat)
Return a C :ctype:`double` representation of the contents of *pyfloat*. If
Return a C :c:type:`double` representation of the contents of *pyfloat*. If
*pyfloat* is not a Python floating point object but has a :meth:`__float__`
method, this method will first be called to convert *pyfloat* into a float.
.. cfunction:: double PyFloat_AS_DOUBLE(PyObject *pyfloat)
.. c:function:: double PyFloat_AS_DOUBLE(PyObject *pyfloat)
Return a C :ctype:`double` representation of the contents of *pyfloat*, but
Return a C :c:type:`double` representation of the contents of *pyfloat*, but
without error checking.
.. cfunction:: PyObject* PyFloat_GetInfo(void)
.. c:function:: PyObject* PyFloat_GetInfo(void)
Return a structseq instance which contains information about the
precision, minimum and maximum values of a float. It's a thin wrapper
around the header file :file:`float.h`.
.. cfunction:: double PyFloat_GetMax()
.. c:function:: double PyFloat_GetMax()
Return the maximum representable finite float *DBL_MAX* as C :ctype:`double`.
Return the maximum representable finite float *DBL_MAX* as C :c:type:`double`.
.. cfunction:: double PyFloat_GetMin()
.. c:function:: double PyFloat_GetMin()
Return the minimum normalized positive float *DBL_MIN* as C :ctype:`double`.
Return the minimum normalized positive float *DBL_MIN* as C :c:type:`double`.
.. cfunction:: int PyFloat_ClearFreeList()
.. c:function:: int PyFloat_ClearFreeList()
Clear the float free list. Return the number of items that could not
be freed.
Doc/c-api/function.rst
View file @ 60203b41
......@@ -10,26 +10,26 @@ Function Objects
There are a few functions specific to Python functions.
.. ctype:: PyFunctionObject
.. c:type:: PyFunctionObject
The C structure used for functions.
.. cvar:: PyTypeObject PyFunction_Type
.. c:var:: PyTypeObject PyFunction_Type
.. index:: single: MethodType (in module types)
This is an instance of :ctype:`PyTypeObject` and represents the Python function
This is an instance of :c:type:`PyTypeObject` and represents the Python function
type. It is exposed to Python programmers as ``types.FunctionType``.
.. cfunction:: int PyFunction_Check(PyObject *o)
.. c:function:: int PyFunction_Check(PyObject *o)
Return true if *o* is a function object (has type :cdata:`PyFunction_Type`).
Return true if *o* is a function object (has type :c:data:`PyFunction_Type`).
The parameter must not be *NULL*.
.. cfunction:: PyObject* PyFunction_New(PyObject *code, PyObject *globals)
.. c:function:: PyObject* PyFunction_New(PyObject *code, PyObject *globals)
Return a new function object associated with the code object *code*. *globals*
must be a dictionary with the global variables accessible to the function.
......@@ -38,30 +38,30 @@ There are a few functions specific to Python functions.
object, the argument defaults and closure are set to *NULL*.
.. cfunction:: PyObject* PyFunction_GetCode(PyObject *op)
.. c:function:: PyObject* PyFunction_GetCode(PyObject *op)
Return the code object associated with the function object *op*.
.. cfunction:: PyObject* PyFunction_GetGlobals(PyObject *op)
.. c:function:: PyObject* PyFunction_GetGlobals(PyObject *op)
Return the globals dictionary associated with the function object *op*.
.. cfunction:: PyObject* PyFunction_GetModule(PyObject *op)
.. c:function:: PyObject* PyFunction_GetModule(PyObject *op)
Return the *__module__* attribute of the function object *op*. This is normally
a string containing the module name, but can be set to any other object by
Python code.
.. cfunction:: PyObject* PyFunction_GetDefaults(PyObject *op)
.. c:function:: PyObject* PyFunction_GetDefaults(PyObject *op)
Return the argument default values of the function object *op*. This can be a
tuple of arguments or *NULL*.
.. cfunction:: int PyFunction_SetDefaults(PyObject *op, PyObject *defaults)
.. c:function:: int PyFunction_SetDefaults(PyObject *op, PyObject *defaults)
Set the argument default values for the function object *op*. *defaults* must be
*Py_None* or a tuple.
......@@ -69,13 +69,13 @@ There are a few functions specific to Python functions.
Raises :exc:`SystemError` and returns ``-1`` on failure.
.. cfunction:: PyObject* PyFunction_GetClosure(PyObject *op)
.. c:function:: PyObject* PyFunction_GetClosure(PyObject *op)
Return the closure associated with the function object *op*. This can be *NULL*
or a tuple of cell objects.
.. cfunction:: int PyFunction_SetClosure(PyObject *op, PyObject *closure)
.. c:function:: int PyFunction_SetClosure(PyObject *op, PyObject *closure)
Set the closure associated with the function object *op*. *closure* must be
*Py_None* or a tuple of cell objects.
......@@ -83,13 +83,13 @@ There are a few functions specific to Python functions.
Raises :exc:`SystemError` and returns ``-1`` on failure.
.. cfunction:: PyObject *PyFunction_GetAnnotations(PyObject *op)
.. c:function:: PyObject *PyFunction_GetAnnotations(PyObject *op)
Return the annotations of the function object *op*. This can be a
mutable dictionary or *NULL*.
.. cfunction:: int PyFunction_SetAnnotations(PyObject *op, PyObject *annotations)
.. c:function:: int PyFunction_SetAnnotations(PyObject *op, PyObject *annotations)
Set the annotations for the function object *op*. *annotations*
must be a dictionary or *Py_None*.
......
Doc/c-api/gcsupport.rst
View file @ 60203b41
......@@ -27,32 +27,32 @@ include the :const:`Py_TPFLAGS_HAVE_GC` and provide an implementation of the
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_NewVar`.
#. The memory for the object must be allocated using :c:func:`PyObject_GC_New`
or :c:func:`PyObject_GC_NewVar`.
#. Once all the fields which may contain references to other containers are
initialized, it must call :cfunc:`PyObject_GC_Track`.
initialized, it must call :c:func:`PyObject_GC_Track`.
.. cfunction:: TYPE* PyObject_GC_New(TYPE, PyTypeObject *type)
.. c:function:: TYPE* PyObject_GC_New(TYPE, PyTypeObject *type)
Analogous to :cfunc:`PyObject_New` but for container objects with the
Analogous to :c:func:`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)
.. c:function:: TYPE* PyObject_GC_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)
Analogous to :cfunc:`PyObject_NewVar` but for container objects with the
Analogous to :c:func:`PyObject_NewVar` but for container objects with the
:const:`Py_TPFLAGS_HAVE_GC` flag set.
.. cfunction:: TYPE* PyObject_GC_Resize(TYPE, PyVarObject *op, Py_ssize_t newsize)
.. c:function:: TYPE* PyObject_GC_Resize(TYPE, PyVarObject *op, Py_ssize_t newsize)
Resize an object allocated by :cfunc:`PyObject_NewVar`. Returns the
Resize an object allocated by :c:func:`PyObject_NewVar`. Returns the
resized object or *NULL* on failure.
.. cfunction:: void PyObject_GC_Track(PyObject *op)
.. c:function:: void PyObject_GC_Track(PyObject *op)
Adds the object *op* to the set of container objects tracked by the
collector. The collector can run at unexpected times so objects must be
......@@ -61,44 +61,44 @@ Constructors for container types must conform to two rules:
end of the constructor.
.. cfunction:: void _PyObject_GC_TRACK(PyObject *op)
.. c:function:: void _PyObject_GC_TRACK(PyObject *op)
A macro version of :cfunc:`PyObject_GC_Track`. It should not be used for
A macro version of :c:func:`PyObject_GC_Track`. It should not be used for
extension modules.
Similarly, the deallocator for the object must conform to a similar pair of
rules:
#. Before fields which refer to other containers are invalidated,
:cfunc:`PyObject_GC_UnTrack` must be called.
:c:func:`PyObject_GC_UnTrack` must be called.
#. The object's memory must be deallocated using :cfunc:`PyObject_GC_Del`.
#. The object's memory must be deallocated using :c:func:`PyObject_GC_Del`.
.. cfunction:: void PyObject_GC_Del(void *op)
.. c:function:: void PyObject_GC_Del(void *op)
Releases memory allocated to an object using :cfunc:`PyObject_GC_New` or
:cfunc:`PyObject_GC_NewVar`.
Releases memory allocated to an object using :c:func:`PyObject_GC_New` or
:c:func:`PyObject_GC_NewVar`.
.. cfunction:: void PyObject_GC_UnTrack(void *op)
.. c:function:: 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
collector. Note that :c:func:`PyObject_GC_Track` can be called again on
this object to add it back to the set of tracked objects. The deallocator
(: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)
.. c:function:: void _PyObject_GC_UNTRACK(PyObject *op)
A macro version of :cfunc:`PyObject_GC_UnTrack`. It should not be used for
A macro version of :c:func:`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)
.. c:type:: 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
......@@ -110,7 +110,7 @@ The :attr:`tp_traverse` handler accepts a function parameter of this type:
The :attr:`tp_traverse` handler must have the following type:
.. ctype:: int (*traverseproc)(PyObject *self, visitproc visit, void *arg)
.. c:type:: int (*traverseproc)(PyObject *self, visitproc visit, void *arg)
Traversal function for a container object. Implementations must call the
*visit* function for each object directly contained by *self*, with the
......@@ -119,12 +119,12 @@ The :attr:`tp_traverse` handler must have the following type:
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
To simplify writing :attr:`tp_traverse` handlers, a :c:func:`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)
.. c:function:: 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`
......@@ -138,15 +138,15 @@ must name its arguments exactly *visit* and *arg*:
return 0;
}
The :attr:`tp_clear` handler must be of the :ctype:`inquiry` type, or *NULL*
The :attr:`tp_clear` handler must be of the :c:type:`inquiry` type, or *NULL*
if the object is immutable.
.. ctype:: int (*inquiry)(PyObject *self)
.. c:type:: int (*inquiry)(PyObject *self)
Drop references that may have created reference cycles. Immutable objects
do not have to define this method since they can never directly create
reference cycles. Note that the object must still be valid after calling
this method (don't just call :cfunc:`Py_DECREF` on a reference). The
this method (don't just call :c:func:`Py_DECREF` on a reference). The
collector will call this method if it detects that this object is involved
in a reference cycle.
Doc/c-api/gen.rst
View file @ 60203b41
......@@ -7,31 +7,31 @@ 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`.
than explicitly calling :c:func:`PyGen_New`.
.. ctype:: PyGenObject
.. c:type:: PyGenObject
The C structure used for generator objects.
.. cvar:: PyTypeObject PyGen_Type
.. c:var:: PyTypeObject PyGen_Type
The type object corresponding to generator objects
.. cfunction:: int PyGen_Check(ob)
.. c:function:: int PyGen_Check(ob)
Return true if *ob* is a generator object; *ob* must not be *NULL*.
.. cfunction:: int PyGen_CheckExact(ob)
.. c:function:: 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)
.. c:function:: PyObject* PyGen_New(PyFrameObject *frame)
Create and return a new generator object based on the *frame* object. A
reference to *frame* is stolen by this function. The parameter must not be
......
Doc/c-api/import.rst
View file @ 60203b41
This diff is collapsed.
Doc/c-api/init.rst
View file @ 60203b41
This diff is collapsed.
Doc/c-api/intro.rst
View file @ 60203b41
This diff is collapsed.
Doc/c-api/iter.rst
View file @ 60203b41
......@@ -7,12 +7,12 @@ Iterator Protocol
There are only a couple of functions specifically for working with iterators.
.. cfunction:: int PyIter_Check(PyObject *o)
.. c:function:: int PyIter_Check(PyObject *o)
Return true if the object *o* supports the iterator protocol.
.. cfunction:: PyObject* PyIter_Next(PyObject *o)
.. c:function:: 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
......
Doc/c-api/iterator.rst
View file @ 60203b41
......@@ -12,37 +12,37 @@ the callable for each item in the sequence, and ending the iteration when the
sentinel value is returned.
.. cvar:: PyTypeObject PySeqIter_Type
.. c:var:: PyTypeObject PySeqIter_Type
Type object for iterator objects returned by :cfunc:`PySeqIter_New` and the
Type object for iterator objects returned by :c:func:`PySeqIter_New` and the
one-argument form of the :func:`iter` built-in function for built-in sequence
types.
.. cfunction:: int PySeqIter_Check(op)
.. c:function:: int PySeqIter_Check(op)
Return true if the type of *op* is :cdata:`PySeqIter_Type`.
Return true if the type of *op* is :c:data:`PySeqIter_Type`.
.. cfunction:: PyObject* PySeqIter_New(PyObject *seq)
.. c:function:: PyObject* PySeqIter_New(PyObject *seq)
Return an iterator that works with a general sequence object, *seq*. The
iteration ends when the sequence raises :exc:`IndexError` for the subscripting
operation.
.. cvar:: PyTypeObject PyCallIter_Type
.. c:var:: PyTypeObject PyCallIter_Type
Type object for iterator objects returned by :cfunc:`PyCallIter_New` and the
Type object for iterator objects returned by :c:func:`PyCallIter_New` and the
two-argument form of the :func:`iter` built-in function.
.. cfunction:: int PyCallIter_Check(op)
.. c:function:: int PyCallIter_Check(op)
Return true if the type of *op* is :cdata:`PyCallIter_Type`.
Return true if the type of *op* is :c:data:`PyCallIter_Type`.
.. cfunction:: PyObject* PyCallIter_New(PyObject *callable, PyObject *sentinel)
.. c:function:: PyObject* PyCallIter_New(PyObject *callable, PyObject *sentinel)
Return a new iterator. The first parameter, *callable*, can be any Python
callable object that can be called with no parameters; each call to it should
......
Doc/c-api/list.rst
View file @ 60203b41
......@@ -8,30 +8,30 @@ List Objects
.. index:: object: list
.. ctype:: PyListObject
.. c:type:: PyListObject
This subtype of :ctype:`PyObject` represents a Python list object.
This subtype of :c:type:`PyObject` represents a Python list object.
.. cvar:: PyTypeObject PyList_Type
.. c:var:: PyTypeObject PyList_Type
This instance of :ctype:`PyTypeObject` represents the Python list type. This
This instance of :c:type:`PyTypeObject` represents the Python list type. This
is the same object as ``list`` in the Python layer.
.. cfunction:: int PyList_Check(PyObject *p)
.. c:function:: int PyList_Check(PyObject *p)
Return true if *p* is a list object or an instance of a subtype of the list
type.
.. cfunction:: int PyList_CheckExact(PyObject *p)
.. c:function:: int PyList_CheckExact(PyObject *p)
Return true if *p* is a list object, but not an instance of a subtype of
the list type.
.. cfunction:: PyObject* PyList_New(Py_ssize_t len)
.. c:function:: PyObject* PyList_New(Py_ssize_t len)
Return a new list of length *len* on success, or *NULL* on failure.
......@@ -39,11 +39,11 @@ List Objects
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`.
:c:func:`PySequence_SetItem` or expose the object to Python code before
setting all items to a real object with :c:func:`PyList_SetItem`.
.. cfunction:: Py_ssize_t PyList_Size(PyObject *list)
.. c:function:: Py_ssize_t PyList_Size(PyObject *list)
.. index:: builtin: len
......@@ -51,12 +51,12 @@ List Objects
``len(list)`` on a list object.
.. cfunction:: Py_ssize_t PyList_GET_SIZE(PyObject *list)
.. c:function:: Py_ssize_t PyList_GET_SIZE(PyObject *list)
Macro form of :cfunc:`PyList_Size` without error checking.
Macro form of :c:func:`PyList_Size` without error checking.
.. cfunction:: PyObject* PyList_GetItem(PyObject *list, Py_ssize_t index)
.. c:function:: 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
......@@ -64,12 +64,12 @@ List Objects
:exc:`IndexError` exception.
.. cfunction:: PyObject* PyList_GET_ITEM(PyObject *list, Py_ssize_t i)
.. c:function:: PyObject* PyList_GET_ITEM(PyObject *list, Py_ssize_t i)
Macro form of :cfunc:`PyList_GetItem` without error checking.
Macro form of :c:func:`PyList_GetItem` without error checking.
.. cfunction:: int PyList_SetItem(PyObject *list, Py_ssize_t index, PyObject *item)
.. c:function:: int PyList_SetItem(PyObject *list, Py_ssize_t index, PyObject *item)
Set the item at index *index* in list to *item*. Return ``0`` on success
or ``-1`` on failure.
......@@ -80,34 +80,34 @@ List Objects
an item already in the list at the affected position.
.. cfunction:: void PyList_SET_ITEM(PyObject *list, Py_ssize_t i, PyObject *o)
.. c:function:: void PyList_SET_ITEM(PyObject *list, Py_ssize_t i, PyObject *o)
Macro form of :cfunc:`PyList_SetItem` without error checking. This is
Macro form of :c:func:`PyList_SetItem` without error checking. This is
normally only used to fill in new lists where there is no previous content.
.. note::
This macro "steals" a reference to *item*, and, unlike
:cfunc:`PyList_SetItem`, does *not* discard a reference to any item that
:c:func:`PyList_SetItem`, does *not* discard a reference to any item that
is being replaced; any reference in *list* at position *i* will be
leaked.
.. cfunction:: int PyList_Insert(PyObject *list, Py_ssize_t index, PyObject *item)
.. c:function:: int PyList_Insert(PyObject *list, Py_ssize_t index, PyObject *item)
Insert the item *item* into list *list* in front of index *index*. Return
``0`` if successful; return ``-1`` and set an exception if unsuccessful.
Analogous to ``list.insert(index, item)``.
.. cfunction:: int PyList_Append(PyObject *list, PyObject *item)
.. c:function:: int PyList_Append(PyObject *list, PyObject *item)
Append the object *item* at the end of list *list*. Return ``0`` if
successful; return ``-1`` and set an exception if unsuccessful. Analogous
to ``list.append(item)``.
.. cfunction:: PyObject* PyList_GetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high)
.. c:function:: PyObject* PyList_GetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high)
Return a list of the objects in *list* containing the objects *between* *low*
and *high*. Return *NULL* and set an exception if unsuccessful. Analogous
......@@ -115,7 +115,7 @@ List Objects
supported.
.. cfunction:: int PyList_SetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist)
.. c:function:: int PyList_SetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist)
Set the slice of *list* between *low* and *high* to the contents of
*itemlist*. Analogous to ``list[low:high] = itemlist``. The *itemlist* may
......@@ -124,19 +124,19 @@ List Objects
slicing from Python, are not supported.
.. cfunction:: int PyList_Sort(PyObject *list)
.. c:function:: int PyList_Sort(PyObject *list)
Sort the items of *list* in place. Return ``0`` on success, ``-1`` on
failure. This is equivalent to ``list.sort()``.
.. cfunction:: int PyList_Reverse(PyObject *list)
.. c:function:: int PyList_Reverse(PyObject *list)
Reverse the items of *list* in place. Return ``0`` on success, ``-1`` on
failure. This is the equivalent of ``list.reverse()``.
.. cfunction:: PyObject* PyList_AsTuple(PyObject *list)
.. c:function:: PyObject* PyList_AsTuple(PyObject *list)
.. index:: builtin: tuple
......
Doc/c-api/long.rst
View file @ 60203b41
This diff is collapsed.
Doc/c-api/mapping.rst
View file @ 60203b41
This diff is collapsed.
Doc/c-api/marshal.rst
View file @ 60203b41
......@@ -19,20 +19,20 @@ unmarshalling. Version 2 uses a binary format for floating point numbers.
*Py_MARSHAL_VERSION* indicates the current file format (currently 2).
.. cfunction:: void PyMarshal_WriteLongToFile(long value, FILE *file, int version)
.. c:function:: void PyMarshal_WriteLongToFile(long value, FILE *file, int version)
Marshal a :ctype:`long` integer, *value*, to *file*. This will only write
Marshal a :c:type:`long` integer, *value*, to *file*. This will only write
the least-significant 32 bits of *value*; regardless of the size of the
native :ctype:`long` type. *version* indicates the file format.
native :c:type:`long` type. *version* indicates the file format.
.. cfunction:: void PyMarshal_WriteObjectToFile(PyObject *value, FILE *file, int version)
.. c:function:: 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)
.. c:function:: PyObject* PyMarshal_WriteObjectToString(PyObject *value, int version)
Return a string object containing the marshalled representation of *value*.
*version* indicates the file format.
......@@ -47,31 +47,31 @@ 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)
.. c:function:: long PyMarshal_ReadLongFromFile(FILE *file)
Return a C :ctype:`long` from the data stream in a :ctype:`FILE\*` opened
Return a C :c:type:`long` from the data stream in a :c:type:`FILE\*` opened
for reading. Only a 32-bit value can be read in using this function,
regardless of the native size of :ctype:`long`.
regardless of the native size of :c:type:`long`.
.. cfunction:: int PyMarshal_ReadShortFromFile(FILE *file)
.. c:function:: int PyMarshal_ReadShortFromFile(FILE *file)
Return a C :ctype:`short` from the data stream in a :ctype:`FILE\*` opened
Return a C :c:type:`short` from the data stream in a :c:type:`FILE\*` opened
for reading. Only a 16-bit value can be read in using this function,
regardless of the native size of :ctype:`short`.
regardless of the native size of :c:type:`short`.
.. cfunction:: PyObject* PyMarshal_ReadObjectFromFile(FILE *file)
.. c:function:: PyObject* PyMarshal_ReadObjectFromFile(FILE *file)
Return a Python object from the data stream in a :ctype:`FILE\*` opened for
Return a Python object from the data stream in a :c:type:`FILE\*` opened for
reading. On error, sets the appropriate exception (:exc:`EOFError` or
:exc:`TypeError`) and returns *NULL*.
.. cfunction:: PyObject* PyMarshal_ReadLastObjectFromFile(FILE *file)
.. c:function:: 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
Return a Python object from the data stream in a :c:type:`FILE\*` opened for
reading. Unlike :c:func:`PyMarshal_ReadObjectFromFile`, this function
assumes that no further objects will be read from the file, allowing it to
aggressively load file data into memory so that the de-serialization can
operate from data in memory rather than reading a byte at a time from the
......@@ -80,7 +80,7 @@ written using these routines?
(:exc:`EOFError` or :exc:`TypeError`) and returns *NULL*.
.. cfunction:: PyObject* PyMarshal_ReadObjectFromString(char *string, Py_ssize_t len)
.. c:function:: PyObject* PyMarshal_ReadObjectFromString(char *string, Py_ssize_t len)
Return a Python object from the data stream in a character buffer
containing *len* bytes pointed to by *string*. On error, sets the
......
Doc/c-api/memory.rst
View file @ 60203b41
This diff is collapsed.
Doc/c-api/memoryview.rst
View file @ 60203b41
This diff is collapsed.
Doc/c-api/method.rst
View file @ 60203b41
This diff is collapsed.
Doc/c-api/module.rst
View file @ 60203b41
This diff is collapsed.
Doc/c-api/none.rst
View file @ 60203b41
This diff is collapsed.
Doc/c-api/number.rst
View file @ 60203b41
This diff is collapsed.
Doc/c-api/objbuffer.rst
View file @ 60203b41
This diff is collapsed.
Doc/c-api/object.rst
View file @ 60203b41
This diff is collapsed.
Doc/c-api/refcounting.rst
View file @ 60203b41
This diff is collapsed.
Doc/c-api/reflection.rst
View file @ 60203b41
This diff is collapsed.
Doc/c-api/sequence.rst
View file @ 60203b41
This diff is collapsed.
Doc/c-api/set.rst
View file @ 60203b41
This diff is collapsed.
Doc/c-api/slice.rst
View file @ 60203b41
This diff is collapsed.
Doc/c-api/structures.rst
View file @ 60203b41
This diff is collapsed.
Doc/c-api/sys.rst
View file @ 60203b41
This diff is collapsed.
Doc/c-api/tuple.rst
View file @ 60203b41
This diff is collapsed.
Doc/c-api/type.rst
View file @ 60203b41
This diff is collapsed.
Doc/c-api/typeobj.rst
View file @ 60203b41
This diff is collapsed.
Doc/c-api/unicode.rst
View file @ 60203b41
This diff is collapsed.
Doc/c-api/veryhigh.rst
View file @ 60203b41
This diff is collapsed.
Doc/c-api/weakref.rst
View file @ 60203b41
This diff is collapsed.
Doc/distutils/builtdist.rst
View file @ 60203b41
This diff is collapsed.
Doc/documenting/markup.rst
View file @ 60203b41
This diff is collapsed.
Doc/extending/embedding.rst
View file @ 60203b41
This diff is collapsed.
Doc/extending/extending.rst
View file @ 60203b41
This diff is collapsed.
Doc/extending/newtypes.rst
View file @ 60203b41
This diff is collapsed.
Doc/extending/windows.rst
View file @ 60203b41
This diff is collapsed.
Doc/faq/extending.rst
View file @ 60203b41
This diff is collapsed.
Doc/faq/gui.rst
View file @ 60203b41
This diff is collapsed.
Doc/faq/programming.rst
View file @ 60203b41
This diff is collapsed.
Doc/faq/windows.rst
View file @ 60203b41
This diff is collapsed.
Doc/howto/cporting.rst
View file @ 60203b41
This diff is collapsed.
Doc/howto/descriptor.rst
View file @ 60203b41
This diff is collapsed.
Doc/library/array.rst
View file @ 60203b41
This diff is collapsed.
Doc/library/asynchat.rst
View file @ 60203b41
This diff is collapsed.
Doc/library/asyncore.rst
View file @ 60203b41
This diff is collapsed.
Doc/library/codecs.rst
View file @ 60203b41
This diff is collapsed.
Doc/library/ctypes.rst
View file @ 60203b41
This diff is collapsed.
Doc/library/datetime.rst
View file @ 60203b41
This diff is collapsed.
Doc/library/exceptions.rst
View file @ 60203b41
This diff is collapsed.
Doc/library/fcntl.rst
View file @ 60203b41
This diff is collapsed.
Doc/library/getopt.rst
View file @ 60203b41
This diff is collapsed.
Doc/library/inspect.rst
View file @ 60203b41
This diff is collapsed.
Doc/library/locale.rst
View file @ 60203b41
This diff is collapsed.
Doc/library/mailbox.rst
View file @ 60203b41
This diff is collapsed.
Doc/library/msilib.rst
View file @ 60203b41
This diff is collapsed.
Doc/library/msvcrt.rst
View file @ 60203b41
This diff is collapsed.
Doc/library/multiprocessing.rst
View file @ 60203b41
This diff is collapsed.
Doc/library/os.rst
View file @ 60203b41
This diff is collapsed.
Doc/library/ossaudiodev.rst
View file @ 60203b41
This diff is collapsed.
Doc/library/platform.rst
View file @ 60203b41
This diff is collapsed.
Doc/library/posix.rst
View file @ 60203b41
This diff is collapsed.
Doc/library/re.rst
View file @ 60203b41
This diff is collapsed.
Doc/library/select.rst
View file @ 60203b41
This diff is collapsed.
Doc/library/signal.rst
View file @ 60203b41
This diff is collapsed.
Doc/library/socket.rst
View file @ 60203b41
This diff is collapsed.
Doc/library/stat.rst
View file @ 60203b41
This diff is collapsed.
Doc/library/stdtypes.rst
View file @ 60203b41
This diff is collapsed.
Doc/library/struct.rst
View file @ 60203b41
This diff is collapsed.
Doc/library/subprocess.rst
View file @ 60203b41
This diff is collapsed.
Doc/library/sys.rst
View file @ 60203b41
This diff is collapsed.
Doc/library/time.rst
View file @ 60203b41
This diff is collapsed.
Doc/library/warnings.rst
View file @ 60203b41
This diff is collapsed.
Doc/library/winsound.rst
View file @ 60203b41
This diff is collapsed.
Doc/library/zlib.rst
View file @ 60203b41
This diff is collapsed.
Doc/reference/expressions.rst
View file @ 60203b41
This diff is collapsed.
Doc/tutorial/inputoutput.rst
View file @ 60203b41
This diff is collapsed.
Doc/whatsnew/2.2.rst
View file @ 60203b41
This diff is collapsed.
Doc/whatsnew/2.3.rst
View file @ 60203b41
This diff is collapsed.
Doc/whatsnew/2.4.rst
View file @ 60203b41
This diff is collapsed.
Doc/whatsnew/2.5.rst
View file @ 60203b41
This diff is collapsed.
Doc/whatsnew/2.6.rst
View file @ 60203b41
This diff is collapsed.
Doc/whatsnew/2.7.rst
View file @ 60203b41
This diff is collapsed.
Doc/whatsnew/3.0.rst
View file @ 60203b41
This diff is collapsed.
Doc/whatsnew/3.1.rst
View file @ 60203b41
This diff is collapsed.
Doc/whatsnew/3.2.rst
View file @ 60203b41
This diff is collapsed.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7