Reference manual for python? [closed]

Question

Is there a recommended reference manual for python that's better than the official docs? I'm an experienced programmer (PHP, C#, javascript, and some C most recently), and I find the python manual pretty lacking compared the PHP manual and MSDN. In particular, the official docs never seem to tell me what errors can happen if I pass in something invalid, and there's apparently not a way to navigate within a module.

Take the os module for example. There's no list of constants or methods I can call on that page, so I have to Ctrl+f for "stat(" until I find it. Then, once I do find it, it doesn't tell me what to expect if I call stat with a directory that doesn't exist, so I just have to try it in a terminal and see what happens.

This seems wildly inefficient… how do python programmers deal with this?

Circumambulate

:O pretty lacking compared to PHP?! It doesn't spoon feed you sure but would never consider it lacking. Id say for the stat issue you have, make an error handler. – Chopfallen

For all the language's warts, the PHP manual is pretty great. Even in the lists of things people hate about PHP, the manual is usually praised. What is an error handler? – Circumambulate

error handler: docs.python.org/tutorial/errors.html (hate to bring you to the docs but just giving you the basic idea). – Chopfallen

Right right, so exception handling stuff. – Circumambulate

Answer 1

In practice, you either make a quick test program to check the behavior, or read the source code. Much of the Python standard library code is fairly clearly written and in fact rather self-documenting, so it's standard practice to refer to it when you need to know the nitty-gritty details of how something works.

One exception: with low-level system functions such as many of those in the os module, the functions map directly on to their C namesakes for the underlying platform. So if you need to know about the behavior of Python's stat, you look up the reference documentation for your platform's native C stat call. In these cases the Python library docs often only explain the basic purpose of the function and how it differs from its C equivalent, if at all.

Sizar

Wow, that's interesting. Are there conventions you rely on? For example, in PHP, things usually return false or null (depending on what type of function it is), so it's pretty safe to check for those two. It seems python is more exception-y? – Circumambulate

You mean conventions to tell whether a function has failed? Yep, Python functions generally raise exceptions when something goes wrong. See e.g. the note about OSError at the beginning of the os docs page. There are probably exceptions to that guideline (no pun intended), but they would be described in the documentation. – Sizar

Oh, I missed that note, that's actually more or less what I was looking for, though. – Circumambulate

Answer 2

I don't think I ever had the same feeling towards the python docs as you do but I did some times need to go out of my way some times for a better understand of how a part of python works. Though that is how most language are. Python is a quick and easy language to learn which requires less time on docs and more time programming. Also python's user base isn't as large as PHP. PHP has people constantly giving examples and details on certain functions daily.

Another great thing about python is its interactive shell to test things out. Just my idea of programming you learn more by doing then seeing. So if you're ever interested in testing something you don't need to drag through compiling, just write a quick script in the interpreter. the interpreter also has reference tools. Example dir(<identifier>) and help(<identifier>) for module, clasa or function needs.

Any way enough defending my favorite language, pyDoc is a little useful tool to help you get what you need from python.

pydoc is a tool that comes with Python that can be used for viewing and generating Python documentation.

Chopfallen