Merged revisions...

Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk

........
  r71873 | jeroen.ruigrok | 2009-04-25 13:15:06 +0200 (za, 25 apr 2009) | 2 lines

  Reformat prior to expanding.
........
  r71874 | jeroen.ruigrok | 2009-04-25 13:59:09 +0200 (za, 25 apr 2009) | 2 lines

  First attempt to document PyObject_HEAD_INIT and PyVarObject_HEAD_INIT.
........
  r71882 | jeroen.ruigrok | 2009-04-25 14:49:10 +0200 (za, 25 apr 2009) | 3 lines

  Issue #4239: adjust email examples not to use connect() and terminate with
  quit() and not close().
........
  r71890 | jeroen.ruigrok | 2009-04-25 15:07:40 +0200 (za, 25 apr 2009) | 3 lines

  Rewrite a sentence to be more in line with the rest of the documentation with
  regard to person and audience.
........
  r71893 | jeroen.ruigrok | 2009-04-25 15:58:58 +0200 (za, 25 apr 2009) | 2 lines

  Reformat file prior to editing.
........
  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.
........
  r71920 | jeroen.ruigrok | 2009-04-25 21:44:55 +0200 (za, 25 apr 2009) | 5 lines

  Issue #4129: More documentation pointers about int -> Py_ssize_t.
  Also fix up the documentation for PyObject_GC_Resize(). It seems that since
  it first got documented, the documentation was actually for
  _PyObject_GC_Resize().
........
  r71921 | jeroen.ruigrok | 2009-04-25 21:46:19 +0200 (za, 25 apr 2009) | 2 lines

  Issue #4129: Documentation notes for int -> Py_ssize_t changes.
........
  r71922 | jeroen.ruigrok | 2009-04-25 21:49:05 +0200 (za, 25 apr 2009) | 2 lines

  Reformat, since I've been busy here anyway.
........
  r71923 | jeroen.ruigrok | 2009-04-25 21:54:34 +0200 (za, 25 apr 2009) | 2 lines

  Issue #4129: Add a versionchanged notice for a few forgotten entries.
........
  r71925 | jeroen.ruigrok | 2009-04-25 22:37:39 +0200 (za, 25 apr 2009) | 2 lines

  Since it's a macro, actually refer to it as such instead of function.
........
  r71926 | jeroen.ruigrok | 2009-04-25 22:40:10 +0200 (za, 25 apr 2009) | 2 lines

  Reformat prior to editing.
........
  r71927 | jeroen.ruigrok | 2009-04-25 22:41:40 +0200 (za, 25 apr 2009) | 2 lines

  Issue #4129: int -> Py_ssize_t documentation.
........
  r71928 | jeroen.ruigrok | 2009-04-25 22:43:30 +0200 (za, 25 apr 2009) | 2 lines

  Reformat prior to editing.
........
  r71929 | jeroen.ruigrok | 2009-04-25 22:44:58 +0200 (za, 25 apr 2009) | 2 lines

  Issue #4129: int -> Py_ssize_t documentation.
........
  r71931 | jeroen.ruigrok | 2009-04-25 22:50:27 +0200 (za, 25 apr 2009) | 2 lines

  Issue #4129: int -> Py_ssize_t documentation.
........
  r71932 | jeroen.ruigrok | 2009-04-25 22:55:39 +0200 (za, 25 apr 2009) | 2 lines

  Issue #4129: more int -> Py_ssize_t documentation.
........
  r71933 | jeroen.ruigrok | 2009-04-25 22:58:35 +0200 (za, 25 apr 2009) | 2 lines

  Issue #4129: more int -> Py_ssize_t documentation.
........
  r71934 | jeroen.ruigrok | 2009-04-25 23:02:34 +0200 (za, 25 apr 2009) | 2 lines

  Issue #4129: field changed from int to Py_ssize_t.
........
  r71937 | jeroen.ruigrok | 2009-04-25 23:16:05 +0200 (za, 25 apr 2009) | 2 lines

  Issue #4129: document int -> Py_ssize_t changes.
........

Doc/c-api/allocation.rst

@@ -11,16 +11,21 @@ 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)
 
 
 .. 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,77 +33,90 @@ Allocating Objects on the Heap
    This does everything :cfunc:`PyObject_Init` does, and also initializes the
    length information for a variable-size object.
 
