Skip to content

gh-151948：Fix all Sphinx reference warnings in Doc/library/select.rst #151957

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
lpyu001 wants to merge 5 commits into
base: main
Choose a base branch
from
+78 −76
Open

gh-151948：Fix all Sphinx reference warnings in Doc/library/select.rst #151957

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
c95064b
Update select.rst
lpyu001 Jun 23, 2026
a0af0a2
Update .nitignore
lpyu001 Jun 23, 2026
0297d51
Update select.rst
lpyu001 Jun 23, 2026
0f8b861
revert unrelated changes
lpyu001 Jun 23, 2026
f329916
Merge branch 'main' into bugifx
lpyu001 Sep 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
153 changes: 78 additions & 75 deletions Doc/library/select.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -305,41 +305,41 @@ Edge and level trigger polling (epoll) objects
+-------------------------+------------------------------------------------+
| Constant | Meaning |
+=========================+================================================+
| :const:`EPOLLIN` | Available for read. |
| .. data:: EPOLLIN | Available for read. |
+-------------------------+------------------------------------------------+
| :const:`EPOLLOUT` | Available for write. |
| .. data:: EPOLLOUT | Available for write. |
+-------------------------+------------------------------------------------+
| :const:`EPOLLPRI` | Urgent data for read. |
| .. data:: EPOLLPRI | Urgent data for read. |
+-------------------------+------------------------------------------------+
| :const:`EPOLLERR` | Error condition happened on the associated fd. |
| .. data:: EPOLLERR | Error condition happened on the associated fd. |
+-------------------------+------------------------------------------------+
| :const:`EPOLLHUP` | Hang up happened on the associated fd. |
| .. data:: EPOLLHUP | Hang up happened on the associated fd. |
+-------------------------+------------------------------------------------+
| :const:`EPOLLET` | Set Edge Trigger behavior, the default is |
| .. data:: EPOLLET | Set Edge Trigger behavior, the default is |
| | Level Trigger behavior. |
+-------------------------+------------------------------------------------+
| :const:`EPOLLONESHOT` | Set one-shot behavior. After one event is |
| .. data:: EPOLLONESHOT | Set one-shot behavior. After one event is |
| | pulled out, the fd is internally disabled. |
+-------------------------+------------------------------------------------+
| :const:`EPOLLEXCLUSIVE` | Wake only one epoll object when the |
| .. data:: EPOLLEXCLUSIVE| Wake only one epoll object when the |
| | associated fd has an event. The default (if |
| | this flag is not set) is to wake all epoll |
| | objects polling on an fd. |
+-------------------------+------------------------------------------------+
| :const:`EPOLLRDHUP` | Stream socket peer closed connection or shut |
| .. data:: EPOLLRDHUP | Stream socket peer closed connection or shut |
| | down writing half of connection. |
+-------------------------+------------------------------------------------+
| :const:`EPOLLRDNORM` | Equivalent to :const:`EPOLLIN` |
| .. data:: EPOLLRDNORM | Equivalent to :const:`EPOLLIN` |
+-------------------------+------------------------------------------------+
| :const:`EPOLLRDBAND` | Priority data band can be read. |
| .. data:: EPOLLRDBAND | Priority data band can be read. |
+-------------------------+------------------------------------------------+
| :const:`EPOLLWRNORM` | Equivalent to :const:`EPOLLOUT`. |
| .. data:: EPOLLWRNORM | Equivalent to :const:`EPOLLOUT`. |
+-------------------------+------------------------------------------------+
| :const:`EPOLLWRBAND` | Priority data may be written. |
| .. data:: EPOLLWRBAND | Priority data may be written. |
+-------------------------+------------------------------------------------+
| :const:`EPOLLMSG` | Ignored. |
| .. data:: EPOLLMSG | Ignored. |
+-------------------------+------------------------------------------------+
| :const:`EPOLLWAKEUP` | Prevents sleep during event waiting. |
| .. data:: EPOLLWAKEUP | Prevents sleep during event waiting. |
+-------------------------+------------------------------------------------+

.. versionadded:: 3.6
Expand Down Expand Up @@ -417,6 +417,28 @@ on bits for the fds of interest, and then afterward the whole bitmap has to be
linearly scanned again. :c:func:`!select` is *O*\ (*highest file descriptor*), while
:c:func:`!poll` is *O*\ (*number of file descriptors*).

