Where to find documentation to python's library's inner workings

Question

Couldn't think of a better wording for the title. See for instance the answer to http://stackoverflow.com/questions/1564501/add-timeout-argument-to-pythons-queue-join

The answer to that question uses an attribute of the Queue class called all_tasks_done (accidentally wrote join_with_timeout here in the original post).

However, in http://docs.python.org/library/queue.html#module-Queue that attribute is never mentioned. Where can someone who wants, for instance, to subclass Queue could find the documentation of the inner workings, other than reading the source code?

EDIT: A lot of answers to this question state that it's best to just read the source. I'll try to explain my problem(s) with that:

1. As much as I love python, it is still not a natural language, and reading english is easier than reading source code
2. It is hard to infer some things from the source by itself, for instance something as "this variable must be locked before any calls to get() or put()". If the variable is commented then I am once again reading english and not the source code, so why not put it in the documentation document and not just in the source?
3. (this is the most important reason IMO) It seems the decision what should be in the documentation and what shouldn't are made almost arbitrarily - can you really give me a good reason to why all_tasks_done shouldn't be mentioned?

Answer 1

I know you said you don't want to read the source code, but why not? it:

• Looks straightforward to understand;
• Is the definitive reference for how Queue works.

In the example you gave (subclassing Queue), you shouldn't need to know the internal workings anyway. What if they change? Your subclass of Queue may end up breaking even though neither the interface nor observable behaviour of Queue has changed.

Answer 2

This problem isn't unique to just the Python library. It's often worth looking at the source if you have read the docs and are still stuck

Answer 3

Use the source, Luke.

Answer 4

I'm looking at Alex Martelli's Python in a Nutshell (2nd edition). On page 344 is section "Customizing Class Queue by Subclassing". Just a couple of paragraphs, but it doesn't mention anything about how to do "join_with_timeout".

I also checked the Python Cookbook -- nothing there either on "all_tasks_done" of the Queue module.

In general, those two are good places to check if you're doing something special with builtin classes or modules.

But I believe that subclassing is the problem here. It depends on the implementation details of the superclass. If you look in the other thread that you mentioned, someone has come up with a solution that doesn't involve subclassing. That solution seems correct to me.