Doc/library/traceback.rst — references to tuples should be replaced with new FrameSummary object

[torsava]

BPO	27910
Nosy	@rbtcollins, @bitdancer, @encukou, @berkerpeksag, @Vgr255, @torsava, @csabella
PRs	bpo-27910: Update documentation of the traceback module #6116 [3.7] bpo-27910: Update documentation of traceback module (GH-6116) #8629 [3.6] bpo-27910: Update documentation of traceback module (GH-6116) #8630
Files	traceback-doc.patch: Patch that fixes traceback documentation to reflect the new usage of FrameSummary and StackSummary objects

^{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 = <Date 2018-08-02.17:01:27.982>
created_at = <Date 2016-08-31.10:04:49.045>
labels = ['3.8', 'type-bug', '3.7', 'docs']
title = 'Doc/library/traceback.rst \xe2\x80\x94 references to tuples should be replaced with new FrameSummary object'
updated_at = <Date 2018-08-02.17:01:27.980>
user = 'https://github.com/torsava'

bugs.python.org fields:

activity = <Date 2018-08-02.17:01:27.980>
actor = 'berker.peksag'
assignee = 'docs@python'
closed = True
closed_date = <Date 2018-08-02.17:01:27.982>
closer = 'berker.peksag'
components = ['Documentation']
creation = <Date 2016-08-31.10:04:49.045>
creator = 'torsava'
dependencies = []
files = ['44293']
hgrepos = []
issue_num = 27910
keywords = ['patch']
message_count = 12.0
messages = ['274010', '274011', '274012', '274016', '275313', '279032', '279034', '313793', '313831', '322974', '322980', '322981']
nosy_count = 9.0
nosy_names = ['rbcollins', 'r.david.murray', 'petr.viktorin', 'SilentGhost', 'docs@python', 'berker.peksag', 'abarry', 'torsava', 'cheryl.sabella']
pr_nums = ['6116', '8629', '8630']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue27910'
versions = ['Python 3.6', 'Python 3.7', 'Python 3.8']

[torsava]

In the documentation for the traceback module, the definitions of functions extract_tb [0], format_list [1] and classmethod from_list [2] mention the old style (4-)tuples that these functions used to return or accept.

Since Python 3.5, however, they return or accept a FrameSummary object instead of the 4-tuple, or a StackSummary object instead of a list of 4-tuples.

I'm including a patch that fixes these definitions to make them reflect the new reality.

[0] https://docs.python.org/3.6/library/traceback.html#traceback.extract_tb
[1] https://docs.python.org/3.6/library/traceback.html#traceback.format_list
[2] https://docs.python.org/3.6/library/traceback.html#traceback.StackSummary.from_list

[SilentGhost]

LGTM.

[berkerpeksag]

I think we need to decide whether this is a documentation bug or a regression in traceback module. See also bpo-25573 for a similar report.

[torsava]

Hi Berker: It's a bit complicated—this specific issue I opened isn't a regression, because it's exactly the change that was intended: Use FrameSummary instead of a 4-tuple to pass the frame data.

If you see the last comment for the bpo-25573 you linked to, that issue has already been resolved by the docs being updated to reflect the new way of passing data.

However, that is not to say there can't be regressions connected to this, but they have to do with the fact that FrameSummary implements only a subset of methods available of tuples. E.g. that FrameSummary does not implement __len__ like tuple does, see bpo-26502.

[encukou]

This was a deliberate change in 3.5.

Issue: https://bugs.python.org/issue17911
News entry: https://docs.python.org/3/whatsnew/3.5.html#traceback

Why do you think it is a regression?
Who would be the person that can decide if it is a doc bug or regression?

[encukou]

ping
Anything I can do to move this forward?

[Vgr255]

This is not a regression, the documentation was just not fully updated when the new feature was added. Patch looks good. This should probably be applied to the 3.5 branch as well.

[csabella]

Tomas,

Would you be willing to make a Github pull request with your patch? Thanks.

[torsava]

Hey Cheryl,
here is the pull request: #6116

[berkerpeksag]

New changeset f394ee5 by Berker Peksag (torsava) in branch 'master':
bpo-27910: Update documentation of traceback module (GH-6116)
f394ee5

[berkerpeksag]

New changeset 0f9df88 by Berker Peksag (Miss Islington (bot)) in branch '3.7':
bpo-27910: Update documentation of traceback module (GH-6116)
0f9df88

[berkerpeksag]

New changeset 295342a by Berker Peksag (Miss Islington (bot)) in branch '3.6':
bpo-27910: Update documentation of traceback module (GH-6116)
295342a