docs: struct: clarify struct caching behaviour

[uniq10]

BPO	42836
Nosy	@uniq10
PRs	GH-87002: fix caching documentation in struct module #24164

^{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 2021-01-06.09:05:31.865>
labels = ['3.7', '3.8', '3.9', '3.10', 'type-feature', 'docs']
title = 'docs: struct: clarify struct caching behaviour'
updated_at = <Date 2021-01-08.06:05:25.841>
user = 'https://github.com/uniq10'

bugs.python.org fields:

activity = <Date 2021-01-08.06:05:25.841>
actor = 'python-dev'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2021-01-06.09:05:31.865>
creator = 'uniq10'
dependencies = []
files = []
hgrepos = []
issue_num = 42836
keywords = ['patch']
message_count = 1.0
messages = ['384476']
nosy_count = 3.0
nosy_names = ['docs@python', 'python-dev', 'uniq10']
pr_nums = ['24164']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue42836'
versions = ['Python 3.7', 'Python 3.8', 'Python 3.9', 'Python 3.10']

Linked PRs

• [3.11] GH-87002: fix caching documentation in struct module (GH-24164) #100643
• [3.10] GH-87002: fix caching documentation in struct module (GH-24164) #100644

[uniq10]

As per docs in :https://docs.python.org/3.7/library/struct.html#struct.Struct

The compiled versions of the most recent format strings passed to Struct and the module-level functions are cached, so programs that use only a few format strings needn’t worry about reusing a single Struct instance.

This statement seems to imply that the format string passed as struct.Struct(format) is also cached. This doesn't appear to be the case.

Only format strings passed to the module level functions seems to be cached.

cache_struct_converter at https://github.com/python/cpython/blob/v3.7.7/Modules/_struct.c#L2052
appears to be used only in the top module level functions pack and pack_into and is not used in Struct.__init__.

Would it be better to change the doc to:

The compiled versions of the most recent format strings passed to the module-level functions are cached, so programs that use only a few format strings needn’t worry about reusing a single Struct instance.

This issue was introduced by 3666b3c

and is present in every version since.

Refs:
#7700
https://bugs.python.org/issue33032