classification
Title: Doc/library/traceback.rst — references to tuples should be replaced with new FrameSummary object
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.8, Python 3.7, Python 3.6
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: SilentGhost, abarry, berker.peksag, cheryl.sabella, docs@python, petr.viktorin, r.david.murray, rbcollins, torsava
Priority: normal Keywords: patch

Created on 2016-08-31 10:04 by torsava, last changed 2018-08-02 17:01 by berker.peksag. This issue is now closed.

Files
File name Uploaded Description Edit
traceback-doc.patch torsava, 2016-08-31 10:04 Patch that fixes traceback documentation to reflect the new usage of FrameSummary and StackSummary objects review
Pull Requests
URL Status Linked Edit
PR 6116 merged torsava, 2018-03-14 18:03
PR 8629 merged miss-islington, 2018-08-02 16:09
PR 8630 merged miss-islington, 2018-08-02 16:10
Messages (12)
msg274010 - (view) Author: Tomas Orsava (torsava) * Date: 2016-08-31 10:04
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
msg274011 - (view) Author: SilentGhost (SilentGhost) * (Python triager) Date: 2016-08-31 10:09
LGTM.
msg274012 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2016-08-31 10:23
I think we need to decide whether this is a documentation bug or a regression in traceback module.  See also issue 25573 for a similar report.
msg274016 - (view) Author: Tomas Orsava (torsava) * Date: 2016-08-31 11:23
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 issue 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 issue 26502.
msg275313 - (view) Author: Petr Viktorin (petr.viktorin) * (Python committer) Date: 2016-09-09 12:01
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?
msg279032 - (view) Author: Petr Viktorin (petr.viktorin) * (Python committer) Date: 2016-10-20 14:01
ping
Anything I can do to move this forward?
msg279034 - (view) Author: Anilyka Barry (abarry) * (Python triager) Date: 2016-10-20 14:18
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.
msg313793 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2018-03-13 23:02
Tomas,

Would you be willing to make a Github pull request with your patch?  Thanks.
msg313831 - (view) Author: Tomas Orsava (torsava) * Date: 2018-03-14 18:03
Hey Cheryl,
here is the pull request: https://github.com/python/cpython/pull/6116
msg322974 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2018-08-02 16:09
New changeset f394ee5eaf6d6d8f45e0478e77d4dbff25c6bea7 by Berker Peksag (torsava) in branch 'master':
bpo-27910: Update documentation of traceback module (GH-6116)
https://github.com/python/cpython/commit/f394ee5eaf6d6d8f45e0478e77d4dbff25c6bea7
msg322980 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2018-08-02 16:51
New changeset 0f9df886d6d1c6b239a2861a0ad0d56bb59e3922 by Berker Peksag (Miss Islington (bot)) in branch '3.7':
bpo-27910: Update documentation of traceback module (GH-6116)
https://github.com/python/cpython/commit/0f9df886d6d1c6b239a2861a0ad0d56bb59e3922
msg322981 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2018-08-02 17:01
New changeset 295342adbfd905d5b4a77f960ea39649df7d9997 by Berker Peksag (Miss Islington (bot)) in branch '3.6':
bpo-27910: Update documentation of traceback module (GH-6116)
https://github.com/python/cpython/commit/295342adbfd905d5b4a77f960ea39649df7d9997
History
Date User Action Args
2018-08-02 17:01:27berker.peksagsetstatus: open -> closed
stage: patch review -> resolved
resolution: fixed
versions: + Python 3.6
2018-08-02 17:01:00berker.peksagsetmessages: + msg322981
2018-08-02 16:51:51berker.peksagsetmessages: + msg322980
2018-08-02 16:10:20miss-islingtonsetpull_requests: + pull_request8135
2018-08-02 16:09:24miss-islingtonsetpull_requests: + pull_request8134
2018-08-02 16:09:02berker.peksagsetmessages: + msg322974
2018-08-02 15:57:41berker.peksaglinkissue30984 superseder
2018-03-14 18:03:55torsavasetmessages: + msg313831
2018-03-14 18:03:00torsavasetstage: needs patch -> patch review
pull_requests: + pull_request5879
2018-03-13 23:02:02cheryl.sabellasetversions: + Python 3.8, - Python 3.5, Python 3.6
nosy: + cheryl.sabella

messages: + msg313793

stage: commit review -> needs patch
2016-10-20 14:18:11abarrysetversions: + Python 3.7
nosy: + abarry

messages: + msg279034

stage: patch review -> commit review
2016-10-20 14:01:48petr.viktorinsetmessages: + msg279032
2016-09-09 12:01:43petr.viktorinsetnosy: + petr.viktorin
messages: + msg275313
2016-08-31 11:23:30torsavasetmessages: + msg274016
2016-08-31 10:23:13berker.peksagsetnosy: + rbcollins, berker.peksag, r.david.murray

messages: + msg274012
stage: commit review -> patch review
2016-08-31 10:09:00SilentGhostsetnosy: + SilentGhost

messages: + msg274011
stage: patch review -> commit review
2016-08-31 10:08:25SilentGhostsettype: behavior
stage: patch review
2016-08-31 10:04:49torsavacreate