[Python-Dev] The socket HOWTO

[Ross Lagerwall]

On Sat, 2011-05-21 at 17:07 +0200, Antoine Pitrou wrote:
> Hello,
> 
> I would like to suggest that we remove the socket HOWTO (currently at
> http://docs.python.org/dev/howto/sockets.html)
> 
> My main issue with this document is that it doesn't seem to have
> a well-defined destination:
> - people who know sockets won't learn anything from it
> - but people who don't know sockets will probably find it clear as mud
> (for example, what's an "INET" or "STREAM" socket? what's "select"?)
> 
> I have other issues, such as the style/tone it's written in. I'm sure
> the author had fun writing it but it doesn't fit well with the rest of
> the documentation. Also, the author gives a lot of "advice" without
> explaining or justifying it ("if somewhere in those input lists of
> sockets is one which has died a nasty death, the select will fail" ->
> is that really true? what is a "nasty death" and how is that supposed to
> happen? couldn't the author have put a 3-line example to demonstrate
> this supposed drawback and how it manifests?).
> 
> And, finally, many statements seem arbitrary ("There’s no question that
> the fastest sockets code uses non-blocking sockets and select to
> multiplex them") or plain wrong ("threading support in Unixes varies
> both in API and quality. So the normal Unix solution is to fork a
> subprocess to deal with each connection"). I don't think giving
> misleading advice to users is really a good idea. And suggesting
> beginners they use non-blocking sockets without even *showing* how (or
> pointing to asyncore or Twisted) is a very bad idea. select() is not
> enough, you still have to be prepared to get EAGAIN or EWOULDBLOCK when
> calling recv() or send() (i.e. select() can give false positives).
> 
> Oh and I think it's obsolete too, because the "class mysocket"
> concatenates the output of recv() with a str rather than a bytes
> object. Not to mention that features of the "class mysocket" can be had
> using a buffered socket.makefile() instead of writing custom code.
> 
> (followed up from http://bugs.python.org/issue12126 at Eli's request)

While I agree with most of what you said, I actually did find it very
useful when first learning sockets.
It's in the top page on google for "socket programming" or "socket how
to". Also, it hinted at some concepts that could then be googled for
more information like select, nonblocking sockets, etc.

However, I would agree that this should be moved out of the
documentation and as suggested in the issue, into the wiki.