592 lines
39 KiB
HTML
592 lines
39 KiB
HTML
|
|
|||
|
<!DOCTYPE html>
|
|||
|
|
|||
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|||
|
<head>
|
|||
|
<meta charset="utf-8" />
|
|||
|
<title>ast — Abstract Syntax Trees — Python 3.7.4 documentation</title>
|
|||
|
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
|
|||
|
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
|||
|
|
|||
|
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
|
|||
|
<script type="text/javascript" src="../_static/jquery.js"></script>
|
|||
|
<script type="text/javascript" src="../_static/underscore.js"></script>
|
|||
|
<script type="text/javascript" src="../_static/doctools.js"></script>
|
|||
|
<script type="text/javascript" src="../_static/language_data.js"></script>
|
|||
|
|
|||
|
<script type="text/javascript" src="../_static/sidebar.js"></script>
|
|||
|
|
|||
|
<link rel="search" type="application/opensearchdescription+xml"
|
|||
|
title="Search within Python 3.7.4 documentation"
|
|||
|
href="../_static/opensearch.xml"/>
|
|||
|
<link rel="author" title="About these documents" href="../about.html" />
|
|||
|
<link rel="index" title="Index" href="../genindex.html" />
|
|||
|
<link rel="search" title="Search" href="../search.html" />
|
|||
|
<link rel="copyright" title="Copyright" href="../copyright.html" />
|
|||
|
<link rel="next" title="symtable — Access to the compiler’s symbol tables" href="symtable.html" />
|
|||
|
<link rel="prev" title="parser — Access Python parse trees" href="parser.html" />
|
|||
|
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
|
|||
|
<link rel="canonical" href="https://docs.python.org/3/library/ast.html" />
|
|||
|
|
|||
|
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
|||
|
<script type="text/javascript" src="../_static/switchers.js"></script>
|
|||
|
|
|||
|
|
|||
|
|
|||
|
<style>
|
|||
|
@media only screen {
|
|||
|
table.full-width-table {
|
|||
|
width: 100%;
|
|||
|
}
|
|||
|
}
|
|||
|
</style>
|
|||
|
|
|||
|
|
|||
|
</head><body>
|
|||
|
|
|||
|
<div class="related" role="navigation" aria-label="related navigation">
|
|||
|
<h3>Navigation</h3>
|
|||
|
<ul>
|
|||
|
<li class="right" style="margin-right: 10px">
|
|||
|
<a href="../genindex.html" title="General Index"
|
|||
|
accesskey="I">index</a></li>
|
|||
|
<li class="right" >
|
|||
|
<a href="../py-modindex.html" title="Python Module Index"
|
|||
|
>modules</a> |</li>
|
|||
|
<li class="right" >
|
|||
|
<a href="symtable.html" title="symtable — Access to the compiler’s symbol tables"
|
|||
|
accesskey="N">next</a> |</li>
|
|||
|
<li class="right" >
|
|||
|
<a href="parser.html" title="parser — Access Python parse trees"
|
|||
|
accesskey="P">previous</a> |</li>
|
|||
|
<li><img src="../_static/py.png" alt=""
|
|||
|
style="vertical-align: middle; margin-top: -1px"/></li>
|
|||
|
<li><a href="https://www.python.org/">Python</a> »</li>
|
|||
|
<li>
|
|||
|
<span class="language_switcher_placeholder">en</span>
|
|||
|
<span class="version_switcher_placeholder">3.7.4</span>
|
|||
|
<a href="../index.html">Documentation </a> »
|
|||
|
</li>
|
|||
|
|
|||
|
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
|
|||
|
<li class="nav-item nav-item-2"><a href="language.html" accesskey="U">Python Language Services</a> »</li>
|
|||
|
<li class="right">
|
|||
|
|
|||
|
|
|||
|
<div class="inline-search" style="display: none" role="search">
|
|||
|
<form class="inline-search" action="../search.html" method="get">
|
|||
|
<input placeholder="Quick search" type="text" name="q" />
|
|||
|
<input type="submit" value="Go" />
|
|||
|
<input type="hidden" name="check_keywords" value="yes" />
|
|||
|
<input type="hidden" name="area" value="default" />
|
|||
|
</form>
|
|||
|
</div>
|
|||
|
<script type="text/javascript">$('.inline-search').show(0);</script>
|
|||
|
|
|
|||
|
</li>
|
|||
|
|
|||
|
</ul>
|
|||
|
</div>
|
|||
|
|
|||
|
<div class="document">
|
|||
|
<div class="documentwrapper">
|
|||
|
<div class="bodywrapper">
|
|||
|
<div class="body" role="main">
|
|||
|
|
|||
|
<div class="section" id="module-ast">
|
|||
|
<span id="ast-abstract-syntax-trees"></span><h1><a class="reference internal" href="#module-ast" title="ast: Abstract Syntax Tree classes and manipulation."><code class="xref py py-mod docutils literal notranslate"><span class="pre">ast</span></code></a> — Abstract Syntax Trees<a class="headerlink" href="#module-ast" title="Permalink to this headline">¶</a></h1>
|
|||
|
<p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.7/Lib/ast.py">Lib/ast.py</a></p>
|
|||
|
<hr class="docutils" />
|
|||
|
<p>The <a class="reference internal" href="#module-ast" title="ast: Abstract Syntax Tree classes and manipulation."><code class="xref py py-mod docutils literal notranslate"><span class="pre">ast</span></code></a> module helps Python applications to process trees of the Python
|
|||
|
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.</p>
|
|||
|
<p>An abstract syntax tree can be generated by passing <code class="xref py py-data docutils literal notranslate"><span class="pre">ast.PyCF_ONLY_AST</span></code> as
|
|||
|
a flag to the <a class="reference internal" href="functions.html#compile" title="compile"><code class="xref py py-func docutils literal notranslate"><span class="pre">compile()</span></code></a> built-in function, or using the <a class="reference internal" href="#ast.parse" title="ast.parse"><code class="xref py py-func docutils literal notranslate"><span class="pre">parse()</span></code></a>
|
|||
|
helper provided in this module. The result will be a tree of objects whose
|
|||
|
classes all inherit from <a class="reference internal" href="#ast.AST" title="ast.AST"><code class="xref py py-class docutils literal notranslate"><span class="pre">ast.AST</span></code></a>. An abstract syntax tree can be
|
|||
|
compiled into a Python code object using the built-in <a class="reference internal" href="functions.html#compile" title="compile"><code class="xref py py-func docutils literal notranslate"><span class="pre">compile()</span></code></a> function.</p>
|
|||
|
<div class="section" id="node-classes">
|
|||
|
<h2>Node classes<a class="headerlink" href="#node-classes" title="Permalink to this headline">¶</a></h2>
|
|||
|
<dl class="class">
|
|||
|
<dt id="ast.AST">
|
|||
|
<em class="property">class </em><code class="descclassname">ast.</code><code class="descname">AST</code><a class="headerlink" href="#ast.AST" title="Permalink to this definition">¶</a></dt>
|
|||
|
<dd><p>This is the base of all AST node classes. The actual node classes are
|
|||
|
derived from the <code class="file docutils literal notranslate"><span class="pre">Parser/Python.asdl</span></code> file, which is reproduced
|
|||
|
<a class="reference internal" href="#abstract-grammar"><span class="std std-ref">below</span></a>. They are defined in the <code class="xref py py-mod docutils literal notranslate"><span class="pre">_ast</span></code> C
|
|||
|
module and re-exported in <a class="reference internal" href="#module-ast" title="ast: Abstract Syntax Tree classes and manipulation."><code class="xref py py-mod docutils literal notranslate"><span class="pre">ast</span></code></a>.</p>
|
|||
|
<p>There is one class defined for each left-hand side symbol in the abstract
|
|||
|
grammar (for example, <code class="xref py py-class docutils literal notranslate"><span class="pre">ast.stmt</span></code> or <code class="xref py py-class docutils literal notranslate"><span class="pre">ast.expr</span></code>). In addition,
|
|||
|
there is one class defined for each constructor on the right-hand side; these
|
|||
|
classes inherit from the classes for the left-hand side trees. For example,
|
|||
|
<code class="xref py py-class docutils literal notranslate"><span class="pre">ast.BinOp</span></code> inherits from <code class="xref py py-class docutils literal notranslate"><span class="pre">ast.expr</span></code>. For production rules
|
|||
|
with alternatives (aka “sums”), the left-hand side class is abstract: only
|
|||
|
instances of specific constructor nodes are ever created.</p>
|
|||
|
<span class="target" id="index-0"></span><span class="target" id="index-1"></span><dl class="attribute">
|
|||
|
<dt id="ast.AST._fields">
|
|||
|
<code class="descname">_fields</code><a class="headerlink" href="#ast.AST._fields" title="Permalink to this definition">¶</a></dt>
|
|||
|
<dd><p>Each concrete class has an attribute <a class="reference internal" href="#ast.AST._fields" title="ast.AST._fields"><code class="xref py py-attr docutils literal notranslate"><span class="pre">_fields</span></code></a> which gives the names
|
|||
|
of all child nodes.</p>
|
|||
|
<p>Each instance of a concrete class has one attribute for each child node,
|
|||
|
of the type as defined in the grammar. For example, <code class="xref py py-class docutils literal notranslate"><span class="pre">ast.BinOp</span></code>
|
|||
|
instances have an attribute <code class="xref py py-attr docutils literal notranslate"><span class="pre">left</span></code> of type <code class="xref py py-class docutils literal notranslate"><span class="pre">ast.expr</span></code>.</p>
|
|||
|
<p>If these attributes are marked as optional in the grammar (using a
|
|||
|
question mark), the value might be <code class="docutils literal notranslate"><span class="pre">None</span></code>. If the attributes can have
|
|||
|
zero-or-more values (marked with an asterisk), the values are represented
|
|||
|
as Python lists. All possible attributes must be present and have valid
|
|||
|
values when compiling an AST with <a class="reference internal" href="functions.html#compile" title="compile"><code class="xref py py-func docutils literal notranslate"><span class="pre">compile()</span></code></a>.</p>
|
|||
|
</dd></dl>
|
|||
|
|
|||
|
<dl class="attribute">
|
|||
|
<dt id="ast.AST.lineno">
|
|||
|
<code class="descname">lineno</code><a class="headerlink" href="#ast.AST.lineno" title="Permalink to this definition">¶</a></dt>
|
|||
|
<dt id="ast.AST.col_offset">
|
|||
|
<code class="descname">col_offset</code><a class="headerlink" href="#ast.AST.col_offset" title="Permalink to this definition">¶</a></dt>
|
|||
|
<dd><p>Instances of <code class="xref py py-class docutils literal notranslate"><span class="pre">ast.expr</span></code> and <code class="xref py py-class docutils literal notranslate"><span class="pre">ast.stmt</span></code> subclasses have
|
|||
|
<a class="reference internal" href="#ast.AST.lineno" title="ast.AST.lineno"><code class="xref py py-attr docutils literal notranslate"><span class="pre">lineno</span></code></a> and <a class="reference internal" href="#ast.AST.col_offset" title="ast.AST.col_offset"><code class="xref py py-attr docutils literal notranslate"><span class="pre">col_offset</span></code></a> attributes. The <a class="reference internal" href="#ast.AST.lineno" title="ast.AST.lineno"><code class="xref py py-attr docutils literal notranslate"><span class="pre">lineno</span></code></a> is
|
|||
|
the line number of source text (1-indexed so the first line is line 1) and
|
|||
|
the <a class="reference internal" href="#ast.AST.col_offset" title="ast.AST.col_offset"><code class="xref py py-attr docutils literal notranslate"><span class="pre">col_offset</span></code></a> is the UTF-8 byte offset of the first token that
|
|||
|
generated the node. The UTF-8 offset is recorded because the parser uses
|
|||
|
UTF-8 internally.</p>
|
|||
|
</dd></dl>
|
|||
|
|
|||
|
<p>The constructor of a class <code class="xref py py-class docutils literal notranslate"><span class="pre">ast.T</span></code> parses its arguments as follows:</p>
|
|||
|
<ul class="simple">
|
|||
|
<li><p>If there are positional arguments, there must be as many as there are items
|
|||
|
in <code class="xref py py-attr docutils literal notranslate"><span class="pre">T._fields</span></code>; they will be assigned as attributes of these names.</p></li>
|
|||
|
<li><p>If there are keyword arguments, they will set the attributes of the same
|
|||
|
names to the given values.</p></li>
|
|||
|
</ul>
|
|||
|
<p>For example, to create and populate an <code class="xref py py-class docutils literal notranslate"><span class="pre">ast.UnaryOp</span></code> node, you could
|
|||
|
use</p>
|
|||
|
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">node</span> <span class="o">=</span> <span class="n">ast</span><span class="o">.</span><span class="n">UnaryOp</span><span class="p">()</span>
|
|||
|
<span class="n">node</span><span class="o">.</span><span class="n">op</span> <span class="o">=</span> <span class="n">ast</span><span class="o">.</span><span class="n">USub</span><span class="p">()</span>
|
|||
|
<span class="n">node</span><span class="o">.</span><span class="n">operand</span> <span class="o">=</span> <span class="n">ast</span><span class="o">.</span><span class="n">Num</span><span class="p">()</span>
|
|||
|
<span class="n">node</span><span class="o">.</span><span class="n">operand</span><span class="o">.</span><span class="n">n</span> <span class="o">=</span> <span class="mi">5</span>
|
|||
|
<span class="n">node</span><span class="o">.</span><span class="n">operand</span><span class="o">.</span><span class="n">lineno</span> <span class="o">=</span> <span class="mi">0</span>
|
|||
|
<span class="n">node</span><span class="o">.</span><span class="n">operand</span><span class="o">.</span><span class="n">col_offset</span> <span class="o">=</span> <span class="mi">0</span>
|
|||
|
<span class="n">node</span><span class="o">.</span><span class="n">lineno</span> <span class="o">=</span> <span class="mi">0</span>
|
|||
|
<span class="n">node</span><span class="o">.</span><span class="n">col_offset</span> <span class="o">=</span> <span class="mi">0</span>
|
|||
|
</pre></div>
|
|||
|
</div>
|
|||
|
<p>or the more compact</p>
|
|||
|
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">node</span> <span class="o">=</span> <span class="n">ast</span><span class="o">.</span><span class="n">UnaryOp</span><span class="p">(</span><span class="n">ast</span><span class="o">.</span><span class="n">USub</span><span class="p">(),</span> <span class="n">ast</span><span class="o">.</span><span class="n">Num</span><span class="p">(</span><span class="mi">5</span><span class="p">,</span> <span class="n">lineno</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="n">col_offset</span><span class="o">=</span><span class="mi">0</span><span class="p">),</span>
|
|||
|
<span class="n">lineno</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="n">col_offset</span><span class="o">=</span><span class="mi">0</span><span class="p">)</span>
|
|||
|
</pre></div>
|
|||
|
</div>
|
|||
|
</dd></dl>
|
|||
|
|
|||
|
</div>
|
|||
|
<div class="section" id="abstract-grammar">
|
|||
|
<span id="id1"></span><h2>Abstract Grammar<a class="headerlink" href="#abstract-grammar" title="Permalink to this headline">¶</a></h2>
|
|||
|
<p>The abstract grammar is currently defined as follows:</p>
|
|||
|
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>-- ASDL's 7 builtin types are:
|
|||
|
-- identifier, int, string, bytes, object, singleton, constant
|
|||
|
--
|
|||
|
-- singleton: None, True or False
|
|||
|
-- constant can be None, whereas None means "no value" for object.
|
|||
|
|
|||
|
module Python
|
|||
|
{
|
|||
|
mod = Module(stmt* body)
|
|||
|
| Interactive(stmt* body)
|
|||
|
| Expression(expr body)
|
|||
|
|
|||
|
-- not really an actual node but useful in Jython's typesystem.
|
|||
|
| Suite(stmt* body)
|
|||
|
|
|||
|
stmt = FunctionDef(identifier name, arguments args,
|
|||
|
stmt* body, expr* decorator_list, expr? returns)
|
|||
|
| AsyncFunctionDef(identifier name, arguments args,
|
|||
|
stmt* body, expr* decorator_list, expr? returns)
|
|||
|
|
|||
|
| ClassDef(identifier name,
|
|||
|
expr* bases,
|
|||
|
keyword* keywords,
|
|||
|
stmt* body,
|
|||
|
expr* decorator_list)
|
|||
|
| Return(expr? value)
|
|||
|
|
|||
|
| Delete(expr* targets)
|
|||
|
| Assign(expr* targets, expr value)
|
|||
|
| AugAssign(expr target, operator op, expr value)
|
|||
|
-- 'simple' indicates that we annotate simple name without parens
|
|||
|
| AnnAssign(expr target, expr annotation, expr? value, int simple)
|
|||
|
|
|||
|
-- use 'orelse' because else is a keyword in target languages
|
|||
|
| For(expr target, expr iter, stmt* body, stmt* orelse)
|
|||
|
| AsyncFor(expr target, expr iter, stmt* body, stmt* orelse)
|
|||
|
| While(expr test, stmt* body, stmt* orelse)
|
|||
|
| If(expr test, stmt* body, stmt* orelse)
|
|||
|
| With(withitem* items, stmt* body)
|
|||
|
| AsyncWith(withitem* items, stmt* body)
|
|||
|
|
|||
|
| Raise(expr? exc, expr? cause)
|
|||
|
| Try(stmt* body, excepthandler* handlers, stmt* orelse, stmt* finalbody)
|
|||
|
| Assert(expr test, expr? msg)
|
|||
|
|
|||
|
| Import(alias* names)
|
|||
|
| ImportFrom(identifier? module, alias* names, int? level)
|
|||
|
|
|||
|
| Global(identifier* names)
|
|||
|
| Nonlocal(identifier* names)
|
|||
|
| Expr(expr value)
|
|||
|
| Pass | Break | Continue
|
|||
|
|
|||
|
-- XXX Jython will be different
|
|||
|
-- col_offset is the byte offset in the utf8 string the parser uses
|
|||
|
attributes (int lineno, int col_offset)
|
|||
|
|
|||
|
-- BoolOp() can use left & right?
|
|||
|
expr = BoolOp(boolop op, expr* values)
|
|||
|
| BinOp(expr left, operator op, expr right)
|
|||
|
| UnaryOp(unaryop op, expr operand)
|
|||
|
| Lambda(arguments args, expr body)
|
|||
|
| IfExp(expr test, expr body, expr orelse)
|
|||
|
| Dict(expr* keys, expr* values)
|
|||
|
| Set(expr* elts)
|
|||
|
| ListComp(expr elt, comprehension* generators)
|
|||
|
| SetComp(expr elt, comprehension* generators)
|
|||
|
| DictComp(expr key, expr value, comprehension* generators)
|
|||
|
| GeneratorExp(expr elt, comprehension* generators)
|
|||
|
-- the grammar constrains where yield expressions can occur
|
|||
|
| Await(expr value)
|
|||
|
| Yield(expr? value)
|
|||
|
| YieldFrom(expr value)
|
|||
|
-- need sequences for compare to distinguish between
|
|||
|
-- x < 4 < 3 and (x < 4) < 3
|
|||
|
| Compare(expr left, cmpop* ops, expr* comparators)
|
|||
|
| Call(expr func, expr* args, keyword* keywords)
|
|||
|
| Num(object n) -- a number as a PyObject.
|
|||
|
| Str(string s) -- need to specify raw, unicode, etc?
|
|||
|
| FormattedValue(expr value, int? conversion, expr? format_spec)
|
|||
|
| JoinedStr(expr* values)
|
|||
|
| Bytes(bytes s)
|
|||
|
| NameConstant(singleton value)
|
|||
|
| Ellipsis
|
|||
|
| Constant(constant value)
|
|||
|
|
|||
|
-- the following expression can appear in assignment context
|
|||
|
| Attribute(expr value, identifier attr, expr_context ctx)
|
|||
|
| Subscript(expr value, slice slice, expr_context ctx)
|
|||
|
| Starred(expr value, expr_context ctx)
|
|||
|
| Name(identifier id, expr_context ctx)
|
|||
|
| List(expr* elts, expr_context ctx)
|
|||
|
| Tuple(expr* elts, expr_context ctx)
|
|||
|
|
|||
|
-- col_offset is the byte offset in the utf8 string the parser uses
|
|||
|
attributes (int lineno, int col_offset)
|
|||
|
|
|||
|
expr_context = Load | Store | Del | AugLoad | AugStore | Param
|
|||
|
|
|||
|
slice = Slice(expr? lower, expr? upper, expr? step)
|
|||
|
| ExtSlice(slice* dims)
|
|||
|
| Index(expr value)
|
|||
|
|
|||
|
boolop = And | Or
|
|||
|
|
|||
|
operator = Add | Sub | Mult | MatMult | Div | Mod | Pow | LShift
|
|||
|
| RShift | BitOr | BitXor | BitAnd | FloorDiv
|
|||
|
|
|||
|
unaryop = Invert | Not | UAdd | USub
|
|||
|
|
|||
|
cmpop = Eq | NotEq | Lt | LtE | Gt | GtE | Is | IsNot | In | NotIn
|
|||
|
|
|||
|
comprehension = (expr target, expr iter, expr* ifs, int is_async)
|
|||
|
|
|||
|
excepthandler = ExceptHandler(expr? type, identifier? name, stmt* body)
|
|||
|
attributes (int lineno, int col_offset)
|
|||
|
|
|||
|
arguments = (arg* args, arg? vararg, arg* kwonlyargs, expr* kw_defaults,
|
|||
|
arg? kwarg, expr* defaults)
|
|||
|
|
|||
|
arg = (identifier arg, expr? annotation)
|
|||
|
attributes (int lineno, int col_offset)
|
|||
|
|
|||
|
-- keyword arguments supplied to call (NULL identifier for **kwargs)
|
|||
|
keyword = (identifier? arg, expr value)
|
|||
|
|
|||
|
-- import name with optional 'as' alias.
|
|||
|
alias = (identifier name, identifier? asname)
|
|||
|
|
|||
|
withitem = (expr context_expr, expr? optional_vars)
|
|||
|
}
|
|||
|
|
|||
|
</pre></div>
|
|||
|
</div>
|
|||
|
</div>
|
|||
|
<div class="section" id="ast-helpers">
|
|||
|
<h2><a class="reference internal" href="#module-ast" title="ast: Abstract Syntax Tree classes and manipulation."><code class="xref py py-mod docutils literal notranslate"><span class="pre">ast</span></code></a> Helpers<a class="headerlink" href="#ast-helpers" title="Permalink to this headline">¶</a></h2>
|
|||
|
<p>Apart from the node classes, the <a class="reference internal" href="#module-ast" title="ast: Abstract Syntax Tree classes and manipulation."><code class="xref py py-mod docutils literal notranslate"><span class="pre">ast</span></code></a> module defines these utility functions
|
|||
|
and classes for traversing abstract syntax trees:</p>
|
|||
|
<dl class="function">
|
|||
|
<dt id="ast.parse">
|
|||
|
<code class="descclassname">ast.</code><code class="descname">parse</code><span class="sig-paren">(</span><em>source</em>, <em>filename='<unknown>'</em>, <em>mode='exec'</em><span class="sig-paren">)</span><a class="headerlink" href="#ast.parse" title="Permalink to this definition">¶</a></dt>
|
|||
|
<dd><p>Parse the source into an AST node. Equivalent to <code class="docutils literal notranslate"><span class="pre">compile(source,</span>
|
|||
|
<span class="pre">filename,</span> <span class="pre">mode,</span> <span class="pre">ast.PyCF_ONLY_AST)</span></code>.</p>
|
|||
|
<div class="admonition warning">
|
|||
|
<p class="admonition-title">Warning</p>
|
|||
|
<p>It is possible to crash the Python interpreter with a
|
|||
|
sufficiently large/complex string due to stack depth limitations
|
|||
|
in Python’s AST compiler.</p>
|
|||
|
</div>
|
|||
|
</dd></dl>
|
|||
|
|
|||
|
<dl class="function">
|
|||
|
<dt id="ast.literal_eval">
|
|||
|
<code class="descclassname">ast.</code><code class="descname">literal_eval</code><span class="sig-paren">(</span><em>node_or_string</em><span class="sig-paren">)</span><a class="headerlink" href="#ast.literal_eval" title="Permalink to this definition">¶</a></dt>
|
|||
|
<dd><p>Safely evaluate an expression node or a string containing a Python literal or
|
|||
|
container display. The string or node provided may only consist of the
|
|||
|
following Python literal structures: strings, bytes, numbers, tuples, lists,
|
|||
|
dicts, sets, booleans, and <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
|
|||
|
<p>This can be used for safely evaluating strings containing Python values from
|
|||
|
untrusted sources without the need to parse the values oneself. It is not
|
|||
|
capable of evaluating arbitrarily complex expressions, for example involving
|
|||
|
operators or indexing.</p>
|
|||
|
<div class="admonition warning">
|
|||
|
<p class="admonition-title">Warning</p>
|
|||
|
<p>It is possible to crash the Python interpreter with a
|
|||
|
sufficiently large/complex string due to stack depth limitations
|
|||
|
in Python’s AST compiler.</p>
|
|||
|
</div>
|
|||
|
<div class="versionchanged">
|
|||
|
<p><span class="versionmodified changed">Changed in version 3.2: </span>Now allows bytes and set literals.</p>
|
|||
|
</div>
|
|||
|
</dd></dl>
|
|||
|
|
|||
|
<dl class="function">
|
|||
|
<dt id="ast.get_docstring">
|
|||
|
<code class="descclassname">ast.</code><code class="descname">get_docstring</code><span class="sig-paren">(</span><em>node</em>, <em>clean=True</em><span class="sig-paren">)</span><a class="headerlink" href="#ast.get_docstring" title="Permalink to this definition">¶</a></dt>
|
|||
|
<dd><p>Return the docstring of the given <em>node</em> (which must be a
|
|||
|
<code class="xref py py-class docutils literal notranslate"><span class="pre">FunctionDef</span></code>, <code class="xref py py-class docutils literal notranslate"><span class="pre">AsyncFunctionDef</span></code>, <code class="xref py py-class docutils literal notranslate"><span class="pre">ClassDef</span></code>,
|
|||
|
or <code class="xref py py-class docutils literal notranslate"><span class="pre">Module</span></code> node), or <code class="docutils literal notranslate"><span class="pre">None</span></code> if it has no docstring.
|
|||
|
If <em>clean</em> is true, clean up the docstring’s indentation with
|
|||
|
<a class="reference internal" href="inspect.html#inspect.cleandoc" title="inspect.cleandoc"><code class="xref py py-func docutils literal notranslate"><span class="pre">inspect.cleandoc()</span></code></a>.</p>
|
|||
|
<div class="versionchanged">
|
|||
|
<p><span class="versionmodified changed">Changed in version 3.5: </span><code class="xref py py-class docutils literal notranslate"><span class="pre">AsyncFunctionDef</span></code> is now supported.</p>
|
|||
|
</div>
|
|||
|
</dd></dl>
|
|||
|
|
|||
|
<dl class="function">
|
|||
|
<dt id="ast.fix_missing_locations">
|
|||
|
<code class="descclassname">ast.</code><code class="descname">fix_missing_locations</code><span class="sig-paren">(</span><em>node</em><span class="sig-paren">)</span><a class="headerlink" href="#ast.fix_missing_locations" title="Permalink to this definition">¶</a></dt>
|
|||
|
<dd><p>When you compile a node tree with <a class="reference internal" href="functions.html#compile" title="compile"><code class="xref py py-func docutils literal notranslate"><span class="pre">compile()</span></code></a>, the compiler expects
|
|||
|
<code class="xref py py-attr docutils literal notranslate"><span class="pre">lineno</span></code> and <code class="xref py py-attr docutils literal notranslate"><span class="pre">col_offset</span></code> attributes for every node that supports
|
|||
|
them. This is rather tedious to fill in for generated nodes, so this helper
|
|||
|
adds these attributes recursively where not already set, by setting them to
|
|||
|
the values of the parent node. It works recursively starting at <em>node</em>.</p>
|
|||
|
</dd></dl>
|
|||
|
|
|||
|
<dl class="function">
|
|||
|
<dt id="ast.increment_lineno">
|
|||
|
<code class="descclassname">ast.</code><code class="descname">increment_lineno</code><span class="sig-paren">(</span><em>node</em>, <em>n=1</em><span class="sig-paren">)</span><a class="headerlink" href="#ast.increment_lineno" title="Permalink to this definition">¶</a></dt>
|
|||
|
<dd><p>Increment the line number of each node in the tree starting at <em>node</em> by <em>n</em>.
|
|||
|
This is useful to “move code” to a different location in a file.</p>
|
|||
|
</dd></dl>
|
|||
|
|
|||
|
<dl class="function">
|
|||
|
<dt id="ast.copy_location">
|
|||
|
<code class="descclassname">ast.</code><code class="descname">copy_location</code><span class="sig-paren">(</span><em>new_node</em>, <em>old_node</em><span class="sig-paren">)</span><a class="headerlink" href="#ast.copy_location" title="Permalink to this definition">¶</a></dt>
|
|||
|
<dd><p>Copy source location (<code class="xref py py-attr docutils literal notranslate"><span class="pre">lineno</span></code> and <code class="xref py py-attr docutils literal notranslate"><span class="pre">col_offset</span></code>) from <em>old_node</em>
|
|||
|
to <em>new_node</em> if possible, and return <em>new_node</em>.</p>
|
|||
|
</dd></dl>
|
|||
|
|
|||
|
<dl class="function">
|
|||
|
<dt id="ast.iter_fields">
|
|||
|
<code class="descclassname">ast.</code><code class="descname">iter_fields</code><span class="sig-paren">(</span><em>node</em><span class="sig-paren">)</span><a class="headerlink" href="#ast.iter_fields" title="Permalink to this definition">¶</a></dt>
|
|||
|
<dd><p>Yield a tuple of <code class="docutils literal notranslate"><span class="pre">(fieldname,</span> <span class="pre">value)</span></code> for each field in <code class="docutils literal notranslate"><span class="pre">node._fields</span></code>
|
|||
|
that is present on <em>node</em>.</p>
|
|||
|
</dd></dl>
|
|||
|
|
|||
|
<dl class="function">
|
|||
|
<dt id="ast.iter_child_nodes">
|
|||
|
<code class="descclassname">ast.</code><code class="descname">iter_child_nodes</code><span class="sig-paren">(</span><em>node</em><span class="sig-paren">)</span><a class="headerlink" href="#ast.iter_child_nodes" title="Permalink to this definition">¶</a></dt>
|
|||
|
<dd><p>Yield all direct child nodes of <em>node</em>, that is, all fields that are nodes
|
|||
|
and all items of fields that are lists of nodes.</p>
|
|||
|
</dd></dl>
|
|||
|
|
|||
|
<dl class="function">
|
|||
|
<dt id="ast.walk">
|
|||
|
<code class="descclassname">ast.</code><code class="descname">walk</code><span class="sig-paren">(</span><em>node</em><span class="sig-paren">)</span><a class="headerlink" href="#ast.walk" title="Permalink to this definition">¶</a></dt>
|
|||
|
<dd><p>Recursively yield all descendant nodes in the tree starting at <em>node</em>
|
|||
|
(including <em>node</em> itself), in no specified order. This is useful if you only
|
|||
|
want to modify nodes in place and don’t care about the context.</p>
|
|||
|
</dd></dl>
|
|||
|
|
|||
|
<dl class="class">
|
|||
|
<dt id="ast.NodeVisitor">
|
|||
|
<em class="property">class </em><code class="descclassname">ast.</code><code class="descname">NodeVisitor</code><a class="headerlink" href="#ast.NodeVisitor" title="Permalink to this definition">¶</a></dt>
|
|||
|
<dd><p>A node visitor base class that walks the abstract syntax tree and calls a
|
|||
|
visitor function for every node found. This function may return a value
|
|||
|
which is forwarded by the <a class="reference internal" href="#ast.NodeVisitor.visit" title="ast.NodeVisitor.visit"><code class="xref py py-meth docutils literal notranslate"><span class="pre">visit()</span></code></a> method.</p>
|
|||
|
<p>This class is meant to be subclassed, with the subclass adding visitor
|
|||
|
methods.</p>
|
|||
|
<dl class="method">
|
|||
|
<dt id="ast.NodeVisitor.visit">
|
|||
|
<code class="descname">visit</code><span class="sig-paren">(</span><em>node</em><span class="sig-paren">)</span><a class="headerlink" href="#ast.NodeVisitor.visit" title="Permalink to this definition">¶</a></dt>
|
|||
|
<dd><p>Visit a node. The default implementation calls the method called
|
|||
|
<code class="samp docutils literal notranslate"><span class="pre">self.visit_</span><em><span class="pre">classname</span></em></code> where <em>classname</em> is the name of the node
|
|||
|
class, or <a class="reference internal" href="#ast.NodeVisitor.generic_visit" title="ast.NodeVisitor.generic_visit"><code class="xref py py-meth docutils literal notranslate"><span class="pre">generic_visit()</span></code></a> if that method doesn’t exist.</p>
|
|||
|
</dd></dl>
|
|||
|
|
|||
|
<dl class="method">
|
|||
|
<dt id="ast.NodeVisitor.generic_visit">
|
|||
|
<code class="descname">generic_visit</code><span class="sig-paren">(</span><em>node</em><span class="sig-paren">)</span><a class="headerlink" href="#ast.NodeVisitor.generic_visit" title="Permalink to this definition">¶</a></dt>
|
|||
|
<dd><p>This visitor calls <a class="reference internal" href="#ast.NodeVisitor.visit" title="ast.NodeVisitor.visit"><code class="xref py py-meth docutils literal notranslate"><span class="pre">visit()</span></code></a> on all children of the node.</p>
|
|||
|
<p>Note that child nodes of nodes that have a custom visitor method won’t be
|
|||
|
visited unless the visitor calls <a class="reference internal" href="#ast.NodeVisitor.generic_visit" title="ast.NodeVisitor.generic_visit"><code class="xref py py-meth docutils literal notranslate"><span class="pre">generic_visit()</span></code></a> or visits them
|
|||
|
itself.</p>
|
|||
|
</dd></dl>
|
|||
|
|
|||
|
<p>Don’t use the <a class="reference internal" href="#ast.NodeVisitor" title="ast.NodeVisitor"><code class="xref py py-class docutils literal notranslate"><span class="pre">NodeVisitor</span></code></a> if you want to apply changes to nodes
|
|||
|
during traversal. For this a special visitor exists
|
|||
|
(<a class="reference internal" href="#ast.NodeTransformer" title="ast.NodeTransformer"><code class="xref py py-class docutils literal notranslate"><span class="pre">NodeTransformer</span></code></a>) that allows modifications.</p>
|
|||
|
</dd></dl>
|
|||
|
|
|||
|
<dl class="class">
|
|||
|
<dt id="ast.NodeTransformer">
|
|||
|
<em class="property">class </em><code class="descclassname">ast.</code><code class="descname">NodeTransformer</code><a class="headerlink" href="#ast.NodeTransformer" title="Permalink to this definition">¶</a></dt>
|
|||
|
<dd><p>A <a class="reference internal" href="#ast.NodeVisitor" title="ast.NodeVisitor"><code class="xref py py-class docutils literal notranslate"><span class="pre">NodeVisitor</span></code></a> subclass that walks the abstract syntax tree and
|
|||
|
allows modification of nodes.</p>
|
|||
|
<p>The <a class="reference internal" href="#ast.NodeTransformer" title="ast.NodeTransformer"><code class="xref py py-class docutils literal notranslate"><span class="pre">NodeTransformer</span></code></a> will walk the AST and use the return value of
|
|||
|
the visitor methods to replace or remove the old node. If the return value
|
|||
|
of the visitor method is <code class="docutils literal notranslate"><span class="pre">None</span></code>, the node will be removed from its
|
|||
|
location, otherwise it is replaced with the return value. The return value
|
|||
|
may be the original node in which case no replacement takes place.</p>
|
|||
|
<p>Here is an example transformer that rewrites all occurrences of name lookups
|
|||
|
(<code class="docutils literal notranslate"><span class="pre">foo</span></code>) to <code class="docutils literal notranslate"><span class="pre">data['foo']</span></code>:</p>
|
|||
|
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">RewriteName</span><span class="p">(</span><span class="n">NodeTransformer</span><span class="p">):</span>
|
|||
|
|
|||
|
<span class="k">def</span> <span class="nf">visit_Name</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">node</span><span class="p">):</span>
|
|||
|
<span class="k">return</span> <span class="n">copy_location</span><span class="p">(</span><span class="n">Subscript</span><span class="p">(</span>
|
|||
|
<span class="n">value</span><span class="o">=</span><span class="n">Name</span><span class="p">(</span><span class="nb">id</span><span class="o">=</span><span class="s1">'data'</span><span class="p">,</span> <span class="n">ctx</span><span class="o">=</span><span class="n">Load</span><span class="p">()),</span>
|
|||
|
<span class="nb">slice</span><span class="o">=</span><span class="n">Index</span><span class="p">(</span><span class="n">value</span><span class="o">=</span><span class="n">Str</span><span class="p">(</span><span class="n">s</span><span class="o">=</span><span class="n">node</span><span class="o">.</span><span class="n">id</span><span class="p">)),</span>
|
|||
|
<span class="n">ctx</span><span class="o">=</span><span class="n">node</span><span class="o">.</span><span class="n">ctx</span>
|
|||
|
<span class="p">),</span> <span class="n">node</span><span class="p">)</span>
|
|||
|
</pre></div>
|
|||
|
</div>
|
|||
|
<p>Keep in mind that if the node you’re operating on has child nodes you must
|
|||
|
either transform the child nodes yourself or call the <code class="xref py py-meth docutils literal notranslate"><span class="pre">generic_visit()</span></code>
|
|||
|
method for the node first.</p>
|
|||
|
<p>For nodes that were part of a collection of statements (that applies to all
|
|||
|
statement nodes), the visitor may also return a list of nodes rather than
|
|||
|
just a single node.</p>
|
|||
|
<p>Usually you use the transformer like this:</p>
|
|||
|
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">node</span> <span class="o">=</span> <span class="n">YourTransformer</span><span class="p">()</span><span class="o">.</span><span class="n">visit</span><span class="p">(</span><span class="n">node</span><span class="p">)</span>
|
|||
|
</pre></div>
|
|||
|
</div>
|
|||
|
</dd></dl>
|
|||
|
|
|||
|
<dl class="function">
|
|||
|
<dt id="ast.dump">
|
|||
|
<code class="descclassname">ast.</code><code class="descname">dump</code><span class="sig-paren">(</span><em>node</em>, <em>annotate_fields=True</em>, <em>include_attributes=False</em><span class="sig-paren">)</span><a class="headerlink" href="#ast.dump" title="Permalink to this definition">¶</a></dt>
|
|||
|
<dd><p>Return a formatted dump of the tree in <em>node</em>. This is mainly useful for
|
|||
|
debugging purposes. The returned string will show the names and the values
|
|||
|
for fields. This makes the code impossible to evaluate, so if evaluation is
|
|||
|
wanted <em>annotate_fields</em> must be set to <code class="docutils literal notranslate"><span class="pre">False</span></code>. Attributes such as line
|
|||
|
numbers and column offsets are not dumped by default. If this is wanted,
|
|||
|
<em>include_attributes</em> can be set to <code class="docutils literal notranslate"><span class="pre">True</span></code>.</p>
|
|||
|
</dd></dl>
|
|||
|
|
|||
|
<div class="admonition seealso">
|
|||
|
<p class="admonition-title">See also</p>
|
|||
|
<p><a class="reference external" href="https://greentreesnakes.readthedocs.io/">Green Tree Snakes</a>, an external documentation resource, has good
|
|||
|
details on working with Python ASTs.</p>
|
|||
|
</div>
|
|||
|
</div>
|
|||
|
</div>
|
|||
|
|
|||
|
|
|||
|
</div>
|
|||
|
</div>
|
|||
|
</div>
|
|||
|
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
|||
|
<div class="sphinxsidebarwrapper">
|
|||
|
<h3><a href="../contents.html">Table of Contents</a></h3>
|
|||
|
<ul>
|
|||
|
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">ast</span></code> — Abstract Syntax Trees</a><ul>
|
|||
|
<li><a class="reference internal" href="#node-classes">Node classes</a></li>
|
|||
|
<li><a class="reference internal" href="#abstract-grammar">Abstract Grammar</a></li>
|
|||
|
<li><a class="reference internal" href="#ast-helpers"><code class="xref py py-mod docutils literal notranslate"><span class="pre">ast</span></code> Helpers</a></li>
|
|||
|
</ul>
|
|||
|
</li>
|
|||
|
</ul>
|
|||
|
|
|||
|
<h4>Previous topic</h4>
|
|||
|
<p class="topless"><a href="parser.html"
|
|||
|
title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">parser</span></code> — Access Python parse trees</a></p>
|
|||
|
<h4>Next topic</h4>
|
|||
|
<p class="topless"><a href="symtable.html"
|
|||
|
title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">symtable</span></code> — Access to the compiler’s symbol tables</a></p>
|
|||
|
<div role="note" aria-label="source link">
|
|||
|
<h3>This Page</h3>
|
|||
|
<ul class="this-page-menu">
|
|||
|
<li><a href="../bugs.html">Report a Bug</a></li>
|
|||
|
<li>
|
|||
|
<a href="https://github.com/python/cpython/blob/3.7/Doc/library/ast.rst"
|
|||
|
rel="nofollow">Show Source
|
|||
|
</a>
|
|||
|
</li>
|
|||
|
</ul>
|
|||
|
</div>
|
|||
|
</div>
|
|||
|
</div>
|
|||
|
<div class="clearer"></div>
|
|||
|
</div>
|
|||
|
<div class="related" role="navigation" aria-label="related navigation">
|
|||
|
<h3>Navigation</h3>
|
|||
|
<ul>
|
|||
|
<li class="right" style="margin-right: 10px">
|
|||
|
<a href="../genindex.html" title="General Index"
|
|||
|
>index</a></li>
|
|||
|
<li class="right" >
|
|||
|
<a href="../py-modindex.html" title="Python Module Index"
|
|||
|
>modules</a> |</li>
|
|||
|
<li class="right" >
|
|||
|
<a href="symtable.html" title="symtable — Access to the compiler’s symbol tables"
|
|||
|
>next</a> |</li>
|
|||
|
<li class="right" >
|
|||
|
<a href="parser.html" title="parser — Access Python parse trees"
|
|||
|
>previous</a> |</li>
|
|||
|
<li><img src="../_static/py.png" alt=""
|
|||
|
style="vertical-align: middle; margin-top: -1px"/></li>
|
|||
|
<li><a href="https://www.python.org/">Python</a> »</li>
|
|||
|
<li>
|
|||
|
<span class="language_switcher_placeholder">en</span>
|
|||
|
<span class="version_switcher_placeholder">3.7.4</span>
|
|||
|
<a href="../index.html">Documentation </a> »
|
|||
|
</li>
|
|||
|
|
|||
|
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
|
|||
|
<li class="nav-item nav-item-2"><a href="language.html" >Python Language Services</a> »</li>
|
|||
|
<li class="right">
|
|||
|
|
|||
|
|
|||
|
<div class="inline-search" style="display: none" role="search">
|
|||
|
<form class="inline-search" action="../search.html" method="get">
|
|||
|
<input placeholder="Quick search" type="text" name="q" />
|
|||
|
<input type="submit" value="Go" />
|
|||
|
<input type="hidden" name="check_keywords" value="yes" />
|
|||
|
<input type="hidden" name="area" value="default" />
|
|||
|
</form>
|
|||
|
</div>
|
|||
|
<script type="text/javascript">$('.inline-search').show(0);</script>
|
|||
|
|
|
|||
|
</li>
|
|||
|
|
|||
|
</ul>
|
|||
|
</div>
|
|||
|
<div class="footer">
|
|||
|
© <a href="../copyright.html">Copyright</a> 2001-2019, Python Software Foundation.
|
|||
|
<br />
|
|||
|
The Python Software Foundation is a non-profit corporation.
|
|||
|
<a href="https://www.python.org/psf/donations/">Please donate.</a>
|
|||
|
<br />
|
|||
|
Last updated on Jul 13, 2019.
|
|||
|
<a href="../bugs.html">Found a bug</a>?
|
|||
|
<br />
|
|||
|
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.0.1.
|
|||
|
</div>
|
|||
|
|
|||
|
</body>
|
|||
|
</html>
|