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