Where is the man page of python library
in [Python]
|
From: march on 22 Jul 2010 23:18 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. 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. 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? What if the peer close the socket? What is the difference between blocking and non-blocking socket? How could I get the errno or exception? All the answers are "No comment". I hate this documentation! guys, where could I turn to for help? Thanks in advance.
From: Steven D'Aprano on 23 Jul 2010 00:07 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
From: march on 23 Jul 2010 01:24 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. On Jul 23, 12:07 pm, Steven D'Aprano <st...(a)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 doesnt find any data, > or if a send() call cant 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
From: Steven D'Aprano on 23 Jul 2010 03:19 On Thu, 22 Jul 2010 22:24:39 -0700, 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. Of course the documentation can be improved. Nobody thinks it is perfect. But the Python documentation is actually pretty good compared to a lot of things out there. Perhaps you're spoilt from reading first class documentation and haven't had to struggle with fifteenth class documentation. > 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. You missed my point. Python is a volunteer effort. If you think the documentation is poor, what are YOU doing to fix that, apart from complaining? We welcome patches to the documentation. If you don't know how to write a patch file, that's okay too. What suggestions do you have for fixing the docs? If people agree that your suggestions are good, *and* they care enough to make the effort, then somebody *might* generate a bug report for it, which eventually *might* lead to somebody producing a patch. But if you want to increase the chances, you need to be active and not just an armchair critic. Write the patch. If you can't write the patch, at least raise a bug report with a suggestion for fixing it. > 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. Volunteers are welcome. The first step is to suggest an improvement to the docs, not just complain that they're not good enough. How would you fix the docs for socket.recv? -- Steven
From: Mark Lawrence on 23 Jul 2010 03:20
[Fix top posting] > > On Jul 23, 12:07 pm, Steven D'Aprano<st...(a)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. |