+   .. 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:: 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.
+
+   .. 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)
 
    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.
 
 
 .. cfunction:: PyObject* Py_InitModule(char *name, PyMethodDef *methods)
 
-   Create a new module object based on a name and table of functions, returning the
-   new module object.
+   Create a new module object based on a name and table of functions,
+   returning the new module object.
 
    .. versionchanged:: 2.3
-      Older versions of Python did not support *NULL* as the value for the *methods*
-      argument.
+      Older versions of Python did not support *NULL* as the value for the
+      *methods* argument.
 
 
 .. cfunction:: PyObject* Py_InitModule3(char *name, PyMethodDef *methods, char *doc)
 
-   Create a new module object based on a name and table of functions, returning the
-   new module object.  If *doc* is non-*NULL*, it will be used to define the
-   docstring for the module.
+   Create a new module object based on a name and table of functions,
+   returning the new module object.  If *doc* is non-*NULL*, it will be used
+   to define the docstring for the module.
 
    .. versionchanged:: 2.3
-      Older versions of Python did not support *NULL* as the value for the *methods*
-      argument.
+      Older versions of Python did not support *NULL* as the value for the
+      *methods* argument.
 
 
 .. cfunction:: PyObject* Py_InitModule4(char *name, PyMethodDef *methods, char *doc, PyObject *self, int apiver)
 
-   Create a new module object based on a name and table of functions, returning the
-   new module object.  If *doc* is non-*NULL*, it will be used to define the
-   docstring for the module.  If *self* is non-*NULL*, it will passed to the
-   functions of the module as their (otherwise *NULL*) first parameter.  (This was
-   added as an experimental feature, and there are no known uses in the current
-   version of Python.)  For *apiver*, the only value which should be passed is
-   defined by the constant :const:`PYTHON_API_VERSION`.
+   Create a new module object based on a name and table of functions,
+   returning the new module object.  If *doc* is non-*NULL*, it will be used
+   to define the docstring for the module.  If *self* is non-*NULL*, it will
+   passed to the functions of the module as their (otherwise *NULL*) first
+   parameter.  (This was added as an experimental feature, and there are no
+   known uses in the current version of Python.)  For *apiver*, the only value
+   which should be passed is defined by the constant
+   :const:`PYTHON_API_VERSION`.
 
    .. note::
 
-      Most uses of this function should probably be using the :cfunc:`Py_InitModule3`
-      instead; only use this if you are sure you need it.
+      Most uses of this function should probably be using the
+      :cfunc:`Py_InitModule3` instead; only use this if you are sure you need
+      it.
 
    .. versionchanged:: 2.3
-      Older versions of Python did not support *NULL* as the value for the *methods*
-      argument.
+      Older versions of Python did not support *NULL* as the value for the
+      *methods* argument.
 
 
 .. cvar:: PyObject _Py_NoneStruct
 
-   Object which is visible in Python as ``None``.  This should only be accessed
-   using the ``Py_None`` macro, which evaluates to a pointer to this object.
+   Object which is visible in Python as ``None``.  This should only be
+   accessed using the ``Py_None`` macro, which evaluates to a pointer to this
+   object.

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)
@@ -34,8 +35,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.
 
    .. versionadded:: 2.4
 
@@ -47,9 +48,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.
 
    .. versionadded:: 2.2
 
@@ -61,9 +62,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``.
 
    .. versionadded:: 2.4
 
@@ -78,24 +79,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: PyString_FromString()
 
-   Insert *value* into the dictionary *p* using *key* as a key. *key* should be a
-   :ctype:`char\*`.  The key object is created using ``PyString_FromString(key)``.
-   Return ``0`` on success or ``-1`` on failure.
+   Insert *value* into the dictionary *p* using *key* as a key. *key* should
+   be a :ctype:`char\*`.  The key object is created using
+   ``PyString_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)
@@ -106,8 +108,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_GetItemString(PyObject *p, const char *key)
@@ -118,41 +120,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::
 
@@ -164,9 +171,10 @@ Dictionary Objects
           ...
       }
 
-   The dictionary *p* should not be mutated during iteration.  It is safe (since
-   Python 2.1) 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::
+   The dictionary *p* should not be mutated during iteration.  It is safe
+   (since Python 2.1) 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::
 
       PyObject *key, *value;
       Py_ssize_t pos = 0;
