[3.9] bpo-44322: Document more SyntaxError details. (GH-26562)

terryjreedy · web-flow · commit d5f8bd60e120 · 2021-06-06T22:57:53.000-04:00
1. SyntaxError args have a tuple of other attributes. 2. Attributes are adjusted for errors in f-string field expressions. 3. Compile() can raise SyntaxErrors. (cherry picked from commit 67dfa6f)
diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst
@@ -390,14 +390,16 @@ The following exceptions are the exceptions that are usually raised.
 
    .. versionadded:: 3.5
 
-.. exception:: SyntaxError
+.. exception:: SyntaxError(message, details)
 
    Raised when the parser encounters a syntax error.  This may occur in an
-   :keyword:`import` statement, in a call to the built-in functions :func:`exec`
+   :keyword:`import` statement, in a call to the built-in functions
+   :func:`compile`, :func:`exec`,
    or :func:`eval`, or when reading the initial script or standard input
    (also interactively).
 
    The :func:`str` of the exception instance returns only the error message.
+   Details is a tuple whose members are also available as separate attributes.
 
    .. attribute:: filename
 
@@ -417,6 +419,11 @@ The following exceptions are the exceptions that are usually raised.
 
       The source code text involved in the error.
 
+   For errors in f-string fields, the message is prefixed by "f-string: "
+   and the offsets are offsets in a text constructed from the replacement
+   expression.  For example, compiling f'Bad {a b} field' results in this
+   args attribute: ('f-string: ...', ('', 1, 4, '(a b)\n')).
+
 
 .. exception:: IndentationError
 
diff --git a/Misc/NEWS.d/next/Documentation/2021-06-06-14-12-00.bpo-44322.K0PHfE.rst b/Misc/NEWS.d/next/Documentation/2021-06-06-14-12-00.bpo-44322.K0PHfE.rst
@@ -0,0 +1,2 @@
+Document that SyntaxError args have a details tuple and that details are
+adjusted for errors in f-string field replacement expressions.
