mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-08-03 16:39:00 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

Merged revisions 71898-71900,71910,71914-71919 via svnmerge from

Browse source 
svn+ssh://pythondev@svn.python.org/python/trunk

........
  r71898 | jeroen.ruigrok | 2009-04-25 16:24:30 +0200 (za, 25 apr 2009) | 2 lines

  Reformat prior to editing.
........
  r71899 | jeroen.ruigrok | 2009-04-25 16:27:00 +0200 (za, 25 apr 2009) | 3 lines

  The type for ppos has been Py_ssize_t since 2.5, reflect this in the
  documentation.
........
  r71900 | jeroen.ruigrok | 2009-04-25 16:28:02 +0200 (za, 25 apr 2009) | 2 lines

  Reformat paragraph.
........
  r71910 | jeroen.ruigrok | 2009-04-25 19:59:03 +0200 (za, 25 apr 2009) | 4 lines

  Issue #4129: Belatedly document which C API functions had their argument(s) or
  return type changed from int or int * to Py_ssize_t or Py_ssize_t * as this
  might cause problems on 64-bit platforms.
........
  r71914 | jeroen.ruigrok | 2009-04-25 20:31:20 +0200 (za, 25 apr 2009) | 2 lines

  Reformat prior to editing.
........
  r71915 | jeroen.ruigrok | 2009-04-25 20:46:03 +0200 (za, 25 apr 2009) | 2 lines

  Issue #4129: Document more int -> Py_ssize_t changes.
........
  r71916 | jeroen.ruigrok | 2009-04-25 20:53:48 +0200 (za, 25 apr 2009) | 2 lines

  Reformat prior to editing.
........
  r71917 | jeroen.ruigrok | 2009-04-25 20:57:32 +0200 (za, 25 apr 2009) | 2 lines

  Reference to an int type, whereas it's a Py_ssize_t as the synopsis states.
........
  r71918 | jeroen.ruigrok | 2009-04-25 21:04:15 +0200 (za, 25 apr 2009) | 2 lines

  Since I edited this file, reformat for future edits.
........
  r71919 | jeroen.ruigrok | 2009-04-25 21:10:52 +0200 (za, 25 apr 2009) | 2 lines

  Reformat prior to editing.
........
This commit is contained in:
Jeroen Ruigrok van der Werven 2009-04-26 21:06:15 +00:00
parent 939c178379
commit bd87552a34
14 changed files with 312 additions and 156 deletions
Download patch file Download diff file Expand all files Collapse all files

45
Doc/c-api/allocation.rst
View file

@ -11,13 +11,18 @@ Allocating Objects on the Heap
.. cfunction:: PyVarObject* _PyObject_NewVar(PyTypeObject *type, Py_ssize_t size)
.. versionchanged:: 2.5
This function used an :ctype:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: PyObject* PyObject_Init(PyObject *op, PyTypeObject *type)
Initialize a newly-allocated object *op* with its type and initial reference.
Returns the initialized object. If *type* indicates that the object
participates in the cyclic garbage detector, it is added to the detector's set
of observed objects. Other fields of the object are not affected.
Initialize a newly-allocated object *op* with its type and initial
reference. Returns the initialized object. If *type* indicates that the
object participates in the cyclic garbage detector, it is added to the
detector's set of observed objects. Other fields of the object are not
affected.
.. cfunction:: PyVarObject* PyObject_InitVar(PyVarObject *op, PyTypeObject *type, Py_ssize_t size)
@ -28,30 +33,32 @@ Allocating Objects on the Heap
.. cfunction:: TYPE* PyObject_New(TYPE, PyTypeObject *type)
Allocate a new Python object using the C structure type *TYPE* and the Python
type object *type*. Fields not defined by the Python object header are not
initialized; the object's reference count will be one. The size of the memory
allocation is determined from the :attr:`tp_basicsize` field of the type object.
Allocate a new Python object using the C structure type *TYPE* and the
Python type object *type*. Fields not defined by the Python object header
are not initialized; the object's reference count will be one. The size of
the memory allocation is determined from the :attr:`tp_basicsize` field of
the type object.
.. cfunction:: TYPE* PyObject_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)
Allocate a new Python object using the C structure type *TYPE* and the Python
type object *type*. Fields not defined by the Python object header are not
initialized. The allocated memory allows for the *TYPE* structure plus *size*
fields of the size given by the :attr:`tp_itemsize` field of *type*. This is
useful for implementing objects like tuples, which are able to determine their
size at construction time. Embedding the array of fields into the same
allocation decreases the number of allocations, improving the memory management
efficiency.
Allocate a new Python object using the C structure type *TYPE* and the
Python type object *type*. Fields not defined by the Python object header
are not initialized. The allocated memory allows for the *TYPE* structure
plus *size* fields of the size given by the :attr:`tp_itemsize` field of
*type*. This is useful for implementing objects like tuples, which are
able to determine their size at construction time. Embedding the array of
fields into the same allocation decreases the number of allocations,
improving the memory management efficiency.
.. cfunction:: void PyObject_Del(PyObject *op)
Releases memory allocated to an object using :cfunc:`PyObject_New` or
:cfunc:`PyObject_NewVar`. This is normally called from the :attr:`tp_dealloc`
handler specified in the object's type. The fields of the object should not be
accessed after this call as the memory is no longer a valid Python object.
:cfunc:`PyObject_NewVar`. This is normally called from the
:attr:`tp_dealloc` handler specified in the object's type. The fields of
the object should not be accessed after this call as the memory is no
longer a valid Python object.
.. cvar:: PyObject _Py_NoneStruct