@@ -183,15 +191,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.
 
    .. versionadded:: 2.2
 
@@ -206,11 +218,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.
 
 .. An example showing the use of these interfaces can be found in "Supporting the
 .. Cycle Collector (XXX not found: ../ext/example-cycle-support.html)".
@@ -23,13 +24,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,20 +48,28 @@ Constructors for container types must conform to two rules:
    Analogous to :cfunc:`PyObject_NewVar` but for container objects with the
    :const:`Py_TPFLAGS_HAVE_GC` flag set.
 
+   .. 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:: 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.
+.. cfunction:: TYPE* PyObject_GC_Resize(TYPE, PyVarObject *op, Py_ssize_t newsize)
+
+   Resize an object allocated by :cfunc:`PyObject_NewVar`.  Returns the
+   resized object or *NULL* on failure.
+
+   .. 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:: 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)
@@ -85,10 +95,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)
@@ -101,11 +111,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:
 
@@ -114,10 +125,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
@@ -126,9 +137,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)
@@ -140,14 +151,15 @@ must name its arguments exactly *visit* and *arg*:
 
    .. versionadded:: 2.4
 
-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/init.rst

@@ -491,13 +491,13 @@ thread could immediately acquire the lock and store its own thread state in the
 global variable). Conversely, when acquiring the lock and restoring the thread
 state, the lock must be acquired before storing the thread state pointer.
 
-Why am I going on with so much detail about this?  Because when threads are
-created from C, they don't have the global interpreter lock, nor is there a
-thread state data structure for them.  Such threads must bootstrap themselves
-into existence, by first creating a thread state data structure, then acquiring
-the lock, and finally storing their thread state pointer, before they can start
-using the Python/C API.  When they are done, they should reset the thread state
-pointer, release the lock, and finally free their thread state data structure.
+It is important to note that when threads are created from C, they don't have
+the global interpreter lock, nor is there a thread state data structure for
+them.  Such threads must bootstrap themselves into existence, by first
+creating a thread state data structure, then acquiring the lock, and finally
+storing their thread state pointer, before they can start using the Python/C
+API.  When they are done, they should reset the thread state pointer, release
+the lock, and finally free their thread state data structure.
 
 Beginning with version 2.3, threads can now take advantage of the
 :cfunc:`PyGILState_\*` functions to do all of the above automatically.  The

Doc/c-api/list.rst

@@ -17,8 +17,9 @@ List Objects
 
    .. index:: single: ListType (in module types)
 
-   This instance of :ctype:`PyTypeObject` represents the Python list type.  This is
-   the same object as ``list`` and ``types.ListType`` in the Python layer.
+   This instance of :ctype:`PyTypeObject` represents the Python list type.
+   This is the same object as ``list`` and ``types.ListType`` in the Python
+   layer.
 
 
 .. cfunction:: int PyList_Check(PyObject *p)
@@ -32,8 +33,8 @@ List Objects
 
 .. cfunction:: int PyList_CheckExact(PyObject *p)
 
-   Return true if *p* is a list object, but not an instance of a subtype of the
-   list type.
+   Return true if *p* is a list object, but not an instance of a subtype of
+   the list type.
 
    .. versionadded:: 2.2
 
@@ -44,10 +45,14 @@ List Objects
 
    .. note::
 
-      If *length* is greater than zero, the returned list object's items are set to
-      ``NULL``.  Thus you cannot use abstract API functions such as
-      :cfunc:`PySequence_SetItem`  or expose the object to Python code before setting
-      all items to a real object with :cfunc:`PyList_SetItem`.
+      If *length* is greater than zero, the returned list object's items are
+      set to ``NULL``.  Thus you cannot use abstract API functions such as
+      :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,80 +62,118 @@ 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)
 
    Macro form of :cfunc:`PyList_Size` without error checking.
 
+   .. versionchanged:: 2.5
+      This macro returned an :ctype:`int`. This might require changes in your
+      code for properly supporting 64-bit systems.
+
 
 .. cfunction:: PyObject* PyList_GetItem(PyObject *list, Py_ssize_t index)
 
-   Return the object at position *pos* in the list pointed to by *p*.  The position
-   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.
+   Return the object at position *pos* in the list pointed to by *p*.  The
+   position 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)
 
    Macro form of :cfunc:`PyList_GetItem` without error checking.
 
