Where is the man page of python library

Fri Jul 23 03:20:03 EDT 2010

[Fix top posting]
>> On Jul 23, 12:07 pm, Steven D'Aprano<st... at REMOVE-THIS-
> cybersource.com.au> wrote:
>> On 2010年7月22日 20:18:43 -0700, march wrote:
>>> Hi, guys.
>>>>> As a regular user of python, I am often annoyed by the fact that the
>>> official python docementation is too short and too simple to satisfy my
>>> requirement.
>>>> Python is a volunteer effort. If the docs don't suit your requirements,
>> we're grateful for patches.
>>>>> While working with socket, I want to know every detail about every API.
>>> I can easilly achieve that by reading man page if the language is C. But
>>> It seems that the Python story is different.
>>>> Python is open source. Where the documentation is silent, the ultimate
>> authority is the source code. Particularly if the code is a thin wrapper
>> around the C library, which I expect (but don't know for sure) the socket
>> code will be.
>>>>> For the interface recv(), all I got is only three sentences. "
>>> Receive data from the socket. The return value is a string representing
>>> the data received. The maximum amount of data to be received at once is
>>> specified by bufsize. "
>>> http://docs.python.org/library/socket.html#socket.socket.recv
>>>>> What if the call fail?
>>>> You will get an exception, just like the page says:
>>>> All errors raise exceptions. The normal exceptions for
>> invalid argument types and out-of-memory conditions can be
>> raised; errors related to socket or address semantics raise
>> the error socket.error.
>>>>> What if the peer close the socket?
>>>> You will get an exception, just like the Fine Manual says.
>>>>> What is the
>>> difference between blocking and non-blocking socket?
>>>> Python isn't a tutor for basic programming concepts like sockets. That's
>> what Google is for :)
>>>> But having said that, the documentation does explain the difference:
>>>> In non-blocking mode, if a recv() call doesn’t find any data,
>> or if a send() call can’t immediately dispose of the data,
>> a error exception is raised; in blocking mode, the calls block
>> until they can proceed.
>>>> http://docs.python.org/library/socket.html#socket.socket.setblocking
>>>>> How could I get the errno or exception?
>>>> You get the exception the same way you get *every* exception: by catching
>> it with a try...except block. If you don't know that, you need to learn
>> the basics and not blame the documentation.
>>>> Untested, but this probably will work:
>>>> try:
>> something_involving_sockets()
>> except socket.error, e:
>> if len(e.args) == 1:
>> print "Error message is:", e.args[0]
>> else:
>> print "errno =", e.args[0]
>> print "Error message is:", e.args[1]
>>>>> All the answers are "No comment".
>>>>> I hate this documentation!
>>>> Don't blame the documentation for your failure to read it. It's true that
>> it could be improved, but most of your questions were answered by the
>> page you linked to.
>>>> --
>> Steven
>On 23/07/2010 06:24, march wrote:
 > Steven, thank you for your reply.
 >
 > It is true that I didn't read the document with enough carefulness.
 > some of my questions are answered in the page I post the link of. Some
 > are not.
 >
 > But the documentation is poor. You need to read throughout the entire
 > page, hoping to find what you need about one single API, and you might
 > fail.
 >
 > I don't think "Python is a volunteer effort" can justify the poor
 > documentation. Linux, glibc are based on volunteer effort too, and
 > they has good documentations.
 >
 > I am not blaming those volunteers who devote their precious time to
 > this language. It will be good if the python communities get more
 > people who like to write documentation.
 >
 > Anyway, thank you again.
 >
I'll be on the Python issue tracker later today. I look forward to 
seeing your first of many contributions to the "poor" Python 
documentation. Pigs might fly? :)
Kindest regards.
Mark Lawrence.