Where is the man page of python library

M

march

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.
 
S

Steven D'Aprano

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.
 
M

march

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.




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.
 
S

Steven D'Aprano

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?
 
M

Mark Lawrence

[Fix top posting]
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, 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.
 
S

Steven D'Aprano

[Fix top posting]

While you were fixing the top posting, did you bother to trim any
unnecessary quoting? Let me scroll down and see...

.... why no, no you didn't.

I'm not a religious man, but the verse about the mote in your brother's
eye might be appropriate about now. It's one thing to make a point about
another's social faux pas, and other to make an equally big one yourself
while doing so.
 
G

Grant Edwards

Python is a volunteer effort. If the docs don't suit your requirements,
we're grateful for patches.


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.



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.



You will get an exception,

Nope. You read a value of "".
just like the Fine Manual says.

If it does say that, it needs to be fixed.

Then quit bitching and submit a patch.
 
R

rantingrick

No, I apparently just made it up.

Yes and i'll bet you've *never* just "made up" anything to scaffold
your arguments? </sarcasm>. Since this trait is one of the major
personality flaws of the deeply religious... are you *sure* your *not*
a religious man Steven? We've also seen our fair share of haughty
arrogance and sanctimoniousness from time to time. Just observations
really. Sorry, i guess I just wanted to put a big neon sign around
your mistake. Of course now we both have our eyes poked out!

In the land of the blind, the one eyed man is king! ;-)
 

Ask a Question

Want to reply to this thread or ask your own question?

You'll need to choose a username for the site, which only take a couple of moments. After that, you can post your question and our members will help you out.

Ask a Question

Members online

No members online now.

Forum statistics

Threads
473,743
Messages
2,569,478
Members
44,899
Latest member
RodneyMcAu

Latest Threads

Top