+   .. versionchanged:: 2.5
+      This macro used an :ctype:`int` for *i*. This might require changes in
+      your code for properly supporting 64-bit systems.
+
 
 .. cfunction:: int PyList_SetItem(PyObject *list, Py_ssize_t index, PyObject *item)
 
-   Set the item at index *index* in list to *item*.  Return ``0`` on success or
-   ``-1`` on failure.
+   Set the item at index *index* in list to *item*.  Return ``0`` on success
+   or ``-1`` on failure.
 
    .. note::
 
-      This function "steals" a reference to *item* and discards a reference to an item
-      already in the list at the affected position.
+      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)
 
-   Macro form of :cfunc:`PyList_SetItem` without error checking. This is normally
-   only used to fill in new lists where there is no previous content.
+   Macro form of :cfunc:`PyList_SetItem` without error checking. This is
+   normally only used to fill in new lists where there is no previous content.
 
    .. note::
 
-      This function "steals" a reference to *item*, and, unlike
-      :cfunc:`PyList_SetItem`, does *not* discard a reference to any item that it
-      being replaced; any reference in *list* at position *i* will be leaked.
+      This macro "steals" a reference to *item*, and, unlike
+      :cfunc:`PyList_SetItem`, does *not* discard a reference to any item that
+      it being replaced; any reference in *list* at position *i* will be
+      leaked.
+
+   .. versionchanged:: 2.5
+      This macro used an :ctype:`int` for *i*. This might require
+      changes in your code for properly supporting 64-bit systems.
 
 
 .. cfunction:: int PyList_Insert(PyObject *list, Py_ssize_t index, PyObject *item)
 
-   Insert the item *item* into list *list* in front of index *index*.  Return ``0``
-   if successful; return ``-1`` and set an exception if unsuccessful.  Analogous to
-   ``list.insert(index, item)``.
+   Insert the item *item* into list *list* in front of index *index*.  Return
+   ``0`` 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)
 
-   Append the object *item* at the end of list *list*. Return ``0`` if successful;
-   return ``-1`` and set an exception if unsuccessful.  Analogous to
-   ``list.append(item)``.
+   Append the object *item* at the end of list *list*. Return ``0`` if
+   successful; return ``-1`` and set an exception if unsuccessful.  Analogous
+   to ``list.append(item)``.
 
 
 .. cfunction:: PyObject* PyList_GetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high)
 
-   Return a list of the objects in *list* containing the objects *between* *low*
-   and *high*.  Return *NULL* and set an exception if unsuccessful. Analogous to
-   ``list[low:high]``.
+   Return a list of the objects in *list* containing the objects *between*
+   *low* 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)
 
-   Set the slice of *list* between *low* and *high* to the contents of *itemlist*.
-   Analogous to ``list[low:high] = itemlist``. The *itemlist* may be *NULL*,
-   indicating the assignment of an empty list (slice deletion). Return ``0`` on
-   success, ``-1`` on failure.
+   Set the slice of *list* between *low* and *high* to the contents of
+   *itemlist*.  Analogous to ``list[low:high] = itemlist``. The *itemlist* may
+   be *NULL*, 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)
 
-   Sort the items of *list* in place.  Return ``0`` on success, ``-1`` on failure.
-   This is equivalent to ``list.sort()``.
+   Sort the items of *list* in place.  Return ``0`` on success, ``-1`` on
+   failure.  This is equivalent to ``list.sort()``.
 
 
 .. cfunction:: int PyList_Reverse(PyObject *list)

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)
 

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/marshal.rst

@@ -5,25 +5,26 @@
 Data marshalling support
 ========================
 
-These routines allow C code to work with serialized objects using the same data
-format as the :mod:`marshal` module.  There are functions to write data into the
-serialization format, and additional functions that can be used to read the data
-back.  Files used to store marshalled data must be opened in binary mode.
+These routines allow C code to work with serialized objects using the same
+data format as the :mod:`marshal` module.  There are functions to write data
+into the serialization format, and additional functions that can be used to
+read the data back.  Files used to store marshalled data must be opened in
+binary mode.
 
 Numeric values are stored with the least significant byte first.
 