The event masks that can be used with polling objects are combinations of the
following constants:

+--------------------+-------------------------------------------+
| Constant | Meaning |
+====================+===========================================+
| .. data:: POLLIN | There is data to read. |
+--------------------+-------------------------------------------+
| .. data:: POLLPRI | There is urgent data to read. |
+--------------------+-------------------------------------------+
| .. data:: POLLOUT | Ready for output: writing will not block. |
+--------------------+-------------------------------------------+
| .. data:: POLLERR | Error condition of some sort. |
+--------------------+-------------------------------------------+
| .. data:: POLLHUP | Hung up. |
+--------------------+-------------------------------------------+
| .. data:: POLLRDHUP| Stream socket peer closed connection, or |
| | shut down writing half of connection. |
+--------------------+-------------------------------------------+
| .. data:: POLLNVAL | Invalid request: descriptor not open. |
+--------------------+-------------------------------------------+


.. method:: poll.register(fd[, eventmask])

Expand All @@ -428,28 +450,9 @@ linearly scanned again. :c:func:`!select` is *O*\ (*highest file descriptor*), w

*eventmask* is an optional bitmask describing the type of events you want to
check for, and can be a combination of the constants :const:`POLLIN`,
:const:`POLLPRI`, and :const:`POLLOUT`, described in the table below. If not
:const:`POLLPRI`, and :const:`POLLOUT`, described in the table above. If not
specified, the default value used will check for all 3 types of events.

+-------------------+-------------------------------------------+

@StanFromIreland StanFromIreland Jun 23, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why was this moved?

@hugovk hugovk Sep 9, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@lpyu001 Please answer this question.

| Constant | Meaning |
+===================+===========================================+
| :const:`POLLIN` | There is data to read. |
+-------------------+-------------------------------------------+
| :const:`POLLPRI` | There is urgent data to read. |
+-------------------+-------------------------------------------+
| :const:`POLLOUT` | Ready for output: writing will not block. |
+-------------------+-------------------------------------------+
| :const:`POLLERR` | Error condition of some sort. |
+-------------------+-------------------------------------------+
| :const:`POLLHUP` | Hung up. |
+-------------------+-------------------------------------------+
| :const:`POLLRDHUP`| Stream socket peer closed connection, or |
| | shut down writing half of connection. |
+-------------------+-------------------------------------------+
| :const:`POLLNVAL` | Invalid request: descriptor not open. |
+-------------------+-------------------------------------------+

Registering a file descriptor that's already registered is not an error, and has
the same effect as registering the descriptor exactly once.

Expand All @@ -459,7 +462,7 @@ linearly scanned again. :c:func:`!select` is *O*\ (*highest file descriptor*), w
Modifies an already registered fd. This has the same effect as
``register(fd, eventmask)``. Attempting to modify a file descriptor
that was never registered causes an :exc:`OSError` exception with errno
:const:`ENOENT` to be raised.
:data:`~errno.ENOENT` to be raised.


.. method:: poll.unregister(fd)
Expand Down Expand Up @@ -522,9 +525,9 @@ Kqueue objects
Create a kqueue object from a given file descriptor.


.. method:: kqueue.control(changelist, max_events[, timeout]) -> eventlist
.. method:: kqueue.control(changelist, max_events[, timeout])

Low level interface to kevent
Low level interface to kevent, returning a list of events.

@StanFromIreland StanFromIreland Jun 23, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Low level interface to kevent, returning a list of events.
Low level interface to kevent, returning a list of :ref:`kevent <kevent-objects>`
objects.


