[docs] Socket server example fails on second and sucessive runs. Please set SO_REUSEADDR flag.

[John Hall]

Problem:
The sockets example runs once because but fails on successive runs because a
socket option flag that allows the port number to be readily reused again
after the program closed is not set.
http://docs.python.org/library/socket.html#example

Solution:
insert
s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)

In between the following lines in the first example. Numbers
are approximate doc source line numbers

869  s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
870  s.bind((HOST, PORT))

and in all other server examples following socket creation prior to a call
to s.bind

Argument in favor of the change. It's confusing to figure out why the
examples run once then fail on successive runs. It's not enough to run once.
Examples should run correctly several times. Users of documentation
frequently run examples  once, then run them again with some changes and
tweaks to figure out how they work. This example is designed to confuse the
user of the documentation who then must figure out why their code fails only
to discover it's because the example as written only runs correctly
once. With an automatic bug built into the code for the second time it's run
this adds unnecessary confusion and justifies the extra line of code.

Considerable evidence of frequent user confusion can be found in forums,
blogs and websites by searching for the error message caused by the problem.

Consideration:
It may not be universally portable. It works well on Linux and according to
documentation should work on windows but I did not verify that or research
other platforms.
http://msdn.microsoft.com/en-us/library/ms740532%28v=vs.85%29.aspx
If there are platforms where this line would fail then a comment or
conditional logic may be needed.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20110419/e7cce309/attachment-0001.html>