Doc: ast.parse parses source, not just expressions

[terryjreedy]

BPO	11000
Nosy	@birkenfeld, @terryjreedy
Files	zast.diff: 'expr' to 'source'

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2011-01-24.22:29:04.824>
created_at = <Date 2011-01-24.20:07:57.713>
labels = ['docs']
title = 'Doc: ast.parse parses source, not just expressions'
updated_at = <Date 2011-01-24.22:29:04.823>
user = 'https://github.com/terryjreedy'

bugs.python.org fields:

activity = <Date 2011-01-24.22:29:04.823>
actor = 'terry.reedy'
assignee = 'docs@python'
closed = True
closed_date = <Date 2011-01-24.22:29:04.824>
closer = 'terry.reedy'
components = ['Documentation']
creation = <Date 2011-01-24.20:07:57.713>
creator = 'terry.reedy'
dependencies = []
files = ['20506']
hgrepos = []
issue_num = 11000
keywords = ['patch']
message_count = 3.0
messages = ['126952', '126953', '126964']
nosy_count = 3.0
nosy_names = ['georg.brandl', 'terry.reedy', 'docs@python']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue11000'
versions = ['Python 3.1', 'Python 2.7', 'Python 3.2']

[terryjreedy]

"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.

[birkenfeld]

Looks fine.

[terryjreedy]

r88172, r88173, r88175