- changelist must be an iterable of kevent objects or ``None``
- max_events must be 0 or a positive integer
Expand Down Expand Up @@ -562,26 +565,26 @@ https://man.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2
+---------------------------+---------------------------------------------+
| Constant | Meaning |
+===========================+=============================================+
| :const:`KQ_FILTER_READ` | Takes a descriptor and returns whenever |
| .. data:: KQ_FILTER_READ | Takes a descriptor and returns whenever |
| | there is data available to read. |
+---------------------------+---------------------------------------------+
| :const:`KQ_FILTER_WRITE` | Takes a descriptor and returns whenever |
| .. data:: KQ_FILTER_WRITE | Takes a descriptor and returns whenever |
| | there is data available to write. |
+---------------------------+---------------------------------------------+
| :const:`KQ_FILTER_AIO` | AIO requests. |
| .. data:: KQ_FILTER_AIO | AIO requests. |
+---------------------------+---------------------------------------------+
| :const:`KQ_FILTER_VNODE` | Returns when one or more of the requested |
| .. data:: KQ_FILTER_VNODE | Returns when one or more of the requested |
| | events watched in *fflag* occurs. |
+---------------------------+---------------------------------------------+
| :const:`KQ_FILTER_PROC` | Watch for events on a process ID. |
| .. data:: KQ_FILTER_PROC | Watch for events on a process ID. |
+---------------------------+---------------------------------------------+
| :const:`KQ_FILTER_NETDEV` | Watch for events on a network device |
| .. data:: KQ_FILTER_NETDEV| Watch for events on a network device |
| | (not available on macOS). |
+---------------------------+---------------------------------------------+
| :const:`KQ_FILTER_SIGNAL` | Returns whenever the watched signal is |
| .. data:: KQ_FILTER_SIGNAL| Returns whenever the watched signal is |
| | delivered to the process. |
+---------------------------+---------------------------------------------+
| :const:`KQ_FILTER_TIMER` | Establishes an arbitrary timer. |
| .. data:: KQ_FILTER_TIMER | Establishes an arbitrary timer. |
+---------------------------+---------------------------------------------+

.. attribute:: kevent.flags
Expand All @@ -591,25 +594,25 @@ https://man.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2
+---------------------------+----------------------------------------------+
| Constant | Meaning |
+===========================+==============================================+
| :const:`KQ_EV_ADD` | Adds or modifies an event. |
| .. data:: KQ_EV_ADD | Adds or modifies an event. |
+---------------------------+----------------------------------------------+
| :const:`KQ_EV_DELETE` | Removes an event from the queue. |
| .. data:: KQ_EV_DELETE | Removes an event from the queue. |
+---------------------------+----------------------------------------------+
| :const:`KQ_EV_ENABLE` | Permits control() to return the event. |
| .. data:: KQ_EV_ENABLE | Permits control() to return the event. |
+---------------------------+----------------------------------------------+
| :const:`KQ_EV_DISABLE` | Disables event. |
| .. data:: KQ_EV_DISABLE | Disables event. |
+---------------------------+----------------------------------------------+
| :const:`KQ_EV_ONESHOT` | Removes event after first occurrence. |
| .. data:: KQ_EV_ONESHOT | Removes event after first occurrence. |
+---------------------------+----------------------------------------------+
| :const:`KQ_EV_CLEAR` | Reset the state after an event is retrieved. |
| .. data:: KQ_EV_CLEAR | Reset the state after an event is retrieved. |
+---------------------------+----------------------------------------------+
| :const:`KQ_EV_SYSFLAGS` | Internal event. |
| .. data:: KQ_EV_SYSFLAGS | Internal event. |
+---------------------------+----------------------------------------------+
| :const:`KQ_EV_FLAG1` | Internal event. |
| .. data:: KQ_EV_FLAG1 | Internal event. |
+---------------------------+----------------------------------------------+
| :const:`KQ_EV_EOF` | Filter-specific EOF condition. |
| .. data:: KQ_EV_EOF | Filter-specific EOF condition. |
+---------------------------+----------------------------------------------+
| :const:`KQ_EV_ERROR` | See return values. |
| .. data:: KQ_EV_ERROR | See return values. |
+---------------------------+----------------------------------------------+


Expand All @@ -622,62 +625,62 @@ https://man.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2
+----------------------------+--------------------------------------------+
| Constant | Meaning |
+============================+============================================+
| :const:`KQ_NOTE_LOWAT` | Low water mark of a socket buffer. |
| .. data:: KQ_NOTE_LOWAT | Low water mark of a socket buffer. |

@StanFromIreland StanFromIreland Jun 23, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This one, and only this one, for some Sphinx reason, is in the attributes scope.

Image

We can work around this (here and under the other attributes) by resetting to the module scope:

.. currentmodule:: select

+----------------------------+--------------------------------------------+

:const:`KQ_FILTER_VNODE` filter flags:

