Where is the man page of python library

[Mark Lawrence]

[Fix top posting]

>
> On Jul 23, 12:07 pm, Steven D'Aprano<st... at REMOVE-THIS-
> cybersource.com.au>  wrote:
>> On Thu, 22 Jul 2010 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.