Skip to content

Commit f684272

Browse files
birkenfeldbirkenfeld
committed
Split the monstrous C API manual files in smaller parts.
1 parent 8b506e7 commit f684272

41 files changed

Lines changed: 5132 additions & 5082 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎Doc/c-api/abstract.rst‎

Lines changed: 8 additions & 1007 deletions
Large diffs are not rendered by default.

‎Doc/c-api/allocation.rst‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
.. highlightlang:: c
2+
3+
.. _allocating-objects:
4+
5+
Allocating Objects on the Heap
6+
==============================
7+
8+
9+
.. cfunction:: PyObject* _PyObject_New(PyTypeObject *type)
10+
11+
12+
.. cfunction:: PyVarObject* _PyObject_NewVar(PyTypeObject *type, Py_ssize_t size)
13+
14+
15+
.. cfunction:: void _PyObject_Del(PyObject *op)
16+
17+
18+
.. cfunction:: PyObject* PyObject_Init(PyObject *op, PyTypeObject *type)
19+
20+
Initialize a newly-allocated object *op* with its type and initial reference.
21+
Returns the initialized object. If *type* indicates that the object
22+
participates in the cyclic garbage detector, it is added to the detector's set
23+
of observed objects. Other fields of the object are not affected.
24+
25+
26+
.. cfunction:: PyVarObject* PyObject_InitVar(PyVarObject *op, PyTypeObject *type, Py_ssize_t size)
27+
28+
This does everything :cfunc:`PyObject_Init` does, and also initializes the
29+
length information for a variable-size object.
30+
31+
32+
.. cfunction:: TYPE* PyObject_New(TYPE, PyTypeObject *type)
33+
34+
Allocate a new Python object using the C structure type *TYPE* and the Python
35+
type object *type*. Fields not defined by the Python object header are not
36+
initialized; the object's reference count will be one. The size of the memory
37+
allocation is determined from the :attr:`tp_basicsize` field of the type object.
38+
39+
40+
.. cfunction:: TYPE* PyObject_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)
41+
42+
Allocate a new Python object using the C structure type *TYPE* and the Python
43+
type object *type*. Fields not defined by the Python object header are not
44+
initialized. The allocated memory allows for the *TYPE* structure plus *size*
45+
fields of the size given by the :attr:`tp_itemsize` field of *type*. This is
46+
useful for implementing objects like tuples, which are able to determine their
47+
size at construction time. Embedding the array of fields into the same
48+
allocation decreases the number of allocations, improving the memory management
49+
efficiency.
50+
51+
52+
.. cfunction:: void PyObject_Del(PyObject *op)
53+
54+
Releases memory allocated to an object using :cfunc:`PyObject_New` or
55+
:cfunc:`PyObject_NewVar`. This is normally called from the :attr:`tp_dealloc`
56+
handler specified in the object's type. The fields of the object should not be
57+
accessed after this call as the memory is no longer a valid Python object.
58+
59+
60+
.. cfunction:: PyObject* Py_InitModule(char *name, PyMethodDef *methods)
61+
62+
Create a new module object based on a name and table of functions, returning the
63+
new module object.
64+
65+
.. versionchanged:: 2.3
66+
Older versions of Python did not support *NULL* as the value for the *methods*
67+
argument.
68+
69+
70+
.. cfunction:: PyObject* Py_InitModule3(char *name, PyMethodDef *methods, char *doc)
71+
72+
Create a new module object based on a name and table of functions, returning the
73+
new module object. If *doc* is non-*NULL*, it will be used to define the
74+
docstring for the module.
75+
76+
.. versionchanged:: 2.3
77+
Older versions of Python did not support *NULL* as the value for the *methods*
78+
argument.
79+
80+
81+
.. cfunction:: PyObject* Py_InitModule4(char *name, PyMethodDef *methods, char *doc, PyObject *self, int apiver)
82+
83+
Create a new module object based on a name and table of functions, returning the
84+
new module object. If *doc* is non-*NULL*, it will be used to define the
85+
docstring for the module. If *self* is non-*NULL*, it will passed to the
86+
functions of the module as their (otherwise *NULL*) first parameter. (This was
87+
added as an experimental feature, and there are no known uses in the current
88+
version of Python.) For *apiver*, the only value which should be passed is
89+
defined by the constant :const:`PYTHON_API_VERSION`.
90+
91+
.. note::
92+
93+
Most uses of this function should probably be using the :cfunc:`Py_InitModule3`
94+
instead; only use this if you are sure you need it.
95+
96+
.. versionchanged:: 2.3
97+
Older versions of Python did not support *NULL* as the value for the *methods*
98+
argument.
99+
100+
101+
.. cvar:: PyObject _Py_NoneStruct
102+
103+
Object which is visible in Python as ``None``. This should only be accessed
104+
using the ``Py_None`` macro, which evaluates to a pointer to this object.