-The module supports two versions of the data format: version 0 is the historical
-version, version 1 (new in Python 2.4) shares interned strings in the file, and
-upon unmarshalling.  Version 2 (new in Python 2.5) uses a binary format for
-floating point numbers.
-*Py_MARSHAL_VERSION* indicates the current file format (currently 2).
+The module supports two versions of the data format: version 0 is the
+historical version, version 1 (new in Python 2.4) shares interned strings in
+the file, and upon unmarshalling.  Version 2 (new in Python 2.5) uses a binary
+format for floating point numbers.  *Py_MARSHAL_VERSION* indicates the current
+file format (currently 2).
 
 
 .. cfunction:: void PyMarshal_WriteLongToFile(long value, FILE *file, int version)
 
-   Marshal a :ctype:`long` integer, *value*, to *file*.  This will only write the
-   least-significant 32 bits of *value*; regardless of the size of the native
-   :ctype:`long` type.
+   Marshal a :ctype:`long` integer, *value*, to *file*.  This will only write
+   the least-significant 32 bits of *value*; regardless of the size of the
+   native :ctype:`long` type.
 
    .. versionchanged:: 2.4
       *version* indicates the file format.
@@ -48,24 +49,24 @@ floating point numbers.
 The following functions allow marshalled values to be read back in.
 
 XXX What about error detection?  It appears that reading past the end of the