12
Doc/c-api/arg.rst
View file

@ -278,10 +278,10 @@ variable(s) whose address should be passed.
``w#`` (read-write character buffer) [char \*, int]
Like ``s#``, but accepts any object which implements the read-write buffer
interface. The :ctype:`char \*` variable is set to point to the first byte of
the buffer, and the :ctype:`int` is set to the length of the buffer. Only
single-segment buffer objects are accepted; :exc:`TypeError` is raised for all
others.
interface. The :ctype:`char \*` variable is set to point to the first byte
of the buffer, and the :ctype:`int` is set to the length of the buffer.
Only single-segment buffer objects are accepted; :exc:`TypeError` is raised
for all others.
``(items)`` (tuple) [*matching-items*]
The object must be a Python sequence whose length is the number of format units
@ -406,6 +406,10 @@ and the following format units are left untouched.
PyArg_ParseTuple(args, "O|O:ref", &object, &callback)
.. versionchanged:: 2.5
This function used an :ctype:`int` type for *min* and *max*. This might
require changes in your code for properly supporting 64-bit systems.
.. cfunction:: PyObject* Py_BuildValue(const char *format, ...)

60
Doc/c-api/buffer.rst
View file

@ -15,8 +15,8 @@ Buffer Objects
Python objects implemented in C can export a "buffer interface." These
functions can be used by an object to expose its data in a raw, byte-oriented
format. Clients of the object can use the buffer interface to access the object
data directly, without needing to copy it first.
format. Clients of the object can use the buffer interface to access the
object data directly, without needing to copy it first.
Two examples of objects that support the buffer interface are bytes and
arrays. The bytes object exposes the character contents in the buffer
@ -61,9 +61,9 @@ could be used to pass around structured data in its native, in-memory format.
.. cmember:: const char *format
:noindex:
A *NULL* terminated string in :mod:`struct` module style syntax giving the
contents of the elements available through the buffer. If this is *NULL*,
``"B"`` (unsigned bytes) is assumed.
A *NULL* terminated string in :mod:`struct` module style syntax giving
the contents of the elements available through the buffer. If this is
*NULL*, ``"B"`` (unsigned bytes) is assumed.
.. cmember:: int ndim
@ -113,11 +113,11 @@ could be used to pass around structured data in its native, in-memory format.
.. cmember:: Py_ssize_t itemsize
This is a storage for the itemsize (in bytes) of each element of the
shared memory. It is technically un-necessary as it can be obtained using
:cfunc:`PyBuffer_SizeFromFormat`, however an exporter may know this
information without parsing the format string and it is necessary to know
the itemsize for proper interpretation of striding. Therefore, storing it
is more convenient and faster.
shared memory. It is technically un-necessary as it can be obtained
using :cfunc:`PyBuffer_SizeFromFormat`, however an exporter may know
this information without parsing the format string and it is necessary
to know the itemsize for proper interpretation of striding. Therefore,
storing it is more convenient and faster.
.. cmember:: void *internal
@ -140,20 +140,20 @@ Buffer related functions
.. cfunction:: int PyObject_GetBuffer(PyObject *obj, PyObject *view, int flags)
Export *obj* into a :ctype:`Py_buffer`, *view*. These arguments must
never be *NULL*. The *flags* argument is a bit field indicating what kind
of buffer the caller is prepared to deal with and therefore what kind of
buffer the exporter is allowed to return. The buffer interface allows for
complicated memory sharing possibilities, but some caller may not be able
to handle all the complexibity but may want to see if the exporter will
let them take a simpler view to its memory.
never be *NULL*. The *flags* argument is a bit field indicating what
kind of buffer the caller is prepared to deal with and therefore what
kind of buffer the exporter is allowed to return. The buffer interface
allows for complicated memory sharing possibilities, but some caller may
not be able to handle all the complexibity but may want to see if the
exporter will let them take a simpler view to its memory.
Some exporters may not be able to share memory in every possible way and
may need to raise errors to signal to some consumers that something is
just not possible. These errors should be a :exc:`BufferError` unless
there is another error that is actually causing the problem. The exporter
can use flags information to simplify how much of the :cdata:`Py_buffer`
structure is filled in with non-default values and/or raise an error if
the object can't support a simpler view of its memory.
there is another error that is actually causing the problem. The
exporter can use flags information to simplify how much of the
:cdata:`Py_buffer` structure is filled in with non-default values and/or
raise an error if the object can't support a simpler view of its memory.
0 is returned on success and -1 on error.
@ -264,16 +264,16 @@ Buffer related functions
.. cfunction:: int PyObject_CopyToObject(PyObject *obj, void *buf, Py_ssize_t len, char fortran)
Copy *len* bytes of data pointed to by the contiguous chunk of memory pointed
to by *buf* into the buffer exported by obj. The buffer must of course be
writable. Return 0 on success and return -1 and raise an error on failure.
If the object does not have a writable buffer, then an error is raised. If
*fortran* is ``'F'``, then if the object is multi-dimensional, then the data
will be copied into the array in Fortran-style (first dimension varies the
fastest). If *fortran* is ``'C'``, then the data will be copied into the
array in C-style (last dimension varies the fastest). If *fortran* is
``'A'``, then it does not matter and the copy will be made in whatever way is
more efficient.
Copy *len* bytes of data pointed to by the contiguous chunk of memory
pointed to by *buf* into the buffer exported by obj. The buffer must of
course be writable. Return 0 on success and return -1 and raise an error
on failure. If the object does not have a writable buffer, then an error
is raised. If *fortran* is ``'F'``, then if the object is
multi-dimensional, then the data will be copied into the array in
Fortran-style (first dimension varies the fastest). If *fortran* is
``'C'``, then the data will be copied into the array in C-style (last
dimension varies the fastest). If *fortran* is ``'A'``, then it does not
matter and the copy will be made in whatever way is more efficient.
.. cfunction:: int PyBuffer_IsContiguous(Py_buffer *view, char fortran)

