1
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
5
<meta content="text/html;charset=ISO-8859-1" name="Content-Type"/>
6
<link href="style.css" media="screen" rel="stylesheet" type="text/css"/></head>
9
<div><a href="http://pylib.org"><img alt="py lib" height="57" id="pyimg" src="http://codespeak.net/img/pylib.png" width="77"/></a></div>
12
<div><a class="menu" href="announce/release-1.2.1.html">1.2.1 ANN</a></div></div>
14
<div><a class="menu" href="install.html">INSTALL</a></div></div>
16
<div><a class="menu" href="contact.html">CONTACT</a></div></div>
18
<div><a class="menu" href="changelog.html">CHANGELOG</a></div></div>
20
<div><a class="menu" href="faq.html">FAQ</a></div></div>
24
<div><a class="menu" href="test/index.html">Index</a></div>
25
<div><a class="menu" href="test/quickstart.html">Quickstart</a></div>
26
<div><a class="menu" href="test/features.html">Features</a></div>
27
<div><a class="menu" href="test/plugin/index.html">Plugins</a></div>
28
<div><a class="menu" href="test/funcargs.html">Funcargs</a></div>
29
<div><a class="menu" href="test/customize.html">Customize</a></div>
30
<div><a class="menu" href="test/talks.html">Tutorials</a></div></div></div>
33
<h3>supporting APIs:</h3>
34
<div><a class="menu" href="index.html">Index</a></div>
35
<div><a class="menu" href="path.html">py.path</a></div>
36
<div><a class="menu" href="code.html">py.code</a></div></div></div></div></div>
37
<div id="contentspace">
38
<div class="document" id="py-code-higher-level-python-code-and-introspection-objects">
39
<h1 class="title">py.code: higher level python code and introspection objects</h1>
41
<p>The <tt class="docutils literal">py.code</tt> part of the pylib contains some functionality to help
42
dealing with Python code objects. Even though working with Python's internal
43
code objects (as found on frames and callables) can be very powerful, it's
44
usually also quite cumbersome, because the API provided by core Python is
45
relatively low level and not very accessible.</p>
46
<p>The <tt class="docutils literal">py.code</tt> library tries to simplify accessing the code objects as well
47
as creating them. There is a small set of interfaces a user needs to deal with,
48
all nicely bundled together, and with a rich set of 'Pythonic' functionality.</p>
49
<div class="section" id="contents-of-the-library">
50
<h1>Contents of the library</h1>
51
<p>Every object in the <tt class="docutils literal">py.code</tt> library wraps a code Python object related
52
to code objects, source code, frames and tracebacks: the <tt class="docutils literal">py.code.Code</tt>
53
class wraps code objects, <tt class="docutils literal">py.code.Source</tt> source snippets,
54
<tt class="docutils literal">py.code.Traceback` exception tracebacks, ``py.code.Frame</tt> frame
55
objects (as found in e.g. tracebacks) and <tt class="docutils literal">py.code.ExceptionInfo</tt> the
56
tuple provided by sys.exc_info() (containing exception and traceback
57
information when an exception occurs). Also in the library is a helper function
58
<tt class="docutils literal">py.code.compile()</tt> that provides the same functionality as Python's
59
built-in 'compile()' function, but returns a wrapped code object.</p>
61
<div class="section" id="the-wrappers">
63
<div class="section" id="py-code-code">
64
<h2><tt class="docutils literal">py.code.Code</tt></h2>
65
<p>Code objects are instantiated with a code object or a callable as argument,
66
and provide functionality to compare themselves with other Code objects, get to
67
the source file or its contents, create new Code objects from scratch, etc.</p>
68
<p>A quick example:</p>
69
<pre class="literal-block">
70
>>> import py
71
>>> c = py.code.Code(py.path.local.read)
72
>>> c.path.basename
74
>>> isinstance(c.source(), py.code.Source)
76
>>> str(c.source()).split('\n')[0]
77
"def read(self, mode='r'):"
80
<div class="section" id="py-code-source">
81
<h2><tt class="docutils literal">py.code.Source</tt></h2>
82
<p>Source objects wrap snippets of Python source code, providing a simple yet
83
powerful interface to read, deindent, slice, compare, compile and manipulate
84
them, things that are not so easy in core Python.</p>
86
<pre class="literal-block">
87
>>> s = py.code.Source("""\
89
... print "foo"
90
... """)
91
>>> str(s).startswith('def') # automatic de-indentation!
93
>>> s.isparseable()
95
>>> sub = s.getstatement(1) # get the statement starting at line 1
96
>>> str(sub).strip() # XXX why is the strip() required?!?
97
'print "foo"'
100
<div class="section" id="py-code-traceback">
101
<h2><tt class="docutils literal">py.code.Traceback</tt></h2>
102
<p>Tracebacks are usually not very easy to examine, you need to access certain
103
somewhat hidden attributes of the traceback's items (resulting in expressions
104
such as 'fname = tb.tb_next.tb_frame.f_code.co_filename'). The Traceback
105
interface (and its TracebackItem children) tries to improve this.</p>
107
<pre class="literal-block">
108
>>> import sys
110
... py.path.local(100) # illegal argument
112
... exc, e, tb = sys.exc_info()
113
>>> t = py.code.Traceback(tb)
114
>>> first = t[1] # get the second entry (first is in this doc)
115
>>> first.path.basename # second is in py/path/local.py
117
>>> isinstance(first.statement, py.code.Source)
119
>>> str(first.statement).strip().startswith('raise ValueError')
123
<div class="section" id="py-code-frame">
124
<h2><tt class="docutils literal">py.code.Frame</tt></h2>
125
<p>Frame wrappers are used in <tt class="docutils literal">py.code.Traceback</tt> items, and will usually not
126
directly be instantiated. They provide some nice methods to evaluate code
127
'inside' the frame (using the frame's local variables), get to the underlying
128
code (frames have a code attribute that points to a <tt class="docutils literal">py.code.Code</tt> object)
129
and examine the arguments.</p>
130
<p>Example (using the 'first' TracebackItem instance created above):</p>
131
<pre class="literal-block">
132
>>> frame = first.frame
133
>>> isinstance(frame.code, py.code.Code)
135
>>> isinstance(frame.eval('self'), py.path.local)
137
>>> [namevalue[0] for namevalue in frame.getargs()]
141
<div class="section" id="py-code-exceptioninfo">
142
<h2><tt class="docutils literal">py.code.ExceptionInfo</tt></h2>
143
<p>A wrapper around the tuple returned by sys.exc_info() (will call sys.exc_info()
144
itself if the tuple is not provided as an argument), provides some handy
145
attributes to easily access the traceback and exception string.</p>
147
<pre class="literal-block">
148
>>> import sys
152
... excinfo = py.code.ExceptionInfo()
153
>>> excinfo.typename
155
>>> isinstance(excinfo.traceback, py.code.Traceback)
157
>>> excinfo.exconly()
158
"NameError: name 'foobar' is not defined"
164
<script type="text/javascript">
165
var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
166
document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
168
<script type="text/javascript">
170
var pageTracker = _gat._getTracker("UA-7597274-3");
171
pageTracker._trackPageview();
172
} catch(err) {}</script>
b'\\ No newline at end of file'
added
removed
doc/code.html
