Skip to content

Clarify chaining exceptions in tutorial/errors.rst #86345

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
greatvovan mannequin opened this issue Oct 28, 2020 · 15 comments
Closed

Clarify chaining exceptions in tutorial/errors.rst #86345

greatvovan mannequin opened this issue Oct 28, 2020 · 15 comments
Labels
3.9 only security fixes 3.10 only security fixes docs Documentation in the Doc dir

Comments

@greatvovan
Copy link
Mannequin

greatvovan mannequin commented Oct 28, 2020

BPO 42179
Nosy @rhettinger, @merwok, @methane, @maxking, @willingc, @miss-islington, @greatvovan
PRs
  • bpo-42179: Clarify exception chaining #23160
  • bpo-42179: Doc/tutorial: Remove mention of __cause__ #23162
  • [3.9] bpo-42179: Doc/tutorial: Remove mention of __cause__ (GH-23162) #23173
  • 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 2021-01-06.23:37:55.313>
    created_at = <Date 2020-10-28.08:31:31.868>
    labels = ['3.9', '3.10', 'docs']
    title = 'Clarify chaining exceptions in tutorial/errors.rst'
    updated_at = <Date 2021-01-06.23:37:55.311>
    user = 'https://github.com/greatvovan'

    bugs.python.org fields:

    activity = <Date 2021-01-06.23:37:55.311>
    actor = 'Vladimir Ryabtsev'
    assignee = 'docs@python'
    closed = True
    closed_date = <Date 2021-01-06.23:37:55.313>
    closer = 'Vladimir Ryabtsev'
    components = ['Documentation']
    creation = <Date 2020-10-28.08:31:31.868>
    creator = 'Vladimir Ryabtsev'
    dependencies = []
    files = []
    hgrepos = []
    issue_num = 42179
    keywords = ['patch']
    message_count = 15.0
    messages = ['379823', '380394', '380396', '380397', '380425', '380432', '380434', '380435', '380436', '380440', '380441', '380570', '380607', '383114', '384542']
    nosy_count = 8.0
    nosy_names = ['rhettinger', 'eric.araujo', 'methane', 'docs@python', 'maxking', 'willingc', 'miss-islington', 'Vladimir Ryabtsev']
    pr_nums = ['23160', '23162', '23173']
    priority = 'normal'
    resolution = 'wont fix'
    stage = 'resolved'
    status = 'closed'
    superseder = None
    type = None
    url = 'https://bugs.python.org/issue42179'
    versions = ['Python 3.9', 'Python 3.10']

    @greatvovan
    Copy link
    Mannequin Author

    greatvovan mannequin commented Oct 28, 2020

    A new section has been added to the page as a result of https://bugs.python.org/issue37826. The change: dcfe111

    The wording it uses (in the beginning of section 8.5), defines chaining as setting __cause__ attribute in an exception, and later states that "Exception chaining happens automatically when an exception is raised inside an exception handler or finally section". This may lead the reader to a wrong idea that re-raising an exception without "from" in "except" and "finally" automatically sets __cause__. In reality it sets only __context__ attribute, which is similar concept to __cause__, but work a bit differently, as explained in library/exceptions.rst. I suggest to mention that difference and provide a link to the main article.

    @greatvovan greatvovan mannequin added 3.9 only security fixes 3.10 only security fixes labels Oct 28, 2020
    @greatvovan greatvovan mannequin assigned docspython Oct 28, 2020
    @greatvovan greatvovan mannequin added docs Documentation in the Doc dir 3.9 only security fixes 3.10 only security fixes labels Oct 28, 2020
    @greatvovan greatvovan mannequin assigned docspython Oct 28, 2020
    @greatvovan greatvovan mannequin added the docs Documentation in the Doc dir label Oct 28, 2020
    @methane
    Copy link
    Member

    methane commented Nov 5, 2020

    Please note that tutorial is a tutorial. It is document to help new user who are learning Python.
    Do you believe special attributes like __cause__ and __contexts__ are really worth to teach for tutorial readers?

    Generally speaking, I think we should *reduce* some details from tutorial.

    @greatvovan
    Copy link
    Mannequin Author

    greatvovan mannequin commented Nov 5, 2020

    1. Such understanding of a tutorial is debatable. Tutorial is just a material for learning written with some system in mind, which is more interesting to read than dry reference material. A tutorial, generally dpeaking, may be both for beginners and for professionals.

    2. The question about exception chaining is popular on Stackoverflow in people who came to Python with Java or C# background (see “python inner exception”).

    3. Whatever material is given, it should not cause confusion, but now it does. Since this section has been added recently, it is better to fix it rather than remove entirely, aren’t you agree?

    @methane
    Copy link
    Member

    methane commented Nov 5, 2020

    1. Such understanding of a tutorial is debatable. Tutorial is just a material for learning written with some system in mind, which is more interesting to read than dry reference material. A tutorial, generally dpeaking, may be both for beginners and for professionals.

    OK, I will send this topic to python-dev first.

    1. The question about exception chaining is popular on Stackoverflow in people who came to Python with Java or C# background (see “python inner exception”).
    2. Whatever material is given, it should not cause confusion, but now it does.

    I searched it but I can not find confusion caused by this tutorial section. Please write a concrete URL caused by current tutorial?

    Since this section has been added recently, it is better to fix it rather than remove entirely, aren’t you agree?

    I prefer removing mention to __cause__, instead of adding mention to __context__.

    No need to remove entire section. We can introduce high level overview of context chaining. Describing the default behavior and "from None" is enough for new users.

    @greatvovan
    Copy link
    Mannequin Author

    greatvovan mannequin commented Nov 5, 2020

    I can not find confusion caused by this tutorial section

    Inada, have you read the very first message in this ticket? It explains why this wording may cause confusion (and it did in me), and describes the problem part. A link for your convenience: https://docs.python.org/3/tutorial/errors.html#exception-chaining

    Describing the default behavior and "from None" is enough for new users

    Strange that you think that "from None" is more useful for beginners than these special attributes.

    Without understanding of __cause__ and __context__, stack traceback message looks like magic. Say you want to handle an exception and retrieve its cause (context) in runtime (this is what exception chaining for) – this section makes no clues about how to do that.

    @merwok
    Copy link
    Member

    merwok commented Nov 5, 2020

    I prefer the patch by Inada-san!

    > Describing the default behavior and "from None" is enough for new users
    Strange that you think that "from None" is more useful for beginners than these special attributes.

    Doesn’t feel strange to me: raise Exc from exc or from None shows how to use the mecanism, whereas the special attributes are about the implementation. A tutorial can show how to use language features like for loops or with statements, but shouldn’t explain how to implement the protocols, that’s too much detail if you’re just starting to learn programming.

    @greatvovan
    Copy link
    Mannequin Author

    greatvovan mannequin commented Nov 5, 2020

    We have automatic chaining, so you don't need to use "from X" unless you want to have some control on the traceback message. Even without knowing of this syntax (and without using "from exc"), a user will get a traceback message similar to what is shown in the example. What is the purpose of the entire section then?

    As I see it, the purpose might be providing some details about how exactly chaining works, so a user: a) could make an informed decision whether they need "from X" or not, b) would know how to retrieve the linked exception programmatically.

    I generally feel that we don't want to deprive a user from special attributes, in Python they are everywhere, you cannot even construct a class instance without __init__().

    @greatvovan
    Copy link
    Mannequin Author

    greatvovan mannequin commented Nov 5, 2020

    Also, the choice of the exception type in the example looks not very apt: you raise "IOError" but the traceback message says "OSError" (which is due to strange design decision "IOError = OSError"). For the tutorial, I would choose an exception that does not disguise as another exception.

    @willingc
    Copy link
    Contributor

    willingc commented Nov 5, 2020

    Thanks Vladimir for raising the issue, and Inada-san and Eric for following up on it.

    I recommend the following:

    • merge PR-23162 including its reference to builtin exceptions
    • after merge of PR-23162, reworking PR-23160 to provide a brief note about __cause__ and __contex__ before the reference link to builtin exceptions

    This would provide a clear tutorial example for the majority of users. For the fraction of users, like Vladimir, a sentence as part of the reference link could address a bit more about __cause__ and __context__ without confusing folks.

    @methane
    Copy link
    Member

    methane commented Nov 6, 2020

    New changeset bde33e4 by Inada Naoki in branch 'master':
    bpo-42179: Doc/tutorial: Remove mention of __cause__ (GH-23162)
    bde33e4

    @miss-islington
    Copy link
    Contributor

    New changeset e74fb2d by Miss Islington (bot) in branch '3.9':
    bpo-42179: Doc/tutorial: Remove mention of __cause__ (GH-23162)
    e74fb2d

    @methane
    Copy link
    Member

    methane commented Nov 9, 2020

    > 1. Such understanding of a tutorial is debatable. Tutorial is just a material for learning written with some system in mind, which is more interesting to read than dry reference material. A tutorial, generally dpeaking, may be both for beginners and for professionals.

    OK, I will send this topic to python-dev first.

    For the record, there is a long thread in python-dev about this issue:

    ## High level discussion: focus on new user vs write more and more details.

    More detail:

    • Abdur-Rahmaan Janhangeer

    Focus on new user:

    • Paul Moore
    • Brett Cannon
    • Guido van Rossum
    • Kyle Stanley
    • Carol Willing
    • Serhiy Storchaka

    ## About this specific case. (Adding __context__ and __suppress_context vs removing __cause__)

    Add __context__:
    (no one)

    Remove __cause__:

    Riccardo Polignieri asked that to be very careful about removing something, but he did not vote for adding __context__ and __supress_context__.

    --

    I merged PR-23162 for keep focus on new users and consistent for now.

    But I have not closed this issue yet because documentation WG may revisit the issue. (see https://mail.python.org/archives/list/python-dev@python.org/message/IWW2YBLJK4T3OWSKDUDVDVXPWDGIFWTC/ ).

    @greatvovan
    Copy link
    Mannequin Author

    greatvovan mannequin commented Nov 9, 2020

    All right, you won. I hope beginner users will be happy :)

    I removed my proposal paragraph about __cause__ and __context__ and kept only changes about exception type (https://bugs.python.org/issue42179#msg380435).

    @willingc
    Copy link
    Contributor

    New changeset 3f9fe23 by Vladimir in branch 'master':
    bpo-42179: Clarify exception chaining (GH-23160)
    3f9fe23

    @greatvovan
    Copy link
    Mannequin Author

    greatvovan mannequin commented Jan 6, 2021

    The issue won't be fixed, but other useful changes applied.

    @greatvovan greatvovan mannequin closed this as completed Jan 6, 2021
    @greatvovan greatvovan mannequin closed this as completed Jan 6, 2021
    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Labels
    3.9 only security fixes 3.10 only security fixes docs Documentation in the Doc dir
    Projects
    None yet
    Development

    No branches or pull requests

    4 participants