Merged revisions 67162 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r67162 | benjamin.peterson | 2008-11-08 10:55:33 -0600 (Sat, 08 Nov 2008) | 1 line
a few compile() and ast doc improvements
........
diff --git a/Doc/library/ast.rst b/Doc/library/ast.rst
index 8590a48..88c0228 100644
--- a/Doc/library/ast.rst
+++ b/Doc/library/ast.rst
@@ -15,13 +15,12 @@
Python release; this module helps to find out programmatically what the current
grammar looks like.
-An abstract syntax tree can be generated by passing :data:`_ast.PyCF_ONLY_AST`
-as a flag to the :func:`compile` builtin function, or using the :func:`parse`
+An abstract syntax tree can be generated by passing :data:`ast.PyCF_ONLY_AST` as
+a flag to the :func:`compile` builtin function, or using the :func:`parse`
helper provided in this module. The result will be a tree of objects whose
-classes all inherit from :class:`ast.AST`.
+classes all inherit from :class:`ast.AST`. An abstract syntax tree can be
+compiled into a Python code object using the built-in :func:`compile` function.
-A modified abstract syntax tree can be compiled into a Python code object using
-the built-in :func:`compile` function.
Node classes
------------
@@ -113,7 +112,7 @@
.. function:: parse(expr, filename='<unknown>', mode='exec')
Parse an expression into an AST node. Equivalent to ``compile(expr,
- filename, mode, PyCF_ONLY_AST)``.
+ filename, mode, ast.PyCF_ONLY_AST)``.
.. function:: literal_eval(node_or_string)
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index c2af1e8..e885c3b 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -199,21 +199,20 @@
.. function:: compile(source, filename, mode[, flags[, dont_inherit]])
- Compile the *source* into a code object or AST object. Code objects can be
- executed by a call to :func:`exec` or evaluated by a call to
- :func:`eval`. *source* can either be a string or an AST object. Refer to the
- :mod:`_ast` module documentation for information on how to compile into and
- from AST objects.
+ Compile the *source* into a code or AST object. Code objects can be executed
+ by an :keyword:`exec` statement or evaluated by a call to :func:`eval`.
+ *source* can either be a string or an AST object. Refer to the :mod:`ast`
+ module documentation for information on how to work with AST objects.
- The *filename* argument should give the file from
- which the code was read; pass some recognizable value if it wasn't
- read from a file (``'<string>'`` is commonly used). The *mode*
- argument specifies what kind of code must be compiled; it can be
- ``'exec'`` if *source* consists of a sequence of statements,
- ``'eval'`` if it consists of a single expression, or ``'single'``
- if it consists of a single interactive statement (in the latter
- case, expression statements that evaluate to something else than
- ``None`` will be printed).
+ The *filename* argument should give the file from which the code was read;
+ pass some recognizable value if it wasn't read from a file (``'<string>'`` is
+ commonly used).
+
+ The *mode* argument specifies what kind of code must be compiled; it can be
+ ``'exec'`` if *source* consists of a sequence of statements, ``'eval'`` if it
+ consists of a single expression, or ``'single'`` if it consists of a single
+ interactive statement (in the latter case, expression statements that
+ evaluate to something else than ``None`` will be printed).
The optional arguments *flags* and *dont_inherit* control which future
statements (see :pep:`236`) affect the compilation of *source*. If neither
@@ -233,6 +232,14 @@
This function raises :exc:`SyntaxError` if the compiled source is invalid,
and :exc:`TypeError` if the source contains null bytes.
+ .. note::
+
+ When compiling a string with multi-line statements, line endings must be
+ represented by a single newline character (``'\n'``), and the input must
+ be terminated by at least one newline character. If line endings are
+ represented by ``'\r\n'``, use :meth:`str.replace` to change them into
+ ``'\n'``.
+
.. function:: complex([real[, imag]])