+----------------------------+--------------------------------------------+
| Constant | Meaning |
+============================+============================================+
| :const:`KQ_NOTE_DELETE` | *unlink()* was called. |
| .. data:: KQ_NOTE_DELETE | *unlink()* was called. |
+----------------------------+--------------------------------------------+
| :const:`KQ_NOTE_WRITE` | A write occurred. |
| .. data:: KQ_NOTE_WRITE | A write occurred. |
+----------------------------+--------------------------------------------+
| :const:`KQ_NOTE_EXTEND` | The file was extended. |
| .. data:: KQ_NOTE_EXTEND | The file was extended. |
+----------------------------+--------------------------------------------+
| :const:`KQ_NOTE_ATTRIB` | An attribute was changed. |
| .. data:: KQ_NOTE_ATTRIB | An attribute was changed. |
+----------------------------+--------------------------------------------+
| :const:`KQ_NOTE_LINK` | The link count has changed. |
| .. data:: KQ_NOTE_LINK | The link count has changed. |
+----------------------------+--------------------------------------------+
| :const:`KQ_NOTE_RENAME` | The file was renamed. |
| .. data:: KQ_NOTE_RENAME | The file was renamed. |
+----------------------------+--------------------------------------------+
| :const:`KQ_NOTE_REVOKE` | Access to the file was revoked. |
| .. data:: KQ_NOTE_REVOKE | Access to the file was revoked. |
+----------------------------+--------------------------------------------+

:const:`KQ_FILTER_PROC` filter flags:

+----------------------------+--------------------------------------------+
| Constant | Meaning |
+============================+============================================+
| :const:`KQ_NOTE_EXIT` | The process has exited. |
| .. data:: KQ_NOTE_EXIT | The process has exited. |
+----------------------------+--------------------------------------------+
| :const:`KQ_NOTE_FORK` | The process has called *fork()*. |
| .. data:: KQ_NOTE_FORK | The process has called *fork()*. |
+----------------------------+--------------------------------------------+
| :const:`KQ_NOTE_EXEC` | The process has executed a new process. |
| .. data:: KQ_NOTE_EXEC | The process has executed a new process. |
+----------------------------+--------------------------------------------+
| :const:`KQ_NOTE_PCTRLMASK` | Internal filter flag. |
| .. data:: KQ_NOTE_PCTRLMASK| Internal filter flag. |
+----------------------------+--------------------------------------------+
| :const:`KQ_NOTE_PDATAMASK` | Internal filter flag. |
| .. data:: KQ_NOTE_PDATAMASK| Internal filter flag. |
+----------------------------+--------------------------------------------+
| :const:`KQ_NOTE_TRACK` | Follow a process across *fork()*. |
| .. data:: KQ_NOTE_TRACK | Follow a process across *fork()*. |
+----------------------------+--------------------------------------------+
| :const:`KQ_NOTE_CHILD` | Returned on the child process for |
| .. data:: KQ_NOTE_CHILD | Returned on the child process for |
| | *NOTE_TRACK*. |
+----------------------------+--------------------------------------------+
| :const:`KQ_NOTE_TRACKERR` | Unable to attach to a child. |
| .. data:: KQ_NOTE_TRACKERR | Unable to attach to a child. |
+----------------------------+--------------------------------------------+

:const:`KQ_FILTER_NETDEV` filter flags (not available on macOS):

+----------------------------+--------------------------------------------+
| Constant | Meaning |
+============================+============================================+
| :const:`KQ_NOTE_LINKUP` | Link is up. |
| .. data:: KQ_NOTE_LINKUP | Link is up. |
+----------------------------+--------------------------------------------+
| :const:`KQ_NOTE_LINKDOWN` | Link is down. |
| .. data:: KQ_NOTE_LINKDOWN | Link is down. |
+----------------------------+--------------------------------------------+
| :const:`KQ_NOTE_LINKINV` | Link state is invalid. |
| .. data:: KQ_NOTE_LINKINV | Link state is invalid. |
+----------------------------+--------------------------------------------+


Expand Down
1 change: 0 additions & 1 deletion Doc/tools/.nitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,6 @@ Doc/library/multiprocessing.rst
Doc/library/optparse.rst
Doc/library/pickletools.rst
Doc/library/pyexpat.rst
Doc/library/select.rst
Doc/library/socket.rst
Doc/library/ssl.rst
Doc/library/termios.rst
Expand Down
Loading