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, 10 insertions, 1 deletions

diff --git a/Doc/library/select.rst b/Doc/library/select.rst
index e252e7a..5ffb215 100644
--- a/Doc/library/select.rst
+++ b/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.