[Python-Dev] The socket HOWTO

Antoine Pitrou solipsis at pitrou.net
Sat Jun 4 20:50:26 CEST 2011


On Sun, 29 May 2011 17:20:29 +0200
"Martin v. Löwis" <martin at v.loewis.de> wrote:
> > 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 what you're saying is that the text is mostly useless (or at least
quite dispensable), but you think it's fine that people waste their
time trying to read it?

Some of the people reading our docs are not fluent English readers, and
it can be quite an effort for them to read some big chunk of text which
will be ultimately pointless.

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

I'm not sure why the examples are good (for example, modern client
code should probably use create_connection() with a host name, not

Also, really, to socket beginners, I think the primary advice should
be: first try to find some high-level library that does the dirty work
for you (for example some protocol-specific lib on the client side, or
something like Twisted or asyncore on the server side). Not "hey,
here's how you write a threaded server in 4 lines of code, and wow,
look, you can also write non-blocking code using select() too!".

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

Well... in a couple of months, someone will tell them their code doesn't
support IPv6 and they'll be lost.

> > what's "select"?)
> It's well explained in the section Non-blocking Sockets, isn't it?

I don't think it explains well how a non-blocking socket works.
It's very opinionated and has little useful technical content. 
EAGAIN and EWOULDBLOCK are not even mentioned!

> It's a HOWTO - of course it has advise without justification.

Well, I think that's bad. When we give advice to users, we should
explain the motivation of the advice given. Otherwise we convey the
impression that there's some magic that people shouldn't try to

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

+1. When reading it I get the idea that the OS might kill sockets in
my back, while in reality the only way a EBADF can happen is if I
explicitly close the socket - i.e. a programming error on my part.

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

+1 :)

Thank you


More information about the Python-Dev mailing list