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

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.
........

Doc/c-api/allocation.rst

@@ -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

Doc/c-api/arg.rst

@@ -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, ...)
 

Doc/c-api/buffer.rst

@@ -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)

Doc/c-api/dict.rst

@@ -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:

Doc/c-api/gcsupport.rst

@@ -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.

Doc/c-api/list.rst

@@ -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)
 

Doc/c-api/long.rst

@@ -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)
 

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)
 

Doc/c-api/object.rst

@@ -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)
 

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)
 

Doc/c-api/set.rst

@@ -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)
 

Doc/c-api/slice.rst

@@ -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.

Doc/c-api/tuple.rst

@@ -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.

Doc/c-api/type.rst

@@ -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)