homepage

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.

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.

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

Thanks for the suggestions! Changed in r67162.