make PyIter_NextItem return 0 for exhausted iterator and 1 when it provides a new value

iritkatriel · iritkatriel · commit edc54c8507f0 · 2023-06-01T22:08:51.000+01:00
diff --git a/Doc/c-api/iter.rst b/Doc/c-api/iter.rst
@@ -40,7 +40,7 @@ something like this::
 
    PyObject *item;
    int res;
-   while ((res = PyIter_NextItem(iterator, &item)) == 0 && item != NULL) {
+   while ((res = PyIter_NextItem(iterator, &item)) == 1) {
        /* do something with item */
        ...
        /* release reference when done */
diff --git a/Include/abstract.h b/Include/abstract.h
@@ -401,7 +401,8 @@ PyAPI_FUNC(int) PyAIter_Check(PyObject *);
    setting *item to the next value, or to NULL if the iterator
    is exhausted.
 
-   Return 0 on success and -1 on error. */
+   Return 1 if *item was set to a new value, 0 if the iterator is
+   exhausted and -1 on error. */
 PyAPI_FUNC(int) PyIter_NextItem(PyObject *iter, PyObject **item);
 
 /* Takes an iterator object and calls its tp_iternext slot,
diff --git a/Modules/_testcapimodule.c b/Modules/_testcapimodule.c
@@ -310,10 +310,14 @@ call_pyiter_nextitem(PyObject* self, PyObject *args)
     if (ret < 0) {
         return NULL;
     }
-    if (item == NULL) {
+    else if (ret == 0) {
+        assert(item == NULL);
         assert(!PyErr_Occurred());
         Py_RETURN_NONE;
     }
+    assert(ret == 1);
+    assert(item != NULL);
+    assert(!PyErr_Occurred());
     return item;
 }
 
diff --git a/Modules/_xxtestfuzz/fuzzer.c b/Modules/_xxtestfuzz/fuzzer.c
@@ -377,7 +377,7 @@ static int fuzz_csv_reader(const char* data, size_t size) {
     if (reader) {
         /* Consume all of the reader as an iterator */
         PyObject* parsed_line;
-        while (PyIter_NextItem(reader, &parsed_line) == 0) {
+        while (PyIter_NextItem(reader, &parsed_line) == 1) {
             Py_DECREF(parsed_line);
         }
     }
diff --git a/Objects/abstract.c b/Objects/abstract.c
@@ -2833,9 +2833,10 @@ PyAIter_Check(PyObject *obj)
             tp->tp_as_async->am_anext != &_PyObject_NextNotImplemented);
 }
 
-/* Set *item to the next item. Return 0 on success and -1 on error.
- * If the iteration terminates normally, set *item to NULL and clear
- * the PyExc_StopIteration exception (if it was set).
+/* If the iterator has another value to return, set *item to this value
+ * and return 1.
+ * If the iterator is exhausted, set *item to NULL and return 0.
+ * On error (other than StopIteration) from tp_iternext, return -1.
  */
 int
 PyIter_NextItem(PyObject *iter, PyObject **item)
@@ -2852,8 +2853,9 @@ PyIter_NextItem(PyObject *iter, PyObject **item)
                 return -1;
             }
         }
+        return 0;
     }
-    return 0;
+    return 1;
 }
 
 /* Return next item.

Original file line number	Diff line number	Diff line change
`@@ -310,10 +310,14 @@ call_pyiter_nextitem(PyObject* self, PyObject *args)`
`310`	`310`	`if (ret < 0) {`
`311`	`311`	`return NULL;`
`312`	`312`	`}`
`313`		`- if (item == NULL) {`
	`313`	`+ else if (ret == 0) {`
	`314`	`+ assert(item == NULL);`
`314`	`315`	`assert(!PyErr_Occurred());`
`315`	`316`	`Py_RETURN_NONE;`
`316`	`317`	`}`
	`318`	`+ assert(ret == 1);`
	`319`	`+ assert(item != NULL);`
	`320`	`+ assert(!PyErr_Occurred());`
`317`	`321`	`return item;`
`318`	`322`	`}`
`319`	`323`
Original file line number	Diff line number	Diff line change
`@@ -377,7 +377,7 @@ static int fuzz_csv_reader(const char* data, size_t size) {`
`377`	`377`	`if (reader) {`
`378`	`378`	`/* Consume all of the reader as an iterator */`
`379`	`379`	`PyObject* parsed_line;`
`380`		`- while (PyIter_NextItem(reader, &parsed_line) == 0) {`
	`380`	`+ while (PyIter_NextItem(reader, &parsed_line) == 1) {`
`381`	`381`	`Py_DECREF(parsed_line);`
`382`	`382`	`}`
`383`	`383`	`}`
Original file line number	Diff line number	Diff line change
`@@ -2833,9 +2833,10 @@ PyAIter_Check(PyObject *obj)`
`2833`	`2833`	`tp->tp_as_async->am_anext != &_PyObject_NextNotImplemented);`
`2834`	`2834`	`}`
`2835`	`2835`
`2836`		`-/* Set *item to the next item. Return 0 on success and -1 on error.`
`2837`		`- * If the iteration terminates normally, set *item to NULL and clear`
`2838`		`- * the PyExc_StopIteration exception (if it was set).`
	`2836`	`+/* If the iterator has another value to return, set *item to this value`
	`2837`	`+ * and return 1.`
	`2838`	`+ * If the iterator is exhausted, set *item to NULL and return 0.`
	`2839`	`+ * On error (other than StopIteration) from tp_iternext, return -1.`
`2839`	`2840`	`*/`
`2840`	`2841`	`int`
`2841`	`2842`	`PyIter_NextItem(PyObject iter, PyObject *item)`
`@@ -2852,8 +2853,9 @@ PyIter_NextItem(PyObject iter, PyObject *item)`
`2852`	`2853`	`return -1;`
`2853`	`2854`	`}`
`2854`	`2855`	`}`
	`2856`	`+ return 0;`
`2855`	`2857`	`}`
`2856`		`- return 0;`
	`2858`	`+ return 1;`
`2857`	`2859`	`}`
`2858`	`2860`
`2859`	`2861`	`/* Return next item.`