From 595d9b6bc661e8609712593a0cb8692f7e9dcd59 Mon Sep 17 00:00:00 2001
From: Georg Brandl <georg@python.org>
Date: Fri, 18 Aug 2006 07:28:03 +0000
Subject: [PATCH] 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)

---
 Doc/api/abstract.tex |  4 ++++
 Doc/api/concrete.tex |  5 +++++
 Doc/api/intro.tex    | 33 +++++++++++----------------------
 Misc/NEWS            | 12 +++++++++++-
 4 files changed, 31 insertions(+), 23 deletions(-)

diff --git a/Doc/api/abstract.tex b/Doc/api/abstract.tex
index 9c39403dfa2..2ea11d12d2b 100644
--- 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 91fd3bb77c3..3a31287b01a 100644
--- 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 1295e5f98dd..80650fede4a 100644
--- 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 1f96071fc8c..de0977d91bf 100644
--- 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?
 =============================================