`structseq_repr` mislabels unnamed `PyStructSequence` fields (e.g. `os.stat_result` slots 7–9)

[XuehaiPan]

Bug report

Bug description:

structseq_repr() indexes tp_members by visible sequence position, but tp_members is built with every PyStructSequence_UnnamedField entry skipped (packed). As a result, every visible slot at or after the first unnamed field is labeled with the name of a later (hidden) field. For os.stat_result, the unnamed integer time slots 7–9 borrow the names of the hidden st_atime/st_mtime/st_ctime float fields.

---

Real-world case — a plain os.stat(). The repr prints st_atime=<integer seconds>, but the st_atime attribute is the float with sub-second precision — they are different fields:

>>> import os
>>> st = os.stat(os.curdir)
>>> st
os.stat_result(st_mode=16877, st_ino=1367263, st_dev=16777232, st_nlink=43,
               st_uid=501, st_gid=20, st_size=1376,
               st_atime=1784619363, st_mtime=1784619363, st_ctime=1784619363)
>>> st[7]           # sequence slot 7 — the integer atime
1784619363
>>> st.st_atime     # the .st_atime attribute — a different, hidden float field
1784619363.4590902

Synthetic case, isolating the mechanism with distinct values per field:

>>> # The repr always labels sequence slot 7 "st_atime", printing slot 7's value:
>>> st = os.stat_result(range(22))
>>> st
os.stat_result(st_mode=0, st_ino=1, st_dev=2, st_nlink=3, st_uid=4, st_gid=5,
               st_size=6, st_atime=7, st_mtime=8, st_ctime=9)
>>> st[7]
7

>>> # But the .st_atime ATTRIBUTE is the hidden field at index 10:
>>> st.st_atime  # field 10 supplied  -> 10
10  # surprise! differs from the repr above

>>> os.stat_result(range(11)).st_atime  # field 10 supplied  -> 10
10
>>> os.stat_result(range(10)).st_atime  # field 10 NOT supplied -> falls back to slot 7 -> 7
7  # surprise!

>>> os.stat_result.n_sequence_fields, os.stat_result.n_unnamed_fields
(10, 3)
>>> os.stat_result.__match_args__       # correctly excludes the 3 unnamed slots
('st_mode', 'st_ino', 'st_dev', 'st_nlink', 'st_uid', 'st_gid', 'st_size')

The mislabel is easy to miss: when only the 10 sequence fields are supplied (range(10)), the hidden float st_atime (index 10) is unset and derives from the integer slot 7, so the repr and the attribute coincidentally agree. Supplying field 10 (range(11) or more, or a real os.stat()) makes them disagree.

CPython versions tested on:

3.14

Operating systems tested on:

macOS

Linked PRs

• gh-154387: Fix structseq_repr mislabeling of unnamed PyStructSequence fields #154434

[picnixz]

I'm not sure yyou're meant to actually access the fields by index. I think we had a discussion in the past about that for some sys but I don't remember well. And for os.stat_result, don't you need to use os.<attr>(res)?

cc @vstinner

[XuehaiPan]

I'm not sure you're meant to actually access the fields by index.

structseq is a subtype of tuple. So it can be unpacked like:

seq = some_c_function(...)
x, y, z = seq

Here is a real-world example:

>>> import torch

>>> seq = torch.sort(torch.tensor([3, 2, 1]))
>>> seq
torch.return_types.sort(
values=tensor([1, 2, 3]),
indices=tensor([2, 1, 0]))

>>> values, indices = seq  # tuple unpack
>>> values
tensor([1, 2, 3])
>>> indices
tensor([2, 1, 0])

>>> seq.values             # access by name
tensor([1, 2, 3])
>>> seq.indices
tensor([2, 1, 0])

Users can access members implicitly by indices.

Although structseq_repr's is not valid for eval(repr(seq)) -> seq. See:

• Enhance Object/structseq.c to match namedtuple and tuple api #46145 (comment)

Users will still be surprised when getting non-obvious results from the repr in the REPL/Notebook (for debugging):

>>> st = os.stat_result(range(22))
>>> st
os.stat_result(st_mode=0, st_ino=1, st_dev=2, st_nlink=3, st_uid=4, st_gid=5,
               st_size=6, st_atime=7, st_mtime=8, st_ctime=9)
>>> st[7]
7
# Inconsistency 1: repr vs. access by .name
>>> st.st_atime
10

