Documentation

Near the end of the documentation of the _thread module there is a list of caveats. It looks like it was written a long time ago and some of its items seem no longer accurate...

We can read that:

• [in the first bullet point]

  Threads interact strangely with interrupts: the KeyboardInterrupt exception will be received by an arbitrary thread. (When the signal module is available, interrupts always go to the main thread.)

  whereas it seems that nowadays we could replace that text with a much simpler statement:

  Interrupts always go to the main thread (the KeyboardInterrupt exception will be received by that thread).

• [in the last bullet point]

  When the main thread exits, it does not do any of its usual cleanup (except that try … finally clauses are honored), and the standard I/O files are not flushed.

  whereas it seems just not true anymore. I believe this bullet point should be removed entirely.

Here, I address a request to a core developer who is an expert in threading to confirm or correct my change suggestions presented above. [EDIT: see the related PR]

See also: https://discuss.python.org/t/are-all-descriptions-of-the-caveats-listed-near-the-end-of-thread-modules-docs-up-to-date/55261/18 (this response by @eryksun is concise and clear, so I suggest TL;DR-readers to focus on it – as some other parts of that discussion thread are not well focused on the questions from the original post).

Linked PRs

• gh-125025: _thread docs: fix/update the *caveats* list #125026
• [3.12] gh-125025: _thread docs: fix/update the *caveats* list (GH-125026) #125031
• [3.13] gh-125025: _thread docs: fix/update the *caveats* list (GH-125026) #125032