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, 16 insertions, 9 deletions

diff --git a/Lib/test/test_epoll.py b/Lib/test/test_epoll.py
index 549e0f7..efb54f4 100644
--- a/Lib/test/test_epoll.py
+++ b/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)
@@ -117,19 +124,19 @@ class TestEPoll(unittest.TestCase):
         try:
             # TypeError: argument must be an int, or have a fileno() method.
             self.assertRaises(TypeError, ep.register, object(),
-                select.EPOLLIN | select.EPOLLOUT)
+                              select.EPOLLIN | select.EPOLLOUT)
             self.assertRaises(TypeError, ep.register, None,
-                select.EPOLLIN | select.EPOLLOUT)
+                              select.EPOLLIN | select.EPOLLOUT)
             # ValueError: file descriptor cannot be a negative integer (-1)
             self.assertRaises(ValueError, ep.register, -1,
-                select.EPOLLIN | select.EPOLLOUT)
+                              select.EPOLLIN | select.EPOLLOUT)
             # OSError: [Errno 9] Bad file descriptor
             self.assertRaises(OSError, ep.register, 10000,
-                select.EPOLLIN | select.EPOLLOUT)
+                              select.EPOLLIN | select.EPOLLOUT)
             # registering twice also raises an exception
             ep.register(server, select.EPOLLIN | select.EPOLLOUT)
             self.assertRaises(OSError, ep.register, server,
-                select.EPOLLIN | select.EPOLLOUT)
+                              select.EPOLLIN | select.EPOLLOUT)
         finally:
             ep.close()
 
@@ -160,9 +167,9 @@ class TestEPoll(unittest.TestCase):
 
         ep = select.epoll(16)
         ep.register(server.fileno(),
-                   select.EPOLLIN | select.EPOLLOUT | select.EPOLLET)
+                    select.EPOLLIN | select.EPOLLOUT | select.EPOLLET)
         ep.register(client.fileno(),
-                   select.EPOLLIN | select.EPOLLOUT | select.EPOLLET)
+                    select.EPOLLIN | select.EPOLLOUT | select.EPOLLET)
 
         now = time.monotonic()
         events = ep.poll(1, 4)