[Python-Dev] The socket HOWTO

["Martin v. Löwis"]

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

No, that's not what I said. I said the people actually *don't* read
the text, so they won't waste time with it. They only glance at the
text, enough to understand the examples.

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

You completely misunderstood. I didn't say that the reading the text is
pointless. I said that people don't read this text, nor any software
documentation, in particular when they are not fluent in English.

>> 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
> connect()).

I disagree. create_connection is an advanced function - you shouldn't
be using it unless you know what it is doing. As a socket tutorial,
people do have to know about connect.

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

No no no no no. Absolutely not.
a) telling people who want to learn sockets "don't learn sockets,
   learn some higher-level library" is besides the point. What do
   you tell them when they did that, and now come back to learn
   sockets?
b) telling people to use Twisted or asyncore on the server side
   if they are new to sockets is bad advice. People *first* have
   to understand sockets, and *then* can use these libraries
   and frameworks. Those libraries aren't made to be black boxes
   that work even if you don't know how - you *have* to know how
   they work inside, or else you can't productively use them.

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

I'd happily kill the entire non-blocking discussion from the tutorial
if it hurts you as much as it hurts me. I wish this non-blocking stuff
never went into Python.

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

No. In a couple of months, they'll understand sockets much better, so
they'll be able to support IPv6 easily.

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

It's not that bad. Please reconsider. People do get a lot of advise
in their lives that isn't motivated down to the root cause, and accept
advise from authority. Only if they understand what it does, they ask
why.

Regards,
Martin