Title: [docs] Document that SyntaxError's offsets are 1-indexed
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.9
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: ammar2, docs@python, gvanrossum, terry.reedy
Priority: normal Keywords: patch

Created on 2021-04-02 16:32 by ammar2, last changed 2021-04-03 18:08 by ammar2. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 25153 merged ammar2, 2021-04-02 16:57
PR 25155 merged miss-islington, 2021-04-02 21:25
PR 25156 merged miss-islington, 2021-04-02 21:25
Messages (6)
msg390081 - (view) Author: Ammar Askar (ammar2) * (Python committer) Date: 2021-04-02 16:32
As pointed out by Guido in, we switched to making the column offsets for SyntaxError be 1-indexed consistently in

The rationale is explained by Guido and expanded upon in follow up comments here: 

This property however was not actually ever added to SyntaxError's documentation:
msg390102 - (view) Author: miss-islington (miss-islington) Date: 2021-04-02 21:25
New changeset b2a91e0c9ee18b50cc86b21211c2258520a9f5d0 by Ammar Askar in branch 'master':
bpo-43705: Document that SyntaxError's offsets are 1-indexed (GH-25153)
msg390106 - (view) Author: miss-islington (miss-islington) Date: 2021-04-02 22:26
New changeset 06653f8d15a8a84ee0f43f739704a9a63c27de54 by Miss Islington (bot) in branch '3.8':
bpo-43705: Document that SyntaxError's offsets are 1-indexed (GH-25153)
msg390107 - (view) Author: miss-islington (miss-islington) Date: 2021-04-02 22:26
New changeset 63c69440c7adb0de1d191a8d3d100b335d5c2f81 by Miss Islington (bot) in branch '3.9':
bpo-43705: Document that SyntaxError's offsets are 1-indexed (GH-25153)
msg390111 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2021-04-02 22:53
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:

('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.
msg390133 - (view) Author: Ammar Askar (ammar2) * (Python committer) Date: 2021-04-03 18:08
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.
Date User Action Args
2021-04-03 18:08:51ammar2setstatus: open -> closed
type: enhancement
messages: + msg390133

resolution: fixed
stage: patch review -> resolved
2021-04-02 22:53:41terry.reedysetnosy: - miss-islington
messages: + msg390111
2021-04-02 22:26:37miss-islingtonsetmessages: + msg390107
2021-04-02 22:26:26miss-islingtonsetmessages: + msg390106
2021-04-02 21:25:56miss-islingtonsetpull_requests: + pull_request23903
2021-04-02 21:25:47miss-islingtonsetpull_requests: + pull_request23902
2021-04-02 21:25:38miss-islingtonsetnosy: + miss-islington
messages: + msg390102
2021-04-02 16:57:49ammar2setkeywords: + patch
stage: patch review
pull_requests: + pull_request23900
2021-04-02 16:32:20ammar2create