Issue 4118: Built-in compile() and ast module doc issues (original) (raw)

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

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.

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.

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