classification
Title: Document when compile returns a code object v. AST
Type: Stage: resolved
Components: Documentation Versions: Python 3.7, Python 2.7
process
Status: closed Resolution: duplicate
Dependencies: Superseder: `compile` doesn't compile into an AST object as specified
View: 27119
Assigned To: docs@python Nosy List: BTaskaya, cheryl.sabella, docs@python, gsnedders
Priority: normal Keywords:

Created on 2018-06-29 15:48 by gsnedders, last changed 2019-12-15 13:02 by cheryl.sabella. This issue is now closed.

Messages (3)
msg320721 - (view) Author: Geoffrey Sneddon (gsnedders) * Date: 2018-06-29 15:48
The compile built-in documentation says:

> Compile the source into a code or AST object.

It doesn't however go on to say when it returns each!

It does however note:

> If you want to parse Python code into its AST representation, see ast.parse().

So compile can compile the source into an AST object, but if I want to parse Python code into an AST I should use ast.parse?

As far as I can tell, this goes back to Python 2.5: https://docs.python.org/2/whatsnew/2.5.html#build-and-c-api-changes

From the What's New page:

> It’s possible for Python code to obtain AST objects by using the compile() built-in and specifying _ast.PyCF_ONLY_AST as the value of the flags parameter

So that would seem to be the case when compile returns an AST!

Interestingly, the implementation of ast.parse *literally just calls compile* (https://github.com/python/cpython/blob/58ed7307ea0b5c5aa052291ebc3030f314f938d8/Lib/ast.py#L30-L35).

Note, however, this means a further part of the compile documentation is wrong:

> The optional arguments flags and dont_inherit control which future statements (see PEP 236) affect the compilation of source.

flags is therefore something more general than just controlling which future statements affect the source, given it also controls the output type of the function.

In short, we should:

 * document the flags argument can take _ast.PyCF_ONLY_AST *or* change the documentation to say it returns a code object (and not an AST object)
msg357689 - (view) Author: Batuhan Taskaya (BTaskaya) * (Python triager) Date: 2019-12-01 19:25
I think this is a duplicate of issue 27119
msg358428 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2019-12-15 13:02
Thank you for the bug report and thank you @BTaskaya for finding the other issue.  I'm closing this as a duplicate of #27119.
History
Date User Action Args
2019-12-15 13:02:01cheryl.sabellasetstatus: open -> closed

superseder: `compile` doesn't compile into an AST object as specified

nosy: + cheryl.sabella
messages: + msg358428
resolution: duplicate
stage: resolved
2019-12-01 19:25:42BTaskayasetnosy: + BTaskaya
messages: + msg357689
2018-06-29 15:48:52gsnedderscreate