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.

Doc/library/select.rst

@@ -57,7 +57,16 @@ The module defines the following:
 
    (Only supported on Linux 2.5.44 and newer.) Return an edge polling object,
    which can be used as Edge or Level Triggered interface for I/O
-   events. *sizehint* and *flags* are deprecated and completely ignored.
+   events.
+
+   *sizehint* informs epoll about the expected number of events to be
+   registered.  It must be positive, or `-1` to use the default. It is only
+   used on older systems where :c:func:`epoll_create1` is not available;
+   otherwise it has no effect (though its value is still checked).
+
+   *flags* is deprecated and completely ignored.  However, when supplied, its
+   value must be ``0`` or ``select.EPOLL_CLOEXEC``, otherwise ``OSError`` is
+   raised.
 
    See the :ref:`epoll-objects` section below for the methods supported by
    epolling objects.

Lib/test/test_epoll.py

@@ -74,11 +74,11 @@ class TestEPoll(unittest.TestCase):
         ep.close()
         self.assertTrue(ep.closed)
         self.assertRaises(ValueError, ep.fileno)
+
         if hasattr(select, "EPOLL_CLOEXEC"):
-            select.epoll(select.EPOLL_CLOEXEC).close()
+            select.epoll(-1, select.EPOLL_CLOEXEC).close()
             select.epoll(flags=select.EPOLL_CLOEXEC).close()
             select.epoll(flags=0).close()
-            self.assertRaises(OSError, select.epoll, flags=12356)
 
     def test_badcreate(self):
         self.assertRaises(TypeError, select.epoll, 1, 2, 3)
@@ -88,6 +88,13 @@ class TestEPoll(unittest.TestCase):
         self.assertRaises(TypeError, select.epoll, ['foo'])
         self.assertRaises(TypeError, select.epoll, {})
 
+        self.assertRaises(ValueError, select.epoll, 0)
+        self.assertRaises(ValueError, select.epoll, -2)
+        self.assertRaises(ValueError, select.epoll, sizehint=-2)
+
+        if hasattr(select, "EPOLL_CLOEXEC"):
+            self.assertRaises(OSError, select.epoll, flags=12356)
+
     def test_context_manager(self):
         with select.epoll(16) as ep:
             self.assertGreater(ep.fileno(), 0)

Misc/NEWS.d/next/Library/2018-06-21-09-33-02.bpo-32568.f_meGY.rst

@@ -0,0 +1,2 @@
+Make select.epoll() and its documentation consistent regarding *sizehint* and
+*flags*.

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);
 }