Python 1.6 alpha 1 released

[Paul Boddie]

Bjorn Pettersen wrote:
> 
> Fredrik Lundh wrote:
> >
> > Bjorn Pettersen <bjorn at roguewave.com> wrote:
> > > Just read the announcement page, and found that socket.connect() no
> > > longer takes two arguments as was previously documented.
> >
> > note that the actual reference page says that connect takes
> > just one argument, and it has done so since at least 1.4.
> 
> The reference page says connect takes address (in italics), and goes
> onto explain what it _can_ be.  I took the example to be part of the
> documentation, and specifically explaining how to use connect with the
> example's socket type.

We work in an industry where documentation often lags behind the code -
something which frequently irritates me, but then I probably do my own bit to
uphold this dubious tradition. So, when documentation is available, as it is in
this case, the developer will often breathe a sigh of relief that they will not
be obliged to read the source code, and then rely on such documentation more
than they should (as it turns out).

Socket programming, especially for anyone who tried it in C, can be daunting to
those new to the subject and it is only natural that people will make the most
out of the examples provided in order to get started. Given that the example in
the library reference (even as recently as the one provided for 1.5.2)
contradicts the supposedly correct way of calling 'connect', we can seemingly
infer that either the intention was always to support this usage of the method
in question, or that the documentation is not to be relied upon. In my
experience, systems with inadequate or inaccurate documentation suffer from a
lack of acceptance as developers fight with the "real" behaviour of the code. I
can hardly believe, though, that the purpose of the documentation is to trick
people into using the Python libraries incorrectly.

Whether or not anyone believes that examples constitute definitive
documentation, the reactions of other contributors in this thread give a useful
insight into the way people (including myself in this case) pick up assumptions
about the way things work. Personally, I tend to test my assumptions in the
interpreter and then, if they behave as anticipated, I believe my assumptions to
be valid. Perhaps this approach is quite common in the Python community, but due
to a reliance on the behaviour of possibly only one implementation of the Python
"standard" it can also be dangerous. However, it is interesting to note that
JPython 1.0.3 seems to permit multiple argument 'connect' calls as well,
although I know that JPython 1.0.3 is not exactly "current".

Paul