floraachy/pytest2
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

[svn r63519] Initial Sphinx-ification of the documentation

Browse Source 
run: 'make html' to build

--HG--
branch : trunk
This commit is contained in:
briandorsey
2009-04-02 09:10:16 +02:00
parent 87bd1d998b
commit 4d95ec5c5c
129 changed files with 11264 additions and 107 deletions
Download Patch File Download Diff File Expand all files Collapse all files

247
py/doc/_build/html/code.html vendored Normal file
View File

@@ -0,0 +1,247 @@
<!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>4. py.code &mdash; py lib v1.0.0b1 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.0.0b1',
COLLAPSE_MODINDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="top" title="py lib v1.0.0b1 documentation" href="index.html" />
<link rel="next" title="5. py/bin/ scripts" href="bin.html" />
<link rel="prev" title="3. 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="bin.html" title="5. py/bin/ scripts"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="path.html" title="3. py.path"
accesskey="P">previous</a> |</li>
<li><a href="index.html">py lib v1.0.0b1 documentation</a> &raquo;</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="py-code">
<h1>4. py.code<a class="headerlink" href="#py-code" title="Permalink to this headline"></a></h1>
<p>The <tt class="docutils literal"><span class="pre">py.code</span></tt> part of the &#8216;py lib&#8217; contains some functionality to help
dealing with Python code objects. Even though working with Python&#8217;s internal
code objects (as found on frames and callables) can be very powerful, it&#8217;s
usually also quite cumbersome, because the API provided by core Python is
relatively low level and not very accessible.</p>
<p>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 &#8216;Pythonic&#8217; functionality.</p>
<p>source: <tt class="docutils literal"><span class="pre">py/code/</span></tt></p>
<div class="section" id="contents-of-the-library">
<h2>4.1. 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></tt> exception tracebacks, <tt class="docutils literal"><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&#8217;s
built-in &#8216;compile()&#8217; function, but returns a wrapped code object.</p>
</div>
<div class="section" id="the-wrappers">
<h2>4.2. The wrappers<a class="headerlink" href="#the-wrappers" title="Permalink to this headline"></a></h2>
<div class="section" id="py-code-code">
<h3>4.2.1. <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">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">py</span>
<span class="gp">&gt;&gt;&gt; </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">&gt;&gt;&gt; </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">&#39;common.py&#39;</span>
<span class="gp">&gt;&gt;&gt; </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">&gt;&gt;&gt; </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">&#39;</span><span class="se">\n</span><span class="s">&#39;</span><span class="p">)[</span><span class="mf">0</span><span class="p">]</span>
<span class="go">&quot;def read(self, mode=&#39;rb&#39;):&quot;</span>
</pre></div>
</div>
<p>source: <tt class="docutils literal"><span class="pre">py/code/code.py</span></tt></p>
</div>
<div class="section" id="py-code-source">
<h3>4.2.2. <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">&gt;&gt;&gt; </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">&quot;&quot;&quot;</span><span class="se">\</span>
<span class="gp">... </span><span class="s"> def foo():</span>
<span class="gp">... </span><span class="s"> print &quot;foo&quot;</span>
<span class="gp">... </span><span class="s">&quot;&quot;&quot;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </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">&#39;def&#39;</span><span class="p">)</span> <span class="c"># automatic de-indentation!</span>
<span class="go">True</span>
<span class="gp">&gt;&gt;&gt; </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">&gt;&gt;&gt; </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="mf">1</span><span class="p">)</span> <span class="c"># get the statement starting at line 1</span>
<span class="gp">&gt;&gt;&gt; </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">&#39;print &quot;foo&quot;&#39;</span>
</pre></div>
</div>
<p>source: <tt class="docutils literal"><span class="pre">py/code/source.py</span></tt></p>
</div>
<div class="section" id="py-code-traceback">
<h3>4.2.3. <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&#8217;s items (resulting in expressions
such as &#8216;fname = tb.tb_next.tb_frame.f_code.co_filename&#8217;). 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">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">sys</span>
<span class="gp">&gt;&gt;&gt; </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="mf">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">&gt;&gt;&gt; </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">&gt;&gt;&gt; </span><span class="n">first</span> <span class="o">=</span> <span class="n">t</span><span class="p">[</span><span class="mf">1</span><span class="p">]</span> <span class="c"># get the second entry (first is in this doc)</span>
<span class="gp">&gt;&gt;&gt; </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">&#39;local.py&#39;</span>
<span class="gp">&gt;&gt;&gt; </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">&gt;&gt;&gt; </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">&#39;raise ValueError&#39;</span><span class="p">)</span>
<span class="go">True</span>
</pre></div>
</div>
<p>source: <tt class="docutils literal"><span class="pre">py/code/traceback2.py</span></tt></p>
</div>
<div class="section" id="py-code-frame">
<h3>4.2.4. <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
&#8216;inside&#8217; the frame (using the frame&#8217;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 &#8216;first&#8217; TracebackItem instance created above):</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </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">&gt;&gt;&gt; </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">&gt;&gt;&gt; </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">&#39;self&#39;</span><span class="p">),</span> <span class="n">py</span><span class="o">.</span><span class="n">__</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">local</span><span class="o">.</span><span class="n">LocalPath</span><span class="p">)</span>
<span class="go">True</span>
<span class="gp">&gt;&gt;&gt; </span><span class="p">[</span><span class="n">namevalue</span><span class="p">[</span><span class="mf">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">[&#39;cls&#39;, &#39;path&#39;]</span>
</pre></div>
</div>
</div>
<div class="section" id="py-code-exceptioninfo">
<h3>4.2.5. <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">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">sys</span>
<span class="gp">&gt;&gt;&gt; </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">&gt;&gt;&gt; </span><span class="n">excinfo</span><span class="o">.</span><span class="n">typename</span>
<span class="go">&#39;NameError&#39;</span>
<span class="gp">&gt;&gt;&gt; </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">&gt;&gt;&gt; </span><span class="n">excinfo</span><span class="o">.</span><span class="n">exconly</span><span class="p">()</span>
<span class="go">&quot;NameError: name &#39;foobar&#39; is not defined&quot;</span>
</pre></div>
</div>
</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 external" href="">4. py.code</a><ul>
<li><a class="reference external" href="#contents-of-the-library">4.1. Contents of the library</a></li>
<li><a class="reference external" href="#the-wrappers">4.2. The wrappers</a><ul>
<li><a class="reference external" href="#py-code-code">4.2.1. <tt class="docutils literal"><span class="pre">py.code.Code</span></tt></a></li>
<li><a class="reference external" href="#py-code-source">4.2.2. <tt class="docutils literal"><span class="pre">py.code.Source</span></tt></a></li>
<li><a class="reference external" href="#py-code-traceback">4.2.3. <tt class="docutils literal"><span class="pre">py.code.Traceback</span></tt></a></li>
<li><a class="reference external" href="#py-code-frame">4.2.4. <tt class="docutils literal"><span class="pre">py.code.Frame</span></tt></a></li>
<li><a class="reference external" href="#py-code-exceptioninfo">4.2.5. <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">3. py.path</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="bin.html"
title="next chapter">5. <tt class="docutils literal"><span class="pre">py/bin/</span></tt> scripts</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" size="18" />
<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="bin.html" title="5. py/bin/ scripts"
>next</a> |</li>
<li class="right" >
<a href="path.html" title="3. py.path"
>previous</a> |</li>
<li><a href="index.html">py lib v1.0.0b1 documentation</a> &raquo;</li>
</ul>
</div>
<div class="footer">
&copy; Copyright 2009, Holger Krekel.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.7.
</div>
</body>
</html>