[Python-Dev] The socket HOWTO (original) (raw)

"Martin v. Löwis" martin at v.loewis.de
Sun May 29 17:20:29 CEST 2011

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 "", line 1, in 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

More information about the Python-Dev mailing list