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.

13 files changed, 171 insertions, 5 deletions

diff --git a/Doc/c-api/allocation.rst b/Doc/c-api/allocation.rst
index 75be4574d0..a4df93f78d 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 e7d997f18e..db0c832d09 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 1bba4958f3..1e80abc49f 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 1dbeffa391..ed07f669a4 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 51f89dffbd..7006babc4a 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 a013eb74aa..c9cb034dc9 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 cff0759b78..78787e30d4 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 79565e1c44..6a538b340d 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 7f5e77a679..c934a1d561 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 a60ccd6237..4bac96ba4b 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 4ff0e14ae7..359b4c57b9 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 5be46c49f8..cf1c790282 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 e4e2e380b7..77a3aec31c 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)