-file will always result in a negative numeric value (where that's relevant), but
-it's not clear that negative values won't be handled properly when there's no
-error.  What's the right way to tell? Should only non-negative values be written
-using these routines?
+file will always result in a negative numeric value (where that's relevant),
+but it's not clear that negative values won't be handled properly when there's
+no error.  What's the right way to tell? Should only non-negative values be
+written using these routines?
 
 
 .. cfunction:: long PyMarshal_ReadLongFromFile(FILE *file)
 
-   Return a C :ctype:`long` from the data stream in a :ctype:`FILE\*` opened for
-   reading.  Only a 32-bit value can be read in using this function, regardless of
-   the native size of :ctype:`long`.
+   Return a C :ctype:`long` from the data stream in a :ctype:`FILE\*` opened
+   for reading.  Only a 32-bit value can be read in using this function,
+   regardless of the native size of :ctype:`long`.
 
 
 .. cfunction:: int PyMarshal_ReadShortFromFile(FILE *file)
 
-   Return a C :ctype:`short` from the data stream in a :ctype:`FILE\*` opened for
-   reading.  Only a 16-bit value can be read in using this function, regardless of
-   the native size of :ctype:`short`.
+   Return a C :ctype:`short` from the data stream in a :ctype:`FILE\*` opened
+   for reading.  Only a 16-bit value can be read in using this function,
+   regardless of the native size of :ctype:`short`.
 
 
 .. cfunction:: PyObject* PyMarshal_ReadObjectFromFile(FILE *file)
@@ -78,17 +79,22 @@ using these routines?
 .. cfunction:: PyObject* PyMarshal_ReadLastObjectFromFile(FILE *file)
 
    Return a Python object from the data stream in a :ctype:`FILE\*` opened for
-   reading.  Unlike :cfunc:`PyMarshal_ReadObjectFromFile`, this function assumes
-   that no further objects will be read from the file, allowing it to aggressively
-   load file data into memory so that the de-serialization can operate from data in
-   memory rather than reading a byte at a time from the file.  Only use these
-   variant if you are certain that you won't be reading anything else from the
-   file.  On error, sets the appropriate exception (:exc:`EOFError` or
-   :exc:`TypeError`) and returns *NULL*.
+   reading.  Unlike :cfunc:`PyMarshal_ReadObjectFromFile`, this function
+   assumes that no further objects will be read from the file, allowing it to
+   aggressively load file data into memory so that the de-serialization can
+   operate from data in memory rather than reading a byte at a time from the
+   file.  Only use these variant if you are certain that you won't be reading
+   anything else from the file.  On error, sets the appropriate exception
+   (:exc:`EOFError` or :exc:`TypeError`) and returns *NULL*.
 
 
 .. cfunction:: PyObject* PyMarshal_ReadObjectFromString(char *string, Py_ssize_t len)
 
-   Return a Python object from the data stream in a character buffer containing
-   *len* bytes pointed to by *string*.  On error, sets the appropriate exception
-   (:exc:`EOFError` or :exc:`TypeError`) and returns *NULL*.
+   Return a Python object from the data stream in a character buffer
+   containing *len* bytes pointed to by *string*.  On error, sets the
+   appropriate exception (:exc:`EOFError` or :exc:`TypeError`) and returns
+   *NULL*.
+
+   .. 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.

Doc/c-api/objbuffer.rst

@@ -2,30 +2,46 @@
 
 .. _abstract-buffer:
 
-Buffer Protocol
-===============
+Old Buffer Protocol
+===================
+
+
+This section describes the legacy buffer protocol, which has been introduced
+in Python 1.6. It is still supported but deprecated in the Python 2.x series.
+Python 3.0 introduces a new buffer protocol which fixes weaknesses and
+shortcomings of the protocol, and has been backported to Python 2.6.  See
+:ref:`bufferobjects` for more information.
 
 
 .. cfunction:: int PyObject_AsCharBuffer(PyObject *obj, const char **buffer, Py_ssize_t *buffer_len)
 
    Returns a pointer to a read-only memory location usable as character-based
    input.  The *obj* argument must support the single-segment character buffer
-   interface.  On success, returns ``0``, sets *buffer* to the memory location and
-   *buffer_len* to the buffer length.  Returns ``-1`` and sets a :exc:`TypeError`
-   on error.
+   interface.  On success, returns ``0``, sets *buffer* to the memory location
+   and *buffer_len* to the buffer length.  Returns ``-1`` and sets a
+   :exc:`TypeError` on error.
 
    .. versionadded:: 1.6
 
+   .. versionchanged:: 2.5
+      This function used an :ctype:`int *` type for *buffer_len*. This might
+      require changes in your code for properly supporting 64-bit systems.
+
 
 .. cfunction:: int PyObject_AsReadBuffer(PyObject *obj, const void **buffer, Py_ssize_t *buffer_len)
 
-   Returns a pointer to a read-only memory location containing arbitrary data.  The
-   *obj* argument must support the single-segment readable buffer interface.  On
-   success, returns ``0``, sets *buffer* to the memory location and *buffer_len* to
-   the buffer length.  Returns ``-1`` and sets a :exc:`TypeError` on error.
+   Returns a pointer to a read-only memory location containing arbitrary data.
+   The *obj* argument must support the single-segment readable buffer
+   interface.  On success, returns ``0``, sets *buffer* to the memory location
+   and *buffer_len* to the buffer length.  Returns ``-1`` and sets a
+   :exc:`TypeError` on error.
 
    .. versionadded:: 1.6
 
+   .. versionchanged:: 2.5
+      This function used an :ctype:`int *` type for *buffer_len*. This might
+      require changes in your code for properly supporting 64-bit systems.
+
 
 .. cfunction:: int PyObject_CheckReadBuffer(PyObject *o)
 
@@ -38,9 +54,13 @@ Buffer Protocol
 .. cfunction:: int PyObject_AsWriteBuffer(PyObject *obj, void **buffer, Py_ssize_t *buffer_len)
 
    Returns a pointer to a writeable memory location.  The *obj* argument must
-   support the single-segment, character buffer interface.  On success, returns
-   ``0``, sets *buffer* to the memory location and *buffer_len* to the buffer
-   length.  Returns ``-1`` and sets a :exc:`TypeError` on error.
+   support the single-segment, character buffer interface.  On success,
+   returns ``0``, sets *buffer* to the memory location and *buffer_len* to the
+   buffer length.  Returns ``-1`` and sets a :exc:`TypeError` on error.
 
    .. versionadded:: 1.6
 
+   .. versionchanged:: 2.5
+      This function used an :ctype:`int *` type for *buffer_len*. This might
+      require changes in your code for properly supporting 64-bit systems.
+

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)
 

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)
 
@@ -138,6 +178,10 @@ Sequence Protocol
    Return the *i*th element of *o*, assuming that *o* was returned by
    :cfunc:`PySequence_Fast`, *o* is not *NULL*, and that *i* is within bounds.
 
+   .. 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_Fast_ITEMS(PyObject *o)
 
@@ -160,6 +204,10 @@ Sequence Protocol
 
    .. versionadded:: 2.3
 
+   .. 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:: Py_ssize_t PySequence_Fast_GET_SIZE(PyObject *o)
 

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)
 

Doc/c-api/slice.rst

