| Current File : //usr/share/doc/python-py-1.4.32/html/code.html |
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>py.code: higher level python code and introspection objects — py 1.4.32 documentation</title>
<link rel="stylesheet" href="_static/default.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: '1.4.32',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</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>
<link rel="top" title="py 1.4.32 documentation" href="index.html" />
<link rel="next" title="py.io" href="io.html" />
<link rel="prev" title="py.path" href="path.html" />
</head>
<body>
<div class="related">
<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="io.html" title="py.io"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="path.html" title="py.path"
accesskey="P">previous</a> |</li>
<li><a href="index.html">py 1.4.32 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="py-code-higher-level-python-code-and-introspection-objects">
<h1>py.code: higher level python code and introspection objects<a class="headerlink" href="#py-code-higher-level-python-code-and-introspection-objects" title="Permalink to this headline">¶</a></h1>
<p><tt class="docutils literal"><span class="pre">py.code</span></tt> provides higher level APIs and objects for Code, Frame, Traceback,
ExceptionInfo and source code construction. The <tt class="docutils literal"><span class="pre">py.code</span></tt> library
tries to simplify accessing the code objects as well as creating them.
There is a small set of interfaces a user needs to deal with, all nicely
bundled together, and with a rich set of ‘Pythonic’ functionality.</p>
<div class="section" id="contents-of-the-library">
<h2>Contents of the library<a class="headerlink" href="#contents-of-the-library" title="Permalink to this headline">¶</a></h2>
<p>Every object in the <tt class="docutils literal"><span class="pre">py.code</span></tt> library wraps a code Python object related
to code objects, source code, frames and tracebacks: the <tt class="docutils literal"><span class="pre">py.code.Code</span></tt>
class wraps code objects, <tt class="docutils literal"><span class="pre">py.code.Source</span></tt> source snippets,
<tt class="docutils literal"><span class="pre">py.code.Traceback`</span> <span class="pre">exception</span> <span class="pre">tracebacks,</span> <span class="pre">``py.code.Frame</span></tt> frame
objects (as found in e.g. tracebacks) and <tt class="docutils literal"><span class="pre">py.code.ExceptionInfo</span></tt> the
tuple provided by sys.exc_info() (containing exception and traceback
information when an exception occurs). Also in the library is a helper function
<tt class="docutils literal"><span class="pre">py.code.compile()</span></tt> that provides the same functionality as Python’s
built-in ‘compile()’ function, but returns a wrapped code object.</p>
</div>
<div class="section" id="the-wrappers">
<h2>The wrappers<a class="headerlink" href="#the-wrappers" title="Permalink to this headline">¶</a></h2>
<div class="section" id="py-code-code">
<h3><tt class="docutils literal"><span class="pre">py.code.Code</span></tt><a class="headerlink" href="#py-code-code" title="Permalink to this headline">¶</a></h3>
<p>Code objects are instantiated with a code object or a callable as argument,
and provide functionality to compare themselves with other Code objects, get to
the source file or its contents, create new Code objects from scratch, etc.</p>
<p>A quick example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">py</span>
<span class="gp">>>> </span><span class="n">c</span> <span class="o">=</span> <span class="n">py</span><span class="o">.</span><span class="n">code</span><span class="o">.</span><span class="n">Code</span><span class="p">(</span><span class="n">py</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">local</span><span class="o">.</span><span class="n">read</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">c</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">basename</span>
<span class="go">'common.py'</span>
<span class="gp">>>> </span><span class="nb">isinstance</span><span class="p">(</span><span class="n">c</span><span class="o">.</span><span class="n">source</span><span class="p">(),</span> <span class="n">py</span><span class="o">.</span><span class="n">code</span><span class="o">.</span><span class="n">Source</span><span class="p">)</span>
<span class="go">True</span>
<span class="gp">>>> </span><span class="nb">str</span><span class="p">(</span><span class="n">c</span><span class="o">.</span><span class="n">source</span><span class="p">())</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="s">'</span><span class="se">\n</span><span class="s">'</span><span class="p">)[</span><span class="mi">0</span><span class="p">]</span>
<span class="go">"def read(self, mode='r'):"</span>
</pre></div>
</div>
<dl class="class">
<dt id="py.code.Code">
<em class="property">class </em><tt class="descclassname">py.code.</tt><tt class="descname">Code</tt><big>(</big><em>rawcode</em><big>)</big><a class="headerlink" href="#py.code.Code" title="Permalink to this definition">¶</a></dt>
<dd><p>wrapper around Python code objects</p>
<dl class="attribute">
<dt id="py.code.Code.path">
<tt class="descname">path</tt><a class="headerlink" href="#py.code.Code.path" title="Permalink to this definition">¶</a></dt>
<dd><p>return a path object pointing to source code (note that it
might not point to an actually existing file).</p>
</dd></dl>
<dl class="attribute">
<dt id="py.code.Code.fullsource">
<tt class="descname">fullsource</tt><a class="headerlink" href="#py.code.Code.fullsource" title="Permalink to this definition">¶</a></dt>
<dd><p>return a py.code.Source object for the full source file of the code</p>
</dd></dl>
<dl class="method">
<dt id="py.code.Code.source">
<tt class="descname">source</tt><big>(</big><big>)</big><a class="headerlink" href="#py.code.Code.source" title="Permalink to this definition">¶</a></dt>
<dd><p>return a py.code.Source object for the code object’s source only</p>
</dd></dl>
<dl class="method">
<dt id="py.code.Code.getargs">
<tt class="descname">getargs</tt><big>(</big><em>var=False</em><big>)</big><a class="headerlink" href="#py.code.Code.getargs" title="Permalink to this definition">¶</a></dt>
<dd><p>return a tuple with the argument names for the code object</p>
<p>if ‘var’ is set True also return the names of the variable and
keyword arguments when present</p>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="py-code-source">
<h3><tt class="docutils literal"><span class="pre">py.code.Source</span></tt><a class="headerlink" href="#py-code-source" title="Permalink to this headline">¶</a></h3>
<p>Source objects wrap snippets of Python source code, providing a simple yet
powerful interface to read, deindent, slice, compare, compile and manipulate
them, things that are not so easy in core Python.</p>
<p>Example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">s</span> <span class="o">=</span> <span class="n">py</span><span class="o">.</span><span class="n">code</span><span class="o">.</span><span class="n">Source</span><span class="p">(</span><span class="s">"""</span><span class="se">\</span>
<span class="gp">... </span><span class="s"> def foo():</span>
<span class="gp">... </span><span class="s"> print "foo"</span>
<span class="gp">... </span><span class="s">"""</span><span class="p">)</span>
<span class="gp">>>> </span><span class="nb">str</span><span class="p">(</span><span class="n">s</span><span class="p">)</span><span class="o">.</span><span class="n">startswith</span><span class="p">(</span><span class="s">'def'</span><span class="p">)</span> <span class="c"># automatic de-indentation!</span>
<span class="go">True</span>
<span class="gp">>>> </span><span class="n">s</span><span class="o">.</span><span class="n">isparseable</span><span class="p">()</span>
<span class="go">True</span>
<span class="gp">>>> </span><span class="n">sub</span> <span class="o">=</span> <span class="n">s</span><span class="o">.</span><span class="n">getstatement</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span> <span class="c"># get the statement starting at line 1</span>
<span class="gp">>>> </span><span class="nb">str</span><span class="p">(</span><span class="n">sub</span><span class="p">)</span><span class="o">.</span><span class="n">strip</span><span class="p">()</span> <span class="c"># XXX why is the strip() required?!?</span>
<span class="go">'print "foo"'</span>
</pre></div>
</div>
<dl class="class">
<dt id="py.code.Source">
<em class="property">class </em><tt class="descclassname">py.code.</tt><tt class="descname">Source</tt><big>(</big><em>*parts</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#py.code.Source" title="Permalink to this definition">¶</a></dt>
<dd><p>a immutable object holding a source code fragment,
possibly deindenting it.</p>
<dl class="method">
<dt id="py.code.Source.strip">
<tt class="descname">strip</tt><big>(</big><big>)</big><a class="headerlink" href="#py.code.Source.strip" title="Permalink to this definition">¶</a></dt>
<dd><p>return new source object with trailing
and leading blank lines removed.</p>
</dd></dl>
<dl class="method">
<dt id="py.code.Source.putaround">
<tt class="descname">putaround</tt><big>(</big><em>before=''</em>, <em>after=''</em>, <em>indent=' '</em><big>)</big><a class="headerlink" href="#py.code.Source.putaround" title="Permalink to this definition">¶</a></dt>
<dd><p>return a copy of the source object with
‘before’ and ‘after’ wrapped around it.</p>
</dd></dl>
<dl class="method">
<dt id="py.code.Source.indent">
<tt class="descname">indent</tt><big>(</big><em>indent=' '</em><big>)</big><a class="headerlink" href="#py.code.Source.indent" title="Permalink to this definition">¶</a></dt>
<dd><p>return a copy of the source object with
all lines indented by the given indent-string.</p>
</dd></dl>
<dl class="method">
<dt id="py.code.Source.getstatement">
<tt class="descname">getstatement</tt><big>(</big><em>lineno</em>, <em>assertion=False</em><big>)</big><a class="headerlink" href="#py.code.Source.getstatement" title="Permalink to this definition">¶</a></dt>
<dd><p>return Source statement which contains the
given linenumber (counted from 0).</p>
</dd></dl>
<dl class="method">
<dt id="py.code.Source.getstatementrange">
<tt class="descname">getstatementrange</tt><big>(</big><em>lineno</em>, <em>assertion=False</em><big>)</big><a class="headerlink" href="#py.code.Source.getstatementrange" title="Permalink to this definition">¶</a></dt>
<dd><p>return (start, end) tuple which spans the minimal
statement region which containing the given lineno.</p>
</dd></dl>
<dl class="method">
<dt id="py.code.Source.deindent">
<tt class="descname">deindent</tt><big>(</big><em>offset=None</em><big>)</big><a class="headerlink" href="#py.code.Source.deindent" title="Permalink to this definition">¶</a></dt>
<dd><p>return a new source object deindented by offset.
If offset is None then guess an indentation offset from
the first non-blank line. Subsequent lines which have a
lower indentation offset will be copied verbatim as
they are assumed to be part of multilines.</p>
</dd></dl>
<dl class="method">
<dt id="py.code.Source.isparseable">
<tt class="descname">isparseable</tt><big>(</big><em>deindent=True</em><big>)</big><a class="headerlink" href="#py.code.Source.isparseable" title="Permalink to this definition">¶</a></dt>
<dd><p>return True if source is parseable, heuristically
deindenting it by default.</p>
</dd></dl>
<dl class="method">
<dt id="py.code.Source.compile">
<tt class="descname">compile</tt><big>(</big><em>filename=None</em>, <em>mode='exec'</em>, <em>flag=0</em>, <em>dont_inherit=0</em>, <em>_genframe=None</em><big>)</big><a class="headerlink" href="#py.code.Source.compile" title="Permalink to this definition">¶</a></dt>
<dd><p>return compiled code object. if filename is None
invent an artificial filename which displays
the source/line position of the caller frame.</p>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="py-code-traceback">
<h3><tt class="docutils literal"><span class="pre">py.code.Traceback</span></tt><a class="headerlink" href="#py-code-traceback" title="Permalink to this headline">¶</a></h3>
<p>Tracebacks are usually not very easy to examine, you need to access certain
somewhat hidden attributes of the traceback’s items (resulting in expressions
such as ‘fname = tb.tb_next.tb_frame.f_code.co_filename’). The Traceback
interface (and its TracebackItem children) tries to improve this.</p>
<p>Example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">sys</span>
<span class="gp">>>> </span><span class="k">try</span><span class="p">:</span>
<span class="gp">... </span> <span class="n">py</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">local</span><span class="p">(</span><span class="mi">100</span><span class="p">)</span> <span class="c"># illegal argument</span>
<span class="gp">... </span><span class="k">except</span><span class="p">:</span>
<span class="gp">... </span> <span class="n">exc</span><span class="p">,</span> <span class="n">e</span><span class="p">,</span> <span class="n">tb</span> <span class="o">=</span> <span class="n">sys</span><span class="o">.</span><span class="n">exc_info</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">t</span> <span class="o">=</span> <span class="n">py</span><span class="o">.</span><span class="n">code</span><span class="o">.</span><span class="n">Traceback</span><span class="p">(</span><span class="n">tb</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">first</span> <span class="o">=</span> <span class="n">t</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="c"># get the second entry (first is in this doc)</span>
<span class="gp">>>> </span><span class="n">first</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">basename</span> <span class="c"># second is in py/path/local.py</span>
<span class="go">'local.py'</span>
<span class="gp">>>> </span><span class="nb">isinstance</span><span class="p">(</span><span class="n">first</span><span class="o">.</span><span class="n">statement</span><span class="p">,</span> <span class="n">py</span><span class="o">.</span><span class="n">code</span><span class="o">.</span><span class="n">Source</span><span class="p">)</span>
<span class="go">True</span>
<span class="gp">>>> </span><span class="nb">str</span><span class="p">(</span><span class="n">first</span><span class="o">.</span><span class="n">statement</span><span class="p">)</span><span class="o">.</span><span class="n">strip</span><span class="p">()</span><span class="o">.</span><span class="n">startswith</span><span class="p">(</span><span class="s">'raise ValueError'</span><span class="p">)</span>
<span class="go">True</span>
</pre></div>
</div>
<dl class="class">
<dt id="py.code.Traceback">
<em class="property">class </em><tt class="descclassname">py.code.</tt><tt class="descname">Traceback</tt><big>(</big><em>tb</em><big>)</big><a class="headerlink" href="#py.code.Traceback" title="Permalink to this definition">¶</a></dt>
<dd><p>Traceback objects encapsulate and offer higher level
access to Traceback entries.</p>
<dl class="attribute">
<dt id="py.code.Traceback.Entry">
<tt class="descname">Entry</tt><a class="headerlink" href="#py.code.Traceback.Entry" title="Permalink to this definition">¶</a></dt>
<dd><p>alias of <tt class="xref py py-class docutils literal"><span class="pre">TracebackEntry</span></tt></p>
</dd></dl>
<dl class="method">
<dt id="py.code.Traceback.cut">
<tt class="descname">cut</tt><big>(</big><em>path=None</em>, <em>lineno=None</em>, <em>firstlineno=None</em>, <em>excludepath=None</em><big>)</big><a class="headerlink" href="#py.code.Traceback.cut" title="Permalink to this definition">¶</a></dt>
<dd><p>return a Traceback instance wrapping part of this Traceback</p>
<p>by provding any combination of path, lineno and firstlineno, the
first frame to start the to-be-returned traceback is determined</p>
<p>this allows cutting the first part of a Traceback instance e.g.
for formatting reasons (removing some uninteresting bits that deal
with handling of the exception/traceback)</p>
</dd></dl>
<dl class="method">
<dt id="py.code.Traceback.filter">
<tt class="descname">filter</tt><big>(</big><em>fn=<function <lambda> at 0x32c2230></em><big>)</big><a class="headerlink" href="#py.code.Traceback.filter" title="Permalink to this definition">¶</a></dt>
<dd><p>return a Traceback instance with certain items removed</p>
<p>fn is a function that gets a single argument, a TracebackItem
instance, and should return True when the item should be added
to the Traceback, False when not</p>
<p>by default this removes all the TracebackItems which are hidden
(see ishidden() above)</p>
</dd></dl>
<dl class="method">
<dt id="py.code.Traceback.getcrashentry">
<tt class="descname">getcrashentry</tt><big>(</big><big>)</big><a class="headerlink" href="#py.code.Traceback.getcrashentry" title="Permalink to this definition">¶</a></dt>
<dd><p>return last non-hidden traceback entry that lead
to the exception of a traceback.</p>
</dd></dl>
<dl class="method">
<dt id="py.code.Traceback.recursionindex">
<tt class="descname">recursionindex</tt><big>(</big><big>)</big><a class="headerlink" href="#py.code.Traceback.recursionindex" title="Permalink to this definition">¶</a></dt>
<dd><p>return the index of the frame/TracebackItem where recursion
originates if appropriate, None if no recursion occurred</p>
</dd></dl>
<dl class="method">
<dt id="py.code.Traceback.append">
<tt class="descname">append</tt><big>(</big><big>)</big><a class="headerlink" href="#py.code.Traceback.append" title="Permalink to this definition">¶</a></dt>
<dd><p>L.append(object) – append object to end</p>
</dd></dl>
<dl class="method">
<dt id="py.code.Traceback.count">
<tt class="descname">count</tt><big>(</big><em>value</em><big>)</big> → integer -- return number of occurrences of value<a class="headerlink" href="#py.code.Traceback.count" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="method">
<dt id="py.code.Traceback.extend">
<tt class="descname">extend</tt><big>(</big><big>)</big><a class="headerlink" href="#py.code.Traceback.extend" title="Permalink to this definition">¶</a></dt>
<dd><p>L.extend(iterable) – extend list by appending elements from the iterable</p>
</dd></dl>
<dl class="method">
<dt id="py.code.Traceback.index">
<tt class="descname">index</tt><big>(</big><em>value</em><span class="optional">[</span>, <em>start</em><span class="optional">[</span>, <em>stop</em><span class="optional">]</span><span class="optional">]</span><big>)</big> → integer -- return first index of value.<a class="headerlink" href="#py.code.Traceback.index" title="Permalink to this definition">¶</a></dt>
<dd><p>Raises ValueError if the value is not present.</p>
</dd></dl>
<dl class="method">
<dt id="py.code.Traceback.insert">
<tt class="descname">insert</tt><big>(</big><big>)</big><a class="headerlink" href="#py.code.Traceback.insert" title="Permalink to this definition">¶</a></dt>
<dd><p>L.insert(index, object) – insert object before index</p>
</dd></dl>
<dl class="method">
<dt id="py.code.Traceback.pop">
<tt class="descname">pop</tt><big>(</big><span class="optional">[</span><em>index</em><span class="optional">]</span><big>)</big> → item -- remove and return item at index (default last).<a class="headerlink" href="#py.code.Traceback.pop" title="Permalink to this definition">¶</a></dt>
<dd><p>Raises IndexError if list is empty or index is out of range.</p>
</dd></dl>
<dl class="method">
<dt id="py.code.Traceback.remove">
<tt class="descname">remove</tt><big>(</big><big>)</big><a class="headerlink" href="#py.code.Traceback.remove" title="Permalink to this definition">¶</a></dt>
<dd><p>L.remove(value) – remove first occurrence of value.
Raises ValueError if the value is not present.</p>
</dd></dl>
<dl class="method">
<dt id="py.code.Traceback.reverse">
<tt class="descname">reverse</tt><big>(</big><big>)</big><a class="headerlink" href="#py.code.Traceback.reverse" title="Permalink to this definition">¶</a></dt>
<dd><p>L.reverse() – reverse <em>IN PLACE</em></p>
</dd></dl>
<dl class="method">
<dt id="py.code.Traceback.sort">
<tt class="descname">sort</tt><big>(</big><big>)</big><a class="headerlink" href="#py.code.Traceback.sort" title="Permalink to this definition">¶</a></dt>
<dd><p>L.sort(cmp=None, key=None, reverse=False) – stable sort <em>IN PLACE</em>;
cmp(x, y) -> -1, 0, 1</p>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="py-code-frame">
<h3><tt class="docutils literal"><span class="pre">py.code.Frame</span></tt><a class="headerlink" href="#py-code-frame" title="Permalink to this headline">¶</a></h3>
<p>Frame wrappers are used in <tt class="docutils literal"><span class="pre">py.code.Traceback</span></tt> items, and will usually not
directly be instantiated. They provide some nice methods to evaluate code
‘inside’ the frame (using the frame’s local variables), get to the underlying
code (frames have a code attribute that points to a <tt class="docutils literal"><span class="pre">py.code.Code</span></tt> object)
and examine the arguments.</p>
<p>Example (using the ‘first’ TracebackItem instance created above):</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">frame</span> <span class="o">=</span> <span class="n">first</span><span class="o">.</span><span class="n">frame</span>
<span class="gp">>>> </span><span class="nb">isinstance</span><span class="p">(</span><span class="n">frame</span><span class="o">.</span><span class="n">code</span><span class="p">,</span> <span class="n">py</span><span class="o">.</span><span class="n">code</span><span class="o">.</span><span class="n">Code</span><span class="p">)</span>
<span class="go">True</span>
<span class="gp">>>> </span><span class="nb">isinstance</span><span class="p">(</span><span class="n">frame</span><span class="o">.</span><span class="n">eval</span><span class="p">(</span><span class="s">'self'</span><span class="p">),</span> <span class="n">py</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">local</span><span class="p">)</span>
<span class="go">True</span>
<span class="gp">>>> </span><span class="p">[</span><span class="n">namevalue</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="k">for</span> <span class="n">namevalue</span> <span class="ow">in</span> <span class="n">frame</span><span class="o">.</span><span class="n">getargs</span><span class="p">()]</span>
<span class="go">['cls', 'path']</span>
</pre></div>
</div>
<dl class="class">
<dt id="py.code.Frame">
<em class="property">class </em><tt class="descclassname">py.code.</tt><tt class="descname">Frame</tt><big>(</big><em>frame</em><big>)</big><a class="headerlink" href="#py.code.Frame" title="Permalink to this definition">¶</a></dt>
<dd><p>Wrapper around a Python frame holding f_locals and f_globals
in which expressions can be evaluated.</p>
<dl class="attribute">
<dt id="py.code.Frame.statement">
<tt class="descname">statement</tt><a class="headerlink" href="#py.code.Frame.statement" title="Permalink to this definition">¶</a></dt>
<dd><p>statement this frame is at</p>
</dd></dl>
<dl class="method">
<dt id="py.code.Frame.eval">
<tt class="descname">eval</tt><big>(</big><em>code</em>, <em>**vars</em><big>)</big><a class="headerlink" href="#py.code.Frame.eval" title="Permalink to this definition">¶</a></dt>
<dd><p>evaluate ‘code’ in the frame</p>
<p>‘vars’ are optional additional local variables</p>
<p>returns the result of the evaluation</p>
</dd></dl>
<dl class="method">
<dt id="py.code.Frame.exec_">
<tt class="descname">exec_</tt><big>(</big><em>code</em>, <em>**vars</em><big>)</big><a class="headerlink" href="#py.code.Frame.exec_" title="Permalink to this definition">¶</a></dt>
<dd><p>exec ‘code’ in the frame</p>
<p>‘vars’ are optiona; additional local variables</p>
</dd></dl>
<dl class="method">
<dt id="py.code.Frame.repr">
<tt class="descname">repr</tt><big>(</big><em>object</em><big>)</big><a class="headerlink" href="#py.code.Frame.repr" title="Permalink to this definition">¶</a></dt>
<dd><p>return a ‘safe’ (non-recursive, one-line) string repr for ‘object’</p>
</dd></dl>
<dl class="method">
<dt id="py.code.Frame.getargs">
<tt class="descname">getargs</tt><big>(</big><em>var=False</em><big>)</big><a class="headerlink" href="#py.code.Frame.getargs" title="Permalink to this definition">¶</a></dt>
<dd><p>return a list of tuples (name, value) for all arguments</p>
<p>if ‘var’ is set True also include the variable and keyword
arguments when present</p>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="py-code-exceptioninfo">
<h3><tt class="docutils literal"><span class="pre">py.code.ExceptionInfo</span></tt><a class="headerlink" href="#py-code-exceptioninfo" title="Permalink to this headline">¶</a></h3>
<p>A wrapper around the tuple returned by sys.exc_info() (will call sys.exc_info()
itself if the tuple is not provided as an argument), provides some handy
attributes to easily access the traceback and exception string.</p>
<p>Example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">sys</span>
<span class="gp">>>> </span><span class="k">try</span><span class="p">:</span>
<span class="gp">... </span> <span class="n">foobar</span><span class="p">()</span>
<span class="gp">... </span><span class="k">except</span><span class="p">:</span>
<span class="gp">... </span> <span class="n">excinfo</span> <span class="o">=</span> <span class="n">py</span><span class="o">.</span><span class="n">code</span><span class="o">.</span><span class="n">ExceptionInfo</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">excinfo</span><span class="o">.</span><span class="n">typename</span>
<span class="go">'NameError'</span>
<span class="gp">>>> </span><span class="nb">isinstance</span><span class="p">(</span><span class="n">excinfo</span><span class="o">.</span><span class="n">traceback</span><span class="p">,</span> <span class="n">py</span><span class="o">.</span><span class="n">code</span><span class="o">.</span><span class="n">Traceback</span><span class="p">)</span>
<span class="go">True</span>
<span class="gp">>>> </span><span class="n">excinfo</span><span class="o">.</span><span class="n">exconly</span><span class="p">()</span>
<span class="go">"NameError: name 'foobar' is not defined"</span>
</pre></div>
</div>
<dl class="class">
<dt id="py.code.ExceptionInfo">
<em class="property">class </em><tt class="descclassname">py.code.</tt><tt class="descname">ExceptionInfo</tt><big>(</big><em>tup=None</em>, <em>exprinfo=None</em><big>)</big><a class="headerlink" href="#py.code.ExceptionInfo" title="Permalink to this definition">¶</a></dt>
<dd><p>wraps sys.exc_info() objects and offers
help for navigating the traceback.</p>
<dl class="attribute">
<dt id="py.code.ExceptionInfo.type">
<tt class="descname">type</tt><em class="property"> = None</em><a class="headerlink" href="#py.code.ExceptionInfo.type" title="Permalink to this definition">¶</a></dt>
<dd><p>the exception class</p>
</dd></dl>
<dl class="attribute">
<dt id="py.code.ExceptionInfo.value">
<tt class="descname">value</tt><em class="property"> = None</em><a class="headerlink" href="#py.code.ExceptionInfo.value" title="Permalink to this definition">¶</a></dt>
<dd><p>the exception instance</p>
</dd></dl>
<dl class="attribute">
<dt id="py.code.ExceptionInfo.tb">
<tt class="descname">tb</tt><em class="property"> = None</em><a class="headerlink" href="#py.code.ExceptionInfo.tb" title="Permalink to this definition">¶</a></dt>
<dd><p>the exception raw traceback</p>
</dd></dl>
<dl class="attribute">
<dt id="py.code.ExceptionInfo.typename">
<tt class="descname">typename</tt><em class="property"> = None</em><a class="headerlink" href="#py.code.ExceptionInfo.typename" title="Permalink to this definition">¶</a></dt>
<dd><p>the exception type name</p>
</dd></dl>
<dl class="attribute">
<dt id="py.code.ExceptionInfo.traceback">
<tt class="descname">traceback</tt><em class="property"> = None</em><a class="headerlink" href="#py.code.ExceptionInfo.traceback" title="Permalink to this definition">¶</a></dt>
<dd><p>the exception traceback (py.code.Traceback instance)</p>
</dd></dl>
<dl class="method">
<dt id="py.code.ExceptionInfo.exconly">
<tt class="descname">exconly</tt><big>(</big><em>tryshort=False</em><big>)</big><a class="headerlink" href="#py.code.ExceptionInfo.exconly" title="Permalink to this definition">¶</a></dt>
<dd><p>return the exception as a string</p>
<p>when ‘tryshort’ resolves to True, and the exception is a
py.code._AssertionError, only the actual exception part of
the exception representation is returned (so ‘AssertionError: ‘ is
removed from the beginning)</p>
</dd></dl>
<dl class="method">
<dt id="py.code.ExceptionInfo.errisinstance">
<tt class="descname">errisinstance</tt><big>(</big><em>exc</em><big>)</big><a class="headerlink" href="#py.code.ExceptionInfo.errisinstance" title="Permalink to this definition">¶</a></dt>
<dd><p>return True if the exception is an instance of exc</p>
</dd></dl>
<dl class="method">
<dt id="py.code.ExceptionInfo.getrepr">
<tt class="descname">getrepr</tt><big>(</big><em>showlocals=False</em>, <em>style='long'</em>, <em>abspath=False</em>, <em>tbfilter=True</em>, <em>funcargs=False</em><big>)</big><a class="headerlink" href="#py.code.ExceptionInfo.getrepr" title="Permalink to this definition">¶</a></dt>
<dd><p>return str()able representation of this exception info.
showlocals: show locals per traceback entry
style: long|short|no|native traceback style
tbfilter: hide entries (where __tracebackhide__ is true)</p>
<p>in case of style==native, tbfilter and showlocals is ignored.</p>
</dd></dl>
</dd></dl>
<dl class="class">
<dt>
<em class="property">class </em><tt class="descclassname">py.code.</tt><tt class="descname">Traceback</tt><big>(</big><em>tb</em><big>)</big></dt>
<dd><p>Traceback objects encapsulate and offer higher level
access to Traceback entries.</p>
<dl class="attribute">
<dt>
<tt class="descname">Entry</tt></dt>
<dd><p>alias of <tt class="xref py py-class docutils literal"><span class="pre">TracebackEntry</span></tt></p>
</dd></dl>
<dl class="method">
<dt>
<tt class="descname">cut</tt><big>(</big><em>path=None</em>, <em>lineno=None</em>, <em>firstlineno=None</em>, <em>excludepath=None</em><big>)</big></dt>
<dd><p>return a Traceback instance wrapping part of this Traceback</p>
<p>by provding any combination of path, lineno and firstlineno, the
first frame to start the to-be-returned traceback is determined</p>
<p>this allows cutting the first part of a Traceback instance e.g.
for formatting reasons (removing some uninteresting bits that deal
with handling of the exception/traceback)</p>
</dd></dl>
<dl class="method">
<dt>
<tt class="descname">filter</tt><big>(</big><em>fn=<function <lambda> at 0x32c2230></em><big>)</big></dt>
<dd><p>return a Traceback instance with certain items removed</p>
<p>fn is a function that gets a single argument, a TracebackItem
instance, and should return True when the item should be added
to the Traceback, False when not</p>
<p>by default this removes all the TracebackItems which are hidden
(see ishidden() above)</p>
</dd></dl>
<dl class="method">
<dt>
<tt class="descname">getcrashentry</tt><big>(</big><big>)</big></dt>
<dd><p>return last non-hidden traceback entry that lead
to the exception of a traceback.</p>
</dd></dl>
<dl class="method">
<dt>
<tt class="descname">recursionindex</tt><big>(</big><big>)</big></dt>
<dd><p>return the index of the frame/TracebackItem where recursion
originates if appropriate, None if no recursion occurred</p>
</dd></dl>
<dl class="method">
<dt>
<tt class="descname">append</tt><big>(</big><big>)</big></dt>
<dd><p>L.append(object) – append object to end</p>
</dd></dl>
<dl class="method">
<dt>
<tt class="descname">count</tt><big>(</big><em>value</em><big>)</big> → integer -- return number of occurrences of value</dt>
<dd></dd></dl>
<dl class="method">
<dt>
<tt class="descname">extend</tt><big>(</big><big>)</big></dt>
<dd><p>L.extend(iterable) – extend list by appending elements from the iterable</p>
</dd></dl>
<dl class="method">
<dt>
<tt class="descname">index</tt><big>(</big><em>value</em><span class="optional">[</span>, <em>start</em><span class="optional">[</span>, <em>stop</em><span class="optional">]</span><span class="optional">]</span><big>)</big> → integer -- return first index of value.</dt>
<dd><p>Raises ValueError if the value is not present.</p>
</dd></dl>
<dl class="method">
<dt>
<tt class="descname">insert</tt><big>(</big><big>)</big></dt>
<dd><p>L.insert(index, object) – insert object before index</p>
</dd></dl>
<dl class="method">
<dt>
<tt class="descname">pop</tt><big>(</big><span class="optional">[</span><em>index</em><span class="optional">]</span><big>)</big> → item -- remove and return item at index (default last).</dt>
<dd><p>Raises IndexError if list is empty or index is out of range.</p>
</dd></dl>
<dl class="method">
<dt>
<tt class="descname">remove</tt><big>(</big><big>)</big></dt>
<dd><p>L.remove(value) – remove first occurrence of value.
Raises ValueError if the value is not present.</p>
</dd></dl>
<dl class="method">
<dt>
<tt class="descname">reverse</tt><big>(</big><big>)</big></dt>
<dd><p>L.reverse() – reverse <em>IN PLACE</em></p>
</dd></dl>
<dl class="method">
<dt>
<tt class="descname">sort</tt><big>(</big><big>)</big></dt>
<dd><p>L.sort(cmp=None, key=None, reverse=False) – stable sort <em>IN PLACE</em>;
cmp(x, y) -> -1, 0, 1</p>
</dd></dl>
</dd></dl>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">py.code: higher level python code and introspection objects</a><ul>
<li><a class="reference internal" href="#contents-of-the-library">Contents of the library</a></li>
<li><a class="reference internal" href="#the-wrappers">The wrappers</a><ul>
<li><a class="reference internal" href="#py-code-code"><tt class="docutils literal"><span class="pre">py.code.Code</span></tt></a></li>
<li><a class="reference internal" href="#py-code-source"><tt class="docutils literal"><span class="pre">py.code.Source</span></tt></a></li>
<li><a class="reference internal" href="#py-code-traceback"><tt class="docutils literal"><span class="pre">py.code.Traceback</span></tt></a></li>
<li><a class="reference internal" href="#py-code-frame"><tt class="docutils literal"><span class="pre">py.code.Frame</span></tt></a></li>
<li><a class="reference internal" href="#py-code-exceptioninfo"><tt class="docutils literal"><span class="pre">py.code.ExceptionInfo</span></tt></a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="path.html"
title="previous chapter">py.path</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="io.html"
title="next chapter">py.io</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/code.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input 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>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<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="io.html" title="py.io"
>next</a> |</li>
<li class="right" >
<a href="path.html" title="py.path"
>previous</a> |</li>
<li><a href="index.html">py 1.4.32 documentation</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2010, holger krekel et. al..
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-7597274-14']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();
</script>
</body>
</html>