From dbd695839fd3ed1e87a77d21b1ec762432da7369 Mon Sep 17 00:00:00 2001
From: Georg Brandl <georg@python.org>
Date: Fri, 18 Aug 2006 07:25:22 +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)

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

diff --git a/Doc/api/abstract.tex b/Doc/api/abstract.tex
index 156583ca1fde..211288d9729f 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 0c18776651a1..46896f1c4550 100644
--- a/Doc/api/concrete.tex
+++ b/Doc/api/concrete.tex
@@ -1766,6 +1766,11 @@ format.
 \begin{cfuncdesc}{PyObject*}{PyList_New}{int 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}{int}{PyList_Size}{PyObject *list}
diff --git a/Doc/api/intro.tex b/Doc/api/intro.tex
index d84b65475766..4aedb89eda5f 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 37c31916aef1..4cb07a87b227 100644
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -166,6 +166,10 @@ Build
 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.
+
 - Clarified documentation for tp_as_buffer->bf_getcharbuffer.
 
 - Bug #1337990: clarified that ``doctest`` does not support examples
-- 
2.47.3