111
Doc/c-api/dict.rst
View file

@ -19,8 +19,9 @@ Dictionary Objects
single: DictType (in module types)
single: DictionaryType (in module types)
This instance of :ctype:`PyTypeObject` represents the Python dictionary type.
This is exposed to Python programs as ``dict`` and ``types.DictType``.
This instance of :ctype:`PyTypeObject` represents the Python dictionary
type. This is exposed to Python programs as ``dict`` and
``types.DictType``.
.. cfunction:: int PyDict_Check(PyObject *p)
@ -31,8 +32,8 @@ Dictionary Objects
.. cfunction:: int PyDict_CheckExact(PyObject *p)
Return true if *p* is a dict object, but not an instance of a subtype of the
dict type.
Return true if *p* is a dict object, but not an instance of a subtype of
the dict type.
.. cfunction:: PyObject* PyDict_New()
@ -42,9 +43,9 @@ Dictionary Objects
.. cfunction:: PyObject* PyDictProxy_New(PyObject *dict)
Return a proxy object for a mapping which enforces read-only behavior. This is
normally used to create a proxy to prevent modification of the dictionary for
non-dynamic class types.
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)
@ -54,9 +55,9 @@ Dictionary Objects
.. cfunction:: int PyDict_Contains(PyObject *p, PyObject *key)
Determine if dictionary *p* contains *key*. If an item in *p* is matches *key*,
return ``1``, otherwise return ``0``. On error, return ``-1``. This is
equivalent to the Python expression ``key in p``.
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)
@ -67,25 +68,25 @@ Dictionary Objects
.. cfunction:: int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)
Insert *value* into the dictionary *p* with a key of *key*. *key* must be
:term:`hashable`; if it isn't, :exc:`TypeError` will be raised. Return ``0``
on success or ``-1`` on failure.
:term:`hashable`; if it isn't, :exc:`TypeError` will be raised. Return
``0`` on success or ``-1`` on failure.
.. cfunction:: int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)
.. index:: single: 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
:cfunc:`PyUnicode_FromString(key)`. Return ``0`` on success or ``-1`` on
Insert *value* into the dictionary *p* using *key* as a key. *key* should
be a :ctype:`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)
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.
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)
@ -96,8 +97,8 @@ Dictionary Objects
.. cfunction:: PyObject* PyDict_GetItem(PyObject *p, PyObject *key)
Return the object from dictionary *p* which has a key *key*. Return *NULL* if
the key *key* is not present, but *without* setting an exception.
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)
@ -116,41 +117,46 @@ Dictionary Objects
.. cfunction:: PyObject* PyDict_Items(PyObject *p)
Return a :ctype:`PyListObject` containing all the items from the dictionary, as
in the dictionary method :meth:`dict.items`.
Return a :ctype:`PyListObject` containing all the items from the
dictionary, as in the dictionary method :meth:`dict.items`.
.. cfunction:: PyObject* PyDict_Keys(PyObject *p)
Return a :ctype:`PyListObject` containing all the keys from the dictionary, as
in the dictionary method :meth:`dict.keys`.
Return a :ctype:`PyListObject` containing all the keys from the dictionary,
as in the dictionary method :meth:`dict.keys`.
.. cfunction:: PyObject* PyDict_Values(PyObject *p)
Return a :ctype:`PyListObject` containing all the values from the dictionary
*p*, as in the dictionary method :meth:`dict.values`.
Return a :ctype:`PyListObject` containing all the values from the
dictionary *p*, as in the dictionary method :meth:`dict.values`.
.. cfunction:: Py_ssize_t PyDict_Size(PyObject *p)
.. index:: builtin: len
Return the number of items in the dictionary. This is equivalent to ``len(p)``
on a dictionary.
Return the number of items in the dictionary. This is equivalent to
``len(p)`` on a dictionary.
.. versionchanged:: 2.5
This function returned an :ctype:`int` type. This might require changes
in your code for properly supporting 64-bit systems.
.. cfunction:: int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)
Iterate over all key-value pairs in the dictionary *p*. The :ctype:`int`
referred to by *ppos* must be initialized to ``0`` prior to the first call to
this function to start the iteration; the function returns true for each pair in
the dictionary, and false once all pairs have been reported. The parameters
*pkey* and *pvalue* should either point to :ctype:`PyObject\*` variables that
will be filled in with each key and value, respectively, or may be *NULL*. Any
references returned through them are borrowed. *ppos* should not be altered
during iteration. Its value represents offsets within the internal dictionary
structure, and since the structure is sparse, the offsets are not consecutive.
Iterate over all key-value pairs in the dictionary *p*. The
:ctype:`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
and value, respectively, or may be *NULL*. Any references returned through
them are borrowed. *ppos* should not be altered during iteration. Its
value represents offsets within the internal dictionary structure, and
since the structure is sparse, the offsets are not consecutive.
For example::
@ -163,8 +169,8 @@ Dictionary Objects
}
The dictionary *p* should not be mutated during iteration. It is safe to
modify the values of the keys as you iterate over the dictionary, but only so
long as the set of keys does not change. For example::
modify the values of the keys as you iterate over the dictionary, but only
so long as the set of keys does not change. For example::
PyObject *key, *value;
Py_ssize_t pos = 0;
@ -184,15 +190,19 @@ Dictionary Objects
Py_DECREF(o);
}
.. versionchanged:: 2.5
This function used an :ctype:`int *` type for *ppos*. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: int PyDict_Merge(PyObject *a, PyObject *b, int override)
Iterate over mapping object *b* adding key-value pairs to dictionary *a*. *b*
may be a dictionary, or any object supporting :func:`PyMapping_Keys` and
:func:`PyObject_GetItem`. If *override* is true, existing pairs in *a* will be
replaced if a matching key is found in *b*, otherwise pairs will only be added
if there is not a matching key in *a*. Return ``0`` on success or ``-1`` if an
exception was raised.
Iterate over mapping object *b* adding key-value pairs to dictionary *a*.
*b* may be a dictionary, or any object supporting :func:`PyMapping_Keys`
and :func:`PyObject_GetItem`. If *override* is true, existing pairs in *a*
will be replaced if a matching key is found in *b*, otherwise pairs will
only be added if there is not a matching key in *a*. Return ``0`` on
success or ``-1`` if an exception was raised.
.. cfunction:: int PyDict_Update(PyObject *a, PyObject *b)
@ -203,11 +213,12 @@ Dictionary Objects
.. cfunction:: int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override)
Update or merge into dictionary *a*, from the key-value pairs in *seq2*. *seq2*
must be an iterable object producing iterable objects of length 2, viewed as
key-value pairs. In case of duplicate keys, the last wins if *override* is
true, else the first wins. Return ``0`` on success or ``-1`` if an exception was
raised. Equivalent Python (except for the return value)::
Update or merge into dictionary *a*, from the key-value pairs in *seq2*.
*seq2* must be an iterable object producing iterable objects of length 2,
viewed as key-value pairs. In case of duplicate keys, the last wins if
*override* is true, else the first wins. Return ``0`` on success or ``-1``
if an exception was raised. Equivalent Python (except for the return
value)::
def PyDict_MergeFromSeq2(a, seq2, override):
for key, value in seq2:

