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

1 files changed, 61 insertions, 50 deletions

diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst
index c748b52..dad5cf0 100644
--- a/Doc/c-api/dict.rst
+++ b/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: