bpo-32568: make select.epoll() and its docs consistent (GH-7840) (GH-8024)
* `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.
(cherry picked from commit 0cdf5f42898350261c5ff65d96334e736130780f)
Co-authored-by: Tal Einat <taleinat+github@gmail.com>
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 @@
(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.