Skip to content
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

[docs] Document that SyntaxError's offsets are 1-indexed #87871

Closed
ammaraskar opened this issue Apr 2, 2021 · 6 comments
Closed

[docs] Document that SyntaxError's offsets are 1-indexed #87871

ammaraskar opened this issue Apr 2, 2021 · 6 comments
Labels
3.9 only security fixes docs Documentation in the Doc dir type-feature A feature request or enhancement

Comments

@ammaraskar
Copy link
Member

BPO 43705
Nosy @gvanrossum, @terryjreedy, @ammaraskar
PRs
  • bpo-43705: Document that SyntaxError's offsets are 1-indexed #25153
  • [3.9] bpo-43705: Document that SyntaxError's offsets are 1-indexed (GH-25153) #25155
  • [3.8] bpo-43705: Document that SyntaxError's offsets are 1-indexed (GH-25153) #25156
  • 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-04-03.18:08:51.943>
    created_at = <Date 2021-04-02.16:32:20.847>
    labels = ['type-feature', '3.9', 'docs']
    title = "[docs] Document that SyntaxError's offsets are 1-indexed"
    updated_at = <Date 2021-04-03.18:08:51.942>
    user = 'https://github.com/ammaraskar'

    bugs.python.org fields:

    activity = <Date 2021-04-03.18:08:51.942>
    actor = 'ammar2'
    assignee = 'docs@python'
    closed = True
    closed_date = <Date 2021-04-03.18:08:51.943>
    closer = 'ammar2'
    components = ['Documentation']
    creation = <Date 2021-04-02.16:32:20.847>
    creator = 'ammar2'
    dependencies = []
    files = []
    hgrepos = []
    issue_num = 43705
    keywords = ['patch']
    message_count = 6.0
    messages = ['390081', '390102', '390106', '390107', '390111', '390133']
    nosy_count = 4.0
    nosy_names = ['gvanrossum', 'terry.reedy', 'docs@python', 'ammar2']
    pr_nums = ['25153', '25155', '25156']
    priority = 'normal'
    resolution = 'fixed'
    stage = 'resolved'
    status = 'closed'
    superseder = None
    type = 'enhancement'
    url = 'https://bugs.python.org/issue43705'
    versions = ['Python 3.9']

    @ammaraskar
    Copy link
    Member Author

    As pointed out by Guido in https://bugs.python.org/issue43555, we switched to making the column offsets for SyntaxError be 1-indexed consistently in https://bugs.python.org/issue34683

    The rationale is explained by Guido and expanded upon in follow up comments here: #9338 (review)

    This property however was not actually ever added to SyntaxError's documentation: https://docs.python.org/3/library/exceptions.html#SyntaxError

    @ammaraskar ammaraskar added the 3.9 only security fixes label Apr 2, 2021
    @ammaraskar ammaraskar added docs Documentation in the Doc dir 3.9 only security fixes labels Apr 2, 2021
    @ammaraskar ammaraskar added the docs Documentation in the Doc dir label Apr 2, 2021
    @miss-islington
    Copy link
    Contributor

    New changeset b2a91e0 by Ammar Askar in branch 'master':
    bpo-43705: Document that SyntaxError's offsets are 1-indexed (GH-25153)
    b2a91e0

    @miss-islington
    Copy link
    Contributor

    New changeset 06653f8 by Miss Islington (bot) in branch '3.8':
    bpo-43705: Document that SyntaxError's offsets are 1-indexed (GH-25153)
    06653f8

    @miss-islington
    Copy link
    Contributor

    New changeset 63c6944 by Miss Islington (bot) in branch '3.9':
    bpo-43705: Document that SyntaxError's offsets are 1-indexed (GH-25153)
    63c6944

    @terryjreedy
    Copy link
    Member

    Should we mention that the 4 attributes are also available as a 4-tuple that is the 2nd item of the args tuple, after the message? Doing so will help when illustrating the following.

    For syntax errors in f-string fields, the expanded doc is still incomplete/erroneous. The text attribute is the replacement expression wrapped in parentheses (or with {} replaced by ()), with \n added; the column is the (1-based) offset within that constructed source.

    >>> try:
    	compile("f'Bad {a b} field'", '', 'exec')
    except SyntaxError as e:
    	print(e.args)

    ('f-string: invalid syntax', ('', 1, 4, '(a b)\n'))

    This was brought to my attention a week or so ago because IDLE still thinks that 4 refers to the 'a' of 'Bad' and marks it is the error location. I had to deduce the rule from examples.

    Whether for this issue or a new one, I am thinking of something like the following.
    ---

    For syntax error instances, the args attribute is (error-message, details-tuple). The str returns only the error message. For convenience, the four details are also available as separate attributes.

    <new list as is>

    For errors in f-string fields, the message is prefixed by "f-string:" and the offset is the offset in a text constructed from the replacement expression. For example, compiling f'Bad {a b} field' results in the following args attribute: ('f-string: invalid syntax', ('', 1, 4, '(a b)\n')).

    I think it okay to require the reader to match '{a b}' and '(a b)\n' to deduce the transformation rule. Messages other than 'invalid syntax', like 'closing parenthesis ...' get the same prefix. Anything Python specific can be labelled as such.

    @ammaraskar
    Copy link
    Member Author

    Aah thanks for pointing that out Terry, I didn't realize f-strings have different semantics for SyntaxError. Would you mind making a separate issue for that, I'll look into making the documentation for it clearer after I get a chance to investigate.

    @ammaraskar ammaraskar added the type-feature A feature request or enhancement label Apr 3, 2021
    @ammaraskar ammaraskar added the type-feature A feature request or enhancement label Apr 3, 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 docs Documentation in the Doc dir type-feature A feature request or enhancement
    Projects
    None yet
    Development

    No branches or pull requests

    3 participants