bpo-32568: make select.epoll() and its docs consistent (#7840)

* `flags` is indeed deprecated, but there is a validation on its value for
  backwards compatibility reasons.  This adds mention of this in the docs.
* The docs say that `sizehint` is deprecated and ignored, but it is still
  used when `epoll_create1()` is unavailable. This adds mention of this in
  the docs.
* `sizehint=-1` is acceptable again, and is replaced with `FD_SETSIZE-1`.
  This is needed to have a default value available at the Python level,
  since `FD_SETSIZE` is not exposed to Python. (see: bpo-31938)
* Reject `sizehint=0` since it is invalid to pass on to `epoll_create()`.

The relevant tests have also been updated.

1 files changed, 6 insertions, 4 deletions

diff --git a/Modules/selectmodule.c b/Modules/selectmodule.c
index a366d1b..6976fb5 100644
--- a/Modules/selectmodule.c
+++ b/Modules/selectmodule.c
@@ -1297,14 +1297,17 @@ newPyEpoll_Object(PyTypeObject *type, int sizehint, SOCKET fd)
 static PyObject *
 pyepoll_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
 {
-    int flags = 0, sizehint = FD_SETSIZE - 1;
+    int flags = 0, sizehint = -1;
     static char *kwlist[] = {"sizehint", "flags", NULL};
 
     if (!PyArg_ParseTupleAndKeywords(args, kwds, "|ii:epoll", kwlist,
                                      &sizehint, &flags))
         return NULL;
-    if (sizehint < 0) {
-        PyErr_SetString(PyExc_ValueError, "negative sizehint");
+    if (sizehint == -1) {
+        sizehint = FD_SETSIZE - 1;
+    }
+    else if (sizehint <= 0) {
+        PyErr_SetString(PyExc_ValueError, "sizehint must be positive or -1");
         return NULL;
     }
 
@@ -1314,7 +1317,6 @@ pyepoll_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
         return NULL;
     }
 #endif
-
     return newPyEpoll_Object(type, sizehint, -1);
 }