classification
Title: Built-in compile() and ast module doc issues
Type: Stage:
Components: Documentation Versions: Python 3.0, Python 2.7, Python 2.6
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: georg.brandl Nosy List: benjamin.peterson, georg.brandl, rhettinger, terry.reedy
Priority: normal Keywords:

Created on 2008-10-13 23:17 by terry.reedy, last changed 2008-11-08 16:56 by benjamin.peterson. This issue is now closed.

Messages (5)
msg74712 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2008-10-13 23:17
From docs.python.org
2.6: Compile the source into a code or AST object.
3.0: Compile the source into a code object.
Add 'or AST ' to the latter.

Both: Refer to the _ast module documentation
<there is none, docs only for the ast module, but see below>

Both: for information on how to compile into and from AST objects.

This sentence should at least have 'and from AST ' deleted. The
information on 'from' is given in the previous sentence.
Both: source can either be a string or an AST object.

The ast doc adds nothing.  "A modified abstract syntax tree can be
compiled into a Python code object using the built-in compile() function."

The remainder of the sentence could be replaced by the shorter
"To compile into an AST object, import ast and pass ast.PyCF_ONLY_AST as
a flag."

This could be followed by "See ast module documentation for more."

----
In the ast doc, both say: "An abstract syntax tree can be generated by
passing _ast.PyCF_ONLY_AST ..."

That should be ast, not _ast; the existence of the shadow C version is a
CPython implementation detail.

In the parse() doc lines, 'PyCF_ONLY_AST' should, I think, have the
'ast' prefix as the former will not work unless one does 'from ast
import PyCF_ONLY_AST' (or '... import *').

----
Back to compile():
2.6 (and before): When compiling a string with multi-line statements...
3.0 <Caveats missing>

The first, about '\n' versus '\r\n' still applies.
print (compile("def f():\r\n  pass #haha",'','exec')) #fails
print (compile("def f():\n  pass #haha",'','exec')) # succeeds

The second, at least for 2.5.2 and 3.0c1 (and I presume for 2.6), only
applies, it seems, based on testing, if the last line consists only of a
comment.  In the second example above, putting '#haha' on a separate
line fails.

See: 'compile' built-in function failures when missing EOL
http://bugs.python.org/issue1479099

I am not sure what to suggest, but a warning that is nearly always a
false alarm confuses and lulls.
msg75618 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2008-11-07 21:49
It appears that blanks on the last line also triggers a syntax error.
See #4262.  So the situation seems to be that the input must *sometimes*
be terminated by .... .  So adding 'sometimes' is the only change I
would make, besides restoring the warning to the 3.0 docs.
msg75623 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2008-11-07 23:29
General comment:

Stylistically, the docs should mostly be stated in a positive manner,
stating what a tool does, how it should be used, and what is left
undefined.  IMO, it is harmful to fill the docs with CAVEATS and WARNINGS.
msg75626 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2008-11-08 02:47
The 2.6 sentence that got deleted in 3.0:

I at least somewhat agree.

"When compiling a string with multi-line statements, two caveats apply:
line endings must be represented by a single newline character ('\n'),
and the input must be terminated by at least one newline character."

could have "two caveats apply" deleted to be more positive.  I would
prefer the following simpler, direct use instruction.

"When compiling a string with multi-line statements, terminate all lines
with a single newline character ('\n')."

This issue came up both in c.l.p discussion and again in invalid #4262
(whose author apparently missed the current sentence).
msg75639 - (view) Author: Benjamin Peterson (benjamin.peterson) * (Python committer) Date: 2008-11-08 16:56
Thanks for the suggestions! Changed in r67162.
History
Date User Action Args
2008-11-08 16:56:02benjamin.petersonsetstatus: open -> closed
resolution: fixed
messages: + msg75639
2008-11-08 02:47:52terry.reedysetmessages: + msg75626
2008-11-07 23:29:22rhettingersetnosy: + rhettinger
messages: + msg75623
2008-11-07 21:49:01terry.reedysetnosy: + benjamin.peterson
messages: + msg75618
2008-10-13 23:17:34terry.reedycreate