74
Doc/c-api/gcsupport.rst
View file

@ -9,7 +9,8 @@ Python's support for detecting and collecting garbage which involves circular
references requires support from object types which are "containers" for other
objects which may also be containers. Types which do not store references to
other objects, or which only store references to atomic types (such as numbers
or strings), do not need to provide any explicit support for garbage collection.
or strings), do not need to provide any explicit support for garbage
collection.
To create a container type, the :attr:`tp_flags` field of the type object must
include the :const:`Py_TPFLAGS_HAVE_GC` and provide an implementation of the
@ -20,13 +21,14 @@ include the :const:`Py_TPFLAGS_HAVE_GC` and provide an implementation of the
.. data:: Py_TPFLAGS_HAVE_GC
:noindex:
Objects with a type with this flag set must conform with the rules documented
here. For convenience these objects will be referred to as container objects.
Objects with a type with this flag set must conform with the rules
documented here. For convenience these objects will be referred to as
container objects.
Constructors for container types must conform to two rules:
#. The memory for the object must be allocated using :cfunc:`PyObject_GC_New` or
:cfunc:`PyObject_GC_VarNew`.
#. The memory for the object must be allocated using :cfunc:`PyObject_GC_New`
or :cfunc:`PyObject_GC_VarNew`.
#. Once all the fields which may contain references to other containers are
initialized, it must call :cfunc:`PyObject_GC_Track`.
@ -46,17 +48,17 @@ Constructors for container types must conform to two rules:
.. cfunction:: PyVarObject * PyObject_GC_Resize(PyVarObject *op, Py_ssize_t)
Resize an object allocated by :cfunc:`PyObject_NewVar`. Returns the resized
object or *NULL* on failure.
Resize an object allocated by :cfunc:`PyObject_NewVar`. Returns the
resized object or *NULL* on failure.
.. cfunction:: void PyObject_GC_Track(PyObject *op)
Adds the object *op* to the set of container objects tracked by the collector.
The collector can run at unexpected times so objects must be valid while being
tracked. This should be called once all the fields followed by the
:attr:`tp_traverse` handler become valid, usually near the end of the
constructor.
Adds the object *op* to the set of container objects tracked by the
collector. The collector can run at unexpected times so objects must be
valid while being tracked. This should be called once all the fields
followed by the :attr:`tp_traverse` handler become valid, usually near the
end of the constructor.
.. cfunction:: void _PyObject_GC_TRACK(PyObject *op)
@ -82,10 +84,10 @@ rules:
.. cfunction:: void PyObject_GC_UnTrack(void *op)
Remove the object *op* from the set of container objects tracked by the
collector. Note that :cfunc:`PyObject_GC_Track` can be called again on this
object to add it back to the set of tracked objects. The deallocator
(:attr:`tp_dealloc` handler) should call this for the object before any of the
fields used by the :attr:`tp_traverse` handler become invalid.
collector. Note that :cfunc:`PyObject_GC_Track` can be called again on
this object to add it back to the set of tracked objects. The deallocator
(:attr:`tp_dealloc` handler) should call this for the object before any of
the fields used by the :attr:`tp_traverse` handler become invalid.
.. cfunction:: void _PyObject_GC_UNTRACK(PyObject *op)
@ -98,11 +100,12 @@ The :attr:`tp_traverse` handler accepts a function parameter of this type:
.. ctype:: int (*visitproc)(PyObject *object, void *arg)
Type of the visitor function passed to the :attr:`tp_traverse` handler. The
function should be called with an object to traverse as *object* and the third
parameter to the :attr:`tp_traverse` handler as *arg*. The Python core uses
several visitor functions to implement cyclic garbage detection; it's not
expected that users will need to write their own visitor functions.
Type of the visitor function passed to the :attr:`tp_traverse` handler.
The function should be called with an object to traverse as *object* and
the third parameter to the :attr:`tp_traverse` handler as *arg*. The
Python core uses several visitor functions to implement cyclic garbage
detection; it's not expected that users will need to write their own
visitor functions.
The :attr:`tp_traverse` handler must have the following type:
@ -111,10 +114,10 @@ The :attr:`tp_traverse` handler must have the following type:
Traversal function for a container object. Implementations must call the
*visit* function for each object directly contained by *self*, with the
parameters to *visit* being the contained object and the *arg* value passed to
the handler. The *visit* function must not be called with a *NULL* object
argument. If *visit* returns a non-zero value that value should be returned
immediately.
parameters to *visit* being the contained object and the *arg* value passed
to the handler. The *visit* function must not be called with a *NULL*
object argument. If *visit* returns a non-zero value that value should be
returned immediately.
To simplify writing :attr:`tp_traverse` handlers, a :cfunc:`Py_VISIT` macro is
provided. In order to use this macro, the :attr:`tp_traverse` implementation
@ -123,9 +126,9 @@ must name its arguments exactly *visit* and *arg*:
.. cfunction:: void Py_VISIT(PyObject *o)
Call the *visit* callback, with arguments *o* and *arg*. If *visit* returns a
non-zero value, then return it. Using this macro, :attr:`tp_traverse` handlers
look like::
Call the *visit* callback, with arguments *o* and *arg*. If *visit* returns
a non-zero value, then return it. Using this macro, :attr:`tp_traverse`
handlers look like::
static int
my_traverse(Noddy *self, visitproc visit, void *arg)
@ -135,14 +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* if
the object is immutable.
The :attr:`tp_clear` handler must be of the :ctype:`inquiry` type, or *NULL*
if the object is immutable.
.. ctype:: int (*inquiry)(PyObject *self)
Drop references that may have created reference cycles. Immutable objects do
not have to define this method since they can never directly create reference
cycles. Note that the object must still be valid after calling this method
(don't just call :cfunc:`Py_DECREF` on a reference). The collector will call
this method if it detects that this object is involved in a reference cycle.
Drop references that may have created reference cycles. Immutable objects
do not have to define this method since they can never directly create
reference cycles. Note that the object must still be valid after calling
this method (don't just call :cfunc:`Py_DECREF` on a reference). The
collector will call this method if it detects that this object is involved
in a reference cycle.

28
Doc/c-api/list.rst
View file

@ -44,6 +44,10 @@ List Objects
:cfunc:`PySequence_SetItem` or expose the object to Python code before setting
all items to a real object with :cfunc:`PyList_SetItem`.
.. versionchanged:: 2.5
This function used an :ctype:`int` for *size*. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: Py_ssize_t PyList_Size(PyObject *list)
@ -52,6 +56,10 @@ List Objects
Return the length of the list object in *list*; this is equivalent to
``len(list)`` on a list object.
.. versionchanged:: 2.5
This function returned an :ctype:`int`. This might require changes in
your code for properly supporting 64-bit systems.
.. cfunction:: Py_ssize_t PyList_GET_SIZE(PyObject *list)
@ -64,6 +72,10 @@ List Objects
must be positive, indexing from the end of the list is not supported. If *pos*
is out of bounds, return *NULL* and set an :exc:`IndexError` exception.
.. versionchanged:: 2.5
This function used an :ctype:`int` for *index*. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: PyObject* PyList_GET_ITEM(PyObject *list, Py_ssize_t i)
@ -80,6 +92,10 @@ List Objects
This function "steals" a reference to *item* and discards a reference to an item
already in the list at the affected position.
.. versionchanged:: 2.5
This function used an :ctype:`int` for *index*. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: void PyList_SET_ITEM(PyObject *list, Py_ssize_t i, PyObject *o)
@ -99,6 +115,10 @@ List Objects
if successful; return ``-1`` and set an exception if unsuccessful. Analogous to
``list.insert(index, item)``.
.. versionchanged:: 2.5
This function used an :ctype:`int` for *index*. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: int PyList_Append(PyObject *list, PyObject *item)
@ -113,6 +133,10 @@ List Objects
and *high*. Return *NULL* and set an exception if unsuccessful. Analogous to
``list[low:high]``.
.. versionchanged:: 2.5
This function used an :ctype:`int` for *low* and *high*. This might
require changes in your code for properly supporting 64-bit systems.
.. cfunction:: int PyList_SetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist)
@ -121,6 +145,10 @@ List Objects
indicating the assignment of an empty list (slice deletion). Return ``0`` on
success, ``-1`` on failure.
.. versionchanged:: 2.5
This function used an :ctype:`int` for *low* and *high*. This might
require changes in your code for properly supporting 64-bit systems.
.. cfunction:: int PyList_Sort(PyObject *list)

4
Doc/c-api/long.rst
View file

@ -100,6 +100,10 @@ All integers are implemented as "long" integer objects of arbitrary size.
string is first encoded to a byte string using :cfunc:`PyUnicode_EncodeDecimal`
and then converted using :cfunc:`PyLong_FromString`.
.. versionchanged:: 2.5
This function used an :ctype:`int` for *length*. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: PyObject* PyLong_FromVoidPtr(void *p)

7
Doc/c-api/mapping.rst
View file

@ -12,7 +12,8 @@ Mapping Protocol
function always succeeds.
.. cfunction:: Py_ssize_t PyMapping_Length(PyObject *o)
.. cfunction:: Py_ssize_t PyMapping_Size(PyObject *o)
Py_ssize_t PyMapping_Length(PyObject *o)
.. index:: builtin: len
@ -20,6 +21,10 @@ Mapping Protocol
objects that do not provide mapping protocol, this is equivalent to the Python
expression ``len(o)``.
.. versionchanged:: 2.5
These functions returned an :ctype:`int` type. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: int PyMapping_DelItemString(PyObject *o, char *key)

4
Doc/c-api/object.rst
View file

@ -304,6 +304,10 @@ is considered sufficient for this determination.
and mapping protocols, the sequence length is returned. On error, ``-1`` is
returned. This is the equivalent to the Python expression ``len(o)``.
.. versionchanged:: 2.5
These functions returned an :ctype:`int` type. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: PyObject* PyObject_GetItem(PyObject *o, PyObject *key)

48
Doc/c-api/sequence.rst
View file

@ -13,6 +13,7 @@ Sequence Protocol
.. cfunction:: Py_ssize_t PySequence_Size(PyObject *o)
Py_ssize_t PySequence_Length(PyObject *o)
.. index:: builtin: len
@ -20,10 +21,9 @@ Sequence Protocol
For objects that do not provide sequence protocol, this is equivalent to the
Python expression ``len(o)``.
.. cfunction:: Py_ssize_t PySequence_Length(PyObject *o)
Alternate name for :cfunc:`PySequence_Size`.
.. versionchanged:: 2.5
These functions returned an :ctype:`int` type. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: PyObject* PySequence_Concat(PyObject *o1, PyObject *o2)
@ -37,6 +37,10 @@ Sequence Protocol
Return the result of repeating sequence object *o* *count* times, or *NULL* on
failure. This is the equivalent of the Python expression ``o * count``.
.. versionchanged:: 2.5
This function used an :ctype:`int` type for *count*. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: PyObject* PySequence_InPlaceConcat(PyObject *o1, PyObject *o2)
@ -51,18 +55,30 @@ Sequence Protocol
failure. The operation is done *in-place* when *o* supports it. This is the
equivalent of the Python expression ``o *= count``.
.. versionchanged:: 2.5
This function used an :ctype:`int` type for *count*. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: PyObject* PySequence_GetItem(PyObject *o, Py_ssize_t i)
Return the *i*th element of *o*, or *NULL* on failure. This is the equivalent of
the Python expression ``o[i]``.
.. versionchanged:: 2.5
This function used an :ctype:`int` type for *i*. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: PyObject* PySequence_GetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2)
Return the slice of sequence object *o* between *i1* and *i2*, or *NULL* on
failure. This is the equivalent of the Python expression ``o[i1:i2]``.
.. versionchanged:: 2.5
This function used an :ctype:`int` type for *i1* and *i2*. This might
require changes in your code for properly supporting 64-bit systems.
.. cfunction:: int PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v)
@ -70,24 +86,40 @@ Sequence Protocol
is the equivalent of the Python statement ``o[i] = v``. This function *does
not* steal a reference to *v*.
.. versionchanged:: 2.5
This function used an :ctype:`int` type for *i*. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: int PySequence_DelItem(PyObject *o, Py_ssize_t i)
Delete the *i*th element of object *o*. Returns ``-1`` on failure. This is the
equivalent of the Python statement ``del o[i]``.
.. versionchanged:: 2.5
This function used an :ctype:`int` type for *i*. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: int PySequence_SetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2, PyObject *v)
Assign the sequence object *v* to the slice in sequence object *o* from *i1* to
*i2*. This is the equivalent of the Python statement ``o[i1:i2] = v``.
.. versionchanged:: 2.5
This function used an :ctype:`int` type for *i1* and *i2*. This might
require changes in your code for properly supporting 64-bit systems.
.. cfunction:: int PySequence_DelSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2)
Delete the slice in sequence object *o* from *i1* to *i2*. Returns ``-1`` on
failure. This is the equivalent of the Python statement ``del o[i1:i2]``.
.. versionchanged:: 2.5
This function used an :ctype:`int` type for *i1* and *i2*. This might
require changes in your code for properly supporting 64-bit systems.
.. cfunction:: Py_ssize_t PySequence_Count(PyObject *o, PyObject *value)
@ -95,6 +127,10 @@ Sequence Protocol
of keys for which ``o[key] == value``. On failure, return ``-1``. This is
equivalent to the Python expression ``o.count(value)``.
.. versionchanged:: 2.5
This function returned an :ctype:`int` type. This might require changes
in your code for properly supporting 64-bit systems.
.. cfunction:: int PySequence_Contains(PyObject *o, PyObject *value)
@ -108,6 +144,10 @@ Sequence Protocol
Return the first index *i* for which ``o[i] == value``. On error, return
``-1``. This is equivalent to the Python expression ``o.index(value)``.
.. versionchanged:: 2.5
This function returned an :ctype:`int` type. This might require changes
in your code for properly supporting 64-bit systems.
.. cfunction:: PyObject* PySequence_List(PyObject *o)

