threading.local documentation should be on the net...

[ztane]

BPO	42343
Nosy	@rhettinger, @ztane, @posita

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2020-11-13.11:17:53.498>
labels = ['easy', 'type-feature', 'docs']
title = 'threading.local documentation should be on the net...'
updated_at = <Date 2022-01-27.11:56:52.582>
user = 'https://github.com/ztane'

bugs.python.org fields:

activity = <Date 2022-01-27.11:56:52.582>
actor = 'posita'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2020-11-13.11:17:53.498>
creator = 'ztane'
dependencies = []
files = []
hgrepos = []
issue_num = 42343
keywords = ['newcomer friendly']
message_count = 4.0
messages = ['380875', '380999', '411858', '411860']
nosy_count = 4.0
nosy_names = ['rhettinger', 'docs@python', 'ztane', 'posita']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue42343'
versions = []

Linked PRs

• gh-86509: docs for thread-local data - add link to _threading_local.py #101824
• [3.11] gh-86509: Add link to Lib/_threading_local.py in threading docs (GH-101824) #102575
• [3.10] gh-86509: Add link to Lib/_threading_local.py in threading docs (GH-101824) #102576

[ztane]

The current documentation of thread.local is

----
Thread-Local Data

Thread-local data is data whose values are thread specific. To manage thread-local data, just create an instance of local (or a subclass) and store attributes on it:

mydata = threading.local()
mydata.x = 1

The instance’s values will be different for separate threads.

class threading.local

A class that represents thread-local data.

For more details and extensive examples, see the documentation string of the _threading_local module.

----

There is no link to the _threading_local module docs in the documentation and none of the content from the modules docstrings appear anywhere on docs.python.org website. This is rather annoying because the docstring contains completely non-trivial information including that threading.local can be subclassed and that the init will be run once for each thread for each instance where attributes are accessed.

[rhettinger]

Would you like to make a PR to fix it?

[posita]

@rhettinger, the docstring1 alluded to in the docs is quite lengthy. Are you suggesting copying it straight across to the standard library documentation? If not, can you give (or link to) some documentation standards or other guidance on constructing a viable PR?

Also, for newcomer friendly issues, it is helpful to link to instructions on how to construct and submit a PR for review. That will increase the likelihood of a community-provided fix.

[posita]

@ztane, if you are interested in trying your hand at a PR, these will be generally useful:

• https://devguide.python.org/
• https://devguide.python.org/documenting/