[New-bugs-announce] [issue45787] HOWTO for socket programming and select documentation contradict

[Alex Waygood]

New submission from Alex Waygood <Alex.Waygood at Gmail.com>:

The HOWTO for socket programming in Python (https://docs.python.org/3/howto/sockets.html#non-blocking sockets) includes the following lines (using triple-quotes here to indicate multiline quotes from the docs):

"""
The major mechanical difference [between blocking and non-blocking sockets] is that [for non-blocking sockets] send, recv, connect and accept can return without having done anything. You have (of course) a number of choices. You can check return code and error codes and generally drive yourself crazy. If you don’t believe me, try it sometime. Your app will grow large, buggy and suck CPU. So let’s skip the brain-dead solutions and do it right.

Use select.
"""

However, if you go to the documentation for the select module (https://docs.python.org/3/library/select html), it pointedly tells you at the top *not* to do exactly what the socket HOWTO tells you to do:

"""
Note The selectors module allows high-level and efficient I/O multiplexing, built upon the select module primitives. Users are encouraged to use the selectors module instead, unless they want precise control over the OS-level primitives used.
"""

----------
assignee: docs at python
components: Documentation
messages: 406167
nosy: AlexWaygood, docs at python, giampaolo.rodola, neologix
priority: normal
severity: normal
status: open
title: HOWTO for socket programming and select documentation contradict
type: behavior
versions: Python 3.10, Python 3.11, Python 3.9

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue45787>
_______________________________________