@@ -22,35 +22,47 @@ 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.  If you want to use slice objects
-   in versions of Python prior to 2.3, you would probably do well to incorporate
-   the source of :cfunc:`PySlice_GetIndicesEx`, suitably renamed, in the source of
-   your extension.
+   You probably do not want to use this function.  If you want to use slice
+   objects in versions of Python prior to 2.3, you would probably do well to
+   incorporate the source of :cfunc:`PySlice_GetIndicesEx`, suitably renamed,
+   in the source of your extension.
+
+   .. 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.
 
    .. versionadded:: 2.3
+
+   .. 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/string.rst

@@ -58,6 +58,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, ...)
 
@@ -132,11 +136,19 @@ 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)
 
    Macro form of :cfunc:`PyString_Size` but without error checking.
 
+   .. versionchanged:: 2.5
+      This macro returned an :ctype:`int` type. This might require changes in
+      your code for properly supporting 64-bit systems.
+
 
 .. cfunction:: char* PyString_AsString(PyObject *string)
 
@@ -172,6 +184,10 @@ called with a non-string parameter.
    *string* and operates on that.  If *string* is not a string object at all,
    :cfunc:`PyString_AsStringAndSize` returns ``-1`` and raises :exc:`TypeError`.
 
+   .. versionchanged:: 2.5
+      This function used an :ctype:`int *` type for *length*. This might
+      require changes in your code for properly supporting 64-bit systems.
+
 
 .. cfunction:: void PyString_Concat(PyObject **string, PyObject *newpart)
 
@@ -200,6 +216,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)
 
@@ -236,6 +255,10 @@ called with a non-string parameter.
    The codec to be used is looked up using the Python codec registry.  Return
    *NULL* if an exception was raised by the codec.
 
+   .. 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* PyString_AsDecodedObject(PyObject *str, const char *encoding, const char *errors)
 
@@ -254,6 +277,10 @@ called with a non-string parameter.
    :meth:`encode` method. The codec to be used is looked up using the Python codec
    registry.  Return *NULL* if an exception was raised by the codec.
 
+   .. 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* PyString_AsEncodedObject(PyObject *str, const char *encoding, const char *errors)
 

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,34 +55,58 @@ 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)
 
    Return the size of the tuple *p*, which must be non-*NULL* and point to a tuple;
    no error checking is performed.
 
+   .. 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* PyTuple_GetItem(PyObject *p, Py_ssize_t pos)
 
    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)
 
    Like :cfunc:`PyTuple_GetItem`, but does no checking of its arguments.
 
+   .. 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_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high)
 
    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 +117,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)
 
@@ -99,6 +131,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:: int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize)
 
@@ -116,6 +152,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)
 

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)
 

Doc/c-api/typeobj.rst

@@ -64,6 +64,10 @@ type objects) *must* have the :attr:`ob_size` field.
 
    This field is not inherited by subtypes.
 
+   .. versionchanged:: 2.5
+      This field used to be an :ctype:`int` type. This might require changes
+      in your code for properly supporting 64-bit systems.
+
 
 .. cmember:: PyTypeObject* PyObject.ob_type
 

Doc/includes/email-alternative.py

@@ -45,4 +45,4 @@ s = smtplib.SMTP('localhost')
 # sendmail function takes 3 arguments: sender's address, recipient's address
 # and message to send - here it is sent as one string.
 s.sendmail(me, you, msg.as_string())
-s.close()
+s.quit()

Doc/includes/email-dir.py

@@ -106,9 +106,8 @@ must be running an SMTP server.
         fp.close()
     else:
         s = smtplib.SMTP()
-        s.connect()
         s.sendmail(opts.sender, opts.recipients, composed)
-        s.close()
+        s.quit()
 
 
 if __name__ == '__main__':

Doc/includes/email-mime.py

@@ -27,6 +27,5 @@ for file in pngfiles:
 
 # Send the email via our own SMTP server.
 s = smtplib.SMTP()
-s.connect()
 s.sendmail(me, family, msg.as_string())
-s.close()
+s.quit()

Doc/includes/email-simple.py

@@ -20,6 +20,5 @@ msg['To'] = you
 # Send the message via our own SMTP server, but don't include the
 # envelope header.
 s = smtplib.SMTP()
-s.connect()
 s.sendmail(me, [you], msg.as_string())
-s.close()
+s.quit()