# Inconsistency 2: result is different when accessed by the same name
>>> os.stat_result(range(11)).st_atime
10
>>> os.stat_result(range(10)).st_atime
7

The correct repr in my mind for the unnamed fields would be like option 1:

# Current: shift and show the following field name
os.stat_result(st_mode=0, st_ino=1, st_dev=2, st_nlink=3, st_uid=4, st_gid=5,
               st_size=6, st_atime=7, st_mtime=8, st_ctime=9)

# Option 1: show as `<unnamed field>`
os.stat_result(st_mode=0, st_ino=1, st_dev=2, st_nlink=3, st_uid=4, st_gid=5,
               st_size=6, <unnamed field>=7, <unnamed field>=8, <unnamed field>=9)

# Option 2: omit the values completely in repr
os.stat_result(st_mode=0, st_ino=1, st_dev=2, st_nlink=3, st_uid=4, st_gid=5,
               st_size=6)
# This does not show the values that can be read from `tuple` unpacking.
>>> tuple(st)
(0, 1, 2, 3, 4, 5, 6, 7, 8, 9)

Use <xxx> to represent the synthetic content like (lambda _: None).__name__ -> '<lambda>'. It also allows us to show every value in the repr that we can read from tuple unpacking.

---

And for os.stat_result, don't you need to use os.<attr>(res)?

I only take os.stat_result as an example here. Since PyStructSequence related APIs are stable, there can be potential usage of PyStructSequence_UnnamedField in the wild, not only in the CPython core.

[pranavchoudhary-tech]

Hi! I was looking for an issue to contribute to and this looks like a great one to tackle. Since no one else seems to be working on it right now, I'd love to take a crack at fixing the structseq_repr indexing logic. I'll open a PR shortly!

[picnixz]

Supplying field 10 (range(11) or more, or a real os.stat()) makes them disagree.

I think there are multiple issues at hand:

• What should we do if we provide more fields than necessary? there are "hidden" fields, but should those hidden fields be considered as valid in this case?
• If we want to allow those hidden fields to be initialized and agree with the __repr__, I wonder whether we can recover the name. The PR I closed had them unnamed which would make the __repr__ weird.
• I do appreciate the <unamed field> format but I think it's too verbose. Instead, we could have [index]=... ([7]=...) or <index>=... (<7>=...) or @${index}=... (@7=...).
• Should we... really have those fields un-named in the case of os.stat_result. ISTM that those fields are good enough to be named (separate issue)
• I'm surprised that we can add more fields than necessary in the constructor (whether they are incorrectly named or not). It looks like a bug to me (it's as if you're trying to fit 12 elements in a 10-tuple)

[XuehaiPan]

I'm surprised that we can add more fields than necessary in the constructor (whether they are incorrectly named or not). It looks like a bug to me (it's as if you're trying to fit 12 elements in a 10-tuple)

I think it is intentional that a structseq holds more elements than structseq.n_sequence_fields (for os.stat_result is 10). We have kept os.stat_result.n_sequence_fields = 10 stable for 16 years, while os.stat_result.n_fields and the members accessible via .name have continued to grow. os.stat_result.n_fields is different between Python versions and platforms.

BTW, the __new__ definition is __new__(cls, sequence: Iterable[Any], dict: Dict[str, Any] = ...) -> Self (see #46145 (comment)). The extra fields (index >= n_sequence_fields) are filled with extra values from sequence or dict:

>>> import os

>>> os.stat_result.n_fields
22
>>> os.stat_result.n_sequence_fields
10
>>> os.stat_result.n_unnamed_fields
3

>>> os.stat_result(range(10)).st_atime
7
>>> os.stat_result(range(11)).st_atime
10
>>> os.stat_result(range(10), {'st_atime': -1}).st_atime
-1
>>> os.stat_result(range(11), {'st_atime': -1}).st_atime
TypeError: os.stat_result() got duplicate or unexpected field name(s)

[picnixz]

>>> os.stat_result.n_fields
22

Oh, so the range(22) was ok. I thought it was less than that. But I checked:

>>> os.stat_result(range(30))
Traceback (most recent call last):
  File "<python-input-1>", line 1, in <module>
    os.stat_result(range(30))
    ~~~~~~~~~~~~~~^^^^^^^^^^^
TypeError: os.stat_result() takes an at most 19-sequence (30-sequence given)

Ok so, this wsa expected.