I don't think that it would make sense to annotate *each* function in the documentation, that would require too much work. I suggest to start to annotate functions which are known to have "side effects" or are not safe whereas users can be surprised to read that they are unsafe in the context of multithreading.

For example, document that os.chdir() is "process-wide" (I'm not sure how to document it). I think that everybody agrees that it's the case, and IMHO it's an useful information. At least, one user has been surprised to read that os.umask() is process-wide:

"I would be great, if the python standard library would provide correspondig thread safe method."
https://bugs.python.org/issue35275

> One idea is that you could author a threading HOWTO document that covers atomicity, locks, queues, reentrancy, etc.  This is a thorny topic and it would be nice to have the principles and techniques collected in one place.

Yes. About the definition of atomicity, thread-safe, process-wide, etc. There is an existing example: contextlib describes "Reentrant context managers".
https://docs.python.org/dev/library/contextlib.html#reentrant-cms

> Ideally, it would include examples of what to expect in various situations.  For example, the pure python OrderedDict can be put in an inconsistent state if two threads make updates without a mutex; however, the containers implemented in C can never be broken even if they don't guarantee atomicity (i.e. a dict update making a pure python callback to __hash__ will never result in a broken dict).

This is where Python becomes obscure. Depending on the implementation, a method can be atomic or not :-/ Maybe atomicity should be documented as a "CPython implementation detail"!?

> ISTM that the docs have presumed that people using threading know what they're doing; however, we know that isn't always true ;-)

I don't understand threads and I have no idea which method are thread-safe or not. Each time, I should look at the doc, read the implementation, etc. :-)