Documentation for PyObject_GetIter(), contributed by Greg Chapman

(with only minor changes by Fred).
This closes SF bug #498607.

Doc/api/abstract.tex

@@ -307,6 +307,14 @@ determination.
   return false.
 \end{cfuncdesc}
 
+\begin{cfuncdesc}{PyObject*}{PyObject_GetIter}{PyObject *o}
+  This is equivalent to the Python expression \samp{iter(\var{o})}.
+  It returns a new iterator for the object argument, or the object 
+  itself if the object is already an iterator.  Raises
+  \exception{TypeError} and returns \NULL{} if the object cannot be
+  iterated.
+\end{cfuncdesc}
+
 
 \section{Number Protocol \label{number}}
 
@@ -855,17 +863,24 @@ To write a loop which iterates over an iterator, the C code should
 look something like this:
 
 \begin{verbatim}
-PyObject *iterator = ...;
+PyObject *iterator = PyObject_GetIter(obj);
 PyObject *item;
 
-while (item = PyIter_Next(iter)) {
+if (iterator == NULL) {
+    /* propagate error */
+}
+
+while (item = PyIter_Next(iterator)) {
     /* do something with item */
     ...
     /* release reference when done */
     Py_DECREF(item);
 }
+
+Py_DECREF(iterator);
+
 if (PyErr_Occurred()) {
-    /* propogate error */
+    /* propagate error */
 }
 else {
     /* continue doing useful work */