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.
|msg74712 - (view)||Author: Terry J. Reedy (terry.reedy) *||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) *||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) *||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) *||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) *||Date: 2008-11-08 16:56|
Thanks for the suggestions! Changed in r67162.
|2008-11-08 16:56:02||benjamin.peterson||set||status: open -> closed|
messages: + msg75639
|2008-11-08 02:47:52||terry.reedy||set||messages: + msg75626|
messages: + msg75623
messages: + msg75618