[Python-Dev] The socket HOWTO

["Martin v. Löwis"]

> I would like to suggest that we remove the socket HOWTO (currently at
> http://docs.python.org/dev/howto/sockets.html)

-1. I think there should be a Python-oriented introduction to sockets.
You may have complaints about the specific wording of the text, but
please understand that these are probably irrelevant to most
first-time readers of this text. My observation is that people actually
don't read the text that much, but instead try to imitate the examples.
So if the examples are good (and I think they are, mostly), it's of
minor relevance whether the text makes all sense the first time.

> - people who know sockets won't learn anything from it

True. People who know sockets just need to read the module
documentation. It is a beauty of the Python library design that it
exposes the API mostly as-is, so if you know Berkeley sockets,
you will be immediately familiar with Python sockets (unlike,
say, Java or .NET, where they decided to regroup the API into
classes).

> - but people who don't know sockets will probably find it clear as mud

See above - it doesn't really matter.

> (for example, what's an "INET" or "STREAM" socket?

You are probably referring to the sentence "I’m only going to talk about
INET sockets, but they account for at least 99% of the sockets in use.
And I’ll only talk about STREAM sockets" here. It's not important
to first-time readers to actually understand that, and the wording
explicitly tells them that they don't need to understand. It says
"there is more stuff, and you won't need it, and the stuff you need
is called INET and STREAM".

It's easy to fix, though, and I fixed it in f70e26452621 (explaining
that this is all about TCPv4).

> what's "select"?)

It's well explained in the section Non-blocking Sockets, isn't it?

> 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

It's a HOWTO - of course it has advise without justification. It's
not a reference documentation which only tells you what it does, but
not what the best way of putting it together is.

> ("if somewhere in those input lists of
> sockets is one which has died a nasty death, the select will fail" ->
> is that really true?

I think it is:

py> import select
py> select.select([100],[],[],0)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
select.error: (9, 'Bad file descriptor')

Of course, rather than "has died a nasty death", it could also say
"has been closed".

> 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?).

It may well be that the author didn't fully understand the problem
when writing the text, so I wouldn't mind removing this specific
paragraph.

> 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'd evaluate these two statements exactly vice versa. The first one
(non-blocking sockets are faster) is plain wrong, and the second one
("threading support in Unix varies") is arbitrary, but factually
correct :-)

I'd drop the entire "Performance" section - there is much more
to be said about socket performance than a few paragraphs of text,
and for the target audience, performance is probably no concern.

> 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.

That's easy to fix, too - c65e1a422bc3

> Not to mention that features of the "class mysocket" can be had
> using a buffered socket.makefile() instead of writing custom code.

I find it actually appropriate in the context. It illustrates a
number of important points about sockets, namely that you cannot
rely on send() and recv() to match in block size. Ultimately, people
that use the socket API *really* need to understand TCP, so it's
good to explain to them that there are issues to consider right
in the first tutorial.

Regards,
Martin