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

[Terry J. Reedy]

Terry J. Reedy <tjreedy at udel.edu> added the comment:

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.

----------
nosy:  -miss-islington

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue43705>
_______________________________________