From ec9199be08e832edb5f432fa56270ef65f97fb83 Mon Sep 17 00:00:00 2001 From: Benjamin Peterson Date: Sat, 8 Nov 2008 17:05:00 +0000 Subject: 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 ........ --- Doc/library/ast.rst | 11 +++++------ Doc/library/functions.rst | 37 ++++++++++++++++++++++--------------- 2 files changed, 27 insertions(+), 21 deletions(-) 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 @@ abstract syntax grammar. The abstract syntax itself might change with each 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 @@ and classes for traversing abstract syntax trees: .. function:: parse(expr, filename='', 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 @@ are always available. They are listed here in alphabetical order. .. 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. - - 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 (``''`` 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). + 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 (``''`` 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 @@ are always available. They are listed here in alphabetical order. 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]]) -- cgit v0.12