cpython-lru_cache-weakref: Doc/library/parser.rst annotate

annotate Doc/library/parser.rst @ 79675:c0a2294de787 2.7

Issue #16199: Backport 2to3 typo fix from 3.2.

author	Chris Jerdonek <chris.jerdonek@gmail.com>
date	Thu, 11 Oct 2012 16:15:46 -0700
parents	c1945703c7cb
children

rev	line source
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2 :mod:`parser` --- Access Python parse trees
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	3 ===========================================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	4
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	5 .. module:: parser
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	6 :synopsis: Access parse trees for Python source code.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	7 .. moduleauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	8 .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	9
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	10
44383 3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 43625 diff changeset	11 .. Copyright 1995 Virginia Polytechnic Institute and State University and Fred
3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 43625 diff changeset	12 L. Drake, Jr. This copyright notice must be distributed on all copies, but
3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 43625 diff changeset	13 this document otherwise may be distributed as part of the Python
3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 43625 diff changeset	14 distribution. No fee may be charged for this document in any representation,
3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 43625 diff changeset	15 either on paper or electronically. This restriction does not affect other
3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 43625 diff changeset	16 elements in a distributed package in any way.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	17
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	18 .. index:: single: parsing; Python source code
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	19
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	20 The :mod:`parser` module provides an interface to Python's internal parser and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	21 byte-code compiler. The primary purpose for this interface is to allow Python
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	22 code to edit the parse tree of a Python expression and create executable code
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	23 from this. This is better than trying to parse and modify an arbitrary Python
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	24 code fragment as a string because parsing is performed in a manner identical to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	25 the code forming the application. It is also faster.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	26
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	27 .. note::
4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	28
4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	29 From Python 2.5 onward, it's much more convenient to cut in at the Abstract
4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	30 Syntax Tree (AST) generation and compilation stage, using the :mod:`ast`
4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	31 module.
4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	32
4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	33 The :mod:`parser` module exports the names documented here also with "st"
4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	34 replaced by "ast"; this is a legacy from the time when there was no other
4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	35 AST and has nothing to do with the AST found in Python 2.5. This is also the
4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	36 reason for the functions' keyword arguments being called ast, not st.
77923 c1945703c7cb Adapt mentions of future changes in doc Éric Araujo <merwok@netwok.org> parents: 77102 diff changeset	37 The "ast" functions have been removed in Python 3.
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	38
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	39 There are a few things to note about this module which are important to making
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	40 use of the data structures created. This is not a tutorial on editing the parse
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	41 trees for Python code, but some examples of using the :mod:`parser` module are
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	42 presented.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	43
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	44 Most importantly, a good understanding of the Python grammar processed by the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	45 internal parser is required. For full information on the language syntax, refer
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	46 to :ref:`reference-index`. The parser
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	47 itself is created from a grammar specification defined in the file
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	48 :file:`Grammar/Grammar` in the standard Python distribution. The parse trees
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	49 stored in the ST objects created by this module are the actual output from the
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	50 internal parser when created by the :func:`expr` or :func:`suite` functions,
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	51 described below. The ST objects created by :func:`sequence2st` faithfully
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	52 simulate those structures. Be aware that the values of the sequences which are
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	53 considered "correct" will vary from one version of Python to another as the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	54 formal grammar for the language is revised. However, transporting code from one
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	55 Python version to another as source text will always allow correct parse trees
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	56 to be created in the target version, with the only restriction being that
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	57 migrating to an older version of the interpreter will not support more recent
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	58 language constructs. The parse trees are not typically compatible from one
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	59 version to another, whereas source code has always been forward-compatible.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	60
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	61 Each element of the sequences returned by :func:`st2list` or :func:`st2tuple`
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	62 has a simple form. Sequences representing non-terminal elements in the grammar
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	63 always have a length greater than one. The first element is an integer which
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	64 identifies a production in the grammar. These integers are given symbolic names
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	65 in the C header file :file:`Include/graminit.h` and the Python module
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	66 :mod:`symbol`. Each additional element of the sequence represents a component
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	67 of the production as recognized in the input string: these are always sequences
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	68 which have the same form as the parent. An important aspect of this structure
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	69 which should be noted is that keywords used to identify the parent node type,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	70 such as the keyword :keyword:`if` in an :const:`if_stmt`, are included in the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	71 node tree without any special treatment. For example, the :keyword:`if` keyword
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	72 is represented by the tuple ``(1, 'if')``, where ``1`` is the numeric value
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	73 associated with all :const:`NAME` tokens, including variable and function names
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	74 defined by the user. In an alternate form returned when line number information
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	75 is requested, the same token might be represented as ``(1, 'if', 12)``, where
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	76 the ``12`` represents the line number at which the terminal symbol was found.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	77
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	78 Terminal elements are represented in much the same way, but without any child
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	79 elements and the addition of the source text which was identified. The example
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	80 of the :keyword:`if` keyword above is representative. The various types of
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	81 terminal symbols are defined in the C header file :file:`Include/token.h` and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	82 the Python module :mod:`token`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	83
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	84 The ST objects are not required to support the functionality of this module,
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	85 but are provided for three purposes: to allow an application to amortize the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	86 cost of processing complex parse trees, to provide a parse tree representation
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	87 which conserves memory space when compared to the Python list or tuple
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	88 representation, and to ease the creation of additional modules in C which
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	89 manipulate parse trees. A simple "wrapper" class may be created in Python to
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	90 hide the use of ST objects.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	91
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	92 The :mod:`parser` module defines functions for a few distinct purposes. The
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	93 most important purposes are to create ST objects and to convert ST objects to
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	94 other representations such as parse trees and compiled code objects, but there
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	95 are also functions which serve to query the type of parse tree represented by an
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	96 ST object.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	97
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	98
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	99 .. seealso::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	100
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	101 Module :mod:`symbol`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	102 Useful constants representing internal nodes of the parse tree.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	103
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	104 Module :mod:`token`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	105 Useful constants representing leaf nodes of the parse tree and functions for
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	106 testing node values.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	107
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	108
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	109 .. _creating-sts:
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	110
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	111 Creating ST Objects
4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	112 -------------------
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	113
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	114 ST objects may be created from source code or from a parse tree. When creating
4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	115 an ST object from source, different functions are used to create the ``'eval'``
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	116 and ``'exec'`` forms.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	117
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	118
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	119 .. function:: expr(source)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	120
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	121 The :func:`expr` function parses the parameter source as if it were an input
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	122 to ``compile(source, 'file.py', 'eval')``. If the parse succeeds, an ST object
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	123 is created to hold the internal parse tree representation, otherwise an
65127 ff734f225b47 Merged revisions 82798,82805,83659,83977,84015,84018,84141,84264,84326-84327,84480,84482,84484,84530-84531,84553,84619,84915-84916 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	124 appropriate exception is raised.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	125
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	126
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	127 .. function:: suite(source)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	128
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	129 The :func:`suite` function parses the parameter source as if it were an input
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	130 to ``compile(source, 'file.py', 'exec')``. If the parse succeeds, an ST object
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	131 is created to hold the internal parse tree representation, otherwise an
65127 ff734f225b47 Merged revisions 82798,82805,83659,83977,84015,84018,84141,84264,84326-84327,84480,84482,84484,84530-84531,84553,84619,84915-84916 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	132 appropriate exception is raised.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	133
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	134
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	135 .. function:: sequence2st(sequence)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	136
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	137 This function accepts a parse tree represented as a sequence and builds an
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	138 internal representation if possible. If it can validate that the tree conforms
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	139 to the Python grammar and all nodes are valid node types in the host version of
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	140 Python, an ST object is created from the internal representation and returned
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	141 to the called. If there is a problem creating the internal representation, or
65127 ff734f225b47 Merged revisions 82798,82805,83659,83977,84015,84018,84141,84264,84326-84327,84480,84482,84484,84530-84531,84553,84619,84915-84916 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	142 if the tree cannot be validated, a :exc:`ParserError` exception is raised. An
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	143 ST object created this way should not be assumed to compile correctly; normal
65127 ff734f225b47 Merged revisions 82798,82805,83659,83977,84015,84018,84141,84264,84326-84327,84480,84482,84484,84530-84531,84553,84619,84915-84916 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	144 exceptions raised by compilation may still be initiated when the ST object is
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	145 passed to :func:`compilest`. This may indicate problems not related to syntax
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	146 (such as a :exc:`MemoryError` exception), but may also be due to constructs such
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	147 as the result of parsing ``del f(0)``, which escapes the Python parser but is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	148 checked by the bytecode compiler.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	149
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	150 Sequences representing terminal tokens may be represented as either two-element
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	151 lists of the form ``(1, 'name')`` or as three-element lists of the form ``(1,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	152 'name', 56)``. If the third element is present, it is assumed to be a valid
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	153 line number. The line number may be specified for any subset of the terminal
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	154 symbols in the input tree.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	155
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	156
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	157 .. function:: tuple2st(sequence)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	158
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	159 This is the same function as :func:`sequence2st`. This entry point is
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	160 maintained for backward compatibility.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	161
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	162
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	163 .. _converting-sts:
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	164
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	165 Converting ST Objects
4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	166 ---------------------
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	167
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	168 ST objects, regardless of the input used to create them, may be converted to
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	169 parse trees represented as list- or tuple- trees, or may be compiled into
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	170 executable code objects. Parse trees may be extracted with or without line
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	171 numbering information.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	172
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	173
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	174 .. function:: st2list(ast[, line_info])
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	175
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	176 This function accepts an ST object from the caller in ast and returns a
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	177 Python list representing the equivalent parse tree. The resulting list
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	178 representation can be used for inspection or the creation of a new parse tree in
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	179 list form. This function does not fail so long as memory is available to build
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	180 the list representation. If the parse tree will only be used for inspection,
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	181 :func:`st2tuple` should be used instead to reduce memory consumption and
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	182 fragmentation. When the list representation is required, this function is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	183 significantly faster than retrieving a tuple representation and converting that
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	184 to nested lists.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	185
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	186 If line_info is true, line number information will be included for all
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	187 terminal tokens as a third element of the list representing the token. Note
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	188 that the line number provided specifies the line on which the token ends.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	189 This information is omitted if the flag is false or omitted.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	190
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	191
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	192 .. function:: st2tuple(ast[, line_info])
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	193
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	194 This function accepts an ST object from the caller in ast and returns a
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	195 Python tuple representing the equivalent parse tree. Other than returning a
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	196 tuple instead of a list, this function is identical to :func:`st2list`.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	197
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	198 If line_info is true, line number information will be included for all
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	199 terminal tokens as a third element of the list representing the token. This
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	200 information is omitted if the flag is false or omitted.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	201
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	202
77102 a36666c52115 #14804: Remove [] around optional arguments with default values Hynek Schlawack <hs@ox.cx> parents: 76732 diff changeset	203 .. function:: compilest(ast, filename='<syntax-tree>')
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	204
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	205 .. index:: builtin: eval
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	206
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	207 The Python byte compiler can be invoked on an ST object to produce code objects
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	208 which can be used as part of an :keyword:`exec` statement or a call to the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	209 built-in :func:`eval` function. This function provides the interface to the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	210 compiler, passing the internal parse tree from ast to the parser, using the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	211 source file name specified by the filename parameter. The default value
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	212 supplied for filename indicates that the source was an ST object.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	213
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	214 Compiling an ST object may result in exceptions related to compilation; an
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	215 example would be a :exc:`SyntaxError` caused by the parse tree for ``del f(0)``:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	216 this statement is considered legal within the formal grammar for Python but is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	217 not a legal language construct. The :exc:`SyntaxError` raised for this
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	218 condition is actually generated by the Python byte-compiler normally, which is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	219 why it can be raised at this point by the :mod:`parser` module. Most causes of
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	220 compilation failure can be diagnosed programmatically by inspection of the parse
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	221 tree.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	222
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	223
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	224 .. _querying-sts:
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	225
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	226 Queries on ST Objects
4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	227 ---------------------
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	228
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	229 Two functions are provided which allow an application to determine if an ST was
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	230 created as an expression or a suite. Neither of these functions can be used to
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	231 determine if an ST was created from source code via :func:`expr` or
4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	232 :func:`suite` or from a parse tree via :func:`sequence2st`.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	233
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	234
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	235 .. function:: isexpr(ast)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	236
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	237 .. index:: builtin: compile
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	238
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	239 When ast represents an ``'eval'`` form, this function returns true, otherwise
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	240 it returns false. This is useful, since code objects normally cannot be queried
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	241 for this information using existing built-in functions. Note that the code
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	242 objects created by :func:`compilest` cannot be queried like this either, and
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	243 are identical to those created by the built-in :func:`compile` function.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	244
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	245
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	246 .. function:: issuite(ast)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	247
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	248 This function mirrors :func:`isexpr` in that it reports whether an ST object
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	249 represents an ``'exec'`` form, commonly known as a "suite." It is not safe to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	250 assume that this function is equivalent to ``not isexpr(ast)``, as additional
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	251 syntactic fragments may be supported in the future.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	252
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	253
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	254 .. _st-errors:
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	255
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	256 Exceptions and Error Handling
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	257 -----------------------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	258
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	259 The parser module defines a single exception, but may also pass other built-in
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	260 exceptions from other portions of the Python runtime environment. See each
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	261 function for information about the exceptions it can raise.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	262
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	263
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	264 .. exception:: ParserError
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	265
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	266 Exception raised when a failure occurs within the parser module. This is
65127 ff734f225b47 Merged revisions 82798,82805,83659,83977,84015,84018,84141,84264,84326-84327,84480,84482,84484,84530-84531,84553,84619,84915-84916 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	267 generally produced for validation failures rather than the built-in
ff734f225b47 Merged revisions 82798,82805,83659,83977,84015,84018,84141,84264,84326-84327,84480,84482,84484,84530-84531,84553,84619,84915-84916 via svnmerge from Georg Brandl <georg@python.org> parents: 50522 diff changeset	268 :exc:`SyntaxError` raised during normal parsing. The exception argument is
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	269 either a string describing the reason of the failure or a tuple containing a
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	270 sequence causing the failure from a parse tree passed to :func:`sequence2st`
4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	271 and an explanatory string. Calls to :func:`sequence2st` need to be able to
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	272 handle either type of exception, while calls to other functions in the module
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	273 will only need to be aware of the simple string values.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	274
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	275 Note that the functions :func:`compilest`, :func:`expr`, and :func:`suite` may
66570 04e8bd9a1aba Merged revisions 86892 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 66457 diff changeset	276 raise exceptions which are normally raised by the parsing and compilation
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	277 process. These include the built in exceptions :exc:`MemoryError`,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	278 :exc:`OverflowError`, :exc:`SyntaxError`, and :exc:`SystemError`. In these
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	279 cases, these exceptions carry all the meaning normally associated with them.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	280 Refer to the descriptions of each function for detailed information.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	281
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	282
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	283 .. _st-objects:
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	284
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	285 ST Objects
4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	286 ----------
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	287
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	288 Ordered and equality comparisons are supported between ST objects. Pickling of
4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	289 ST objects (using the :mod:`pickle` module) is also supported.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	290
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	291
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	292 .. data:: STType
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	293
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	294 The type of the objects returned by :func:`expr`, :func:`suite` and
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	295 :func:`sequence2st`.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	296
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	297 ST objects have the following methods:
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	298
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	299
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	300 .. method:: ST.compile([filename])
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	301
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	302 Same as ``compilest(st, filename)``.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	303
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	304
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	305 .. method:: ST.isexpr()
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	306
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	307 Same as ``isexpr(st)``.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	308
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	309
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	310 .. method:: ST.issuite()
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	311
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	312 Same as ``issuite(st)``.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	313
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	314
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	315 .. method:: ST.tolist([line_info])
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	316
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	317 Same as ``st2list(st, line_info)``.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	318
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	319
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	320 .. method:: ST.totuple([line_info])
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	321
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	322 Same as ``st2tuple(st, line_info)``.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	323
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	324
66457 a803fd841fd1 Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 65127 diff changeset	325 Example: Emulation of :func:`compile`
a803fd841fd1 Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 65127 diff changeset	326 -------------------------------------
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	327
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	328 While many useful operations may take place between parsing and bytecode
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	329 generation, the simplest operation is to do nothing. For this purpose, using
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	330 the :mod:`parser` module to produce an intermediate data structure is equivalent
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	331 to the code ::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	332
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	333 >>> code = compile('a + 5', 'file.py', 'eval')
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	334 >>> a = 5
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	335 >>> eval(code)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	336 10
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	337
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	338 The equivalent operation using the :mod:`parser` module is somewhat longer, and
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	339 allows the intermediate internal parse tree to be retained as an ST object::
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	340
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	341 >>> import parser
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	342 >>> st = parser.expr('a + 5')
4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	343 >>> code = st.compile('file.py')
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	344 >>> a = 5
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	345 >>> eval(code)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	346 10
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	347
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	348 An application which needs both ST and code objects can package this code into
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	349 readily available functions::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	350
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	351 import parser
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	352
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	353 def load_suite(source_string):
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	354 st = parser.suite(source_string)
4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	355 return st, st.compile()
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	356
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	357 def load_expression(source_string):
47513 4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	358 st = parser.expr(source_string)
4f70a9de2865 Document the "st" API, to avoid confusion with the "new" AST. Georg Brandl <georg@python.org> parents: 44383 diff changeset	359 return st, st.compile()

Mercurial > cpython-lru_cache-weakref

annotate Doc/library/parser.rst @ 79675:c0a2294de787 2.7