Improve documentation for Resource thread safety in the resources guide
Describe the issue
The multithreading section of the Resources guide states both a prohibition and a recommendation in the same paragraph (resources.rst#L214):
Resource instances are not thread safe and should not be shared across threads or processes. These special classes contain additional meta data that cannot be shared. It's recommended to create a new Resource for each thread or process
Reading it, it isn't obvious whether creating a Resource per thread is required or merely preferred. A reader who takes "recommended" at face value may conclude sharing is acceptable with care.
This came up in #1592, where a user noted the same thing and read it as ambiguous.
Some context on how the two sentences ended up together: the "recommended" phrasing is the original 2015 wording, when the section only suggested a Resource per thread. The "not thread safe and should not be shared" sentence was added later by #2848, and the earlier wording stayed as-is.
Suggested tweak, replacing "recommended" so the sentence matches the safety claim above it:
-meta data that cannot be shared. It's recommended to create a new
+meta data that cannot be shared. You must create a new
Resource for each thread or process::The same phrasing appears in the sessions guide and could be adjusted in the same pass. This is separate from botocore#2991, which covers adding guidance for boto3.client rather than the wording here.
Links
- https://boto3.amazonaws.com/v1/documentation/api/latest/guide/resources.html#multithreading-or-multiprocessing-with-resources
- https://github.com/boto/boto3/blob/develop/docs/source/guide/resources.rst#L214
- https://boto3.amazonaws.com/v1/documentation/api/latest/guide/session.html#multithreading-or-multiprocessing-with-sessions
Source: boto/boto3