[Python-Dev] The socket HOWTO

[Antoine Pitrou]

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)

Regards

Antoine.