From 089c5cdd09b2474194a40b4943dff9359db4969c Mon Sep 17 00:00:00 2001 From: Jeroen Ruigrok van der Werven Date: Sat, 25 Apr 2009 17:59:03 +0000 Subject: 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. --- Doc/c-api/allocation.rst | 4 ++++ Doc/c-api/arg.rst | 4 ++++ Doc/c-api/buffer.rst | 22 ++++++++++++++++++++++ Doc/c-api/dict.rst | 8 ++++++++ Doc/c-api/list.rst | 28 ++++++++++++++++++++++++++++ Doc/c-api/long.rst | 4 ++++ Doc/c-api/mapping.rst | 7 ++++++- Doc/c-api/object.rst | 4 ++++ Doc/c-api/sequence.rst | 48 ++++++++++++++++++++++++++++++++++++++++++++---- Doc/c-api/set.rst | 4 ++++ Doc/c-api/string.rst | 11 +++++++++++ Doc/c-api/tuple.rst | 28 ++++++++++++++++++++++++++++ Doc/c-api/type.rst | 4 ++++ 13 files changed, 171 insertions(+), 5 deletions(-) diff --git a/Doc/c-api/allocation.rst b/Doc/c-api/allocation.rst index 75be457..a4df93f 100644 --- a/Doc/c-api/allocation.rst +++ b/Doc/c-api/allocation.rst @@ -11,6 +11,10 @@ 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:: void _PyObject_Del(PyObject *op) diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst index e7d997f..db0c832 100644 --- a/Doc/c-api/arg.rst +++ b/Doc/c-api/arg.rst @@ -403,6 +403,10 @@ and the following format units are left untouched. .. versionadded:: 2.2 + .. 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, ...) diff --git a/Doc/c-api/buffer.rst b/Doc/c-api/buffer.rst index 1bba495..1e80abc 100644 --- a/Doc/c-api/buffer.rst +++ b/Doc/c-api/buffer.rst @@ -376,6 +376,11 @@ could be used to pass around structured data in its native, in-memory format. then the new buffer's contents extend to the length of the *base* object's exported buffer data. + .. versionchanged:: 2.5 + This function used an :ctype:`int` type for *offset* and *size*. This + might require changes in your code for properly supporting 64-bit + systems. + .. cfunction:: PyObject* PyBuffer_FromReadWriteObject(PyObject *base, Py_ssize_t offset, Py_ssize_t size) @@ -383,6 +388,11 @@ could be used to pass around structured data in its native, in-memory format. those for :cfunc:`PyBuffer_FromObject`. If the *base* object does not export the writeable buffer protocol, then :exc:`TypeError` is raised. + .. versionchanged:: 2.5 + This function used an :ctype:`int` type for *offset* and *size*. This + might require changes in your code for properly supporting 64-bit + systems. + .. cfunction:: PyObject* PyBuffer_FromMemory(void *ptr, Py_ssize_t size) @@ -393,11 +403,19 @@ could be used to pass around structured data in its native, in-memory format. :const:`Py_END_OF_BUFFER` may *not* be passed for the *size* parameter; :exc:`ValueError` will be raised in that case. + .. versionchanged:: 2.5 + This function used an :ctype:`int` type for *size*. This might require + changes in your code for properly supporting 64-bit systems. + .. cfunction:: PyObject* PyBuffer_FromReadWriteMemory(void *ptr, Py_ssize_t size) Similar to :cfunc:`PyBuffer_FromMemory`, but the returned buffer is writable. + .. 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* PyBuffer_New(Py_ssize_t size) @@ -405,3 +423,7 @@ could be used to pass around structured data in its native, in-memory format. *size* bytes. :exc:`ValueError` is returned if *size* is not zero or positive. Note that the memory buffer (as returned by :cfunc:`PyObject_AsWriteBuffer`) is not specifically aligned. + + .. 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. diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst index 1dbeffa..ed07f66 100644 --- a/Doc/c-api/dict.rst +++ b/Doc/c-api/dict.rst @@ -143,6 +143,10 @@ Dictionary Objects 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) @@ -187,6 +191,10 @@ 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) diff --git a/Doc/c-api/list.rst b/Doc/c-api/list.rst index 51f89df..7006bab 100644 --- a/Doc/c-api/list.rst +++ b/Doc/c-api/list.rst @@ -49,6 +49,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) @@ -57,6 +61,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) @@ -69,6 +77,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) @@ -85,6 +97,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) @@ -104,6 +120,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) @@ -118,6 +138,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) @@ -126,6 +150,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) diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst index a013eb7..c9cb034 100644 --- a/Doc/c-api/long.rst +++ b/Doc/c-api/long.rst @@ -106,6 +106,10 @@ Long Integer Objects .. versionadded:: 1.6 + .. 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) diff --git a/Doc/c-api/mapping.rst b/Doc/c-api/mapping.rst index cff0759..78787e3 100644 --- a/Doc/c-api/mapping.rst +++ b/Doc/c-api/mapping.rst @@ -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) diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst index 79565e1..6a538b3 100644 --- a/Doc/c-api/object.rst +++ b/Doc/c-api/object.rst @@ -351,6 +351,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) diff --git a/Doc/c-api/sequence.rst b/Doc/c-api/sequence.rst index 7f5e77a..c934a1d 100644 --- a/Doc/c-api/sequence.rst +++ b/Doc/c-api/sequence.rst @@ -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) diff --git a/Doc/c-api/set.rst b/Doc/c-api/set.rst index a60ccd6..4bac96b 100644 --- a/Doc/c-api/set.rst +++ b/Doc/c-api/set.rst @@ -116,6 +116,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) diff --git a/Doc/c-api/string.rst b/Doc/c-api/string.rst index 4ff0e14..359b4c5 100644 --- a/Doc/c-api/string.rst +++ b/Doc/c-api/string.rst @@ -60,6 +60,10 @@ called with a non-string parameter. *len* on success, and *NULL* on failure. If *v* is *NULL*, the contents of the string are uninitialized. + .. versionchanged:: 2.5 + This function used an :ctype:`int` type for *len*. This might require + changes in your code for properly supporting 64-bit systems. + .. cfunction:: PyObject* PyString_FromFormat(const char *format, ...) @@ -134,6 +138,10 @@ called with a non-string parameter. Return the length of the string in string object *string*. + .. 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 PyString_GET_SIZE(PyObject *string) @@ -202,6 +210,9 @@ called with a non-string parameter. fails, the original string object at *\*string* is deallocated, *\*string* is set to *NULL*, a memory exception is set, and ``-1`` is returned. + .. versionchanged:: 2.5 + This function used an :ctype:`int` type for *newsize*. This might + require changes in your code for properly supporting 64-bit systems. .. cfunction:: PyObject* PyString_Format(PyObject *format, PyObject *args) diff --git a/Doc/c-api/tuple.rst b/Doc/c-api/tuple.rst index 5be46c4..cf1c790 100644 --- a/Doc/c-api/tuple.rst +++ b/Doc/c-api/tuple.rst @@ -42,6 +42,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, ...) @@ -51,11 +55,19 @@ Tuple Objects .. versionadded:: 2.4 + .. 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) @@ -68,6 +80,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) @@ -79,6 +95,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) @@ -89,6 +109,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) @@ -116,6 +140,10 @@ Tuple Objects .. versionchanged:: 2.2 Removed unused third parameter, *last_is_sticky*. + .. 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) diff --git a/Doc/c-api/type.rst b/Doc/c-api/type.rst index e4e2e38..77a3aec 100644 --- a/Doc/c-api/type.rst +++ b/Doc/c-api/type.rst @@ -76,6 +76,10 @@ Type Objects .. versionadded:: 2.2 + .. 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) -- cgit v0.12