#4828·boto3

Improve documentation for Resource thread safety in the resources guide

Author: adev-codeCreated Aug 14, 2026Updated Aug 17, 2026
Labelsbugdocumentationp3

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:

diff
-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