[New-bugs-announce] [issue11000] Doc: ast.parse parses source, not just expressions

[Terry J. Reedy]

New submission from Terry J. Reedy <tjreedy at udel.edu>:

"ast.parse(expr, filename='<unknown>', mode='exec') 
Parse an expression into an AST node. Equivalent to compile(expr, filename, mode, ast.PyCF_ONLY_AST)."

but

"compile(source, ...) 
Compile the source into a code or AST object. 
...
The mode argument specifies what kind of code must be compiled; it can be 'exec' if source consists of a sequence of statements,"

and indeed, with all three versions,

>>> import ast
>>> e3=ast.parse('x=1; y=2\nif x: print(y)')
>>> o3 = compile(e3,'','exec')
>>> exec(o3)
2
>>> print(x,y)
(1, 2)

Attached patch (untested) changes doc and doc string.

Inquiry: I suspect that the filename is *not* attached to the ast. (In any case, it must be explicitly supplied to a subsequent compile() call.) If so, it is a useless parameter and the api and doc should be

parse(source, mode) ... Equivalent to compile(source, '<unknown>', ...

If so, and failing such a change, should the doc warn people to not bother supplying a filename arg?

I also wonder whether the mode arg has any effect on the ast. If not, same question.

----------
assignee: docs at python
components: Documentation
files: zast.diff
keywords: patch
messages: 126952
nosy: docs at python, georg.brandl, terry.reedy
priority: normal
severity: normal
status: open
title: Doc: ast.parse parses source, not just expressions
versions: Python 2.7, Python 3.1, Python 3.2
Added file: http://bugs.python.org/file20506/zast.diff

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