‎Doc/c-api/bool.rst‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
.. highlightlang:: c
2+
3+
.. _boolobjects:
4+
5+
Boolean Objects
6+
---------------
7+
8+
Booleans in Python are implemented as a subclass of integers. There are only
9+
two booleans, :const:`Py_False` and :const:`Py_True`. As such, the normal
10+
creation and deletion functions don't apply to booleans. The following macros
11+
are available, however.
12+
13+
14+
.. cfunction:: int PyBool_Check(PyObject *o)
15+
16+
Return true if *o* is of type :cdata:`PyBool_Type`.
17+
18+
.. versionadded:: 2.3
19+
20+
21+
.. cvar:: PyObject* Py_False
22+
23+
The Python ``False`` object. This object has no methods. It needs to be
24+
treated just like any other object with respect to reference counts.
25+
26+
27+
.. cvar:: PyObject* Py_True
28+
29+
The Python ``True`` object. This object has no methods. It needs to be treated
30+
just like any other object with respect to reference counts.
31+
32+
33+
.. cmacro:: Py_RETURN_FALSE
34+
35+
Return :const:`Py_False` from a function, properly incrementing its reference
36+
count.
37+
38+
.. versionadded:: 2.4
39+
40+
41+
.. cmacro:: Py_RETURN_TRUE
42+
43+
Return :const:`Py_True` from a function, properly incrementing its reference
44+
count.
45+
46+
.. versionadded:: 2.4
47+
48+
49+
.. cfunction:: PyObject* PyBool_FromLong(long v)
50+
51+
Return a new reference to :const:`Py_True` or :const:`Py_False` depending on the
52+
truth value of *v*.
53+
54+
.. versionadded:: 2.3

‎Doc/c-api/buffer.rst‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
.. highlightlang:: c
2+
3+
.. _bufferobjects:
4+
5+
Buffer Objects
6+
--------------
7+
8+
.. sectionauthor:: Greg Stein <gstein@lyra.org>
9+
10+
11+
.. index::
12+
object: buffer
13+
single: buffer interface
14+
15+
Python objects implemented in C can export a group of functions called the
16+
"buffer interface." These functions can be used by an object to expose its data
17+
in a raw, byte-oriented format. Clients of the object can use the buffer
18+
interface to access the object data directly, without needing to copy it first.
19+
20+
Two examples of objects that support the buffer interface are strings and
21+
arrays. The string object exposes the character contents in the buffer
22+
interface's byte-oriented form. An array can also expose its contents, but it
23+
should be noted that array elements may be multi-byte values.
24+
25+
An example user of the buffer interface is the file object's :meth:`write`
26+
method. Any object that can export a series of bytes through the buffer
27+
interface can be written to a file. There are a number of format codes to
28+
:cfunc:`PyArg_ParseTuple` that operate against an object's buffer interface,
29+
returning data from the target object.
30+
31+
.. index:: single: PyBufferProcs
32+
33+
More information on the buffer interface is provided in the section
34+
:ref:`buffer-structs`, under the description for :ctype:`PyBufferProcs`.
35+
36+
A "buffer object" is defined in the :file:`bufferobject.h` header (included by
37+
:file:`Python.h`). These objects look very similar to string objects at the
38+
Python programming level: they support slicing, indexing, concatenation, and
39+
some other standard string operations. However, their data can come from one of
40+
two sources: from a block of memory, or from another object which exports the
41+
buffer interface.
42+
43+
Buffer objects are useful as a way to expose the data from another object's
44+
buffer interface to the Python programmer. They can also be used as a zero-copy
45+
slicing mechanism. Using their ability to reference a block of memory, it is
46+
possible to expose any data to the Python programmer quite easily. The memory
47+
could be a large, constant array in a C extension, it could be a raw block of
48+
memory for manipulation before passing to an operating system library, or it
49+
could be used to pass around structured data in its native, in-memory format.
50+
51+
52+
.. ctype:: PyBufferObject
53+
54+
This subtype of :ctype:`PyObject` represents a buffer object.
55+
56+
57+
.. cvar:: PyTypeObject PyBuffer_Type
58+
59+
.. index:: single: BufferType (in module types)
60+
61+
The instance of :ctype:`PyTypeObject` which represents the Python buffer type;
62+
it is the same object as ``buffer`` and ``types.BufferType`` in the Python
63+
layer. .
64+
65+
66+
.. cvar:: int Py_END_OF_BUFFER
67+
68+
This constant may be passed as the *size* parameter to
69+
:cfunc:`PyBuffer_FromObject` or :cfunc:`PyBuffer_FromReadWriteObject`. It
70+
indicates that the new :ctype:`PyBufferObject` should refer to *base* object
71+
from the specified *offset* to the end of its exported buffer. Using this
72+
enables the caller to avoid querying the *base* object for its length.
73+
74+
75+
.. cfunction:: int PyBuffer_Check(PyObject *p)
76+
77+
Return true if the argument has type :cdata:`PyBuffer_Type`.
78+
79+
80+
.. cfunction:: PyObject* PyBuffer_FromObject(PyObject *base, Py_ssize_t offset, Py_ssize_t size)
81+
82+
Return a new read-only buffer object. This raises :exc:`TypeError` if *base*
83+
doesn't support the read-only buffer protocol or doesn't provide exactly one
84+
buffer segment, or it raises :exc:`ValueError` if *offset* is less than zero.
85+
The buffer will hold a reference to the *base* object, and the buffer's contents
86+
will refer to the *base* object's buffer interface, starting as position
87+
*offset* and extending for *size* bytes. If *size* is :const:`Py_END_OF_BUFFER`,
88+
then the new buffer's contents extend to the length of the *base* object's
89+
exported buffer data.
90+
91+
92+
.. cfunction:: PyObject* PyBuffer_FromReadWriteObject(PyObject *base, Py_ssize_t offset, Py_ssize_t size)
93+
94+
Return a new writable buffer object. Parameters and exceptions are similar to
95+
those for :cfunc:`PyBuffer_FromObject`. If the *base* object does not export
96+
the writeable buffer protocol, then :exc:`TypeError` is raised.
97+
98+
99+
.. cfunction:: PyObject* PyBuffer_FromMemory(void *ptr, Py_ssize_t size)
100+
101+
Return a new read-only buffer object that reads from a specified location in
102+
memory, with a specified size. The caller is responsible for ensuring that the
103+
memory buffer, passed in as *ptr*, is not deallocated while the returned buffer
104+
object exists. Raises :exc:`ValueError` if *size* is less than zero. Note that
105+
:const:`Py_END_OF_BUFFER` may *not* be passed for the *size* parameter;
106+
:exc:`ValueError` will be raised in that case.
107+
108+
109+
.. cfunction:: PyObject* PyBuffer_FromReadWriteMemory(void *ptr, Py_ssize_t size)
110+
111+
Similar to :cfunc:`PyBuffer_FromMemory`, but the returned buffer is writable.
112+
113+
114+
.. cfunction:: PyObject* PyBuffer_New(Py_ssize_t size)
115+
116+
Return a new writable buffer object that maintains its own memory buffer of
117+
*size* bytes. :exc:`ValueError` is returned if *size* is not zero or positive.
118+
Note that the memory buffer (as returned by :cfunc:`PyObject_AsWriteBuffer`) is
119+
not specifically aligned.

