struct's docstring implies alignment is always performed

[eli-b]

BPO	32853
Nosy	@eli-b

^{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 2018-02-15.16:52:04.289>
labels = ['type-bug', '3.8', 'docs']
title = "struct's docstring implies alignment is always performed"
updated_at = <Date 2018-02-15.16:52:04.289>
user = 'https://github.com/eli-b'

bugs.python.org fields:

activity = <Date 2018-02-15.16:52:04.289>
actor = 'Eli_B'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2018-02-15.16:52:04.289>
creator = 'Eli_B'
dependencies = []
files = []
hgrepos = []
issue_num = 32853
keywords = []
message_count = 1.0
messages = ['312214']
nosy_count = 2.0
nosy_names = ['docs@python', 'Eli_B']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue32853'
versions = ['Python 3.8']

Linked PRs

• gh-77034: Update struct docstring, slashing most of it #107003

[eli-b]

In module struct's docstring, it says:
"...
The optional first format char indicates byte order, size and alignment:\n
@: native order, size & alignment (default)\n
=: native order, std. size & alignment\n
<: little-endian, std. size & alignment\n
>: big-endian, std. size & alignment\n
!: same as >\n
..."
The wording sounds like either native or standard alignment is performed, regardless of the optional first format char.

In comparison, the table in https://docs.python.org/3.8/library/struct.html#byte-order-size-and-alignment states that in all modes other than the default, no alignment is performed. This is the actual behavior of the module.

[iritkatriel]

@mdickinson which is correct, the documentation or the docstring?

[mdickinson]

@iritkatriel The online docs are right here. We've been using the phrase "standard size and alignment" to mean "standard sizes and no implicitly added padding" - i.e., "standard alignment" means "no alignment". I think that's mostly clear from the surrounding context when looking at docs.python.org, but agree that it's far from clear when just looking at the docstring.

How about simply replacing std. size & alignment with std. size, no alignment everywhere in the docstring?

[mdickinson]

@smontanaro: do you have opinions on how best to rewrite the docstrings, given your recent improvements to the online docs?

[smontanaro]

Not off the top of my head @mdickinson. Let me review the docs and docstrings and get back to you...