[docs] [issue30637] Syntax error reported on compile(...), but not on compile(..., ast.PyCF_ONLY_AST)

[Nick Coghlan]

Nick Coghlan added the comment:

It's intended behaviour, but you're right that we don't explicitly document anywhere that SyntaxError can be reported from three different places:

- the initial parsing based on the language Grammar
- the conversion of the parse tree into the AST
- the conversion of the AST into a runtime code object

It isn't possible to separate the first two from pure Python code, but ast.parse() (aka the ast.PyCF_ONLY_AST compile flag) skips the last one.

As Michał noted, it's usually that last stage which checks for "higher level" constructs related to lexical structure, where certain statements can only be meaningfully executed when used inside a suitable compound statement, but can still be parsed outside it:

```
>>> ast.dump(ast.parse("break"))
'Module(body=[Break()])'
>>> ast.dump(ast.parse("continue"))
'Module(body=[Continue()])'
>>> ast.dump(ast.parse("return"))
'Module(body=[Return(value=None)])'
>>> ast.dump(ast.parse("yield"))
'Module(body=[Expr(value=Yield(value=None))])'
```

(`await` currently isn't in that category, but that's specifically due to the parser hacks used to enable it without needing a __future__ import)

The appropriate fix would probably be to add a sentence to the `ast.PyCF_ONLY_AST` documentation to say that some syntax errors are only detected when compiling the AST to a code object.

----------
assignee:  -> docs at python
components: +Documentation -Interpreter Core
nosy: +docs at python, ncoghlan
stage:  -> needs patch
type:  -> enhancement

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue30637>
_______________________________________