sources for code.html [rev. unknown]
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
  <head>
    <title>[code] </title>
    <meta content="text/html;charset=ISO-8859-1" name="Content-Type"/>
    <link href="style.css" media="screen" rel="stylesheet" type="text/css"/></head>
  <body>
    <div><a href="http://codespeak.net"><img alt="py lib" height="114" id="pyimg" src="http://codespeak.net/img/pylib.png" width="154"/></a></div>
    <div id="metaspace">
      <div class="project_title">[code] </div>
      <div id="menubar"><a class="menu" href="index.html">index</a> <a class="menu" href="../../apigen/api/index.html">api</a> <a class="menu" href="../../apigen/source/index.html">source</a> <a class="menu" href="contact.html">contact</a> <a class="menu" href="download.html">download</a></div></div>
    <div id="contentspace">
      <div id="docinfoline">
        <div style="float: right; font-style: italic;"> </div></div>
<div class="document" id="py-code">
<h1 class="title"><a class="reference external" href="../../apigen/api/code.html">py.code</a></h1>

<p>The <a class="reference external" href="../../apigen/api/code.html">py.code</a> part of the 'py lib' contains some functionality to help
dealing with Python code objects. Even though working with Python's internal
code objects (as found on frames and callables) can be very powerful, it's
usually also quite cumbersome, because the API provided by core Python is
relatively low level and not very accessible.</p>
<p>The <a class="reference external" href="../../apigen/api/code.html">py.code</a> 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>
<p>source: <a class="reference external" href="../../apigen/source/code/index.html">py/code/</a></p>
<div class="section" id="contents-of-the-library">
<h1>Contents of the library</h1>
<p>Every object in the <a class="reference external" href="../../apigen/api/code.html">py.code</a> library wraps a code Python object related
to code objects, source code, frames and tracebacks: the <a class="reference external" href="../../apigen/api/code.Code.html">py.code.Code</a>
class wraps code objects, <a class="reference external" href="../../apigen/api/code.Source.html">py.code.Source</a> source snippets,
<a class="reference external" href="../../apigen/api/code.Traceback.html">py.code.Traceback</a> exception tracebacks, <a class="reference external" href="../../apigen/api/code.Frame.html">py.code.Frame</a> frame
objects (as found in e.g. tracebacks) and <a class="reference external" href="../../apigen/api/code.ExceptionInfo.html">py.code.ExceptionInfo</a> the
tuple provided by sys.exc_info() (containing exception and traceback
information when an exception occurs). Also in the library is a helper function
<a class="reference external" href="../../apigen/api/code.compile.html">py.code.compile()</a> 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">
<h1>The wrappers</h1>
<div class="section" id="py-code-code">
<h2><a class="reference external" href="../../apigen/api/code.Code.html">py.code.Code</a></h2>
<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>
<pre class="literal-block">
&gt;&gt;&gt; import py
&gt;&gt;&gt; c = py.code.Code(py.path.local.read)
&gt;&gt;&gt; c.path.basename
'common.py'
&gt;&gt;&gt; isinstance(c.source(), py.code.Source)
True
&gt;&gt;&gt; str(c.source()).split('\n')[0]
&quot;def read(self, mode='rb'):&quot;
</pre>
<p>source: <a class="reference external" href="../../apigen/source/code/code.py.html">py/code/code.py</a></p>
</div>
<div class="section" id="py-code-source">
<h2><a class="reference external" href="../../apigen/api/code.Source.html">py.code.Source</a></h2>
<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>
<pre class="literal-block">
&gt;&gt;&gt; s = py.code.Source(&quot;&quot;&quot;\
...   def foo():
...     print &quot;foo&quot;
... &quot;&quot;&quot;)
&gt;&gt;&gt; str(s).startswith('def') # automatic de-indentation!
True
&gt;&gt;&gt; s.isparseable()
True
&gt;&gt;&gt; sub = s.getstatement(1) # get the statement starting at line 1
&gt;&gt;&gt; str(sub).strip() # XXX why is the strip() required?!?
'print &quot;foo&quot;'
</pre>
<p>source: <a class="reference external" href="../../apigen/source/code/source.py.html">py/code/source.py</a></p>
</div>
<div class="section" id="py-code-traceback">
<h2><a class="reference external" href="../../apigen/api/code.Traceback.html">py.code.Traceback</a></h2>
<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>
<pre class="literal-block">
&gt;&gt;&gt; import sys
&gt;&gt;&gt; try:
...   py.path.local(100) # illegal argument
... except:
...   exc, e, tb = sys.exc_info()
&gt;&gt;&gt; t = py.code.Traceback(tb)
&gt;&gt;&gt; first = t[1] # get the second entry (first is in this doc)
&gt;&gt;&gt; first.path.basename # second is in py/path/local.py
'local.py'
&gt;&gt;&gt; isinstance(first.statement, py.code.Source)
True
&gt;&gt;&gt; str(first.statement).strip().startswith('raise ValueError')
True
</pre>
<p>source: <a class="reference external" href="../../apigen/source/code/traceback2.py.html">py/code/traceback2.py</a></p>
</div>
<div class="section" id="py-code-frame">
<h2><a class="reference external" href="../../apigen/api/code.Frame.html">py.code.Frame</a></h2>
<p>Frame wrappers are used in <a class="reference external" href="../../apigen/api/code.Traceback.html">py.code.Traceback</a> 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 <a class="reference external" href="../../apigen/api/code.Code.html">py.code.Code</a> object)
and examine the arguments.</p>
<p>Example (using the 'first' TracebackItem instance created above):</p>
<pre class="literal-block">
&gt;&gt;&gt; frame = first.frame
&gt;&gt;&gt; isinstance(frame.code, py.code.Code)
True
&gt;&gt;&gt; isinstance(frame.eval('self'), py.__.path.local.local.LocalPath)
True
&gt;&gt;&gt; [namevalue[0] for namevalue in frame.getargs()]
['cls', 'path']
</pre>
</div>
<div class="section" id="py-code-exceptioninfo">
<h2><a class="reference external" href="../../apigen/api/code.ExceptionInfo.html">py.code.ExceptionInfo</a></h2>
<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>
<pre class="literal-block">
&gt;&gt;&gt; import sys
&gt;&gt;&gt; try:
...   foobar()
... except:
...   excinfo = py.code.ExceptionInfo()
&gt;&gt;&gt; excinfo.typename
'exceptions.NameError'
&gt;&gt;&gt; isinstance(excinfo.traceback, py.code.Traceback)
True
&gt;&gt;&gt; excinfo.exconly()
&quot;NameError: name 'foobar' is not defined&quot;
</pre>
</div>
</div>
</div>
</div></body></html>