Bug #1541682: Fix example in the "Refcount details" API docs.

Additionally, remove a faulty example showing PySequence_SetItem applied
to a newly created list object and add notes that this isn't a good idea.
 (backport from rev. 51364)

diff --git a/Doc/api/abstract.tex b/Doc/api/abstract.tex
index 9c39403dfa23bf511841a07ada08a9755c35fc2e..2ea11d12d2bcd2e1d949318f6daeebe29dbc0278 100644 (file)
--- a/Doc/api/abstract.tex
+++ b/Doc/api/abstract.tex
@@ -5,6 +5,10 @@ of their type, or with wide classes of object types (e.g. all
 numerical types, or all sequence types).  When used on object types
 for which they do not apply, they will raise a Python exception.
 
+It is not possible to use these functions on objects that are not properly
+initialized, such a list object that has been created by
+\cfunction{PyList_New()}, but whose items have not been set to some
+non-\code{NULL} value yet.
 
 \section{Object Protocol \label{object}}
 

diff --git a/Doc/api/concrete.tex b/Doc/api/concrete.tex
index 91fd3bb77c3468170b6583f8983dc93ac4162f2a..3a31287b01a1ab520dd957086b681067f8a6a23e 100644 (file)
--- a/Doc/api/concrete.tex
+++ b/Doc/api/concrete.tex
@@ -1840,6 +1840,11 @@ format.
 \begin{cfuncdesc}{PyObject*}{PyList_New}{Py_ssize_t len}
   Return a new list of length \var{len} on success, or \NULL{} on
   failure.
+  \note{If \var{length} is greater than zero, the returned list object's
+        items are set to \code{NULL}.  Thus you cannot use abstract
+        API functions such as \cfunction{PySequence_SetItem()} on it
+        or expose it to Python code before setting all items to a
+        real object with \cfunction{PyList_SetItem()}.}
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{Py_ssize_t}{PyList_Size}{PyObject *list}

diff --git a/Doc/api/intro.tex b/Doc/api/intro.tex
index 1295e5f98dd9eb87ef9ad4ed4566eb2951932c80..80650fede4a9688708d0dae47c0fcb68c76d31c9 100644 (file)
--- a/Doc/api/intro.tex
+++ b/Doc/api/intro.tex
@@ -225,25 +225,10 @@ immutable data type.  You should only use
 \cfunction{PyTuple_SetItem()} for tuples that you are creating
 yourself.
 
-Equivalent code for populating a list can be written using 
-\cfunction{PyList_New()} and \cfunction{PyList_SetItem()}.  Such code
-can also use \cfunction{PySequence_SetItem()}; this illustrates the
-difference between the two (the extra \cfunction{Py_DECREF()} calls):
+Equivalent code for populating a list can be written using
+\cfunction{PyList_New()} and \cfunction{PyList_SetItem()}.
 
-\begin{verbatim}
-PyObject *l, *x;
-
-l = PyList_New(3);
-x = PyInt_FromLong(1L);
-PySequence_SetItem(l, 0, x); Py_DECREF(x);
-x = PyInt_FromLong(2L);
-PySequence_SetItem(l, 1, x); Py_DECREF(x);
-x = PyString_FromString("three");
-PySequence_SetItem(l, 2, x); Py_DECREF(x);
-\end{verbatim}
-
-You might find it strange that the ``recommended'' approach takes more
-code.  However, in practice, you will rarely use these ways of
+However, in practice, you will rarely use these ways of
 creating and populating a tuple or list.  There's a generic function,
 \cfunction{Py_BuildValue()}, that can create most common objects from
 C values, directed by a \dfn{format string}.  For example, the
@@ -251,10 +236,10 @@ above two blocks of code could be replaced by the following (which
 also takes care of the error checking):
 
 \begin{verbatim}
-PyObject *t, *l;
+PyObject *tuple, *list;
 
-t = Py_BuildValue("(iis)", 1, 2, "three");
-l = Py_BuildValue("[iis]", 1, 2, "three");
+tuple = Py_BuildValue("(iis)", 1, 2, "three");
+list = Py_BuildValue("[iis]", 1, 2, "three");
 \end{verbatim}
 
 It is much more common to use \cfunction{PyObject_SetItem()} and
@@ -276,8 +261,12 @@ set_all(PyObject *target, PyObject *item)
     if (n < 0)
         return -1;
     for (i = 0; i < n; i++) {
-        if (PyObject_SetItem(target, i, item) < 0)
+        PyObject *index = PyInt_FromLong(i);
+        if (!index)
+            return -1;
+        if (PyObject_SetItem(target, index, item) < 0)
             return -1;
+        Py_DECREF(index);
     }
     return 0;
 }

diff --git a/Misc/NEWS b/Misc/NEWS
index 1f96071fc8cce9d67fc805af1b057523d98c5ca7..de0977d91bf08b685c90d40194e5fc70162bf5e3 100644 (file)
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -4,7 +4,7 @@ Python News
 
 (editors: check NEWS.help for information about editing NEWS using ReST.)
 
-What's New in Python 2.5 ?
+What's New in Python 2.5?
 =============================================
 
 *Release date: XX-SEP-2006*
@@ -15,11 +15,21 @@ Library
 - Bug #1541863: uuid.uuid1 failed to generate unique identifiers
   on systems with low clock resolution.
 
+
+Documentation
+-------------
+
+- Bug #1541682: Fix example in the "Refcount details" API docs.
+  Additionally, remove a faulty example showing PySequence_SetItem applied
+  to a newly created list object and add notes that this isn't a good idea.
+
+
 Build
 -----
 
 - Fix OpenSSL debug build process.
 
+
 What's New in Python 2.5 release candidate 1?
 =============================================