4
Doc/c-api/set.rst
View file

@ -106,6 +106,10 @@ or :class:`frozenset` or instances of their subtypes.
``len(anyset)``. Raises a :exc:`PyExc_SystemError` if *anyset* is not a
:class:`set`, :class:`frozenset`, or an instance of a subtype.
.. versionchanged:: 2.5
This function returned an :ctype:`int`. This might require changes in
your code for properly supporting 64-bit systems.
.. cfunction:: Py_ssize_t PySet_GET_SIZE(PyObject *anyset)

38
Doc/c-api/slice.rst
View file

@ -22,30 +22,42 @@ Slice Objects
.. cfunction:: PyObject* PySlice_New(PyObject *start, PyObject *stop, PyObject *step)
Return a new slice object with the given values. The *start*, *stop*, and
*step* parameters are used as the values of the slice object attributes of the
same names. Any of the values may be *NULL*, in which case the ``None`` will be
used for the corresponding attribute. Return *NULL* if the new object could not
be allocated.
*step* parameters are used as the values of the slice object attributes of
the same names. Any of the values may be *NULL*, in which case the
``None`` will be used for the corresponding attribute. Return *NULL* if
the new object could not be allocated.
.. cfunction:: int PySlice_GetIndices(PySliceObject *slice, Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step)
Retrieve the start, stop and step indices from the slice object *slice*,
assuming a sequence of length *length*. Treats indices greater than *length* as
errors.
assuming a sequence of length *length*. Treats indices greater than
*length* as errors.
Returns 0 on success and -1 on error with no exception set (unless one of the
indices was not :const:`None` and failed to be converted to an integer, in which
case -1 is returned with an exception set).
Returns 0 on success and -1 on error with no exception set (unless one of
the indices was not :const:`None` and failed to be converted to an integer,
in which case -1 is returned with an exception set).
You probably do not want to use this function.
.. versionchanged:: 2.5
This function used an :ctype:`int` type for *length* and an
:ctype:`int *` type for *start*, *stop*, and *step*. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: int PySlice_GetIndicesEx(PySliceObject *slice, Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step, Py_ssize_t *slicelength)
Usable replacement for :cfunc:`PySlice_GetIndices`. Retrieve the start, stop,
and step indices from the slice object *slice* assuming a sequence of length
*length*, and store the length of the slice in *slicelength*. Out of bounds
indices are clipped in a manner consistent with the handling of normal slices.
Usable replacement for :cfunc:`PySlice_GetIndices`. Retrieve the start,
stop, and step indices from the slice object *slice* assuming a sequence of
length *length*, and store the length of the slice in *slicelength*. Out
of bounds indices are clipped in a manner consistent with the handling of
normal slices.
Returns 0 on success and -1 on error with exception set.
.. versionchanged:: 2.5
This function used an :ctype:`int` type for *length* and an
:ctype:`int *` type for *start*, *stop*, *step*, and *slicelength*. This
might require changes in your code for properly supporting 64-bit
systems.

29
Doc/c-api/tuple.rst
View file

@ -37,6 +37,10 @@ Tuple Objects
Return a new tuple object of size *len*, or *NULL* on failure.
.. versionchanged:: 2.5
This function used an :ctype:`int` type for *len*. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: PyObject* PyTuple_Pack(Py_ssize_t n, ...)
@ -44,11 +48,19 @@ Tuple Objects
are initialized to the subsequent *n* C arguments pointing to Python objects.
``PyTuple_Pack(2, a, b)`` is equivalent to ``Py_BuildValue("(OO)", a, b)``.
.. versionchanged:: 2.5
This function used an :ctype:`int` type for *n*. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: Py_ssize_t PyTuple_Size(PyObject *p)
Take a pointer to a tuple object, and return the size of that tuple.
.. versionchanged:: 2.5
This function returned an :ctype:`int` type. This might require changes
in your code for properly supporting 64-bit systems.
.. cfunction:: Py_ssize_t PyTuple_GET_SIZE(PyObject *p)
@ -61,6 +73,10 @@ Tuple Objects
Return the object at position *pos* in the tuple pointed to by *p*. If *pos* is
out of bounds, return *NULL* and sets an :exc:`IndexError` exception.
.. versionchanged:: 2.5
This function used an :ctype:`int` type for *pos*. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: PyObject* PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)
@ -72,6 +88,10 @@ Tuple Objects
Take a slice of the tuple pointed to by *p* from *low* to *high* and return it
as a new tuple.
.. versionchanged:: 2.5
This function used an :ctype:`int` type for *low* and *high*. This might
require changes in your code for properly supporting 64-bit systems.
.. cfunction:: int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)
@ -82,6 +102,10 @@ Tuple Objects
This function "steals" a reference to *o*.
.. versionchanged:: 2.5
This function used an :ctype:`int` type for *pos*. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: void PyTuple_SET_ITEM(PyObject *p, Py_ssize_t pos, PyObject *o)
@ -106,6 +130,11 @@ Tuple Objects
``*p`` is destroyed. On failure, returns ``-1`` and sets ``*p`` to *NULL*, and
raises :exc:`MemoryError` or :exc:`SystemError`.
.. versionchanged:: 2.5
This function used an :ctype:`int` type for *newsize*. This might
require changes in your code for properly supporting 64-bit systems.
.. cfunction:: int PyTuple_ClearFreeList(void)
Clear the free list. Return the total number of freed items.

4
Doc/c-api/type.rst
View file

@ -66,6 +66,10 @@ Type Objects
XXX: Document.
.. versionchanged:: 2.5
This function used an :ctype:`int` type for *nitems*. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: PyObject* PyType_GenericNew(PyTypeObject *type, PyObject *args, PyObject *kwds)