‎Doc/c-api/cell.rst‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
.. highlightlang:: c
2+
3+
.. _cell-objects:
4+
5+
Cell Objects
6+
------------
7+
8+
"Cell" objects are used to implement variables referenced by multiple scopes.
9+
For each such variable, a cell object is created to store the value; the local
10+
variables of each stack frame that references the value contains a reference to
11+
the cells from outer scopes which also use that variable. When the value is
12+
accessed, the value contained in the cell is used instead of the cell object
13+
itself. This de-referencing of the cell object requires support from the
14+
generated byte-code; these are not automatically de-referenced when accessed.
15+
Cell objects are not likely to be useful elsewhere.
16+
17+
18+
.. ctype:: PyCellObject
19+
20+
The C structure used for cell objects.
21+
22+
23+
.. cvar:: PyTypeObject PyCell_Type
24+
25+
The type object corresponding to cell objects.
26+
27+
28+
.. cfunction:: int PyCell_Check(ob)
29+
30+
Return true if *ob* is a cell object; *ob* must not be *NULL*.
31+
32+
33+
.. cfunction:: PyObject* PyCell_New(PyObject *ob)
34+
35+
Create and return a new cell object containing the value *ob*. The parameter may
36+
be *NULL*.
37+
38+
39+
.. cfunction:: PyObject* PyCell_Get(PyObject *cell)
40+
41+
Return the contents of the cell *cell*.
42+
43+
44+
.. cfunction:: PyObject* PyCell_GET(PyObject *cell)
45+
46+
Return the contents of the cell *cell*, but without checking that *cell* is
47+
non-*NULL* and a cell object.
48+
49+
50+
.. cfunction:: int PyCell_Set(PyObject *cell, PyObject *value)
51+
52+
Set the contents of the cell object *cell* to *value*. This releases the
53+
reference to any current content of the cell. *value* may be *NULL*. *cell*
54+
must be non-*NULL*; if it is not a cell object, ``-1`` will be returned. On
55+
success, ``0`` will be returned.
56+
57+
58+
.. cfunction:: void PyCell_SET(PyObject *cell, PyObject *value)
59+
60+
Sets the value of the cell object *cell* to *value*. No reference counts are
61+
adjusted, and no checks are made for safety; *cell* must be non-*NULL* and must
62+
be a cell object.

0 commit comments

Comments
 (0)