[Python-checkins] r51363 - in python/branches/release24-maint: Doc/api/abstract.tex Doc/api/concrete.tex Doc/api/intro.tex Misc/NEWS
georg.brandl
python-checkins at python.org
Fri Aug 18 09:25:24 CEST 2006
Author: georg.brandl
Date: Fri Aug 18 09:25:22 2006
New Revision: 51363
Modified:
python/branches/release24-maint/Doc/api/abstract.tex
python/branches/release24-maint/Doc/api/concrete.tex
python/branches/release24-maint/Doc/api/intro.tex
python/branches/release24-maint/Misc/NEWS
Log:
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)
Modified: python/branches/release24-maint/Doc/api/abstract.tex
==============================================================================
--- python/branches/release24-maint/Doc/api/abstract.tex (original)
+++ python/branches/release24-maint/Doc/api/abstract.tex Fri Aug 18 09:25:22 2006
@@ -5,6 +5,10 @@
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}}
Modified: python/branches/release24-maint/Doc/api/concrete.tex
==============================================================================
--- python/branches/release24-maint/Doc/api/concrete.tex (original)
+++ python/branches/release24-maint/Doc/api/concrete.tex Fri Aug 18 09:25:22 2006
@@ -1766,6 +1766,11 @@
\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}
Modified: python/branches/release24-maint/Doc/api/intro.tex
==============================================================================
--- python/branches/release24-maint/Doc/api/intro.tex (original)
+++ python/branches/release24-maint/Doc/api/intro.tex Fri Aug 18 09:25:22 2006
@@ -225,25 +225,10 @@
\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 @@
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 @@
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;
}
Modified: python/branches/release24-maint/Misc/NEWS
==============================================================================
--- python/branches/release24-maint/Misc/NEWS (original)
+++ python/branches/release24-maint/Misc/NEWS Fri Aug 18 09:25:22 2006
@@ -166,6 +166,10 @@
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
More information about the Python-checkins
mailing list