Added runp and bumped release number of plac to 0.7.3

author: micheles <micheles@micheles-laptop> 2010-08-31 07:58:27 +0200
committer: micheles <micheles@micheles-laptop> 2010-08-31 07:58:27 +0200
commit: 13ef00b3231dd71e331e34891bea6345e5b96097 (patch)
tree: 804fee4adaae672ef4bd7fb1a60b856e20691556
parent: e1e09b354cf2924ed4dbad0c4776a61f4355d1b0 (diff)
download: micheles-13ef00b3231dd71e331e34891bea6345e5b96097.tar.gz
9 files changed, 2001 insertions, 10727 deletions
diff --git a/plac/CHANGES.txt b/plac/CHANGES.txt
index 805ceb6..569bf03 100644
--- a/plac/CHANGES.txt
+++ b/plac/CHANGES.txt
@@ -1,6 +1,7 @@
 HISTORY
 ----------
 
+0.7.3 Put the documentation in a single document; added runp (2010-08-31)
 0.7.2 Interpreter.call does not start an interpreter automagically anymore;
       better documented and added tests for the metavar concept (2010-08-31)
 0.7.1 A few bug fixes (2010-08-11)
diff --git a/plac/Makefile b/plac/Makefile
index 5afc3e5..e98aa51 100644
--- a/plac/Makefile
+++ b/plac/Makefile
@@ -1,9 +1,7 @@
 default:
-	make doc/plac.pdf; make doc/plac_adv.pdf
-doc/plac.pdf: doc/plac.txt
+	make doc/plac.pdf
+doc/plac.pdf: doc/plac.txt doc/plac_core.txt doc/plac_adv.txt
 	cd doc; rst2pdf --footer=###Page### plac.txt; rst2html --stylesheet=$(HOME)/gcode/df.css plac.txt plac.html
-doc/plac_adv.pdf: doc/plac_adv.txt
-	cd doc; rst2pdf --footer=###Page### plac_adv.txt; rst2html --stylesheet=$(HOME)/gcode/df.css plac_adv.txt plac_adv.html
 upload:
 	python3 setup.py register sdist upload 
 2:
diff --git a/plac/doc/plac.html b/plac/doc/plac.html
index 354af7a..9b40db9 100644
--- a/plac/doc/plac.html
+++ b/plac/doc/plac.html
@@ -3,7 +3,7 @@
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
 <title></title>
 <style type="text/css">
 
@@ -432,7 +432,7 @@ h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
 </tr>
 <tr class="field"><th class="field-name">Requires:</th><td class="field-body">Python 2.3+</td>
 </tr>
-<tr class="field"><th class="field-name">Installation:</th><td class="field-body"><tt class="docutils literal">easy_install <span class="pre">-U</span> plac</tt></td>
+<tr class="field"><th class="field-name">Installation:</th><td class="field-body"><tt class="docutils literal"><span class="pre">easy_install</span> <span class="pre">-U</span> <span class="pre">plac</span></tt></td>
 </tr>
 <tr class="field"><th class="field-name">License:</th><td class="field-body">BSD license</td>
 </tr>
@@ -551,7 +551,7 @@ if __name__ == '__main__':
         sys.exit('Unrecognized arguments: %s' % ' '.join(sys.argv[2:]))
 
 </pre>
-<p>As you see the whole <tt class="docutils literal">if __name__ == '__main__'</tt> block (nine lines)
+<p>As you see the whole <tt class="docutils literal"><span class="pre">if</span> <span class="pre">__name__</span> <span class="pre">==</span> <span class="pre">'__main__'</span></tt> block (nine lines)
 is essentially boilerplate that should not exist.  Actually I think
 the language should recognize the main function and pass to it the
 command-line arguments automatically; unfortunaly this is unlikely to
@@ -641,12 +641,12 @@ if __name__ == '__main__':
 
 </pre>
 <p>Here I want to perform a query on a database table, by extracting the
-most recent data: it makes sense for <tt class="docutils literal">today</tt> to be a default argument.
-If there is a most used table (in this example a table called <tt class="docutils literal">'product'</tt>)
+most recent data: it makes sense for <tt class="docutils literal"><span class="pre">today</span></tt> to be a default argument.
+If there is a most used table (in this example a table called <tt class="docutils literal"><span class="pre">'product'</span></tt>)
 it also makes sense to make it a default argument. Performing the parsing
 of the command-line arguments by hand takes 8 ugly lines of boilerplate
 (using <a class="reference external" href="http://argparse.googlecode.com">argparse</a> would require about the same number of lines).
-With <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> the entire <tt class="docutils literal">__main__</tt> block reduces to the usual two lines:</p>
+With <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> the entire <tt class="docutils literal"><span class="pre">__main__</span></tt> block reduces to the usual two lines:</p>
 <pre class="literal-block">
 if __name__ == '__main__':
     import plac; plac.call(main)
@@ -706,7 +706,7 @@ let's the machine take care of the details.</p>
 the sense that it delivers the programmer from the burden of writing
 the parser, but is less of a hack: instead of extracting the parser
 from the docstring of the module, it extracts it from the signature of
-the <tt class="docutils literal">main</tt> function.</p>
+the <tt class="docutils literal"><span class="pre">main</span></tt> function.</p>
 <p>The idea comes from the <cite>function annotations</cite> concept, a new
 feature of Python 3. An example is worth a thousand words, so here
 it is:</p>
@@ -724,7 +724,7 @@ if __name__ == '__main__':
     import plac; plac.call(main)
 
 </pre>
-<p>Here the arguments of the <tt class="docutils literal">main</tt> function have been annotated with
+<p>Here the arguments of the <tt class="docutils literal"><span class="pre">main</span></tt> function have been annotated with
 strings which are intented to be used in the help message:</p>
 <pre class="literal-block">
 usage: example7_.py [-h] dsn [scripts [scripts ...]]
@@ -766,10 +766,10 @@ if __name__ == '__main__':
     import plac; plac.call(main)
 
 </pre>
-<p>Here the argument <tt class="docutils literal">command</tt> has been annotated with the tuple
-<tt class="docutils literal">(&quot;SQL query&quot;, 'option', 'c')</tt>: the first string is the help string
+<p>Here the argument <tt class="docutils literal"><span class="pre">command</span></tt> has been annotated with the tuple
+<tt class="docutils literal"><span class="pre">(&quot;SQL</span> <span class="pre">query&quot;,</span> <span class="pre">'option',</span> <span class="pre">'c')</span></tt>: the first string is the help string
 which will appear in the usage message, the second string tells <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a>
-that <tt class="docutils literal">command</tt> is an option and the third string that there is also
+that <tt class="docutils literal"><span class="pre">command</span></tt> is an option and the third string that there is also
 a short form of the option <tt class="docutils literal"><span class="pre">-c</span></tt>, the long form being <tt class="docutils literal"><span class="pre">--command</span></tt>.
 The usage message is the following:</p>
 <pre class="literal-block">
@@ -793,7 +793,7 @@ $ python3 example8.py --command=&quot;select * from table&quot; dsn
 executing select * from table on dsn
 </pre>
 <p>The third argument in the function annotation can be omitted: in such
-case it will be assumed to be <tt class="docutils literal">None</tt>. The consequence is that
+case it will be assumed to be <tt class="docutils literal"><span class="pre">None</span></tt>. The consequence is that
 the usual dichotomy between long and short options (GNU-style options)
 disappears: we get <em>smart options</em>, which have the single character prefix
 of short options and behave like both long and short options, since
@@ -834,8 +834,8 @@ $ python3 example6.py -com=&quot;select&quot; dsn
 usage: example6.py [-h] [-command COMMAND] dsn
 example6.py: error: unrecognized arguments: -com=select
 </pre>
-<p>If the option is not passed, the variable <tt class="docutils literal">command</tt>
-will get the value <tt class="docutils literal">None</tt>. However, it is possible to specify a non-trivial
+<p>If the option is not passed, the variable <tt class="docutils literal"><span class="pre">command</span></tt>
+will get the value <tt class="docutils literal"><span class="pre">None</span></tt>. However, it is possible to specify a non-trivial
 default. Here is an example:</p>
 <pre class="literal-block">
 # example8_.py
@@ -869,7 +869,7 @@ executing 'select * from table' on dsn
 <div class="section" id="scripts-with-flags">
 <h2><a class="toc-backref" href="#id58">Scripts with flags</a></h2>
 <p><a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> is able to recognize flags, i.e. boolean options which are
-<tt class="docutils literal">True</tt> if they are passed to the command line and <tt class="docutils literal">False</tt>
+<tt class="docutils literal"><span class="pre">True</span></tt> if they are passed to the command line and <tt class="docutils literal"><span class="pre">False</span></tt>
 if they are absent. Here is an example:</p>
 <pre class="literal-block">
 # example9.py
@@ -899,12 +899,12 @@ $ python3 example9.py -v dsn
 connecting to dsn
 </pre>
 <p>Notice that it is an error trying to specify a default for flags: the
-default value for a flag is always <tt class="docutils literal">False</tt>. If you feel the need to
+default value for a flag is always <tt class="docutils literal"><span class="pre">False</span></tt>. If you feel the need to
 implement non-boolean flags, you should use an option with two
 choices, as explained in the &quot;more features&quot; section.</p>
 <p>For consistency with the way the usage message is printed, I suggest
 you to follow the Flag-Option-Required-Default (FORD) convention: in
-the <tt class="docutils literal">main</tt> function write first the flag arguments, then the option
+the <tt class="docutils literal"><span class="pre">main</span></tt> function write first the flag arguments, then the option
 arguments, then the required arguments and finally the default
 arguments. This is just a convention and you are not forced to use it,
 except for the default arguments (including the varargs) which must
@@ -939,7 +939,7 @@ main.__annotations__ = dict(
 <p>One should be careful to match the keys of the annotation dictionary
 with the names of the arguments in the annotated function; for lazy
 people with Python 2.4 available the simplest way is to use the
-<tt class="docutils literal">plac.annotations</tt> decorator that performs the check for you:</p>
+<tt class="docutils literal"><span class="pre">plac.annotations</span></tt> decorator that performs the check for you:</p>
 <pre class="literal-block">
 &#64;plac.annotations(
     dsn=&quot;Database dsn&quot;,
@@ -948,7 +948,7 @@ def main(dsn, *scripts):
     ...
 </pre>
 <p>In the rest of this article I will assume that you are using Python 2.X with
-X &gt;= 4 and I will use the <tt class="docutils literal">plac.annotations</tt> decorator. Notice however
+X &gt;= 4 and I will use the <tt class="docutils literal"><span class="pre">plac.annotations</span></tt> decorator. Notice however
 that the core features of <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> run even on Python 2.3.</p>
 </div>
 <div class="section" id="more-features">
@@ -960,22 +960,26 @@ the features of <a class="reference external" href="http://argparse.googlecode.c
 in <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a>.  Until now, I have only showed simple annotations, but in
 general an annotation is a 6-tuple of the form</p>
 <blockquote>
-<tt class="docutils literal">(help, kind, abbrev, type, choices, metavar)</tt></blockquote>
-<p>where <tt class="docutils literal">help</tt> is the help message, <tt class="docutils literal">kind</tt> is a string in the set {
-<tt class="docutils literal">&quot;flag&quot;</tt>, <tt class="docutils literal">&quot;option&quot;</tt>, <tt class="docutils literal">&quot;positional&quot;</tt>}, <tt class="docutils literal">abbrev</tt> is a
-one-character string or <tt class="docutils literal">None</tt>, <tt class="docutils literal">type</tt> is a callable taking a
+<tt class="docutils literal"><span class="pre">(help,</span> <span class="pre">kind,</span> <span class="pre">abbrev,</span> <span class="pre">type,</span> <span class="pre">choices,</span> <span class="pre">metavar)</span></tt></blockquote>
+<p>where <tt class="docutils literal"><span class="pre">help</span></tt> is the help message, <tt class="docutils literal"><span class="pre">kind</span></tt> is a string in the set {
+<tt class="docutils literal"><span class="pre">&quot;flag&quot;</span></tt>, <tt class="docutils literal"><span class="pre">&quot;option&quot;</span></tt>, <tt class="docutils literal"><span class="pre">&quot;positional&quot;</span></tt>}, <tt class="docutils literal"><span class="pre">abbrev</span></tt> is a
+one-character string or <tt class="docutils literal"><span class="pre">None</span></tt>, <tt class="docutils literal"><span class="pre">type</span></tt> is a callable taking a
 string in input,
-<tt class="docutils literal">choices</tt> is a discrete sequence of values and <tt class="docutils literal">metavar</tt> is a string.</p>
-<p><tt class="docutils literal">type</tt> is used to automagically convert the command line arguments
+<tt class="docutils literal"><span class="pre">choices</span></tt> is a discrete sequence of values and <tt class="docutils literal"><span class="pre">metavar</span></tt> is a string.</p>
+<p><tt class="docutils literal"><span class="pre">type</span></tt> is used to automagically convert the command line arguments
 from the string type to any Python type; by default there is no
-conversion and <tt class="docutils literal">type=None</tt>.</p>
-<p><tt class="docutils literal">choices</tt> is used to restrict the number of the valid
-options; by default there is no restriction i.e. <tt class="docutils literal">choices=None</tt>.</p>
-<p><tt class="docutils literal">metavar</tt> is used to change the argument name in the usage message
-(and only there); by default the metavar is <tt class="docutils literal">None</tt>: this means that
-the name in the usage message is the same as the argument name,
-unless the argument has a default and in such a case is
-equal to the stringified form of the default.</p>
+conversion and <tt class="docutils literal"><span class="pre">type=None</span></tt>.</p>
+<p><tt class="docutils literal"><span class="pre">choices</span></tt> is used to restrict the number of the valid
+options; by default there is no restriction i.e. <tt class="docutils literal"><span class="pre">choices=None</span></tt>.</p>
+<p><tt class="docutils literal"><span class="pre">metavar</span></tt> has two meanings. For a positional argument it is used to
+change the argument name in the usage message (and only there). By
+default the metavar is <tt class="docutils literal"><span class="pre">None</span></tt> and the name in the usage message is
+the same as the argument name.  For an option
+the <tt class="docutils literal"><span class="pre">metavar</span></tt> is used differently in the usage message, which has
+now the form <tt class="docutils literal"><span class="pre">[--option-name</span> <span class="pre">METAVAR]</span></tt>. If the <tt class="docutils literal"><span class="pre">metavar</span></tt> is <tt class="docutils literal"><span class="pre">None</span></tt>,
+then it is equal to the uppercased name of the argument, unless the
+argument has a default and in such a case is equal to the stringified
+form of the default.</p>
 <p>Here is an example showing many of the features (copied from the
 <a class="reference external" href="http://argparse.googlecode.com">argparse</a> documentation):</p>
 <pre class="literal-block">
@@ -1015,7 +1019,7 @@ optional arguments:
   -h, --help  show this help message and exit
 
 </pre>
-<p>Notice that the docstring of the <tt class="docutils literal">main</tt> function has been automatically added
+<p>Notice that the docstring of the <tt class="docutils literal"><span class="pre">main</span></tt> function has been automatically added
 to the usage message. Here are a couple of examples of use:</p>
 <pre class="literal-block">
 $ python example10.py add 1 2 3 4
@@ -1026,13 +1030,13 @@ $ python example10.py ad 1 2 3 4 # a mispelling error
 usage: example10.py [-h] {add,mul} [n [n ...]]
 example10.py: error: argument operator: invalid choice: 'ad' (choose from 'add', 'mul')
 </pre>
-<p><tt class="docutils literal">plac.call</tt> can also be used in doctests like this:</p>
+<p><tt class="docutils literal"><span class="pre">plac.call</span></tt> can also be used in doctests like this:</p>
 <pre class="doctest-block">
 &gt;&gt;&gt; import plac, example10
 &gt;&gt;&gt; plac.call(example10.main, ['add', '1', '2'])
 3.0
 </pre>
-<p><tt class="docutils literal">plac.call</tt> works for generators too:</p>
+<p><tt class="docutils literal"><span class="pre">plac.call</span></tt> works for generators too:</p>
 <pre class="doctest-block">
 &gt;&gt;&gt; def main(n):
 ...     for i in range(int(n)):
@@ -1040,12 +1044,12 @@ example10.py: error: argument operator: invalid choice: 'ad' (choose from 'add',
 &gt;&gt;&gt; plac.call(main, ['3'])
 [0, 1, 2]
 </pre>
-<p>Internally <tt class="docutils literal">plac.call</tt> tries to convert the output of the main function
+<p>Internally <tt class="docutils literal"><span class="pre">plac.call</span></tt> tries to convert the output of the main function
 into a list, if possible. If the output is not iterable or it is a
 string, it is left unchanged, but if it is iterable it is converted.
-In particular, generator objects are exhausted by <tt class="docutils literal">plac.call</tt>.</p>
+In particular, generator objects are exhausted by <tt class="docutils literal"><span class="pre">plac.call</span></tt>.</p>
 <p>This behavior avoids mistakes like forgetting of applying
-<tt class="docutils literal">list(result)</tt> to the result of <tt class="docutils literal">plac.call</tt>; moreover it makes
+<tt class="docutils literal"><span class="pre">list(result)</span></tt> to the result of <tt class="docutils literal"><span class="pre">plac.call</span></tt>; moreover it makes
 errors visible early, and avoids mistakes in code like the following:</p>
 <pre class="literal-block">
 try:
@@ -1056,13 +1060,13 @@ except:
 <p>Without the &quot;listify&quot; functionality, a main function returning a
 generator object would not raise any exception until the generator
 is iterated over.</p>
-<p>If you are a fan of lazyness, you can still have it by setting the <tt class="docutils literal">eager</tt>
-flag to <tt class="docutils literal">False</tt>, as in the following example:</p>
+<p>If you are a fan of lazyness, you can still have it by setting the <tt class="docutils literal"><span class="pre">eager</span></tt>
+flag to <tt class="docutils literal"><span class="pre">False</span></tt>, as in the following example:</p>
 <pre class="literal-block">
 for line in plac.call(main, args, eager=False):
     print(line)
 </pre>
-<p>If <tt class="docutils literal">main</tt> returns a generator object this example will print each
+<p>If <tt class="docutils literal"><span class="pre">main</span></tt> returns a generator object this example will print each
 line as soon as available, whereas the default behaviour is to print
 all the lines together and the end of the computation.</p>
 </div>
@@ -1070,7 +1074,7 @@ all the lines together and the end of the computation.</p>
 <h2><a class="toc-backref" href="#id61">A realistic example</a></h2>
 <p>Here is a more realistic script using most of the features of <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> to
 run SQL queries on a database by relying on <a class="reference external" href="http://www.sqlalchemy.org/">SQLAlchemy</a>. Notice the usage
-of the <tt class="docutils literal">type</tt> feature to automagically convert a SQLAlchemy connection
+of the <tt class="docutils literal"><span class="pre">type</span></tt> feature to automagically convert a SQLAlchemy connection
 string into a <a class="reference external" href="http://www.sqlalchemy.org/docs/reference/ext/sqlsoup.html">SqlSoup</a> object:</p>
 <pre class="literal-block">
 # dbcli.py
@@ -1105,12 +1109,12 @@ if __name__ == '__main__':
 
 </pre>
 <p>You can see the <em>yield-is-print</em> pattern here: instead of using
-<tt class="docutils literal">print</tt> in the main function, I use <tt class="docutils literal">yield</tt>, and I perform the
-print in the <tt class="docutils literal">__main__</tt> block. The advantage of the pattern is that
-tests invoking <tt class="docutils literal">plac.call</tt> and checking the result become trivial:
+<tt class="docutils literal"><span class="pre">print</span></tt> in the main function, I use <tt class="docutils literal"><span class="pre">yield</span></tt>, and I perform the
+print in the <tt class="docutils literal"><span class="pre">__main__</span></tt> block. The advantage of the pattern is that
+tests invoking <tt class="docutils literal"><span class="pre">plac.call</span></tt> and checking the result become trivial:
 had I performed the printing in the main function, the test would have
-involved an ugly hack like redirecting <tt class="docutils literal">sys.stdout</tt> to a
-<tt class="docutils literal">StringIO</tt> object.</p>
+involved an ugly hack like redirecting <tt class="docutils literal"><span class="pre">sys.stdout</span></tt> to a
+<tt class="docutils literal"><span class="pre">StringIO</span></tt> object.</p>
 <p>Here is the usage message:</p>
 <pre class="literal-block">
 usage: dbcli.py [-h] [-H] [-c SQL] [-d |] db [scripts [scripts ...]]
@@ -1134,7 +1138,7 @@ optional arguments:
 <h2><a class="toc-backref" href="#id62">Keyword arguments</a></h2>
 <p>Starting from release 0.4, <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> supports keyword arguments.  In
 practice that means that if your main function has keyword arguments,
-<a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> treats specially arguments of the form <tt class="docutils literal">&quot;name=value&quot;</tt> in the
+<a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> treats specially arguments of the form <tt class="docutils literal"><span class="pre">&quot;name=value&quot;</span></tt> in the
 command line.  Here is an example:</p>
 <pre class="literal-block">
 # example12.py
@@ -1178,7 +1182,7 @@ args=('a1', 'a2')
 kw={'name': 'value'}
 </pre>
 <p>When using keyword arguments, one must be careful to use names which
-are not alreay taken; for instance in this examples the name <tt class="docutils literal">opt</tt>
+are not alreay taken; for instance in this examples the name <tt class="docutils literal"><span class="pre">opt</span></tt>
 is taken:</p>
 <pre class="literal-block">
 $ python example12.py 1 2 kw1=1 kw2=2 opt=0
@@ -1260,29 +1264,29 @@ if __name__ == '__main__':
 implemented a custom help command.</li>
 <li>I have changed the prefix character used to recognize the options
 to a dot.</li>
-<li>Keyword arguments recognition (in the <tt class="docutils literal">**setters</tt>) is used to make it
+<li>Keyword arguments recognition (in the <tt class="docutils literal"><span class="pre">**setters</span></tt>) is used to make it
 possible to store a value in the shelve with the syntax
-<tt class="docutils literal">param_name=param_value</tt>.</li>
-<li><tt class="docutils literal">*params</tt> are used to retrieve parameters from the shelve and some
+<tt class="docutils literal"><span class="pre">param_name=param_value</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">*params</span></tt> are used to retrieve parameters from the shelve and some
 error checking is performed in the case of missing parameters</li>
-<li>A command to clear the shelve is implemented as a flag (<tt class="docutils literal">.clear</tt>).</li>
+<li>A command to clear the shelve is implemented as a flag (<tt class="docutils literal"><span class="pre">.clear</span></tt>).</li>
 <li>A command to delete a given parameter is implemented as an option
-(<tt class="docutils literal">.delete</tt>).</li>
-<li>There is an option with default (<tt class="docutils literal">.filename=conf.shelve</tt>) to store
+(<tt class="docutils literal"><span class="pre">.delete</span></tt>).</li>
+<li>There is an option with default (<tt class="docutils literal"><span class="pre">.filename=conf.shelve</span></tt>) to store
 the filename of the shelve.</li>
 <li>All things considered, the code looks like a poor man object oriented
 interface implemented with a chain of elifs instead of methods. Of course,
 <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> can do better than that, but let me start from a low-level approach
 first.</li>
 </ol>
-<p>If you run <tt class="docutils literal">ishelve.py</tt> without arguments you get the following
+<p>If you run <tt class="docutils literal"><span class="pre">ishelve.py</span></tt> without arguments you get the following
 message:</p>
 <pre class="literal-block">
 $ python ishelve.py
 no arguments passed, use .help to see the available commands
 </pre>
-<p>If you run <tt class="docutils literal">ishelve.py</tt> with the option <tt class="docutils literal">.h</tt> (or any abbreviation
-of <tt class="docutils literal">.help</tt>) you get:</p>
+<p>If you run <tt class="docutils literal"><span class="pre">ishelve.py</span></tt> with the option <tt class="docutils literal"><span class="pre">.h</span></tt> (or any abbreviation
+of <tt class="docutils literal"><span class="pre">.help</span></tt>) you get:</p>
 <pre class="literal-block">
 $ python ishelve.py .h
 Commands: .help, .showall, .clear, .delete
@@ -1322,7 +1326,7 @@ following assumes knowledge of <a class="reference external" href="http://argpar
 <li>plac does not support the destination concept: the destination
 coincides with the name of the argument, always. This restriction
 has some drawbacks. For instance, suppose you want to define a long
-option called <tt class="docutils literal"><span class="pre">--yield</span></tt>. In this case the destination would be <tt class="docutils literal">yield</tt>,
+option called <tt class="docutils literal"><span class="pre">--yield</span></tt>. In this case the destination would be <tt class="docutils literal"><span class="pre">yield</span></tt>,
 which is a Python keyword, and since you cannot introduce an
 argument with that name in a function definition, it is impossible
 to implement it. Your choices are to change the name of the long
@@ -1333,16 +1337,16 @@ form - normal users expect options to be optional. You should avoid
 the use of required options whenever possible.</em> Notice that since
 <a class="reference external" href="http://argparse.googlecode.com">argparse</a> supports them, <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> can manage them too, but not directly.</li>
 <li><a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> supports only regular boolean flags. <a class="reference external" href="http://argparse.googlecode.com">argparse</a> has the ability to
-define generalized two-value flags with values different from <tt class="docutils literal">True</tt>
-and <tt class="docutils literal">False</tt>. An earlier version of <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> had this feature too, but
+define generalized two-value flags with values different from <tt class="docutils literal"><span class="pre">True</span></tt>
+and <tt class="docutils literal"><span class="pre">False</span></tt>. An earlier version of <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> had this feature too, but
 since you can use options with two choices instead, and in any case
-the conversion from <tt class="docutils literal">{True, False}</tt> to any couple of values
+the conversion from <tt class="docutils literal"><span class="pre">{True,</span> <span class="pre">False}</span></tt> to any couple of values
 can be trivially implemented with a ternary operator
-(<tt class="docutils literal">value1 if flag else value2</tt>), I have removed it (KISS rules!).</li>
-<li><a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> does not support <tt class="docutils literal">nargs</tt> options directly (it uses them internally,
+(<tt class="docutils literal"><span class="pre">value1</span> <span class="pre">if</span> <span class="pre">flag</span> <span class="pre">else</span> <span class="pre">value2</span></tt>), I have removed it (KISS rules!).</li>
+<li><a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> does not support <tt class="docutils literal"><span class="pre">nargs</span></tt> options directly (it uses them internally,
 though, to implement flag recognition). The reason it that all the use
 cases of interest to me are covered by <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> and did not feel the need
-to increase the learning curve by adding direct support for <tt class="docutils literal">nargs</tt>.</li>
+to increase the learning curve by adding direct support for <tt class="docutils literal"><span class="pre">nargs</span></tt>.</li>
 <li><a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> does support subparsers, but you must read the <a class="reference external" href="in-writing">advanced usage
 document</a> to see how it works.</li>
 <li><a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> does not support actions directly. This also
@@ -1353,14 +1357,14 @@ the  <a class="reference external" href="in-writing">advanced usage document</a>
 <p><a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> can leverage directly on many <a class="reference external" href="http://argparse.googlecode.com">argparse</a> features.</p>
 <p>For instance, you can make invisible an argument in the usage message
 simply by using <tt class="docutils literal"><span class="pre">'==SUPPRESS=='</span></tt> as help string (or
-<tt class="docutils literal">argparse.SUPPRESS</tt>). Similarly, you can use <a class="reference external" href="http://argparse.googlecode.com/svn/tags/r11/doc/other-utilities.html?highlight=filetype#FileType">argparse.FileType</a>
+<tt class="docutils literal"><span class="pre">argparse.SUPPRESS</span></tt>). Similarly, you can use <a class="reference external" href="http://argparse.googlecode.com/svn/tags/r11/doc/other-utilities.html?highlight=filetype#FileType">argparse.FileType</a>
 directly.</p>
 <p>It is also possible to pass options to the underlying
-<tt class="docutils literal">argparse.ArgumentParser</tt> object (currently it accepts the default
-arguments <tt class="docutils literal">description</tt>, <tt class="docutils literal">epilog</tt>, <tt class="docutils literal">prog</tt>, <tt class="docutils literal">usage</tt>,
-<tt class="docutils literal">add_help</tt>, <tt class="docutils literal">argument_default</tt>, <tt class="docutils literal">parents</tt>, <tt class="docutils literal">prefix_chars</tt>,
-<tt class="docutils literal">fromfile_prefix_chars</tt>, <tt class="docutils literal">conflict_handler</tt>, <tt class="docutils literal">formatter_class</tt>).
-It is enough to set such attributes on the <tt class="docutils literal">main</tt> function.  For
+<tt class="docutils literal"><span class="pre">argparse.ArgumentParser</span></tt> object (currently it accepts the default
+arguments <tt class="docutils literal"><span class="pre">description</span></tt>, <tt class="docutils literal"><span class="pre">epilog</span></tt>, <tt class="docutils literal"><span class="pre">prog</span></tt>, <tt class="docutils literal"><span class="pre">usage</span></tt>,
+<tt class="docutils literal"><span class="pre">add_help</span></tt>, <tt class="docutils literal"><span class="pre">argument_default</span></tt>, <tt class="docutils literal"><span class="pre">parents</span></tt>, <tt class="docutils literal"><span class="pre">prefix_chars</span></tt>,
+<tt class="docutils literal"><span class="pre">fromfile_prefix_chars</span></tt>, <tt class="docutils literal"><span class="pre">conflict_handler</span></tt>, <tt class="docutils literal"><span class="pre">formatter_class</span></tt>).
+It is enough to set such attributes on the <tt class="docutils literal"><span class="pre">main</span></tt> function.  For
 instance</p>
 <pre class="literal-block">
 def main(...):
@@ -1373,22 +1377,22 @@ mechanism does not look particularly elegant, but it works well
 enough.  I assume that the typical user of <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> will be happy with
 the defaults and would not want to change them; still it is possible
 if she wants to.</p>
-<p>For instance, by setting the <tt class="docutils literal">description</tt> attribute, it is possible
+<p>For instance, by setting the <tt class="docutils literal"><span class="pre">description</span></tt> attribute, it is possible
 to add a comment to the usage message (by default the docstring of the
-<tt class="docutils literal">main</tt> function is used as description).</p>
+<tt class="docutils literal"><span class="pre">main</span></tt> function is used as description).</p>
 <p>It is also possible to change the option prefix; for
 instance if your script must run under Windows and you want to use &quot;/&quot;
 as option prefix you can add the line:</p>
 <pre class="literal-block">
 main.prefix_chars='/-'
 </pre>
-<p>The first prefix char (<tt class="docutils literal">/</tt>) is used
+<p>The first prefix char (<tt class="docutils literal"><span class="pre">/</span></tt>) is used
 as the default for the recognition of options and flags;
-the second prefix char (<tt class="docutils literal">-</tt>) is kept to keep the <tt class="docutils literal"><span class="pre">-h/--help</span></tt> option
+the second prefix char (<tt class="docutils literal"><span class="pre">-</span></tt>) is kept to keep the <tt class="docutils literal"><span class="pre">-h/--help</span></tt> option
 working: however you can disable it and reimplement it, if you like,
-as seen in the <tt class="docutils literal">ishelve</tt> example.</p>
+as seen in the <tt class="docutils literal"><span class="pre">ishelve</span></tt> example.</p>
 <p>It is possible to access directly the underlying <a class="reference external" href="http://argparse.googlecode.com/svn/tags/r11/doc/ArgumentParser.html">ArgumentParser</a> object, by
-invoking the <tt class="docutils literal">plac.parser_from</tt> utility function:</p>
+invoking the <tt class="docutils literal"><span class="pre">plac.parser_from</span></tt> utility function:</p>
 <pre class="doctest-block">
 &gt;&gt;&gt; import plac
 &gt;&gt;&gt; def main(arg):
@@ -1397,17 +1401,17 @@ invoking the <tt class="docutils literal">plac.parser_from</tt> utility function
 &gt;&gt;&gt; print(plac.parser_from(main)) #doctest: +ELLIPSIS
 ArgumentParser(prog=...)
 </pre>
-<p>Internally <tt class="docutils literal">plac.call</tt> uses <tt class="docutils literal">plac.parser_from</tt> and adds the parser
-to the main function as an attribute.  When <tt class="docutils literal">plac.call(func)</tt> is
+<p>Internally <tt class="docutils literal"><span class="pre">plac.call</span></tt> uses <tt class="docutils literal"><span class="pre">plac.parser_from</span></tt> and adds the parser
+to the main function as an attribute.  When <tt class="docutils literal"><span class="pre">plac.call(func)</span></tt> is
 invoked multiple time, the parser is re-used and not rebuilt from scratch again.</p>
-<p>I use <tt class="docutils literal">plac.parser_from</tt> in the unit tests of the module, but regular
+<p>I use <tt class="docutils literal"><span class="pre">plac.parser_from</span></tt> in the unit tests of the module, but regular
 users should not need to use it, unless they want to access <em>all</em>
 of the features of <a class="reference external" href="http://argparse.googlecode.com">argparse</a> directly without calling the main function.</p>
 <p>Interested readers should read the documentation of <a class="reference external" href="http://argparse.googlecode.com">argparse</a> to
 understand the meaning of the other options. If there is a set of
 options that you use very often, you may consider writing a decorator
-adding such options to the <tt class="docutils literal">main</tt> function for you. For simplicity,
-<a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> does not perform any magic except the addition of the <tt class="docutils literal">.p</tt>
+adding such options to the <tt class="docutils literal"><span class="pre">main</span></tt> function for you. For simplicity,
+<a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> does not perform any magic except the addition of the <tt class="docutils literal"><span class="pre">.p</span></tt>
 attribute.</p>
 </div>
 <div class="section" id="plac-vs-the-rest-of-the-world">
@@ -1448,10 +1452,10 @@ quite advanced tool with a domain of applicability which far exceeds
 the realm of command-line arguments parsers.</p>
 <p>Version 0.5 of <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> doubled the code base and the documentation: it is
 based on the idea of using <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> to implement command-line interpreters,
-i.e. something akin to the <tt class="docutils literal">cmd</tt> module in the standard library, only better.
+i.e. something akin to the <tt class="docutils literal"><span class="pre">cmd</span></tt> module in the standard library, only better.
 The new features of <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> are described in the <a class="reference external" href="in-writing">advanced usage document</a> .
-They are implemented in a separated module (<tt class="docutils literal">plac_ext.py</tt>), since
-they require Python 2.5 to work, whereas <tt class="docutils literal">plac_core.py</tt> only requires
+They are implemented in a separated module (<tt class="docutils literal"><span class="pre">plac_ext.py</span></tt>), since
+they require Python 2.5 to work, whereas <tt class="docutils literal"><span class="pre">plac_core.py</span></tt> only requires
 Python 2.3.</p>
 </div>
 <div class="section" id="trivia-the-story-behind-the-name">
@@ -1471,8 +1475,8 @@ of functions annotations in Python 3.</li>
 </ol>
 <p>Putting together these two observations with the original idea of inferring the
 parser I decided to build an <a class="reference external" href="http://argparse.googlecode.com/svn/tags/r11/doc/ArgumentParser.html">ArgumentParser</a> object from function
-annotations. The <tt class="docutils literal">optionparser</tt> name was ruled out, since I was
-now using <a class="reference external" href="http://argparse.googlecode.com">argparse</a>; a name like <tt class="docutils literal">argparse_plus</tt> was also ruled out,
+annotations. The <tt class="docutils literal"><span class="pre">optionparser</span></tt> name was ruled out, since I was
+now using <a class="reference external" href="http://argparse.googlecode.com">argparse</a>; a name like <tt class="docutils literal"><span class="pre">argparse_plus</span></tt> was also ruled out,
 since the typical usage was completely different from the <a class="reference external" href="http://argparse.googlecode.com">argparse</a> usage.</p>
 <p>I made a research on PyPI and the name <em>clap</em> (Command Line Arguments Parser)
 was not taken, so I renamed everything to clap. After two days
@@ -1499,7 +1503,7 @@ will steal it from me!</p>
 </tr>
 <tr class="field"><th class="field-name">Project page:</th><td class="field-body"><a class="reference external" href="http://micheles.googlecode.com/hg/plac/doc/plac.html">http://micheles.googlecode.com/hg/plac/doc/plac.html</a></td>
 </tr>
-<tr class="field"><th class="field-name">Installation:</th><td class="field-body"><tt class="docutils literal">easy_install <span class="pre">-U</span> plac</tt></td>
+<tr class="field"><th class="field-name">Installation:</th><td class="field-body"><tt class="docutils literal"><span class="pre">easy_install</span> <span class="pre">-U</span> <span class="pre">plac</span></tt></td>
 </tr>
 <tr class="field"><th class="field-name">License:</th><td class="field-body">BSD license</td>
 </tr>
@@ -1571,7 +1575,7 @@ write domain specific languages (DSL). With <a class="reference external" href="
 can test your application interactively as well as with batch
 scripts, and even with the analogous of Python doctests for your
 defined language.</p>
-<p>You can easily replace the <tt class="docutils literal">cmd</tt> module of the standard library and
+<p>You can easily replace the <tt class="docutils literal"><span class="pre">cmd</span></tt> module of the standard library and
 you could easily write an application like <a class="reference external" href="http://twill.idyll.org/">twill</a> with <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a>. Or you
 could use it to script your building procedure. <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> also supports
 parallel execution of multiple commands and can be used as
@@ -1585,13 +1589,13 @@ you can do with <a class="reference external" href="http://pypi.python.org/pypi/
 for interactive applications.
 In particular, if you have a script with a large startup time which must be run
 multiple times, it is best to turn it into an interactive application,
-so that the startup is performed only once.  <tt class="docutils literal">plac</tt> provides an
-<tt class="docutils literal">Interpreter</tt> class just for this purpose.</p>
-<p>The <tt class="docutils literal">Interpreter</tt> class wraps the main function of a script and
-provides an <tt class="docutils literal">.interact</tt> method to start an interactive interpreter
+so that the startup is performed only once.  <tt class="docutils literal"><span class="pre">plac</span></tt> provides an
+<tt class="docutils literal"><span class="pre">Interpreter</span></tt> class just for this purpose.</p>
+<p>The <tt class="docutils literal"><span class="pre">Interpreter</span></tt> class wraps the main function of a script and
+provides an <tt class="docutils literal"><span class="pre">.interact</span></tt> method to start an interactive interpreter
 reading commands from the console.</p>
 <p>For instance, you can define an interactive interpreter on top of the
-<tt class="docutils literal">ishelve</tt> script introduced in the <a class="reference external" href="http://micheles.googlecode.com/hg/plac/doc/plac.html">basic documentation</a> as
+<tt class="docutils literal"><span class="pre">ishelve</span></tt> script introduced in the <a class="reference external" href="http://micheles.googlecode.com/hg/plac/doc/plac.html">basic documentation</a> as
 follows:</p>
 <pre class="literal-block">
 # shelve_interpreter.py
@@ -1618,7 +1622,7 @@ if __name__ == '__main__':
 <p>A trick has been used here: the ishelve command-line interface has been
 hidden inside an external interface. They are distinct: for instance
 the external interface recognizes the <tt class="docutils literal"><span class="pre">-h/--help</span></tt> flag whereas the
-internal interface only recognizes the <tt class="docutils literal">.help</tt> command:</p>
+internal interface only recognizes the <tt class="docutils literal"><span class="pre">.help</span></tt> command:</p>
 <pre class="literal-block">
 $ python shelve_interpreter.py -h
 </pre>
@@ -1669,17 +1673,17 @@ i&gt; .show
 b=2
 i&gt; [CTRL-D]
 </pre>
-<p>The <tt class="docutils literal">.interact</tt> method
+<p>The <tt class="docutils literal"><span class="pre">.interact</span></tt> method
 reads commands from the console and send them to the
 underlying interpreter, until the user send a CTRL-D
 command (CTRL-Z in Windows). There is a default
-argument <tt class="docutils literal"><span class="pre">prompt='i&gt;</span> '</tt> which
+argument <tt class="docutils literal"><span class="pre">prompt='i&gt;</span> <span class="pre">'</span></tt> which
 can be used to change the prompt. The text displayed at the beginning
 of the interactive session is the docstring of the main function.
-<tt class="docutils literal">plac</tt> also understands command abbreviations: in this example
-<tt class="docutils literal">del</tt> is an abbreviation for <tt class="docutils literal">delete</tt>. In case of ambiguous
-abbreviations <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> raises a <tt class="docutils literal">NameError</tt>.</p>
-<p>Finally I must notice that the <tt class="docutils literal">plac.Interpreter</tt> is available only if you
+<tt class="docutils literal"><span class="pre">plac</span></tt> also understands command abbreviations: in this example
+<tt class="docutils literal"><span class="pre">del</span></tt> is an abbreviation for <tt class="docutils literal"><span class="pre">delete</span></tt>. In case of ambiguous
+abbreviations <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> raises a <tt class="docutils literal"><span class="pre">NameError</span></tt>.</p>
+<p>Finally I must notice that the <tt class="docutils literal"><span class="pre">plac.Interpreter</span></tt> is available only if you
 are using a recent version of Python (&gt;= 2.5), because it is a context
 manager object which uses extended generators internally.</p>
 </div>
@@ -1688,7 +1692,7 @@ manager object which uses extended generators internally.</p>
 <p>You can conveniently test your application in interactive mode.
 However manual testing is a poor substitute for automatic testing.</p>
 <p>In principle, one could write automatic tests for the
-<tt class="docutils literal">ishelve</tt> application by using <tt class="docutils literal">plac.call</tt> directly:</p>
+<tt class="docutils literal"><span class="pre">ishelve</span></tt> application by using <tt class="docutils literal"><span class="pre">plac.call</span></tt> directly:</p>
 <pre class="literal-block">
 # test_ishelve.py
 import plac, ishelve
@@ -1704,15 +1708,15 @@ if __name__ == '__main__':
     test()
 
 </pre>
-<p>However, using <tt class="docutils literal">plac.call</tt> is not especially nice. The big
-issue is that <tt class="docutils literal">plac.call</tt> responds to invalid input by printing an
-error message on stderr and by raising a <tt class="docutils literal">SystemExit</tt>: this is
+<p>However, using <tt class="docutils literal"><span class="pre">plac.call</span></tt> is not especially nice. The big
+issue is that <tt class="docutils literal"><span class="pre">plac.call</span></tt> responds to invalid input by printing an
+error message on stderr and by raising a <tt class="docutils literal"><span class="pre">SystemExit</span></tt>: this is
 certainly not a nice thing to do in a test.</p>
 <p>As a consequence of this behavior it is impossible to test for invalid
-commands, unless you wrap the <tt class="docutils literal">SystemExit</tt> exception by
+commands, unless you wrap the <tt class="docutils literal"><span class="pre">SystemExit</span></tt> exception by
 hand each time (a possibly you do something with the error message in
-stderr too). Luckily, <tt class="docutils literal">plac</tt> offers a better testing support through
-the <tt class="docutils literal">check</tt> method of <tt class="docutils literal">Interpreter</tt> objects:</p>
+stderr too). Luckily, <tt class="docutils literal"><span class="pre">plac</span></tt> offers a better testing support through
+the <tt class="docutils literal"><span class="pre">check</span></tt> method of <tt class="docutils literal"><span class="pre">Interpreter</span></tt> objects:</p>
 <pre class="literal-block">
 # test_ishelve_more.py
 from __future__ import with_statement
@@ -1727,36 +1731,36 @@ def test():
         i.check('a', 'a: not found')
 
 </pre>
-<p>The method <tt class="docutils literal">.check(given_input, expected_output)</tt> works on strings
-and raises an <tt class="docutils literal">AssertionError</tt> if the output produced by the
+<p>The method <tt class="docutils literal"><span class="pre">.check(given_input,</span> <span class="pre">expected_output)</span></tt> works on strings
+and raises an <tt class="docutils literal"><span class="pre">AssertionError</span></tt> if the output produced by the
 interpreter is different from the expected output for the given input.
-Notice that <tt class="docutils literal">AssertionError</tt> is catched by tools like <tt class="docutils literal">py.test</tt> and
-<tt class="docutils literal">nosetests</tt> and actually <tt class="docutils literal">plac</tt> tests are intended to be run with
+Notice that <tt class="docutils literal"><span class="pre">AssertionError</span></tt> is catched by tools like <tt class="docutils literal"><span class="pre">py.test</span></tt> and
+<tt class="docutils literal"><span class="pre">nosetests</span></tt> and actually <tt class="docutils literal"><span class="pre">plac</span></tt> tests are intended to be run with
 such tools.</p>
 <p>Interpreters offer a minor syntactic advantage with respect to calling
-<tt class="docutils literal">plac.call</tt> directly, but they offer a <em>major</em> semantic advantage when things
-go wrong (read exceptions): an <tt class="docutils literal">Interpreter</tt> object internally invokes
-something like <tt class="docutils literal">plac.call</tt>, but it wraps all exceptions, so that <tt class="docutils literal">i.check</tt>
-is guaranteed not to raise any exception except <tt class="docutils literal">AssertionError</tt>.</p>
-<p>Even the <tt class="docutils literal">SystemExit</tt> exception is captured and you can write your test as</p>
+<tt class="docutils literal"><span class="pre">plac.call</span></tt> directly, but they offer a <em>major</em> semantic advantage when things
+go wrong (read exceptions): an <tt class="docutils literal"><span class="pre">Interpreter</span></tt> object internally invokes
+something like <tt class="docutils literal"><span class="pre">plac.call</span></tt>, but it wraps all exceptions, so that <tt class="docutils literal"><span class="pre">i.check</span></tt>
+is guaranteed not to raise any exception except <tt class="docutils literal"><span class="pre">AssertionError</span></tt>.</p>
+<p>Even the <tt class="docutils literal"><span class="pre">SystemExit</span></tt> exception is captured and you can write your test as</p>
 <blockquote>
-<tt class="docutils literal"><span class="pre">i.check('-cler',</span> 'SystemExit: unrecognized arguments: <span class="pre">-cler')</span></tt></blockquote>
+<tt class="docutils literal"><span class="pre">i.check('-cler',</span> <span class="pre">'SystemExit:</span> <span class="pre">unrecognized</span> <span class="pre">arguments:</span> <span class="pre">-cler')</span></tt></blockquote>
 <p>without risk of exiting from the Python interpreter.</p>
 <p>There is a second advantage of interpreters: if the main function contains some
 initialization code and finalization code
-(<tt class="docutils literal">__enter__</tt> and <tt class="docutils literal">__exit__</tt> functions) they will be run only
+(<tt class="docutils literal"><span class="pre">__enter__</span></tt> and <tt class="docutils literal"><span class="pre">__exit__</span></tt> functions) they will be run only
 once at the beginning and at the end of the interpreter loop.
-<tt class="docutils literal">plac.call</tt> instead ignores the initialization/finalization code.</p>
+<tt class="docutils literal"><span class="pre">plac.call</span></tt> instead ignores the initialization/finalization code.</p>
 </div>
 <div class="section" id="plac-easy-tests">
 <h2><a class="toc-backref" href="#id72">Plac easy tests</a></h2>
-<p>Writing your tests in terms of <tt class="docutils literal">Interpreter.check</tt> is certainly an
-improvement over writing them in terms of <tt class="docutils literal">plac.call</tt>, but they
-are still too low-level for my taste. The <tt class="docutils literal">Interpreter</tt> class provides
+<p>Writing your tests in terms of <tt class="docutils literal"><span class="pre">Interpreter.check</span></tt> is certainly an
+improvement over writing them in terms of <tt class="docutils literal"><span class="pre">plac.call</span></tt>, but they
+are still too low-level for my taste. The <tt class="docutils literal"><span class="pre">Interpreter</span></tt> class provides
 support for doctest-style tests, a.k.a. <em>plac easy tests</em>.</p>
 <p>By using plac easy tests you can cut and paste your interactive session and
 turn it into a runnable automatics test.
-Consider for instance the following file <tt class="docutils literal">ishelve.placet</tt> (the <tt class="docutils literal">.placet</tt>
+Consider for instance the following file <tt class="docutils literal"><span class="pre">ishelve.placet</span></tt> (the <tt class="docutils literal"><span class="pre">.placet</span></tt>
 extension is a mnemonic for plac easy tests):</p>
 <pre class="literal-block">
 #!ishelve.py
@@ -1776,45 +1780,45 @@ i&gt; .cler # spelling error
 </pre>
 <p>Notice the precence of the shebang line containing the name of the
 <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> tool to test (a <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> tool is just a Python module with a
-function called <tt class="docutils literal">main</tt>). The shebang is ignored by the interpreter
+function called <tt class="docutils literal"><span class="pre">main</span></tt>). The shebang is ignored by the interpreter
 (it looks like a comment to it) but it is there so that external
 tools (say a test runner) can infer the plac interpreter
 to use to test the file.</p>
-<p>You can test <tt class="docutils literal">ishelve.placet</tt> file by calling the
-<tt class="docutils literal">.doctest</tt> method of the interpreter, as in this example:</p>
+<p>You can test <tt class="docutils literal"><span class="pre">ishelve.placet</span></tt> file by calling the
+<tt class="docutils literal"><span class="pre">.doctest</span></tt> method of the interpreter, as in this example:</p>
 <pre class="literal-block">
 $ python -c&quot;import plac, ishelve
 plac.Interpreter(ishelve.main).doctest(open('ishelve.placet'), verbose=True)&quot;
 </pre>
-<p>Internally <tt class="docutils literal">Interpreter.doctests</tt> invokes something like <tt class="docutils literal">Interpreter.check</tt>
+<p>Internally <tt class="docutils literal"><span class="pre">Interpreter.doctests</span></tt> invokes something like <tt class="docutils literal"><span class="pre">Interpreter.check</span></tt>
 multiple times inside the same context and compare the output with the
 expected output: if even a check fails, the whole test fail.</p>
-<p>You should realize tha the easy tests supported by <tt class="docutils literal">plac</tt> are <em>not</em>
+<p>You should realize tha the easy tests supported by <tt class="docutils literal"><span class="pre">plac</span></tt> are <em>not</em>
 unittests: they are functional tests. They model then user interaction and the
 order of the operations generally matters.  The single subtests in a
-<tt class="docutils literal">.placet</tt> file are not independent and it makes sense to exit
+<tt class="docutils literal"><span class="pre">.placet</span></tt> file are not independent and it makes sense to exit
 immediately at the first failure.</p>
 <p>The support for doctests in <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> comes nearly for free, thanks to the
 <a class="reference external" href="http://docs.python.org/library/shlex.html">shlex</a> module in the standard library, which is able to parse simple
 languages as the ones you can implement with <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a>. In particular,
 thanks to <a class="reference external" href="http://docs.python.org/library/shlex.html">shlex</a>, <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> is able to recognize comments (the default
-comment character is <tt class="docutils literal">#</tt>), escape sequences and more. Look at the
+comment character is <tt class="docutils literal"><span class="pre">#</span></tt>), escape sequences and more. Look at the
 <a class="reference external" href="http://docs.python.org/library/shlex.html">shlex</a> documentation if you need to customize how the language is
 interpreted. For more flexibility, it is even possible to pass to the
-interpreter a custom split function with signature <tt class="docutils literal">split(line,
-commentchar)</tt>.</p>
+interpreter a custom split function with signature <tt class="docutils literal"><span class="pre">split(line,</span>
+<span class="pre">commentchar)</span></tt>.</p>
 <p>In addition, I have implemented from scratch some support for line number
 recognition, so that if a test fail you get the line number of the
 failing command. This is especially useful if your tests are
 stored in external files, even if plac easy tests does not need to be in
-a file: you can just pass to the <tt class="docutils literal">.doctest</tt> method a list of
+a file: you can just pass to the <tt class="docutils literal"><span class="pre">.doctest</span></tt> method a list of
 strings corresponding to the lines of the file.</p>
 <p>At the present <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> does not use any code from the doctest
 module, but the situation may change in the future (it would be nice
 if <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> could reuse doctests directives like ELLIPSIS).</p>
-<p>It is straighforward to integrate your <tt class="docutils literal">.placet</tt> tests with standard
-testing tools. For instance, you can integrate your doctests with <tt class="docutils literal">nose</tt>
-or <tt class="docutils literal">py.test</tt> as follow:</p>
+<p>It is straighforward to integrate your <tt class="docutils literal"><span class="pre">.placet</span></tt> tests with standard
+testing tools. For instance, you can integrate your doctests with <tt class="docutils literal"><span class="pre">nose</span></tt>
+or <tt class="docutils literal"><span class="pre">py.test</span></tt> as follow:</p>
 <pre class="literal-block">
 import os, shlex, plac
 
@@ -1831,32 +1835,32 @@ def test_doct():
        main = plac.import_main(*shlex.split(firstline))
        yield plac.Interpreter(main).doctest, lines[1:]
 </pre>
-<p>Here you should notice that usage of <tt class="docutils literal">plac.import_main</tt>, an utility
+<p>Here you should notice that usage of <tt class="docutils literal"><span class="pre">plac.import_main</span></tt>, an utility
 which is able to import the main function of the script specified in
 the shebang line. You can use both the full path name of the
 tool, or a relative path name. In this case the runner look at the
-environment variable <tt class="docutils literal">PLACPATH</tt> and it searches
-the plac tool in the directories specified there (<tt class="docutils literal">PLACPATH</tt> is just
+environment variable <tt class="docutils literal"><span class="pre">PLACPATH</span></tt> and it searches
+the plac tool in the directories specified there (<tt class="docutils literal"><span class="pre">PLACPATH</span></tt> is just
 a string containing directory names separated by colons). If the variable
-<tt class="docutils literal">PLACPATH</tt> is not defined, it just looks in the current directory.
-If the plac tool is not found, an <tt class="docutils literal">ImportError</tt> is raised.</p>
+<tt class="docutils literal"><span class="pre">PLACPATH</span></tt> is not defined, it just looks in the current directory.
+If the plac tool is not found, an <tt class="docutils literal"><span class="pre">ImportError</span></tt> is raised.</p>
 </div>
 <div class="section" id="plac-batch-scripts">
 <h2><a class="toc-backref" href="#id73">Plac batch scripts</a></h2>
 <p>It is pretty easy to realize that an interactive interpreter can
 also be used to run batch scripts: instead of reading the commands from
 the console, it is enough to read the commands from a file.
-<a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> interpreters provide an <tt class="docutils literal">.execute</tt> method to perform just that.</p>
+<a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> interpreters provide an <tt class="docutils literal"><span class="pre">.execute</span></tt> method to perform just that.</p>
 <p>There is just a subtle point to notice: whereas in an interactive loop
 one wants to manage all exceptions, a batch script should not in the
 background in case of unexpected errors. The implementation of
-<tt class="docutils literal">Interpreter.execute</tt> makes sure that any error raised by
-<tt class="docutils literal">plac.call</tt> internally is re-raised.  In other words, <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a>
+<tt class="docutils literal"><span class="pre">Interpreter.execute</span></tt> makes sure that any error raised by
+<tt class="docutils literal"><span class="pre">plac.call</span></tt> internally is re-raised.  In other words, <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a>
 interpreters <em>wrap the errors, but does not eat them</em>: the errors are
 always accessible and can be re-raised on demand.</p>
 <p>The exception is the case of invalid commands, which are skipped.
 Consider for instance the following batch file, which contains a
-mispelled command (<tt class="docutils literal">.dl</tt> instead of <tt class="docutils literal">.del</tt>):</p>
+mispelled command (<tt class="docutils literal"><span class="pre">.dl</span></tt> instead of <tt class="docutils literal"><span class="pre">.del</span></tt>):</p>
 <pre class="literal-block">
 #!ishelve.py
 .clear 
@@ -1867,8 +1871,8 @@ a=1 b=2
 .show
 
 </pre>
-<p>If you execute the batch file, the interpreter will print a <tt class="docutils literal">.dl: not found</tt>
-at the <tt class="docutils literal">.dl</tt> line and will continue:</p>
+<p>If you execute the batch file, the interpreter will print a <tt class="docutils literal"><span class="pre">.dl:</span> <span class="pre">not</span> <span class="pre">found</span></tt>
+at the <tt class="docutils literal"><span class="pre">.dl</span></tt> line and will continue:</p>
 <pre class="literal-block">
 $ python -c &quot;import plac, ishelve
 plac.Interpreter(ishelve.main).execute(open('ishelve.plac'), verbose=True)&quot;
@@ -1888,14 +1892,14 @@ i&gt; .dl b
 i&gt; .show
 b=2
 </pre>
-<p>The <tt class="docutils literal">verbose</tt> flag is there to show the lines which are being interpreted
-(prefixed by <tt class="docutils literal">i&gt;</tt>). This is done on purpose, so that you can cut and paste
-the output of the batch script and turn it into a <tt class="docutils literal">.placet</tt> test
+<p>The <tt class="docutils literal"><span class="pre">verbose</span></tt> flag is there to show the lines which are being interpreted
+(prefixed by <tt class="docutils literal"><span class="pre">i&gt;</span></tt>). This is done on purpose, so that you can cut and paste
+the output of the batch script and turn it into a <tt class="docutils literal"><span class="pre">.placet</span></tt> test
 (cool, isn't it?).</p>
 </div>
 <div class="section" id="implementing-subcommands">
 <h2><a class="toc-backref" href="#id74">Implementing subcommands</a></h2>
-<p>When I discussed the <tt class="docutils literal">ishelve</tt> implementation in the <a class="reference external" href="http://micheles.googlecode.com/hg/plac/doc/plac.html">basic
+<p>When I discussed the <tt class="docutils literal"><span class="pre">ishelve</span></tt> implementation in the <a class="reference external" href="http://micheles.googlecode.com/hg/plac/doc/plac.html">basic
 documentation</a>, I said that it looked like a poor man implementation
 of an object system as a chain of elifs; I also said that <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> was
 able to do much better than that.  Here I will substantiate my claim.</p>
@@ -1903,10 +1907,10 @@ able to do much better than that.  Here I will substantiate my claim.</p>
 generic container of commands.  This is useful if you want to
 implement <em>subcommands</em> (a familiar example of a command-line
 application featuring subcommands is subversion).</p>
-<p>Technically a container of commands is any object with a <tt class="docutils literal">.commands</tt> attribute
+<p>Technically a container of commands is any object with a <tt class="docutils literal"><span class="pre">.commands</span></tt> attribute
 listing a set of functions or methods which are valid commands. A command
-container may have initialization/finalization hooks (<tt class="docutils literal">__enter__/__exit__</tt>)
-and dispatch hooks (<tt class="docutils literal">__missing__</tt>, invoked for invalid command names).
+container may have initialization/finalization hooks (<tt class="docutils literal"><span class="pre">__enter__/__exit__</span></tt>)
+and dispatch hooks (<tt class="docutils literal"><span class="pre">__missing__</span></tt>, invoked for invalid command names).
 Moreover, only when using command containers <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> is able to provide
 automatic autocompletion of commands.</p>
 <p>The shelve interface can be rewritten in an object-oriented way as follows:</p>
@@ -1956,24 +1960,24 @@ if __name__ == '__main__':
     plac.Interpreter(plac.call(ShelveInterface)).interact()
 
 </pre>
-<p><tt class="docutils literal">plac.Interpreter</tt> objects wrap context manager objects
+<p><tt class="docutils literal"><span class="pre">plac.Interpreter</span></tt> objects wrap context manager objects
 consistently.  In other words, if you wrap an object with
-<tt class="docutils literal">__enter__</tt> and <tt class="docutils literal">__exit__</tt> methods, they are invoked in the right
-order (<tt class="docutils literal">__enter__</tt> before the interpreter loop starts and
-<tt class="docutils literal">__exit__</tt> after the interpreter loop ends, both in the regular and
-in the exceptional case). In our example, the methods <tt class="docutils literal">__enter__</tt>
-and <tt class="docutils literal">__exit__</tt> make sure the the shelve is opened and closed
+<tt class="docutils literal"><span class="pre">__enter__</span></tt> and <tt class="docutils literal"><span class="pre">__exit__</span></tt> methods, they are invoked in the right
+order (<tt class="docutils literal"><span class="pre">__enter__</span></tt> before the interpreter loop starts and
+<tt class="docutils literal"><span class="pre">__exit__</span></tt> after the interpreter loop ends, both in the regular and
+in the exceptional case). In our example, the methods <tt class="docutils literal"><span class="pre">__enter__</span></tt>
+and <tt class="docutils literal"><span class="pre">__exit__</span></tt> make sure the the shelve is opened and closed
 correctly even in the case of exceptions. Notice that I have not
-implemented any error checking in the <tt class="docutils literal">show</tt> and <tt class="docutils literal">delete</tt> methods
+implemented any error checking in the <tt class="docutils literal"><span class="pre">show</span></tt> and <tt class="docutils literal"><span class="pre">delete</span></tt> methods
 on purpose, to verify that <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> works correctly in the presence of
 exceptions.</p>
 <p>When working with command containers, <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> automatically adds two
-special commands to the set of provided commands: <tt class="docutils literal">.help</tt>
-and <tt class="docutils literal">.last_tb</tt>. The <tt class="docutils literal">.help</tt> command is the easier to understand:
+special commands to the set of provided commands: <tt class="docutils literal"><span class="pre">.help</span></tt>
+and <tt class="docutils literal"><span class="pre">.last_tb</span></tt>. The <tt class="docutils literal"><span class="pre">.help</span></tt> command is the easier to understand:
 when invoked without arguments it displays the list of available commands
 with the same formatting of the <a class="reference external" href="http://docs.python.org/library/cmd.html">cmd</a> module; when invoked with the name of
 a command it displays the usage message for that command.
-The <tt class="docutils literal">.last_tb</tt> command is useful when debugging: in case of errors,
+The <tt class="docutils literal"><span class="pre">.last_tb</span></tt> command is useful when debugging: in case of errors,
 it allows you to display the traceback of the last executed command.</p>
 <p>Here is a session of usage on an Unix-like operating system:</p>
 <pre class="literal-block">
@@ -2020,23 +2024,23 @@ i&gt; .last_tb
 i&gt;
 </pre>
 <p>Notice that in interactive mode the traceback is hidden, unless
-you pass the <tt class="docutils literal">verbose</tt> flag to the <tt class="docutils literal">Interpreter.interact</tt> method.</p>
+you pass the <tt class="docutils literal"><span class="pre">verbose</span></tt> flag to the <tt class="docutils literal"><span class="pre">Interpreter.interact</span></tt> method.</p>
 </div>
 <div class="section" id="plac-interpreter-call">
 <h2><a class="toc-backref" href="#id75">plac.Interpreter.call</a></h2>
-<p>At the core of <tt class="docutils literal">plac</tt> there is the <tt class="docutils literal">call</tt> function which invokes
+<p>At the core of <tt class="docutils literal"><span class="pre">plac</span></tt> there is the <tt class="docutils literal"><span class="pre">call</span></tt> function which invokes
 a callable with the list of the arguments passed at the command-line
-(<tt class="docutils literal">sys.argv[1:]</tt>). Thanks to <tt class="docutils literal">plac.call</tt> you can launch your module
+(<tt class="docutils literal"><span class="pre">sys.argv[1:]</span></tt>). Thanks to <tt class="docutils literal"><span class="pre">plac.call</span></tt> you can launch your module
 by simply adding the lines:</p>
 <pre class="literal-block">
 if __name__ == '__main__':
     plac.call(main)
 </pre>
-<p>Everything works fine if <tt class="docutils literal">main</tt> is a simple callable performing some
-action; however, in many cases, one has a <tt class="docutils literal">main</tt> &quot;function&quot; which
+<p>Everything works fine if <tt class="docutils literal"><span class="pre">main</span></tt> is a simple callable performing some
+action; however, in many cases, one has a <tt class="docutils literal"><span class="pre">main</span></tt> &quot;function&quot; which
 is a actually a factory returning a command container object. For
 instance, in my second shelve example the main function is the class
-<tt class="docutils literal">ShelveInterface</tt>, and the two lines needed to run the module are
+<tt class="docutils literal"><span class="pre">ShelveInterface</span></tt>, and the two lines needed to run the module are
 a bit ugly:</p>
 <pre class="literal-block">
 if __name__ == '__main__':
@@ -2046,14 +2050,14 @@ if __name__ == '__main__':
 it is not possible to run it as a script. It would be nice instead
 to be able to specify the command to execute on the command-line
 and have the interpreter start, execute the command and finish
-properly (I mean by calling <tt class="docutils literal">__enter__</tt> and <tt class="docutils literal">__exit__</tt>)
+properly (I mean by calling <tt class="docutils literal"><span class="pre">__enter__</span></tt> and <tt class="docutils literal"><span class="pre">__exit__</span></tt>)
 without needing user input. The the script could be called from
 a batch shell script working in the background.
-In order to provide such functionality <tt class="docutils literal">plac.Interpreter</tt> provides
-a classmethod named <tt class="docutils literal">.call</tt> which takes the factory, instantiates
+In order to provide such functionality <tt class="docutils literal"><span class="pre">plac.Interpreter</span></tt> provides
+a classmethod named <tt class="docutils literal"><span class="pre">.call</span></tt> which takes the factory, instantiates
 it with the arguments read from the command line, wraps the resulting
 container object as an interpreter and runs it with the rest arguments
-found in the command line. Here is the code to turn the <tt class="docutils literal">ShelveInterface</tt>
+found in the command line. Here is the code to turn the <tt class="docutils literal"><span class="pre">ShelveInterface</span></tt>
 into a script</p>
 <pre class="literal-block">
 # ishelve3.py
@@ -2066,29 +2070,27 @@ if __name__ == '__main__':
 <p>and here are a few examples of usage:</p>
 <pre class="literal-block">
 $ python ishelve3.py -h
-</pre>
-<pre class="literal-block">
-usage: ishelve3.py [-h] [-configfile CONFIGFILE]
+usage: ishelve3.py [-h] [-i] [-configfile CONFIGFILE] [args [args ...]]
 
-A minimal interface over a shelve object.
+positional arguments:
+  args
 
 optional arguments:
   -h, --help            show this help message and exit
+  -i, --interact        start interactive interpreter
   -configfile CONFIGFILE
                         path name of the shelve
 
-</pre>
-<pre class="literal-block">
 $ python ishelve3.py set a 1
 setting a=1
 $ python ishelve3.py show a
 a = 1
 </pre>
-<p>If you do not pass enough arguments in the command line, then the
-script will automatically enter in interactive mode and ask the user
-for the command to execute:</p>
+<p>If you pass the <tt class="docutils literal"><span class="pre">-i</span></tt> flag in the command line, then the
+script will enter in interactive mode and ask the user
+for the commands to execute:</p>
 <pre class="literal-block">
-$ python ishelve3.py
+$ python ishelve3.py -i
 A minimal interface over a shelve object.
 Operating on /home/micheles/conf.shelve.
 .help to see the available commands.
@@ -2097,21 +2099,21 @@ i&gt;
 </pre>
 <p>In a sense, I have closed the circle: at the beginning of this
 document I discussed how to turn a script into an interactive
-application (the <tt class="docutils literal">shelve_interpreter.py</tt> example), whereas here I
+application (the <tt class="docutils literal"><span class="pre">shelve_interpreter.py</span></tt> example), whereas here I
 have show how to turn an interactive application into a script.</p>
-<p>The complete signature of <tt class="docutils literal">plac.Interpreter.call</tt> is the following:</p>
+<p>The complete signature of <tt class="docutils literal"><span class="pre">plac.Interpreter.call</span></tt> is the following:</p>
 <pre class="literal-block">
 call(factory, arglist=sys.argv[1:],
      commentchar='#', split=shlex.split,
      stdin=sys.stdin, prompt='i&gt; ', verbose=False)
 </pre>
 <p>The factory must have a fixed number of positional arguments (no
-default arguments, no varargs, no kwargs), otherwise a <tt class="docutils literal">TypeError</tt>
+default arguments, no varargs, no kwargs), otherwise a <tt class="docutils literal"><span class="pre">TypeError</span></tt>
 is raised: the reason is that we want to be able to distinguish the
 command-line arguments needed to instantiate the factory from the rest
 arguments that must be sent to the corresponding interpreter object.
 It is also possible to specify a list of arguments different from
-<tt class="docutils literal">sys.argv[1:]</tt> (useful in tests), the character to be recognized as
+<tt class="docutils literal"><span class="pre">sys.argv[1:]</span></tt> (useful in tests), the character to be recognized as
 a comment, the splitting function, the input source and the prompt to
 use while in interactive mode, and a verbose flag.</p>
 </div>
@@ -2122,8 +2124,8 @@ means that if your Python was compiled with readline support you get
 autocompletion and persistent command history for free.  By default
 all commands are autocomplete in a case sensitive way.  If you want to
 add new words to the autocompletion set, or you want to change the
-location of the <tt class="docutils literal">.history</tt> file, or to change the case sensitivity,
-the way to go is to pass a <tt class="docutils literal">plac.ReadlineInput</tt> object to the
+location of the <tt class="docutils literal"><span class="pre">.history</span></tt> file, or to change the case sensitivity,
+the way to go is to pass a <tt class="docutils literal"><span class="pre">plac.ReadlineInput</span></tt> object to the
 interpreter.  Here is an example, assuming you want to build a
 database interface understanding SQL commands:</p>
 <pre class="literal-block">
@@ -2163,9 +2165,9 @@ $ python sql_interface.py &lt;some dsn&gt;
 sql&gt; SELECT a.* FROM TABLE1 AS a INNER JOIN TABLE2 AS b ON a.id = b.id
 ...
 </pre>
-<p>You can check that entering just <tt class="docutils literal">sel</tt> and pressing TAB the readline library
-completes the <tt class="docutils literal">SELECT</tt> keyword for you and makes it upper case; idem for
-<tt class="docutils literal">FROM</tt>, <tt class="docutils literal">INNER</tt>, <tt class="docutils literal">JOIN</tt> and even for the names of the tables. An
+<p>You can check that entering just <tt class="docutils literal"><span class="pre">sel</span></tt> and pressing TAB the readline library
+completes the <tt class="docutils literal"><span class="pre">SELECT</span></tt> keyword for you and makes it upper case; idem for
+<tt class="docutils literal"><span class="pre">FROM</span></tt>, <tt class="docutils literal"><span class="pre">INNER</span></tt>, <tt class="docutils literal"><span class="pre">JOIN</span></tt> and even for the names of the tables. An
 obvious improvement is to read the names of the tables by introspecting
 the database: actually you can even read the names of the views and of
 the columns, and have full autocompletion. All the entered commands
@@ -2181,9 +2183,9 @@ readline library only if available, it does not include it and it does
 not rely on it in any fundamental way, so that the <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> licence does
 not need to be the GPL (actually it is a BSD
 do-whatever-you-want-with-it licence).</p>
-<p>The interactive mode of <tt class="docutils literal">plac</tt> can be used as a replacement of the
+<p>The interactive mode of <tt class="docutils literal"><span class="pre">plac</span></tt> can be used as a replacement of the
 <a class="reference external" href="http://docs.python.org/library/cmd.html">cmd</a> module in the standard library. It is actually better than <a class="reference external" href="http://docs.python.org/library/cmd.html">cmd</a>:
-for instance, the <tt class="docutils literal">.help</tt> command is more powerful, since it
+for instance, the <tt class="docutils literal"><span class="pre">.help</span></tt> command is more powerful, since it
 provides information about the arguments accepted by the given command:</p>
 <pre class="literal-block">
 i&gt; .help set
@@ -2217,7 +2219,7 @@ options, flags, varargs, keyword arguments, arguments with defaults,
 arguments with a fixed number of choices, type conversion and all the
 features provided of <a class="reference external" href="http://argparse.googlecode.com">argparse</a> which should be reimplemented from scratch
 using <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a>.</p>
-<p>Moreover at the moment <tt class="docutils literal">plac</tt> also understands command abbreviations.
+<p>Moreover at the moment <tt class="docutils literal"><span class="pre">plac</span></tt> also understands command abbreviations.
 However, this feature may disappear in
 future releases. It was meaningful in the past, when <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> did not support
 readline.</p>
@@ -2229,15 +2231,15 @@ NameError: Ambiguous command 'sh': matching ['showall', 'show']
 </div>
 <div class="section" id="the-plac-runner">
 <h2><a class="toc-backref" href="#id77">The plac runner</a></h2>
-<p>The distribution of <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> includes a runner script named <tt class="docutils literal">plac_runner.py</tt>,
+<p>The distribution of <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> includes a runner script named <tt class="docutils literal"><span class="pre">plac_runner.py</span></tt>,
 which will be installed in a suitable directory in your system by <a class="reference external" href="http://docs.python.org/distutils/">distutils</a>
-(say in <tt class="docutils literal">\usr\local\bin\plac_runner.py</tt> in a Unix-like operative system).
-The runner provides many facilities to run <tt class="docutils literal">.plac</tt> scripts and
-<tt class="docutils literal">.placet</tt> files, as well as Python modules containg a <tt class="docutils literal">main</tt>
+(say in <tt class="docutils literal"><span class="pre">\usr\local\bin\plac_runner.py</span></tt> in a Unix-like operative system).
+The runner provides many facilities to run <tt class="docutils literal"><span class="pre">.plac</span></tt> scripts and
+<tt class="docutils literal"><span class="pre">.placet</span></tt> files, as well as Python modules containg a <tt class="docutils literal"><span class="pre">main</span></tt>
 object, which can be a function, a command container object or
 even a command container class.</p>
 <p>For instance, suppose you want to execute a script containing commands
-defined in the <tt class="docutils literal">ishelve2</tt> module like the following one:</p>
+defined in the <tt class="docutils literal"><span class="pre">ishelve2</span></tt> module like the following one:</p>
 <pre class="literal-block">
 #!ishelve2.py:ShelveInterface -c ~/conf.shelve
 set a 1
@@ -2245,11 +2247,11 @@ del a
 del a # intentional error
 
 </pre>
-<p>The first line of the <tt class="docutils literal">.plac</tt> script contains the name of the
+<p>The first line of the <tt class="docutils literal"><span class="pre">.plac</span></tt> script contains the name of the
 python module containing the plac interpreter and the arguments
 which must be passed to its main function in order to be able
 to instantiate an interpreter object. In this case I appended
-<tt class="docutils literal">:ShelveInterface</tt> to the name of the module to specify the
+<tt class="docutils literal"><span class="pre">:ShelveInterface</span></tt> to the name of the module to specify the
 object that must be imported: if not specified, by default the
 object named 'main' is imported.
 The other lines contains commands.
@@ -2267,9 +2269,9 @@ plac runner does not eat the traceback.</p>
 <p>The runner can also be used to run Python modules in interactive
 mode and non-interactive mode. If you put this alias in your bashrc</p>
 <blockquote>
-<tt class="docutils literal">alias <span class="pre">plac=&quot;plac_runner.py&quot;</span></tt></blockquote>
-<p>(or you define a suitable <tt class="docutils literal">plac.bat</tt> script in Windows) you can
-run the <tt class="docutils literal">ishelve2.py</tt> script in interactive mode as
+<tt class="docutils literal"><span class="pre">alias</span> <span class="pre">plac=&quot;plac_runner.py&quot;</span></tt></blockquote>
+<p>(or you define a suitable <tt class="docutils literal"><span class="pre">plac.bat</span></tt> script in Windows) you can
+run the <tt class="docutils literal"><span class="pre">ishelve2.py</span></tt> script in interactive mode as
 follows:</p>
 <pre class="literal-block">
 $ plac -i ishelve2.py
@@ -2287,7 +2289,7 @@ i&gt; show b
 b = 2
 </pre>
 <p>Now you can cut and paste the interactive session an turns into into
-a <tt class="docutils literal">.placet</tt> file like the following:</p>
+a <tt class="docutils literal"><span class="pre">.placet</span></tt> file like the following:</p>
 <pre class="literal-block">
 #!ishelve2.py:ShelveInterface -configfile=~/test.shelve
 i&gt; del
@@ -2301,7 +2303,7 @@ a = 1
 
 </pre>
 <p>Notice that the first line specifies a test database
-<tt class="docutils literal">~/test.shelve</tt>, to avoid clobbering your default shelve. If you
+<tt class="docutils literal"><span class="pre">~/test.shelve</span></tt>, to avoid clobbering your default shelve. If you
 mispell the arguments in the first line plac will give you an
 <a class="reference external" href="http://argparse.googlecode.com">argparse</a> error message (just try).</p>
 <p>You can run placets following the shebang convention directly with
@@ -2316,17 +2318,17 @@ extension your like, but <em>it relies on the first line of the file to invoke
 the corresponding plac tool with the given arguments</em>.</p>
 <p>The plac runner does not provide any test discovery facility,
 but you can use standard Unix tools to help. For instance, you can
-run all the <tt class="docutils literal">.placet</tt> files into a directory and its subdirectories
+run all the <tt class="docutils literal"><span class="pre">.placet</span></tt> files into a directory and its subdirectories
 as follows:</p>
 <pre class="literal-block">
 $ find . -name \*.placet | xargs plac_runner.py -t
 </pre>
 <p>The plac runner expects the main function of your script to
-return a plac tool, i.e. a function or an object with a <tt class="docutils literal">.commands</tt>
+return a plac tool, i.e. a function or an object with a <tt class="docutils literal"><span class="pre">.commands</span></tt>
 attribute. It this is not the case the runner gracefully exits.</p>
 <p>It also works in non-interactive mode, if you call it as</p>
 <blockquote>
-<tt class="docutils literal">$ plac module.py args ...</tt></blockquote>
+<tt class="docutils literal"><span class="pre">$</span> <span class="pre">plac</span> <span class="pre">module.py</span> <span class="pre">args</span> <span class="pre">...</span></tt></blockquote>
 <p>Here is an example:</p>
 <pre class="literal-block">
 $ plac ishelve.py a=1
@@ -2334,15 +2336,15 @@ setting a=1
 $ plac ishelve.py .show
 a=1
 </pre>
-<p>Notice that in non-interactive mode the runner just invokes <tt class="docutils literal">plac.call</tt>
-on the <tt class="docutils literal">main</tt> object of the Python module.</p>
+<p>Notice that in non-interactive mode the runner just invokes <tt class="docutils literal"><span class="pre">plac.call</span></tt>
+on the <tt class="docutils literal"><span class="pre">main</span></tt> object of the Python module.</p>
 </div>
 <div class="section" id="a-non-class-based-example">
 <h2><a class="toc-backref" href="#id78">A non class-based example</a></h2>
 <p><a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> does not force you to use classes to define command containers.
 Even a simple function can be a valid command container, it is
-enough to add to it a <tt class="docutils literal">.commands</tt> attribute and possibly
-<tt class="docutils literal">__enter__</tt> and/or <tt class="docutils literal">__exit__</tt> attributes.</p>
+enough to add to it a <tt class="docutils literal"><span class="pre">.commands</span></tt> attribute and possibly
+<tt class="docutils literal"><span class="pre">__enter__</span></tt> and/or <tt class="docutils literal"><span class="pre">__exit__</span></tt> attributes.</p>
 <p>In particular, a Python module is a perfect container of commands. As an
 example, consider the following module implementing a fake Version
 Control System:</p>
@@ -2379,13 +2381,13 @@ def __exit__(etype, exc, tb):
 main = __import__(__name__) # the module imports itself!
 
 </pre>
-<p>Notice that I have defined both an <tt class="docutils literal">__exit__</tt> hook and a <tt class="docutils literal">__missing__</tt>
+<p>Notice that I have defined both an <tt class="docutils literal"><span class="pre">__exit__</span></tt> hook and a <tt class="docutils literal"><span class="pre">__missing__</span></tt>
 hook, invoked for non-existing commands.
-The real trick here is the line <tt class="docutils literal">main = __import__(__name__)</tt>, which
-define <tt class="docutils literal">main</tt> to be an alias for the current module.</p>
-<p>The <tt class="docutils literal">vcs</tt> module does not contain an <tt class="docutils literal">if __name__ == '__main__'</tt>
+The real trick here is the line <tt class="docutils literal"><span class="pre">main</span> <span class="pre">=</span> <span class="pre">__import__(__name__)</span></tt>, which
+define <tt class="docutils literal"><span class="pre">main</span></tt> to be an alias for the current module.</p>
+<p>The <tt class="docutils literal"><span class="pre">vcs</span></tt> module does not contain an <tt class="docutils literal"><span class="pre">if</span> <span class="pre">__name__</span> <span class="pre">==</span> <span class="pre">'__main__'</span></tt>
 block, but you can still run it through the plac runner
-(try <tt class="docutils literal">plac vcs.py <span class="pre">-h</span></tt>):</p>
+(try <tt class="docutils literal"><span class="pre">plac</span> <span class="pre">vcs.py</span> <span class="pre">-h</span></tt>):</p>
 <pre class="literal-block">
 usage: plac_runner.py vcs.py [-h] {status,commit,checkout} ...
 
@@ -2443,8 +2445,8 @@ Command 'sto' does not exist
 i&gt; [CTRL-D]
 ok
 </pre>
-<p>Notice the invocation of the <tt class="docutils literal">__missing__</tt> hook for non-existing commands.
-Notice also that the <tt class="docutils literal">__exit__</tt> hook gets called only in interactive
+<p>Notice the invocation of the <tt class="docutils literal"><span class="pre">__missing__</span></tt> hook for non-existing commands.
+Notice also that the <tt class="docutils literal"><span class="pre">__exit__</span></tt> hook gets called only in interactive
 mode.</p>
 <p>If the commands are completely independent, a module is a good fit for
 a method container. In other situations, it is best to use a custom
@@ -2456,21 +2458,21 @@ class.</p>
 small (around 50 lines of code) so that you can study it and write
 your own runner if want to. If you need to go to such level
 of detail, you should know that the most important method of
-the <tt class="docutils literal">Interpreter</tt> class is the <tt class="docutils literal">.send</tt> method, which takes
+the <tt class="docutils literal"><span class="pre">Interpreter</span></tt> class is the <tt class="docutils literal"><span class="pre">.send</span></tt> method, which takes
 strings in input and returns a four-tuple with attributes
-<tt class="docutils literal">.str</tt>, <tt class="docutils literal">.etype</tt>, <tt class="docutils literal">.exc</tt> and <tt class="docutils literal">.tb</tt>:</p>
+<tt class="docutils literal"><span class="pre">.str</span></tt>, <tt class="docutils literal"><span class="pre">.etype</span></tt>, <tt class="docutils literal"><span class="pre">.exc</span></tt> and <tt class="docutils literal"><span class="pre">.tb</span></tt>:</p>
 <ul class="simple">
-<li><tt class="docutils literal">.str</tt> is the output of the command, if successful (a string);</li>
-<li><tt class="docutils literal">.etype</tt> is the class of the exception, if the command fail;</li>
-<li><tt class="docutils literal">.exc</tt> is the exception instance;</li>
-<li><tt class="docutils literal">.tb</tt> is the traceback.</li>
+<li><tt class="docutils literal"><span class="pre">.str</span></tt> is the output of the command, if successful (a string);</li>
+<li><tt class="docutils literal"><span class="pre">.etype</span></tt> is the class of the exception, if the command fail;</li>
+<li><tt class="docutils literal"><span class="pre">.exc</span></tt> is the exception instance;</li>
+<li><tt class="docutils literal"><span class="pre">.tb</span></tt> is the traceback.</li>
 </ul>
-<p>Moreover the <tt class="docutils literal">__str__</tt> representation of the output object is redefined
+<p>Moreover the <tt class="docutils literal"><span class="pre">__str__</span></tt> representation of the output object is redefined
 to return the output string if the command was successful or the error
 message if the command failed (actually it returns the error message
 preceded by the name of the exception class).</p>
 <p>For instance, if you send a mispelled option to
-the interpreter a <tt class="docutils literal">SystemExit</tt> will be trapped:</p>
+the interpreter a <tt class="docutils literal"><span class="pre">SystemExit</span></tt> will be trapped:</p>
 <pre class="doctest-block">
 &gt;&gt;&gt; import plac
 &gt;&gt;&gt; from ishelve import ishelve
@@ -2479,8 +2481,8 @@ the interpreter a <tt class="docutils literal">SystemExit</tt> will be trapped:<
 ...
 SystemExit: unrecognized arguments: .cler
 </pre>
-<p>It is important to invoke the <tt class="docutils literal">.send</tt> method inside the context manager,
-otherwise you will get a <tt class="docutils literal">RuntimeError</tt>.</p>
+<p>It is important to invoke the <tt class="docutils literal"><span class="pre">.send</span></tt> method inside the context manager,
+otherwise you will get a <tt class="docutils literal"><span class="pre">RuntimeError</span></tt>.</p>
 <p>For instance, suppose you want to implement a graphical runner for a
 plac-based interpreter with two text widgets: one to enter the commands
 and one to display the results. Suppose you want to display the errors
@@ -2514,7 +2516,7 @@ paragraph <em>Managing the output of concurrent commands</em> (using Tkinter
 for simplicity and portability).</p>
 <p>There is a final <em>caveat</em>: since the plac interpreter loop is
 implemented via extended generators, plac interpreters are single threaded: you
-will get an error if you <tt class="docutils literal">.send</tt> commands from separated threads.
+will get an error if you <tt class="docutils literal"><span class="pre">.send</span></tt> commands from separated threads.
 You can circumvent the problem by using a queue. If EXIT is a sentinel
 value to signal exiting from the interpreter look, you can write code
 like this:</p>
@@ -2557,7 +2559,7 @@ if __name__ == '__main__':
     plac.Interpreter.call(FakeImporter)
 
 </pre>
-<p>If you run the <tt class="docutils literal">import_file</tt> command, you will have to wait for 200 seconds
+<p>If you run the <tt class="docutils literal"><span class="pre">import_file</span></tt> command, you will have to wait for 200 seconds
 before entering a new command:</p>
 <pre class="literal-block">
 $ python importer1.py dsn
@@ -2582,18 +2584,18 @@ and processes.</p>
 necessarily the best way) is to run it into a separated thread. In our
 example it is sufficient to replace the line</p>
 <blockquote>
-<tt class="docutils literal">commands = ['import_file']</tt></blockquote>
+<tt class="docutils literal"><span class="pre">commands</span> <span class="pre">=</span> <span class="pre">['import_file']</span></tt></blockquote>
 <p>with</p>
 <blockquote>
-<tt class="docutils literal">thcommands = ['import_file']</tt></blockquote>
-<p>to tell to the <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> interpreter that the command <tt class="docutils literal">import_file</tt> should be
+<tt class="docutils literal"><span class="pre">thcommands</span> <span class="pre">=</span> <span class="pre">['import_file']</span></tt></blockquote>
+<p>to tell to the <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> interpreter that the command <tt class="docutils literal"><span class="pre">import_file</span></tt> should be
 run into a separated thread. Here is an example session:</p>
 <pre class="literal-block">
 i&gt; import_file file1
 &lt;ThreadedTask 1 [import_file file1] RUNNING&gt;
 </pre>
 <p>The import task started in a separated thread. You can see the
-progress of the task by using the special command <tt class="docutils literal">.output</tt>:</p>
+progress of the task by using the special command <tt class="docutils literal"><span class="pre">.output</span></tt>:</p>
 <pre class="literal-block">
 i&gt; .output 1
 &lt;ThreadedTask 1 [import_file file1] RUNNING&gt;
@@ -2614,7 +2616,7 @@ Imported 400 lines
 i&gt; .output 1
 &lt;ThreadedTask 1 [import_file file1] FINISHED&gt;
 </pre>
-<p>You can even skip the number argument: then <tt class="docutils literal">.output</tt> will the return
+<p>You can even skip the number argument: then <tt class="docutils literal"><span class="pre">.output</span></tt> will the return
 the output of the last launched command (the special commands like .output
 do not count).</p>
 <p>You can launch many tasks one after the other:</p>
@@ -2624,7 +2626,7 @@ i&gt; import_file file2
 i&gt; import_file file3
 &lt;ThreadedTask 6 [import_file file3] RUNNING&gt;
 </pre>
-<p>The <tt class="docutils literal">.list</tt> command displays all the running tasks:</p>
+<p>The <tt class="docutils literal"><span class="pre">.list</span></tt> command displays all the running tasks:</p>
 <pre class="literal-block">
 i&gt; .list
 &lt;ThreadedTask 5 [import_file file2] RUNNING&gt;
@@ -2640,11 +2642,11 @@ i&gt; .output 5
 &lt;ThreadedTask 5 [import_file file2] KILLED&gt;
 </pre>
 <p>You should notice that since at the Python level it is impossible to kill
-a thread, the <tt class="docutils literal">.kill</tt> commands works by setting the status of the task to
-<tt class="docutils literal">TOBEKILLED</tt>. Internally the generator corresponding to the command
+a thread, the <tt class="docutils literal"><span class="pre">.kill</span></tt> commands works by setting the status of the task to
+<tt class="docutils literal"><span class="pre">TOBEKILLED</span></tt>. Internally the generator corresponding to the command
 is executed in the thread and the status is checked at each iteration:
-when the status become <tt class="docutils literal">TOBEKILLED</tt> a <tt class="docutils literal">GeneratorExit</tt> exception is
-raised and the thread terminates (softly, so that the <tt class="docutils literal">finally</tt> clause
+when the status become <tt class="docutils literal"><span class="pre">TOBEKILLED</span></tt> a <tt class="docutils literal"><span class="pre">GeneratorExit</span></tt> exception is
+raised and the thread terminates (softly, so that the <tt class="docutils literal"><span class="pre">finally</span></tt> clause
 is honored). In our example the generator is yielding
 back control once every 100 iterations, i.e. every two seconds (not much).
 In order to get a responsive interface it is a good idea to yield more
@@ -2686,10 +2688,10 @@ the current implementation only works in Unix-like operating systems
 module.</p>
 <p>In our example, to enable the feature it is sufficient to replace the line</p>
 <blockquote>
-<tt class="docutils literal">thcommands = ['import_file']</tt></blockquote>
+<tt class="docutils literal"><span class="pre">thcommands</span> <span class="pre">=</span> <span class="pre">['import_file']</span></tt></blockquote>
 <p>with</p>
 <blockquote>
-<tt class="docutils literal">mpcommands = ['import_file']</tt>.</blockquote>
+<tt class="docutils literal"><span class="pre">mpcommands</span> <span class="pre">=</span> <span class="pre">['import_file']</span></tt>.</blockquote>
 <p>The user experience is exactly the same as with threads and you will not see any
 difference at the user interface level:</p>
 <pre class="literal-block">
@@ -2711,9 +2713,9 @@ process, because traceback objects are not pickleable. Moreover,
 you cannot rely on automatic sharing of your objects.</p>
 <p>On the plus side, when using processes you do not need to worry about
 killing a command: they are killed immediately using a SIGTERM signal,
-and there is not a <tt class="docutils literal">TOBEKILLED</tt> mechanism. Moreover, the killing is
+and there is not a <tt class="docutils literal"><span class="pre">TOBEKILLED</span></tt> mechanism. Moreover, the killing is
 guaranteed to be soft: internally a command receiving a SIGTERM raises
-a <tt class="docutils literal">TerminatedProcess</tt> exception which is trapped in the generator
+a <tt class="docutils literal"><span class="pre">TerminatedProcess</span></tt> exception which is trapped in the generator
 loop, so that the command is closed properly.</p>
 <p>Using processes allows to take full advantage of multicore machines
 and it is safer than using threads, so it is the recommended approach
@@ -2723,16 +2725,16 @@ unless you are working on Windows.</p>
 <h2><a class="toc-backref" href="#id83">Managing the output of concurrent commands</a></h2>
 <p><a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> acts as a command-line task launcher and can be used as the base
 to build a GUI-based task launcher and task monitor. To this aim the
-interpreter class provides a <tt class="docutils literal">.submit</tt> method which returns a task
-object and a <tt class="docutils literal">.tasks</tt> method returning the list of all the tasks
-submitted to the interpreter.  The <tt class="docutils literal">submit</tt> method does not start the task
+interpreter class provides a <tt class="docutils literal"><span class="pre">.submit</span></tt> method which returns a task
+object and a <tt class="docutils literal"><span class="pre">.tasks</span></tt> method returning the list of all the tasks
+submitted to the interpreter.  The <tt class="docutils literal"><span class="pre">submit</span></tt> method does not start the task
 and thus it is nonblocking.
-Each task has an <tt class="docutils literal">.outlist</tt> attribute which is a list
+Each task has an <tt class="docutils literal"><span class="pre">.outlist</span></tt> attribute which is a list
 storing the value yielded by the generator underlying the task (the
-<tt class="docutils literal">None</tt> values are skipped though): the <tt class="docutils literal">.outlist</tt> grows as the
-task runs and more values are yielded. Accessing the <tt class="docutils literal">.outlist</tt> is
+<tt class="docutils literal"><span class="pre">None</span></tt> values are skipped though): the <tt class="docutils literal"><span class="pre">.outlist</span></tt> grows as the
+task runs and more values are yielded. Accessing the <tt class="docutils literal"><span class="pre">.outlist</span></tt> is
 nonblocking and can be done freely.
-Finally there is a <tt class="docutils literal">.result</tt>
+Finally there is a <tt class="docutils literal"><span class="pre">.result</span></tt>
 property which waits for the task to finish and returns the last yielded
 value or raises an exception.</p>
 <p>Here is some example code to visualize the output of the FakeImporter
@@ -2781,13 +2783,13 @@ World&quot; of parallel computing, i.e. the computation of pi with
 independent processes.  There is a huge number of algorithms to
 compute pi; here I will describe a trivial one chosen for simplicity,
 not per efficienty. The trick is to consider the first quadrant of a
-circle with radius 1 and to extract a number of points <tt class="docutils literal">(x, y)</tt> with
-<tt class="docutils literal">x</tt> and <tt class="docutils literal">y</tt> random variables in the interval <tt class="docutils literal">[0,1]</tt>. The
+circle with radius 1 and to extract a number of points <tt class="docutils literal"><span class="pre">(x,</span> <span class="pre">y)</span></tt> with
+<tt class="docutils literal"><span class="pre">x</span></tt> and <tt class="docutils literal"><span class="pre">y</span></tt> random variables in the interval <tt class="docutils literal"><span class="pre">[0,1]</span></tt>. The
 probability of extracting a number inside the quadrant (i.e. with
-<tt class="docutils literal">x^2 + y^2 &lt; 1</tt>) is proportional to the area of the quadrant
-(i.e. <tt class="docutils literal">pi/4</tt>). The value of <tt class="docutils literal">pi</tt> therefore can be extracted by
+<tt class="docutils literal"><span class="pre">x^2</span> <span class="pre">+</span> <span class="pre">y^2</span> <span class="pre">&lt;</span> <span class="pre">1</span></tt>) is proportional to the area of the quadrant
+(i.e. <tt class="docutils literal"><span class="pre">pi/4</span></tt>). The value of <tt class="docutils literal"><span class="pre">pi</span></tt> therefore can be extracted by
 multiplying by 4 the ratio between the number of points in the
-quadrant versus the total number of points <tt class="docutils literal">N</tt>, for <tt class="docutils literal">N</tt> large:</p>
+quadrant versus the total number of points <tt class="docutils literal"><span class="pre">N</span></tt>, for <tt class="docutils literal"><span class="pre">N</span></tt> large:</p>
 <pre class="literal-block">
 def calc_pi(N):
     inside = 0
@@ -2805,7 +2807,7 @@ expect a threaded computation to be even slower than a sequential
 computation, due to the GIL and the scheduling overhead.</p>
 <p>Here is a script implementing the algorithm and working in three different
 modes (parallel mode, threaded mode and sequential mode) depending on a
-<tt class="docutils literal">mode</tt> option:</p>
+<tt class="docutils literal"><span class="pre">mode</span></tt> option:</p>
 <pre class="literal-block">
 from __future__ import with_statement
 from random import random
@@ -2872,12 +2874,12 @@ if __name__ == '__main__':
         pc.close()
 
 </pre>
-<p>Notice the <tt class="docutils literal">submit_tasks</tt> method, which instantiates and initializes a
-<tt class="docutils literal">plac.Interpreter</tt> object and submits a number of commands corresponding
-to the number of available CPUs. The <tt class="docutils literal">calc_pi</tt> command yield a log
+<p>Notice the <tt class="docutils literal"><span class="pre">submit_tasks</span></tt> method, which instantiates and initializes a
+<tt class="docutils literal"><span class="pre">plac.Interpreter</span></tt> object and submits a number of commands corresponding
+to the number of available CPUs. The <tt class="docutils literal"><span class="pre">calc_pi</span></tt> command yield a log
 message every million of interactions, just to monitor the progress of
-the computation. The <tt class="docutils literal">run</tt> method starts all the submitted commands
-in parallel and sums the results. It returns the average value of <tt class="docutils literal">pi</tt>
+the computation. The <tt class="docutils literal"><span class="pre">run</span></tt> method starts all the submitted commands
+in parallel and sums the results. It returns the average value of <tt class="docutils literal"><span class="pre">pi</span></tt>
 after the slowest CPU has finished its job (if the CPUs are equal and
 equally busy they should finish more or less at the same time).</p>
 <p>Here are the results on my old Macbook with Ubuntu 10.04 and Python 2.6,
@@ -2892,6 +2894,16 @@ $ python picalculator.py -mS 10000000
 </pre>
 <p>As you see using processes one gets a 2x speedup indeed, where the threaded
 mode is some 20% slower than the sequential mode.</p>
+<p>Since the pattern submit a bunch of tasks, starts them and collect the
+results is so common, <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> provides an utility function
+<tt class="docutils literal"><span class="pre">runp(genseq,</span> <span class="pre">mode='p',</span> <span class="pre">start=True)</span></tt> to start
+a bunch a generators and return a list of task objects. By default
+<tt class="docutils literal"><span class="pre">runp</span></tt> use processes, but you can use threads by passing <tt class="docutils literal"><span class="pre">t</span></tt> as
+mode. If you do not wont to start the tasks, you can say so (<tt class="docutils literal"><span class="pre">start=False</span></tt>).
+With <tt class="docutils literal"><span class="pre">runp</span></tt> the picalculator becomes a one-liner:</p>
+<pre class="literal-block">
+sum(task.result for task in plac.runp(calc_pi(N) for i in range(ncpus)))/ncpus
+</pre>
 </div>
 <div class="section" id="the-plac-server">
 <h2><a class="toc-backref" href="#id85">The plac server</a></h2>
@@ -2901,10 +2913,10 @@ a builtin server which is able to accept commands from multiple
 clients and to execute them. The server works by instantiating
 a separate interpreter for each client, so that if a client interpreter
 dies for any reason the other interpreters keep working.
-To avoid external dependencies the server is based on the <tt class="docutils literal">asynchat</tt>
+To avoid external dependencies the server is based on the <tt class="docutils literal"><span class="pre">asynchat</span></tt>
 module in the standard library, but it would not be difficult to
 replace the server with a different one (for instance, a Twisted server).
-Since <tt class="docutils literal">asynchat</tt>-based servers are asynchronous, any blocking command
+Since <tt class="docutils literal"><span class="pre">asynchat</span></tt>-based servers are asynchronous, any blocking command
 in the interpreter should be run in a separated process or thread.
 The default port for the <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> server is 2199, and the command to
 signal end-of-connection is EOF.
@@ -2922,7 +2934,7 @@ if __name__ == '__main__':
    plac.call(main)
 
 </pre>
-<p>You can connect to the server with <tt class="docutils literal">telnet</tt> on port 2199, as follows:</p>
+<p>You can connect to the server with <tt class="docutils literal"><span class="pre">telnet</span></tt> on port 2199, as follows:</p>
 <pre class="literal-block">
 $ telnet localhost 2199
 Trying ::1...
@@ -2946,30 +2958,30 @@ in the world. Having read this document you may think that it is not
 so easy after all. But it is a false impression. Actually the
 rules are quite simple:</p>
 <ol class="arabic simple">
-<li>if you want to implement a command-line script, use <tt class="docutils literal">plac.call</tt>;</li>
-<li>if you want to implement a command interpreter, use <tt class="docutils literal">plac.Interpreter</tt>:<ul>
-<li>for an interactive interpreter, call the <tt class="docutils literal">.interact</tt> method;</li>
-<li>for an batch interpreter, call the <tt class="docutils literal">.execute</tt> method;</li>
+<li>if you want to implement a command-line script, use <tt class="docutils literal"><span class="pre">plac.call</span></tt>;</li>
+<li>if you want to implement a command interpreter, use <tt class="docutils literal"><span class="pre">plac.Interpreter</span></tt>:<ul>
+<li>for an interactive interpreter, call the <tt class="docutils literal"><span class="pre">.interact</span></tt> method;</li>
+<li>for an batch interpreter, call the <tt class="docutils literal"><span class="pre">.execute</span></tt> method;</li>
 </ul>
 </li>
-<li>for testing call the <tt class="docutils literal">Interpreter.check</tt> method in the appropriate context
-or use the <tt class="docutils literal">Interpreter.doctest</tt> feature;</li>
+<li>for testing call the <tt class="docutils literal"><span class="pre">Interpreter.check</span></tt> method in the appropriate context
+or use the <tt class="docutils literal"><span class="pre">Interpreter.doctest</span></tt> feature;</li>
 <li>if you need to go at a lower level, you may need to call the
-<tt class="docutils literal">Interpreter.send</tt> method which returns a (finished) <tt class="docutils literal">Task</tt> object.</li>
+<tt class="docutils literal"><span class="pre">Interpreter.send</span></tt> method which returns a (finished) <tt class="docutils literal"><span class="pre">Task</span></tt> object.</li>
 <li>long running command can be executed in the background as threads or
-processes: just declare them in the lists <tt class="docutils literal">thcommands</tt> and <tt class="docutils literal">mpcommands</tt>
+processes: just declare them in the lists <tt class="docutils literal"><span class="pre">thcommands</span></tt> and <tt class="docutils literal"><span class="pre">mpcommands</span></tt>
 respectively.</li>
-<li>the <tt class="docutils literal">.start_server</tt> method starts an asynchronous server on the
+<li>the <tt class="docutils literal"><span class="pre">.start_server</span></tt> method starts an asynchronous server on the
 given port number (default 2199)</li>
 </ol>
-<p>Moreover, remember that <tt class="docutils literal">plac_runner.py</tt> is your friend.</p>
+<p>Moreover, remember that <tt class="docutils literal"><span class="pre">plac_runner.py</span></tt> is your friend.</p>
 </div>
 <hr class="docutils" />
 <div class="section" id="appendix-custom-annotation-objects">
 <h2><a class="toc-backref" href="#id87">Appendix: custom annotation objects</a></h2>
-<p>Internally <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> uses an <tt class="docutils literal">Annotation</tt> class to convert the tuples
+<p>Internally <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> uses an <tt class="docutils literal"><span class="pre">Annotation</span></tt> class to convert the tuples
 in the function signature into annotation objects, i.e. objects with
-six attributes <tt class="docutils literal">help, kind, short, type, choices, metavar</tt>.</p>
+six attributes <tt class="docutils literal"><span class="pre">help,</span> <span class="pre">kind,</span> <span class="pre">short,</span> <span class="pre">type,</span> <span class="pre">choices,</span> <span class="pre">metavar</span></tt>.</p>
 <p>Advanced users can implement their own annotation objects.
 For instance, here is an example of how you could implement annotations for
 positional arguments:</p>
@@ -3015,7 +3027,7 @@ optional arguments:
   -h, --help  show this help message and exit
 
 </pre>
-<p>You can go on and define <tt class="docutils literal">Option</tt> and <tt class="docutils literal">Flag</tt> classes, if you like.
+<p>You can go on and define <tt class="docutils literal"><span class="pre">Option</span></tt> and <tt class="docutils literal"><span class="pre">Flag</span></tt> classes, if you like.
 Using custom annotation objects you could do advanced things like extracting the
 annotations from a configuration file or from a database, but I expect such
 use cases to be quite rare: the default mechanism should work
diff --git a/plac/doc/plac.pdf b/plac/doc/plac.pdf
index 0a6f91d..c25ccec 100644
--- a/plac/doc/plac.pdf
+++ b/plac/doc/plac.pdf
@@ -5,9 +5,8 @@
 % The standard fonts dictionary
 << /F1 2 0 R
  /F2 3 0 R
- /F3 4 0 R
- /F4 8 0 R
- /F5 95 0 R >>
+ /F3 7 0 R
+ /F4 94 0 R >>
 endobj
 % 'F1': class PDFType1Font 
 2 0 obj
@@ -27,17 +26,8 @@ endobj
  /Subtype /Type1
  /Type /Font >>
 endobj
-% 'F3': class PDFType1Font 
-4 0 obj
-% Font Times-Roman
-<< /BaseFont /Times-Roman
- /Encoding /WinAnsiEncoding
- /Name /F3
- /Subtype /Type1
- /Type /Font >>
-endobj
 % 'Annot.NUMBER1': class PDFDictionary 
-5 0 obj
+4 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (mailto:michele.simionato@gmail.com) >>
@@ -52,7 +42,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER2': class PDFDictionary 
-6 0 obj
+5 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -67,7 +57,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER3': class PDFDictionary 
-7 0 obj
+6 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://micheles.googlecode.com/hg/plac/doc/plac.html) >>
@@ -81,21 +71,21 @@ endobj
  /Subtype /Link
  /Type /Annot >>
 endobj
-% 'F4': class PDFType1Font 
-8 0 obj
+% 'F3': class PDFType1Font 
+7 0 obj
 % Font Courier
 << /BaseFont /Courier
  /Encoding /WinAnsiEncoding
- /Name /F4
+ /Name /F3
  /Subtype /Type1
  /Type /Font >>
 endobj
 % 'Page1': class PDFPage 
-9 0 obj
+8 0 obj
 % Page dictionary
-<< /Annots [ 5 0 R
- 6 0 R
- 7 0 R ]
+<< /Annots [ 4 0 R
+ 5 0 R
+ 6 0 R ]
  /Contents 412 0 R
  /MediaBox [ 0
  0
@@ -113,12 +103,12 @@ endobj
  /Type /Page >>
 endobj
 % 'Annot.NUMBER4': class LinkAnnotation 
-10 0 obj
+9 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 9 0 R
+ /Dest [ 8 0 R
  /XYZ
  62.69291
  765.0236
@@ -131,12 +121,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER5': class LinkAnnotation 
-11 0 obj
+10 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 9 0 R
+ /Dest [ 8 0 R
  /XYZ
  62.69291
  765.0236
@@ -149,12 +139,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER6': class LinkAnnotation 
-12 0 obj
+11 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 96 0 R
+ /Dest [ 95 0 R
  /XYZ
  62.69291
  765.0236
@@ -167,12 +157,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER7': class LinkAnnotation 
-13 0 obj
+12 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 96 0 R
+ /Dest [ 95 0 R
  /XYZ
  62.69291
  765.0236
@@ -185,12 +175,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER8': class LinkAnnotation 
-14 0 obj
+13 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 96 0 R
+ /Dest [ 95 0 R
  /XYZ
  62.69291
  411.0236
@@ -203,12 +193,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER9': class LinkAnnotation 
-15 0 obj
+14 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 96 0 R
+ /Dest [ 95 0 R
  /XYZ
  62.69291
  411.0236
@@ -221,12 +211,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER10': class LinkAnnotation 
-16 0 obj
+15 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 110 0 R
+ /Dest [ 109 0 R
  /XYZ
  62.69291
  765.0236
@@ -239,12 +229,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER11': class LinkAnnotation 
-17 0 obj
+16 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 110 0 R
+ /Dest [ 109 0 R
  /XYZ
  62.69291
  765.0236
@@ -257,12 +247,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER12': class LinkAnnotation 
-18 0 obj
+17 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 120 0 R
+ /Dest [ 119 0 R
  /XYZ
  62.69291
  741.0236
@@ -275,12 +265,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER13': class LinkAnnotation 
-19 0 obj
+18 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 120 0 R
+ /Dest [ 119 0 R
  /XYZ
  62.69291
  741.0236
@@ -293,12 +283,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER14': class LinkAnnotation 
-20 0 obj
+19 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 124 0 R
+ /Dest [ 123 0 R
  /XYZ
  62.69291
  765.0236
@@ -311,12 +301,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER15': class LinkAnnotation 
-21 0 obj
+20 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 124 0 R
+ /Dest [ 123 0 R
  /XYZ
  62.69291
  765.0236
@@ -329,12 +319,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER16': class LinkAnnotation 
-22 0 obj
+21 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 124 0 R
+ /Dest [ 123 0 R
  /XYZ
  62.69291
  265.7299
@@ -347,12 +337,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER17': class LinkAnnotation 
-23 0 obj
+22 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 124 0 R
+ /Dest [ 123 0 R
  /XYZ
  62.69291
  265.7299
@@ -365,12 +355,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER18': class LinkAnnotation 
-24 0 obj
+23 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 132 0 R
+ /Dest [ 131 0 R
  /XYZ
  62.69291
  522.6236
@@ -383,12 +373,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER19': class LinkAnnotation 
-25 0 obj
+24 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 132 0 R
+ /Dest [ 131 0 R
  /XYZ
  62.69291
  522.6236
@@ -401,12 +391,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER20': class LinkAnnotation 
-26 0 obj
+25 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 137 0 R
+ /Dest [ 136 0 R
  /XYZ
  62.69291
  552.6236
@@ -419,12 +409,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER21': class LinkAnnotation 
-27 0 obj
+26 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 137 0 R
+ /Dest [ 136 0 R
  /XYZ
  62.69291
  552.6236
@@ -437,12 +427,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER22': class LinkAnnotation 
-28 0 obj
+27 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 140 0 R
+ /Dest [ 139 0 R
  /XYZ
  62.69291
  513.8236
@@ -455,12 +445,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER23': class LinkAnnotation 
-29 0 obj
+28 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 140 0 R
+ /Dest [ 139 0 R
  /XYZ
  62.69291
  513.8236
@@ -473,12 +463,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER24': class LinkAnnotation 
-30 0 obj
+29 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 142 0 R
+ /Dest [ 141 0 R
  /XYZ
  62.69291
  493.4236
@@ -491,12 +481,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER25': class LinkAnnotation 
-31 0 obj
+30 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 142 0 R
+ /Dest [ 141 0 R
  /XYZ
  62.69291
  493.4236
@@ -509,12 +499,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER26': class LinkAnnotation 
-32 0 obj
+31 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 159 0 R
+ /Dest [ 158 0 R
  /XYZ
  62.69291
  422.6236
@@ -527,12 +517,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER27': class LinkAnnotation 
-33 0 obj
+32 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 159 0 R
+ /Dest [ 158 0 R
  /XYZ
  62.69291
  422.6236
@@ -545,12 +535,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER28': class LinkAnnotation 
-34 0 obj
+33 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 208 0 R
+ /Dest [ 207 0 R
  /XYZ
  62.69291
  741.0236
@@ -563,12 +553,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER29': class LinkAnnotation 
-35 0 obj
+34 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 208 0 R
+ /Dest [ 207 0 R
  /XYZ
  62.69291
  741.0236
@@ -581,12 +571,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER30': class LinkAnnotation 
-36 0 obj
+35 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 208 0 R
+ /Dest [ 207 0 R
  /XYZ
  62.69291
  513.0236
@@ -599,12 +589,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER31': class LinkAnnotation 
-37 0 obj
+36 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 208 0 R
+ /Dest [ 207 0 R
  /XYZ
  62.69291
  513.0236
@@ -617,12 +607,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER32': class LinkAnnotation 
-38 0 obj
+37 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 208 0 R
+ /Dest [ 207 0 R
  /XYZ
  62.69291
  309.0236
@@ -635,12 +625,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER33': class LinkAnnotation 
-39 0 obj
+38 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 208 0 R
+ /Dest [ 207 0 R
  /XYZ
  62.69291
  309.0236
@@ -653,12 +643,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER34': class LinkAnnotation 
-40 0 obj
+39 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 214 0 R
+ /Dest [ 213 0 R
  /XYZ
  62.69291
  681.0236
@@ -671,12 +661,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER35': class LinkAnnotation 
-41 0 obj
+40 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 214 0 R
+ /Dest [ 213 0 R
  /XYZ
  62.69291
  681.0236
@@ -689,12 +679,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER36': class LinkAnnotation 
-42 0 obj
+41 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 297 0 R
+ /Dest [ 296 0 R
  /XYZ
  62.69291
  765.0236
@@ -707,12 +697,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER37': class LinkAnnotation 
-43 0 obj
+42 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 297 0 R
+ /Dest [ 296 0 R
  /XYZ
  62.69291
  765.0236
@@ -725,12 +715,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER38': class LinkAnnotation 
-44 0 obj
+43 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 297 0 R
+ /Dest [ 296 0 R
  /XYZ
  62.69291
  543.0236
@@ -743,12 +733,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER39': class LinkAnnotation 
-45 0 obj
+44 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 297 0 R
+ /Dest [ 296 0 R
  /XYZ
  62.69291
  543.0236
@@ -761,12 +751,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER40': class LinkAnnotation 
-46 0 obj
+45 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 300 0 R
+ /Dest [ 299 0 R
  /XYZ
  62.69291
  765.0236
@@ -779,12 +769,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER41': class LinkAnnotation 
-47 0 obj
+46 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 300 0 R
+ /Dest [ 299 0 R
  /XYZ
  62.69291
  765.0236
@@ -797,12 +787,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER42': class LinkAnnotation 
-48 0 obj
+47 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 309 0 R
+ /Dest [ 308 0 R
  /XYZ
  62.69291
  741.0236
@@ -815,12 +805,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER43': class LinkAnnotation 
-49 0 obj
+48 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 309 0 R
+ /Dest [ 308 0 R
  /XYZ
  62.69291
  741.0236
@@ -833,12 +823,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER44': class LinkAnnotation 
-50 0 obj
+49 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 314 0 R
+ /Dest [ 313 0 R
  /XYZ
  62.69291
  431.8485
@@ -851,12 +841,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER45': class LinkAnnotation 
-51 0 obj
+50 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 314 0 R
+ /Dest [ 313 0 R
  /XYZ
  62.69291
  431.8485
@@ -869,12 +859,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER46': class LinkAnnotation 
-52 0 obj
+51 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 319 0 R
+ /Dest [ 318 0 R
  /XYZ
  62.69291
  515.8236
@@ -887,12 +877,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER47': class LinkAnnotation 
-53 0 obj
+52 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 319 0 R
+ /Dest [ 318 0 R
  /XYZ
  62.69291
  515.8236
@@ -905,12 +895,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER48': class LinkAnnotation 
-54 0 obj
+53 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 324 0 R
+ /Dest [ 323 0 R
  /XYZ
  62.69291
  441.5042
@@ -923,12 +913,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER49': class LinkAnnotation 
-55 0 obj
+54 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 324 0 R
+ /Dest [ 323 0 R
  /XYZ
  62.69291
  441.5042
@@ -941,12 +931,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER50': class LinkAnnotation 
-56 0 obj
+55 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 332 0 R
+ /Dest [ 331 0 R
  /XYZ
  62.69291
  765.0236
@@ -959,12 +949,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER51': class LinkAnnotation 
-57 0 obj
+56 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 332 0 R
+ /Dest [ 331 0 R
  /XYZ
  62.69291
  765.0236
@@ -977,12 +967,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER52': class LinkAnnotation 
-58 0 obj
+57 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 343 0 R
+ /Dest [ 342 0 R
  /XYZ
  62.69291
  258.6236
@@ -995,12 +985,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER53': class LinkAnnotation 
-59 0 obj
+58 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 343 0 R
+ /Dest [ 342 0 R
  /XYZ
  62.69291
  258.6236
@@ -1013,12 +1003,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER54': class LinkAnnotation 
-60 0 obj
+59 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 347 0 R
+ /Dest [ 346 0 R
  /XYZ
  62.69291
  401.4236
@@ -1031,12 +1021,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER55': class LinkAnnotation 
-61 0 obj
+60 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 347 0 R
+ /Dest [ 346 0 R
  /XYZ
  62.69291
  401.4236
@@ -1049,12 +1039,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER56': class LinkAnnotation 
-62 0 obj
+61 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 350 0 R
+ /Dest [ 349 0 R
  /XYZ
  62.69291
  408.6236
@@ -1067,12 +1057,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER57': class LinkAnnotation 
-63 0 obj
+62 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 350 0 R
+ /Dest [ 349 0 R
  /XYZ
  62.69291
  408.6236
@@ -1085,12 +1075,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER58': class LinkAnnotation 
-64 0 obj
+63 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 354 0 R
+ /Dest [ 353 0 R
  /XYZ
  62.69291
  244.6236
@@ -1103,12 +1093,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER59': class LinkAnnotation 
-65 0 obj
+64 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 354 0 R
+ /Dest [ 353 0 R
  /XYZ
  62.69291
  244.6236
@@ -1121,12 +1111,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER60': class LinkAnnotation 
-66 0 obj
+65 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 357 0 R
+ /Dest [ 356 0 R
  /XYZ
  62.69291
  354.6236
@@ -1139,12 +1129,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER61': class LinkAnnotation 
-67 0 obj
+66 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 357 0 R
+ /Dest [ 356 0 R
  /XYZ
  62.69291
  354.6236
@@ -1157,12 +1147,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER62': class LinkAnnotation 
-68 0 obj
+67 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 361 0 R
+ /Dest [ 360 0 R
  /XYZ
  62.69291
  511.8236
@@ -1175,12 +1165,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER63': class LinkAnnotation 
-69 0 obj
+68 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 361 0 R
+ /Dest [ 360 0 R
  /XYZ
  62.69291
  511.8236
@@ -1193,12 +1183,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER64': class LinkAnnotation 
-70 0 obj
+69 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 363 0 R
+ /Dest [ 362 0 R
  /XYZ
  62.69291
  711.0236
@@ -1211,12 +1201,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER65': class LinkAnnotation 
-71 0 obj
+70 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 363 0 R
+ /Dest [ 362 0 R
  /XYZ
  62.69291
  711.0236
@@ -1229,12 +1219,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER66': class LinkAnnotation 
-72 0 obj
+71 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 365 0 R
+ /Dest [ 364 0 R
  /XYZ
  62.69291
  765.0236
@@ -1247,12 +1237,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER67': class LinkAnnotation 
-73 0 obj
+72 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 365 0 R
+ /Dest [ 364 0 R
  /XYZ
  62.69291
  765.0236
@@ -1265,7 +1255,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER68': class LinkAnnotation 
-74 0 obj
+73 0 obj
 << /Border [ 0
  0
  0 ]
@@ -1273,7 +1263,7 @@ endobj
  /Dest [ 369 0 R
  /XYZ
  62.69291
- 729.0236
+ 630.4159
  0 ]
  /Rect [ 82.69291
  150.5936
@@ -1283,7 +1273,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER69': class LinkAnnotation 
-75 0 obj
+74 0 obj
 << /Border [ 0
  0
  0 ]
@@ -1291,7 +1281,7 @@ endobj
  /Dest [ 369 0 R
  /XYZ
  62.69291
- 729.0236
+ 630.4159
  0 ]
  /Rect [ 521.4627
  150.5936
@@ -1301,7 +1291,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER70': class LinkAnnotation 
-76 0 obj
+75 0 obj
 << /Border [ 0
  0
  0 ]
@@ -1309,7 +1299,7 @@ endobj
  /Dest [ 369 0 R
  /XYZ
  62.69291
- 258.6236
+ 160.0159
  0 ]
  /Rect [ 82.69291
  132.5936
@@ -1319,7 +1309,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER71': class LinkAnnotation 
-77 0 obj
+76 0 obj
 << /Border [ 0
  0
  0 ]
@@ -1327,7 +1317,7 @@ endobj
  /Dest [ 369 0 R
  /XYZ
  62.69291
- 258.6236
+ 160.0159
  0 ]
  /Rect [ 521.4627
  132.5936
@@ -1337,7 +1327,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER72': class LinkAnnotation 
-78 0 obj
+77 0 obj
 << /Border [ 0
  0
  0 ]
@@ -1345,7 +1335,7 @@ endobj
  /Dest [ 371 0 R
  /XYZ
  62.69291
- 586.6772
+ 508.6772
  0 ]
  /Rect [ 82.69291
  114.5936
@@ -1355,7 +1345,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER73': class LinkAnnotation 
-79 0 obj
+78 0 obj
 << /Border [ 0
  0
  0 ]
@@ -1363,7 +1353,7 @@ endobj
  /Dest [ 371 0 R
  /XYZ
  62.69291
- 586.6772
+ 508.6772
  0 ]
  /Rect [ 521.4627
  114.5936
@@ -1373,9 +1363,10 @@ endobj
  /Type /Annot >>
 endobj
 % 'Page2': class PDFPage 
-80 0 obj
+79 0 obj
 % Page dictionary
-<< /Annots [ 10 0 R
+<< /Annots [ 9 0 R
+ 10 0 R
  11 0 R
  12 0 R
  13 0 R
@@ -1443,8 +1434,7 @@ endobj
  75 0 R
  76 0 R
  77 0 R
- 78 0 R
- 79 0 R ]
+ 78 0 R ]
  /Contents 413 0 R
  /MediaBox [ 0
  0
@@ -1462,7 +1452,7 @@ endobj
  /Type /Page >>
 endobj
 % 'Annot.NUMBER74': class PDFDictionary 
-81 0 obj
+80 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://docs.python.org/library/getopt.html) >>
@@ -1477,7 +1467,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER75': class PDFDictionary 
-82 0 obj
+81 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://docs.python.org/library/optparse.html) >>
@@ -1492,7 +1482,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER76': class PDFDictionary 
-83 0 obj
+82 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://argparse.googlecode.com) >>
@@ -1507,7 +1497,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER77': class PDFDictionary 
-84 0 obj
+83 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://argparse.googlecode.com) >>
@@ -1522,7 +1512,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER78': class PDFDictionary 
-85 0 obj
+84 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://www.welton.it/articles/scalable_systems) >>
@@ -1537,7 +1527,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER79': class PDFDictionary 
-86 0 obj
+85 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -1552,7 +1542,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER80': class PDFDictionary 
-87 0 obj
+86 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://argparse.googlecode.com) >>
@@ -1567,7 +1557,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER81': class PDFDictionary 
-88 0 obj
+87 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -1582,7 +1572,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER82': class PDFDictionary 
-89 0 obj
+88 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://argparse.googlecode.com) >>
@@ -1597,7 +1587,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER83': class PDFDictionary 
-90 0 obj
+89 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -1612,7 +1602,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER84': class PDFDictionary 
-91 0 obj
+90 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://argparse.googlecode.com) >>
@@ -1627,7 +1617,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER85': class PDFDictionary 
-92 0 obj
+91 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -1642,7 +1632,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER86': class PDFDictionary 
-93 0 obj
+92 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -1657,7 +1647,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER87': class PDFDictionary 
-94 0 obj
+93 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -1671,19 +1661,20 @@ endobj
  /Subtype /Link
  /Type /Annot >>
 endobj
-% 'F5': class PDFType1Font 
-95 0 obj
+% 'F4': class PDFType1Font 
+94 0 obj
 % Font Helvetica-Oblique
 << /BaseFont /Helvetica-Oblique
  /Encoding /WinAnsiEncoding
- /Name /F5
+ /Name /F4
  /Subtype /Type1
  /Type /Font >>
 endobj
 % 'Page3': class PDFPage 
-96 0 obj
+95 0 obj
 % Page dictionary
-<< /Annots [ 81 0 R
+<< /Annots [ 80 0 R
+ 81 0 R
  82 0 R
  83 0 R
  84 0 R
@@ -1695,8 +1686,7 @@ endobj
  90 0 R
  91 0 R
  92 0 R
- 93 0 R
- 94 0 R ]
+ 93 0 R ]
  /Contents 414 0 R
  /MediaBox [ 0
  0
@@ -1714,7 +1704,7 @@ endobj
  /Type /Page >>
 endobj
 % 'Annot.NUMBER88': class PDFDictionary 
-97 0 obj
+96 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://docs.python.org/library/getopt.html) >>
@@ -1729,7 +1719,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER89': class PDFDictionary 
-98 0 obj
+97 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://docs.python.org/library/optparse.html) >>
@@ -1744,7 +1734,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER90': class PDFDictionary 
-99 0 obj
+98 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://argparse.googlecode.com) >>
@@ -1759,7 +1749,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER91': class PDFDictionary 
-100 0 obj
+99 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -1774,7 +1764,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER92': class PDFDictionary 
-101 0 obj
+100 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -1789,7 +1779,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER93': class PDFDictionary 
-102 0 obj
+101 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -1804,7 +1794,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER94': class PDFDictionary 
-103 0 obj
+102 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://argparse.googlecode.com) >>
@@ -1819,7 +1809,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER95': class PDFDictionary 
-104 0 obj
+103 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -1834,7 +1824,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER96': class PDFDictionary 
-105 0 obj
+104 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -1849,17 +1839,17 @@ endobj
  /Type /Annot >>
 endobj
 % 'Page4': class PDFPage 
-106 0 obj
+105 0 obj
 % Page dictionary
-<< /Annots [ 97 0 R
+<< /Annots [ 96 0 R
+ 97 0 R
  98 0 R
  99 0 R
  100 0 R
  101 0 R
  102 0 R
  103 0 R
- 104 0 R
- 105 0 R ]
+ 104 0 R ]
  /Contents 415 0 R
  /MediaBox [ 0
  0
@@ -1877,7 +1867,7 @@ endobj
  /Type /Page >>
 endobj
 % 'Annot.NUMBER97': class PDFDictionary 
-107 0 obj
+106 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://argparse.googlecode.com) >>
@@ -1892,7 +1882,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER98': class PDFDictionary 
-108 0 obj
+107 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -1907,7 +1897,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER99': class PDFDictionary 
-109 0 obj
+108 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -1922,11 +1912,11 @@ endobj
  /Type /Annot >>
 endobj
 % 'Page5': class PDFPage 
-110 0 obj
+109 0 obj
 % Page dictionary
-<< /Annots [ 107 0 R
- 108 0 R
- 109 0 R ]
+<< /Annots [ 106 0 R
+ 107 0 R
+ 108 0 R ]
  /Contents 416 0 R
  /MediaBox [ 0
  0
@@ -1944,7 +1934,7 @@ endobj
  /Type /Page >>
 endobj
 % 'Annot.NUMBER100': class PDFDictionary 
-111 0 obj
+110 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -1959,7 +1949,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER101': class PDFDictionary 
-112 0 obj
+111 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -1974,7 +1964,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER102': class PDFDictionary 
-113 0 obj
+112 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://code.activestate.com/recipes/278844-parsing-the-command-line/) >>
@@ -1989,11 +1979,11 @@ endobj
  /Type /Annot >>
 endobj
 % 'Page6': class PDFPage 
-114 0 obj
+113 0 obj
 % Page dictionary
-<< /Annots [ 111 0 R
- 112 0 R
- 113 0 R ]
+<< /Annots [ 110 0 R
+ 111 0 R
+ 112 0 R ]
  /Contents 417 0 R
  /MediaBox [ 0
  0
@@ -2011,7 +2001,7 @@ endobj
  /Type /Page >>
 endobj
 % 'Annot.NUMBER103': class PDFDictionary 
-115 0 obj
+114 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -2026,7 +2016,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER104': class PDFDictionary 
-116 0 obj
+115 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://code.activestate.com/recipes/278844-parsing-the-command-line/) >>
@@ -2041,7 +2031,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER105': class PDFDictionary 
-117 0 obj
+116 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://code.activestate.com/recipes/278844-parsing-the-command-line/) >>
@@ -2056,7 +2046,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER106': class PDFDictionary 
-118 0 obj
+117 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -2071,7 +2061,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER107': class PDFDictionary 
-119 0 obj
+118 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -2086,13 +2076,13 @@ endobj
  /Type /Annot >>
 endobj
 % 'Page7': class PDFPage 
-120 0 obj
+119 0 obj
 % Page dictionary
-<< /Annots [ 115 0 R
+<< /Annots [ 114 0 R
+ 115 0 R
  116 0 R
  117 0 R
- 118 0 R
- 119 0 R ]
+ 118 0 R ]
  /Contents 418 0 R
  /MediaBox [ 0
  0
@@ -2110,7 +2100,7 @@ endobj
  /Type /Page >>
 endobj
 % 'Page8': class PDFPage 
-121 0 obj
+120 0 obj
 % Page dictionary
 << /Contents 419 0 R
  /MediaBox [ 0
@@ -2129,7 +2119,7 @@ endobj
  /Type /Page >>
 endobj
 % 'Annot.NUMBER108': class PDFDictionary 
-122 0 obj
+121 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -2144,7 +2134,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER109': class PDFDictionary 
-123 0 obj
+122 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -2159,10 +2149,10 @@ endobj
  /Type /Annot >>
 endobj
 % 'Page9': class PDFPage 
-124 0 obj
+123 0 obj
 % Page dictionary
-<< /Annots [ 122 0 R
- 123 0 R ]
+<< /Annots [ 121 0 R
+ 122 0 R ]
  /Contents 420 0 R
  /MediaBox [ 0
  0
@@ -2180,7 +2170,7 @@ endobj
  /Type /Page >>
 endobj
 % 'Annot.NUMBER110': class PDFDictionary 
-125 0 obj
+124 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -2195,7 +2185,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER111': class PDFDictionary 
-126 0 obj
+125 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -2210,7 +2200,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER112': class PDFDictionary 
-127 0 obj
+126 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://argparse.googlecode.com) >>
@@ -2225,7 +2215,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER113': class PDFDictionary 
-128 0 obj
+127 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://argparse.googlecode.com) >>
@@ -2240,7 +2230,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER114': class PDFDictionary 
-129 0 obj
+128 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://argparse.googlecode.com) >>
@@ -2255,7 +2245,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER115': class PDFDictionary 
-130 0 obj
+129 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -2270,7 +2260,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER116': class PDFDictionary 
-131 0 obj
+130 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://argparse.googlecode.com) >>
@@ -2278,22 +2268,22 @@ endobj
  0
  0 ]
  /Rect [ 360.0429
- 274.1936
+ 238.1936
  402.2829
- 286.1936 ]
+ 250.1936 ]
  /Subtype /Link
  /Type /Annot >>
 endobj
 % 'Page10': class PDFPage 
-132 0 obj
+131 0 obj
 % Page dictionary
-<< /Annots [ 125 0 R
+<< /Annots [ 124 0 R
+ 125 0 R
  126 0 R
  127 0 R
  128 0 R
  129 0 R
- 130 0 R
- 131 0 R ]
+ 130 0 R ]
  /Contents 421 0 R
  /MediaBox [ 0
  0
@@ -2311,7 +2301,7 @@ endobj
  /Type /Page >>
 endobj
 % 'Page11': class PDFPage 
-133 0 obj
+132 0 obj
 % Page dictionary
 << /Contents 422 0 R
  /MediaBox [ 0
@@ -2330,7 +2320,7 @@ endobj
  /Type /Page >>
 endobj
 % 'Annot.NUMBER117': class PDFDictionary 
-134 0 obj
+133 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -2345,7 +2335,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER118': class PDFDictionary 
-135 0 obj
+134 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://www.sqlalchemy.org/) >>
@@ -2360,7 +2350,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER119': class PDFDictionary 
-136 0 obj
+135 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://www.sqlalchemy.org/docs/reference/ext/sqlsoup.html) >>
@@ -2375,11 +2365,11 @@ endobj
  /Type /Annot >>
 endobj
 % 'Page12': class PDFPage 
-137 0 obj
+136 0 obj
 % Page dictionary
-<< /Annots [ 134 0 R
- 135 0 R
- 136 0 R ]
+<< /Annots [ 133 0 R
+ 134 0 R
+ 135 0 R ]
  /Contents 423 0 R
  /MediaBox [ 0
  0
@@ -2397,7 +2387,7 @@ endobj
  /Type /Page >>
 endobj
 % 'Annot.NUMBER120': class PDFDictionary 
-138 0 obj
+137 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -2412,7 +2402,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER121': class PDFDictionary 
-139 0 obj
+138 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -2427,10 +2417,10 @@ endobj
  /Type /Annot >>
 endobj
 % 'Page13': class PDFPage 
-140 0 obj
+139 0 obj
 % Page dictionary
-<< /Annots [ 138 0 R
- 139 0 R ]
+<< /Annots [ 137 0 R
+ 138 0 R ]
  /Contents 424 0 R
  /MediaBox [ 0
  0
@@ -2448,7 +2438,7 @@ endobj
  /Type /Page >>
 endobj
 % 'Annot.NUMBER122': class PDFDictionary 
-141 0 obj
+140 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -2463,9 +2453,9 @@ endobj
  /Type /Annot >>
 endobj
 % 'Page14': class PDFPage 
-142 0 obj
+141 0 obj
 % Page dictionary
-<< /Annots [ 141 0 R ]
+<< /Annots [ 140 0 R ]
  /Contents 425 0 R
  /MediaBox [ 0
  0
@@ -2483,7 +2473,7 @@ endobj
  /Type /Page >>
 endobj
 % 'Annot.NUMBER123': class PDFDictionary 
-143 0 obj
+142 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://argparse.googlecode.com) >>
@@ -2498,7 +2488,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER124': class PDFDictionary 
-144 0 obj
+143 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -2513,10 +2503,10 @@ endobj
  /Type /Annot >>
 endobj
 % 'Page15': class PDFPage 
-145 0 obj
+144 0 obj
 % Page dictionary
-<< /Annots [ 143 0 R
- 144 0 R ]
+<< /Annots [ 142 0 R
+ 143 0 R ]
  /Contents 426 0 R
  /MediaBox [ 0
  0
@@ -2534,7 +2524,7 @@ endobj
  /Type /Page >>
 endobj
 % 'Annot.NUMBER125': class PDFDictionary 
-146 0 obj
+145 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -2549,7 +2539,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER126': class PDFDictionary 
-147 0 obj
+146 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://argparse.googlecode.com) >>
@@ -2564,7 +2554,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER127': class PDFDictionary 
-148 0 obj
+147 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://argparse.googlecode.com) >>
@@ -2579,7 +2569,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER128': class PDFDictionary 
-149 0 obj
+148 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://argparse.googlecode.com) >>
@@ -2594,7 +2584,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER129': class PDFDictionary 
-150 0 obj
+149 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -2609,7 +2599,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER130': class PDFDictionary 
-151 0 obj
+150 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://argparse.googlecode.com) >>
@@ -2624,7 +2614,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER131': class PDFDictionary 
-152 0 obj
+151 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://argparse.googlecode.com) >>
@@ -2639,7 +2629,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER132': class PDFDictionary 
-153 0 obj
+152 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -2654,7 +2644,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER133': class PDFDictionary 
-154 0 obj
+153 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -2669,7 +2659,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER134': class PDFDictionary 
-155 0 obj
+154 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://argparse.googlecode.com) >>
@@ -2684,7 +2674,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER135': class PDFDictionary 
-156 0 obj
+155 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -2699,7 +2689,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER136': class PDFDictionary 
-157 0 obj
+156 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -2714,7 +2704,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER137': class PDFDictionary 
-158 0 obj
+157 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -2729,9 +2719,10 @@ endobj
  /Type /Annot >>
 endobj
 % 'Page16': class PDFPage 
-159 0 obj
+158 0 obj
 % Page dictionary
-<< /Annots [ 146 0 R
+<< /Annots [ 145 0 R
+ 146 0 R
  147 0 R
  148 0 R
  149 0 R
@@ -2742,8 +2733,7 @@ endobj
  154 0 R
  155 0 R
  156 0 R
- 157 0 R
- 158 0 R ]
+ 157 0 R ]
  /Contents 427 0 R
  /MediaBox [ 0
  0
@@ -2761,7 +2751,7 @@ endobj
  /Type /Page >>
 endobj
 % 'Annot.NUMBER138': class PDFDictionary 
-160 0 obj
+159 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -2776,10 +2766,10 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER139': class PDFDictionary 
-161 0 obj
+160 0 obj
 << /A << /S /URI
  /Type /Action
- /URI (file:///home/micheles/Dropbox/md/gcodedev/plac/in-writing) >>
+ /URI (file:///home/micheles/Dropbox/md/gcodedev/plac/doc/in-writing) >>
  /Border [ 0
  0
  0 ]
@@ -2791,7 +2781,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER140': class PDFDictionary 
-162 0 obj
+161 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -2806,7 +2796,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER141': class PDFDictionary 
-163 0 obj
+162 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -2821,10 +2811,10 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER142': class PDFDictionary 
-164 0 obj
+163 0 obj
 << /A << /S /URI
  /Type /Action
- /URI (file:///home/micheles/Dropbox/md/gcodedev/plac/in-writing) >>
+ /URI (file:///home/micheles/Dropbox/md/gcodedev/plac/doc/in-writing) >>
  /Border [ 0
  0
  0 ]
@@ -2836,10 +2826,10 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER143': class PDFDictionary 
-165 0 obj
+164 0 obj
 << /A << /S /URI
  /Type /Action
- /URI (file:///home/micheles/Dropbox/md/gcodedev/plac/in-writing) >>
+ /URI (file:///home/micheles/Dropbox/md/gcodedev/plac/doc/in-writing) >>
  /Border [ 0
  0
  0 ]
@@ -2851,7 +2841,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER144': class PDFDictionary 
-166 0 obj
+165 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -2866,7 +2856,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER145': class PDFDictionary 
-167 0 obj
+166 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://argparse.googlecode.com) >>
@@ -2881,7 +2871,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER146': class PDFDictionary 
-168 0 obj
+167 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://argparse.googlecode.com/svn/tags/r11/doc/other-utilities.html?highlight=filetype#FileType) >>
@@ -2896,7 +2886,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER147': class PDFDictionary 
-169 0 obj
+168 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -2911,7 +2901,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER148': class PDFDictionary 
-170 0 obj
+169 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://argparse.googlecode.com/svn/tags/r11/doc/ArgumentParser.html) >>
@@ -2926,7 +2916,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER149': class PDFDictionary 
-171 0 obj
+170 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://argparse.googlecode.com) >>
@@ -2941,7 +2931,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER150': class PDFDictionary 
-172 0 obj
+171 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://argparse.googlecode.com) >>
@@ -2956,7 +2946,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER151': class PDFDictionary 
-173 0 obj
+172 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -2971,9 +2961,10 @@ endobj
  /Type /Annot >>
 endobj
 % 'Page17': class PDFPage 
-174 0 obj
+173 0 obj
 % Page dictionary
-<< /Annots [ 160 0 R
+<< /Annots [ 159 0 R
+ 160 0 R
  161 0 R
  162 0 R
  163 0 R
@@ -2985,8 +2976,7 @@ endobj
  169 0 R
  170 0 R
  171 0 R
- 172 0 R
- 173 0 R ]
+ 172 0 R ]
  /Contents 428 0 R
  /MediaBox [ 0
  0
@@ -3004,7 +2994,7 @@ endobj
  /Type /Page >>
 endobj
 % 'Annot.NUMBER152': class PDFDictionary 
-175 0 obj
+174 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -3019,7 +3009,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER153': class PDFDictionary 
-176 0 obj
+175 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -3034,7 +3024,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER154': class PDFDictionary 
-177 0 obj
+176 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/opterator) >>
@@ -3049,7 +3039,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER155': class PDFDictionary 
-178 0 obj
+177 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/CLIArgs) >>
@@ -3064,7 +3054,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER156': class PDFDictionary 
-179 0 obj
+178 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://argparse.googlecode.com) >>
@@ -3079,7 +3069,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER157': class PDFDictionary 
-180 0 obj
+179 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -3094,7 +3084,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER158': class PDFDictionary 
-181 0 obj
+180 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/Clap/0.7) >>
@@ -3109,7 +3099,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER159': class PDFDictionary 
-182 0 obj
+181 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -3124,7 +3114,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER160': class PDFDictionary 
-183 0 obj
+182 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/Clap/0.7) >>
@@ -3139,7 +3129,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER161': class PDFDictionary 
-184 0 obj
+183 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -3154,7 +3144,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER162': class PDFDictionary 
-185 0 obj
+184 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -3169,7 +3159,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER163': class PDFDictionary 
-186 0 obj
+185 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://docs.python.org/library/cmd.html) >>
@@ -3184,7 +3174,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER164': class PDFDictionary 
-187 0 obj
+186 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://packages.python.org/cmd2/) >>
@@ -3199,7 +3189,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER165': class PDFDictionary 
-188 0 obj
+187 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://packages.python.org/cmd2/) >>
@@ -3214,7 +3204,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER166': class PDFDictionary 
-189 0 obj
+188 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -3229,7 +3219,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER167': class PDFDictionary 
-190 0 obj
+189 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -3244,7 +3234,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER168': class PDFDictionary 
-191 0 obj
+190 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://argparse.googlecode.com) >>
@@ -3259,7 +3249,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER169': class PDFDictionary 
-192 0 obj
+191 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://argparse.googlecode.com) >>
@@ -3274,7 +3264,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER170': class PDFDictionary 
-193 0 obj
+192 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -3289,7 +3279,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER171': class PDFDictionary 
-194 0 obj
+193 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -3304,7 +3294,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER172': class PDFDictionary 
-195 0 obj
+194 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -3319,7 +3309,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER173': class PDFDictionary 
-196 0 obj
+195 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -3334,7 +3324,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER174': class PDFDictionary 
-197 0 obj
+196 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -3349,10 +3339,10 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER175': class PDFDictionary 
-198 0 obj
+197 0 obj
 << /A << /S /URI
  /Type /Action
- /URI (file:///home/micheles/Dropbox/md/gcodedev/plac/in-writing) >>
+ /URI (file:///home/micheles/Dropbox/md/gcodedev/plac/doc/in-writing) >>
  /Border [ 0
  0
  0 ]
@@ -3364,7 +3354,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER176': class PDFDictionary 
-199 0 obj
+198 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -3379,7 +3369,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER177': class PDFDictionary 
-200 0 obj
+199 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://code.activestate.com/recipes/278844-parsing-the-command-line/) >>
@@ -3394,7 +3384,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER178': class PDFDictionary 
-201 0 obj
+200 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -3409,7 +3399,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER179': class PDFDictionary 
-202 0 obj
+201 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://docs.python.org/library/optparse.html?highlight=optionparser#optparse.OptionParser) >>
@@ -3424,7 +3414,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER180': class PDFDictionary 
-203 0 obj
+202 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://argparse.googlecode.com) >>
@@ -3439,7 +3429,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER181': class PDFDictionary 
-204 0 obj
+203 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://argparse.googlecode.com) >>
@@ -3454,7 +3444,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER182': class PDFDictionary 
-205 0 obj
+204 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://argparse.googlecode.com/svn/tags/r11/doc/ArgumentParser.html) >>
@@ -3469,7 +3459,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER183': class PDFDictionary 
-206 0 obj
+205 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://argparse.googlecode.com) >>
@@ -3484,7 +3474,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER184': class PDFDictionary 
-207 0 obj
+206 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://argparse.googlecode.com) >>
@@ -3499,9 +3489,10 @@ endobj
  /Type /Annot >>
 endobj
 % 'Page18': class PDFPage 
-208 0 obj
+207 0 obj
 % Page dictionary
-<< /Annots [ 175 0 R
+<< /Annots [ 174 0 R
+ 175 0 R
  176 0 R
  177 0 R
  178 0 R
@@ -3532,8 +3523,7 @@ endobj
  203 0 R
  204 0 R
  205 0 R
- 206 0 R
- 207 0 R ]
+ 206 0 R ]
  /Contents 429 0 R
  /MediaBox [ 0
  0
@@ -3551,7 +3541,7 @@ endobj
  /Type /Page >>
 endobj
 % 'Annot.NUMBER185': class PDFDictionary 
-209 0 obj
+208 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/Clap/0.7) >>
@@ -3566,7 +3556,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER186': class PDFDictionary 
-210 0 obj
+209 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -3581,7 +3571,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER187': class PDFDictionary 
-211 0 obj
+210 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (mailto:michele.simionato@gmail.com) >>
@@ -3596,7 +3586,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER188': class PDFDictionary 
-212 0 obj
+211 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -3611,7 +3601,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER189': class PDFDictionary 
-213 0 obj
+212 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://micheles.googlecode.com/hg/plac/doc/plac.html) >>
@@ -3626,13 +3616,13 @@ endobj
  /Type /Annot >>
 endobj
 % 'Page19': class PDFPage 
-214 0 obj
+213 0 obj
 % Page dictionary
-<< /Annots [ 209 0 R
+<< /Annots [ 208 0 R
+ 209 0 R
  210 0 R
  211 0 R
- 212 0 R
- 213 0 R ]
+ 212 0 R ]
  /Contents 430 0 R
  /MediaBox [ 0
  0
@@ -3650,12 +3640,12 @@ endobj
  /Type /Page >>
 endobj
 % 'Annot.NUMBER190': class LinkAnnotation 
-215 0 obj
+214 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 9 0 R
+ /Dest [ 8 0 R
  /XYZ
  62.69291
  765.0236
@@ -3668,12 +3658,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER191': class LinkAnnotation 
-216 0 obj
+215 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 9 0 R
+ /Dest [ 8 0 R
  /XYZ
  62.69291
  765.0236
@@ -3686,12 +3676,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER192': class LinkAnnotation 
-217 0 obj
+216 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 96 0 R
+ /Dest [ 95 0 R
  /XYZ
  62.69291
  765.0236
@@ -3704,12 +3694,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER193': class LinkAnnotation 
-218 0 obj
+217 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 96 0 R
+ /Dest [ 95 0 R
  /XYZ
  62.69291
  765.0236
@@ -3722,12 +3712,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER194': class LinkAnnotation 
-219 0 obj
+218 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 96 0 R
+ /Dest [ 95 0 R
  /XYZ
  62.69291
  411.0236
@@ -3740,12 +3730,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER195': class LinkAnnotation 
-220 0 obj
+219 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 96 0 R
+ /Dest [ 95 0 R
  /XYZ
  62.69291
  411.0236
@@ -3758,12 +3748,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER196': class LinkAnnotation 
-221 0 obj
+220 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 110 0 R
+ /Dest [ 109 0 R
  /XYZ
  62.69291
  765.0236
@@ -3776,12 +3766,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER197': class LinkAnnotation 
-222 0 obj
+221 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 110 0 R
+ /Dest [ 109 0 R
  /XYZ
  62.69291
  765.0236
@@ -3794,12 +3784,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER198': class LinkAnnotation 
-223 0 obj
+222 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 120 0 R
+ /Dest [ 119 0 R
  /XYZ
  62.69291
  741.0236
@@ -3812,12 +3802,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER199': class LinkAnnotation 
-224 0 obj
+223 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 120 0 R
+ /Dest [ 119 0 R
  /XYZ
  62.69291
  741.0236
@@ -3830,12 +3820,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER200': class LinkAnnotation 
-225 0 obj
+224 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 124 0 R
+ /Dest [ 123 0 R
  /XYZ
  62.69291
  765.0236
@@ -3848,12 +3838,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER201': class LinkAnnotation 
-226 0 obj
+225 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 124 0 R
+ /Dest [ 123 0 R
  /XYZ
  62.69291
  765.0236
@@ -3866,12 +3856,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER202': class LinkAnnotation 
-227 0 obj
+226 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 124 0 R
+ /Dest [ 123 0 R
  /XYZ
  62.69291
  265.7299
@@ -3884,12 +3874,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER203': class LinkAnnotation 
-228 0 obj
+227 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 124 0 R
+ /Dest [ 123 0 R
  /XYZ
  62.69291
  265.7299
@@ -3902,12 +3892,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER204': class LinkAnnotation 
-229 0 obj
+228 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 132 0 R
+ /Dest [ 131 0 R
  /XYZ
  62.69291
  522.6236
@@ -3920,12 +3910,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER205': class LinkAnnotation 
-230 0 obj
+229 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 132 0 R
+ /Dest [ 131 0 R
  /XYZ
  62.69291
  522.6236
@@ -3938,12 +3928,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER206': class LinkAnnotation 
-231 0 obj
+230 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 137 0 R
+ /Dest [ 136 0 R
  /XYZ
  62.69291
  552.6236
@@ -3956,12 +3946,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER207': class LinkAnnotation 
-232 0 obj
+231 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 137 0 R
+ /Dest [ 136 0 R
  /XYZ
  62.69291
  552.6236
@@ -3974,12 +3964,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER208': class LinkAnnotation 
-233 0 obj
+232 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 140 0 R
+ /Dest [ 139 0 R
  /XYZ
  62.69291
  513.8236
@@ -3992,12 +3982,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER209': class LinkAnnotation 
-234 0 obj
+233 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 140 0 R
+ /Dest [ 139 0 R
  /XYZ
  62.69291
  513.8236
@@ -4010,12 +4000,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER210': class LinkAnnotation 
-235 0 obj
+234 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 142 0 R
+ /Dest [ 141 0 R
  /XYZ
  62.69291
  493.4236
@@ -4028,12 +4018,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER211': class LinkAnnotation 
-236 0 obj
+235 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 142 0 R
+ /Dest [ 141 0 R
  /XYZ
  62.69291
  493.4236
@@ -4046,12 +4036,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER212': class LinkAnnotation 
-237 0 obj
+236 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 159 0 R
+ /Dest [ 158 0 R
  /XYZ
  62.69291
  422.6236
@@ -4064,12 +4054,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER213': class LinkAnnotation 
-238 0 obj
+237 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 159 0 R
+ /Dest [ 158 0 R
  /XYZ
  62.69291
  422.6236
@@ -4082,12 +4072,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER214': class LinkAnnotation 
-239 0 obj
+238 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 208 0 R
+ /Dest [ 207 0 R
  /XYZ
  62.69291
  741.0236
@@ -4100,12 +4090,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER215': class LinkAnnotation 
-240 0 obj
+239 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 208 0 R
+ /Dest [ 207 0 R
  /XYZ
  62.69291
  741.0236
@@ -4118,12 +4108,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER216': class LinkAnnotation 
-241 0 obj
+240 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 208 0 R
+ /Dest [ 207 0 R
  /XYZ
  62.69291
  513.0236
@@ -4136,12 +4126,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER217': class LinkAnnotation 
-242 0 obj
+241 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 208 0 R
+ /Dest [ 207 0 R
  /XYZ
  62.69291
  513.0236
@@ -4154,12 +4144,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER218': class LinkAnnotation 
-243 0 obj
+242 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 208 0 R
+ /Dest [ 207 0 R
  /XYZ
  62.69291
  309.0236
@@ -4172,12 +4162,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER219': class LinkAnnotation 
-244 0 obj
+243 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 208 0 R
+ /Dest [ 207 0 R
  /XYZ
  62.69291
  309.0236
@@ -4190,12 +4180,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER220': class LinkAnnotation 
-245 0 obj
+244 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 214 0 R
+ /Dest [ 213 0 R
  /XYZ
  62.69291
  681.0236
@@ -4208,12 +4198,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER221': class LinkAnnotation 
-246 0 obj
+245 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 214 0 R
+ /Dest [ 213 0 R
  /XYZ
  62.69291
  681.0236
@@ -4226,12 +4216,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER222': class LinkAnnotation 
-247 0 obj
+246 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 297 0 R
+ /Dest [ 296 0 R
  /XYZ
  62.69291
  765.0236
@@ -4244,12 +4234,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER223': class LinkAnnotation 
-248 0 obj
+247 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 297 0 R
+ /Dest [ 296 0 R
  /XYZ
  62.69291
  765.0236
@@ -4262,12 +4252,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER224': class LinkAnnotation 
-249 0 obj
+248 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 297 0 R
+ /Dest [ 296 0 R
  /XYZ
  62.69291
  543.0236
@@ -4280,12 +4270,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER225': class LinkAnnotation 
-250 0 obj
+249 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 297 0 R
+ /Dest [ 296 0 R
  /XYZ
  62.69291
  543.0236
@@ -4298,12 +4288,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER226': class LinkAnnotation 
-251 0 obj
+250 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 300 0 R
+ /Dest [ 299 0 R
  /XYZ
  62.69291
  765.0236
@@ -4316,12 +4306,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER227': class LinkAnnotation 
-252 0 obj
+251 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 300 0 R
+ /Dest [ 299 0 R
  /XYZ
  62.69291
  765.0236
@@ -4334,12 +4324,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER228': class LinkAnnotation 
-253 0 obj
+252 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 309 0 R
+ /Dest [ 308 0 R
  /XYZ
  62.69291
  741.0236
@@ -4352,12 +4342,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER229': class LinkAnnotation 
-254 0 obj
+253 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 309 0 R
+ /Dest [ 308 0 R
  /XYZ
  62.69291
  741.0236
@@ -4370,12 +4360,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER230': class LinkAnnotation 
-255 0 obj
+254 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 314 0 R
+ /Dest [ 313 0 R
  /XYZ
  62.69291
  431.8485
@@ -4388,12 +4378,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER231': class LinkAnnotation 
-256 0 obj
+255 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 314 0 R
+ /Dest [ 313 0 R
  /XYZ
  62.69291
  431.8485
@@ -4406,12 +4396,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER232': class LinkAnnotation 
-257 0 obj
+256 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 319 0 R
+ /Dest [ 318 0 R
  /XYZ
  62.69291
  515.8236
@@ -4424,12 +4414,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER233': class LinkAnnotation 
-258 0 obj
+257 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 319 0 R
+ /Dest [ 318 0 R
  /XYZ
  62.69291
  515.8236
@@ -4442,12 +4432,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER234': class LinkAnnotation 
-259 0 obj
+258 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 324 0 R
+ /Dest [ 323 0 R
  /XYZ
  62.69291
  441.5042
@@ -4460,12 +4450,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER235': class LinkAnnotation 
-260 0 obj
+259 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 324 0 R
+ /Dest [ 323 0 R
  /XYZ
  62.69291
  441.5042
@@ -4478,12 +4468,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER236': class LinkAnnotation 
-261 0 obj
+260 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 332 0 R
+ /Dest [ 331 0 R
  /XYZ
  62.69291
  765.0236
@@ -4496,12 +4486,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER237': class LinkAnnotation 
-262 0 obj
+261 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 332 0 R
+ /Dest [ 331 0 R
  /XYZ
  62.69291
  765.0236
@@ -4514,12 +4504,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER238': class LinkAnnotation 
-263 0 obj
+262 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 343 0 R
+ /Dest [ 342 0 R
  /XYZ
  62.69291
  258.6236
@@ -4532,12 +4522,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER239': class LinkAnnotation 
-264 0 obj
+263 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 343 0 R
+ /Dest [ 342 0 R
  /XYZ
  62.69291
  258.6236
@@ -4550,12 +4540,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER240': class LinkAnnotation 
-265 0 obj
+264 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 347 0 R
+ /Dest [ 346 0 R
  /XYZ
  62.69291
  401.4236
@@ -4568,12 +4558,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER241': class LinkAnnotation 
-266 0 obj
+265 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 347 0 R
+ /Dest [ 346 0 R
  /XYZ
  62.69291
  401.4236
@@ -4586,12 +4576,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER242': class LinkAnnotation 
-267 0 obj
+266 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 350 0 R
+ /Dest [ 349 0 R
  /XYZ
  62.69291
  408.6236
@@ -4604,12 +4594,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER243': class LinkAnnotation 
-268 0 obj
+267 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 350 0 R
+ /Dest [ 349 0 R
  /XYZ
  62.69291
  408.6236
@@ -4622,12 +4612,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER244': class LinkAnnotation 
-269 0 obj
+268 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 354 0 R
+ /Dest [ 353 0 R
  /XYZ
  62.69291
  244.6236
@@ -4640,12 +4630,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER245': class LinkAnnotation 
-270 0 obj
+269 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 354 0 R
+ /Dest [ 353 0 R
  /XYZ
  62.69291
  244.6236
@@ -4658,12 +4648,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER246': class LinkAnnotation 
-271 0 obj
+270 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 357 0 R
+ /Dest [ 356 0 R
  /XYZ
  62.69291
  354.6236
@@ -4676,12 +4666,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER247': class LinkAnnotation 
-272 0 obj
+271 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 357 0 R
+ /Dest [ 356 0 R
  /XYZ
  62.69291
  354.6236
@@ -4694,12 +4684,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER248': class LinkAnnotation 
-273 0 obj
+272 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 361 0 R
+ /Dest [ 360 0 R
  /XYZ
  62.69291
  511.8236
@@ -4712,12 +4702,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER249': class LinkAnnotation 
-274 0 obj
+273 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 361 0 R
+ /Dest [ 360 0 R
  /XYZ
  62.69291
  511.8236
@@ -4730,12 +4720,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER250': class LinkAnnotation 
-275 0 obj
+274 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 363 0 R
+ /Dest [ 362 0 R
  /XYZ
  62.69291
  711.0236
@@ -4748,12 +4738,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER251': class LinkAnnotation 
-276 0 obj
+275 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 363 0 R
+ /Dest [ 362 0 R
  /XYZ
  62.69291
  711.0236
@@ -4766,12 +4756,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER252': class LinkAnnotation 
-277 0 obj
+276 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 365 0 R
+ /Dest [ 364 0 R
  /XYZ
  62.69291
  765.0236
@@ -4784,12 +4774,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER253': class LinkAnnotation 
-278 0 obj
+277 0 obj
 << /Border [ 0
  0
  0 ]
  /Contents ()
- /Dest [ 365 0 R
+ /Dest [ 364 0 R
  /XYZ
  62.69291
  765.0236
@@ -4802,7 +4792,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER254': class LinkAnnotation 
-279 0 obj
+278 0 obj
 << /Border [ 0
  0
  0 ]
@@ -4810,7 +4800,7 @@ endobj
  /Dest [ 369 0 R
  /XYZ
  62.69291
- 729.0236
+ 630.4159
  0 ]
  /Rect [ 82.69291
  150.5936
@@ -4820,7 +4810,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER255': class LinkAnnotation 
-280 0 obj
+279 0 obj
 << /Border [ 0
  0
  0 ]
@@ -4828,7 +4818,7 @@ endobj
  /Dest [ 369 0 R
  /XYZ
  62.69291
- 729.0236
+ 630.4159
  0 ]
  /Rect [ 521.4627
  150.5936
@@ -4838,7 +4828,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER256': class LinkAnnotation 
-281 0 obj
+280 0 obj
 << /Border [ 0
  0
  0 ]
@@ -4846,7 +4836,7 @@ endobj
  /Dest [ 369 0 R
  /XYZ
  62.69291
- 258.6236
+ 160.0159
  0 ]
  /Rect [ 82.69291
  132.5936
@@ -4856,7 +4846,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER257': class LinkAnnotation 
-282 0 obj
+281 0 obj
 << /Border [ 0
  0
  0 ]
@@ -4864,7 +4854,7 @@ endobj
  /Dest [ 369 0 R
  /XYZ
  62.69291
- 258.6236
+ 160.0159
  0 ]
  /Rect [ 521.4627
  132.5936
@@ -4874,7 +4864,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER258': class LinkAnnotation 
-283 0 obj
+282 0 obj
 << /Border [ 0
  0
  0 ]
@@ -4882,7 +4872,7 @@ endobj
  /Dest [ 371 0 R
  /XYZ
  62.69291
- 586.6772
+ 508.6772
  0 ]
  /Rect [ 82.69291
  114.5936
@@ -4892,7 +4882,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER259': class LinkAnnotation 
-284 0 obj
+283 0 obj
 << /Border [ 0
  0
  0 ]
@@ -4900,7 +4890,7 @@ endobj
  /Dest [ 371 0 R
  /XYZ
  62.69291
- 586.6772
+ 508.6772
  0 ]
  /Rect [ 521.4627
  114.5936
@@ -4910,9 +4900,10 @@ endobj
  /Type /Annot >>
 endobj
 % 'Page20': class PDFPage 
-285 0 obj
+284 0 obj
 % Page dictionary
-<< /Annots [ 215 0 R
+<< /Annots [ 214 0 R
+ 215 0 R
  216 0 R
  217 0 R
  218 0 R
@@ -4980,8 +4971,7 @@ endobj
  280 0 R
  281 0 R
  282 0 R
- 283 0 R
- 284 0 R ]
+ 283 0 R ]
  /Contents 431 0 R
  /MediaBox [ 0
  0
@@ -4999,7 +4989,7 @@ endobj
  /Type /Page >>
 endobj
 % 'Annot.NUMBER260': class PDFDictionary 
-286 0 obj
+285 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -5014,7 +5004,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER261': class PDFDictionary 
-287 0 obj
+286 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -5029,7 +5019,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER262': class PDFDictionary 
-288 0 obj
+287 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -5044,7 +5034,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER263': class PDFDictionary 
-289 0 obj
+288 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -5059,7 +5049,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER264': class PDFDictionary 
-290 0 obj
+289 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -5074,7 +5064,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER265': class PDFDictionary 
-291 0 obj
+290 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://twill.idyll.org/) >>
@@ -5089,7 +5079,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER266': class PDFDictionary 
-292 0 obj
+291 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -5104,7 +5094,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER267': class PDFDictionary 
-293 0 obj
+292 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -5119,7 +5109,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER268': class PDFDictionary 
-294 0 obj
+293 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -5134,7 +5124,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER269': class PDFDictionary 
-295 0 obj
+294 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -5149,7 +5139,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER270': class PDFDictionary 
-296 0 obj
+295 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://micheles.googlecode.com/hg/plac/doc/plac.html) >>
@@ -5164,9 +5154,10 @@ endobj
  /Type /Annot >>
 endobj
 % 'Page21': class PDFPage 
-297 0 obj
+296 0 obj
 % Page dictionary
-<< /Annots [ 286 0 R
+<< /Annots [ 285 0 R
+ 286 0 R
  287 0 R
  288 0 R
  289 0 R
@@ -5175,8 +5166,7 @@ endobj
  292 0 R
  293 0 R
  294 0 R
- 295 0 R
- 296 0 R ]
+ 295 0 R ]
  /Contents 432 0 R
  /MediaBox [ 0
  0
@@ -5194,7 +5184,7 @@ endobj
  /Type /Page >>
 endobj
 % 'Annot.NUMBER271': class PDFDictionary 
-298 0 obj
+297 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -5209,9 +5199,9 @@ endobj
  /Type /Annot >>
 endobj
 % 'Page22': class PDFPage 
-299 0 obj
+298 0 obj
 % Page dictionary
-<< /Annots [ 298 0 R ]
+<< /Annots [ 297 0 R ]
  /Contents 433 0 R
  /MediaBox [ 0
  0
@@ -5229,7 +5219,7 @@ endobj
  /Type /Page >>
 endobj
 % 'Page23': class PDFPage 
-300 0 obj
+299 0 obj
 % Page dictionary
 << /Contents 434 0 R
  /MediaBox [ 0
@@ -5248,7 +5238,7 @@ endobj
  /Type /Page >>
 endobj
 % 'Annot.NUMBER272': class PDFDictionary 
-301 0 obj
+300 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -5263,7 +5253,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER273': class PDFDictionary 
-302 0 obj
+301 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -5278,7 +5268,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER274': class PDFDictionary 
-303 0 obj
+302 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -5293,7 +5283,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER275': class PDFDictionary 
-304 0 obj
+303 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://docs.python.org/library/shlex.html) >>
@@ -5308,7 +5298,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER276': class PDFDictionary 
-305 0 obj
+304 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -5323,7 +5313,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER277': class PDFDictionary 
-306 0 obj
+305 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://docs.python.org/library/shlex.html) >>
@@ -5338,7 +5328,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER278': class PDFDictionary 
-307 0 obj
+306 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -5353,7 +5343,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER279': class PDFDictionary 
-308 0 obj
+307 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://docs.python.org/library/shlex.html) >>
@@ -5368,16 +5358,16 @@ endobj
  /Type /Annot >>
 endobj
 % 'Page24': class PDFPage 
-309 0 obj
+308 0 obj
 % Page dictionary
-<< /Annots [ 301 0 R
+<< /Annots [ 300 0 R
+ 301 0 R
  302 0 R
  303 0 R
  304 0 R
  305 0 R
  306 0 R
- 307 0 R
- 308 0 R ]
+ 307 0 R ]
  /Contents 435 0 R
  /MediaBox [ 0
  0
@@ -5395,7 +5385,7 @@ endobj
  /Type /Page >>
 endobj
 % 'Annot.NUMBER280': class PDFDictionary 
-310 0 obj
+309 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -5410,7 +5400,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER281': class PDFDictionary 
-311 0 obj
+310 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -5425,7 +5415,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER282': class PDFDictionary 
-312 0 obj
+311 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -5440,7 +5430,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER283': class PDFDictionary 
-313 0 obj
+312 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -5455,12 +5445,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Page25': class PDFPage 
-314 0 obj
+313 0 obj
 % Page dictionary
-<< /Annots [ 310 0 R
+<< /Annots [ 309 0 R
+ 310 0 R
  311 0 R
- 312 0 R
- 313 0 R ]
+ 312 0 R ]
  /Contents 436 0 R
  /MediaBox [ 0
  0
@@ -5478,7 +5468,7 @@ endobj
  /Type /Page >>
 endobj
 % 'Annot.NUMBER284': class PDFDictionary 
-315 0 obj
+314 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://micheles.googlecode.com/hg/plac/doc/plac.html) >>
@@ -5493,7 +5483,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER285': class PDFDictionary 
-316 0 obj
+315 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -5508,7 +5498,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER286': class PDFDictionary 
-317 0 obj
+316 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -5523,7 +5513,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER287': class PDFDictionary 
-318 0 obj
+317 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -5538,12 +5528,12 @@ endobj
  /Type /Annot >>
 endobj
 % 'Page26': class PDFPage 
-319 0 obj
+318 0 obj
 % Page dictionary
-<< /Annots [ 315 0 R
+<< /Annots [ 314 0 R
+ 315 0 R
  316 0 R
- 317 0 R
- 318 0 R ]
+ 317 0 R ]
  /Contents 437 0 R
  /MediaBox [ 0
  0
@@ -5561,7 +5551,7 @@ endobj
  /Type /Page >>
 endobj
 % 'Annot.NUMBER288': class PDFDictionary 
-320 0 obj
+319 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -5576,7 +5566,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER289': class PDFDictionary 
-321 0 obj
+320 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -5591,7 +5581,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER290': class PDFDictionary 
-322 0 obj
+321 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://docs.python.org/library/cmd.html) >>
@@ -5606,11 +5596,11 @@ endobj
  /Type /Annot >>
 endobj
 % 'Page27': class PDFPage 
-323 0 obj
+322 0 obj
 % Page dictionary
-<< /Annots [ 320 0 R
- 321 0 R
- 322 0 R ]
+<< /Annots [ 319 0 R
+ 320 0 R
+ 321 0 R ]
  /Contents 438 0 R
  /MediaBox [ 0
  0
@@ -5628,7 +5618,7 @@ endobj
  /Type /Page >>
 endobj
 % 'Page28': class PDFPage 
-324 0 obj
+323 0 obj
 % Page dictionary
 << /Contents 439 0 R
  /MediaBox [ 0
@@ -5647,7 +5637,7 @@ endobj
  /Type /Page >>
 endobj
 % 'Page29': class PDFPage 
-325 0 obj
+324 0 obj
 % Page dictionary
 << /Contents 440 0 R
  /MediaBox [ 0
@@ -5666,7 +5656,7 @@ endobj
  /Type /Page >>
 endobj
 % 'Annot.NUMBER291': class PDFDictionary 
-326 0 obj
+325 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -5681,7 +5671,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER292': class PDFDictionary 
-327 0 obj
+326 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://freshmeat.net/projects/rlwrap/) >>
@@ -5696,7 +5686,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER293': class PDFDictionary 
-328 0 obj
+327 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -5711,7 +5701,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER294': class PDFDictionary 
-329 0 obj
+328 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://ipython.scipy.org/moin/PyReadline/Intro) >>
@@ -5726,7 +5716,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER295': class PDFDictionary 
-330 0 obj
+329 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -5741,7 +5731,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER296': class PDFDictionary 
-331 0 obj
+330 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -5756,14 +5746,14 @@ endobj
  /Type /Annot >>
 endobj
 % 'Page30': class PDFPage 
-332 0 obj
+331 0 obj
 % Page dictionary
-<< /Annots [ 326 0 R
+<< /Annots [ 325 0 R
+ 326 0 R
  327 0 R
  328 0 R
  329 0 R
- 330 0 R
- 331 0 R ]
+ 330 0 R ]
  /Contents 441 0 R
  /MediaBox [ 0
  0
@@ -5781,7 +5771,7 @@ endobj
  /Type /Page >>
 endobj
 % 'Annot.NUMBER297': class PDFDictionary 
-333 0 obj
+332 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://docs.python.org/library/cmd.html) >>
@@ -5796,7 +5786,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER298': class PDFDictionary 
-334 0 obj
+333 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://docs.python.org/library/cmd.html) >>
@@ -5811,7 +5801,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER299': class PDFDictionary 
-335 0 obj
+334 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://argparse.googlecode.com) >>
@@ -5826,7 +5816,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER300': class PDFDictionary 
-336 0 obj
+335 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -5841,7 +5831,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER301': class PDFDictionary 
-337 0 obj
+336 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://argparse.googlecode.com) >>
@@ -5856,7 +5846,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER302': class PDFDictionary 
-338 0 obj
+337 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -5871,7 +5861,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER303': class PDFDictionary 
-339 0 obj
+338 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -5886,7 +5876,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER304': class PDFDictionary 
-340 0 obj
+339 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -5901,7 +5891,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER305': class PDFDictionary 
-341 0 obj
+340 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -5916,7 +5906,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER306': class PDFDictionary 
-342 0 obj
+341 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://docs.python.org/distutils/) >>
@@ -5931,9 +5921,10 @@ endobj
  /Type /Annot >>
 endobj
 % 'Page31': class PDFPage 
-343 0 obj
+342 0 obj
 % Page dictionary
-<< /Annots [ 333 0 R
+<< /Annots [ 332 0 R
+ 333 0 R
  334 0 R
  335 0 R
  336 0 R
@@ -5941,8 +5932,7 @@ endobj
  338 0 R
  339 0 R
  340 0 R
- 341 0 R
- 342 0 R ]
+ 341 0 R ]
  /Contents 442 0 R
  /MediaBox [ 0
  0
@@ -5960,7 +5950,7 @@ endobj
  /Type /Page >>
 endobj
 % 'Annot.NUMBER307': class PDFDictionary 
-344 0 obj
+343 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://argparse.googlecode.com) >>
@@ -5975,9 +5965,9 @@ endobj
  /Type /Annot >>
 endobj
 % 'Page32': class PDFPage 
-345 0 obj
+344 0 obj
 % Page dictionary
-<< /Annots [ 344 0 R ]
+<< /Annots [ 343 0 R ]
  /Contents 443 0 R
  /MediaBox [ 0
  0
@@ -5995,7 +5985,7 @@ endobj
  /Type /Page >>
 endobj
 % 'Annot.NUMBER308': class PDFDictionary 
-346 0 obj
+345 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -6010,9 +6000,9 @@ endobj
  /Type /Annot >>
 endobj
 % 'Page33': class PDFPage 
-347 0 obj
+346 0 obj
 % Page dictionary
-<< /Annots [ 346 0 R ]
+<< /Annots [ 345 0 R ]
  /Contents 444 0 R
  /MediaBox [ 0
  0
@@ -6030,7 +6020,7 @@ endobj
  /Type /Page >>
 endobj
 % 'Page34': class PDFPage 
-348 0 obj
+347 0 obj
 % Page dictionary
 << /Contents 445 0 R
  /MediaBox [ 0
@@ -6049,7 +6039,7 @@ endobj
  /Type /Page >>
 endobj
 % 'Annot.NUMBER309': class PDFDictionary 
-349 0 obj
+348 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -6064,9 +6054,9 @@ endobj
  /Type /Annot >>
 endobj
 % 'Page35': class PDFPage 
-350 0 obj
+349 0 obj
 % Page dictionary
-<< /Annots [ 349 0 R ]
+<< /Annots [ 348 0 R ]
  /Contents 446 0 R
  /MediaBox [ 0
  0
@@ -6084,7 +6074,7 @@ endobj
  /Type /Page >>
 endobj
 % 'Annot.NUMBER310': class PDFDictionary 
-351 0 obj
+350 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -6099,7 +6089,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER311': class PDFDictionary 
-352 0 obj
+351 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://docs.python.org/library/multiprocessing.html) >>
@@ -6114,7 +6104,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER312': class PDFDictionary 
-353 0 obj
+352 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -6129,11 +6119,11 @@ endobj
  /Type /Annot >>
 endobj
 % 'Page36': class PDFPage 
-354 0 obj
+353 0 obj
 % Page dictionary
-<< /Annots [ 351 0 R
- 352 0 R
- 353 0 R ]
+<< /Annots [ 350 0 R
+ 351 0 R
+ 352 0 R ]
  /Contents 447 0 R
  /MediaBox [ 0
  0
@@ -6151,7 +6141,7 @@ endobj
  /Type /Page >>
 endobj
 % 'Annot.NUMBER313': class PDFDictionary 
-355 0 obj
+354 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -6166,7 +6156,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER314': class PDFDictionary 
-356 0 obj
+355 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -6181,10 +6171,10 @@ endobj
  /Type /Annot >>
 endobj
 % 'Page37': class PDFPage 
-357 0 obj
+356 0 obj
 % Page dictionary
-<< /Annots [ 355 0 R
- 356 0 R ]
+<< /Annots [ 354 0 R
+ 355 0 R ]
  /Contents 448 0 R
  /MediaBox [ 0
  0
@@ -6202,7 +6192,7 @@ endobj
  /Type /Page >>
 endobj
 % 'Page38': class PDFPage 
-358 0 obj
+357 0 obj
 % Page dictionary
 << /Contents 449 0 R
  /MediaBox [ 0
@@ -6221,7 +6211,7 @@ endobj
  /Type /Page >>
 endobj
 % 'Annot.NUMBER315': class PDFDictionary 
-359 0 obj
+358 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -6236,7 +6226,7 @@ endobj
  /Type /Annot >>
 endobj
 % 'Annot.NUMBER316': class PDFDictionary 
-360 0 obj
+359 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://docs.python.org/library/multiprocessing.html) >>
@@ -6251,10 +6241,10 @@ endobj
  /Type /Annot >>
 endobj
 % 'Page39': class PDFPage 
-361 0 obj
+360 0 obj
 % Page dictionary
-<< /Annots [ 359 0 R
- 360 0 R ]
+<< /Annots [ 358 0 R
+ 359 0 R ]
  /Contents 450 0 R
  /MediaBox [ 0
  0
@@ -6272,7 +6262,7 @@ endobj
  /Type /Page >>
 endobj
 % 'Annot.NUMBER317': class PDFDictionary 
-362 0 obj
+361 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -6287,9 +6277,9 @@ endobj
  /Type /Annot >>
 endobj
 % 'Page40': class PDFPage 
-363 0 obj
+362 0 obj
 % Page dictionary
-<< /Annots [ 362 0 R ]
+<< /Annots [ 361 0 R ]
  /Contents 451 0 R
  /MediaBox [ 0
  0
@@ -6307,7 +6297,7 @@ endobj
  /Type /Page >>
 endobj
 % 'Annot.NUMBER318': class PDFDictionary 
-364 0 obj
+363 0 obj
 << /A << /S /URI
  /Type /Action
  /URI (http://pypi.python.org/pypi/plac) >>
@@ -6322,9 +6312,9 @@ endobj
  /Type /Annot >>
 endobj
 % 'Page41': class PDFPage 
-365 0 obj
+364 0 obj
 % Page dictionary
-<< /Annots [ 364 0 R ]
+<< /Annots [ 363 0 R ]
  /Contents 452 0 R
  /MediaBox [ 0
  0
@@ -6342,7 +6332,7 @@ endobj
  /Type /Page >>
 endobj
 % 'Page42': class PDFPage 
-366 0 obj
+365 0 obj
 % Page dictionary
 << /Contents 453 0 R
  /MediaBox [ 0
@@ -6361,6 +6351,21 @@ endobj
  /Type /Page >>
 endobj
 % 'Annot.NUMBER319': class PDFDictionary 
+366 0 obj
+<< /A << /S /URI
+ /Type /Action
+ /URI (http://pypi.python.org/pypi/plac) >>
+ /Border [ 0
+ 0
+ 0 ]
+ /Rect [ 473.5049
+ 726.5936
+ 494.7927
+ 738.5936 ]
+ /Subtype /Link
+ /Type /Annot >>
+endobj
+% 'Annot.NUMBER320': class PDFDictionary 
 367 0 obj
 << /A << /S /URI
  /Type /Action
@@ -6369,13 +6374,13 @@ endobj
  0
  0 ]
  /Rect [ 172.4311
- 612.5936
+ 513.9859
  194.7087
- 624.5936 ]
+ 525.9859 ]
  /Subtype /Link
  /Type /Annot >>
 endobj
-% 'Annot.NUMBER320': class PDFDictionary 
+% 'Annot.NUMBER321': class PDFDictionary 
 368 0 obj
 << /A << /S /URI
  /Type /Action
@@ -6384,16 +6389,17 @@ endobj
  0
  0 ]
  /Rect [ 91.57623
- 226.1936
+ 127.5859
  114.8995
- 238.1936 ]
+ 139.5859 ]
  /Subtype /Link
  /Type /Annot >>
 endobj
 % 'Page43': class PDFPage 
 369 0 obj
 % Page dictionary
-<< /Annots [ 367 0 R
+<< /Annots [ 366 0 R
+ 367 0 R
  368 0 R ]
  /Contents 454 0 R
  /MediaBox [ 0
@@ -6411,7 +6417,7 @@ endobj
  /Trans <<  >>
  /Type /Page >>
 endobj
-% 'Annot.NUMBER321': class PDFDictionary 
+% 'Annot.NUMBER322': class PDFDictionary 
 370 0 obj
 << /A << /S /URI
  /Type /Action
@@ -6420,9 +6426,9 @@ endobj
  0
  0 ]
  /Rect [ 106.6216
- 554.2472
+ 476.2472
  128.3202
- 566.2472 ]
+ 488.2472 ]
  /Subtype /Link
  /Type /Annot >>
 endobj
@@ -6477,7 +6483,7 @@ endobj
 % 'R374': class PDFInfo 
 374 0 obj
 << /Author ()
- /CreationDate (D:20100811080133-01'00')
+ /CreationDate (D:20100831075140-01'00')
  /Keywords ()
  /Producer (ReportLab http://www.reportlab.com)
  /Subject (\(unspecified\))
@@ -6493,7 +6499,7 @@ endobj
 % 'Outline.0': class OutlineEntryObject 
 376 0 obj
 << /Count 14
- /Dest [ 9 0 R
+ /Dest [ 8 0 R
  /XYZ
  62.69291
  765.0236
@@ -6506,7 +6512,7 @@ endobj
 endobj
 % 'Outline.36.0': class OutlineEntryObject 
 377 0 obj
-<< /Dest [ 96 0 R
+<< /Dest [ 95 0 R
  /XYZ
  62.69291
  765.0236
@@ -6517,7 +6523,7 @@ endobj
 endobj
 % 'Outline.36.1': class OutlineEntryObject 
 378 0 obj
-<< /Dest [ 96 0 R
+<< /Dest [ 95 0 R
  /XYZ
  62.69291
  411.0236
@@ -6529,7 +6535,7 @@ endobj
 endobj
 % 'Outline.36.2': class OutlineEntryObject 
 379 0 obj
-<< /Dest [ 110 0 R
+<< /Dest [ 109 0 R
  /XYZ
  62.69291
  765.0236
@@ -6541,7 +6547,7 @@ endobj
 endobj
 % 'Outline.36.3': class OutlineEntryObject 
 380 0 obj
-<< /Dest [ 120 0 R
+<< /Dest [ 119 0 R
  /XYZ
  62.69291
  741.0236
@@ -6553,7 +6559,7 @@ endobj
 endobj
 % 'Outline.36.4': class OutlineEntryObject 
 381 0 obj
-<< /Dest [ 124 0 R
+<< /Dest [ 123 0 R
  /XYZ
  62.69291
  765.0236
@@ -6565,7 +6571,7 @@ endobj
 endobj
 % 'Outline.36.5': class OutlineEntryObject 
 382 0 obj
-<< /Dest [ 124 0 R
+<< /Dest [ 123 0 R
  /XYZ
  62.69291
  265.7299
@@ -6577,7 +6583,7 @@ endobj
 endobj
 % 'Outline.36.6': class OutlineEntryObject 
 383 0 obj
-<< /Dest [ 132 0 R
+<< /Dest [ 131 0 R
  /XYZ
  62.69291
  522.6236
@@ -6589,7 +6595,7 @@ endobj
 endobj
 % 'Outline.36.7': class OutlineEntryObject 
 384 0 obj
-<< /Dest [ 137 0 R
+<< /Dest [ 136 0 R
  /XYZ
  62.69291
  552.6236
@@ -6601,7 +6607,7 @@ endobj
 endobj
 % 'Outline.36.8': class OutlineEntryObject 
 385 0 obj
-<< /Dest [ 140 0 R
+<< /Dest [ 139 0 R
  /XYZ
  62.69291
  513.8236
@@ -6613,7 +6619,7 @@ endobj
 endobj
 % 'Outline.36.9': class OutlineEntryObject 
 386 0 obj
-<< /Dest [ 142 0 R
+<< /Dest [ 141 0 R
  /XYZ
  62.69291
  493.4236
@@ -6625,7 +6631,7 @@ endobj
 endobj
 % 'Outline.36.10': class OutlineEntryObject 
 387 0 obj
-<< /Dest [ 159 0 R
+<< /Dest [ 158 0 R
  /XYZ
  62.69291
  422.6236
@@ -6637,7 +6643,7 @@ endobj
 endobj
 % 'Outline.36.11': class OutlineEntryObject 
 388 0 obj
-<< /Dest [ 208 0 R
+<< /Dest [ 207 0 R
  /XYZ
  62.69291
  741.0236
@@ -6649,7 +6655,7 @@ endobj
 endobj
 % 'Outline.36.12': class OutlineEntryObject 
 389 0 obj
-<< /Dest [ 208 0 R
+<< /Dest [ 207 0 R
  /XYZ
  62.69291
  513.0236
@@ -6661,7 +6667,7 @@ endobj
 endobj
 % 'Outline.36.13': class OutlineEntryObject 
 390 0 obj
-<< /Dest [ 208 0 R
+<< /Dest [ 207 0 R
  /XYZ
  62.69291
  309.0236
@@ -6673,7 +6679,7 @@ endobj
 % 'Outline.1': class OutlineEntryObject 
 391 0 obj
 << /Count 19
- /Dest [ 214 0 R
+ /Dest [ 213 0 R
  /XYZ
  62.69291
  681.0236
@@ -6686,7 +6692,7 @@ endobj
 endobj
 % 'Outline.37.0': class OutlineEntryObject 
 392 0 obj
-<< /Dest [ 297 0 R
+<< /Dest [ 296 0 R
  /XYZ
  62.69291
  765.0236
@@ -6697,7 +6703,7 @@ endobj
 endobj
 % 'Outline.37.1': class OutlineEntryObject 
 393 0 obj
-<< /Dest [ 297 0 R
+<< /Dest [ 296 0 R
  /XYZ
  62.69291
  543.0236
@@ -6709,7 +6715,7 @@ endobj
 endobj
 % 'Outline.37.2': class OutlineEntryObject 
 394 0 obj
-<< /Dest [ 300 0 R
+<< /Dest [ 299 0 R
  /XYZ
  62.69291
  765.0236
@@ -6721,7 +6727,7 @@ endobj
 endobj
 % 'Outline.37.3': class OutlineEntryObject 
 395 0 obj
-<< /Dest [ 309 0 R
+<< /Dest [ 308 0 R
  /XYZ
  62.69291
  741.0236
@@ -6733,7 +6739,7 @@ endobj
 endobj
 % 'Outline.37.4': class OutlineEntryObject 
 396 0 obj
-<< /Dest [ 314 0 R
+<< /Dest [ 313 0 R
  /XYZ
  62.69291
  431.8485
@@ -6745,7 +6751,7 @@ endobj
 endobj
 % 'Outline.37.5': class OutlineEntryObject 
 397 0 obj
-<< /Dest [ 319 0 R
+<< /Dest [ 318 0 R
  /XYZ
  62.69291
  515.8236
@@ -6757,7 +6763,7 @@ endobj
 endobj
 % 'Outline.37.6': class OutlineEntryObject 
 398 0 obj
-<< /Dest [ 324 0 R
+<< /Dest [ 323 0 R
  /XYZ
  62.69291
  441.5042
@@ -6769,7 +6775,7 @@ endobj
 endobj
 % 'Outline.37.7': class OutlineEntryObject 
 399 0 obj
-<< /Dest [ 332 0 R
+<< /Dest [ 331 0 R
  /XYZ
  62.69291
  765.0236
@@ -6781,7 +6787,7 @@ endobj
 endobj
 % 'Outline.37.8': class OutlineEntryObject 
 400 0 obj
-<< /Dest [ 343 0 R
+<< /Dest [ 342 0 R
  /XYZ
  62.69291
  258.6236
@@ -6793,7 +6799,7 @@ endobj
 endobj
 % 'Outline.37.9': class OutlineEntryObject 
 401 0 obj
-<< /Dest [ 347 0 R
+<< /Dest [ 346 0 R
  /XYZ
  62.69291
  401.4236
@@ -6805,7 +6811,7 @@ endobj
 endobj
 % 'Outline.37.10': class OutlineEntryObject 
 402 0 obj
-<< /Dest [ 350 0 R
+<< /Dest [ 349 0 R
  /XYZ
  62.69291
  408.6236
@@ -6817,7 +6823,7 @@ endobj
 endobj
 % 'Outline.37.11': class OutlineEntryObject 
 403 0 obj
-<< /Dest [ 354 0 R
+<< /Dest [ 353 0 R
  /XYZ
  62.69291
  244.6236
@@ -6829,7 +6835,7 @@ endobj
 endobj
 % 'Outline.37.12': class OutlineEntryObject 
 404 0 obj
-<< /Dest [ 357 0 R
+<< /Dest [ 356 0 R
  /XYZ
  62.69291
  354.6236
@@ -6841,7 +6847,7 @@ endobj
 endobj
 % 'Outline.37.13': class OutlineEntryObject 
 405 0 obj
-<< /Dest [ 361 0 R
+<< /Dest [ 360 0 R
  /XYZ
  62.69291
  511.8236
@@ -6853,7 +6859,7 @@ endobj
 endobj
 % 'Outline.37.14': class OutlineEntryObject 
 406 0 obj
-<< /Dest [ 363 0 R
+<< /Dest [ 362 0 R
  /XYZ
  62.69291
  711.0236
@@ -6865,7 +6871,7 @@ endobj
 endobj
 % 'Outline.37.15': class OutlineEntryObject 
 407 0 obj
-<< /Dest [ 365 0 R
+<< /Dest [ 364 0 R
  /XYZ
  62.69291
  765.0236
@@ -6880,7 +6886,7 @@ endobj
 << /Dest [ 369 0 R
  /XYZ
  62.69291
- 729.0236
+ 630.4159
  0 ]
  /Next 409 0 R
  /Parent 391 0 R
@@ -6892,7 +6898,7 @@ endobj
 << /Dest [ 369 0 R
  /XYZ
  62.69291
- 258.6236
+ 160.0159
  0 ]
  /Next 410 0 R
  /Parent 391 0 R
@@ -6904,7 +6910,7 @@ endobj
 << /Dest [ 371 0 R
  /XYZ
  62.69291
- 586.6772
+ 508.6772
  0 ]
  /Parent 391 0 R
  /Prev 409 0 R
@@ -6914,48 +6920,48 @@ endobj
 411 0 obj
 % page tree
 << /Count 45
- /Kids [ 9 0 R
- 80 0 R
- 96 0 R
- 106 0 R
- 110 0 R
- 114 0 R
+ /Kids [ 8 0 R
+ 79 0 R
+ 95 0 R
+ 105 0 R
+ 109 0 R
+ 113 0 R
+ 119 0 R
  120 0 R
- 121 0 R
- 124 0 R
+ 123 0 R
+ 131 0 R
  132 0 R
- 133 0 R
- 137 0 R
- 140 0 R
- 142 0 R
- 145 0 R
- 159 0 R
- 174 0 R
- 208 0 R
- 214 0 R
- 285 0 R
- 297 0 R
+ 136 0 R
+ 139 0 R
+ 141 0 R
+ 144 0 R
+ 158 0 R
+ 173 0 R
+ 207 0 R
+ 213 0 R
+ 284 0 R
+ 296 0 R
+ 298 0 R
  299 0 R
- 300 0 R
- 309 0 R
- 314 0 R
- 319 0 R
+ 308 0 R
+ 313 0 R
+ 318 0 R
+ 322 0 R
  323 0 R
  324 0 R
- 325 0 R
- 332 0 R
- 343 0 R
- 345 0 R
+ 331 0 R
+ 342 0 R
+ 344 0 R
+ 346 0 R
  347 0 R
- 348 0 R
- 350 0 R
- 354 0 R
+ 349 0 R
+ 353 0 R
+ 356 0 R
  357 0 R
- 358 0 R
- 361 0 R
- 363 0 R
+ 360 0 R
+ 362 0 R
+ 364 0 R
  365 0 R
- 366 0 R
  369 0 R
  371 0 R
  372 0 R ]
@@ -6979,7 +6985,7 @@ Q
 q
 1 0 0 1 62.69291 717.0236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 3 cm
 q
@@ -7000,7 +7006,7 @@ Q
 q
 1 0 0 1 62.69291 702.0236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 3 cm
 q
@@ -7022,7 +7028,7 @@ Q
 q
 1 0 0 1 62.69291 687.0236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 3 cm
 q
@@ -7043,7 +7049,7 @@ Q
 q
 1 0 0 1 62.69291 660.0236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 3 cm
 q
@@ -7065,7 +7071,7 @@ Q
 q
 1 0 0 1 62.69291 645.0236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 3 cm
 q
@@ -7087,7 +7093,7 @@ Q
 q
 1 0 0 1 62.69291 630.0236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 3 cm
 q
@@ -7108,7 +7114,7 @@ Q
 q
 1 0 0 1 62.69291 615.0236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 3 cm
 q
@@ -7120,7 +7126,7 @@ q
 1 0 0 1 91.03937 3 cm
 q
 0 0 0 rg
-BT 1 0 0 1 0 5.71 Tm /F4 10 Tf 12 TL (easy_install -U plac) Tj T* ET
+BT 1 0 0 1 0 5.71 Tm /F3 10 Tf 12 TL (easy_install -U plac) Tj T* ET
 Q
 Q
 q
@@ -7129,7 +7135,7 @@ Q
 q
 1 0 0 1 62.69291 600.0236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 3 cm
 q
@@ -7173,7 +7179,7 @@ Q
 q
 1 0 0 1 62.69291 108.0236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 0 615 cm
 q
@@ -7723,7 +7729,7 @@ Q
 q
 1 0 0 1 62.69291 327.0236 cm
 q
-BT 1 0 0 1 0 52.82 Tm .352209 Tw 12 TL /F1 10 Tf 0 0 0 rg (Let me start with the simplest possible thing: a script that takes a single argument and does something to) Tj T* 0 Tw 1.053984 Tw (it. It cannot get simpler than that, unless you consider a script without command-line arguments, where) Tj T* 0 Tw .735488 Tw (there is nothing to parse. Still, it is a use case ) Tj /F5 10 Tf (extremely common) Tj /F1 10 Tf (: I need to write scripts like that nearly) Tj T* 0 Tw .486655 Tw (every day, I wrote hundreds of them in the last few years and I have never been happy. Here is a typical) Tj T* 0 Tw (example of code I have been writing by hand for years:) Tj T* ET
+BT 1 0 0 1 0 52.82 Tm .352209 Tw 12 TL /F1 10 Tf 0 0 0 rg (Let me start with the simplest possible thing: a script that takes a single argument and does something to) Tj T* 0 Tw 1.053984 Tw (it. It cannot get simpler than that, unless you consider a script without command-line arguments, where) Tj T* 0 Tw .735488 Tw (there is nothing to parse. Still, it is a use case ) Tj /F4 10 Tf (extremely common) Tj /F1 10 Tf (: I need to write scripts like that nearly) Tj T* 0 Tw .486655 Tw (every day, I wrote hundreds of them in the last few years and I have never been happy. Here is a typical) Tj T* 0 Tw (example of code I have been writing by hand for years:) Tj T* ET
 Q
 Q
 q
@@ -7741,7 +7747,7 @@ n -6 -6 468.6898 192 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 173.71 Tm /F4 10 Tf 12 TL (# example1.py) Tj T* (def main\(dsn\):) Tj T* (    "Do something with the database") Tj T* (    print\(dsn\)) Tj T* (    # ...) Tj T*  T* (if __name__ == '__main__':) Tj T* (    import sys) Tj T* (    n = len\(sys.argv[1:]\)) Tj T* (    if n == 0:) Tj T* (        sys.exit\('usage: python %s dsn' % sys.argv[0]\)) Tj T* (    elif n == 1:) Tj T* (        main\(sys.argv[1]\)) Tj T* (    else:) Tj T* (        sys.exit\('Unrecognized arguments: %s' % ' '.join\(sys.argv[2:]\)\)) Tj T* ET
+BT 1 0 0 1 0 173.71 Tm /F3 10 Tf 12 TL (# example1.py) Tj T* (def main\(dsn\):) Tj T* (    "Do something with the database") Tj T* (    print\(dsn\)) Tj T* (    # ...) Tj T*  T* (if __name__ == '__main__':) Tj T* (    import sys) Tj T* (    n = len\(sys.argv[1:]\)) Tj T* (    if n == 0:) Tj T* (        sys.exit\('usage: python %s dsn' % sys.argv[0]\)) Tj T* (    elif n == 1:) Tj T* (        main\(sys.argv[1]\)) Tj T* (    else:) Tj T* (        sys.exit\('Unrecognized arguments: %s' % ' '.join\(sys.argv[2:]\)\)) Tj T* ET
 Q
 Q
 Q
@@ -7750,7 +7756,7 @@ Q
 q
 1 0 0 1 62.69291 93.82362 cm
 q
-BT 1 0 0 1 0 16.82 Tm .880651 Tw 12 TL /F1 10 Tf 0 0 0 rg (As you see the whole ) Tj /F4 10 Tf (if __name__ == '__main__' ) Tj /F1 10 Tf (block \(nine lines\) is essentially boilerplate that ) Tj T* 0 Tw 1.972927 Tw (should not exist. Actually I think the language should recognize the main function and pass to it the) Tj T* 0 Tw ET
+BT 1 0 0 1 0 16.82 Tm .880651 Tw 12 TL /F1 10 Tf 0 0 0 rg (As you see the whole ) Tj /F3 10 Tf (if __name__ == '__main__' ) Tj /F1 10 Tf (block \(nine lines\) is essentially boilerplate that ) Tj T* 0 Tw 1.972927 Tw (should not exist. Actually I think the language should recognize the main function and pass to it the) Tj T* 0 Tw ET
 Q
 Q
 q
@@ -7773,7 +7779,7 @@ stream
 q
 1 0 0 1 62.69291 693.0236 cm
 q
-BT 1 0 0 1 0 64.82 Tm 3.309147 Tw 12 TL /F1 10 Tf 0 0 0 rg (command-line arguments automatically; unfortunaly this is unlikely to happen. I have been writing) Tj T* 0 Tw 1.767356 Tw (boilerplate like this in hundreds of scripts for years, and every time I ) Tj /F5 10 Tf (hate ) Tj /F1 10 Tf (it. The purpose of using a) Tj T* 0 Tw 1.47229 Tw (scripting language is convenience and trivial things should be trivial. Unfortunately the standard library) Tj T* 0 Tw .69881 Tw (does not help for this incredibly common use case. Using ) Tj 0 0 .501961 rg (getopt ) Tj 0 0 0 rg (and ) Tj 0 0 .501961 rg (optparse ) Tj 0 0 0 rg (does not help, since they) Tj T* 0 Tw .894104 Tw (are intended to manage options and not positional arguments; the ) Tj 0 0 .501961 rg (argparse ) Tj 0 0 0 rg (module helps a bit and it is) Tj T* 0 Tw (able to reduce the boilerplate from nine lines to six lines:) Tj T* ET
+BT 1 0 0 1 0 64.82 Tm 3.309147 Tw 12 TL /F1 10 Tf 0 0 0 rg (command-line arguments automatically; unfortunaly this is unlikely to happen. I have been writing) Tj T* 0 Tw 1.767356 Tw (boilerplate like this in hundreds of scripts for years, and every time I ) Tj /F4 10 Tf (hate ) Tj /F1 10 Tf (it. The purpose of using a) Tj T* 0 Tw 1.47229 Tw (scripting language is convenience and trivial things should be trivial. Unfortunately the standard library) Tj T* 0 Tw .69881 Tw (does not help for this incredibly common use case. Using ) Tj 0 0 .501961 rg (getopt ) Tj 0 0 0 rg (and ) Tj 0 0 .501961 rg (optparse ) Tj 0 0 0 rg (does not help, since they) Tj T* 0 Tw .894104 Tw (are intended to manage options and not positional arguments; the ) Tj 0 0 .501961 rg (argparse ) Tj 0 0 0 rg (module helps a bit and it is) Tj T* 0 Tw (able to reduce the boilerplate from nine lines to six lines:) Tj T* ET
 Q
 Q
 q
@@ -7791,7 +7797,7 @@ n -6 -6 468.6898 156 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 137.71 Tm /F4 10 Tf 12 TL (# example2.py) Tj T* (def main\(dsn\):) Tj T* (    "Do something on the database") Tj T* (    print\(dsn\)) Tj T* (    # ...) Tj T*  T* (if __name__ == '__main__':) Tj T* (    import argparse) Tj T* (    p = argparse.ArgumentParser\(\)) Tj T* (    p.add_argument\('dsn'\)) Tj T* (    arg = p.parse_args\(\)) Tj T* (    main\(arg.dsn\)) Tj T* ET
+BT 1 0 0 1 0 137.71 Tm /F3 10 Tf 12 TL (# example2.py) Tj T* (def main\(dsn\):) Tj T* (    "Do something on the database") Tj T* (    print\(dsn\)) Tj T* (    # ...) Tj T*  T* (if __name__ == '__main__':) Tj T* (    import argparse) Tj T* (    p = argparse.ArgumentParser\(\)) Tj T* (    p.add_argument\('dsn'\)) Tj T* (    arg = p.parse_args\(\)) Tj T* (    main\(arg.dsn\)) Tj T* ET
 Q
 Q
 Q
@@ -7825,7 +7831,7 @@ n -6 -6 468.6898 108 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 89.71 Tm /F4 10 Tf 12 TL (# example3.py) Tj T* (def main\(dsn\):) Tj T* (    "Do something with the database") Tj T* (    print\(dsn\)) Tj T* (    # ...) Tj T* ( ) Tj T* (if __name__ == '__main__':) Tj T* (    import plac; plac.call\(main\)) Tj T* ET
+BT 1 0 0 1 0 89.71 Tm /F3 10 Tf 12 TL (# example3.py) Tj T* (def main\(dsn\):) Tj T* (    "Do something with the database") Tj T* (    print\(dsn\)) Tj T* (    # ...) Tj T* ( ) Tj T* (if __name__ == '__main__':) Tj T* (    import plac; plac.call\(main\)) Tj T* ET
 Q
 Q
 Q
@@ -7852,7 +7858,7 @@ n -6 -6 468.6898 24 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 5.71 Tm /F4 10 Tf 12 TL ($ python example3.py -h) Tj T* ET
+BT 1 0 0 1 0 5.71 Tm /F3 10 Tf 12 TL ($ python example3.py -h) Tj T* ET
 Q
 Q
 Q
@@ -7873,7 +7879,7 @@ n -6 -6 468.6898 120 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 101.71 Tm /F4 10 Tf 12 TL (usage: example3.py [-h] dsn) Tj T*  T* (Do something with the database) Tj T*  T* (positional arguments:) Tj T* (  dsn) Tj T*  T* (optional arguments:) Tj T* (  -h, --help  show this help message and exit) Tj T* ET
+BT 1 0 0 1 0 101.71 Tm /F3 10 Tf 12 TL (usage: example3.py [-h] dsn) Tj T*  T* (Do something with the database) Tj T*  T* (positional arguments:) Tj T* (  dsn) Tj T*  T* (optional arguments:) Tj T* (  -h, --help  show this help message and exit) Tj T* ET
 Q
 Q
 Q
@@ -7929,7 +7935,7 @@ q
 n -6 -6 468.6898 192 re B*
 Q
 q
-BT 1 0 0 1 0 173.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (# example4.py) Tj T* (from datetime import datetime) Tj T*  T* (def main\(dsn, table='product', today=datetime.today\(\)\):) Tj T* (    "Do something on the database") Tj T* (    print\(dsn, table, today\)) Tj T*  T* (if __name__ == '__main__':) Tj T* (    import sys) Tj T* (    args = sys.argv[1:]) Tj T* (    if not args:) Tj T* (        sys.exit\('usage: python %s dsn' % sys.argv[0]\)) Tj T* (    elif len\(args\) ) Tj (>) Tj ( 2:) Tj T* (        sys.exit\('Unrecognized arguments: %s' % ' '.join\(argv[2:]\)\)) Tj T* (    main\(*args\)) Tj T* ET
+BT 1 0 0 1 0 173.71 Tm 12 TL /F3 10 Tf 0 0 0 rg (# example4.py) Tj T* (from datetime import datetime) Tj T*  T* (def main\(dsn, table='product', today=datetime.today\(\)\):) Tj T* (    "Do something on the database") Tj T* (    print\(dsn, table, today\)) Tj T*  T* (if __name__ == '__main__':) Tj T* (    import sys) Tj T* (    args = sys.argv[1:]) Tj T* (    if not args:) Tj T* (        sys.exit\('usage: python %s dsn' % sys.argv[0]\)) Tj T* (    elif len\(args\) ) Tj (>) Tj ( 2:) Tj T* (        sys.exit\('Unrecognized arguments: %s' % ' '.join\(argv[2:]\)\)) Tj T* (    main\(*args\)) Tj T* ET
 Q
 Q
 Q
@@ -7938,7 +7944,7 @@ Q
 q
 1 0 0 1 62.69291 447.8236 cm
 q
-BT 1 0 0 1 0 52.82 Tm .038488 Tw 12 TL /F1 10 Tf 0 0 0 rg (Here I want to perform a query on a database table, by extracting the most recent data: it makes sense for) Tj T* 0 Tw .299988 Tw /F4 10 Tf (today ) Tj /F1 10 Tf (to be a default argument. If there is a most used table \(in this example a table called ) Tj /F4 10 Tf ('product') Tj /F1 10 Tf (\)) Tj T* 0 Tw 3.313984 Tw (it also makes sense to make it a default argument. Performing the parsing of the command-line) Tj T* 0 Tw .083735 Tw (arguments by hand takes 8 ugly lines of boilerplate \(using ) Tj 0 0 .501961 rg (argparse ) Tj 0 0 0 rg (would require about the same number) Tj T* 0 Tw (of lines\). With ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (the entire ) Tj /F4 10 Tf (__main__ ) Tj /F1 10 Tf (block reduces to the usual two lines:) Tj T* ET
+BT 1 0 0 1 0 52.82 Tm .038488 Tw 12 TL /F1 10 Tf 0 0 0 rg (Here I want to perform a query on a database table, by extracting the most recent data: it makes sense for) Tj T* 0 Tw .299988 Tw /F3 10 Tf (today ) Tj /F1 10 Tf (to be a default argument. If there is a most used table \(in this example a table called ) Tj /F3 10 Tf ('product') Tj /F1 10 Tf (\)) Tj T* 0 Tw 3.313984 Tw (it also makes sense to make it a default argument. Performing the parsing of the command-line) Tj T* 0 Tw .083735 Tw (arguments by hand takes 8 ugly lines of boilerplate \(using ) Tj 0 0 .501961 rg (argparse ) Tj 0 0 0 rg (would require about the same number) Tj T* 0 Tw (of lines\). With ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (the entire ) Tj /F3 10 Tf (__main__ ) Tj /F1 10 Tf (block reduces to the usual two lines:) Tj T* ET
 Q
 Q
 q
@@ -7956,7 +7962,7 @@ n -6 -6 468.6898 36 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 17.71 Tm /F4 10 Tf 12 TL (if __name__ == '__main__':) Tj T* (    import plac; plac.call\(main\)) Tj T* ET
+BT 1 0 0 1 0 17.71 Tm /F3 10 Tf 12 TL (if __name__ == '__main__':) Tj T* (    import plac; plac.call\(main\)) Tj T* ET
 Q
 Q
 Q
@@ -7984,7 +7990,7 @@ n -6 -6 468.6898 144 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 125.71 Tm /F4 10 Tf 12 TL (usage: example5.py [-h] dsn [table] [today]) Tj T*  T* (Do something on the database) Tj T*  T* (positional arguments:) Tj T* (  dsn) Tj T* (  table) Tj T* (  today) Tj T*  T* (optional arguments:) Tj T* (  -h, --help  show this help message and exit) Tj T* ET
+BT 1 0 0 1 0 125.71 Tm /F3 10 Tf 12 TL (usage: example5.py [-h] dsn [table] [today]) Tj T*  T* (Do something on the database) Tj T*  T* (positional arguments:) Tj T* (  dsn) Tj T* (  table) Tj T* (  today) Tj T*  T* (optional arguments:) Tj T* (  -h, --help  show this help message and exit) Tj T* ET
 Q
 Q
 Q
@@ -8011,7 +8017,7 @@ n -6 -6 468.6898 96 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 77.71 Tm /F4 10 Tf 12 TL (# example7.py) Tj T* (from datetime import datetime) Tj T*  T* (def main\(dsn, *scripts\):) Tj T* (    "Run the given scripts on the database") Tj T* (    for script in scripts:) Tj T* (        print\('executing %s' % script\)) Tj T* ET
+BT 1 0 0 1 0 77.71 Tm /F3 10 Tf 12 TL (# example7.py) Tj T* (from datetime import datetime) Tj T*  T* (def main\(dsn, *scripts\):) Tj T* (    "Run the given scripts on the database") Tj T* (    for script in scripts:) Tj T* (        print\('executing %s' % script\)) Tj T* ET
 Q
 Q
 Q
@@ -8049,7 +8055,7 @@ n -6 -6 468.6898 60 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 41.71 Tm /F4 10 Tf 12 TL (        # ...) Tj T*  T* (if __name__ == '__main__':) Tj T* (    import plac; plac.call\(main\)) Tj T* ET
+BT 1 0 0 1 0 41.71 Tm /F3 10 Tf 12 TL (        # ...) Tj T*  T* (if __name__ == '__main__':) Tj T* (    import plac; plac.call\(main\)) Tj T* ET
 Q
 Q
 Q
@@ -8077,7 +8083,7 @@ n -6 -6 468.6898 132 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 113.71 Tm /F4 10 Tf 12 TL (usage: example7.py [-h] dsn [scripts [scripts ...]]) Tj T*  T* (Run the given scripts on the database) Tj T*  T* (positional arguments:) Tj T* (  dsn) Tj T* (  scripts) Tj T*  T* (optional arguments:) Tj T* (  -h, --help  show this help message and exit) Tj T* ET
+BT 1 0 0 1 0 113.71 Tm /F3 10 Tf 12 TL (usage: example7.py [-h] dsn [scripts [scripts ...]]) Tj T*  T* (Run the given scripts on the database) Tj T*  T* (positional arguments:) Tj T* (  dsn) Tj T* (  scripts) Tj T*  T* (optional arguments:) Tj T* (  -h, --help  show this help message and exit) Tj T* ET
 Q
 Q
 Q
@@ -8086,19 +8092,19 @@ Q
 q
 1 0 0 1 62.69291 498.6236 cm
 q
-BT 1 0 0 1 0 28.82 Tm .952485 Tw 12 TL /F1 10 Tf 0 0 0 rg (The examples here should have made clear that ) Tj /F5 10 Tf (plac is able to figure out the command-line arguments) Tj T* 0 Tw .899988 Tw (parser to use from the signature of the main function) Tj /F1 10 Tf (. This is the whole idea behind ) Tj 0 0 .501961 rg (plac) Tj 0 0 0 rg (: if the intent is) Tj T* 0 Tw (clear, let's the machine take care of the details.) Tj T* ET
+BT 1 0 0 1 0 28.82 Tm .952485 Tw 12 TL /F1 10 Tf 0 0 0 rg (The examples here should have made clear that ) Tj /F4 10 Tf (plac is able to figure out the command-line arguments) Tj T* 0 Tw .899988 Tw (parser to use from the signature of the main function) Tj /F1 10 Tf (. This is the whole idea behind ) Tj 0 0 .501961 rg (plac) Tj 0 0 0 rg (: if the intent is) Tj T* 0 Tw (clear, let's the machine take care of the details.) Tj T* ET
 Q
 Q
 q
 1 0 0 1 62.69291 456.6236 cm
 q
-BT 1 0 0 1 0 28.82 Tm 3.036235 Tw 12 TL /F1 10 Tf 0 0 .501961 rg (plac ) Tj 0 0 0 rg (is inspired to an old Python Cookbook recipe \() Tj 0 0 .501961 rg (optionparse) Tj 0 0 0 rg (\), in the sense that it delivers the) Tj T* 0 Tw .847209 Tw (programmer from the burden of writing the parser, but is less of a hack: instead of extracting the parser) Tj T* 0 Tw (from the docstring of the module, it extracts it from the signature of the ) Tj /F4 10 Tf (main ) Tj /F1 10 Tf (function.) Tj T* ET
+BT 1 0 0 1 0 28.82 Tm 3.036235 Tw 12 TL /F1 10 Tf 0 0 .501961 rg (plac ) Tj 0 0 0 rg (is inspired to an old Python Cookbook recipe \() Tj 0 0 .501961 rg (optionparse) Tj 0 0 0 rg (\), in the sense that it delivers the) Tj T* 0 Tw .847209 Tw (programmer from the burden of writing the parser, but is less of a hack: instead of extracting the parser) Tj T* 0 Tw (from the docstring of the module, it extracts it from the signature of the ) Tj /F3 10 Tf (main ) Tj /F1 10 Tf (function.) Tj T* ET
 Q
 Q
 q
 1 0 0 1 62.69291 426.6236 cm
 q
-BT 1 0 0 1 0 16.82 Tm .319987 Tw 12 TL /F1 10 Tf 0 0 0 rg (The idea comes from the ) Tj /F5 10 Tf (function annotations ) Tj /F1 10 Tf (concept, a new feature of Python 3. An example is worth a) Tj T* 0 Tw (thousand words, so here it is:) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm .319987 Tw 12 TL /F1 10 Tf 0 0 0 rg (The idea comes from the ) Tj /F4 10 Tf (function annotations ) Tj /F1 10 Tf (concept, a new feature of Python 3. An example is worth a) Tj T* 0 Tw (thousand words, so here it is:) Tj T* ET
 Q
 Q
 q
@@ -8116,7 +8122,7 @@ n -6 -6 468.6898 144 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 125.71 Tm /F4 10 Tf 12 TL (# example7_.py) Tj T* (from datetime import datetime) Tj T*  T* (def main\(dsn: "Database dsn", *scripts: "SQL scripts"\):) Tj T* (    "Run the given scripts on the database") Tj T* (    for script in scripts:) Tj T* (        print\('executing %s' % script\)) Tj T* (        # ...) Tj T*  T* (if __name__ == '__main__':) Tj T* (    import plac; plac.call\(main\)) Tj T* ET
+BT 1 0 0 1 0 125.71 Tm /F3 10 Tf 12 TL (# example7_.py) Tj T* (from datetime import datetime) Tj T*  T* (def main\(dsn: "Database dsn", *scripts: "SQL scripts"\):) Tj T* (    "Run the given scripts on the database") Tj T* (    for script in scripts:) Tj T* (        print\('executing %s' % script\)) Tj T* (        # ...) Tj T*  T* (if __name__ == '__main__':) Tj T* (    import plac; plac.call\(main\)) Tj T* ET
 Q
 Q
 Q
@@ -8125,7 +8131,7 @@ Q
 q
 1 0 0 1 62.69291 241.4236 cm
 q
-BT 1 0 0 1 0 16.82 Tm .17528 Tw 12 TL /F1 10 Tf 0 0 0 rg (Here the arguments of the ) Tj /F4 10 Tf (main ) Tj /F1 10 Tf (function have been annotated with strings which are intented to be used) Tj T* 0 Tw (in the help message:) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm .17528 Tw 12 TL /F1 10 Tf 0 0 0 rg (Here the arguments of the ) Tj /F3 10 Tf (main ) Tj /F1 10 Tf (function have been annotated with strings which are intented to be used) Tj T* 0 Tw (in the help message:) Tj T* ET
 Q
 Q
 q
@@ -8143,7 +8149,7 @@ n -6 -6 468.6898 132 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 113.71 Tm /F4 10 Tf 12 TL (usage: example7_.py [-h] dsn [scripts [scripts ...]]) Tj T*  T* (Run the given scripts on the database) Tj T*  T* (positional arguments:) Tj T* (  dsn         Database dsn) Tj T* (  scripts     SQL scripts) Tj T*  T* (optional arguments:) Tj T* (  -h, --help  show this help message and exit) Tj T* ET
+BT 1 0 0 1 0 113.71 Tm /F3 10 Tf 12 TL (usage: example7_.py [-h] dsn [scripts [scripts ...]]) Tj T*  T* (Run the given scripts on the database) Tj T*  T* (positional arguments:) Tj T* (  dsn         Database dsn) Tj T* (  scripts     SQL scripts) Tj T*  T* (optional arguments:) Tj T* (  -h, --help  show this help message and exit) Tj T* ET
 Q
 Q
 Q
@@ -8199,7 +8205,7 @@ n -6 -6 468.6898 108 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 89.71 Tm /F4 10 Tf 12 TL (# example8.py) Tj T* (def main\(command: \("SQL query", 'option', 'c'\), dsn\):) Tj T* (    if command:) Tj T* (        print\('executing %s on %s' % \(command, dsn\)\)) Tj T* (        # ...) Tj T*  T* (if __name__ == '__main__':) Tj T* (    import plac; plac.call\(main\)) Tj T* ET
+BT 1 0 0 1 0 89.71 Tm /F3 10 Tf 12 TL (# example8.py) Tj T* (def main\(command: \("SQL query", 'option', 'c'\), dsn\):) Tj T* (    if command:) Tj T* (        print\('executing %s on %s' % \(command, dsn\)\)) Tj T* (        # ...) Tj T*  T* (if __name__ == '__main__':) Tj T* (    import plac; plac.call\(main\)) Tj T* ET
 Q
 Q
 Q
@@ -8208,7 +8214,7 @@ Q
 q
 1 0 0 1 62.69291 459.8236 cm
 q
-BT 1 0 0 1 0 40.82 Tm .929213 Tw 12 TL /F1 10 Tf 0 0 0 rg (Here the argument ) Tj /F4 10 Tf (command ) Tj /F1 10 Tf (has been annotated with the tuple ) Tj /F4 10 Tf (\("SQL query", 'option', 'c'\)) Tj /F1 10 Tf (:) Tj T* 0 Tw .62683 Tw (the first string is the help string which will appear in the usage message, the second string tells ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (that) Tj T* 0 Tw .931894 Tw /F4 10 Tf (command ) Tj /F1 10 Tf (is an option and the third string that there is also a short form of the option ) Tj /F4 10 Tf (-c) Tj /F1 10 Tf (, the long form) Tj T* 0 Tw (being ) Tj /F4 10 Tf (--command) Tj /F1 10 Tf (. The usage message is the following:) Tj T* ET
+BT 1 0 0 1 0 40.82 Tm .929213 Tw 12 TL /F1 10 Tf 0 0 0 rg (Here the argument ) Tj /F3 10 Tf (command ) Tj /F1 10 Tf (has been annotated with the tuple ) Tj /F3 10 Tf (\("SQL query", 'option', 'c'\)) Tj /F1 10 Tf (:) Tj T* 0 Tw .62683 Tw (the first string is the help string which will appear in the usage message, the second string tells ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (that) Tj T* 0 Tw .931894 Tw /F3 10 Tf (command ) Tj /F1 10 Tf (is an option and the third string that there is also a short form of the option ) Tj /F3 10 Tf (-c) Tj /F1 10 Tf (, the long form) Tj T* 0 Tw (being ) Tj /F3 10 Tf (--command) Tj /F1 10 Tf (. The usage message is the following:) Tj T* ET
 Q
 Q
 q
@@ -8226,7 +8232,7 @@ n -6 -6 468.6898 120 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 101.71 Tm /F4 10 Tf 12 TL (usage: example8.py [-h] [-c COMMAND] dsn) Tj T*  T* (positional arguments:) Tj T* (  dsn) Tj T*  T* (optional arguments:) Tj T* (  -h, --help            show this help message and exit) Tj T* (  -c COMMAND, --command COMMAND) Tj T* (                        SQL query) Tj T* ET
+BT 1 0 0 1 0 101.71 Tm /F3 10 Tf 12 TL (usage: example8.py [-h] [-c COMMAND] dsn) Tj T*  T* (positional arguments:) Tj T* (  dsn) Tj T*  T* (optional arguments:) Tj T* (  -h, --help            show this help message and exit) Tj T* (  -c COMMAND, --command COMMAND) Tj T* (                        SQL query) Tj T* ET
 Q
 Q
 Q
@@ -8254,7 +8260,7 @@ n -6 -6 468.6898 72 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 53.71 Tm /F4 10 Tf 12 TL ($ python3 example8.py -c"select * from table" dsn) Tj T* (executing select * from table on dsn) Tj T*  T* ($ python3 example8.py --command="select * from table" dsn) Tj T* (executing select * from table on dsn) Tj T* ET
+BT 1 0 0 1 0 53.71 Tm /F3 10 Tf 12 TL ($ python3 example8.py -c"select * from table" dsn) Tj T* (executing select * from table on dsn) Tj T*  T* ($ python3 example8.py --command="select * from table" dsn) Tj T* (executing select * from table on dsn) Tj T* ET
 Q
 Q
 Q
@@ -8263,7 +8269,7 @@ Q
 q
 1 0 0 1 62.69291 173.4236 cm
 q
-BT 1 0 0 1 0 40.82 Tm .268935 Tw 12 TL /F1 10 Tf 0 0 0 rg (The third argument in the function annotation can be omitted: in such case it will be assumed to be ) Tj /F4 10 Tf (None) Tj /F1 10 Tf (.) Tj T* 0 Tw 2.839213 Tw (The consequence is that the usual dichotomy between long and short options \(GNU-style options\)) Tj T* 0 Tw .396235 Tw (disappears: we get ) Tj /F5 10 Tf (smart options) Tj /F1 10 Tf (, which have the single character prefix of short options and behave like) Tj T* 0 Tw (both long and short options, since they can be abbreviated. Here is an example featuring smart options:) Tj T* ET
+BT 1 0 0 1 0 40.82 Tm .268935 Tw 12 TL /F1 10 Tf 0 0 0 rg (The third argument in the function annotation can be omitted: in such case it will be assumed to be ) Tj /F3 10 Tf (None) Tj /F1 10 Tf (.) Tj T* 0 Tw 2.839213 Tw (The consequence is that the usual dichotomy between long and short options \(GNU-style options\)) Tj T* 0 Tw .396235 Tw (disappears: we get ) Tj /F4 10 Tf (smart options) Tj /F1 10 Tf (, which have the single character prefix of short options and behave like) Tj T* 0 Tw (both long and short options, since they can be abbreviated. Here is an example featuring smart options:) Tj T* ET
 Q
 Q
 q
@@ -8281,7 +8287,7 @@ n -6 -6 468.6898 72 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 53.71 Tm /F4 10 Tf 12 TL (# example6.py) Tj T* (def main\(dsn, command: \("SQL query", 'option'\)\):) Tj T* (    print\('executing %r on %s' % \(command, dsn\)\)) Tj T*  T* (if __name__ == '__main__':) Tj T* ET
+BT 1 0 0 1 0 53.71 Tm /F3 10 Tf 12 TL (# example6.py) Tj T* (def main\(dsn, command: \("SQL query", 'option'\)\):) Tj T* (    print\('executing %r on %s' % \(command, dsn\)\)) Tj T*  T* (if __name__ == '__main__':) Tj T* ET
 Q
 Q
 Q
@@ -8319,7 +8325,7 @@ n -6 -6 468.6898 24 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 5.71 Tm /F4 10 Tf 12 TL (    import plac; plac.call\(main\)) Tj T* ET
+BT 1 0 0 1 0 5.71 Tm /F3 10 Tf 12 TL (    import plac; plac.call\(main\)) Tj T* ET
 Q
 Q
 Q
@@ -8340,7 +8346,7 @@ n -6 -6 468.6898 108 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 89.71 Tm /F4 10 Tf 12 TL (usage: example6.py [-h] [-command COMMAND] dsn) Tj T*  T* (positional arguments:) Tj T* (  dsn) Tj T*  T* (optional arguments:) Tj T* (  -h, --help        show this help message and exit) Tj T* (  -command COMMAND  SQL query) Tj T* ET
+BT 1 0 0 1 0 89.71 Tm /F3 10 Tf 12 TL (usage: example6.py [-h] [-command COMMAND] dsn) Tj T*  T* (positional arguments:) Tj T* (  dsn) Tj T*  T* (optional arguments:) Tj T* (  -h, --help        show this help message and exit) Tj T* (  -command COMMAND  SQL query) Tj T* ET
 Q
 Q
 Q
@@ -8368,7 +8374,7 @@ n -6 -6 468.6898 84 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 65.71 Tm /F4 10 Tf 12 TL ($ python3 example6.py -c "select" dsn) Tj T* (executing 'select' on dsn) Tj T* ($ python3 example6.py -com "select" dsn) Tj T* (executing 'select' on dsn) Tj T* ($ python3 example6.py -command="select" dsn) Tj T* (executing 'select' on dsn) Tj T* ET
+BT 1 0 0 1 0 65.71 Tm /F3 10 Tf 12 TL ($ python3 example6.py -c "select" dsn) Tj T* (executing 'select' on dsn) Tj T* ($ python3 example6.py -com "select" dsn) Tj T* (executing 'select' on dsn) Tj T* ($ python3 example6.py -command="select" dsn) Tj T* (executing 'select' on dsn) Tj T* ET
 Q
 Q
 Q
@@ -8377,7 +8383,7 @@ Q
 q
 1 0 0 1 62.69291 489.4236 cm
 q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (Notice that the form ) Tj /F4 10 Tf (-command=SQL ) Tj /F1 10 Tf (is recognized only for the full option, not for its abbreviations:) Tj T* ET
+BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (Notice that the form ) Tj /F3 10 Tf (-command=SQL ) Tj /F1 10 Tf (is recognized only for the full option, not for its abbreviations:) Tj T* ET
 Q
 Q
 q
@@ -8395,7 +8401,7 @@ n -6 -6 468.6898 48 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 29.71 Tm /F4 10 Tf 12 TL ($ python3 example6.py -com="select" dsn) Tj T* (usage: example6.py [-h] [-command COMMAND] dsn) Tj T* (example6.py: error: unrecognized arguments: -com=select) Tj T* ET
+BT 1 0 0 1 0 29.71 Tm /F3 10 Tf 12 TL ($ python3 example6.py -com="select" dsn) Tj T* (usage: example6.py [-h] [-command COMMAND] dsn) Tj T* (example6.py: error: unrecognized arguments: -com=select) Tj T* ET
 Q
 Q
 Q
@@ -8404,7 +8410,7 @@ Q
 q
 1 0 0 1 62.69291 400.2236 cm
 q
-BT 1 0 0 1 0 16.82 Tm 1.724987 Tw 12 TL /F1 10 Tf 0 0 0 rg (If the option is not passed, the variable ) Tj /F4 10 Tf (command ) Tj /F1 10 Tf (will get the value ) Tj /F4 10 Tf (None) Tj /F1 10 Tf (. However, it is possible to) Tj T* 0 Tw (specify a non-trivial default. Here is an example:) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm 1.724987 Tw 12 TL /F1 10 Tf 0 0 0 rg (If the option is not passed, the variable ) Tj /F3 10 Tf (command ) Tj /F1 10 Tf (will get the value ) Tj /F3 10 Tf (None) Tj /F1 10 Tf (. However, it is possible to) Tj T* 0 Tw (specify a non-trivial default. Here is an example:) Tj T* ET
 Q
 Q
 q
@@ -8422,7 +8428,7 @@ n -6 -6 468.6898 84 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 65.71 Tm /F4 10 Tf 12 TL (# example8_.py) Tj T* (def main\(dsn, command: \("SQL query", 'option'\)='select * from table'\):) Tj T* (    print\('executing %r on %s' % \(command, dsn\)\)) Tj T*  T* (if __name__ == '__main__':) Tj T* (    import plac; plac.call\(main\)) Tj T* ET
+BT 1 0 0 1 0 65.71 Tm /F3 10 Tf 12 TL (# example8_.py) Tj T* (def main\(dsn, command: \("SQL query", 'option'\)='select * from table'\):) Tj T* (    print\('executing %r on %s' % \(command, dsn\)\)) Tj T*  T* (if __name__ == '__main__':) Tj T* (    import plac; plac.call\(main\)) Tj T* ET
 Q
 Q
 Q
@@ -8450,7 +8456,7 @@ n -6 -6 468.6898 120 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 101.71 Tm /F4 10 Tf 12 TL (usage: example8_.py [-h] [-command select * from table] dsn) Tj T*  T* (positional arguments:) Tj T* (  dsn) Tj T*  T* (optional arguments:) Tj T* (  -h, --help            show this help message and exit) Tj T* (  -command select * from table) Tj T* (                        SQL query) Tj T* ET
+BT 1 0 0 1 0 101.71 Tm /F3 10 Tf 12 TL (usage: example8_.py [-h] [-command select * from table] dsn) Tj T*  T* (positional arguments:) Tj T* (  dsn) Tj T*  T* (optional arguments:) Tj T* (  -h, --help            show this help message and exit) Tj T* (  -command select * from table) Tj T* (                        SQL query) Tj T* ET
 Q
 Q
 Q
@@ -8459,7 +8465,7 @@ Q
 q
 1 0 0 1 62.69291 137.8236 cm
 q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (When you run the script and you do not pass the ) Tj /F4 10 Tf (-command ) Tj /F1 10 Tf (option, the default query will be executed:) Tj T* ET
+BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (When you run the script and you do not pass the ) Tj /F3 10 Tf (-command ) Tj /F1 10 Tf (option, the default query will be executed:) Tj T* ET
 Q
 Q
 q
@@ -8477,7 +8483,7 @@ n -6 -6 468.6898 36 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 17.71 Tm /F4 10 Tf 12 TL ($ python3 example8_.py dsn) Tj T* (executing 'select * from table' on dsn) Tj T* ET
+BT 1 0 0 1 0 17.71 Tm /F3 10 Tf 12 TL ($ python3 example8_.py dsn) Tj T* (executing 'select * from table' on dsn) Tj T* ET
 Q
 Q
 Q
@@ -8509,7 +8515,7 @@ Q
 q
 1 0 0 1 62.69291 717.0236 cm
 q
-BT 1 0 0 1 0 16.82 Tm .815542 Tw 12 TL /F1 10 Tf 0 0 .501961 rg (plac ) Tj 0 0 0 rg (is able to recognize flags, i.e. boolean options which are ) Tj /F4 10 Tf (True ) Tj /F1 10 Tf (if they are passed to the command) Tj T* 0 Tw (line and ) Tj /F4 10 Tf (False ) Tj /F1 10 Tf (if they are absent. Here is an example:) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm .815542 Tw 12 TL /F1 10 Tf 0 0 .501961 rg (plac ) Tj 0 0 0 rg (is able to recognize flags, i.e. boolean options which are ) Tj /F3 10 Tf (True ) Tj /F1 10 Tf (if they are passed to the command) Tj T* 0 Tw (line and ) Tj /F3 10 Tf (False ) Tj /F1 10 Tf (if they are absent. Here is an example:) Tj T* ET
 Q
 Q
 q
@@ -8527,7 +8533,7 @@ n -6 -6 486 120 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 101.71 Tm /F4 10 Tf 12 TL (# example9.py) Tj T*  T* (def main\(verbose: \('prints more info', 'flag', 'v'\), dsn: 'connection string'\):) Tj T* (    if verbose:) Tj T* (        print\('connecting to %s' % dsn\)) Tj T* (    # ...) Tj T*  T* (if __name__ == '__main__':) Tj T* (    import plac; plac.call\(main\)) Tj T* ET
+BT 1 0 0 1 0 101.71 Tm /F3 10 Tf 12 TL (# example9.py) Tj T*  T* (def main\(verbose: \('prints more info', 'flag', 'v'\), dsn: 'connection string'\):) Tj T* (    if verbose:) Tj T* (        print\('connecting to %s' % dsn\)) Tj T* (    # ...) Tj T*  T* (if __name__ == '__main__':) Tj T* (    import plac; plac.call\(main\)) Tj T* ET
 Q
 Q
 Q
@@ -8548,7 +8554,7 @@ n -6 -6 468.6898 108 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 89.71 Tm /F4 10 Tf 12 TL (usage: example9.py [-h] [-v] dsn) Tj T*  T* (positional arguments:) Tj T* (  dsn            connection string) Tj T*  T* (optional arguments:) Tj T* (  -h, --help     show this help message and exit) Tj T* (  -v, --verbose  prints more info) Tj T* ET
+BT 1 0 0 1 0 89.71 Tm /F3 10 Tf 12 TL (usage: example9.py [-h] [-v] dsn) Tj T*  T* (positional arguments:) Tj T* (  dsn            connection string) Tj T*  T* (optional arguments:) Tj T* (  -h, --help     show this help message and exit) Tj T* (  -v, --verbose  prints more info) Tj T* ET
 Q
 Q
 Q
@@ -8569,7 +8575,7 @@ n -6 -6 468.6898 36 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 17.71 Tm /F4 10 Tf 12 TL ($ python3 example9.py -v dsn) Tj T* (connecting to dsn) Tj T* ET
+BT 1 0 0 1 0 17.71 Tm /F3 10 Tf 12 TL ($ python3 example9.py -v dsn) Tj T* (connecting to dsn) Tj T* ET
 Q
 Q
 Q
@@ -8578,19 +8584,19 @@ Q
 q
 1 0 0 1 62.69291 385.7299 cm
 q
-BT 1 0 0 1 0 28.82 Tm .31408 Tw 12 TL /F1 10 Tf 0 0 0 rg (Notice that it is an error trying to specify a default for flags: the default value for a flag is always ) Tj /F4 10 Tf (False) Tj /F1 10 Tf (. If) Tj T* 0 Tw 2.652485 Tw (you feel the need to implement non-boolean flags, you should use an option with two choices, as) Tj T* 0 Tw (explained in the "more features" section.) Tj T* ET
+BT 1 0 0 1 0 28.82 Tm .31408 Tw 12 TL /F1 10 Tf 0 0 0 rg (Notice that it is an error trying to specify a default for flags: the default value for a flag is always ) Tj /F3 10 Tf (False) Tj /F1 10 Tf (. If) Tj T* 0 Tw 2.652485 Tw (you feel the need to implement non-boolean flags, you should use an option with two choices, as) Tj T* 0 Tw (explained in the "more features" section.) Tj T* ET
 Q
 Q
 q
 1 0 0 1 62.69291 319.7299 cm
 q
-BT 1 0 0 1 0 52.82 Tm 5.832651 Tw 12 TL /F1 10 Tf 0 0 0 rg (For consistency with the way the usage message is printed, I suggest you to follow the) Tj T* 0 Tw 1.895433 Tw (Flag-Option-Required-Default \(FORD\) convention: in the ) Tj /F4 10 Tf (main ) Tj /F1 10 Tf (function write first the flag arguments,) Tj T* 0 Tw .881235 Tw (then the option arguments, then the required arguments and finally the default arguments. This is just a) Tj T* 0 Tw .110574 Tw (convention and you are not forced to use it, except for the default arguments \(including the varargs\) which) Tj T* 0 Tw (must stay at the end as it is required by the Python syntax.) Tj T* ET
+BT 1 0 0 1 0 52.82 Tm 5.832651 Tw 12 TL /F1 10 Tf 0 0 0 rg (For consistency with the way the usage message is printed, I suggest you to follow the) Tj T* 0 Tw 1.895433 Tw (Flag-Option-Required-Default \(FORD\) convention: in the ) Tj /F3 10 Tf (main ) Tj /F1 10 Tf (function write first the flag arguments,) Tj T* 0 Tw .881235 Tw (then the option arguments, then the required arguments and finally the default arguments. This is just a) Tj T* 0 Tw .110574 Tw (convention and you are not forced to use it, except for the default arguments \(including the varargs\) which) Tj T* 0 Tw (must stay at the end as it is required by the Python syntax.) Tj T* ET
 Q
 Q
 q
 1 0 0 1 62.69291 277.7299 cm
 q
-BT 1 0 0 1 0 28.82 Tm .897045 Tw 12 TL /F1 10 Tf 0 0 0 rg (I also suggests to specify a one-character abbreviation for flags: in this way you can use the GNU-style) Tj T* 0 Tw 2.034431 Tw (composition of flags \(i.e. ) Tj /F4 10 Tf (-zxvf ) Tj /F1 10 Tf (is an abbreviation of ) Tj /F4 10 Tf (-z -x -v -f) Tj /F1 10 Tf (\). I usually do not provide the) Tj T* 0 Tw (one-character abbreviation for options, since it does not make sense to compose them.) Tj T* ET
+BT 1 0 0 1 0 28.82 Tm .897045 Tw 12 TL /F1 10 Tf 0 0 0 rg (I also suggests to specify a one-character abbreviation for flags: in this way you can use the GNU-style) Tj T* 0 Tw 2.034431 Tw (composition of flags \(i.e. ) Tj /F3 10 Tf (-zxvf ) Tj /F1 10 Tf (is an abbreviation of ) Tj /F3 10 Tf (-z -x -v -f) Tj /F1 10 Tf (\). I usually do not provide the) Tj T* 0 Tw (one-character abbreviation for options, since it does not make sense to compose them.) Tj T* ET
 Q
 Q
 q
@@ -8620,7 +8626,7 @@ n -6 -6 468.6898 36 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 17.71 Tm /F4 10 Tf 12 TL (def main\(dsn: "Database dsn", *scripts: "SQL scripts"\):) Tj T* (    ...) Tj T* ET
+BT 1 0 0 1 0 17.71 Tm /F3 10 Tf 12 TL (def main\(dsn: "Database dsn", *scripts: "SQL scripts"\):) Tj T* (    ...) Tj T* ET
 Q
 Q
 Q
@@ -8647,7 +8653,7 @@ endobj
 % 'R421': class PDFStream 
 421 0 obj
 % page stream
-<< /Length 5845 >>
+<< /Length 6172 >>
 stream
 1 0 0 1 0 0 cm BT /F1 12 Tf 14.4 TL ET
 q
@@ -8665,7 +8671,7 @@ n -6 -6 468.6898 72 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 53.71 Tm /F4 10 Tf 12 TL (def main\(dsn, *scripts\):) Tj T* (    ...) Tj T* (main.__annotations__ = dict\() Tj T* (    dsn="Database dsn",) Tj T* (    scripts="SQL scripts"\)) Tj T* ET
+BT 1 0 0 1 0 53.71 Tm /F3 10 Tf 12 TL (def main\(dsn, *scripts\):) Tj T* (    ...) Tj T* (main.__annotations__ = dict\() Tj T* (    dsn="Database dsn",) Tj T* (    scripts="SQL scripts"\)) Tj T* ET
 Q
 Q
 Q
@@ -8674,7 +8680,7 @@ Q
 q
 1 0 0 1 62.69291 647.8236 cm
 q
-BT 1 0 0 1 0 28.82 Tm .536098 Tw 12 TL /F1 10 Tf 0 0 0 rg (One should be careful to match the keys of the annotation dictionary with the names of the arguments in) Tj T* 0 Tw 3.347485 Tw (the annotated function; for lazy people with Python 2.4 available the simplest way is to use the) Tj T* 0 Tw /F4 10 Tf (plac.annotations ) Tj /F1 10 Tf (decorator that performs the check for you:) Tj T* ET
+BT 1 0 0 1 0 28.82 Tm .536098 Tw 12 TL /F1 10 Tf 0 0 0 rg (One should be careful to match the keys of the annotation dictionary with the names of the arguments in) Tj T* 0 Tw 3.347485 Tw (the annotated function; for lazy people with Python 2.4 available the simplest way is to use the) Tj T* 0 Tw /F3 10 Tf (plac.annotations ) Tj /F1 10 Tf (decorator that performs the check for you:) Tj T* ET
 Q
 Q
 q
@@ -8692,7 +8698,7 @@ n -6 -6 468.6898 72 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 53.71 Tm /F4 10 Tf 12 TL (@plac.annotations\() Tj T* (    dsn="Database dsn",) Tj T* (    scripts="SQL scripts"\)) Tj T* (def main\(dsn, *scripts\):) Tj T* (    ...) Tj T* ET
+BT 1 0 0 1 0 53.71 Tm /F3 10 Tf 12 TL (@plac.annotations\() Tj T* (    dsn="Database dsn",) Tj T* (    scripts="SQL scripts"\)) Tj T* (def main\(dsn, *scripts\):) Tj T* (    ...) Tj T* ET
 Q
 Q
 Q
@@ -8701,7 +8707,7 @@ Q
 q
 1 0 0 1 62.69291 534.6236 cm
 q
-BT 1 0 0 1 0 16.82 Tm 1.846077 Tw 12 TL /F1 10 Tf 0 0 0 rg (In the rest of this article I will assume that you are using Python 2.X with X >) Tj (= 4 and I will use the) Tj T* 0 Tw /F4 10 Tf (plac.annotations ) Tj /F1 10 Tf (decorator. Notice however that the core features of ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (run even on Python 2.3.) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm 1.846077 Tw 12 TL /F1 10 Tf 0 0 0 rg (In the rest of this article I will assume that you are using Python 2.X with X >) Tj (= 4 and I will use the) Tj T* 0 Tw /F3 10 Tf (plac.annotations ) Tj /F1 10 Tf (decorator. Notice however that the core features of ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (run even on Python 2.3.) Tj T* ET
 Q
 Q
 q
@@ -8713,7 +8719,7 @@ Q
 q
 1 0 0 1 62.69291 450.6236 cm
 q
-BT 1 0 0 1 0 40.82 Tm 1.483488 Tw 12 TL /F1 10 Tf 0 0 0 rg (One of the goals of ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (is to have a learning curve of ) Tj /F5 10 Tf (minutes ) Tj /F1 10 Tf (for its core features, compared to the) Tj T* 0 Tw 1.152093 Tw (learning curve of ) Tj /F5 10 Tf (hours ) Tj /F1 10 Tf (of ) Tj 0 0 .501961 rg (argparse) Tj 0 0 0 rg (. In order to reach this goal, I have ) Tj /F5 10 Tf (not ) Tj /F1 10 Tf (sacrificed all the features of) Tj T* 0 Tw 2.89936 Tw 0 0 .501961 rg (argparse) Tj 0 0 0 rg (. Actually a lot of ) Tj 0 0 .501961 rg (argparse ) Tj 0 0 0 rg (power persists in ) Tj 0 0 .501961 rg (plac) Tj 0 0 0 rg (. Until now, I have only showed simple) Tj T* 0 Tw (annotations, but in general an annotation is a 6-tuple of the form) Tj T* ET
+BT 1 0 0 1 0 40.82 Tm 1.483488 Tw 12 TL /F1 10 Tf 0 0 0 rg (One of the goals of ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (is to have a learning curve of ) Tj /F4 10 Tf (minutes ) Tj /F1 10 Tf (for its core features, compared to the) Tj T* 0 Tw 1.152093 Tw (learning curve of ) Tj /F4 10 Tf (hours ) Tj /F1 10 Tf (of ) Tj 0 0 .501961 rg (argparse) Tj 0 0 0 rg (. In order to reach this goal, I have ) Tj /F4 10 Tf (not ) Tj /F1 10 Tf (sacrificed all the features of) Tj T* 0 Tw 2.89936 Tw 0 0 .501961 rg (argparse) Tj 0 0 0 rg (. Actually a lot of ) Tj 0 0 .501961 rg (argparse ) Tj 0 0 0 rg (power persists in ) Tj 0 0 .501961 rg (plac) Tj 0 0 0 rg (. Until now, I have only showed simple) Tj T* 0 Tw (annotations, but in general an annotation is a 6-tuple of the form) Tj T* ET
 Q
 Q
 q
@@ -8722,13 +8728,13 @@ Q
 q
 1 0 0 1 62.69291 432.6236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 BT 1 0 0 1 0 2 Tm  T* ET
 q
 1 0 0 1 20 0 cm
 q
 0 0 0 rg
-BT 1 0 0 1 0 5.71 Tm /F4 10 Tf 12 TL (\(help, kind, abbrev, type, choices, metavar\)) Tj T* ET
+BT 1 0 0 1 0 5.71 Tm /F3 10 Tf 12 TL (\(help, kind, abbrev, type, choices, metavar\)) Tj T* ET
 Q
 Q
 q
@@ -8740,35 +8746,35 @@ Q
 q
 1 0 0 1 62.69291 390.6236 cm
 q
-BT 1 0 0 1 0 28.82 Tm 1.068735 Tw 12 TL /F1 10 Tf 0 0 0 rg (where ) Tj /F4 10 Tf (help ) Tj /F1 10 Tf (is the help message, ) Tj /F4 10 Tf (kind ) Tj /F1 10 Tf (is a string in the set { ) Tj /F4 10 Tf ("flag") Tj /F1 10 Tf (, ) Tj /F4 10 Tf ("option") Tj /F1 10 Tf (, ) Tj /F4 10 Tf ("positional") Tj /F1 10 Tf (},) Tj T* 0 Tw 1.579431 Tw /F4 10 Tf (abbrev ) Tj /F1 10 Tf (is a one-character string or ) Tj /F4 10 Tf (None) Tj /F1 10 Tf (, ) Tj /F4 10 Tf (type ) Tj /F1 10 Tf (is a callable taking a string in input, ) Tj /F4 10 Tf (choices ) Tj /F1 10 Tf (is a) Tj T* 0 Tw (discrete sequence of values and ) Tj /F4 10 Tf (metavar ) Tj /F1 10 Tf (is a string.) Tj T* ET
+BT 1 0 0 1 0 28.82 Tm 1.068735 Tw 12 TL /F1 10 Tf 0 0 0 rg (where ) Tj /F3 10 Tf (help ) Tj /F1 10 Tf (is the help message, ) Tj /F3 10 Tf (kind ) Tj /F1 10 Tf (is a string in the set { ) Tj /F3 10 Tf ("flag") Tj /F1 10 Tf (, ) Tj /F3 10 Tf ("option") Tj /F1 10 Tf (, ) Tj /F3 10 Tf ("positional") Tj /F1 10 Tf (},) Tj T* 0 Tw 1.579431 Tw /F3 10 Tf (abbrev ) Tj /F1 10 Tf (is a one-character string or ) Tj /F3 10 Tf (None) Tj /F1 10 Tf (, ) Tj /F3 10 Tf (type ) Tj /F1 10 Tf (is a callable taking a string in input, ) Tj /F3 10 Tf (choices ) Tj /F1 10 Tf (is a) Tj T* 0 Tw (discrete sequence of values and ) Tj /F3 10 Tf (metavar ) Tj /F1 10 Tf (is a string.) Tj T* ET
 Q
 Q
 q
 1 0 0 1 62.69291 360.6236 cm
 q
-BT 1 0 0 1 0 16.82 Tm 1.05061 Tw 12 TL /F4 10 Tf 0 0 0 rg (type ) Tj /F1 10 Tf (is used to automagically convert the command line arguments from the string type to any Python) Tj T* 0 Tw (type; by default there is no conversion and ) Tj /F4 10 Tf (type=None) Tj /F1 10 Tf (.) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm 1.05061 Tw 12 TL /F3 10 Tf 0 0 0 rg (type ) Tj /F1 10 Tf (is used to automagically convert the command line arguments from the string type to any Python) Tj T* 0 Tw (type; by default there is no conversion and ) Tj /F3 10 Tf (type=None) Tj /F1 10 Tf (.) Tj T* ET
 Q
 Q
 q
 1 0 0 1 62.69291 330.6236 cm
 q
-BT 1 0 0 1 0 16.82 Tm 2.904692 Tw 12 TL /F4 10 Tf 0 0 0 rg (choices ) Tj /F1 10 Tf (is used to restrict the number of the valid options; by default there is no restriction i.e.) Tj T* 0 Tw /F4 10 Tf (choices=None) Tj /F1 10 Tf (.) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm 2.904692 Tw 12 TL /F3 10 Tf 0 0 0 rg (choices ) Tj /F1 10 Tf (is used to restrict the number of the valid options; by default there is no restriction i.e.) Tj T* 0 Tw /F3 10 Tf (choices=None) Tj /F1 10 Tf (.) Tj T* ET
 Q
 Q
 q
-1 0 0 1 62.69291 288.6236 cm
+1 0 0 1 62.69291 252.6236 cm
 q
-BT 1 0 0 1 0 28.82 Tm 1.071751 Tw 12 TL /F4 10 Tf 0 0 0 rg (metavar ) Tj /F1 10 Tf (is used to change the argument name in the usage message \(and only there\); by default the) Tj T* 0 Tw 1.056654 Tw (metavar is ) Tj /F4 10 Tf (None) Tj /F1 10 Tf (: this means that the name in the usage message is the same as the argument name,) Tj T* 0 Tw (unless the argument has a default and in such a case is equal to the stringified form of the default.) Tj T* ET
+BT 1 0 0 1 0 64.82 Tm 1.171163 Tw 12 TL /F3 10 Tf 0 0 0 rg (metavar ) Tj /F1 10 Tf (has two meanings. For a positional argument it is used to change the argument name in the) Tj T* 0 Tw .352209 Tw (usage message \(and only there\). By default the metavar is ) Tj /F3 10 Tf (None ) Tj /F1 10 Tf (and the name in the usage message is) Tj T* 0 Tw .752339 Tw (the same as the argument name. For an option the ) Tj /F3 10 Tf (metavar ) Tj /F1 10 Tf (is used differently in the usage message,) Tj T* 0 Tw .802927 Tw (which has now the form ) Tj /F3 10 Tf ([--option-name METAVAR]) Tj /F1 10 Tf (. If the ) Tj /F3 10 Tf (metavar ) Tj /F1 10 Tf (is ) Tj /F3 10 Tf (None) Tj /F1 10 Tf (, then it is equal to the) Tj T* 0 Tw .50683 Tw (uppercased name of the argument, unless the argument has a default and in such a case is equal to the) Tj T* 0 Tw (stringified form of the default.) Tj T* ET
 Q
 Q
 q
-1 0 0 1 62.69291 270.6236 cm
+1 0 0 1 62.69291 234.6236 cm
 q
 BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (Here is an example showing many of the features \(copied from the ) Tj 0 0 .501961 rg (argparse ) Tj 0 0 0 rg (documentation\):) Tj T* ET
 Q
 Q
 q
-1 0 0 1 62.69291 97.40054 cm
+1 0 0 1 62.69291 96.55439 cm
 q
 q
 .976496 0 0 .976496 0 0 cm
@@ -8778,11 +8784,11 @@ q
 .662745 .662745 .662745 RG
 .5 w
 .960784 .960784 .862745 rg
-n -6 -6 480 168 re B*
+n -6 -6 480 132 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 149.71 Tm /F4 10 Tf 12 TL (# example10.py) Tj T* (import plac) Tj T*  T* (@plac.annotations\() Tj T* (operator=\("The name of an operator", 'positional', None, str, ['add', 'mul']\),) Tj T* (numbers=\("A number", 'positional', None, float, None, "n"\)\)) Tj T* (def main\(operator, *numbers\):) Tj T* (    "A script to add and multiply numbers") Tj T* (    if operator == 'mul':) Tj T* (        op = float.__mul__) Tj T* (        result = 1.0) Tj T* (    else: # operator == 'add') Tj T* (        op = float.__add__) Tj T* ET
+BT 1 0 0 1 0 113.71 Tm /F3 10 Tf 12 TL (# example10.py) Tj T* (import plac) Tj T*  T* (@plac.annotations\() Tj T* (operator=\("The name of an operator", 'positional', None, str, ['add', 'mul']\),) Tj T* (numbers=\("A number", 'positional', None, float, None, "n"\)\)) Tj T* (def main\(operator, *numbers\):) Tj T* (    "A script to add and multiply numbers") Tj T* (    if operator == 'mul':) Tj T* (        op = float.__mul__) Tj T* ET
 Q
 Q
 Q
@@ -8802,11 +8808,11 @@ endobj
 % 'R422': class PDFStream 
 422 0 obj
 % page stream
-<< /Length 4152 >>
+<< /Length 4255 >>
 stream
 1 0 0 1 0 0 cm BT /F1 12 Tf 14.4 TL ET
 q
-1 0 0 1 62.69291 667.8236 cm
+1 0 0 1 62.69291 631.8236 cm
 q
 q
 1 0 0 1 0 0 cm
@@ -8816,25 +8822,25 @@ q
 .662745 .662745 .662745 RG
 .5 w
 .960784 .960784 .862745 rg
-n -6 -6 468.6898 96 re B*
+n -6 -6 468.6898 132 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 77.71 Tm /F4 10 Tf 12 TL (        result = 0.0) Tj T* (    for n in numbers:) Tj T* (        result = op\(result, n\)) Tj T* (    return result) Tj T*  T* (if __name__ == '__main__':) Tj T* (    print\(plac.call\(main\)\)) Tj T* ET
+BT 1 0 0 1 0 113.71 Tm /F3 10 Tf 12 TL (        result = 1.0) Tj T* (    else: # operator == 'add') Tj T* (        op = float.__add__) Tj T* (        result = 0.0) Tj T* (    for n in numbers:) Tj T* (        result = op\(result, n\)) Tj T* (    return result) Tj T*  T* (if __name__ == '__main__':) Tj T* (    print\(plac.call\(main\)\)) Tj T* ET
 Q
 Q
 Q
 Q
 Q
 q
-1 0 0 1 62.69291 647.8236 cm
+1 0 0 1 62.69291 611.8236 cm
 q
 0 0 0 rg
 BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL (Here is the usage:) Tj T* ET
 Q
 Q
 q
-1 0 0 1 62.69291 506.6236 cm
+1 0 0 1 62.69291 470.6236 cm
 q
 q
 1 0 0 1 0 0 cm
@@ -8848,20 +8854,20 @@ n -6 -6 468.6898 132 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 113.71 Tm /F4 10 Tf 12 TL (usage: example10.py [-h] {add,mul} [n [n ...]]) Tj T*  T* (A script to add and multiply numbers) Tj T*  T* (positional arguments:) Tj T* (  {add,mul}   The name of an operator) Tj T* (  n           A number) Tj T*  T* (optional arguments:) Tj T* (  -h, --help  show this help message and exit) Tj T* ET
+BT 1 0 0 1 0 113.71 Tm /F3 10 Tf 12 TL (usage: example10.py [-h] {add,mul} [n [n ...]]) Tj T*  T* (A script to add and multiply numbers) Tj T*  T* (positional arguments:) Tj T* (  {add,mul}   The name of an operator) Tj T* (  n           A number) Tj T*  T* (optional arguments:) Tj T* (  -h, --help  show this help message and exit) Tj T* ET
 Q
 Q
 Q
 Q
 Q
 q
-1 0 0 1 62.69291 474.6236 cm
+1 0 0 1 62.69291 438.6236 cm
 q
-BT 1 0 0 1 0 16.82 Tm .15186 Tw 12 TL /F1 10 Tf 0 0 0 rg (Notice that the docstring of the ) Tj /F4 10 Tf (main ) Tj /F1 10 Tf (function has been automatically added to the usage message. Here) Tj T* 0 Tw (are a couple of examples of use:) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm .15186 Tw 12 TL /F1 10 Tf 0 0 0 rg (Notice that the docstring of the ) Tj /F3 10 Tf (main ) Tj /F1 10 Tf (function has been automatically added to the usage message. Here) Tj T* 0 Tw (are a couple of examples of use:) Tj T* ET
 Q
 Q
 q
-1 0 0 1 62.69291 381.2849 cm
+1 0 0 1 62.69291 345.2849 cm
 q
 q
 .87797 0 0 .87797 0 0 cm
@@ -8875,20 +8881,20 @@ n -6 -6 534 96 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 77.71 Tm /F4 10 Tf 12 TL ($ python example10.py add 1 2 3 4) Tj T* (10.0) Tj T* ($ python example10.py mul 1 2 3 4) Tj T* (24.0) Tj T* ($ python example10.py ad 1 2 3 4 # a mispelling error) Tj T* (usage: example10.py [-h] {add,mul} [n [n ...]]) Tj T* (example10.py: error: argument operator: invalid choice: 'ad' \(choose from 'add', 'mul'\)) Tj T* ET
+BT 1 0 0 1 0 77.71 Tm /F3 10 Tf 12 TL ($ python example10.py add 1 2 3 4) Tj T* (10.0) Tj T* ($ python example10.py mul 1 2 3 4) Tj T* (24.0) Tj T* ($ python example10.py ad 1 2 3 4 # a mispelling error) Tj T* (usage: example10.py [-h] {add,mul} [n [n ...]]) Tj T* (example10.py: error: argument operator: invalid choice: 'ad' \(choose from 'add', 'mul'\)) Tj T* ET
 Q
 Q
 Q
 Q
 Q
 q
-1 0 0 1 62.69291 361.2849 cm
+1 0 0 1 62.69291 325.2849 cm
 q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F4 10 Tf 0 0 0 rg (plac.call ) Tj /F1 10 Tf (can also be used in doctests like this:) Tj T* ET
+BT 1 0 0 1 0 4.82 Tm 12 TL /F3 10 Tf 0 0 0 rg (plac.call ) Tj /F1 10 Tf (can also be used in doctests like this:) Tj T* ET
 Q
 Q
 q
-1 0 0 1 62.69291 304.0849 cm
+1 0 0 1 62.69291 268.0849 cm
 q
 q
 1 0 0 1 0 0 cm
@@ -8901,20 +8907,20 @@ q
 n -6 -6 468.6898 48 re B*
 Q
 q
-BT 1 0 0 1 0 29.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (>) Tj (>) Tj (>) Tj ( import plac, example10) Tj T* (>) Tj (>) Tj (>) Tj ( plac.call\(example10.main, ['add', '1', '2']\)) Tj T* (3.0) Tj T* ET
+BT 1 0 0 1 0 29.71 Tm 12 TL /F3 10 Tf 0 0 0 rg (>) Tj (>) Tj (>) Tj ( import plac, example10) Tj T* (>) Tj (>) Tj (>) Tj ( plac.call\(example10.main, ['add', '1', '2']\)) Tj T* (3.0) Tj T* ET
 Q
 Q
 Q
 Q
 Q
 q
-1 0 0 1 62.69291 284.0849 cm
+1 0 0 1 62.69291 248.0849 cm
 q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F4 10 Tf 0 0 0 rg (plac.call ) Tj /F1 10 Tf (works for generators too:) Tj T* ET
+BT 1 0 0 1 0 4.82 Tm 12 TL /F3 10 Tf 0 0 0 rg (plac.call ) Tj /F1 10 Tf (works for generators too:) Tj T* ET
 Q
 Q
 q
-1 0 0 1 62.69291 202.8849 cm
+1 0 0 1 62.69291 166.8849 cm
 q
 q
 1 0 0 1 0 0 cm
@@ -8927,22 +8933,22 @@ q
 n -6 -6 468.6898 72 re B*
 Q
 q
-BT 1 0 0 1 0 53.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (>) Tj (>) Tj (>) Tj ( def main\(n\):) Tj T* (...     for i in range\(int\(n\)\):) Tj T* (...         yield i) Tj T* (>) Tj (>) Tj (>) Tj ( plac.call\(main, ['3']\)) Tj T* ([0, 1, 2]) Tj T* ET
+BT 1 0 0 1 0 53.71 Tm 12 TL /F3 10 Tf 0 0 0 rg (>) Tj (>) Tj (>) Tj ( def main\(n\):) Tj T* (...     for i in range\(int\(n\)\):) Tj T* (...         yield i) Tj T* (>) Tj (>) Tj (>) Tj ( plac.call\(main, ['3']\)) Tj T* ([0, 1, 2]) Tj T* ET
 Q
 Q
 Q
 Q
 Q
 q
-1 0 0 1 62.69291 158.8849 cm
+1 0 0 1 62.69291 122.8849 cm
 q
-BT 1 0 0 1 0 28.82 Tm .158409 Tw 12 TL /F1 10 Tf 0 0 0 rg (Internally ) Tj /F4 10 Tf (plac.call ) Tj /F1 10 Tf (tries to convert the output of the main function into a list, if possible. If the output is) Tj T* 0 Tw .725703 Tw (not iterable or it is a string, it is left unchanged, but if it is iterable it is converted. In particular, generator) Tj T* 0 Tw (objects are exhausted by ) Tj /F4 10 Tf (plac.call) Tj /F1 10 Tf (.) Tj T* ET
+BT 1 0 0 1 0 28.82 Tm .158409 Tw 12 TL /F1 10 Tf 0 0 0 rg (Internally ) Tj /F3 10 Tf (plac.call ) Tj /F1 10 Tf (tries to convert the output of the main function into a list, if possible. If the output is) Tj T* 0 Tw .725703 Tw (not iterable or it is a string, it is left unchanged, but if it is iterable it is converted. In particular, generator) Tj T* 0 Tw (objects are exhausted by ) Tj /F3 10 Tf (plac.call) Tj /F1 10 Tf (.) Tj T* ET
 Q
 Q
 q
-1 0 0 1 62.69291 128.8849 cm
+1 0 0 1 62.69291 92.8849 cm
 q
-BT 1 0 0 1 0 16.82 Tm 1.450751 Tw 12 TL /F1 10 Tf 0 0 0 rg (This behavior avoids mistakes like forgetting of applying ) Tj /F4 10 Tf (list\(result\) ) Tj /F1 10 Tf (to the result of ) Tj /F4 10 Tf (plac.call) Tj /F1 10 Tf (;) Tj T* 0 Tw (moreover it makes errors visible early, and avoids mistakes in code like the following:) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm 1.450751 Tw 12 TL /F1 10 Tf 0 0 0 rg (This behavior avoids mistakes like forgetting of applying ) Tj /F3 10 Tf (list\(result\) ) Tj /F1 10 Tf (to the result of ) Tj /F3 10 Tf (plac.call) Tj /F1 10 Tf (;) Tj T* 0 Tw (moreover it makes errors visible early, and avoids mistakes in code like the following:) Tj T* ET
 Q
 Q
 q
@@ -8977,7 +8983,7 @@ n -6 -6 468.6898 60 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 41.71 Tm /F4 10 Tf 12 TL (try:) Tj T* (    result = plac.call\(main, args\)) Tj T* (except:) Tj T* (   # do something) Tj T* ET
+BT 1 0 0 1 0 41.71 Tm /F3 10 Tf 12 TL (try:) Tj T* (    result = plac.call\(main, args\)) Tj T* (except:) Tj T* (   # do something) Tj T* ET
 Q
 Q
 Q
@@ -8993,7 +8999,7 @@ Q
 q
 1 0 0 1 62.69291 641.8236 cm
 q
-BT 1 0 0 1 0 16.82 Tm .647262 Tw 12 TL /F1 10 Tf 0 0 0 rg (If you are a fan of lazyness, you can still have it by setting the ) Tj /F4 10 Tf (eager ) Tj /F1 10 Tf (flag to ) Tj /F4 10 Tf (False) Tj /F1 10 Tf (, as in the following) Tj T* 0 Tw (example:) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm .647262 Tw 12 TL /F1 10 Tf 0 0 0 rg (If you are a fan of lazyness, you can still have it by setting the ) Tj /F3 10 Tf (eager ) Tj /F1 10 Tf (flag to ) Tj /F3 10 Tf (False) Tj /F1 10 Tf (, as in the following) Tj T* 0 Tw (example:) Tj T* ET
 Q
 Q
 q
@@ -9011,7 +9017,7 @@ n -6 -6 468.6898 36 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 17.71 Tm /F4 10 Tf 12 TL (for line in plac.call\(main, args, eager=False\):) Tj T* (    print\(line\)) Tj T* ET
+BT 1 0 0 1 0 17.71 Tm /F3 10 Tf 12 TL (for line in plac.call\(main, args, eager=False\):) Tj T* (    print\(line\)) Tj T* ET
 Q
 Q
 Q
@@ -9020,7 +9026,7 @@ Q
 q
 1 0 0 1 62.69291 564.6236 cm
 q
-BT 1 0 0 1 0 16.82 Tm 1.35528 Tw 12 TL /F1 10 Tf 0 0 0 rg (If ) Tj /F4 10 Tf (main ) Tj /F1 10 Tf (returns a generator object this example will print each line as soon as available, whereas the) Tj T* 0 Tw (default behaviour is to print all the lines together and the end of the computation.) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm 1.35528 Tw 12 TL /F1 10 Tf 0 0 0 rg (If ) Tj /F3 10 Tf (main ) Tj /F1 10 Tf (returns a generator object this example will print each line as soon as available, whereas the) Tj T* 0 Tw (default behaviour is to print all the lines together and the end of the computation.) Tj T* ET
 Q
 Q
 q
@@ -9032,7 +9038,7 @@ Q
 q
 1 0 0 1 62.69291 492.6236 cm
 q
-BT 1 0 0 1 0 28.82 Tm 1.234488 Tw 12 TL /F1 10 Tf 0 0 0 rg (Here is a more realistic script using most of the features of ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (to run SQL queries on a database by) Tj T* 0 Tw .930697 Tw (relying on ) Tj 0 0 .501961 rg (SQLAlchemy) Tj 0 0 0 rg (. Notice the usage of the ) Tj /F4 10 Tf (type ) Tj /F1 10 Tf (feature to automagically convert a SQLAlchemy) Tj T* 0 Tw (connection string into a ) Tj 0 0 .501961 rg (SqlSoup ) Tj 0 0 0 rg (object:) Tj T* ET
+BT 1 0 0 1 0 28.82 Tm 1.234488 Tw 12 TL /F1 10 Tf 0 0 0 rg (Here is a more realistic script using most of the features of ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (to run SQL queries on a database by) Tj T* 0 Tw .930697 Tw (relying on ) Tj 0 0 .501961 rg (SQLAlchemy) Tj 0 0 0 rg (. Notice the usage of the ) Tj /F3 10 Tf (type ) Tj /F1 10 Tf (feature to automagically convert a SQLAlchemy) Tj T* 0 Tw (connection string into a ) Tj 0 0 .501961 rg (SqlSoup ) Tj 0 0 0 rg (object:) Tj T* ET
 Q
 Q
 q
@@ -9050,7 +9056,7 @@ n -6 -6 468.6898 360 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 341.71 Tm /F4 10 Tf 12 TL (# dbcli.py) Tj T* (import plac) Tj T* (from sqlalchemy.ext.sqlsoup import SqlSoup) Tj T*  T* (@plac.annotations\() Tj T* (    db=\("Connection string", 'positional', None, SqlSoup\),) Tj T* (    header=\("Header", 'flag', 'H'\),) Tj T* (    sqlcmd=\("SQL command", 'option', 'c', str, None, "SQL"\),) Tj T* (    delimiter=\("Column separator", 'option', 'd'\),) Tj T* (    scripts="SQL scripts",) Tj T* (    \)) Tj T* (def main\(db, header, sqlcmd, delimiter="|", *scripts\):) Tj T* (    "A script to run queries and SQL scripts on a database") Tj T* (    yield 'Working on %s' % db.bind.url) Tj T*  T* (    if sqlcmd:) Tj T* (        result = db.bind.execute\(sqlcmd\)) Tj T* (        if header: # print the header) Tj T* (            yield delimiter.join\(result.keys\(\)\)) Tj T* (        for row in result: # print the rows) Tj T* (            yield delimiter.join\(map\(str, row\)\)) Tj T*  T* (    for script in scripts:) Tj T* (        db.bind.execute\(file\(script\).read\(\)\)) Tj T* (        yield 'executed %s' % script) Tj T*  T* (if __name__ == '__main__':) Tj T* (    for output in plac.call\(main\):) Tj T* (        print\(output\)) Tj T* ET
+BT 1 0 0 1 0 341.71 Tm /F3 10 Tf 12 TL (# dbcli.py) Tj T* (import plac) Tj T* (from sqlalchemy.ext.sqlsoup import SqlSoup) Tj T*  T* (@plac.annotations\() Tj T* (    db=\("Connection string", 'positional', None, SqlSoup\),) Tj T* (    header=\("Header", 'flag', 'H'\),) Tj T* (    sqlcmd=\("SQL command", 'option', 'c', str, None, "SQL"\),) Tj T* (    delimiter=\("Column separator", 'option', 'd'\),) Tj T* (    scripts="SQL scripts",) Tj T* (    \)) Tj T* (def main\(db, header, sqlcmd, delimiter="|", *scripts\):) Tj T* (    "A script to run queries and SQL scripts on a database") Tj T* (    yield 'Working on %s' % db.bind.url) Tj T*  T* (    if sqlcmd:) Tj T* (        result = db.bind.execute\(sqlcmd\)) Tj T* (        if header: # print the header) Tj T* (            yield delimiter.join\(result.keys\(\)\)) Tj T* (        for row in result: # print the rows) Tj T* (            yield delimiter.join\(map\(str, row\)\)) Tj T*  T* (    for script in scripts:) Tj T* (        db.bind.execute\(file\(script\).read\(\)\)) Tj T* (        yield 'executed %s' % script) Tj T*  T* (if __name__ == '__main__':) Tj T* (    for output in plac.call\(main\):) Tj T* (        print\(output\)) Tj T* ET
 Q
 Q
 Q
@@ -9059,7 +9065,7 @@ Q
 q
 1 0 0 1 62.69291 91.42362 cm
 q
-BT 1 0 0 1 0 16.82 Tm .049987 Tw 12 TL /F1 10 Tf 0 0 0 rg (You can see the ) Tj /F5 10 Tf (yield-is-print ) Tj /F1 10 Tf (pattern here: instead of using ) Tj /F4 10 Tf (print ) Tj /F1 10 Tf (in the main function, I use ) Tj /F4 10 Tf (yield) Tj /F1 10 Tf (, and ) Tj T* 0 Tw 3.55061 Tw (I perform the print in the ) Tj /F4 10 Tf (__main__ ) Tj /F1 10 Tf (block. The advantage of the pattern is that tests invoking) Tj T* 0 Tw ET
+BT 1 0 0 1 0 16.82 Tm .049987 Tw 12 TL /F1 10 Tf 0 0 0 rg (You can see the ) Tj /F4 10 Tf (yield-is-print ) Tj /F1 10 Tf (pattern here: instead of using ) Tj /F3 10 Tf (print ) Tj /F1 10 Tf (in the main function, I use ) Tj /F3 10 Tf (yield) Tj /F1 10 Tf (, and ) Tj T* 0 Tw 3.55061 Tw (I perform the print in the ) Tj /F3 10 Tf (__main__ ) Tj /F1 10 Tf (block. The advantage of the pattern is that tests invoking) Tj T* 0 Tw ET
 Q
 Q
 q
@@ -9082,7 +9088,7 @@ stream
 q
 1 0 0 1 62.69291 741.0236 cm
 q
-BT 1 0 0 1 0 16.82 Tm .52936 Tw 12 TL /F4 10 Tf 0 0 0 rg (plac.call ) Tj /F1 10 Tf (and checking the result become trivial: had I performed the printing in the main function, the) Tj T* 0 Tw (test would have involved an ugly hack like redirecting ) Tj /F4 10 Tf (sys.stdout ) Tj /F1 10 Tf (to a ) Tj /F4 10 Tf (StringIO ) Tj /F1 10 Tf (object.) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm .52936 Tw 12 TL /F3 10 Tf 0 0 0 rg (plac.call ) Tj /F1 10 Tf (and checking the result become trivial: had I performed the printing in the main function, the) Tj T* 0 Tw (test would have involved an ugly hack like redirecting ) Tj /F3 10 Tf (sys.stdout ) Tj /F1 10 Tf (to a ) Tj /F3 10 Tf (StringIO ) Tj /F1 10 Tf (object.) Tj T* ET
 Q
 Q
 q
@@ -9107,7 +9113,7 @@ n -6 -6 468.6898 168 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 149.71 Tm /F4 10 Tf 12 TL (usage: dbcli.py [-h] [-H] [-c SQL] [-d |] db [scripts [scripts ...]]) Tj T*  T* (A script to run queries and SQL scripts on a database) Tj T*  T* (positional arguments:) Tj T* (  db                    Connection string) Tj T* (  scripts               SQL scripts) Tj T*  T* (optional arguments:) Tj T* (  -h, --help            show this help message and exit) Tj T* (  -H, --header          Header) Tj T* (  -c SQL, --sqlcmd SQL  SQL command) Tj T* (  -d |, --delimiter |   Column separator) Tj T* ET
+BT 1 0 0 1 0 149.71 Tm /F3 10 Tf 12 TL (usage: dbcli.py [-h] [-H] [-c SQL] [-d |] db [scripts [scripts ...]]) Tj T*  T* (A script to run queries and SQL scripts on a database) Tj T*  T* (positional arguments:) Tj T* (  db                    Connection string) Tj T* (  scripts               SQL scripts) Tj T*  T* (optional arguments:) Tj T* (  -h, --help            show this help message and exit) Tj T* (  -H, --header          Header) Tj T* (  -c SQL, --sqlcmd SQL  SQL command) Tj T* (  -d |, --delimiter |   Column separator) Tj T* ET
 Q
 Q
 Q
@@ -9129,7 +9135,7 @@ Q
 q
 1 0 0 1 62.69291 453.8236 cm
 q
-BT 1 0 0 1 0 28.82 Tm 1.831984 Tw 12 TL /F1 10 Tf 0 0 0 rg (Starting from release 0.4, ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (supports keyword arguments. In practice that means that if your main) Tj T* 0 Tw 2.099213 Tw (function has keyword arguments, ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (treats specially arguments of the form ) Tj /F4 10 Tf ("name=value" ) Tj /F1 10 Tf (in the) Tj T* 0 Tw (command line. Here is an example:) Tj T* ET
+BT 1 0 0 1 0 28.82 Tm 1.831984 Tw 12 TL /F1 10 Tf 0 0 0 rg (Starting from release 0.4, ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (supports keyword arguments. In practice that means that if your main) Tj T* 0 Tw 2.099213 Tw (function has keyword arguments, ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (treats specially arguments of the form ) Tj /F3 10 Tf ("name=value" ) Tj /F1 10 Tf (in the) Tj T* 0 Tw (command line. Here is an example:) Tj T* ET
 Q
 Q
 q
@@ -9147,7 +9153,7 @@ n -6 -6 468.6898 228 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 209.71 Tm /F4 10 Tf 12 TL (# example12.py) Tj T* (import plac) Tj T*  T* (@plac.annotations\() Tj T* (   opt=\('some option', 'option'\),) Tj T* (   args='default arguments',) Tj T* (   kw='keyword arguments'\)) Tj T* (def main\(opt, *args, **kw\):) Tj T* (   if opt:) Tj T* (      yield 'opt=%s' % opt) Tj T* (   if args:) Tj T* (      yield 'args=%s' % str\(args\)) Tj T* (   if kw:) Tj T* (      yield 'kw=%s' % kw) Tj T*  T* (if __name__ == '__main__':) Tj T* (    for output in plac.call\(main\):) Tj T* (       print\(output\)) Tj T* ET
+BT 1 0 0 1 0 209.71 Tm /F3 10 Tf 12 TL (# example12.py) Tj T* (import plac) Tj T*  T* (@plac.annotations\() Tj T* (   opt=\('some option', 'option'\),) Tj T* (   args='default arguments',) Tj T* (   kw='keyword arguments'\)) Tj T* (def main\(opt, *args, **kw\):) Tj T* (   if opt:) Tj T* (      yield 'opt=%s' % opt) Tj T* (   if args:) Tj T* (      yield 'args=%s' % str\(args\)) Tj T* (   if kw:) Tj T* (      yield 'kw=%s' % kw) Tj T*  T* (if __name__ == '__main__':) Tj T* (    for output in plac.call\(main\):) Tj T* (       print\(output\)) Tj T* ET
 Q
 Q
 Q
@@ -9175,7 +9181,7 @@ n -6 -6 468.6898 96 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 77.71 Tm /F4 10 Tf 12 TL (usage: example12.py [-h] [-opt OPT] [args [args ...]] [kw [kw ...]]) Tj T*  T* (positional arguments:) Tj T* (  args        default arguments) Tj T* (  kw          keyword arguments) Tj T*  T* (optional arguments:) Tj T* ET
+BT 1 0 0 1 0 77.71 Tm /F3 10 Tf 12 TL (usage: example12.py [-h] [-opt OPT] [args [args ...]] [kw [kw ...]]) Tj T*  T* (positional arguments:) Tj T* (  args        default arguments) Tj T* (  kw          keyword arguments) Tj T*  T* (optional arguments:) Tj T* ET
 Q
 Q
 Q
@@ -9213,7 +9219,7 @@ n -6 -6 468.6898 36 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 17.71 Tm /F4 10 Tf 12 TL (  -h, --help  show this help message and exit) Tj T* (  -opt OPT    some option) Tj T* ET
+BT 1 0 0 1 0 17.71 Tm /F3 10 Tf 12 TL (  -h, --help  show this help message and exit) Tj T* (  -opt OPT    some option) Tj T* ET
 Q
 Q
 Q
@@ -9241,7 +9247,7 @@ n -6 -6 468.6898 60 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 41.71 Tm /F4 10 Tf 12 TL ($ python example12.py -o X a1 a2 name=value) Tj T* (opt=X) Tj T* (args=\('a1', 'a2'\)) Tj T* (kw={'name': 'value'}) Tj T* ET
+BT 1 0 0 1 0 41.71 Tm /F3 10 Tf 12 TL ($ python example12.py -o X a1 a2 name=value) Tj T* (opt=X) Tj T* (args=\('a1', 'a2'\)) Tj T* (kw={'name': 'value'}) Tj T* ET
 Q
 Q
 Q
@@ -9250,7 +9256,7 @@ Q
 q
 1 0 0 1 62.69291 606.6236 cm
 q
-BT 1 0 0 1 0 16.82 Tm 2.133735 Tw 12 TL /F1 10 Tf 0 0 0 rg (When using keyword arguments, one must be careful to use names which are not alreay taken; for) Tj T* 0 Tw (instance in this examples the name ) Tj /F4 10 Tf (opt ) Tj /F1 10 Tf (is taken:) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm 2.133735 Tw 12 TL /F1 10 Tf 0 0 0 rg (When using keyword arguments, one must be careful to use names which are not alreay taken; for) Tj T* 0 Tw (instance in this examples the name ) Tj /F3 10 Tf (opt ) Tj /F1 10 Tf (is taken:) Tj T* ET
 Q
 Q
 q
@@ -9268,7 +9274,7 @@ n -6 -6 468.6898 48 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 29.71 Tm /F4 10 Tf 12 TL ($ python example12.py 1 2 kw1=1 kw2=2 opt=0) Tj T* (usage: example12.py [-h] [-o OPT] [args [args ...]] [kw [kw ...]]) Tj T* (example12.py: error: colliding keyword arguments: opt) Tj T* ET
+BT 1 0 0 1 0 29.71 Tm /F3 10 Tf 12 TL ($ python example12.py 1 2 kw1=1 kw2=2 opt=0) Tj T* (usage: example12.py [-h] [-o OPT] [args [args ...]] [kw [kw ...]]) Tj T* (example12.py: error: colliding keyword arguments: opt) Tj T* ET
 Q
 Q
 Q
@@ -9307,7 +9313,7 @@ q
 n -6 -6 492 324 re B*
 Q
 q
-BT 1 0 0 1 0 305.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (# ishelve.py) Tj T* (import os, shelve, plac) Tj T*  T* (DEFAULT_SHELVE = os.path.expanduser\('~/conf.shelve'\)) Tj T*  T* (@plac.annotations\() Tj T* (    help=\('show help', 'flag'\),) Tj T* (    showall=\('show all parameters in the shelve', 'flag'\),) Tj T* (    clear=\('clear the shelve', 'flag'\),) Tj T* (    delete=\('delete an element', 'option'\),) Tj T* (    filename=\('filename of the shelve', 'option'\),) Tj T* (    params='names of the parameters in the shelve',) Tj T* (    setters='setters param=value'\)) Tj T* (def main\(help, showall, clear, delete, filename=DEFAULT_SHELVE,) Tj T* (         *params, **setters\):) Tj T* (    "A simple interface to a shelve. Use .help to see the available commands.") Tj T* (    sh = shelve.open\(filename\)) Tj T* (    try:) Tj T* (        if not any\([help, showall, clear, delete, params, setters]\):) Tj T* (            yield 'no arguments passed, use .help to see the available commands') Tj T* (        elif help: # custom help) Tj T* (            yield 'Commands: .help, .showall, .clear, .delete') Tj T* (            yield ') Tj (<) Tj (param) Tj (>) Tj ( ...') Tj T* (            yield ') Tj (<) Tj (param=value) Tj (>) Tj ( ...') Tj T* (        elif showall:) Tj T* (            for param, name in sh.items\(\):) Tj T* ET
+BT 1 0 0 1 0 305.71 Tm 12 TL /F3 10 Tf 0 0 0 rg (# ishelve.py) Tj T* (import os, shelve, plac) Tj T*  T* (DEFAULT_SHELVE = os.path.expanduser\('~/conf.shelve'\)) Tj T*  T* (@plac.annotations\() Tj T* (    help=\('show help', 'flag'\),) Tj T* (    showall=\('show all parameters in the shelve', 'flag'\),) Tj T* (    clear=\('clear the shelve', 'flag'\),) Tj T* (    delete=\('delete an element', 'option'\),) Tj T* (    filename=\('filename of the shelve', 'option'\),) Tj T* (    params='names of the parameters in the shelve',) Tj T* (    setters='setters param=value'\)) Tj T* (def main\(help, showall, clear, delete, filename=DEFAULT_SHELVE,) Tj T* (         *params, **setters\):) Tj T* (    "A simple interface to a shelve. Use .help to see the available commands.") Tj T* (    sh = shelve.open\(filename\)) Tj T* (    try:) Tj T* (        if not any\([help, showall, clear, delete, params, setters]\):) Tj T* (            yield 'no arguments passed, use .help to see the available commands') Tj T* (        elif help: # custom help) Tj T* (            yield 'Commands: .help, .showall, .clear, .delete') Tj T* (            yield ') Tj (<) Tj (param) Tj (>) Tj ( ...') Tj T* (            yield ') Tj (<) Tj (param=value) Tj (>) Tj ( ...') Tj T* (        elif showall:) Tj T* (            for param, name in sh.items\(\):) Tj T* ET
 Q
 Q
 Q
@@ -9344,7 +9350,7 @@ q
 n -6 -6 468.6898 348 re B*
 Q
 q
-BT 1 0 0 1 0 329.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (                yield '%s=%s' % \(param, name\)) Tj T* (        elif clear:) Tj T* (            sh.clear\(\)) Tj T* (            yield 'cleared the shelve') Tj T* (        elif delete:) Tj T* (            try:) Tj T* (                del sh[delete]) Tj T* (            except KeyError:) Tj T* (                yield '%s: not found' % delete) Tj T* (            else:) Tj T* (                yield 'deleted %s' % delete) Tj T* (        for param in params:) Tj T* (            try:) Tj T* (                yield sh[param]) Tj T* (            except KeyError:) Tj T* (                yield '%s: not found' % param           ) Tj T* (        for param, value in setters.items\(\):) Tj T* (            sh[param] = value) Tj T* (            yield 'setting %s=%s' % \(param, value\)) Tj T* (    finally:) Tj T* (        sh.close\(\)) Tj T*  T* (main.add_help = False # there is a custom help, remove the default one) Tj T* (main.prefix_chars = '.' # use dot-prefixed commands) Tj T*  T* (if __name__ == '__main__':) Tj T* (    for output in plac.call\(main\):) Tj T* (        print\(output\)) Tj T* ET
+BT 1 0 0 1 0 329.71 Tm 12 TL /F3 10 Tf 0 0 0 rg (                yield '%s=%s' % \(param, name\)) Tj T* (        elif clear:) Tj T* (            sh.clear\(\)) Tj T* (            yield 'cleared the shelve') Tj T* (        elif delete:) Tj T* (            try:) Tj T* (                del sh[delete]) Tj T* (            except KeyError:) Tj T* (                yield '%s: not found' % delete) Tj T* (            else:) Tj T* (                yield 'deleted %s' % delete) Tj T* (        for param in params:) Tj T* (            try:) Tj T* (                yield sh[param]) Tj T* (            except KeyError:) Tj T* (                yield '%s: not found' % param           ) Tj T* (        for param, value in setters.items\(\):) Tj T* (            sh[param] = value) Tj T* (            yield 'setting %s=%s' % \(param, value\)) Tj T* (    finally:) Tj T* (        sh.close\(\)) Tj T*  T* (main.add_help = False # there is a custom help, remove the default one) Tj T* (main.prefix_chars = '.' # use dot-prefixed commands) Tj T*  T* (if __name__ == '__main__':) Tj T* (    for output in plac.call\(main\):) Tj T* (        print\(output\)) Tj T* ET
 Q
 Q
 Q
@@ -9366,7 +9372,7 @@ Q
 q
 1 0 0 1 62.69291 359.8236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 15 cm
 q
@@ -9392,7 +9398,7 @@ Q
 q
 1 0 0 1 62.69291 341.8236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 3 cm
 q
@@ -9419,7 +9425,7 @@ Q
 q
 1 0 0 1 62.69291 311.8236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 15 cm
 q
@@ -9430,7 +9436,7 @@ Q
 q
 1 0 0 1 23 3 cm
 q
-BT 1 0 0 1 0 16.82 Tm .864985 Tw 12 TL /F1 10 Tf 0 0 0 rg (Keyword arguments recognition \(in the ) Tj /F4 10 Tf (**setters) Tj /F1 10 Tf (\) is used to make it possible to store a value in) Tj T* 0 Tw (the shelve with the syntax ) Tj /F4 10 Tf (param_name=param_value) Tj /F1 10 Tf (.) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm .864985 Tw 12 TL /F1 10 Tf 0 0 0 rg (Keyword arguments recognition \(in the ) Tj /F3 10 Tf (**setters) Tj /F1 10 Tf (\) is used to make it possible to store a value in) Tj T* 0 Tw (the shelve with the syntax ) Tj /F3 10 Tf (param_name=param_value) Tj /F1 10 Tf (.) Tj T* ET
 Q
 Q
 q
@@ -9445,7 +9451,7 @@ Q
 q
 1 0 0 1 62.69291 281.8236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 15 cm
 q
@@ -9456,7 +9462,7 @@ Q
 q
 1 0 0 1 23 3 cm
 q
-BT 1 0 0 1 0 16.82 Tm .649318 Tw 12 TL /F4 10 Tf 0 0 0 rg (*params ) Tj /F1 10 Tf (are used to retrieve parameters from the shelve and some error checking is performed in) Tj T* 0 Tw (the case of missing parameters) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm .649318 Tw 12 TL /F3 10 Tf 0 0 0 rg (*params ) Tj /F1 10 Tf (are used to retrieve parameters from the shelve and some error checking is performed in) Tj T* 0 Tw (the case of missing parameters) Tj T* ET
 Q
 Q
 q
@@ -9471,7 +9477,7 @@ Q
 q
 1 0 0 1 62.69291 263.8236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 3 cm
 q
@@ -9482,7 +9488,7 @@ Q
 q
 1 0 0 1 23 3 cm
 q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (A command to clear the shelve is implemented as a flag \() Tj /F4 10 Tf (.clear) Tj /F1 10 Tf (\).) Tj T* ET
+BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (A command to clear the shelve is implemented as a flag \() Tj /F3 10 Tf (.clear) Tj /F1 10 Tf (\).) Tj T* ET
 Q
 Q
 q
@@ -9497,7 +9503,7 @@ Q
 q
 1 0 0 1 62.69291 245.8236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 3 cm
 q
@@ -9508,7 +9514,7 @@ Q
 q
 1 0 0 1 23 3 cm
 q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (A command to delete a given parameter is implemented as an option \() Tj /F4 10 Tf (.delete) Tj /F1 10 Tf (\).) Tj T* ET
+BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (A command to delete a given parameter is implemented as an option \() Tj /F3 10 Tf (.delete) Tj /F1 10 Tf (\).) Tj T* ET
 Q
 Q
 q
@@ -9523,7 +9529,7 @@ Q
 q
 1 0 0 1 62.69291 227.8236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 3 cm
 q
@@ -9534,7 +9540,7 @@ Q
 q
 1 0 0 1 23 3 cm
 q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (There is an option with default \() Tj /F4 10 Tf (.filename=conf.shelve) Tj /F1 10 Tf (\) to store the filename of the shelve.) Tj T* ET
+BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (There is an option with default \() Tj /F3 10 Tf (.filename=conf.shelve) Tj /F1 10 Tf (\) to store the filename of the shelve.) Tj T* ET
 Q
 Q
 q
@@ -9549,7 +9555,7 @@ Q
 q
 1 0 0 1 62.69291 185.8236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 27 cm
 q
@@ -9575,7 +9581,7 @@ Q
 q
 1 0 0 1 62.69291 167.8236 cm
 q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (If you run ) Tj /F4 10 Tf (ishelve.py ) Tj /F1 10 Tf (without arguments you get the following message:) Tj T* ET
+BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (If you run ) Tj /F3 10 Tf (ishelve.py ) Tj /F1 10 Tf (without arguments you get the following message:) Tj T* ET
 Q
 Q
 q
@@ -9593,7 +9599,7 @@ n -6 -6 468.6898 36 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 17.71 Tm /F4 10 Tf 12 TL ($ python ishelve.py) Tj T* (no arguments passed, use .help to see the available commands) Tj T* ET
+BT 1 0 0 1 0 17.71 Tm /F3 10 Tf 12 TL ($ python ishelve.py) Tj T* (no arguments passed, use .help to see the available commands) Tj T* ET
 Q
 Q
 Q
@@ -9602,7 +9608,7 @@ Q
 q
 1 0 0 1 62.69291 102.6236 cm
 q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (If you run ) Tj /F4 10 Tf (ishelve.py ) Tj /F1 10 Tf (with the option ) Tj /F4 10 Tf (.h ) Tj /F1 10 Tf (\(or any abbreviation of ) Tj /F4 10 Tf (.help) Tj /F1 10 Tf (\) you get:) Tj T* ET
+BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (If you run ) Tj /F3 10 Tf (ishelve.py ) Tj /F1 10 Tf (with the option ) Tj /F3 10 Tf (.h ) Tj /F1 10 Tf (\(or any abbreviation of ) Tj /F3 10 Tf (.help) Tj /F1 10 Tf (\) you get:) Tj T* ET
 Q
 Q
 q
@@ -9636,7 +9642,7 @@ q
 n -6 -6 468.6898 60 re B*
 Q
 q
-BT 1 0 0 1 0 41.71 Tm 12 TL /F4 10 Tf 0 0 0 rg ($ python ishelve.py .h) Tj T* (Commands: .help, .showall, .clear, .delete) Tj T* (<) Tj (param) Tj (>) Tj ( ...) Tj T* (<) Tj (param=value) Tj (>) Tj ( ...) Tj T* ET
+BT 1 0 0 1 0 41.71 Tm 12 TL /F3 10 Tf 0 0 0 rg ($ python ishelve.py .h) Tj T* (Commands: .help, .showall, .clear, .delete) Tj T* (<) Tj (param) Tj (>) Tj ( ...) Tj T* (<) Tj (param=value) Tj (>) Tj ( ...) Tj T* ET
 Q
 Q
 Q
@@ -9664,7 +9670,7 @@ n -6 -6 468.6898 240 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 221.71 Tm /F4 10 Tf 12 TL ($ python ishelve.py .clear # start from an empty shelve) Tj T* (cleared the shelve) Tj T* ($ python ishelve.py a=1 b=2) Tj T* (setting a=1) Tj T* (setting b=2) Tj T* ($ python ishelve.py .showall) Tj T* (b=2) Tj T* (a=1) Tj T* ($ python ishelve.py .del b # abbreviation for .delete) Tj T* (deleted b) Tj T* ($ python ishelve.py a) Tj T* (1) Tj T* ($ python ishelve.py b) Tj T* (b: not found) Tj T* ($ python ishelve.py .cler # mispelled command) Tj T* (usage: ishelve.py [.help] [.showall] [.clear] [.delete DELETE]) Tj T* (                  [.filename /home/micheles/conf.shelve]) Tj T* (                  [params [params ...]] [setters [setters ...]]) Tj T* (ishelve.py: error: unrecognized arguments: .cler) Tj T* ET
+BT 1 0 0 1 0 221.71 Tm /F3 10 Tf 12 TL ($ python ishelve.py .clear # start from an empty shelve) Tj T* (cleared the shelve) Tj T* ($ python ishelve.py a=1 b=2) Tj T* (setting a=1) Tj T* (setting b=2) Tj T* ($ python ishelve.py .showall) Tj T* (b=2) Tj T* (a=1) Tj T* ($ python ishelve.py .del b # abbreviation for .delete) Tj T* (deleted b) Tj T* ($ python ishelve.py a) Tj T* (1) Tj T* ($ python ishelve.py b) Tj T* (b: not found) Tj T* ($ python ishelve.py .cler # mispelled command) Tj T* (usage: ishelve.py [.help] [.showall] [.clear] [.delete DELETE]) Tj T* (                  [.filename /home/micheles/conf.shelve]) Tj T* (                  [params [params ...]] [setters [setters ...]]) Tj T* (ishelve.py: error: unrecognized arguments: .cler) Tj T* ET
 Q
 Q
 Q
@@ -9691,7 +9697,7 @@ Q
 q
 1 0 0 1 62.69291 278.6236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 63 cm
 q
@@ -9702,7 +9708,7 @@ Q
 q
 1 0 0 1 23 3 cm
 q
-BT 1 0 0 1 0 64.82 Tm 2.69784 Tw 12 TL /F1 10 Tf 0 0 0 rg (plac does not support the destination concept: the destination coincides with the name of the) Tj T* 0 Tw .359983 Tw (argument, always. This restriction has some drawbacks. For instance, suppose you want to define a) Tj T* 0 Tw 2.758651 Tw (long option called ) Tj /F4 10 Tf (--yield) Tj /F1 10 Tf (. In this case the destination would be ) Tj /F4 10 Tf (yield) Tj /F1 10 Tf (, which is a Python) Tj T* 0 Tw 1.181235 Tw (keyword, and since you cannot introduce an argument with that name in a function definition, it is) Tj T* 0 Tw 2.12528 Tw (impossible to implement it. Your choices are to change the name of the long option, or to use) Tj T* 0 Tw 0 0 .501961 rg (argparse ) Tj 0 0 0 rg (with a suitable destination.) Tj T* ET
+BT 1 0 0 1 0 64.82 Tm 2.69784 Tw 12 TL /F1 10 Tf 0 0 0 rg (plac does not support the destination concept: the destination coincides with the name of the) Tj T* 0 Tw .359983 Tw (argument, always. This restriction has some drawbacks. For instance, suppose you want to define a) Tj T* 0 Tw 2.758651 Tw (long option called ) Tj /F3 10 Tf (--yield) Tj /F1 10 Tf (. In this case the destination would be ) Tj /F3 10 Tf (yield) Tj /F1 10 Tf (, which is a Python) Tj T* 0 Tw 1.181235 Tw (keyword, and since you cannot introduce an argument with that name in a function definition, it is) Tj T* 0 Tw 2.12528 Tw (impossible to implement it. Your choices are to change the name of the long option, or to use) Tj T* 0 Tw 0 0 .501961 rg (argparse ) Tj 0 0 0 rg (with a suitable destination.) Tj T* ET
 Q
 Q
 q
@@ -9717,7 +9723,7 @@ Q
 q
 1 0 0 1 62.69291 224.6236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 39 cm
 q
@@ -9728,7 +9734,7 @@ Q
 q
 1 0 0 1 23 3 cm
 q
-BT 1 0 0 1 0 40.82 Tm 1.120751 Tw 12 TL /F1 10 Tf 0 0 .501961 rg (plac ) Tj 0 0 0 rg (does not support "required options". As the ) Tj 0 0 .501961 rg (argparse ) Tj 0 0 0 rg (documentation puts it: ) Tj /F5 10 Tf (Required options) Tj T* 0 Tw 1.075318 Tw (are generally considered bad form - normal users expect options to be optional. You should avoid) Tj T* 0 Tw .874269 Tw (the use of required options whenever possible. ) Tj /F1 10 Tf (Notice that since ) Tj 0 0 .501961 rg (argparse ) Tj 0 0 0 rg (supports them, ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (can) Tj T* 0 Tw (manage them too, but not directly.) Tj T* ET
+BT 1 0 0 1 0 40.82 Tm 1.120751 Tw 12 TL /F1 10 Tf 0 0 .501961 rg (plac ) Tj 0 0 0 rg (does not support "required options". As the ) Tj 0 0 .501961 rg (argparse ) Tj 0 0 0 rg (documentation puts it: ) Tj /F4 10 Tf (Required options) Tj T* 0 Tw 1.075318 Tw (are generally considered bad form - normal users expect options to be optional. You should avoid) Tj T* 0 Tw .874269 Tw (the use of required options whenever possible. ) Tj /F1 10 Tf (Notice that since ) Tj 0 0 .501961 rg (argparse ) Tj 0 0 0 rg (supports them, ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (can) Tj T* 0 Tw (manage them too, but not directly.) Tj T* ET
 Q
 Q
 q
@@ -9743,7 +9749,7 @@ Q
 q
 1 0 0 1 62.69291 158.6236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 51 cm
 q
@@ -9754,7 +9760,7 @@ Q
 q
 1 0 0 1 23 3 cm
 q
-BT 1 0 0 1 0 52.82 Tm 1.539982 Tw 12 TL /F1 10 Tf 0 0 .501961 rg (plac ) Tj 0 0 0 rg (supports only regular boolean flags. ) Tj 0 0 .501961 rg (argparse ) Tj 0 0 0 rg (has the ability to define generalized two-value) Tj T* 0 Tw .361751 Tw (flags with values different from ) Tj /F4 10 Tf (True ) Tj /F1 10 Tf (and ) Tj /F4 10 Tf (False) Tj /F1 10 Tf (. An earlier version of ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (had this feature too, but) Tj T* 0 Tw .814985 Tw (since you can use options with two choices instead, and in any case the conversion from ) Tj /F4 10 Tf ({True,) Tj T* 0 Tw .901984 Tw (False} ) Tj /F1 10 Tf (to any couple of values can be trivially implemented with a ternary operator \() Tj /F4 10 Tf (value1 if) Tj T* 0 Tw (flag else value2) Tj /F1 10 Tf (\), I have removed it \(KISS rules!\).) Tj T* ET
+BT 1 0 0 1 0 52.82 Tm 1.539982 Tw 12 TL /F1 10 Tf 0 0 .501961 rg (plac ) Tj 0 0 0 rg (supports only regular boolean flags. ) Tj 0 0 .501961 rg (argparse ) Tj 0 0 0 rg (has the ability to define generalized two-value) Tj T* 0 Tw .361751 Tw (flags with values different from ) Tj /F3 10 Tf (True ) Tj /F1 10 Tf (and ) Tj /F3 10 Tf (False) Tj /F1 10 Tf (. An earlier version of ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (had this feature too, but) Tj T* 0 Tw .814985 Tw (since you can use options with two choices instead, and in any case the conversion from ) Tj /F3 10 Tf ({True,) Tj T* 0 Tw .901984 Tw (False} ) Tj /F1 10 Tf (to any couple of values can be trivially implemented with a ternary operator \() Tj /F3 10 Tf (value1 if) Tj T* 0 Tw (flag else value2) Tj /F1 10 Tf (\), I have removed it \(KISS rules!\).) Tj T* ET
 Q
 Q
 q
@@ -9769,7 +9775,7 @@ Q
 q
 1 0 0 1 62.69291 116.6236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 27 cm
 q
@@ -9780,7 +9786,7 @@ Q
 q
 1 0 0 1 23 3 cm
 q
-BT 1 0 0 1 0 28.82 Tm 1.797126 Tw 12 TL /F1 10 Tf 0 0 .501961 rg (plac ) Tj 0 0 0 rg (does not support ) Tj /F4 10 Tf (nargs ) Tj /F1 10 Tf (options directly \(it uses them internally, though, to implement flag) Tj T* 0 Tw .90683 Tw (recognition\). The reason it that all the use cases of interest to me are covered by ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (and did not) Tj T* 0 Tw (feel the need to increase the learning curve by adding direct support for ) Tj /F4 10 Tf (nargs) Tj /F1 10 Tf (.) Tj T* ET
+BT 1 0 0 1 0 28.82 Tm 1.797126 Tw 12 TL /F1 10 Tf 0 0 .501961 rg (plac ) Tj 0 0 0 rg (does not support ) Tj /F3 10 Tf (nargs ) Tj /F1 10 Tf (options directly \(it uses them internally, though, to implement flag) Tj T* 0 Tw .90683 Tw (recognition\). The reason it that all the use cases of interest to me are covered by ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (and did not) Tj T* 0 Tw (feel the need to increase the learning curve by adding direct support for ) Tj /F3 10 Tf (nargs) Tj /F1 10 Tf (.) Tj T* ET
 Q
 Q
 q
@@ -9812,7 +9818,7 @@ stream
 q
 1 0 0 1 62.69291 735.0236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 15 cm
 q
@@ -9838,7 +9844,7 @@ Q
 q
 1 0 0 1 62.69291 693.0236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 27 cm
 q
@@ -9870,13 +9876,13 @@ Q
 q
 1 0 0 1 62.69291 633.0236 cm
 q
-BT 1 0 0 1 0 28.82 Tm 5.575697 Tw 12 TL /F1 10 Tf 0 0 0 rg (For instance, you can make invisible an argument in the usage message simply by using) Tj T* 0 Tw 1.435976 Tw /F4 10 Tf ('==SUPPRESS==' ) Tj /F1 10 Tf (as help string \(or ) Tj /F4 10 Tf (argparse.SUPPRESS) Tj /F1 10 Tf (\). Similarly, you can use ) Tj 0 0 .501961 rg (argparse.FileType) Tj T* 0 Tw 0 0 0 rg (directly.) Tj T* ET
+BT 1 0 0 1 0 28.82 Tm 5.575697 Tw 12 TL /F1 10 Tf 0 0 0 rg (For instance, you can make invisible an argument in the usage message simply by using) Tj T* 0 Tw 1.435976 Tw /F3 10 Tf ('==SUPPRESS==' ) Tj /F1 10 Tf (as help string \(or ) Tj /F3 10 Tf (argparse.SUPPRESS) Tj /F1 10 Tf (\). Similarly, you can use ) Tj 0 0 .501961 rg (argparse.FileType) Tj T* 0 Tw 0 0 0 rg (directly.) Tj T* ET
 Q
 Q
 q
 1 0 0 1 62.69291 579.0236 cm
 q
-BT 1 0 0 1 0 40.82 Tm 1.639213 Tw 12 TL /F1 10 Tf 0 0 0 rg (It is also possible to pass options to the underlying ) Tj /F4 10 Tf (argparse.ArgumentParser ) Tj /F1 10 Tf (object \(currently it) Tj T* 0 Tw .285529 Tw (accepts the default arguments ) Tj /F4 10 Tf (description) Tj /F1 10 Tf (, ) Tj /F4 10 Tf (epilog) Tj /F1 10 Tf (, ) Tj /F4 10 Tf (prog) Tj /F1 10 Tf (, ) Tj /F4 10 Tf (usage) Tj /F1 10 Tf (, ) Tj /F4 10 Tf (add_help) Tj /F1 10 Tf (, ) Tj /F4 10 Tf (argument_default) Tj /F1 10 Tf (,) Tj T* 0 Tw 1.439953 Tw /F4 10 Tf (parents) Tj /F1 10 Tf (, ) Tj /F4 10 Tf (prefix_chars) Tj /F1 10 Tf (, ) Tj /F4 10 Tf (fromfile_prefix_chars) Tj /F1 10 Tf (, ) Tj /F4 10 Tf (conflict_handler) Tj /F1 10 Tf (, ) Tj /F4 10 Tf (formatter_class) Tj /F1 10 Tf (\). It) Tj T* 0 Tw (is enough to set such attributes on the ) Tj /F4 10 Tf (main ) Tj /F1 10 Tf (function. For instance) Tj T* ET
+BT 1 0 0 1 0 40.82 Tm 1.639213 Tw 12 TL /F1 10 Tf 0 0 0 rg (It is also possible to pass options to the underlying ) Tj /F3 10 Tf (argparse.ArgumentParser ) Tj /F1 10 Tf (object \(currently it) Tj T* 0 Tw .285529 Tw (accepts the default arguments ) Tj /F3 10 Tf (description) Tj /F1 10 Tf (, ) Tj /F3 10 Tf (epilog) Tj /F1 10 Tf (, ) Tj /F3 10 Tf (prog) Tj /F1 10 Tf (, ) Tj /F3 10 Tf (usage) Tj /F1 10 Tf (, ) Tj /F3 10 Tf (add_help) Tj /F1 10 Tf (, ) Tj /F3 10 Tf (argument_default) Tj /F1 10 Tf (,) Tj T* 0 Tw 1.439953 Tw /F3 10 Tf (parents) Tj /F1 10 Tf (, ) Tj /F3 10 Tf (prefix_chars) Tj /F1 10 Tf (, ) Tj /F3 10 Tf (fromfile_prefix_chars) Tj /F1 10 Tf (, ) Tj /F3 10 Tf (conflict_handler) Tj /F1 10 Tf (, ) Tj /F3 10 Tf (formatter_class) Tj /F1 10 Tf (\). It) Tj T* 0 Tw (is enough to set such attributes on the ) Tj /F3 10 Tf (main ) Tj /F1 10 Tf (function. For instance) Tj T* ET
 Q
 Q
 q
@@ -9894,7 +9900,7 @@ n -6 -6 468.6898 60 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 41.71 Tm /F4 10 Tf 12 TL (def main\(...\):) Tj T* (    pass) Tj T*  T* (main.add_help = False) Tj T* ET
+BT 1 0 0 1 0 41.71 Tm /F3 10 Tf 12 TL (def main\(...\):) Tj T* (    pass) Tj T*  T* (main.add_help = False) Tj T* ET
 Q
 Q
 Q
@@ -9903,13 +9909,13 @@ Q
 q
 1 0 0 1 62.69291 465.8236 cm
 q
-BT 1 0 0 1 0 28.82 Tm .239318 Tw 12 TL /F1 10 Tf 0 0 0 rg (disables the recognition of the help flag ) Tj /F4 10 Tf (-h, --help) Tj /F1 10 Tf (. This mechanism does not look particularly elegant,) Tj T* 0 Tw .566988 Tw (but it works well enough. I assume that the typical user of ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (will be happy with the defaults and would) Tj T* 0 Tw (not want to change them; still it is possible if she wants to.) Tj T* ET
+BT 1 0 0 1 0 28.82 Tm .239318 Tw 12 TL /F1 10 Tf 0 0 0 rg (disables the recognition of the help flag ) Tj /F3 10 Tf (-h, --help) Tj /F1 10 Tf (. This mechanism does not look particularly elegant,) Tj T* 0 Tw .566988 Tw (but it works well enough. I assume that the typical user of ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (will be happy with the defaults and would) Tj T* 0 Tw (not want to change them; still it is possible if she wants to.) Tj T* ET
 Q
 Q
 q
 1 0 0 1 62.69291 435.8236 cm
 q
-BT 1 0 0 1 0 16.82 Tm 2.391235 Tw 12 TL /F1 10 Tf 0 0 0 rg (For instance, by setting the ) Tj /F4 10 Tf (description ) Tj /F1 10 Tf (attribute, it is possible to add a comment to the usage) Tj T* 0 Tw (message \(by default the docstring of the ) Tj /F4 10 Tf (main ) Tj /F1 10 Tf (function is used as description\).) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm 2.391235 Tw 12 TL /F1 10 Tf 0 0 0 rg (For instance, by setting the ) Tj /F3 10 Tf (description ) Tj /F1 10 Tf (attribute, it is possible to add a comment to the usage) Tj T* 0 Tw (message \(by default the docstring of the ) Tj /F3 10 Tf (main ) Tj /F1 10 Tf (function is used as description\).) Tj T* ET
 Q
 Q
 q
@@ -9934,7 +9940,7 @@ n -6 -6 468.6898 24 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 5.71 Tm /F4 10 Tf 12 TL (main.prefix_chars='/-') Tj T* ET
+BT 1 0 0 1 0 5.71 Tm /F3 10 Tf 12 TL (main.prefix_chars='/-') Tj T* ET
 Q
 Q
 Q
@@ -9943,13 +9949,13 @@ Q
 q
 1 0 0 1 62.69291 328.6236 cm
 q
-BT 1 0 0 1 0 28.82 Tm .924198 Tw 12 TL /F1 10 Tf 0 0 0 rg (The first prefix char \() Tj /F4 10 Tf (/) Tj /F1 10 Tf (\) is used as the default for the recognition of options and flags; the second prefix) Tj T* 0 Tw .26832 Tw (char \() Tj /F4 10 Tf (-) Tj /F1 10 Tf (\) is kept to keep the ) Tj /F4 10 Tf (-h/--help ) Tj /F1 10 Tf (option working: however you can disable it and reimplement it, if) Tj T* 0 Tw (you like, as seen in the ) Tj /F4 10 Tf (ishelve ) Tj /F1 10 Tf (example.) Tj T* ET
+BT 1 0 0 1 0 28.82 Tm .924198 Tw 12 TL /F1 10 Tf 0 0 0 rg (The first prefix char \() Tj /F3 10 Tf (/) Tj /F1 10 Tf (\) is used as the default for the recognition of options and flags; the second prefix) Tj T* 0 Tw .26832 Tw (char \() Tj /F3 10 Tf (-) Tj /F1 10 Tf (\) is kept to keep the ) Tj /F3 10 Tf (-h/--help ) Tj /F1 10 Tf (option working: however you can disable it and reimplement it, if) Tj T* 0 Tw (you like, as seen in the ) Tj /F3 10 Tf (ishelve ) Tj /F1 10 Tf (example.) Tj T* ET
 Q
 Q
 q
 1 0 0 1 62.69291 298.6236 cm
 q
-BT 1 0 0 1 0 16.82 Tm 7.709147 Tw 12 TL /F1 10 Tf 0 0 0 rg (It is possible to access directly the underlying ) Tj 0 0 .501961 rg (ArgumentParser ) Tj 0 0 0 rg (object, by invoking the) Tj T* 0 Tw /F4 10 Tf (plac.parser_from ) Tj /F1 10 Tf (utility function:) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm 7.709147 Tw 12 TL /F1 10 Tf 0 0 0 rg (It is possible to access directly the underlying ) Tj 0 0 .501961 rg (ArgumentParser ) Tj 0 0 0 rg (object, by invoking the) Tj T* 0 Tw /F3 10 Tf (plac.parser_from ) Tj /F1 10 Tf (utility function:) Tj T* ET
 Q
 Q
 q
@@ -9966,7 +9972,7 @@ q
 n -6 -6 468.6898 84 re B*
 Q
 q
-BT 1 0 0 1 0 65.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (>) Tj (>) Tj (>) Tj ( import plac) Tj T* (>) Tj (>) Tj (>) Tj ( def main\(arg\):) Tj T* (...     pass) Tj T* (...) Tj T* (>) Tj (>) Tj (>) Tj ( print\(plac.parser_from\(main\)\) #doctest: +ELLIPSIS) Tj T* (ArgumentParser\(prog=...\)) Tj T* ET
+BT 1 0 0 1 0 65.71 Tm 12 TL /F3 10 Tf 0 0 0 rg (>) Tj (>) Tj (>) Tj ( import plac) Tj T* (>) Tj (>) Tj (>) Tj ( def main\(arg\):) Tj T* (...     pass) Tj T* (...) Tj T* (>) Tj (>) Tj (>) Tj ( print\(plac.parser_from\(main\)\) #doctest: +ELLIPSIS) Tj T* (ArgumentParser\(prog=...\)) Tj T* ET
 Q
 Q
 Q
@@ -9975,19 +9981,19 @@ Q
 q
 1 0 0 1 62.69291 161.4236 cm
 q
-BT 1 0 0 1 0 28.82 Tm 2.646905 Tw 12 TL /F1 10 Tf 0 0 0 rg (Internally ) Tj /F4 10 Tf (plac.call ) Tj /F1 10 Tf (uses ) Tj /F4 10 Tf (plac.parser_from ) Tj /F1 10 Tf (and adds the parser to the main function as an) Tj T* 0 Tw .982126 Tw (attribute. When ) Tj /F4 10 Tf (plac.call\(func\) ) Tj /F1 10 Tf (is invoked multiple time, the parser is re-used and not rebuilt from) Tj T* 0 Tw (scratch again.) Tj T* ET
+BT 1 0 0 1 0 28.82 Tm 2.646905 Tw 12 TL /F1 10 Tf 0 0 0 rg (Internally ) Tj /F3 10 Tf (plac.call ) Tj /F1 10 Tf (uses ) Tj /F3 10 Tf (plac.parser_from ) Tj /F1 10 Tf (and adds the parser to the main function as an) Tj T* 0 Tw .982126 Tw (attribute. When ) Tj /F3 10 Tf (plac.call\(func\) ) Tj /F1 10 Tf (is invoked multiple time, the parser is re-used and not rebuilt from) Tj T* 0 Tw (scratch again.) Tj T* ET
 Q
 Q
 q
 1 0 0 1 62.69291 131.4236 cm
 q
-BT 1 0 0 1 0 16.82 Tm .982765 Tw 12 TL /F1 10 Tf 0 0 0 rg (I use ) Tj /F4 10 Tf (plac.parser_from ) Tj /F1 10 Tf (in the unit tests of the module, but regular users should not need to use it,) Tj T* 0 Tw (unless they want to access ) Tj /F5 10 Tf (all ) Tj /F1 10 Tf (of the features of ) Tj 0 0 .501961 rg (argparse ) Tj 0 0 0 rg (directly without calling the main function.) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm .982765 Tw 12 TL /F1 10 Tf 0 0 0 rg (I use ) Tj /F3 10 Tf (plac.parser_from ) Tj /F1 10 Tf (in the unit tests of the module, but regular users should not need to use it,) Tj T* 0 Tw (unless they want to access ) Tj /F4 10 Tf (all ) Tj /F1 10 Tf (of the features of ) Tj 0 0 .501961 rg (argparse ) Tj 0 0 0 rg (directly without calling the main function.) Tj T* ET
 Q
 Q
 q
 1 0 0 1 62.69291 89.42362 cm
 q
-BT 1 0 0 1 0 28.82 Tm 1.442126 Tw 12 TL /F1 10 Tf 0 0 0 rg (Interested readers should read the documentation of ) Tj 0 0 .501961 rg (argparse ) Tj 0 0 0 rg (to understand the meaning of the other ) Tj T* 0 Tw .771567 Tw (options. If there is a set of options that you use very often, you may consider writing a decorator adding ) Tj T* 0 Tw 1.257045 Tw (such options to the ) Tj /F4 10 Tf (main ) Tj /F1 10 Tf (function for you. For simplicity, ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (does not perform any magic except the) Tj T* 0 Tw ET
+BT 1 0 0 1 0 28.82 Tm 1.442126 Tw 12 TL /F1 10 Tf 0 0 0 rg (Interested readers should read the documentation of ) Tj 0 0 .501961 rg (argparse ) Tj 0 0 0 rg (to understand the meaning of the other ) Tj T* 0 Tw .771567 Tw (options. If there is a set of options that you use very often, you may consider writing a decorator adding ) Tj T* 0 Tw 1.257045 Tw (such options to the ) Tj /F3 10 Tf (main ) Tj /F1 10 Tf (function for you. For simplicity, ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (does not perform any magic except the) Tj T* 0 Tw ET
 Q
 Q
 q
@@ -10010,7 +10016,7 @@ stream
 q
 1 0 0 1 62.69291 753.0236 cm
 q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (addition of the ) Tj /F4 10 Tf (.p ) Tj /F1 10 Tf (attribute.) Tj T* ET
+BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (addition of the ) Tj /F3 10 Tf (.p ) Tj /F1 10 Tf (attribute.) Tj T* ET
 Q
 Q
 q
@@ -10034,7 +10040,7 @@ Q
 q
 1 0 0 1 62.69291 657.0236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 3 cm
 q
@@ -10060,7 +10066,7 @@ Q
 q
 1 0 0 1 62.69291 639.0236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 3 cm
 q
@@ -10122,7 +10128,7 @@ Q
 q
 1 0 0 1 62.69291 321.0236 cm
 q
-BT 1 0 0 1 0 52.82 Tm .285988 Tw 12 TL /F1 10 Tf 0 0 0 rg (Version 0.5 of ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (doubled the code base and the documentation: it is based on the idea of using ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (to) Tj T* 0 Tw .408555 Tw (implement command-line interpreters, i.e. something akin to the ) Tj /F4 10 Tf (cmd ) Tj /F1 10 Tf (module in the standard library, only) Tj T* 0 Tw .49936 Tw (better. The new features of ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (are described in the ) Tj 0 0 .501961 rg (advanced usage document ) Tj 0 0 0 rg (. They are implemented) Tj T* 0 Tw .313828 Tw (in a separated module \() Tj /F4 10 Tf (plac_ext.py) Tj /F1 10 Tf (\), since they require Python 2.5 to work, whereas ) Tj /F4 10 Tf (plac_core.py) Tj T* 0 Tw /F1 10 Tf (only requires Python 2.3.) Tj T* ET
+BT 1 0 0 1 0 52.82 Tm .285988 Tw 12 TL /F1 10 Tf 0 0 0 rg (Version 0.5 of ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (doubled the code base and the documentation: it is based on the idea of using ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (to) Tj T* 0 Tw .408555 Tw (implement command-line interpreters, i.e. something akin to the ) Tj /F3 10 Tf (cmd ) Tj /F1 10 Tf (module in the standard library, only) Tj T* 0 Tw .49936 Tw (better. The new features of ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (are described in the ) Tj 0 0 .501961 rg (advanced usage document ) Tj 0 0 0 rg (. They are implemented) Tj T* 0 Tw .313828 Tw (in a separated module \() Tj /F3 10 Tf (plac_ext.py) Tj /F1 10 Tf (\), since they require Python 2.5 to work, whereas ) Tj /F3 10 Tf (plac_core.py) Tj T* 0 Tw /F1 10 Tf (only requires Python 2.3.) Tj T* ET
 Q
 Q
 q
@@ -10146,7 +10152,7 @@ Q
 q
 1 0 0 1 62.69291 189.0236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 15 cm
 q
@@ -10172,7 +10178,7 @@ Q
 q
 1 0 0 1 62.69291 159.0236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 15 cm
 q
@@ -10199,7 +10205,7 @@ Q
 q
 1 0 0 1 62.69291 105.0236 cm
 q
-BT 1 0 0 1 0 40.82 Tm .600574 Tw 12 TL /F1 10 Tf 0 0 0 rg (Putting together these two observations with the original idea of inferring the parser I decided to build an) Tj T* 0 Tw .516905 Tw 0 0 .501961 rg (ArgumentParser ) Tj 0 0 0 rg (object from function annotations. The ) Tj /F4 10 Tf (optionparser ) Tj /F1 10 Tf (name was ruled out, since I was) Tj T* 0 Tw 2.085984 Tw (now using ) Tj 0 0 .501961 rg (argparse) Tj 0 0 0 rg (; a name like ) Tj /F4 10 Tf (argparse_plus ) Tj /F1 10 Tf (was also ruled out, since the typical usage was) Tj T* 0 Tw (completely different from the ) Tj 0 0 .501961 rg (argparse ) Tj 0 0 0 rg (usage.) Tj T* ET
+BT 1 0 0 1 0 40.82 Tm .600574 Tw 12 TL /F1 10 Tf 0 0 0 rg (Putting together these two observations with the original idea of inferring the parser I decided to build an) Tj T* 0 Tw .516905 Tw 0 0 .501961 rg (ArgumentParser ) Tj 0 0 0 rg (object from function annotations. The ) Tj /F3 10 Tf (optionparser ) Tj /F1 10 Tf (name was ruled out, since I was) Tj T* 0 Tw 2.085984 Tw (now using ) Tj 0 0 .501961 rg (argparse) Tj 0 0 0 rg (; a name like ) Tj /F3 10 Tf (argparse_plus ) Tj /F1 10 Tf (was also ruled out, since the typical usage was) Tj T* 0 Tw (completely different from the ) Tj 0 0 .501961 rg (argparse ) Tj 0 0 0 rg (usage.) Tj T* ET
 Q
 Q
 q
@@ -10222,7 +10228,7 @@ stream
 q
 1 0 0 1 62.69291 741.0236 cm
 q
-BT 1 0 0 1 0 16.82 Tm 1.093876 Tw 12 TL /F1 10 Tf 0 0 0 rg (I made a research on PyPI and the name ) Tj /F5 10 Tf (clap ) Tj /F1 10 Tf (\(Command Line Arguments Parser\) was not taken, so I) Tj T* 0 Tw (renamed everything to clap. After two days a ) Tj 0 0 .501961 rg (Clap ) Tj 0 0 0 rg (module appeared on PyPI <) Tj (expletives deleted) Tj (>) Tj (!) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm 1.093876 Tw 12 TL /F1 10 Tf 0 0 0 rg (I made a research on PyPI and the name ) Tj /F4 10 Tf (clap ) Tj /F1 10 Tf (\(Command Line Arguments Parser\) was not taken, so I) Tj T* 0 Tw (renamed everything to clap. After two days a ) Tj 0 0 .501961 rg (Clap ) Tj 0 0 0 rg (module appeared on PyPI <) Tj (expletives deleted) Tj (>) Tj (!) Tj T* ET
 Q
 Q
 q
@@ -10250,7 +10256,7 @@ Q
 q
 1 0 0 1 62.69291 633.0236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 3 cm
 q
@@ -10271,7 +10277,7 @@ Q
 q
 1 0 0 1 62.69291 618.0236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 3 cm
 q
@@ -10293,7 +10299,7 @@ Q
 q
 1 0 0 1 62.69291 603.0236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 3 cm
 q
@@ -10314,7 +10320,7 @@ Q
 q
 1 0 0 1 62.69291 576.0236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 3 cm
 q
@@ -10336,7 +10342,7 @@ Q
 q
 1 0 0 1 62.69291 561.0236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 3 cm
 q
@@ -10358,7 +10364,7 @@ Q
 q
 1 0 0 1 62.69291 546.0236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 3 cm
 q
@@ -10370,7 +10376,7 @@ q
 1 0 0 1 91.03937 3 cm
 q
 0 0 0 rg
-BT 1 0 0 1 0 5.71 Tm /F4 10 Tf 12 TL (easy_install -U plac) Tj T* ET
+BT 1 0 0 1 0 5.71 Tm /F3 10 Tf 12 TL (easy_install -U plac) Tj T* ET
 Q
 Q
 q
@@ -10379,7 +10385,7 @@ Q
 q
 1 0 0 1 62.69291 531.0236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 3 cm
 q
@@ -10400,7 +10406,7 @@ Q
 q
 1 0 0 1 62.69291 516.0236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 3 cm
 q
@@ -10422,7 +10428,7 @@ q
 1 0 0 1 62.69291 474.0236 cm
 q
 0 0 0 rg
-BT 1 0 0 1 0 28.82 Tm /F5 10 Tf 12 TL 2.399986 Tw (The present document discusses a few of the advanced use cases for plac. It shows how to write) Tj T* 0 Tw 2.164651 Tw (interactive and non-interactive interpreters with plac, and how to use plac for testing and scripting a) Tj T* 0 Tw (generic application. It assumes you have already read an understood the basic documentation.) Tj T* ET
+BT 1 0 0 1 0 28.82 Tm /F4 10 Tf 12 TL 2.399986 Tw (The present document discusses a few of the advanced use cases for plac. It shows how to write) Tj T* 0 Tw 2.164651 Tw (interactive and non-interactive interpreters with plac, and how to use plac for testing and scripting a) Tj T* 0 Tw (generic application. It assumes you have already read an understood the basic documentation.) Tj T* ET
 Q
 Q
 q
@@ -10451,7 +10457,7 @@ Q
 q
 1 0 0 1 62.69291 108.0236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 0 615 cm
 q
@@ -10971,7 +10977,7 @@ Q
 q
 1 0 0 1 62.69291 705.0236 cm
 q
-BT 1 0 0 1 0 28.82 Tm .539036 Tw 12 TL /F1 10 Tf 0 0 0 rg (One of the design goals of ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (is to make it dead easy to write a scriptable and testable interface for an) Tj T* 0 Tw .813876 Tw (application. You can use ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (whenever you have an API with strings in input and strings in output, and) Tj T* 0 Tw (that includes a ) Tj /F5 10 Tf (huge ) Tj /F1 10 Tf (domain of applications.) Tj T* ET
+BT 1 0 0 1 0 28.82 Tm .539036 Tw 12 TL /F1 10 Tf 0 0 0 rg (One of the design goals of ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (is to make it dead easy to write a scriptable and testable interface for an) Tj T* 0 Tw .813876 Tw (application. You can use ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (whenever you have an API with strings in input and strings in output, and) Tj T* 0 Tw (that includes a ) Tj /F4 10 Tf (huge ) Tj /F1 10 Tf (domain of applications.) Tj T* ET
 Q
 Q
 q
@@ -10989,7 +10995,7 @@ Q
 q
 1 0 0 1 62.69291 555.0236 cm
 q
-BT 1 0 0 1 0 52.82 Tm .694104 Tw 12 TL /F1 10 Tf 0 0 0 rg (You can easily replace the ) Tj /F4 10 Tf (cmd ) Tj /F1 10 Tf (module of the standard library and you could easily write an application) Tj T* 0 Tw 2.271751 Tw (like ) Tj 0 0 .501961 rg (twill ) Tj 0 0 0 rg (with ) Tj 0 0 .501961 rg (plac) Tj 0 0 0 rg (. Or you could use it to script your building procedure. ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (also supports parallel) Tj T* 0 Tw .907765 Tw (execution of multiple commands and can be used as task manager and monitor. It is also quite easy to) Tj T* 0 Tw 1.483488 Tw (build a GUI or a Web application on top of ) Tj 0 0 .501961 rg (plac) Tj 0 0 0 rg (. When speaking of things you can do with ) Tj 0 0 .501961 rg (plac) Tj 0 0 0 rg (, your) Tj T* 0 Tw (imagination is the only limit!) Tj T* ET
+BT 1 0 0 1 0 52.82 Tm .694104 Tw 12 TL /F1 10 Tf 0 0 0 rg (You can easily replace the ) Tj /F3 10 Tf (cmd ) Tj /F1 10 Tf (module of the standard library and you could easily write an application) Tj T* 0 Tw 2.271751 Tw (like ) Tj 0 0 .501961 rg (twill ) Tj 0 0 0 rg (with ) Tj 0 0 .501961 rg (plac) Tj 0 0 0 rg (. Or you could use it to script your building procedure. ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (also supports parallel) Tj T* 0 Tw .907765 Tw (execution of multiple commands and can be used as task manager and monitor. It is also quite easy to) Tj T* 0 Tw 1.483488 Tw (build a GUI or a Web application on top of ) Tj 0 0 .501961 rg (plac) Tj 0 0 0 rg (. When speaking of things you can do with ) Tj 0 0 .501961 rg (plac) Tj 0 0 0 rg (, your) Tj T* 0 Tw (imagination is the only limit!) Tj T* ET
 Q
 Q
 q
@@ -11001,19 +11007,19 @@ Q
 q
 1 0 0 1 62.69291 471.0236 cm
 q
-BT 1 0 0 1 0 40.82 Tm 1.300751 Tw 12 TL /F1 10 Tf 0 0 0 rg (Command-line scripts have many advantages, but they are no substitute for interactive applications. In) Tj T* 0 Tw .088171 Tw (particular, if you have a script with a large startup time which must be run multiple times, it is best to turn it) Tj T* 0 Tw 4.582126 Tw (into an interactive application, so that the startup is performed only once. ) Tj /F4 10 Tf (plac ) Tj /F1 10 Tf (provides an) Tj T* 0 Tw /F4 10 Tf (Interpreter ) Tj /F1 10 Tf (class just for this purpose.) Tj T* ET
+BT 1 0 0 1 0 40.82 Tm 1.300751 Tw 12 TL /F1 10 Tf 0 0 0 rg (Command-line scripts have many advantages, but they are no substitute for interactive applications. In) Tj T* 0 Tw .088171 Tw (particular, if you have a script with a large startup time which must be run multiple times, it is best to turn it) Tj T* 0 Tw 4.582126 Tw (into an interactive application, so that the startup is performed only once. ) Tj /F3 10 Tf (plac ) Tj /F1 10 Tf (provides an) Tj T* 0 Tw /F3 10 Tf (Interpreter ) Tj /F1 10 Tf (class just for this purpose.) Tj T* ET
 Q
 Q
 q
 1 0 0 1 62.69291 441.0236 cm
 q
-BT 1 0 0 1 0 16.82 Tm 1.293984 Tw 12 TL /F1 10 Tf 0 0 0 rg (The ) Tj /F4 10 Tf (Interpreter ) Tj /F1 10 Tf (class wraps the main function of a script and provides an ) Tj /F4 10 Tf (.interact ) Tj /F1 10 Tf (method to) Tj T* 0 Tw (start an interactive interpreter reading commands from the console.) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm 1.293984 Tw 12 TL /F1 10 Tf 0 0 0 rg (The ) Tj /F3 10 Tf (Interpreter ) Tj /F1 10 Tf (class wraps the main function of a script and provides an ) Tj /F3 10 Tf (.interact ) Tj /F1 10 Tf (method to) Tj T* 0 Tw (start an interactive interpreter reading commands from the console.) Tj T* ET
 Q
 Q
 q
 1 0 0 1 62.69291 411.0236 cm
 q
-BT 1 0 0 1 0 16.82 Tm 1.49436 Tw 12 TL /F1 10 Tf 0 0 0 rg (For instance, you can define an interactive interpreter on top of the ) Tj /F4 10 Tf (ishelve ) Tj /F1 10 Tf (script introduced in the) Tj T* 0 Tw 0 0 .501961 rg (basic documentation ) Tj 0 0 0 rg (as follows:) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm 1.49436 Tw 12 TL /F1 10 Tf 0 0 0 rg (For instance, you can define an interactive interpreter on top of the ) Tj /F3 10 Tf (ishelve ) Tj /F1 10 Tf (script introduced in the) Tj T* 0 Tw 0 0 .501961 rg (basic documentation ) Tj 0 0 0 rg (as follows:) Tj T* ET
 Q
 Q
 q
@@ -11031,7 +11037,7 @@ n -6 -6 468.6898 240 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 221.71 Tm /F4 10 Tf 12 TL (# shelve_interpreter.py) Tj T* (import plac, ishelve) Tj T*  T* (@plac.annotations\() Tj T* (    interactive=\('start interactive interface', 'flag'\),) Tj T* (    subcommands='the commands of the underlying ishelve interpreter'\)) Tj T* (def main\(interactive, *subcommands\):) Tj T* (    """) Tj T* (    This script works both interactively and non-interactively.) Tj T* (    Use .help to see the internal commands.) Tj T* (    """) Tj T* (    if interactive:) Tj T* (        plac.Interpreter\(ishelve.main\).interact\(\)) Tj T* (    else:) Tj T* (        for out in plac.call\(ishelve.main, subcommands\):) Tj T* (            print\(out\)) Tj T*  T* (if __name__ == '__main__':) Tj T* (    plac.call\(main\)) Tj T* ET
+BT 1 0 0 1 0 221.71 Tm /F3 10 Tf 12 TL (# shelve_interpreter.py) Tj T* (import plac, ishelve) Tj T*  T* (@plac.annotations\() Tj T* (    interactive=\('start interactive interface', 'flag'\),) Tj T* (    subcommands='the commands of the underlying ishelve interpreter'\)) Tj T* (def main\(interactive, *subcommands\):) Tj T* (    """) Tj T* (    This script works both interactively and non-interactively.) Tj T* (    Use .help to see the internal commands.) Tj T* (    """) Tj T* (    if interactive:) Tj T* (        plac.Interpreter\(ishelve.main\).interact\(\)) Tj T* (    else:) Tj T* (        for out in plac.call\(ishelve.main, subcommands\):) Tj T* (            print\(out\)) Tj T*  T* (if __name__ == '__main__':) Tj T* (    plac.call\(main\)) Tj T* ET
 Q
 Q
 Q
@@ -11040,7 +11046,7 @@ Q
 q
 1 0 0 1 62.69291 117.8236 cm
 q
-BT 1 0 0 1 0 28.82 Tm 2.200651 Tw 12 TL /F1 10 Tf 0 0 0 rg (A trick has been used here: the ishelve command-line interface has been hidden inside an external) Tj T* 0 Tw .917674 Tw (interface. They are distinct: for instance the external interface recognizes the ) Tj /F4 10 Tf (-h/--help ) Tj /F1 10 Tf (flag whereas) Tj T* 0 Tw (the internal interface only recognizes the ) Tj /F4 10 Tf (.help ) Tj /F1 10 Tf (command:) Tj T* ET
+BT 1 0 0 1 0 28.82 Tm 2.200651 Tw 12 TL /F1 10 Tf 0 0 0 rg (A trick has been used here: the ishelve command-line interface has been hidden inside an external) Tj T* 0 Tw .917674 Tw (interface. They are distinct: for instance the external interface recognizes the ) Tj /F3 10 Tf (-h/--help ) Tj /F1 10 Tf (flag whereas) Tj T* 0 Tw (the internal interface only recognizes the ) Tj /F3 10 Tf (.help ) Tj /F1 10 Tf (command:) Tj T* ET
 Q
 Q
 q
@@ -11075,7 +11081,7 @@ n -6 -6 468.6898 24 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 5.71 Tm /F4 10 Tf 12 TL ($ python shelve_interpreter.py -h) Tj T* ET
+BT 1 0 0 1 0 5.71 Tm /F3 10 Tf 12 TL ($ python shelve_interpreter.py -h) Tj T* ET
 Q
 Q
 Q
@@ -11096,7 +11102,7 @@ n -6 -6 468.6898 168 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 149.71 Tm /F4 10 Tf 12 TL (usage: shelve_interpreter.py [-h] [-interactive]) Tj T* (                             [subcommands [subcommands ...]]) Tj T*  T* (    This script works both interactively and non-interactively.) Tj T* (    Use .help to see the internal commands.) Tj T* (    ) Tj T*  T* (positional arguments:) Tj T* (  subcommands   the commands of the underlying ishelve interpreter) Tj T*  T* (optional arguments:) Tj T* (  -h, --help    show this help message and exit) Tj T* (  -interactive  start interactive interface) Tj T* ET
+BT 1 0 0 1 0 149.71 Tm /F3 10 Tf 12 TL (usage: shelve_interpreter.py [-h] [-interactive]) Tj T* (                             [subcommands [subcommands ...]]) Tj T*  T* (    This script works both interactively and non-interactively.) Tj T* (    Use .help to see the internal commands.) Tj T* (    ) Tj T*  T* (positional arguments:) Tj T* (  subcommands   the commands of the underlying ishelve interpreter) Tj T*  T* (optional arguments:) Tj T* (  -h, --help    show this help message and exit) Tj T* (  -interactive  start interactive interface) Tj T* ET
 Q
 Q
 Q
@@ -11124,7 +11130,7 @@ n -6 -6 468.6898 36 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 17.71 Tm /F4 10 Tf 12 TL ($ python shelve_interpreter.py .clear # non-interactive use) Tj T* (cleared the shelve) Tj T* ET
+BT 1 0 0 1 0 17.71 Tm /F3 10 Tf 12 TL ($ python shelve_interpreter.py .clear # non-interactive use) Tj T* (cleared the shelve) Tj T* ET
 Q
 Q
 Q
@@ -11151,7 +11157,7 @@ q
 n -6 -6 468.6898 276 re B*
 Q
 q
-BT 1 0 0 1 0 257.71 Tm 12 TL /F4 10 Tf 0 0 0 rg ($ python shelve_interpreter.py -i # interactive use) Tj T* (A simple interface to a shelve. Use .help to see the available commands.) Tj T* (i) Tj (>) Tj ( .help) Tj T* (Commands: .help, .showall, .clear, .delete) Tj T* (<) Tj (param) Tj (>) Tj ( ...) Tj T* (<) Tj (param=value) Tj (>) Tj ( ...) Tj T* (i) Tj (>) Tj ( a=1) Tj T* (setting a=1) Tj T* (i) Tj (>) Tj ( a) Tj T* (1) Tj T* (i) Tj (>) Tj ( b=2) Tj T* (setting b=2) Tj T* (i) Tj (>) Tj ( a b) Tj T* (1) Tj T* (2) Tj T* (i) Tj (>) Tj ( .del a) Tj T* (deleted a) Tj T* (i) Tj (>) Tj ( a) Tj T* (a: not found) Tj T* (i) Tj (>) Tj ( .show) Tj T* (b=2) Tj T* (i) Tj (>) Tj ( [CTRL-D]) Tj T* ET
+BT 1 0 0 1 0 257.71 Tm 12 TL /F3 10 Tf 0 0 0 rg ($ python shelve_interpreter.py -i # interactive use) Tj T* (A simple interface to a shelve. Use .help to see the available commands.) Tj T* (i) Tj (>) Tj ( .help) Tj T* (Commands: .help, .showall, .clear, .delete) Tj T* (<) Tj (param) Tj (>) Tj ( ...) Tj T* (<) Tj (param=value) Tj (>) Tj ( ...) Tj T* (i) Tj (>) Tj ( a=1) Tj T* (setting a=1) Tj T* (i) Tj (>) Tj ( a) Tj T* (1) Tj T* (i) Tj (>) Tj ( b=2) Tj T* (setting b=2) Tj T* (i) Tj (>) Tj ( a b) Tj T* (1) Tj T* (2) Tj T* (i) Tj (>) Tj ( .del a) Tj T* (deleted a) Tj T* (i) Tj (>) Tj ( a) Tj T* (a: not found) Tj T* (i) Tj (>) Tj ( .show) Tj T* (b=2) Tj T* (i) Tj (>) Tj ( [CTRL-D]) Tj T* ET
 Q
 Q
 Q
@@ -11160,13 +11166,13 @@ Q
 q
 1 0 0 1 62.69291 124.2236 cm
 q
-BT 1 0 0 1 0 52.82 Tm .256412 Tw 12 TL /F1 10 Tf 0 0 0 rg (The ) Tj /F4 10 Tf (.interact ) Tj /F1 10 Tf (method reads commands from the console and send them to the underlying interpreter,) Tj T* 0 Tw .065984 Tw (until the user send a CTRL-D command \(CTRL-Z in Windows\). There is a default argument ) Tj /F4 10 Tf (prompt='i) Tj (>) Tj T* 0 Tw .41832 Tw (' ) Tj /F1 10 Tf (which can be used to change the prompt. The text displayed at the beginning of the interactive session) Tj T* 0 Tw 1.407126 Tw (is the docstring of the main function. ) Tj /F4 10 Tf (plac ) Tj /F1 10 Tf (also understands command abbreviations: in this example) Tj T* 0 Tw /F4 10 Tf (del ) Tj /F1 10 Tf (is an abbreviation for ) Tj /F4 10 Tf (delete) Tj /F1 10 Tf (. In case of ambiguous abbreviations ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (raises a ) Tj /F4 10 Tf (NameError) Tj /F1 10 Tf (.) Tj T* ET
+BT 1 0 0 1 0 52.82 Tm .256412 Tw 12 TL /F1 10 Tf 0 0 0 rg (The ) Tj /F3 10 Tf (.interact ) Tj /F1 10 Tf (method reads commands from the console and send them to the underlying interpreter,) Tj T* 0 Tw .065984 Tw (until the user send a CTRL-D command \(CTRL-Z in Windows\). There is a default argument ) Tj /F3 10 Tf (prompt='i) Tj (>) Tj T* 0 Tw .41832 Tw (' ) Tj /F1 10 Tf (which can be used to change the prompt. The text displayed at the beginning of the interactive session) Tj T* 0 Tw 1.407126 Tw (is the docstring of the main function. ) Tj /F3 10 Tf (plac ) Tj /F1 10 Tf (also understands command abbreviations: in this example) Tj T* 0 Tw /F3 10 Tf (del ) Tj /F1 10 Tf (is an abbreviation for ) Tj /F3 10 Tf (delete) Tj /F1 10 Tf (. In case of ambiguous abbreviations ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (raises a ) Tj /F3 10 Tf (NameError) Tj /F1 10 Tf (.) Tj T* ET
 Q
 Q
 q
 1 0 0 1 62.69291 94.22362 cm
 q
-BT 1 0 0 1 0 16.82 Tm .847045 Tw 12 TL /F1 10 Tf 0 0 0 rg (Finally I must notice that the ) Tj /F4 10 Tf (plac.Interpreter ) Tj /F1 10 Tf (is available only if you are using a recent version of) Tj T* 0 Tw (Python \() Tj (>) Tj (= 2.5\), because it is a context manager object which uses extended generators internally.) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm .847045 Tw 12 TL /F1 10 Tf 0 0 0 rg (Finally I must notice that the ) Tj /F3 10 Tf (plac.Interpreter ) Tj /F1 10 Tf (is available only if you are using a recent version of) Tj T* 0 Tw (Python \() Tj (>) Tj (= 2.5\), because it is a context manager object which uses extended generators internally.) Tj T* ET
 Q
 Q
 q
@@ -11202,7 +11208,7 @@ Q
 q
 1 0 0 1 62.69291 699.0236 cm
 q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (In principle, one could write automatic tests for the ) Tj /F4 10 Tf (ishelve ) Tj /F1 10 Tf (application by using ) Tj /F4 10 Tf (plac.call ) Tj /F1 10 Tf (directly:) Tj T* ET
+BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (In principle, one could write automatic tests for the ) Tj /F3 10 Tf (ishelve ) Tj /F1 10 Tf (application by using ) Tj /F3 10 Tf (plac.call ) Tj /F1 10 Tf (directly:) Tj T* ET
 Q
 Q
 q
@@ -11220,7 +11226,7 @@ n -6 -6 468.6898 156 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 137.71 Tm /F4 10 Tf 12 TL (# test_ishelve.py) Tj T* (import plac, ishelve) Tj T*  T* (def test\(\):) Tj T* (    assert plac.call\(ishelve.main, ['.clear']\) == ['cleared the shelve']) Tj T* (    assert plac.call\(ishelve.main, ['a=1']\) == ['setting a=1']) Tj T* (    assert plac.call\(ishelve.main, ['a']\) == ['1']) Tj T* (    assert plac.call\(ishelve.main, ['.delete=a']\) == ['deleted a']) Tj T* (    assert plac.call\(ishelve.main, ['a']\) == ['a: not found']) Tj T*  T* (if __name__ == '__main__':) Tj T* (    test\(\)) Tj T* ET
+BT 1 0 0 1 0 137.71 Tm /F3 10 Tf 12 TL (# test_ishelve.py) Tj T* (import plac, ishelve) Tj T*  T* (def test\(\):) Tj T* (    assert plac.call\(ishelve.main, ['.clear']\) == ['cleared the shelve']) Tj T* (    assert plac.call\(ishelve.main, ['a=1']\) == ['setting a=1']) Tj T* (    assert plac.call\(ishelve.main, ['a']\) == ['1']) Tj T* (    assert plac.call\(ishelve.main, ['.delete=a']\) == ['deleted a']) Tj T* (    assert plac.call\(ishelve.main, ['a']\) == ['a: not found']) Tj T*  T* (if __name__ == '__main__':) Tj T* (    test\(\)) Tj T* ET
 Q
 Q
 Q
@@ -11229,13 +11235,13 @@ Q
 q
 1 0 0 1 62.69291 489.8236 cm
 q
-BT 1 0 0 1 0 28.82 Tm .390651 Tw 12 TL /F1 10 Tf 0 0 0 rg (However, using ) Tj /F4 10 Tf (plac.call ) Tj /F1 10 Tf (is not especially nice. The big issue is that ) Tj /F4 10 Tf (plac.call ) Tj /F1 10 Tf (responds to invalid) Tj T* 0 Tw 1.249987 Tw (input by printing an error message on stderr and by raising a ) Tj /F4 10 Tf (SystemExit) Tj /F1 10 Tf (: this is certainly not a nice) Tj T* 0 Tw (thing to do in a test.) Tj T* ET
+BT 1 0 0 1 0 28.82 Tm .390651 Tw 12 TL /F1 10 Tf 0 0 0 rg (However, using ) Tj /F3 10 Tf (plac.call ) Tj /F1 10 Tf (is not especially nice. The big issue is that ) Tj /F3 10 Tf (plac.call ) Tj /F1 10 Tf (responds to invalid) Tj T* 0 Tw 1.249987 Tw (input by printing an error message on stderr and by raising a ) Tj /F3 10 Tf (SystemExit) Tj /F1 10 Tf (: this is certainly not a nice) Tj T* 0 Tw (thing to do in a test.) Tj T* ET
 Q
 Q
 q
 1 0 0 1 62.69291 447.8236 cm
 q
-BT 1 0 0 1 0 28.82 Tm 1.616457 Tw 12 TL /F1 10 Tf 0 0 0 rg (As a consequence of this behavior it is impossible to test for invalid commands, unless you wrap the) Tj T* 0 Tw .259985 Tw /F4 10 Tf (SystemExit ) Tj /F1 10 Tf (exception by hand each time \(a possibly you do something with the error message in stderr) Tj T* 0 Tw (too\). Luckily, ) Tj /F4 10 Tf (plac ) Tj /F1 10 Tf (offers a better testing support through the ) Tj /F4 10 Tf (check ) Tj /F1 10 Tf (method of ) Tj /F4 10 Tf (Interpreter ) Tj /F1 10 Tf (objects:) Tj T* ET
+BT 1 0 0 1 0 28.82 Tm 1.616457 Tw 12 TL /F1 10 Tf 0 0 0 rg (As a consequence of this behavior it is impossible to test for invalid commands, unless you wrap the) Tj T* 0 Tw .259985 Tw /F3 10 Tf (SystemExit ) Tj /F1 10 Tf (exception by hand each time \(a possibly you do something with the error message in stderr) Tj T* 0 Tw (too\). Luckily, ) Tj /F3 10 Tf (plac ) Tj /F1 10 Tf (offers a better testing support through the ) Tj /F3 10 Tf (check ) Tj /F1 10 Tf (method of ) Tj /F3 10 Tf (Interpreter ) Tj /F1 10 Tf (objects:) Tj T* ET
 Q
 Q
 q
@@ -11253,7 +11259,7 @@ n -6 -6 468.6898 144 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 125.71 Tm /F4 10 Tf 12 TL (# test_ishelve_more.py) Tj T* (from __future__ import with_statement) Tj T* (import plac, ishelve) Tj T*  T* (def test\(\):) Tj T* (    with plac.Interpreter\(ishelve.main\) as i:) Tj T* (        i.check\('.clear', 'cleared the shelve'\)) Tj T* (        i.check\('a=1', 'setting a=1'\)) Tj T* (        i.check\('a', '1'\)) Tj T* (        i.check\('.delete=a', 'deleted a'\)) Tj T* (        i.check\('a', 'a: not found'\)) Tj T* ET
+BT 1 0 0 1 0 125.71 Tm /F3 10 Tf 12 TL (# test_ishelve_more.py) Tj T* (from __future__ import with_statement) Tj T* (import plac, ishelve) Tj T*  T* (def test\(\):) Tj T* (    with plac.Interpreter\(ishelve.main\) as i:) Tj T* (        i.check\('.clear', 'cleared the shelve'\)) Tj T* (        i.check\('a=1', 'setting a=1'\)) Tj T* (        i.check\('a', '1'\)) Tj T* (        i.check\('.delete=a', 'deleted a'\)) Tj T* (        i.check\('a', 'a: not found'\)) Tj T* ET
 Q
 Q
 Q
@@ -11262,19 +11268,19 @@ Q
 q
 1 0 0 1 62.69291 238.6236 cm
 q
-BT 1 0 0 1 0 40.82 Tm 6.299974 Tw 12 TL /F1 10 Tf 0 0 0 rg (The method ) Tj /F4 10 Tf (.check\(given_input, expected_output\) ) Tj /F1 10 Tf (works on strings and raises an) Tj T* 0 Tw .971318 Tw /F4 10 Tf (AssertionError ) Tj /F1 10 Tf (if the output produced by the interpreter is different from the expected output for the) Tj T* 0 Tw 2.186905 Tw (given input. Notice that ) Tj /F4 10 Tf (AssertionError ) Tj /F1 10 Tf (is catched by tools like ) Tj /F4 10 Tf (py.test ) Tj /F1 10 Tf (and ) Tj /F4 10 Tf (nosetests ) Tj /F1 10 Tf (and) Tj T* 0 Tw (actually ) Tj /F4 10 Tf (plac ) Tj /F1 10 Tf (tests are intended to be run with such tools.) Tj T* ET
+BT 1 0 0 1 0 40.82 Tm 6.299974 Tw 12 TL /F1 10 Tf 0 0 0 rg (The method ) Tj /F3 10 Tf (.check\(given_input, expected_output\) ) Tj /F1 10 Tf (works on strings and raises an) Tj T* 0 Tw .971318 Tw /F3 10 Tf (AssertionError ) Tj /F1 10 Tf (if the output produced by the interpreter is different from the expected output for the) Tj T* 0 Tw 2.186905 Tw (given input. Notice that ) Tj /F3 10 Tf (AssertionError ) Tj /F1 10 Tf (is catched by tools like ) Tj /F3 10 Tf (py.test ) Tj /F1 10 Tf (and ) Tj /F3 10 Tf (nosetests ) Tj /F1 10 Tf (and) Tj T* 0 Tw (actually ) Tj /F3 10 Tf (plac ) Tj /F1 10 Tf (tests are intended to be run with such tools.) Tj T* ET
 Q
 Q
 q
 1 0 0 1 62.69291 184.6236 cm
 q
-BT 1 0 0 1 0 40.82 Tm .239984 Tw 12 TL /F1 10 Tf 0 0 0 rg (Interpreters offer a minor syntactic advantage with respect to calling ) Tj /F4 10 Tf (plac.call ) Tj /F1 10 Tf (directly, but they offer a) Tj T* 0 Tw .96748 Tw /F5 10 Tf (major ) Tj /F1 10 Tf (semantic advantage when things go wrong \(read exceptions\): an ) Tj /F4 10 Tf (Interpreter ) Tj /F1 10 Tf (object internally) Tj T* 0 Tw 1.181318 Tw (invokes something like ) Tj /F4 10 Tf (plac.call) Tj /F1 10 Tf (, but it wraps all exceptions, so that ) Tj /F4 10 Tf (i.check ) Tj /F1 10 Tf (is guaranteed not to) Tj T* 0 Tw (raise any exception except ) Tj /F4 10 Tf (AssertionError) Tj /F1 10 Tf (.) Tj T* ET
+BT 1 0 0 1 0 40.82 Tm .239984 Tw 12 TL /F1 10 Tf 0 0 0 rg (Interpreters offer a minor syntactic advantage with respect to calling ) Tj /F3 10 Tf (plac.call ) Tj /F1 10 Tf (directly, but they offer a) Tj T* 0 Tw .96748 Tw /F4 10 Tf (major ) Tj /F1 10 Tf (semantic advantage when things go wrong \(read exceptions\): an ) Tj /F3 10 Tf (Interpreter ) Tj /F1 10 Tf (object internally) Tj T* 0 Tw 1.181318 Tw (invokes something like ) Tj /F3 10 Tf (plac.call) Tj /F1 10 Tf (, but it wraps all exceptions, so that ) Tj /F3 10 Tf (i.check ) Tj /F1 10 Tf (is guaranteed not to) Tj T* 0 Tw (raise any exception except ) Tj /F3 10 Tf (AssertionError) Tj /F1 10 Tf (.) Tj T* ET
 Q
 Q
 q
 1 0 0 1 62.69291 166.6236 cm
 q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (Even the ) Tj /F4 10 Tf (SystemExit ) Tj /F1 10 Tf (exception is captured and you can write your test as) Tj T* ET
+BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (Even the ) Tj /F3 10 Tf (SystemExit ) Tj /F1 10 Tf (exception is captured and you can write your test as) Tj T* ET
 Q
 Q
 q
@@ -11283,13 +11289,13 @@ Q
 q
 1 0 0 1 62.69291 148.6236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 BT 1 0 0 1 0 2 Tm  T* ET
 q
 1 0 0 1 20 0 cm
 q
 0 0 0 rg
-BT 1 0 0 1 0 5.71 Tm /F4 10 Tf 12 TL (i.check\('-cler', 'SystemExit: unrecognized arguments: -cler'\)) Tj T* ET
+BT 1 0 0 1 0 5.71 Tm /F3 10 Tf 12 TL (i.check\('-cler', 'SystemExit: unrecognized arguments: -cler'\)) Tj T* ET
 Q
 Q
 q
@@ -11308,7 +11314,7 @@ Q
 q
 1 0 0 1 62.69291 100.6236 cm
 q
-BT 1 0 0 1 0 16.82 Tm 1.422651 Tw 12 TL /F1 10 Tf 0 0 0 rg (There is a second advantage of interpreters: if the main function contains some initialization code and ) Tj T* 0 Tw .454651 Tw (finalization code \() Tj /F4 10 Tf (__enter__ ) Tj /F1 10 Tf (and ) Tj /F4 10 Tf (__exit__ ) Tj /F1 10 Tf (functions\) they will be run only once at the beginning and) Tj T* 0 Tw ET
+BT 1 0 0 1 0 16.82 Tm 1.422651 Tw 12 TL /F1 10 Tf 0 0 0 rg (There is a second advantage of interpreters: if the main function contains some initialization code and ) Tj T* 0 Tw .454651 Tw (finalization code \() Tj /F3 10 Tf (__enter__ ) Tj /F1 10 Tf (and ) Tj /F3 10 Tf (__exit__ ) Tj /F1 10 Tf (functions\) they will be run only once at the beginning and) Tj T* 0 Tw ET
 Q
 Q
 q
@@ -11331,7 +11337,7 @@ stream
 q
 1 0 0 1 62.69291 753.0236 cm
 q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (at the end of the interpreter loop. ) Tj /F4 10 Tf (plac.call ) Tj /F1 10 Tf (instead ignores the initialization/finalization code.) Tj T* ET
+BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (at the end of the interpreter loop. ) Tj /F3 10 Tf (plac.call ) Tj /F1 10 Tf (instead ignores the initialization/finalization code.) Tj T* ET
 Q
 Q
 q
@@ -11343,13 +11349,13 @@ Q
 q
 1 0 0 1 62.69291 681.0236 cm
 q
-BT 1 0 0 1 0 28.82 Tm 1.517126 Tw 12 TL /F1 10 Tf 0 0 0 rg (Writing your tests in terms of ) Tj /F4 10 Tf (Interpreter.check ) Tj /F1 10 Tf (is certainly an improvement over writing them in) Tj T* 0 Tw 1.807318 Tw (terms of ) Tj /F4 10 Tf (plac.call) Tj /F1 10 Tf (, but they are still too low-level for my taste. The ) Tj /F4 10 Tf (Interpreter ) Tj /F1 10 Tf (class provides) Tj T* 0 Tw (support for doctest-style tests, a.k.a. ) Tj /F5 10 Tf (plac easy tests) Tj /F1 10 Tf (.) Tj T* ET
+BT 1 0 0 1 0 28.82 Tm 1.517126 Tw 12 TL /F1 10 Tf 0 0 0 rg (Writing your tests in terms of ) Tj /F3 10 Tf (Interpreter.check ) Tj /F1 10 Tf (is certainly an improvement over writing them in) Tj T* 0 Tw 1.807318 Tw (terms of ) Tj /F3 10 Tf (plac.call) Tj /F1 10 Tf (, but they are still too low-level for my taste. The ) Tj /F3 10 Tf (Interpreter ) Tj /F1 10 Tf (class provides) Tj T* 0 Tw (support for doctest-style tests, a.k.a. ) Tj /F4 10 Tf (plac easy tests) Tj /F1 10 Tf (.) Tj T* ET
 Q
 Q
 q
 1 0 0 1 62.69291 639.0236 cm
 q
-BT 1 0 0 1 0 28.82 Tm 2.142209 Tw 12 TL /F1 10 Tf 0 0 0 rg (By using plac easy tests you can cut and paste your interactive session and turn it into a runnable) Tj T* 0 Tw .519213 Tw (automatics test. Consider for instance the following file ) Tj /F4 10 Tf (ishelve.placet ) Tj /F1 10 Tf (\(the ) Tj /F4 10 Tf (.placet ) Tj /F1 10 Tf (extension is a) Tj T* 0 Tw (mnemonic for plac easy tests\):) Tj T* ET
+BT 1 0 0 1 0 28.82 Tm 2.142209 Tw 12 TL /F1 10 Tf 0 0 0 rg (By using plac easy tests you can cut and paste your interactive session and turn it into a runnable) Tj T* 0 Tw .519213 Tw (automatics test. Consider for instance the following file ) Tj /F3 10 Tf (ishelve.placet ) Tj /F1 10 Tf (\(the ) Tj /F3 10 Tf (.placet ) Tj /F1 10 Tf (extension is a) Tj T* 0 Tw (mnemonic for plac easy tests\):) Tj T* ET
 Q
 Q
 q
@@ -11366,7 +11372,7 @@ q
 n -6 -6 468.6898 168 re B*
 Q
 q
-BT 1 0 0 1 0 149.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (#!ishelve.py) Tj T* (i) Tj (>) Tj ( .clear # start from a clean state) Tj T* (cleared the shelve) Tj T* (i) Tj (>) Tj ( a=1) Tj T* (setting a=1) Tj T* (i) Tj (>) Tj ( a) Tj T* (1) Tj T* (i) Tj (>) Tj ( .del a) Tj T* (deleted a) Tj T* (i) Tj (>) Tj ( a) Tj T* (a: not found) Tj T* (i) Tj (>) Tj ( .cler # spelling error) Tj T* (.cler: not found) Tj T* ET
+BT 1 0 0 1 0 149.71 Tm 12 TL /F3 10 Tf 0 0 0 rg (#!ishelve.py) Tj T* (i) Tj (>) Tj ( .clear # start from a clean state) Tj T* (cleared the shelve) Tj T* (i) Tj (>) Tj ( a=1) Tj T* (setting a=1) Tj T* (i) Tj (>) Tj ( a) Tj T* (1) Tj T* (i) Tj (>) Tj ( .del a) Tj T* (deleted a) Tj T* (i) Tj (>) Tj ( a) Tj T* (a: not found) Tj T* (i) Tj (>) Tj ( .cler # spelling error) Tj T* (.cler: not found) Tj T* ET
 Q
 Q
 Q
@@ -11375,13 +11381,13 @@ Q
 q
 1 0 0 1 62.69291 405.8236 cm
 q
-BT 1 0 0 1 0 40.82 Tm .697132 Tw 12 TL /F1 10 Tf 0 0 0 rg (Notice the precence of the shebang line containing the name of the ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (tool to test \(a ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (tool is just a) Tj T* 0 Tw 1.511751 Tw (Python module with a function called ) Tj /F4 10 Tf (main) Tj /F1 10 Tf (\). The shebang is ignored by the interpreter \(it looks like a) Tj T* 0 Tw .487608 Tw (comment to it\) but it is there so that external tools \(say a test runner\) can infer the plac interpreter to use) Tj T* 0 Tw (to test the file.) Tj T* ET
+BT 1 0 0 1 0 40.82 Tm .697132 Tw 12 TL /F1 10 Tf 0 0 0 rg (Notice the precence of the shebang line containing the name of the ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (tool to test \(a ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (tool is just a) Tj T* 0 Tw 1.511751 Tw (Python module with a function called ) Tj /F3 10 Tf (main) Tj /F1 10 Tf (\). The shebang is ignored by the interpreter \(it looks like a) Tj T* 0 Tw .487608 Tw (comment to it\) but it is there so that external tools \(say a test runner\) can infer the plac interpreter to use) Tj T* 0 Tw (to test the file.) Tj T* ET
 Q
 Q
 q
 1 0 0 1 62.69291 375.8236 cm
 q
-BT 1 0 0 1 0 16.82 Tm 2.419984 Tw 12 TL /F1 10 Tf 0 0 0 rg (You can test ) Tj /F4 10 Tf (ishelve.placet ) Tj /F1 10 Tf (file by calling the ) Tj /F4 10 Tf (.doctest ) Tj /F1 10 Tf (method of the interpreter, as in this) Tj T* 0 Tw (example:) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm 2.419984 Tw 12 TL /F1 10 Tf 0 0 0 rg (You can test ) Tj /F3 10 Tf (ishelve.placet ) Tj /F1 10 Tf (file by calling the ) Tj /F3 10 Tf (.doctest ) Tj /F1 10 Tf (method of the interpreter, as in this) Tj T* 0 Tw (example:) Tj T* ET
 Q
 Q
 q
@@ -11399,7 +11405,7 @@ n -6 -6 474 36 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 17.71 Tm /F4 10 Tf 12 TL ($ python -c"import plac, ishelve) Tj T* (plac.Interpreter\(ishelve.main\).doctest\(open\('ishelve.placet'\), verbose=True\)") Tj T* ET
+BT 1 0 0 1 0 17.71 Tm /F3 10 Tf 12 TL ($ python -c"import plac, ishelve) Tj T* (plac.Interpreter\(ishelve.main\).doctest\(open\('ishelve.placet'\), verbose=True\)") Tj T* ET
 Q
 Q
 Q
@@ -11408,25 +11414,25 @@ Q
 q
 1 0 0 1 62.69291 287.0393 cm
 q
-BT 1 0 0 1 0 28.82 Tm 4.007109 Tw 12 TL /F1 10 Tf 0 0 0 rg (Internally ) Tj /F4 10 Tf (Interpreter.doctests ) Tj /F1 10 Tf (invokes something like ) Tj /F4 10 Tf (Interpreter.check ) Tj /F1 10 Tf (multiple times) Tj T* 0 Tw .226654 Tw (inside the same context and compare the output with the expected output: if even a check fails, the whole) Tj T* 0 Tw (test fail.) Tj T* ET
+BT 1 0 0 1 0 28.82 Tm 4.007109 Tw 12 TL /F1 10 Tf 0 0 0 rg (Internally ) Tj /F3 10 Tf (Interpreter.doctests ) Tj /F1 10 Tf (invokes something like ) Tj /F3 10 Tf (Interpreter.check ) Tj /F1 10 Tf (multiple times) Tj T* 0 Tw .226654 Tw (inside the same context and compare the output with the expected output: if even a check fails, the whole) Tj T* 0 Tw (test fail.) Tj T* ET
 Q
 Q
 q
 1 0 0 1 62.69291 245.0393 cm
 q
-BT 1 0 0 1 0 28.82 Tm .175868 Tw 12 TL /F1 10 Tf 0 0 0 rg (You should realize tha the easy tests supported by ) Tj /F4 10 Tf (plac ) Tj /F1 10 Tf (are ) Tj /F5 10 Tf (not ) Tj /F1 10 Tf (unittests: they are functional tests. They) Tj T* 0 Tw 1.22936 Tw (model then user interaction and the order of the operations generally matters. The single subtests in a) Tj T* 0 Tw /F4 10 Tf (.placet ) Tj /F1 10 Tf (file are not independent and it makes sense to exit immediately at the first failure.) Tj T* ET
+BT 1 0 0 1 0 28.82 Tm .175868 Tw 12 TL /F1 10 Tf 0 0 0 rg (You should realize tha the easy tests supported by ) Tj /F3 10 Tf (plac ) Tj /F1 10 Tf (are ) Tj /F4 10 Tf (not ) Tj /F1 10 Tf (unittests: they are functional tests. They) Tj T* 0 Tw 1.22936 Tw (model then user interaction and the order of the operations generally matters. The single subtests in a) Tj T* 0 Tw /F3 10 Tf (.placet ) Tj /F1 10 Tf (file are not independent and it makes sense to exit immediately at the first failure.) Tj T* ET
 Q
 Q
 q
 1 0 0 1 62.69291 167.0393 cm
 q
-BT 1 0 0 1 0 64.82 Tm .414431 Tw 12 TL /F1 10 Tf 0 0 0 rg (The support for doctests in ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (comes nearly for free, thanks to the ) Tj 0 0 .501961 rg (shlex ) Tj 0 0 0 rg (module in the standard library,) Tj T* 0 Tw .352765 Tw (which is able to parse simple languages as the ones you can implement with ) Tj 0 0 .501961 rg (plac) Tj 0 0 0 rg (. In particular, thanks to) Tj T* 0 Tw .875984 Tw 0 0 .501961 rg (shlex) Tj 0 0 0 rg (, ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (is able to recognize comments \(the default comment character is ) Tj /F4 10 Tf (#) Tj /F1 10 Tf (\), escape sequences and) Tj T* 0 Tw 1.50686 Tw (more. Look at the ) Tj 0 0 .501961 rg (shlex ) Tj 0 0 0 rg (documentation if you need to customize how the language is interpreted. For) Tj T* 0 Tw 2.794985 Tw (more flexibility, it is even possible to pass to the interpreter a custom split function with signature) Tj T* 0 Tw /F4 10 Tf (split\(line, commentchar\)) Tj /F1 10 Tf (.) Tj T* ET
+BT 1 0 0 1 0 64.82 Tm .414431 Tw 12 TL /F1 10 Tf 0 0 0 rg (The support for doctests in ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (comes nearly for free, thanks to the ) Tj 0 0 .501961 rg (shlex ) Tj 0 0 0 rg (module in the standard library,) Tj T* 0 Tw .352765 Tw (which is able to parse simple languages as the ones you can implement with ) Tj 0 0 .501961 rg (plac) Tj 0 0 0 rg (. In particular, thanks to) Tj T* 0 Tw .875984 Tw 0 0 .501961 rg (shlex) Tj 0 0 0 rg (, ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (is able to recognize comments \(the default comment character is ) Tj /F3 10 Tf (#) Tj /F1 10 Tf (\), escape sequences and) Tj T* 0 Tw 1.50686 Tw (more. Look at the ) Tj 0 0 .501961 rg (shlex ) Tj 0 0 0 rg (documentation if you need to customize how the language is interpreted. For) Tj T* 0 Tw 2.794985 Tw (more flexibility, it is even possible to pass to the interpreter a custom split function with signature) Tj T* 0 Tw /F3 10 Tf (split\(line, commentchar\)) Tj /F1 10 Tf (.) Tj T* ET
 Q
 Q
 q
 1 0 0 1 62.69291 113.0393 cm
 q
-BT 1 0 0 1 0 40.82 Tm .136654 Tw 12 TL /F1 10 Tf 0 0 0 rg (In addition, I have implemented from scratch some support for line number recognition, so that if a test fail) Tj T* 0 Tw .042093 Tw (you get the line number of the failing command. This is especially useful if your tests are stored in external) Tj T* 0 Tw .610898 Tw (files, even if plac easy tests does not need to be in a file: you can just pass to the ) Tj /F4 10 Tf (.doctest ) Tj /F1 10 Tf (method a) Tj T* 0 Tw (list of strings corresponding to the lines of the file.) Tj T* ET
+BT 1 0 0 1 0 40.82 Tm .136654 Tw 12 TL /F1 10 Tf 0 0 0 rg (In addition, I have implemented from scratch some support for line number recognition, so that if a test fail) Tj T* 0 Tw .042093 Tw (you get the line number of the failing command. This is especially useful if your tests are stored in external) Tj T* 0 Tw .610898 Tw (files, even if plac easy tests does not need to be in a file: you can just pass to the ) Tj /F3 10 Tf (.doctest ) Tj /F1 10 Tf (method a) Tj T* 0 Tw (list of strings corresponding to the lines of the file.) Tj T* ET
 Q
 Q
 q
@@ -11455,7 +11461,7 @@ Q
 q
 1 0 0 1 62.69291 711.0236 cm
 q
-BT 1 0 0 1 0 16.82 Tm 1.447318 Tw 12 TL /F1 10 Tf 0 0 0 rg (It is straighforward to integrate your ) Tj /F4 10 Tf (.placet ) Tj /F1 10 Tf (tests with standard testing tools. For instance, you can) Tj T* 0 Tw (integrate your doctests with ) Tj /F4 10 Tf (nose ) Tj /F1 10 Tf (or ) Tj /F4 10 Tf (py.test ) Tj /F1 10 Tf (as follow:) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm 1.447318 Tw 12 TL /F1 10 Tf 0 0 0 rg (It is straighforward to integrate your ) Tj /F3 10 Tf (.placet ) Tj /F1 10 Tf (tests with standard testing tools. For instance, you can) Tj T* 0 Tw (integrate your doctests with ) Tj /F3 10 Tf (nose ) Tj /F1 10 Tf (or ) Tj /F3 10 Tf (py.test ) Tj /F1 10 Tf (as follow:) Tj T* ET
 Q
 Q
 q
@@ -11473,7 +11479,7 @@ n -6 -6 474 180 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 161.71 Tm /F4 10 Tf 12 TL (import os, shlex, plac) Tj T*  T* (def test_doct\(\):) Tj T* (   """) Tj T* (   Find all the doctests in the current directory and run them with the) Tj T* (   corresponding plac interpreter \(the shebang rules!\)) Tj T* (   """) Tj T* (   placets = [f for f in os.listdir\('.'\) if f.endswith\('.placet'\)]) Tj T* (   for placet in placets:) Tj T* (       lines = list\(open\(placet\)\)) Tj T* (       assert lines[0].startswith\('#!'\), 'Missing or incorrect shebang line!') Tj T* (       firstline = lines[0][2:] # strip the shebang) Tj T* (       main = plac.import_main\(*shlex.split\(firstline\)\)) Tj T* (       yield plac.Interpreter\(main\).doctest, lines[1:]) Tj T* ET
+BT 1 0 0 1 0 161.71 Tm /F3 10 Tf 12 TL (import os, shlex, plac) Tj T*  T* (def test_doct\(\):) Tj T* (   """) Tj T* (   Find all the doctests in the current directory and run them with the) Tj T* (   corresponding plac interpreter \(the shebang rules!\)) Tj T* (   """) Tj T* (   placets = [f for f in os.listdir\('.'\) if f.endswith\('.placet'\)]) Tj T* (   for placet in placets:) Tj T* (       lines = list\(open\(placet\)\)) Tj T* (       assert lines[0].startswith\('#!'\), 'Missing or incorrect shebang line!') Tj T* (       firstline = lines[0][2:] # strip the shebang) Tj T* (       main = plac.import_main\(*shlex.split\(firstline\)\)) Tj T* (       yield plac.Interpreter\(main\).doctest, lines[1:]) Tj T* ET
 Q
 Q
 Q
@@ -11482,7 +11488,7 @@ Q
 q
 1 0 0 1 62.69291 443.8485 cm
 q
-BT 1 0 0 1 0 64.82 Tm 1.44811 Tw 12 TL /F1 10 Tf 0 0 0 rg (Here you should notice that usage of ) Tj /F4 10 Tf (plac.import_main) Tj /F1 10 Tf (, an utility which is able to import the main) Tj T* 0 Tw .775703 Tw (function of the script specified in the shebang line. You can use both the full path name of the tool, or a) Tj T* 0 Tw .87686 Tw (relative path name. In this case the runner look at the environment variable ) Tj /F4 10 Tf (PLACPATH ) Tj /F1 10 Tf (and it searches) Tj T* 0 Tw 1.900651 Tw (the plac tool in the directories specified there \() Tj /F4 10 Tf (PLACPATH ) Tj /F1 10 Tf (is just a string containing directory names) Tj T* 0 Tw .56332 Tw (separated by colons\). If the variable ) Tj /F4 10 Tf (PLACPATH ) Tj /F1 10 Tf (is not defined, it just looks in the current directory. If the) Tj T* 0 Tw (plac tool is not found, an ) Tj /F4 10 Tf (ImportError ) Tj /F1 10 Tf (is raised.) Tj T* ET
+BT 1 0 0 1 0 64.82 Tm 1.44811 Tw 12 TL /F1 10 Tf 0 0 0 rg (Here you should notice that usage of ) Tj /F3 10 Tf (plac.import_main) Tj /F1 10 Tf (, an utility which is able to import the main) Tj T* 0 Tw .775703 Tw (function of the script specified in the shebang line. You can use both the full path name of the tool, or a) Tj T* 0 Tw .87686 Tw (relative path name. In this case the runner look at the environment variable ) Tj /F3 10 Tf (PLACPATH ) Tj /F1 10 Tf (and it searches) Tj T* 0 Tw 1.900651 Tw (the plac tool in the directories specified there \() Tj /F3 10 Tf (PLACPATH ) Tj /F1 10 Tf (is just a string containing directory names) Tj T* 0 Tw .56332 Tw (separated by colons\). If the variable ) Tj /F3 10 Tf (PLACPATH ) Tj /F1 10 Tf (is not defined, it just looks in the current directory. If the) Tj T* 0 Tw (plac tool is not found, an ) Tj /F3 10 Tf (ImportError ) Tj /F1 10 Tf (is raised.) Tj T* ET
 Q
 Q
 q
@@ -11494,19 +11500,19 @@ Q
 q
 1 0 0 1 62.69291 371.8485 cm
 q
-BT 1 0 0 1 0 28.82 Tm .772093 Tw 12 TL /F1 10 Tf 0 0 0 rg (It is pretty easy to realize that an interactive interpreter can also be used to run batch scripts: instead of) Tj T* 0 Tw .504692 Tw (reading the commands from the console, it is enough to read the commands from a file. ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (interpreters) Tj T* 0 Tw (provide an ) Tj /F4 10 Tf (.execute ) Tj /F1 10 Tf (method to perform just that.) Tj T* ET
+BT 1 0 0 1 0 28.82 Tm .772093 Tw 12 TL /F1 10 Tf 0 0 0 rg (It is pretty easy to realize that an interactive interpreter can also be used to run batch scripts: instead of) Tj T* 0 Tw .504692 Tw (reading the commands from the console, it is enough to read the commands from a file. ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (interpreters) Tj T* 0 Tw (provide an ) Tj /F3 10 Tf (.execute ) Tj /F1 10 Tf (method to perform just that.) Tj T* ET
 Q
 Q
 q
 1 0 0 1 62.69291 305.8485 cm
 q
-BT 1 0 0 1 0 52.82 Tm .098935 Tw 12 TL /F1 10 Tf 0 0 0 rg (There is just a subtle point to notice: whereas in an interactive loop one wants to manage all exceptions, a) Tj T* 0 Tw 3.866412 Tw (batch script should not in the background in case of unexpected errors. The implementation of) Tj T* 0 Tw .103059 Tw /F4 10 Tf (Interpreter.execute ) Tj /F1 10 Tf (makes sure that any error raised by ) Tj /F4 10 Tf (plac.call ) Tj /F1 10 Tf (internally is re-raised. In other) Tj T* 0 Tw .407045 Tw (words, ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (interpreters ) Tj /F5 10 Tf (wrap the errors, but does not eat them) Tj /F1 10 Tf (: the errors are always accessible and can) Tj T* 0 Tw (be re-raised on demand.) Tj T* ET
+BT 1 0 0 1 0 52.82 Tm .098935 Tw 12 TL /F1 10 Tf 0 0 0 rg (There is just a subtle point to notice: whereas in an interactive loop one wants to manage all exceptions, a) Tj T* 0 Tw 3.866412 Tw (batch script should not in the background in case of unexpected errors. The implementation of) Tj T* 0 Tw .103059 Tw /F3 10 Tf (Interpreter.execute ) Tj /F1 10 Tf (makes sure that any error raised by ) Tj /F3 10 Tf (plac.call ) Tj /F1 10 Tf (internally is re-raised. In other) Tj T* 0 Tw .407045 Tw (words, ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (interpreters ) Tj /F4 10 Tf (wrap the errors, but does not eat them) Tj /F1 10 Tf (: the errors are always accessible and can) Tj T* 0 Tw (be re-raised on demand.) Tj T* ET
 Q
 Q
 q
 1 0 0 1 62.69291 275.8485 cm
 q
-BT 1 0 0 1 0 16.82 Tm 1.239318 Tw 12 TL /F1 10 Tf 0 0 0 rg (The exception is the case of invalid commands, which are skipped. Consider for instance the following) Tj T* 0 Tw (batch file, which contains a mispelled command \() Tj /F4 10 Tf (.dl ) Tj /F1 10 Tf (instead of ) Tj /F4 10 Tf (.del) Tj /F1 10 Tf (\):) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm 1.239318 Tw 12 TL /F1 10 Tf 0 0 0 rg (The exception is the case of invalid commands, which are skipped. Consider for instance the following) Tj T* 0 Tw (batch file, which contains a mispelled command \() Tj /F3 10 Tf (.dl ) Tj /F1 10 Tf (instead of ) Tj /F3 10 Tf (.del) Tj /F1 10 Tf (\):) Tj T* ET
 Q
 Q
 q
@@ -11524,7 +11530,7 @@ n -6 -6 468.6898 96 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 77.71 Tm /F4 10 Tf 12 TL (#!ishelve.py) Tj T* (.clear ) Tj T* (a=1 b=2) Tj T* (.show) Tj T* (.del a) Tj T* (.dl b) Tj T* (.show) Tj T* ET
+BT 1 0 0 1 0 77.71 Tm /F3 10 Tf 12 TL (#!ishelve.py) Tj T* (.clear ) Tj T* (a=1 b=2) Tj T* (.show) Tj T* (.del a) Tj T* (.dl b) Tj T* (.show) Tj T* ET
 Q
 Q
 Q
@@ -11533,7 +11539,7 @@ Q
 q
 1 0 0 1 62.69291 138.6485 cm
 q
-BT 1 0 0 1 0 16.82 Tm 1.939461 Tw 12 TL /F1 10 Tf 0 0 0 rg (If you execute the batch file, the interpreter will print a ) Tj /F4 10 Tf (.dl: not found ) Tj /F1 10 Tf (at the ) Tj /F4 10 Tf (.dl ) Tj /F1 10 Tf (line and will) Tj T* 0 Tw (continue:) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm 1.939461 Tw 12 TL /F1 10 Tf 0 0 0 rg (If you execute the batch file, the interpreter will print a ) Tj /F3 10 Tf (.dl: not found ) Tj /F1 10 Tf (at the ) Tj /F3 10 Tf (.dl ) Tj /F1 10 Tf (line and will) Tj T* 0 Tw (continue:) Tj T* ET
 Q
 Q
 q
@@ -11550,7 +11556,7 @@ q
 n -6 -6 468.6898 36 re B*
 Q
 q
-BT 1 0 0 1 0 17.71 Tm 12 TL /F4 10 Tf 0 0 0 rg ($ python -c "import plac, ishelve) Tj T* (plac.Interpreter\(ishelve.main\).execute\(open\('ishelve.plac'\), verbose=True\)") Tj T* ET
+BT 1 0 0 1 0 17.71 Tm 12 TL /F3 10 Tf 0 0 0 rg ($ python -c "import plac, ishelve) Tj T* (plac.Interpreter\(ishelve.main\).execute\(open\('ishelve.plac'\), verbose=True\)") Tj T* ET
 Q
 Q
 Q
@@ -11587,7 +11593,7 @@ q
 n -6 -6 468.6898 192 re B*
 Q
 q
-BT 1 0 0 1 0 173.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (i) Tj (>) Tj ( .clear) Tj T* (cleared the shelve) Tj T* (i) Tj (>) Tj ( a=1 b=2) Tj T* (setting a=1) Tj T* (setting b=2) Tj T* (i) Tj (>) Tj ( .show) Tj T* (b=2) Tj T* (a=1) Tj T* (i) Tj (>) Tj ( .del a) Tj T* (deleted a) Tj T* (i) Tj (>) Tj ( .dl b) Tj T* (2) Tj T* (.dl: not found) Tj T* (i) Tj (>) Tj ( .show) Tj T* (b=2) Tj T* ET
+BT 1 0 0 1 0 173.71 Tm 12 TL /F3 10 Tf 0 0 0 rg (i) Tj (>) Tj ( .clear) Tj T* (cleared the shelve) Tj T* (i) Tj (>) Tj ( a=1 b=2) Tj T* (setting a=1) Tj T* (setting b=2) Tj T* (i) Tj (>) Tj ( .show) Tj T* (b=2) Tj T* (a=1) Tj T* (i) Tj (>) Tj ( .del a) Tj T* (deleted a) Tj T* (i) Tj (>) Tj ( .dl b) Tj T* (2) Tj T* (.dl: not found) Tj T* (i) Tj (>) Tj ( .show) Tj T* (b=2) Tj T* ET
 Q
 Q
 Q
@@ -11596,7 +11602,7 @@ Q
 q
 1 0 0 1 62.69291 527.8236 cm
 q
-BT 1 0 0 1 0 28.82 Tm .159988 Tw 12 TL /F1 10 Tf 0 0 0 rg (The ) Tj /F4 10 Tf (verbose ) Tj /F1 10 Tf (flag is there to show the lines which are being interpreted \(prefixed by ) Tj /F4 10 Tf (i) Tj (>) Tj /F1 10 Tf (\). This is done on) Tj T* 0 Tw 1.359988 Tw (purpose, so that you can cut and paste the output of the batch script and turn it into a ) Tj /F4 10 Tf (.placet ) Tj /F1 10 Tf (test) Tj T* 0 Tw (\(cool, isn't it?\).) Tj T* ET
+BT 1 0 0 1 0 28.82 Tm .159988 Tw 12 TL /F1 10 Tf 0 0 0 rg (The ) Tj /F3 10 Tf (verbose ) Tj /F1 10 Tf (flag is there to show the lines which are being interpreted \(prefixed by ) Tj /F3 10 Tf (i) Tj (>) Tj /F1 10 Tf (\). This is done on) Tj T* 0 Tw 1.359988 Tw (purpose, so that you can cut and paste the output of the batch script and turn it into a ) Tj /F3 10 Tf (.placet ) Tj /F1 10 Tf (test) Tj T* 0 Tw (\(cool, isn't it?\).) Tj T* ET
 Q
 Q
 q
@@ -11608,19 +11614,19 @@ Q
 q
 1 0 0 1 62.69291 455.8236 cm
 q
-BT 1 0 0 1 0 28.82 Tm 1.182485 Tw 12 TL /F1 10 Tf 0 0 0 rg (When I discussed the ) Tj /F4 10 Tf (ishelve ) Tj /F1 10 Tf (implementation in the ) Tj 0 0 .501961 rg (basic documentation) Tj 0 0 0 rg (, I said that it looked like a) Tj T* 0 Tw .116655 Tw (poor man implementation of an object system as a chain of elifs; I also said that ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (was able to do much) Tj T* 0 Tw (better than that. Here I will substantiate my claim.) Tj T* ET
+BT 1 0 0 1 0 28.82 Tm 1.182485 Tw 12 TL /F1 10 Tf 0 0 0 rg (When I discussed the ) Tj /F3 10 Tf (ishelve ) Tj /F1 10 Tf (implementation in the ) Tj 0 0 .501961 rg (basic documentation) Tj 0 0 0 rg (, I said that it looked like a) Tj T* 0 Tw .116655 Tw (poor man implementation of an object system as a chain of elifs; I also said that ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (was able to do much) Tj T* 0 Tw (better than that. Here I will substantiate my claim.) Tj T* ET
 Q
 Q
 q
 1 0 0 1 62.69291 413.8236 cm
 q
-BT 1 0 0 1 0 28.82 Tm .89104 Tw 12 TL /F1 10 Tf 0 0 .501961 rg (plac ) Tj 0 0 0 rg (is actually able to infer a set of subparsers from a generic container of commands. This is useful if) Tj T* 0 Tw 3.125814 Tw (you want to implement ) Tj /F5 10 Tf (subcommands ) Tj /F1 10 Tf (\(a familiar example of a command-line application featuring) Tj T* 0 Tw (subcommands is subversion\).) Tj T* ET
+BT 1 0 0 1 0 28.82 Tm .89104 Tw 12 TL /F1 10 Tf 0 0 .501961 rg (plac ) Tj 0 0 0 rg (is actually able to infer a set of subparsers from a generic container of commands. This is useful if) Tj T* 0 Tw 3.125814 Tw (you want to implement ) Tj /F4 10 Tf (subcommands ) Tj /F1 10 Tf (\(a familiar example of a command-line application featuring) Tj T* 0 Tw (subcommands is subversion\).) Tj T* ET
 Q
 Q
 q
 1 0 0 1 62.69291 347.8236 cm
 q
-BT 1 0 0 1 0 52.82 Tm .015868 Tw 12 TL /F1 10 Tf 0 0 0 rg (Technically a container of commands is any object with a ) Tj /F4 10 Tf (.commands ) Tj /F1 10 Tf (attribute listing a set of functions or) Tj T* 0 Tw 2.550888 Tw (methods which are valid commands. A command container may have initialization/finalization hooks) Tj T* 0 Tw 2.55664 Tw (\() Tj /F4 10 Tf (__enter__/__exit__) Tj /F1 10 Tf (\) and dispatch hooks \() Tj /F4 10 Tf (__missing__) Tj /F1 10 Tf (, invoked for invalid command names\).) Tj T* 0 Tw 2.113828 Tw (Moreover, only when using command containers ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (is able to provide automatic autocompletion of) Tj T* 0 Tw (commands.) Tj T* ET
+BT 1 0 0 1 0 52.82 Tm .015868 Tw 12 TL /F1 10 Tf 0 0 0 rg (Technically a container of commands is any object with a ) Tj /F3 10 Tf (.commands ) Tj /F1 10 Tf (attribute listing a set of functions or) Tj T* 0 Tw 2.550888 Tw (methods which are valid commands. A command container may have initialization/finalization hooks) Tj T* 0 Tw 2.55664 Tw (\() Tj /F3 10 Tf (__enter__/__exit__) Tj /F1 10 Tf (\) and dispatch hooks \() Tj /F3 10 Tf (__missing__) Tj /F1 10 Tf (, invoked for invalid command names\).) Tj T* 0 Tw 2.113828 Tw (Moreover, only when using command containers ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (is able to provide automatic autocompletion of) Tj T* 0 Tw (commands.) Tj T* ET
 Q
 Q
 q
@@ -11645,7 +11651,7 @@ n -6 -6 468.6898 228 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 209.71 Tm /F4 10 Tf 12 TL (# ishelve2.py) Tj T* (import shelve, os, sys, plac) Tj T*  T* (class ShelveInterface\(object\):) Tj T* (    "A minimal interface over a shelve object.") Tj T* (    commands = 'set', 'show', 'showall', 'delete') Tj T* (    @plac.annotations\() Tj T* (        configfile=\('path name of the shelve', 'option'\)\)) Tj T* (    def __init__\(self, configfile\):) Tj T* (        self.configfile = configfile or '~/conf.shelve') Tj T* (        self.fname = os.path.expanduser\(self.configfile\)) Tj T* (        self.__doc__ += '\\nOperating on %s.\\n.help to see '\\) Tj T* (            'the available commands.\\n'  % self.fname) Tj T* (    def __enter__\(self\):) Tj T* (        self.sh = shelve.open\(self.fname\)) Tj T* (        return self) Tj T* (    def __exit__\(self, etype, exc, tb\):) Tj T* (        self.sh.close\(\)) Tj T* ET
+BT 1 0 0 1 0 209.71 Tm /F3 10 Tf 12 TL (# ishelve2.py) Tj T* (import shelve, os, sys, plac) Tj T*  T* (class ShelveInterface\(object\):) Tj T* (    "A minimal interface over a shelve object.") Tj T* (    commands = 'set', 'show', 'showall', 'delete') Tj T* (    @plac.annotations\() Tj T* (        configfile=\('path name of the shelve', 'option'\)\)) Tj T* (    def __init__\(self, configfile\):) Tj T* (        self.configfile = configfile or '~/conf.shelve') Tj T* (        self.fname = os.path.expanduser\(self.configfile\)) Tj T* (        self.__doc__ += '\\nOperating on %s.\\n.help to see '\\) Tj T* (            'the available commands.\\n'  % self.fname) Tj T* (    def __enter__\(self\):) Tj T* (        self.sh = shelve.open\(self.fname\)) Tj T* (        return self) Tj T* (    def __exit__\(self, etype, exc, tb\):) Tj T* (        self.sh.close\(\)) Tj T* ET
 Q
 Q
 Q
@@ -11683,7 +11689,7 @@ n -6 -6 468.6898 312 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 293.71 Tm /F4 10 Tf 12 TL (    def set\(self, name, value\):) Tj T* (        "set name value") Tj T* (        yield 'setting %s=%s' % \(name, value\)) Tj T* (        self.sh[name] = value) Tj T* (    def show\(self, *names\):) Tj T* (        "show given parameters") Tj T* (        for name in names:) Tj T* (            yield '%s = %s' % \(name, self.sh[name]\) # no error checking) Tj T* (    def showall\(self\):) Tj T* (        "show all parameters") Tj T* (        for name in self.sh:) Tj T* (            yield '%s = %s' % \(name, self.sh[name]\)) Tj T* (    def delete\(self, name=None\):) Tj T* (        "delete given parameter \(or everything\)") Tj T* (        if name is None:) Tj T* (            yield 'deleting everything') Tj T* (            self.sh.clear\(\)) Tj T* (        else:) Tj T* (            yield 'deleting %s' % name) Tj T* (            del self.sh[name] # no error checking) Tj T*  T* (main = ShelveInterface # useful for the tests) Tj T*  T* (if __name__ == '__main__':) Tj T* (    plac.Interpreter\(plac.call\(ShelveInterface\)\).interact\(\)) Tj T* ET
+BT 1 0 0 1 0 293.71 Tm /F3 10 Tf 12 TL (    def set\(self, name, value\):) Tj T* (        "set name value") Tj T* (        yield 'setting %s=%s' % \(name, value\)) Tj T* (        self.sh[name] = value) Tj T* (    def show\(self, *names\):) Tj T* (        "show given parameters") Tj T* (        for name in names:) Tj T* (            yield '%s = %s' % \(name, self.sh[name]\) # no error checking) Tj T* (    def showall\(self\):) Tj T* (        "show all parameters") Tj T* (        for name in self.sh:) Tj T* (            yield '%s = %s' % \(name, self.sh[name]\)) Tj T* (    def delete\(self, name=None\):) Tj T* (        "delete given parameter \(or everything\)") Tj T* (        if name is None:) Tj T* (            yield 'deleting everything') Tj T* (            self.sh.clear\(\)) Tj T* (        else:) Tj T* (            yield 'deleting %s' % name) Tj T* (            del self.sh[name] # no error checking) Tj T*  T* (main = ShelveInterface # useful for the tests) Tj T*  T* (if __name__ == '__main__':) Tj T* (    plac.Interpreter\(plac.call\(ShelveInterface\)\).interact\(\)) Tj T* ET
 Q
 Q
 Q
@@ -11692,13 +11698,13 @@ Q
 q
 1 0 0 1 62.69291 359.8236 cm
 q
-BT 1 0 0 1 0 76.82 Tm .885366 Tw 12 TL /F4 10 Tf 0 0 0 rg (plac.Interpreter ) Tj /F1 10 Tf (objects wrap context manager objects consistently. In other words, if you wrap an) Tj T* 0 Tw 2.323828 Tw (object with ) Tj /F4 10 Tf (__enter__ ) Tj /F1 10 Tf (and ) Tj /F4 10 Tf (__exit__ ) Tj /F1 10 Tf (methods, they are invoked in the right order \() Tj /F4 10 Tf (__enter__) Tj T* 0 Tw .23528 Tw /F1 10 Tf (before the interpreter loop starts and ) Tj /F4 10 Tf (__exit__ ) Tj /F1 10 Tf (after the interpreter loop ends, both in the regular and in) Tj T* 0 Tw 1.916412 Tw (the exceptional case\). In our example, the methods ) Tj /F4 10 Tf (__enter__ ) Tj /F1 10 Tf (and ) Tj /F4 10 Tf (__exit__ ) Tj /F1 10 Tf (make sure the the) Tj T* 0 Tw .339398 Tw (shelve is opened and closed correctly even in the case of exceptions. Notice that I have not implemented) Tj T* 0 Tw .814104 Tw (any error checking in the ) Tj /F4 10 Tf (show ) Tj /F1 10 Tf (and ) Tj /F4 10 Tf (delete ) Tj /F1 10 Tf (methods on purpose, to verify that ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (works correctly in) Tj T* 0 Tw (the presence of exceptions.) Tj T* ET
+BT 1 0 0 1 0 76.82 Tm .885366 Tw 12 TL /F3 10 Tf 0 0 0 rg (plac.Interpreter ) Tj /F1 10 Tf (objects wrap context manager objects consistently. In other words, if you wrap an) Tj T* 0 Tw 2.323828 Tw (object with ) Tj /F3 10 Tf (__enter__ ) Tj /F1 10 Tf (and ) Tj /F3 10 Tf (__exit__ ) Tj /F1 10 Tf (methods, they are invoked in the right order \() Tj /F3 10 Tf (__enter__) Tj T* 0 Tw .23528 Tw /F1 10 Tf (before the interpreter loop starts and ) Tj /F3 10 Tf (__exit__ ) Tj /F1 10 Tf (after the interpreter loop ends, both in the regular and in) Tj T* 0 Tw 1.916412 Tw (the exceptional case\). In our example, the methods ) Tj /F3 10 Tf (__enter__ ) Tj /F1 10 Tf (and ) Tj /F3 10 Tf (__exit__ ) Tj /F1 10 Tf (make sure the the) Tj T* 0 Tw .339398 Tw (shelve is opened and closed correctly even in the case of exceptions. Notice that I have not implemented) Tj T* 0 Tw .814104 Tw (any error checking in the ) Tj /F3 10 Tf (show ) Tj /F1 10 Tf (and ) Tj /F3 10 Tf (delete ) Tj /F1 10 Tf (methods on purpose, to verify that ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (works correctly in) Tj T* 0 Tw (the presence of exceptions.) Tj T* ET
 Q
 Q
 q
 1 0 0 1 62.69291 281.8236 cm
 q
-BT 1 0 0 1 0 64.82 Tm 1.567126 Tw 12 TL /F1 10 Tf 0 0 0 rg (When working with command containers, ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (automatically adds two special commands to the set of) Tj T* 0 Tw 1.176136 Tw (provided commands: ) Tj /F4 10 Tf (.help ) Tj /F1 10 Tf (and ) Tj /F4 10 Tf (.last_tb) Tj /F1 10 Tf (. The ) Tj /F4 10 Tf (.help ) Tj /F1 10 Tf (command is the easier to understand: when) Tj T* 0 Tw .39811 Tw (invoked without arguments it displays the list of available commands with the same formatting of the ) Tj 0 0 .501961 rg (cmd) Tj T* 0 Tw 1.19561 Tw 0 0 0 rg (module; when invoked with the name of a command it displays the usage message for that command.) Tj T* 0 Tw 2.33686 Tw (The ) Tj /F4 10 Tf (.last_tb ) Tj /F1 10 Tf (command is useful when debugging: in case of errors, it allows you to display the) Tj T* 0 Tw (traceback of the last executed command.) Tj T* ET
+BT 1 0 0 1 0 64.82 Tm 1.567126 Tw 12 TL /F1 10 Tf 0 0 0 rg (When working with command containers, ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (automatically adds two special commands to the set of) Tj T* 0 Tw 1.176136 Tw (provided commands: ) Tj /F3 10 Tf (.help ) Tj /F1 10 Tf (and ) Tj /F3 10 Tf (.last_tb) Tj /F1 10 Tf (. The ) Tj /F3 10 Tf (.help ) Tj /F1 10 Tf (command is the easier to understand: when) Tj T* 0 Tw .39811 Tw (invoked without arguments it displays the list of available commands with the same formatting of the ) Tj 0 0 .501961 rg (cmd) Tj T* 0 Tw 1.19561 Tw 0 0 0 rg (module; when invoked with the name of a command it displays the usage message for that command.) Tj T* 0 Tw 2.33686 Tw (The ) Tj /F3 10 Tf (.last_tb ) Tj /F1 10 Tf (command is useful when debugging: in case of errors, it allows you to display the) Tj T* 0 Tw (traceback of the last executed command.) Tj T* ET
 Q
 Q
 q
@@ -11722,7 +11728,7 @@ q
 n -6 -6 468.6898 156 re B*
 Q
 q
-BT 1 0 0 1 0 137.71 Tm 12 TL /F4 10 Tf 0 0 0 rg ($ python ishelve2.py) Tj T* (A minimal interface over a shelve object.) Tj T* (Operating on /home/micheles/conf.shelve.) Tj T* (.help to see the available commands.) Tj T* (i) Tj (>) Tj ( .help) Tj T*  T* (special commands) Tj T* (================) Tj T* (.help .last_tb) Tj T*  T* (custom commands) Tj T* (===============) Tj T* ET
+BT 1 0 0 1 0 137.71 Tm 12 TL /F3 10 Tf 0 0 0 rg ($ python ishelve2.py) Tj T* (A minimal interface over a shelve object.) Tj T* (Operating on /home/micheles/conf.shelve.) Tj T* (.help to see the available commands.) Tj T* (i) Tj (>) Tj ( .help) Tj T*  T* (special commands) Tj T* (================) Tj T* (.help .last_tb) Tj T*  T* (custom commands) Tj T* (===============) Tj T* ET
 Q
 Q
 Q
@@ -11759,7 +11765,7 @@ q
 n -6 -6 606 360 re B*
 Q
 q
-BT 1 0 0 1 0 341.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (delete  set  show  showall) Tj T*  T* (i) Tj (>) Tj ( delete) Tj T* (deleting everything) Tj T* (i) Tj (>) Tj ( set a pippo) Tj T* (setting a=pippo) Tj T* (i) Tj (>) Tj ( set b lippo) Tj T* (setting b=lippo) Tj T* (i) Tj (>) Tj ( showall) Tj T* (b = lippo) Tj T* (a = pippo) Tj T* (i) Tj (>) Tj ( show a b) Tj T* (a = pippo) Tj T* (b = lippo) Tj T* (i) Tj (>) Tj ( del a) Tj T* (deleting a) Tj T* (i) Tj (>) Tj ( showall) Tj T* (b = lippo) Tj T* (i) Tj (>) Tj ( delete a) Tj T* (deleting a) Tj T* (KeyError: 'a') Tj T* (i) Tj (>) Tj ( .last_tb) Tj T* ( File "/usr/local/lib/python2.6/dist-packages/plac-0.6.0-py2.6.egg/plac_ext.py", line 190, in _wrap) Tj T* (    for value in genobj:) Tj T* (  File "./ishelve2.py", line 37, in delete) Tj T* (    del self.sh[name] # no error checking) Tj T* (  File "/usr/lib/python2.6/shelve.py", line 136, in __delitem__) Tj T* (    del self.dict[key]) Tj T* (i) Tj (>) Tj T* ET
+BT 1 0 0 1 0 341.71 Tm 12 TL /F3 10 Tf 0 0 0 rg (delete  set  show  showall) Tj T*  T* (i) Tj (>) Tj ( delete) Tj T* (deleting everything) Tj T* (i) Tj (>) Tj ( set a pippo) Tj T* (setting a=pippo) Tj T* (i) Tj (>) Tj ( set b lippo) Tj T* (setting b=lippo) Tj T* (i) Tj (>) Tj ( showall) Tj T* (b = lippo) Tj T* (a = pippo) Tj T* (i) Tj (>) Tj ( show a b) Tj T* (a = pippo) Tj T* (b = lippo) Tj T* (i) Tj (>) Tj ( del a) Tj T* (deleting a) Tj T* (i) Tj (>) Tj ( showall) Tj T* (b = lippo) Tj T* (i) Tj (>) Tj ( delete a) Tj T* (deleting a) Tj T* (KeyError: 'a') Tj T* (i) Tj (>) Tj ( .last_tb) Tj T* ( File "/usr/local/lib/python2.6/dist-packages/plac-0.6.0-py2.6.egg/plac_ext.py", line 190, in _wrap) Tj T* (    for value in genobj:) Tj T* (  File "./ishelve2.py", line 37, in delete) Tj T* (    del self.sh[name] # no error checking) Tj T* (  File "/usr/lib/python2.6/shelve.py", line 136, in __delitem__) Tj T* (    del self.dict[key]) Tj T* (i) Tj (>) Tj T* ET
 Q
 Q
 Q
@@ -11768,7 +11774,7 @@ Q
 q
 1 0 0 1 62.69291 453.5042 cm
 q
-BT 1 0 0 1 0 16.82 Tm 2.571235 Tw 12 TL /F1 10 Tf 0 0 0 rg (Notice that in interactive mode the traceback is hidden, unless you pass the ) Tj /F4 10 Tf (verbose ) Tj /F1 10 Tf (flag to the) Tj T* 0 Tw /F4 10 Tf (Interpreter.interact ) Tj /F1 10 Tf (method.) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm 2.571235 Tw 12 TL /F1 10 Tf 0 0 0 rg (Notice that in interactive mode the traceback is hidden, unless you pass the ) Tj /F3 10 Tf (verbose ) Tj /F1 10 Tf (flag to the) Tj T* 0 Tw /F3 10 Tf (Interpreter.interact ) Tj /F1 10 Tf (method.) Tj T* ET
 Q
 Q
 q
@@ -11780,7 +11786,7 @@ Q
 q
 1 0 0 1 62.69291 381.5042 cm
 q
-BT 1 0 0 1 0 28.82 Tm 1.066303 Tw 12 TL /F1 10 Tf 0 0 0 rg (At the core of ) Tj /F4 10 Tf (plac ) Tj /F1 10 Tf (there is the ) Tj /F4 10 Tf (call ) Tj /F1 10 Tf (function which invokes a callable with the list of the arguments) Tj T* 0 Tw .937674 Tw (passed at the command-line \() Tj /F4 10 Tf (sys.argv[1:]) Tj /F1 10 Tf (\). Thanks to ) Tj /F4 10 Tf (plac.call ) Tj /F1 10 Tf (you can launch your module by) Tj T* 0 Tw (simply adding the lines:) Tj T* ET
+BT 1 0 0 1 0 28.82 Tm 1.066303 Tw 12 TL /F1 10 Tf 0 0 0 rg (At the core of ) Tj /F3 10 Tf (plac ) Tj /F1 10 Tf (there is the ) Tj /F3 10 Tf (call ) Tj /F1 10 Tf (function which invokes a callable with the list of the arguments) Tj T* 0 Tw .937674 Tw (passed at the command-line \() Tj /F3 10 Tf (sys.argv[1:]) Tj /F1 10 Tf (\). Thanks to ) Tj /F3 10 Tf (plac.call ) Tj /F1 10 Tf (you can launch your module by) Tj T* 0 Tw (simply adding the lines:) Tj T* ET
 Q
 Q
 q
@@ -11798,7 +11804,7 @@ n -6 -6 468.6898 36 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 17.71 Tm /F4 10 Tf 12 TL (if __name__ == '__main__':) Tj T* (    plac.call\(main\)) Tj T* ET
+BT 1 0 0 1 0 17.71 Tm /F3 10 Tf 12 TL (if __name__ == '__main__':) Tj T* (    plac.call\(main\)) Tj T* ET
 Q
 Q
 Q
@@ -11807,7 +11813,7 @@ Q
 q
 1 0 0 1 62.69291 280.3042 cm
 q
-BT 1 0 0 1 0 40.82 Tm .50436 Tw 12 TL /F1 10 Tf 0 0 0 rg (Everything works fine if ) Tj /F4 10 Tf (main ) Tj /F1 10 Tf (is a simple callable performing some action; however, in many cases, one) Tj T* 0 Tw .087633 Tw (has a ) Tj /F4 10 Tf (main ) Tj /F1 10 Tf ("function" which is a actually a factory returning a command container object. For instance, in) Tj T* 0 Tw .573318 Tw (my second shelve example the main function is the class ) Tj /F4 10 Tf (ShelveInterface) Tj /F1 10 Tf (, and the two lines needed) Tj T* 0 Tw (to run the module are a bit ugly:) Tj T* ET
+BT 1 0 0 1 0 40.82 Tm .50436 Tw 12 TL /F1 10 Tf 0 0 0 rg (Everything works fine if ) Tj /F3 10 Tf (main ) Tj /F1 10 Tf (is a simple callable performing some action; however, in many cases, one) Tj T* 0 Tw .087633 Tw (has a ) Tj /F3 10 Tf (main ) Tj /F1 10 Tf ("function" which is a actually a factory returning a command container object. For instance, in) Tj T* 0 Tw .573318 Tw (my second shelve example the main function is the class ) Tj /F3 10 Tf (ShelveInterface) Tj /F1 10 Tf (, and the two lines needed) Tj T* 0 Tw (to run the module are a bit ugly:) Tj T* ET
 Q
 Q
 q
@@ -11825,7 +11831,7 @@ n -6 -6 468.6898 36 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 17.71 Tm /F4 10 Tf 12 TL (if __name__ == '__main__':) Tj T* (   plac.Interpreter\(plac.call\(ShelveInterface\)\).interact\(\)) Tj T* ET
+BT 1 0 0 1 0 17.71 Tm /F3 10 Tf 12 TL (if __name__ == '__main__':) Tj T* (   plac.Interpreter\(plac.call\(ShelveInterface\)\).interact\(\)) Tj T* ET
 Q
 Q
 Q
@@ -11834,7 +11840,7 @@ Q
 q
 1 0 0 1 62.69291 131.1042 cm
 q
-BT 1 0 0 1 0 88.82 Tm .435227 Tw 12 TL /F1 10 Tf 0 0 0 rg (Moreover, now the program runs, but only in interactive mode, i.e. it is not possible to run it as a script. It) Tj T* 0 Tw .721098 Tw (would be nice instead to be able to specify the command to execute on the command-line and have the) Tj T* 0 Tw 4.08229 Tw (interpreter start, execute the command and finish properly \(I mean by calling ) Tj /F4 10 Tf (__enter__ ) Tj /F1 10 Tf (and) Tj T* 0 Tw .427633 Tw /F4 10 Tf (__exit__) Tj /F1 10 Tf (\) without needing user input. The the script could be called from a batch shell script working in) Tj T* 0 Tw 2.26816 Tw (the background. In order to provide such functionality ) Tj /F4 10 Tf (plac.Interpreter ) Tj /F1 10 Tf (provides a classmethod) Tj T* 0 Tw 1.173318 Tw (named ) Tj /F4 10 Tf (.call ) Tj /F1 10 Tf (which takes the factory, instantiates it with the arguments read from the command line,) Tj T* 0 Tw 1.517045 Tw (wraps the resulting container object as an interpreter and runs it with the rest arguments found in the) Tj T* 0 Tw (command line. Here is the code to turn the ) Tj /F4 10 Tf (ShelveInterface ) Tj /F1 10 Tf (into a script) Tj T* ET
+BT 1 0 0 1 0 88.82 Tm .435227 Tw 12 TL /F1 10 Tf 0 0 0 rg (Moreover, now the program runs, but only in interactive mode, i.e. it is not possible to run it as a script. It) Tj T* 0 Tw .721098 Tw (would be nice instead to be able to specify the command to execute on the command-line and have the) Tj T* 0 Tw 4.08229 Tw (interpreter start, execute the command and finish properly \(I mean by calling ) Tj /F3 10 Tf (__enter__ ) Tj /F1 10 Tf (and) Tj T* 0 Tw .427633 Tw /F3 10 Tf (__exit__) Tj /F1 10 Tf (\) without needing user input. The the script could be called from a batch shell script working in) Tj T* 0 Tw 2.26816 Tw (the background. In order to provide such functionality ) Tj /F3 10 Tf (plac.Interpreter ) Tj /F1 10 Tf (provides a classmethod) Tj T* 0 Tw 1.173318 Tw (named ) Tj /F3 10 Tf (.call ) Tj /F1 10 Tf (which takes the factory, instantiates it with the arguments read from the command line,) Tj T* 0 Tw 1.517045 Tw (wraps the resulting container object as an interpreter and runs it with the rest arguments found in the) Tj T* 0 Tw (command line. Here is the code to turn the ) Tj /F3 10 Tf (ShelveInterface ) Tj /F1 10 Tf (into a script) Tj T* ET
 Q
 Q
 q
@@ -11851,7 +11857,7 @@ endobj
 % 'R440': class PDFStream 
 440 0 obj
 % page stream
-<< /Length 4534 >>
+<< /Length 4143 >>
 stream
 1 0 0 1 0 0 cm BT /F1 12 Tf 14.4 TL ET
 q
@@ -11869,7 +11875,7 @@ n -6 -6 468.6898 72 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 53.71 Tm /F4 10 Tf 12 TL (# ishelve3.py) Tj T* (from ishelve2 import ShelveInterface as main) Tj T*  T* (if __name__ == '__main__':) Tj T* (    import plac; plac.Interpreter.call\(main\)) Tj T* ET
+BT 1 0 0 1 0 53.71 Tm /F3 10 Tf 12 TL (# ishelve3.py) Tj T* (from ishelve2 import ShelveInterface as main) Tj T*  T* (if __name__ == '__main__':) Tj T* (    import plac; plac.Interpreter.call\(main\)) Tj T* ET
 Q
 Q
 Q
@@ -11883,28 +11889,7 @@ BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL (and here are a few examples of usage:) Tj
 Q
 Q
 q
-1 0 0 1 62.69291 638.6236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 24 re B*
-Q
-q
-0 0 0 rg
-BT 1 0 0 1 0 5.71 Tm /F4 10 Tf 12 TL ($ python ishelve3.py -h) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 521.4236 cm
+1 0 0 1 62.69291 458.6236 cm
 q
 q
 1 0 0 1 0 0 cm
@@ -11914,46 +11899,24 @@ q
 .662745 .662745 .662745 RG
 .5 w
 .960784 .960784 .862745 rg
-n -6 -6 468.6898 108 re B*
-Q
-q
-0 0 0 rg
-BT 1 0 0 1 0 89.71 Tm /F4 10 Tf 12 TL (usage: ishelve3.py [-h] [-configfile CONFIGFILE]) Tj T*  T* (A minimal interface over a shelve object.) Tj T*  T* (optional arguments:) Tj T* (  -h, --help            show this help message and exit) Tj T* (  -configfile CONFIGFILE) Tj T* (                        path name of the shelve) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 452.2236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 60 re B*
+n -6 -6 468.6898 204 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 41.71 Tm /F4 10 Tf 12 TL ($ python ishelve3.py set a 1) Tj T* (setting a=1) Tj T* ($ python ishelve3.py show a) Tj T* (a = 1) Tj T* ET
+BT 1 0 0 1 0 185.71 Tm /F3 10 Tf 12 TL ($ python ishelve3.py -h) Tj T* (usage: ishelve3.py [-h] [-i] [-configfile CONFIGFILE] [args [args ...]]) Tj T*  T* (positional arguments:) Tj T* (  args) Tj T*  T* (optional arguments:) Tj T* (  -h, --help            show this help message and exit) Tj T* (  -i, --interact        start interactive interpreter) Tj T* (  -configfile CONFIGFILE) Tj T* (                        path name of the shelve) Tj T*  T* ($ python ishelve3.py set a 1) Tj T* (setting a=1) Tj T* ($ python ishelve3.py show a) Tj T* (a = 1) Tj T* ET
 Q
 Q
 Q
 Q
 Q
 q
-1 0 0 1 62.69291 420.2236 cm
+1 0 0 1 62.69291 426.6236 cm
 q
-0 0 0 rg
-BT 1 0 0 1 0 16.82 Tm /F1 10 Tf 12 TL 1.77881 Tw (If you do not pass enough arguments in the command line, then the script will automatically enter in) Tj T* 0 Tw (interactive mode and ask the user for the command to execute:) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm .079989 Tw 12 TL /F1 10 Tf 0 0 0 rg (If you pass the ) Tj /F3 10 Tf (-i ) Tj /F1 10 Tf (flag in the command line, then the script will enter in interactive mode and ask the user) Tj T* 0 Tw (for the commands to execute:) Tj T* ET
 Q
 Q
 q
-1 0 0 1 62.69291 327.0236 cm
+1 0 0 1 62.69291 333.4236 cm
 q
 q
 1 0 0 1 0 0 cm
@@ -11966,26 +11929,26 @@ q
 n -6 -6 468.6898 84 re B*
 Q
 q
-BT 1 0 0 1 0 65.71 Tm 12 TL /F4 10 Tf 0 0 0 rg ($ python ishelve3.py) Tj T* (A minimal interface over a shelve object.) Tj T* (Operating on /home/micheles/conf.shelve.) Tj T* (.help to see the available commands.) Tj T*  T* (i) Tj (>) Tj T* ET
+BT 1 0 0 1 0 65.71 Tm 12 TL /F3 10 Tf 0 0 0 rg ($ python ishelve3.py -i) Tj T* (A minimal interface over a shelve object.) Tj T* (Operating on /home/micheles/conf.shelve.) Tj T* (.help to see the available commands.) Tj T*  T* (i) Tj (>) Tj T* ET
 Q
 Q
 Q
 Q
 Q
 q
-1 0 0 1 62.69291 283.0236 cm
+1 0 0 1 62.69291 289.4236 cm
 q
-BT 1 0 0 1 0 28.82 Tm .221417 Tw 12 TL /F1 10 Tf 0 0 0 rg (In a sense, I have closed the circle: at the beginning of this document I discussed how to turn a script into) Tj T* 0 Tw .784147 Tw (an interactive application \(the ) Tj /F4 10 Tf (shelve_interpreter.py ) Tj /F1 10 Tf (example\), whereas here I have show how to) Tj T* 0 Tw (turn an interactive application into a script.) Tj T* ET
+BT 1 0 0 1 0 28.82 Tm .221417 Tw 12 TL /F1 10 Tf 0 0 0 rg (In a sense, I have closed the circle: at the beginning of this document I discussed how to turn a script into) Tj T* 0 Tw .784147 Tw (an interactive application \(the ) Tj /F3 10 Tf (shelve_interpreter.py ) Tj /F1 10 Tf (example\), whereas here I have show how to) Tj T* 0 Tw (turn an interactive application into a script.) Tj T* ET
 Q
 Q
 q
-1 0 0 1 62.69291 265.0236 cm
+1 0 0 1 62.69291 271.4236 cm
 q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (The complete signature of ) Tj /F4 10 Tf (plac.Interpreter.call ) Tj /F1 10 Tf (is the following:) Tj T* ET
+BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (The complete signature of ) Tj /F3 10 Tf (plac.Interpreter.call ) Tj /F1 10 Tf (is the following:) Tj T* ET
 Q
 Q
 q
-1 0 0 1 62.69291 207.8236 cm
+1 0 0 1 62.69291 214.2236 cm
 q
 q
 1 0 0 1 0 0 cm
@@ -11998,16 +11961,16 @@ q
 n -6 -6 468.6898 48 re B*
 Q
 q
-BT 1 0 0 1 0 29.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (call\(factory, arglist=sys.argv[1:],) Tj T* (     commentchar='#', split=shlex.split,) Tj T* (     stdin=sys.stdin, prompt='i) Tj (>) Tj ( ', verbose=False\)) Tj T* ET
+BT 1 0 0 1 0 29.71 Tm 12 TL /F3 10 Tf 0 0 0 rg (call\(factory, arglist=sys.argv[1:],) Tj T* (     commentchar='#', split=shlex.split,) Tj T* (     stdin=sys.stdin, prompt='i) Tj (>) Tj ( ', verbose=False\)) Tj T* ET
 Q
 Q
 Q
 Q
 Q
 q
-1 0 0 1 62.69291 127.8236 cm
+1 0 0 1 62.69291 134.2236 cm
 q
-BT 1 0 0 1 0 64.82 Tm 1.756651 Tw 12 TL /F1 10 Tf 0 0 0 rg (The factory must have a fixed number of positional arguments \(no default arguments, no varargs, no) Tj T* 0 Tw 1.87881 Tw (kwargs\), otherwise a ) Tj /F4 10 Tf (TypeError ) Tj /F1 10 Tf (is raised: the reason is that we want to be able to distinguish the) Tj T* 0 Tw .829984 Tw (command-line arguments needed to instantiate the factory from the rest arguments that must be sent to) Tj T* 0 Tw 2.609984 Tw (the corresponding interpreter object. It is also possible to specify a list of arguments different from) Tj T* 0 Tw .513318 Tw /F4 10 Tf (sys.argv[1:] ) Tj /F1 10 Tf (\(useful in tests\), the character to be recognized as a comment, the splitting function, the) Tj T* 0 Tw (input source and the prompt to use while in interactive mode, and a verbose flag.) Tj T* ET
+BT 1 0 0 1 0 64.82 Tm 1.756651 Tw 12 TL /F1 10 Tf 0 0 0 rg (The factory must have a fixed number of positional arguments \(no default arguments, no varargs, no) Tj T* 0 Tw 1.87881 Tw (kwargs\), otherwise a ) Tj /F3 10 Tf (TypeError ) Tj /F1 10 Tf (is raised: the reason is that we want to be able to distinguish the) Tj T* 0 Tw .829984 Tw (command-line arguments needed to instantiate the factory from the rest arguments that must be sent to) Tj T* 0 Tw 2.609984 Tw (the corresponding interpreter object. It is also possible to specify a list of arguments different from) Tj T* 0 Tw .513318 Tw /F3 10 Tf (sys.argv[1:] ) Tj /F1 10 Tf (\(useful in tests\), the character to be recognized as a comment, the splitting function, the) Tj T* 0 Tw (input source and the prompt to use while in interactive mode, and a verbose flag.) Tj T* ET
 Q
 Q
 q
@@ -12036,7 +11999,7 @@ Q
 q
 1 0 0 1 62.69291 669.0236 cm
 q
-BT 1 0 0 1 0 64.82 Tm 1.022485 Tw 12 TL /F1 10 Tf 0 0 0 rg (Starting from release 0.6 ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (offers full readline support. That means that if your Python was compiled) Tj T* 0 Tw 2.120697 Tw (with readline support you get autocompletion and persistent command history for free. By default all) Tj T* 0 Tw .144104 Tw (commands are autocomplete in a case sensitive way. If you want to add new words to the autocompletion) Tj T* 0 Tw .116488 Tw (set, or you want to change the location of the ) Tj /F4 10 Tf (.history ) Tj /F1 10 Tf (file, or to change the case sensitivity, the way to) Tj T* 0 Tw .18436 Tw (go is to pass a ) Tj /F4 10 Tf (plac.ReadlineInput ) Tj /F1 10 Tf (object to the interpreter. Here is an example, assuming you want) Tj T* 0 Tw (to build a database interface understanding SQL commands:) Tj T* ET
+BT 1 0 0 1 0 64.82 Tm 1.022485 Tw 12 TL /F1 10 Tf 0 0 0 rg (Starting from release 0.6 ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (offers full readline support. That means that if your Python was compiled) Tj T* 0 Tw 2.120697 Tw (with readline support you get autocompletion and persistent command history for free. By default all) Tj T* 0 Tw .144104 Tw (commands are autocomplete in a case sensitive way. If you want to add new words to the autocompletion) Tj T* 0 Tw .116488 Tw (set, or you want to change the location of the ) Tj /F3 10 Tf (.history ) Tj /F1 10 Tf (file, or to change the case sensitivity, the way to) Tj T* 0 Tw .18436 Tw (go is to pass a ) Tj /F3 10 Tf (plac.ReadlineInput ) Tj /F1 10 Tf (object to the interpreter. Here is an example, assuming you want) Tj T* 0 Tw (to build a database interface understanding SQL commands:) Tj T* ET
 Q
 Q
 q
@@ -12053,7 +12016,7 @@ q
 n -6 -6 486 348 re B*
 Q
 q
-BT 1 0 0 1 0 329.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (import os, plac) Tj T* (from sqlalchemy.ext.sqlsoup import SqlSoup) Tj T*  T* (SQLKEYWORDS = set\(['select', 'from', 'inner', 'join', 'outer', 'left', 'right']) Tj T* (                  \) # and many others) Tj T* (DBTABLES = set\(['table1', 'table2']\) # you can read them from the db schema) Tj T*  T* (COMPLETIONS = SQLKEYWORDS | DBTABLES) Tj T*  T* (class SqlInterface\(object\):) Tj T* (    commands = ['SELECT']) Tj T* (    def __init__\(self, dsn\):) Tj T* (        self.soup = SqlSoup\(dsn\)) Tj T* (    def SELECT\(self, argstring\):) Tj T* (        sql = 'SELECT ' + argstring) Tj T* (        for row in self.soup.bind.execute\(sql\):) Tj T* (            yield str\(row\) # the formatting can be much improved) Tj T*  T* (rl_input = plac.ReadlineInput\() Tj T* (    COMPLETIONS, histfile=os.path.expanduser\('~/.sql_interface.history'\), ) Tj T* (    case_sensitive=False\)) Tj T*  T* (def split_on_first_space\(line, commentchar\):) Tj T* (    return line.strip\(\).split\(' ', 1\) # ignoring comments) Tj T* (    ) Tj T* (if __name__ == '__main__':) Tj T* (    plac.Interpreter.call\(SqlInterface, split=split_on_first_space,) Tj T* (                          stdin=rl_input, prompt='sql) Tj (>) Tj ( '\)) Tj T* ET
+BT 1 0 0 1 0 329.71 Tm 12 TL /F3 10 Tf 0 0 0 rg (import os, plac) Tj T* (from sqlalchemy.ext.sqlsoup import SqlSoup) Tj T*  T* (SQLKEYWORDS = set\(['select', 'from', 'inner', 'join', 'outer', 'left', 'right']) Tj T* (                  \) # and many others) Tj T* (DBTABLES = set\(['table1', 'table2']\) # you can read them from the db schema) Tj T*  T* (COMPLETIONS = SQLKEYWORDS | DBTABLES) Tj T*  T* (class SqlInterface\(object\):) Tj T* (    commands = ['SELECT']) Tj T* (    def __init__\(self, dsn\):) Tj T* (        self.soup = SqlSoup\(dsn\)) Tj T* (    def SELECT\(self, argstring\):) Tj T* (        sql = 'SELECT ' + argstring) Tj T* (        for row in self.soup.bind.execute\(sql\):) Tj T* (            yield str\(row\) # the formatting can be much improved) Tj T*  T* (rl_input = plac.ReadlineInput\() Tj T* (    COMPLETIONS, histfile=os.path.expanduser\('~/.sql_interface.history'\), ) Tj T* (    case_sensitive=False\)) Tj T*  T* (def split_on_first_space\(line, commentchar\):) Tj T* (    return line.strip\(\).split\(' ', 1\) # ignoring comments) Tj T* (    ) Tj T* (if __name__ == '__main__':) Tj T* (    plac.Interpreter.call\(SqlInterface, split=split_on_first_space,) Tj T* (                          stdin=rl_input, prompt='sql) Tj (>) Tj ( '\)) Tj T* ET
 Q
 Q
 Q
@@ -12080,7 +12043,7 @@ q
 n -6 -6 468.6898 48 re B*
 Q
 q
-BT 1 0 0 1 0 29.71 Tm 12 TL /F4 10 Tf 0 0 0 rg ($ python sql_interface.py ) Tj (<) Tj (some dsn) Tj (>) Tj  T* (sql) Tj (>) Tj ( SELECT a.* FROM TABLE1 AS a INNER JOIN TABLE2 AS b ON a.id = b.id) Tj T* (...) Tj T* ET
+BT 1 0 0 1 0 29.71 Tm 12 TL /F3 10 Tf 0 0 0 rg ($ python sql_interface.py ) Tj (<) Tj (some dsn) Tj (>) Tj  T* (sql) Tj (>) Tj ( SELECT a.* FROM TABLE1 AS a INNER JOIN TABLE2 AS b ON a.id = b.id) Tj T* (...) Tj T* ET
 Q
 Q
 Q
@@ -12089,7 +12052,7 @@ Q
 q
 1 0 0 1 62.69291 167.0307 cm
 q
-BT 1 0 0 1 0 64.82 Tm 1.951318 Tw 12 TL /F1 10 Tf 0 0 0 rg (You can check that entering just ) Tj /F4 10 Tf (sel ) Tj /F1 10 Tf (and pressing TAB the readline library completes the ) Tj /F4 10 Tf (SELECT) Tj T* 0 Tw .797356 Tw /F1 10 Tf (keyword for you and makes it upper case; idem for ) Tj /F4 10 Tf (FROM) Tj /F1 10 Tf (, ) Tj /F4 10 Tf (INNER) Tj /F1 10 Tf (, ) Tj /F4 10 Tf (JOIN ) Tj /F1 10 Tf (and even for the names of the) Tj T* 0 Tw .256235 Tw (tables. An obvious improvement is to read the names of the tables by introspecting the database: actually) Tj T* 0 Tw 1.616654 Tw (you can even read the names of the views and of the columns, and have full autocompletion. All the) Tj T* 0 Tw 2.047251 Tw (entered commands and recorded and saved in the file ) Tj /F4 10 Tf (~/.sql_interface.history ) Tj /F1 10 Tf (when exiting) Tj T* 0 Tw (from the command-line interface.) Tj T* ET
+BT 1 0 0 1 0 64.82 Tm 1.951318 Tw 12 TL /F1 10 Tf 0 0 0 rg (You can check that entering just ) Tj /F3 10 Tf (sel ) Tj /F1 10 Tf (and pressing TAB the readline library completes the ) Tj /F3 10 Tf (SELECT) Tj T* 0 Tw .797356 Tw /F1 10 Tf (keyword for you and makes it upper case; idem for ) Tj /F3 10 Tf (FROM) Tj /F1 10 Tf (, ) Tj /F3 10 Tf (INNER) Tj /F1 10 Tf (, ) Tj /F3 10 Tf (JOIN ) Tj /F1 10 Tf (and even for the names of the) Tj T* 0 Tw .256235 Tw (tables. An obvious improvement is to read the names of the tables by introspecting the database: actually) Tj T* 0 Tw 1.616654 Tw (you can even read the names of the views and of the columns, and have full autocompletion. All the) Tj T* 0 Tw 2.047251 Tw (entered commands and recorded and saved in the file ) Tj /F3 10 Tf (~/.sql_interface.history ) Tj /F1 10 Tf (when exiting) Tj T* 0 Tw (from the command-line interface.) Tj T* ET
 Q
 Q
 q
@@ -12118,7 +12081,7 @@ stream
 q
 1 0 0 1 62.69291 729.0236 cm
 q
-BT 1 0 0 1 0 28.82 Tm .187882 Tw 12 TL /F1 10 Tf 0 0 0 rg (The interactive mode of ) Tj /F4 10 Tf (plac ) Tj /F1 10 Tf (can be used as a replacement of the ) Tj 0 0 .501961 rg (cmd ) Tj 0 0 0 rg (module in the standard library. It) Tj T* 0 Tw 2.730651 Tw (is actually better than ) Tj 0 0 .501961 rg (cmd) Tj 0 0 0 rg (: for instance, the ) Tj /F4 10 Tf (.help ) Tj /F1 10 Tf (command is more powerful, since it provides) Tj T* 0 Tw (information about the arguments accepted by the given command:) Tj T* ET
+BT 1 0 0 1 0 28.82 Tm .187882 Tw 12 TL /F1 10 Tf 0 0 0 rg (The interactive mode of ) Tj /F3 10 Tf (plac ) Tj /F1 10 Tf (can be used as a replacement of the ) Tj 0 0 .501961 rg (cmd ) Tj 0 0 0 rg (module in the standard library. It) Tj T* 0 Tw 2.730651 Tw (is actually better than ) Tj 0 0 .501961 rg (cmd) Tj 0 0 0 rg (: for instance, the ) Tj /F3 10 Tf (.help ) Tj /F1 10 Tf (command is more powerful, since it provides) Tj T* 0 Tw (information about the arguments accepted by the given command:) Tj T* ET
 Q
 Q
 q
@@ -12135,7 +12098,7 @@ q
 n -6 -6 468.6898 300 re B*
 Q
 q
-BT 1 0 0 1 0 281.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (i) Tj (>) Tj ( .help set) Tj T* (usage:  set name value) Tj T*  T* (set name value) Tj T*  T* (positional arguments:) Tj T* (  name) Tj T* (  value) Tj T*  T* (i) Tj (>) Tj ( .help delete) Tj T* (usage:  delete [name]) Tj T*  T* (delete given parameter \(or everything\)) Tj T*  T* (positional arguments:) Tj T* (  name) Tj T*  T* (i) Tj (>) Tj ( .help show) Tj T* (usage:  show [names [names ...]]) Tj T*  T* (show given parameters) Tj T*  T* (positional arguments:) Tj T* (  names) Tj T* ET
+BT 1 0 0 1 0 281.71 Tm 12 TL /F3 10 Tf 0 0 0 rg (i) Tj (>) Tj ( .help set) Tj T* (usage:  set name value) Tj T*  T* (set name value) Tj T*  T* (positional arguments:) Tj T* (  name) Tj T* (  value) Tj T*  T* (i) Tj (>) Tj ( .help delete) Tj T* (usage:  delete [name]) Tj T*  T* (delete given parameter \(or everything\)) Tj T*  T* (positional arguments:) Tj T* (  name) Tj T*  T* (i) Tj (>) Tj ( .help show) Tj T* (usage:  show [names [names ...]]) Tj T*  T* (show given parameters) Tj T*  T* (positional arguments:) Tj T* (  names) Tj T* ET
 Q
 Q
 Q
@@ -12150,7 +12113,7 @@ Q
 q
 1 0 0 1 62.69291 333.8236 cm
 q
-BT 1 0 0 1 0 16.82 Tm 1.78248 Tw 12 TL /F1 10 Tf 0 0 0 rg (Moreover at the moment ) Tj /F4 10 Tf (plac ) Tj /F1 10 Tf (also understands command abbreviations. However, this feature may) Tj T* 0 Tw (disappear in future releases. It was meaningful in the past, when ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (did not support readline.) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm 1.78248 Tw 12 TL /F1 10 Tf 0 0 0 rg (Moreover at the moment ) Tj /F3 10 Tf (plac ) Tj /F1 10 Tf (also understands command abbreviations. However, this feature may) Tj T* 0 Tw (disappear in future releases. It was meaningful in the past, when ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (did not support readline.) Tj T* ET
 Q
 Q
 q
@@ -12173,7 +12136,7 @@ q
 n -6 -6 468.6898 36 re B*
 Q
 q
-BT 1 0 0 1 0 17.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (i) Tj (>) Tj ( sh) Tj T* (NameError: Ambiguous command 'sh': matching ['showall', 'show']) Tj T* ET
+BT 1 0 0 1 0 17.71 Tm 12 TL /F3 10 Tf 0 0 0 rg (i) Tj (>) Tj ( sh) Tj T* (NameError: Ambiguous command 'sh': matching ['showall', 'show']) Tj T* ET
 Q
 Q
 Q
@@ -12188,13 +12151,13 @@ Q
 q
 1 0 0 1 62.69291 174.6236 cm
 q
-BT 1 0 0 1 0 52.82 Tm 1.531318 Tw 12 TL /F1 10 Tf 0 0 0 rg (The distribution of ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (includes a runner script named ) Tj /F4 10 Tf (plac_runner.py) Tj /F1 10 Tf (, which will be installed in a) Tj T* 0 Tw .44748 Tw (suitable directory in your system by ) Tj 0 0 .501961 rg (distutils ) Tj 0 0 0 rg (\(say in ) Tj /F4 10 Tf (\\usr\\local\\bin\\plac_runner.py ) Tj /F1 10 Tf (in a Unix-like) Tj T* 0 Tw .680651 Tw (operative system\). The runner provides many facilities to run ) Tj /F4 10 Tf (.plac ) Tj /F1 10 Tf (scripts and ) Tj /F4 10 Tf (.placet ) Tj /F1 10 Tf (files, as well) Tj T* 0 Tw 1.47311 Tw (as Python modules containg a ) Tj /F4 10 Tf (main ) Tj /F1 10 Tf (object, which can be a function, a command container object or) Tj T* 0 Tw (even a command container class.) Tj T* ET
+BT 1 0 0 1 0 52.82 Tm 1.531318 Tw 12 TL /F1 10 Tf 0 0 0 rg (The distribution of ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (includes a runner script named ) Tj /F3 10 Tf (plac_runner.py) Tj /F1 10 Tf (, which will be installed in a) Tj T* 0 Tw .44748 Tw (suitable directory in your system by ) Tj 0 0 .501961 rg (distutils ) Tj 0 0 0 rg (\(say in ) Tj /F3 10 Tf (\\usr\\local\\bin\\plac_runner.py ) Tj /F1 10 Tf (in a Unix-like) Tj T* 0 Tw .680651 Tw (operative system\). The runner provides many facilities to run ) Tj /F3 10 Tf (.plac ) Tj /F1 10 Tf (scripts and ) Tj /F3 10 Tf (.placet ) Tj /F1 10 Tf (files, as well) Tj T* 0 Tw 1.47311 Tw (as Python modules containg a ) Tj /F3 10 Tf (main ) Tj /F1 10 Tf (object, which can be a function, a command container object or) Tj T* 0 Tw (even a command container class.) Tj T* ET
 Q
 Q
 q
 1 0 0 1 62.69291 144.6236 cm
 q
-BT 1 0 0 1 0 16.82 Tm 1.994269 Tw 12 TL /F1 10 Tf 0 0 0 rg (For instance, suppose you want to execute a script containing commands defined in the ) Tj /F4 10 Tf (ishelve2) Tj T* 0 Tw /F1 10 Tf (module like the following one:) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm 1.994269 Tw 12 TL /F1 10 Tf 0 0 0 rg (For instance, suppose you want to execute a script containing commands defined in the ) Tj /F3 10 Tf (ishelve2) Tj T* 0 Tw /F1 10 Tf (module like the following one:) Tj T* ET
 Q
 Q
 q
@@ -12212,7 +12175,7 @@ n -6 -6 468.6898 36 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 17.71 Tm /F4 10 Tf 12 TL (#!ishelve2.py:ShelveInterface -c ~/conf.shelve) Tj T* (set a 1) Tj T* ET
+BT 1 0 0 1 0 17.71 Tm /F3 10 Tf 12 TL (#!ishelve2.py:ShelveInterface -c ~/conf.shelve) Tj T* (set a 1) Tj T* ET
 Q
 Q
 Q
@@ -12250,7 +12213,7 @@ n -6 -6 468.6898 36 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 17.71 Tm /F4 10 Tf 12 TL (del a) Tj T* (del a # intentional error) Tj T* ET
+BT 1 0 0 1 0 17.71 Tm /F3 10 Tf 12 TL (del a) Tj T* (del a # intentional error) Tj T* ET
 Q
 Q
 Q
@@ -12259,7 +12222,7 @@ Q
 q
 1 0 0 1 62.69291 659.8236 cm
 q
-BT 1 0 0 1 0 52.82 Tm .575868 Tw 12 TL /F1 10 Tf 0 0 0 rg (The first line of the ) Tj /F4 10 Tf (.plac ) Tj /F1 10 Tf (script contains the name of the python module containing the plac interpreter) Tj T* 0 Tw 2.327209 Tw (and the arguments which must be passed to its main function in order to be able to instantiate an) Tj T* 0 Tw .202485 Tw (interpreter object. In this case I appended ) Tj /F4 10 Tf (:ShelveInterface ) Tj /F1 10 Tf (to the name of the module to specify the) Tj T* 0 Tw 1.030574 Tw (object that must be imported: if not specified, by default the object named 'main' is imported. The other) Tj T* 0 Tw (lines contains commands. You can run the script as follows:) Tj T* ET
+BT 1 0 0 1 0 52.82 Tm .575868 Tw 12 TL /F1 10 Tf 0 0 0 rg (The first line of the ) Tj /F3 10 Tf (.plac ) Tj /F1 10 Tf (script contains the name of the python module containing the plac interpreter) Tj T* 0 Tw 2.327209 Tw (and the arguments which must be passed to its main function in order to be able to instantiate an) Tj T* 0 Tw .202485 Tw (interpreter object. In this case I appended ) Tj /F3 10 Tf (:ShelveInterface ) Tj /F1 10 Tf (to the name of the module to specify the) Tj T* 0 Tw 1.030574 Tw (object that must be imported: if not specified, by default the object named 'main' is imported. The other) Tj T* 0 Tw (lines contains commands. You can run the script as follows:) Tj T* ET
 Q
 Q
 q
@@ -12277,7 +12240,7 @@ n -6 -6 492 84 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 65.71 Tm /F4 10 Tf 12 TL ($ plac_runner.py --batch ishelve2.plac) Tj T* (setting a=1) Tj T* (deleting a) Tj T* (Traceback \(most recent call last\):) Tj T* (  ...) Tj T* (_bsddb.DBNotFoundError: \(-30988, 'DB_NOTFOUND: No matching key/data pair found'\)) Tj T* ET
+BT 1 0 0 1 0 65.71 Tm /F3 10 Tf 12 TL ($ plac_runner.py --batch ishelve2.plac) Tj T* (setting a=1) Tj T* (deleting a) Tj T* (Traceback \(most recent call last\):) Tj T* (  ...) Tj T* (_bsddb.DBNotFoundError: \(-30988, 'DB_NOTFOUND: No matching key/data pair found'\)) Tj T* ET
 Q
 Q
 Q
@@ -12303,13 +12266,13 @@ Q
 q
 1 0 0 1 62.69291 490.6505 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 BT 1 0 0 1 0 2 Tm  T* ET
 q
 1 0 0 1 20 0 cm
 q
 0 0 0 rg
-BT 1 0 0 1 0 5.71 Tm /F4 10 Tf 12 TL (alias plac="plac_runner.py") Tj T* ET
+BT 1 0 0 1 0 5.71 Tm /F3 10 Tf 12 TL (alias plac="plac_runner.py") Tj T* ET
 Q
 Q
 q
@@ -12321,7 +12284,7 @@ Q
 q
 1 0 0 1 62.69291 460.6505 cm
 q
-BT 1 0 0 1 0 16.82 Tm 2.955318 Tw 12 TL /F1 10 Tf 0 0 0 rg (\(or you define a suitable ) Tj /F4 10 Tf (plac.bat ) Tj /F1 10 Tf (script in Windows\) you can run the ) Tj /F4 10 Tf (ishelve2.py ) Tj /F1 10 Tf (script in) Tj T* 0 Tw (interactive mode as follows:) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm 2.955318 Tw 12 TL /F1 10 Tf 0 0 0 rg (\(or you define a suitable ) Tj /F3 10 Tf (plac.bat ) Tj /F1 10 Tf (script in Windows\) you can run the ) Tj /F3 10 Tf (ishelve2.py ) Tj /F1 10 Tf (script in) Tj T* 0 Tw (interactive mode as follows:) Tj T* ET
 Q
 Q
 q
@@ -12338,7 +12301,7 @@ q
 n -6 -6 468.6898 168 re B*
 Q
 q
-BT 1 0 0 1 0 149.71 Tm 12 TL /F4 10 Tf 0 0 0 rg ($ plac -i ishelve2.py) Tj T* (A minimal interface over a shelve object.) Tj T* (Operating on /home/micheles/conf.shelve.) Tj T* (.help to see the available commands.) Tj T*  T* (i) Tj (>) Tj ( del) Tj T* (deleting everything) Tj T* (i) Tj (>) Tj ( set a 1) Tj T* (setting a=1) Tj T* (i) Tj (>) Tj ( set b 2) Tj T* (setting b=2) Tj T* (i) Tj (>) Tj ( show b) Tj T* (b = 2) Tj T* ET
+BT 1 0 0 1 0 149.71 Tm 12 TL /F3 10 Tf 0 0 0 rg ($ plac -i ishelve2.py) Tj T* (A minimal interface over a shelve object.) Tj T* (Operating on /home/micheles/conf.shelve.) Tj T* (.help to see the available commands.) Tj T*  T* (i) Tj (>) Tj ( del) Tj T* (deleting everything) Tj T* (i) Tj (>) Tj ( set a 1) Tj T* (setting a=1) Tj T* (i) Tj (>) Tj ( set b 2) Tj T* (setting b=2) Tj T* (i) Tj (>) Tj ( show b) Tj T* (b = 2) Tj T* ET
 Q
 Q
 Q
@@ -12347,7 +12310,7 @@ Q
 q
 1 0 0 1 62.69291 263.4505 cm
 q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (Now you can cut and paste the interactive session an turns into into a ) Tj /F4 10 Tf (.placet ) Tj /F1 10 Tf (file like the following:) Tj T* ET
+BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (Now you can cut and paste the interactive session an turns into into a ) Tj /F3 10 Tf (.placet ) Tj /F1 10 Tf (file like the following:) Tj T* ET
 Q
 Q
 q
@@ -12364,7 +12327,7 @@ q
 n -6 -6 468.6898 120 re B*
 Q
 q
-BT 1 0 0 1 0 101.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (#!ishelve2.py:ShelveInterface -configfile=~/test.shelve) Tj T* (i) Tj (>) Tj ( del) Tj T* (deleting everything) Tj T* (i) Tj (>) Tj ( set a 1) Tj T* (setting a=1) Tj T* (i) Tj (>) Tj ( set b 2) Tj T* (setting b=2) Tj T* (i) Tj (>) Tj ( show a) Tj T* (a = 1) Tj T* ET
+BT 1 0 0 1 0 101.71 Tm 12 TL /F3 10 Tf 0 0 0 rg (#!ishelve2.py:ShelveInterface -configfile=~/test.shelve) Tj T* (i) Tj (>) Tj ( del) Tj T* (deleting everything) Tj T* (i) Tj (>) Tj ( set a 1) Tj T* (setting a=1) Tj T* (i) Tj (>) Tj ( set b 2) Tj T* (setting b=2) Tj T* (i) Tj (>) Tj ( show a) Tj T* (a = 1) Tj T* ET
 Q
 Q
 Q
@@ -12373,7 +12336,7 @@ Q
 q
 1 0 0 1 62.69291 102.2505 cm
 q
-BT 1 0 0 1 0 16.82 Tm 2.145697 Tw 12 TL /F1 10 Tf 0 0 0 rg (Notice that the first line specifies a test database ) Tj /F4 10 Tf (~/test.shelve) Tj /F1 10 Tf (, to avoid clobbering your default) Tj T* 0 Tw (shelve. If you mispell the arguments in the first line plac will give you an ) Tj 0 0 .501961 rg (argparse ) Tj 0 0 0 rg (error message \(just try\).) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm 2.145697 Tw 12 TL /F1 10 Tf 0 0 0 rg (Notice that the first line specifies a test database ) Tj /F3 10 Tf (~/test.shelve) Tj /F1 10 Tf (, to avoid clobbering your default) Tj T* 0 Tw (shelve. If you mispell the arguments in the first line plac will give you an ) Tj 0 0 .501961 rg (argparse ) Tj 0 0 0 rg (error message \(just try\).) Tj T* ET
 Q
 Q
 q
@@ -12415,7 +12378,7 @@ n -6 -6 468.6898 36 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 17.71 Tm /F4 10 Tf 12 TL ($ plac --test ishelve2.placet) Tj T* (run 1 plac test\(s\)) Tj T* ET
+BT 1 0 0 1 0 17.71 Tm /F3 10 Tf 12 TL ($ plac --test ishelve2.placet) Tj T* (run 1 plac test\(s\)) Tj T* ET
 Q
 Q
 Q
@@ -12424,13 +12387,13 @@ Q
 q
 1 0 0 1 62.69291 663.8236 cm
 q
-BT 1 0 0 1 0 28.82 Tm .32104 Tw 12 TL /F1 10 Tf 0 0 0 rg (If you want to see the output of the tests, pass the ) Tj /F4 10 Tf (-v/--verbose ) Tj /F1 10 Tf (flag. Notice that he runner ignore the) Tj T* 0 Tw .24856 Tw (extension, so you can actually use any extension your like, but ) Tj /F5 10 Tf (it relies on the first line of the file to invoke) Tj T* 0 Tw (the corresponding plac tool with the given arguments) Tj /F1 10 Tf (.) Tj T* ET
+BT 1 0 0 1 0 28.82 Tm .32104 Tw 12 TL /F1 10 Tf 0 0 0 rg (If you want to see the output of the tests, pass the ) Tj /F3 10 Tf (-v/--verbose ) Tj /F1 10 Tf (flag. Notice that he runner ignore the) Tj T* 0 Tw .24856 Tw (extension, so you can actually use any extension your like, but ) Tj /F4 10 Tf (it relies on the first line of the file to invoke) Tj T* 0 Tw (the corresponding plac tool with the given arguments) Tj /F1 10 Tf (.) Tj T* ET
 Q
 Q
 q
 1 0 0 1 62.69291 633.8236 cm
 q
-BT 1 0 0 1 0 16.82 Tm .537209 Tw 12 TL /F1 10 Tf 0 0 0 rg (The plac runner does not provide any test discovery facility, but you can use standard Unix tools to help.) Tj T* 0 Tw (For instance, you can run all the ) Tj /F4 10 Tf (.placet ) Tj /F1 10 Tf (files into a directory and its subdirectories as follows:) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm .537209 Tw 12 TL /F1 10 Tf 0 0 0 rg (The plac runner does not provide any test discovery facility, but you can use standard Unix tools to help.) Tj T* 0 Tw (For instance, you can run all the ) Tj /F3 10 Tf (.placet ) Tj /F1 10 Tf (files into a directory and its subdirectories as follows:) Tj T* ET
 Q
 Q
 q
@@ -12448,7 +12411,7 @@ n -6 -6 468.6898 24 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 5.71 Tm /F4 10 Tf 12 TL ($ find . -name \\*.placet | xargs plac_runner.py -t) Tj T* ET
+BT 1 0 0 1 0 5.71 Tm /F3 10 Tf 12 TL ($ find . -name \\*.placet | xargs plac_runner.py -t) Tj T* ET
 Q
 Q
 Q
@@ -12457,7 +12420,7 @@ Q
 q
 1 0 0 1 62.69291 568.6236 cm
 q
-BT 1 0 0 1 0 16.82 Tm .760988 Tw 12 TL /F1 10 Tf 0 0 0 rg (The plac runner expects the main function of your script to return a plac tool, i.e. a function or an object) Tj T* 0 Tw (with a ) Tj /F4 10 Tf (.commands ) Tj /F1 10 Tf (attribute. It this is not the case the runner gracefully exits.) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm .760988 Tw 12 TL /F1 10 Tf 0 0 0 rg (The plac runner expects the main function of your script to return a plac tool, i.e. a function or an object) Tj T* 0 Tw (with a ) Tj /F3 10 Tf (.commands ) Tj /F1 10 Tf (attribute. It this is not the case the runner gracefully exits.) Tj T* ET
 Q
 Q
 q
@@ -12473,13 +12436,13 @@ Q
 q
 1 0 0 1 62.69291 532.6236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 BT 1 0 0 1 0 2 Tm  T* ET
 q
 1 0 0 1 20 0 cm
 q
 0 0 0 rg
-BT 1 0 0 1 0 5.71 Tm /F4 10 Tf 12 TL ($ plac module.py args ...) Tj T* ET
+BT 1 0 0 1 0 5.71 Tm /F3 10 Tf 12 TL ($ plac module.py args ...) Tj T* ET
 Q
 Q
 q
@@ -12510,7 +12473,7 @@ n -6 -6 468.6898 60 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 41.71 Tm /F4 10 Tf 12 TL ($ plac ishelve.py a=1) Tj T* (setting a=1) Tj T* ($ plac ishelve.py .show) Tj T* (a=1) Tj T* ET
+BT 1 0 0 1 0 41.71 Tm /F3 10 Tf 12 TL ($ plac ishelve.py a=1) Tj T* (setting a=1) Tj T* ($ plac ishelve.py .show) Tj T* (a=1) Tj T* ET
 Q
 Q
 Q
@@ -12519,7 +12482,7 @@ Q
 q
 1 0 0 1 62.69291 413.4236 cm
 q
-BT 1 0 0 1 0 16.82 Tm .01561 Tw 12 TL /F1 10 Tf 0 0 0 rg (Notice that in non-interactive mode the runner just invokes ) Tj /F4 10 Tf (plac.call ) Tj /F1 10 Tf (on the ) Tj /F4 10 Tf (main ) Tj /F1 10 Tf (object of the Python) Tj T* 0 Tw (module.) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm .01561 Tw 12 TL /F1 10 Tf 0 0 0 rg (Notice that in non-interactive mode the runner just invokes ) Tj /F3 10 Tf (plac.call ) Tj /F1 10 Tf (on the ) Tj /F3 10 Tf (main ) Tj /F1 10 Tf (object of the Python) Tj T* 0 Tw (module.) Tj T* ET
 Q
 Q
 q
@@ -12531,7 +12494,7 @@ Q
 q
 1 0 0 1 62.69291 341.4236 cm
 q
-BT 1 0 0 1 0 28.82 Tm .907209 Tw 12 TL /F1 10 Tf 0 0 .501961 rg (plac ) Tj 0 0 0 rg (does not force you to use classes to define command containers. Even a simple function can be a) Tj T* 0 Tw 1.796651 Tw (valid command container, it is enough to add to it a ) Tj /F4 10 Tf (.commands ) Tj /F1 10 Tf (attribute and possibly ) Tj /F4 10 Tf (__enter__) Tj T* 0 Tw /F1 10 Tf (and/or ) Tj /F4 10 Tf (__exit__ ) Tj /F1 10 Tf (attributes.) Tj T* ET
+BT 1 0 0 1 0 28.82 Tm .907209 Tw 12 TL /F1 10 Tf 0 0 .501961 rg (plac ) Tj 0 0 0 rg (does not force you to use classes to define command containers. Even a simple function can be a) Tj T* 0 Tw 1.796651 Tw (valid command container, it is enough to add to it a ) Tj /F3 10 Tf (.commands ) Tj /F1 10 Tf (attribute and possibly ) Tj /F3 10 Tf (__enter__) Tj T* 0 Tw /F1 10 Tf (and/or ) Tj /F3 10 Tf (__exit__ ) Tj /F1 10 Tf (attributes.) Tj T* ET
 Q
 Q
 q
@@ -12556,7 +12519,7 @@ n -6 -6 468.6898 204 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 185.71 Tm /F4 10 Tf 12 TL ("A Fake Version Control System") Tj T*  T* (import plac) Tj T*  T* (commands = 'checkout', 'commit', 'status') Tj T*  T* (@plac.annotations\(url='url of the source code'\)) Tj T* (def checkout\(url\):) Tj T* (    "A fake checkout command") Tj T* (    return \('checkout ', url\)) Tj T*  T* (@plac.annotations\(message=\('commit message', 'option'\)\)) Tj T* (def commit\(message\):) Tj T* (    "A fake commit command") Tj T* (    return \('commit ', message\)) Tj T*  T* ET
+BT 1 0 0 1 0 185.71 Tm /F3 10 Tf 12 TL ("A Fake Version Control System") Tj T*  T* (import plac) Tj T*  T* (commands = 'checkout', 'commit', 'status') Tj T*  T* (@plac.annotations\(url='url of the source code'\)) Tj T* (def checkout\(url\):) Tj T* (    "A fake checkout command") Tj T* (    return \('checkout ', url\)) Tj T*  T* (@plac.annotations\(message=\('commit message', 'option'\)\)) Tj T* (def commit\(message\):) Tj T* (    "A fake commit command") Tj T* (    return \('commit ', message\)) Tj T*  T* ET
 Q
 Q
 Q
@@ -12594,7 +12557,7 @@ n -6 -6 468.6898 180 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 161.71 Tm /F4 10 Tf 12 TL (@plac.annotations\(quiet=\('summary information', 'flag', 'q'\)\)) Tj T* (def status\(quiet\):) Tj T* (    "A fake status command") Tj T* (    return \('status ', quiet\)) Tj T*  T* (def __missing__\(name\):) Tj T* (    return 'Command %r does not exist' % name) Tj T*  T* (def __exit__\(etype, exc, tb\):) Tj T* (    "Will be called automatically at the end of the call/cmdloop") Tj T* (    if etype in \(None, GeneratorExit\): # success) Tj T* (        print\('ok'\)) Tj T*  T* (main = __import__\(__name__\) # the module imports itself!) Tj T* ET
+BT 1 0 0 1 0 161.71 Tm /F3 10 Tf 12 TL (@plac.annotations\(quiet=\('summary information', 'flag', 'q'\)\)) Tj T* (def status\(quiet\):) Tj T* (    "A fake status command") Tj T* (    return \('status ', quiet\)) Tj T*  T* (def __missing__\(name\):) Tj T* (    return 'Command %r does not exist' % name) Tj T*  T* (def __exit__\(etype, exc, tb\):) Tj T* (    "Will be called automatically at the end of the call/cmdloop") Tj T* (    if etype in \(None, GeneratorExit\): # success) Tj T* (        print\('ok'\)) Tj T*  T* (main = __import__\(__name__\) # the module imports itself!) Tj T* ET
 Q
 Q
 Q
@@ -12603,13 +12566,13 @@ Q
 q
 1 0 0 1 62.69291 539.8236 cm
 q
-BT 1 0 0 1 0 28.82 Tm .431318 Tw 12 TL /F1 10 Tf 0 0 0 rg (Notice that I have defined both an ) Tj /F4 10 Tf (__exit__ ) Tj /F1 10 Tf (hook and a ) Tj /F4 10 Tf (__missing__ ) Tj /F1 10 Tf (hook, invoked for non-existing) Tj T* 0 Tw .592651 Tw (commands. The real trick here is the line ) Tj /F4 10 Tf (main = __import__\(__name__\)) Tj /F1 10 Tf (, which define ) Tj /F4 10 Tf (main ) Tj /F1 10 Tf (to be) Tj T* 0 Tw (an alias for the current module.) Tj T* ET
+BT 1 0 0 1 0 28.82 Tm .431318 Tw 12 TL /F1 10 Tf 0 0 0 rg (Notice that I have defined both an ) Tj /F3 10 Tf (__exit__ ) Tj /F1 10 Tf (hook and a ) Tj /F3 10 Tf (__missing__ ) Tj /F1 10 Tf (hook, invoked for non-existing) Tj T* 0 Tw .592651 Tw (commands. The real trick here is the line ) Tj /F3 10 Tf (main = __import__\(__name__\)) Tj /F1 10 Tf (, which define ) Tj /F3 10 Tf (main ) Tj /F1 10 Tf (to be) Tj T* 0 Tw (an alias for the current module.) Tj T* ET
 Q
 Q
 q
 1 0 0 1 62.69291 509.8236 cm
 q
-BT 1 0 0 1 0 16.82 Tm 1.259986 Tw 12 TL /F1 10 Tf 0 0 0 rg (The ) Tj /F4 10 Tf (vcs ) Tj /F1 10 Tf (module does not contain an ) Tj /F4 10 Tf (if __name__ == '__main__' ) Tj /F1 10 Tf (block, but you can still run it) Tj T* 0 Tw (through the plac runner \(try ) Tj /F4 10 Tf (plac vcs.py -h) Tj /F1 10 Tf (\):) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm 1.259986 Tw 12 TL /F1 10 Tf 0 0 0 rg (The ) Tj /F3 10 Tf (vcs ) Tj /F1 10 Tf (module does not contain an ) Tj /F3 10 Tf (if __name__ == '__main__' ) Tj /F1 10 Tf (block, but you can still run it) Tj T* 0 Tw (through the plac runner \(try ) Tj /F3 10 Tf (plac vcs.py -h) Tj /F1 10 Tf (\):) Tj T* ET
 Q
 Q
 q
@@ -12627,7 +12590,7 @@ n -6 -6 468.6898 132 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 113.71 Tm /F4 10 Tf 12 TL (usage: plac_runner.py vcs.py [-h] {status,commit,checkout} ...) Tj T*  T* (A Fake Version Control System) Tj T*  T* (optional arguments:) Tj T* (  -h, --help            show this help message and exit) Tj T*  T* (subcommands:) Tj T* (  {status,commit,checkout}) Tj T* (                        -h to get additional help) Tj T* ET
+BT 1 0 0 1 0 113.71 Tm /F3 10 Tf 12 TL (usage: plac_runner.py vcs.py [-h] {status,commit,checkout} ...) Tj T*  T* (A Fake Version Control System) Tj T*  T* (optional arguments:) Tj T* (  -h, --help            show this help message and exit) Tj T*  T* (subcommands:) Tj T* (  {status,commit,checkout}) Tj T* (                        -h to get additional help) Tj T* ET
 Q
 Q
 Q
@@ -12636,7 +12599,7 @@ Q
 q
 1 0 0 1 62.69291 348.6236 cm
 q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (You can get help for the subcommands by postponing ) Tj /F4 10 Tf (-h ) Tj /F1 10 Tf (after the name of the command:) Tj T* ET
+BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (You can get help for the subcommands by postponing ) Tj /F3 10 Tf (-h ) Tj /F1 10 Tf (after the name of the command:) Tj T* ET
 Q
 Q
 q
@@ -12654,7 +12617,7 @@ n -6 -6 468.6898 108 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 89.71 Tm /F4 10 Tf 12 TL ($ plac vcs.py status -h) Tj T* (usage: vcs.py status [-h] [-q]) Tj T*  T* (A fake status command) Tj T*  T* (optional arguments:) Tj T* (  -h, --help   show this help message and exit) Tj T* (  -q, --quiet  summary information) Tj T* ET
+BT 1 0 0 1 0 89.71 Tm /F3 10 Tf 12 TL ($ plac vcs.py status -h) Tj T* (usage: vcs.py status [-h] [-q]) Tj T*  T* (A fake status command) Tj T*  T* (optional arguments:) Tj T* (  -h, --help   show this help message and exit) Tj T* (  -q, --quiet  summary information) Tj T* ET
 Q
 Q
 Q
@@ -12663,7 +12626,7 @@ Q
 q
 1 0 0 1 62.69291 199.4236 cm
 q
-BT 1 0 0 1 0 16.82 Tm 2.064985 Tw 12 TL /F1 10 Tf 0 0 0 rg (Notice how the docstring of the command is automatically shown in usage message, as well as the) Tj T* 0 Tw (documentation for the sub flag ) Tj /F4 10 Tf (-q) Tj /F1 10 Tf (.) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm 2.064985 Tw 12 TL /F1 10 Tf 0 0 0 rg (Notice how the docstring of the command is automatically shown in usage message, as well as the) Tj T* 0 Tw (documentation for the sub flag ) Tj /F3 10 Tf (-q) Tj /F1 10 Tf (.) Tj T* ET
 Q
 Q
 q
@@ -12688,7 +12651,7 @@ n -6 -6 468.6898 72 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 53.71 Tm /F4 10 Tf 12 TL ($ plac vcs.py check url) Tj T* (checkout) Tj T* (url) Tj T* ($ plac vcs.py st -q) Tj T* (status) Tj T* ET
+BT 1 0 0 1 0 53.71 Tm /F3 10 Tf 12 TL ($ plac vcs.py check url) Tj T* (checkout) Tj T* (url) Tj T* ($ plac vcs.py st -q) Tj T* (status) Tj T* ET
 Q
 Q
 Q
@@ -12726,7 +12689,7 @@ n -6 -6 468.6898 60 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 41.71 Tm /F4 10 Tf 12 TL (True) Tj T* ($ plac vcs.py co) Tj T* (commit) Tj T* (None) Tj T* ET
+BT 1 0 0 1 0 41.71 Tm /F3 10 Tf 12 TL (True) Tj T* ($ plac vcs.py co) Tj T* (commit) Tj T* (None) Tj T* ET
 Q
 Q
 Q
@@ -12753,7 +12716,7 @@ q
 n -6 -6 468.6898 192 re B*
 Q
 q
-BT 1 0 0 1 0 173.71 Tm 12 TL /F4 10 Tf 0 0 0 rg ($ plac -i vcs.py) Tj T* (usage: plac_runner.py vcs.py [-h] {status,commit,checkout} ...) Tj T* (i) Tj (>) Tj ( check url) Tj T* (checkout) Tj T* (url) Tj T* (i) Tj (>) Tj ( st -q) Tj T* (status) Tj T* (True) Tj T* (i) Tj (>) Tj ( co) Tj T* (commit) Tj T* (None) Tj T* (i) Tj (>) Tj ( sto) Tj T* (Command 'sto' does not exist) Tj T* (i) Tj (>) Tj ( [CTRL-D]) Tj T* (ok) Tj T* ET
+BT 1 0 0 1 0 173.71 Tm 12 TL /F3 10 Tf 0 0 0 rg ($ plac -i vcs.py) Tj T* (usage: plac_runner.py vcs.py [-h] {status,commit,checkout} ...) Tj T* (i) Tj (>) Tj ( check url) Tj T* (checkout) Tj T* (url) Tj T* (i) Tj (>) Tj ( st -q) Tj T* (status) Tj T* (True) Tj T* (i) Tj (>) Tj ( co) Tj T* (commit) Tj T* (None) Tj T* (i) Tj (>) Tj ( sto) Tj T* (Command 'sto' does not exist) Tj T* (i) Tj (>) Tj ( [CTRL-D]) Tj T* (ok) Tj T* ET
 Q
 Q
 Q
@@ -12762,7 +12725,7 @@ Q
 q
 1 0 0 1 62.69291 450.6236 cm
 q
-BT 1 0 0 1 0 16.82 Tm 2.986905 Tw 12 TL /F1 10 Tf 0 0 0 rg (Notice the invocation of the ) Tj /F4 10 Tf (__missing__ ) Tj /F1 10 Tf (hook for non-existing commands. Notice also that the) Tj T* 0 Tw /F4 10 Tf (__exit__ ) Tj /F1 10 Tf (hook gets called only in interactive mode.) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm 2.986905 Tw 12 TL /F1 10 Tf 0 0 0 rg (Notice the invocation of the ) Tj /F3 10 Tf (__missing__ ) Tj /F1 10 Tf (hook for non-existing commands. Notice also that the) Tj T* 0 Tw /F3 10 Tf (__exit__ ) Tj /F1 10 Tf (hook gets called only in interactive mode.) Tj T* ET
 Q
 Q
 q
@@ -12781,7 +12744,7 @@ Q
 q
 1 0 0 1 62.69291 336.6236 cm
 q
-BT 1 0 0 1 0 40.82 Tm .167209 Tw 12 TL /F1 10 Tf 0 0 0 rg (The runner included in the ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (distribution is intentionally kept small \(around 50 lines of code\) so that you) Tj T* 0 Tw .081294 Tw (can study it and write your own runner if want to. If you need to go to such level of detail, you should know) Tj T* 0 Tw .42061 Tw (that the most important method of the ) Tj /F4 10 Tf (Interpreter ) Tj /F1 10 Tf (class is the ) Tj /F4 10 Tf (.send ) Tj /F1 10 Tf (method, which takes strings in) Tj T* 0 Tw (input and returns a four-tuple with attributes ) Tj /F4 10 Tf (.str) Tj /F1 10 Tf (, ) Tj /F4 10 Tf (.etype) Tj /F1 10 Tf (, ) Tj /F4 10 Tf (.exc ) Tj /F1 10 Tf (and ) Tj /F4 10 Tf (.tb) Tj /F1 10 Tf (:) Tj T* ET
+BT 1 0 0 1 0 40.82 Tm .167209 Tw 12 TL /F1 10 Tf 0 0 0 rg (The runner included in the ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (distribution is intentionally kept small \(around 50 lines of code\) so that you) Tj T* 0 Tw .081294 Tw (can study it and write your own runner if want to. If you need to go to such level of detail, you should know) Tj T* 0 Tw .42061 Tw (that the most important method of the ) Tj /F3 10 Tf (Interpreter ) Tj /F1 10 Tf (class is the ) Tj /F3 10 Tf (.send ) Tj /F1 10 Tf (method, which takes strings in) Tj T* 0 Tw (input and returns a four-tuple with attributes ) Tj /F3 10 Tf (.str) Tj /F1 10 Tf (, ) Tj /F3 10 Tf (.etype) Tj /F1 10 Tf (, ) Tj /F3 10 Tf (.exc ) Tj /F1 10 Tf (and ) Tj /F3 10 Tf (.tb) Tj /F1 10 Tf (:) Tj T* ET
 Q
 Q
 q
@@ -12793,7 +12756,7 @@ Q
 q
 1 0 0 1 62.69291 312.6236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 3 cm
 q
@@ -12804,7 +12767,7 @@ Q
 q
 1 0 0 1 23 3 cm
 q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F4 10 Tf 0 0 0 rg (.str ) Tj /F1 10 Tf (is the output of the command, if successful \(a string\);) Tj T* ET
+BT 1 0 0 1 0 4.82 Tm 12 TL /F3 10 Tf 0 0 0 rg (.str ) Tj /F1 10 Tf (is the output of the command, if successful \(a string\);) Tj T* ET
 Q
 Q
 q
@@ -12819,7 +12782,7 @@ Q
 q
 1 0 0 1 62.69291 294.6236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 3 cm
 q
@@ -12830,7 +12793,7 @@ Q
 q
 1 0 0 1 23 3 cm
 q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F4 10 Tf 0 0 0 rg (.etype ) Tj /F1 10 Tf (is the class of the exception, if the command fail;) Tj T* ET
+BT 1 0 0 1 0 4.82 Tm 12 TL /F3 10 Tf 0 0 0 rg (.etype ) Tj /F1 10 Tf (is the class of the exception, if the command fail;) Tj T* ET
 Q
 Q
 q
@@ -12845,7 +12808,7 @@ Q
 q
 1 0 0 1 62.69291 276.6236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 3 cm
 q
@@ -12856,7 +12819,7 @@ Q
 q
 1 0 0 1 23 3 cm
 q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F4 10 Tf 0 0 0 rg (.exc ) Tj /F1 10 Tf (is the exception instance;) Tj T* ET
+BT 1 0 0 1 0 4.82 Tm 12 TL /F3 10 Tf 0 0 0 rg (.exc ) Tj /F1 10 Tf (is the exception instance;) Tj T* ET
 Q
 Q
 q
@@ -12871,7 +12834,7 @@ Q
 q
 1 0 0 1 62.69291 258.6236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 3 cm
 q
@@ -12882,7 +12845,7 @@ Q
 q
 1 0 0 1 23 3 cm
 q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F4 10 Tf 0 0 0 rg (.tb ) Tj /F1 10 Tf (is the traceback.) Tj T* ET
+BT 1 0 0 1 0 4.82 Tm 12 TL /F3 10 Tf 0 0 0 rg (.tb ) Tj /F1 10 Tf (is the traceback.) Tj T* ET
 Q
 Q
 q
@@ -12897,13 +12860,13 @@ Q
 q
 1 0 0 1 62.69291 216.6236 cm
 q
-BT 1 0 0 1 0 28.82 Tm .937485 Tw 12 TL /F1 10 Tf 0 0 0 rg (Moreover the ) Tj /F4 10 Tf (__str__ ) Tj /F1 10 Tf (representation of the output object is redefined to return the output string if the) Tj T* 0 Tw 2.686651 Tw (command was successful or the error message if the command failed \(actually it returns the error) Tj T* 0 Tw (message preceded by the name of the exception class\).) Tj T* ET
+BT 1 0 0 1 0 28.82 Tm .937485 Tw 12 TL /F1 10 Tf 0 0 0 rg (Moreover the ) Tj /F3 10 Tf (__str__ ) Tj /F1 10 Tf (representation of the output object is redefined to return the output string if the) Tj T* 0 Tw 2.686651 Tw (command was successful or the error message if the command failed \(actually it returns the error) Tj T* 0 Tw (message preceded by the name of the exception class\).) Tj T* ET
 Q
 Q
 q
 1 0 0 1 62.69291 198.6236 cm
 q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (For instance, if you send a mispelled option to the interpreter a ) Tj /F4 10 Tf (SystemExit ) Tj /F1 10 Tf (will be trapped:) Tj T* ET
+BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (For instance, if you send a mispelled option to the interpreter a ) Tj /F3 10 Tf (SystemExit ) Tj /F1 10 Tf (will be trapped:) Tj T* ET
 Q
 Q
 q
@@ -12920,7 +12883,7 @@ q
 n -6 -6 468.6898 84 re B*
 Q
 q
-BT 1 0 0 1 0 65.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (>) Tj (>) Tj (>) Tj ( import plac) Tj T* (>) Tj (>) Tj (>) Tj ( from ishelve import ishelve) Tj T* (>) Tj (>) Tj (>) Tj ( with plac.Interpreter\(ishelve\) as i:) Tj T* (...     print\(i.send\('.cler'\)\)) Tj T* (...) Tj T* (SystemExit: unrecognized arguments: .cler) Tj T* ET
+BT 1 0 0 1 0 65.71 Tm 12 TL /F3 10 Tf 0 0 0 rg (>) Tj (>) Tj (>) Tj ( import plac) Tj T* (>) Tj (>) Tj (>) Tj ( from ishelve import ishelve) Tj T* (>) Tj (>) Tj (>) Tj ( with plac.Interpreter\(ishelve\) as i:) Tj T* (...     print\(i.send\('.cler'\)\)) Tj T* (...) Tj T* (SystemExit: unrecognized arguments: .cler) Tj T* ET
 Q
 Q
 Q
@@ -12946,7 +12909,7 @@ stream
 q
 1 0 0 1 62.69291 741.0236 cm
 q
-BT 1 0 0 1 0 16.82 Tm 2.90561 Tw 12 TL /F1 10 Tf 0 0 0 rg (It is important to invoke the ) Tj /F4 10 Tf (.send ) Tj /F1 10 Tf (method inside the context manager, otherwise you will get a) Tj T* 0 Tw /F4 10 Tf (RuntimeError) Tj /F1 10 Tf (.) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm 2.90561 Tw 12 TL /F1 10 Tf 0 0 0 rg (It is important to invoke the ) Tj /F3 10 Tf (.send ) Tj /F1 10 Tf (method inside the context manager, otherwise you will get a) Tj T* 0 Tw /F3 10 Tf (RuntimeError) Tj /F1 10 Tf (.) Tj T* ET
 Q
 Q
 q
@@ -12971,7 +12934,7 @@ n -6 -6 468.6898 228 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 209.71 Tm /F4 10 Tf 12 TL (input_widget = WidgetReadingInput\(\)) Tj T* (output_widget = WidgetDisplayingOutput\(\)) Tj T*  T* (def send\(interpreter, line\):) Tj T* (    out = interpreter.send\(line\)) Tj T* (    if out.tb: # there was an error) Tj T* (        output_widget.display\(out.tb, color='red'\)) Tj T* (    else:) Tj T* (        output_widget.display\(out.str\)) Tj T*  T* (main = plac.import_main\(tool_path\) # get the main object) Tj T*  T* (with plac.Interpreter\(main\) as i:) Tj T* (   def callback\(event\):) Tj T* (      if event.user_pressed_ENTER\(\):) Tj T* (           send\(i, input_widget.last_line\)) Tj T* (   input_widget.addcallback\(callback\)) Tj T* (   gui_mainloop.start\(\)) Tj T* ET
+BT 1 0 0 1 0 209.71 Tm /F3 10 Tf 12 TL (input_widget = WidgetReadingInput\(\)) Tj T* (output_widget = WidgetDisplayingOutput\(\)) Tj T*  T* (def send\(interpreter, line\):) Tj T* (    out = interpreter.send\(line\)) Tj T* (    if out.tb: # there was an error) Tj T* (        output_widget.display\(out.tb, color='red'\)) Tj T* (    else:) Tj T* (        output_widget.display\(out.str\)) Tj T*  T* (main = plac.import_main\(tool_path\) # get the main object) Tj T*  T* (with plac.Interpreter\(main\) as i:) Tj T* (   def callback\(event\):) Tj T* (      if event.user_pressed_ENTER\(\):) Tj T* (           send\(i, input_widget.last_line\)) Tj T* (   input_widget.addcallback\(callback\)) Tj T* (   gui_mainloop.start\(\)) Tj T* ET
 Q
 Q
 Q
@@ -12987,13 +12950,13 @@ Q
 q
 1 0 0 1 62.69291 399.8236 cm
 q
-BT 1 0 0 1 0 16.82 Tm .259988 Tw 12 TL /F1 10 Tf 0 0 0 rg (An example of GUI program built on top of ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (is given later on, in the paragraph ) Tj /F5 10 Tf (Managing the output of) Tj T* 0 Tw (concurrent commands ) Tj /F1 10 Tf (\(using Tkinter for simplicity and portability\).) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm .259988 Tw 12 TL /F1 10 Tf 0 0 0 rg (An example of GUI program built on top of ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (is given later on, in the paragraph ) Tj /F4 10 Tf (Managing the output of) Tj T* 0 Tw (concurrent commands ) Tj /F1 10 Tf (\(using Tkinter for simplicity and portability\).) Tj T* ET
 Q
 Q
 q
 1 0 0 1 62.69291 345.8236 cm
 q
-BT 1 0 0 1 0 40.82 Tm 2.090651 Tw 12 TL /F1 10 Tf 0 0 0 rg (There is a final ) Tj /F5 10 Tf (caveat) Tj /F1 10 Tf (: since the plac interpreter loop is implemented via extended generators, plac) Tj T* 0 Tw .988651 Tw (interpreters are single threaded: you will get an error if you ) Tj /F4 10 Tf (.send ) Tj /F1 10 Tf (commands from separated threads.) Tj T* 0 Tw .947882 Tw (You can circumvent the problem by using a queue. If EXIT is a sentinel value to signal exiting from the) Tj T* 0 Tw (interpreter look, you can write code like this:) Tj T* ET
+BT 1 0 0 1 0 40.82 Tm 2.090651 Tw 12 TL /F1 10 Tf 0 0 0 rg (There is a final ) Tj /F4 10 Tf (caveat) Tj /F1 10 Tf (: since the plac interpreter loop is implemented via extended generators, plac) Tj T* 0 Tw .988651 Tw (interpreters are single threaded: you will get an error if you ) Tj /F3 10 Tf (.send ) Tj /F1 10 Tf (commands from separated threads.) Tj T* 0 Tw .947882 Tw (You can circumvent the problem by using a queue. If EXIT is a sentinel value to signal exiting from the) Tj T* 0 Tw (interpreter look, you can write code like this:) Tj T* ET
 Q
 Q
 q
@@ -13011,7 +12974,7 @@ n -6 -6 468.6898 48 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 29.71 Tm /F4 10 Tf 12 TL (with interpreter:) Tj T* (    for input_value in iter\(input_queue.get, EXIT\):) Tj T* (        output_queue.put\(interpreter.send\(input_value\)\)) Tj T* ET
+BT 1 0 0 1 0 29.71 Tm /F3 10 Tf 12 TL (with interpreter:) Tj T* (    for input_value in iter\(input_queue.get, EXIT\):) Tj T* (        output_queue.put\(interpreter.send\(input_value\)\)) Tj T* ET
 Q
 Q
 Q
@@ -13050,7 +13013,7 @@ n -6 -6 468.6898 84 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 65.71 Tm /F4 10 Tf 12 TL (import time) Tj T* (import plac) Tj T*  T* (class FakeImporter\(object\):) Tj T* (    "A fake importer with an import_file command") Tj T* (    commands = ['import_file']) Tj T* ET
+BT 1 0 0 1 0 65.71 Tm /F3 10 Tf 12 TL (import time) Tj T* (import plac) Tj T*  T* (class FakeImporter\(object\):) Tj T* (    "A fake importer with an import_file command") Tj T* (    commands = ['import_file']) Tj T* ET
 Q
 Q
 Q
@@ -13088,7 +13051,7 @@ n -6 -6 468.6898 180 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 161.71 Tm /F4 10 Tf 12 TL (    def __init__\(self, dsn\):) Tj T* (        self.dsn = dsn) Tj T* (    def import_file\(self, fname\):) Tj T* (        "Import a file into the database") Tj T* (        try:) Tj T* (            for n in range\(10000\):) Tj T* (                time.sleep\(.01\)) Tj T* (                if n % 100 == 99:) Tj T* (                    yield 'Imported %d lines' % \(n+1\)) Tj T* (        finally:) Tj T* (            print\('closing the file'\)) Tj T*  T* (if __name__ == '__main__':) Tj T* (    plac.Interpreter.call\(FakeImporter\)) Tj T* ET
+BT 1 0 0 1 0 161.71 Tm /F3 10 Tf 12 TL (    def __init__\(self, dsn\):) Tj T* (        self.dsn = dsn) Tj T* (    def import_file\(self, fname\):) Tj T* (        "Import a file into the database") Tj T* (        try:) Tj T* (            for n in range\(10000\):) Tj T* (                time.sleep\(.01\)) Tj T* (                if n % 100 == 99:) Tj T* (                    yield 'Imported %d lines' % \(n+1\)) Tj T* (        finally:) Tj T* (            print\('closing the file'\)) Tj T*  T* (if __name__ == '__main__':) Tj T* (    plac.Interpreter.call\(FakeImporter\)) Tj T* ET
 Q
 Q
 Q
@@ -13097,7 +13060,7 @@ Q
 q
 1 0 0 1 62.69291 551.8236 cm
 q
-BT 1 0 0 1 0 16.82 Tm 1.466457 Tw 12 TL /F1 10 Tf 0 0 0 rg (If you run the ) Tj /F4 10 Tf (import_file ) Tj /F1 10 Tf (command, you will have to wait for 200 seconds before entering a new) Tj T* 0 Tw (command:) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm 1.466457 Tw 12 TL /F1 10 Tf 0 0 0 rg (If you run the ) Tj /F3 10 Tf (import_file ) Tj /F1 10 Tf (command, you will have to wait for 200 seconds before entering a new) Tj T* 0 Tw (command:) Tj T* ET
 Q
 Q
 q
@@ -13114,7 +13077,7 @@ q
 n -6 -6 468.6898 132 re B*
 Q
 q
-BT 1 0 0 1 0 113.71 Tm 12 TL /F4 10 Tf 0 0 0 rg ($ python importer1.py dsn) Tj T* (A fake importer with an import_file command) Tj T* (i) Tj (>) Tj ( import_file file1) Tj T* (... ) Tj (<) Tj (wait 3+ minutes) Tj (>) Tj  T* (Imported 100 lines) Tj T* (Imported 200 lines) Tj T* (Imported 300 lines) Tj T* (...) Tj T* (Imported 10000 lines) Tj T* (closing the file) Tj T* ET
+BT 1 0 0 1 0 113.71 Tm 12 TL /F3 10 Tf 0 0 0 rg ($ python importer1.py dsn) Tj T* (A fake importer with an import_file command) Tj T* (i) Tj (>) Tj ( import_file file1) Tj T* (... ) Tj (<) Tj (wait 3+ minutes) Tj (>) Tj  T* (Imported 100 lines) Tj T* (Imported 200 lines) Tj T* (Imported 300 lines) Tj T* (...) Tj T* (Imported 10000 lines) Tj T* (closing the file) Tj T* ET
 Q
 Q
 Q
@@ -13145,13 +13108,13 @@ Q
 q
 1 0 0 1 62.69291 288.6236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 BT 1 0 0 1 0 2 Tm  T* ET
 q
 1 0 0 1 20 0 cm
 q
 0 0 0 rg
-BT 1 0 0 1 0 5.71 Tm /F4 10 Tf 12 TL (commands = ['import_file']) Tj T* ET
+BT 1 0 0 1 0 5.71 Tm /F3 10 Tf 12 TL (commands = ['import_file']) Tj T* ET
 Q
 Q
 q
@@ -13173,13 +13136,13 @@ Q
 q
 1 0 0 1 62.69291 252.6236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 BT 1 0 0 1 0 2 Tm  T* ET
 q
 1 0 0 1 20 0 cm
 q
 0 0 0 rg
-BT 1 0 0 1 0 5.71 Tm /F4 10 Tf 12 TL (thcommands = ['import_file']) Tj T* ET
+BT 1 0 0 1 0 5.71 Tm /F3 10 Tf 12 TL (thcommands = ['import_file']) Tj T* ET
 Q
 Q
 q
@@ -13191,7 +13154,7 @@ Q
 q
 1 0 0 1 62.69291 222.6236 cm
 q
-BT 1 0 0 1 0 16.82 Tm 1.38311 Tw 12 TL /F1 10 Tf 0 0 0 rg (to tell to the ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (interpreter that the command ) Tj /F4 10 Tf (import_file ) Tj /F1 10 Tf (should be run into a separated thread.) Tj T* 0 Tw (Here is an example session:) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm 1.38311 Tw 12 TL /F1 10 Tf 0 0 0 rg (to tell to the ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (interpreter that the command ) Tj /F3 10 Tf (import_file ) Tj /F1 10 Tf (should be run into a separated thread.) Tj T* 0 Tw (Here is an example session:) Tj T* ET
 Q
 Q
 q
@@ -13208,7 +13171,7 @@ q
 n -6 -6 468.6898 36 re B*
 Q
 q
-BT 1 0 0 1 0 17.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (i) Tj (>) Tj ( import_file file1) Tj T* (<) Tj (ThreadedTask 1 [import_file file1] RUNNING) Tj (>) Tj T* ET
+BT 1 0 0 1 0 17.71 Tm 12 TL /F3 10 Tf 0 0 0 rg (i) Tj (>) Tj ( import_file file1) Tj T* (<) Tj (ThreadedTask 1 [import_file file1] RUNNING) Tj (>) Tj T* ET
 Q
 Q
 Q
@@ -13217,7 +13180,7 @@ Q
 q
 1 0 0 1 62.69291 145.4236 cm
 q
-BT 1 0 0 1 0 16.82 Tm .595777 Tw 12 TL /F1 10 Tf 0 0 0 rg (The import task started in a separated thread. You can see the progress of the task by using the special) Tj T* 0 Tw (command ) Tj /F4 10 Tf (.output) Tj /F1 10 Tf (:) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm .595777 Tw 12 TL /F1 10 Tf 0 0 0 rg (The import task started in a separated thread. You can see the progress of the task by using the special) Tj T* 0 Tw (command ) Tj /F3 10 Tf (.output) Tj /F1 10 Tf (:) Tj T* ET
 Q
 Q
 q
@@ -13234,7 +13197,7 @@ q
 n -6 -6 468.6898 36 re B*
 Q
 q
-BT 1 0 0 1 0 17.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (i) Tj (>) Tj ( .output 1) Tj T* (<) Tj (ThreadedTask 1 [import_file file1] RUNNING) Tj (>) Tj  T* ET
+BT 1 0 0 1 0 17.71 Tm 12 TL /F3 10 Tf 0 0 0 rg (i) Tj (>) Tj ( .output 1) Tj T* (<) Tj (ThreadedTask 1 [import_file file1] RUNNING) Tj (>) Tj  T* ET
 Q
 Q
 Q
@@ -13271,7 +13234,7 @@ q
 n -6 -6 468.6898 36 re B*
 Q
 q
-BT 1 0 0 1 0 17.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (Imported 100 lines) Tj T* (Imported 200 lines) Tj T* ET
+BT 1 0 0 1 0 17.71 Tm 12 TL /F3 10 Tf 0 0 0 rg (Imported 100 lines) Tj T* (Imported 200 lines) Tj T* ET
 Q
 Q
 Q
@@ -13298,7 +13261,7 @@ q
 n -6 -6 468.6898 84 re B*
 Q
 q
-BT 1 0 0 1 0 65.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (i) Tj (>) Tj ( .output 1) Tj T* (<) Tj (ThreadedTask 1 [import_file file1] RUNNING) Tj (>) Tj  T* (Imported 100 lines) Tj T* (Imported 200 lines) Tj T* (Imported 300 lines) Tj T* (Imported 400 lines) Tj T* ET
+BT 1 0 0 1 0 65.71 Tm 12 TL /F3 10 Tf 0 0 0 rg (i) Tj (>) Tj ( .output 1) Tj T* (<) Tj (ThreadedTask 1 [import_file file1] RUNNING) Tj (>) Tj  T* (Imported 100 lines) Tj T* (Imported 200 lines) Tj T* (Imported 300 lines) Tj T* (Imported 400 lines) Tj T* ET
 Q
 Q
 Q
@@ -13325,7 +13288,7 @@ q
 n -6 -6 468.6898 36 re B*
 Q
 q
-BT 1 0 0 1 0 17.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (i) Tj (>) Tj ( .output 1) Tj T* (<) Tj (ThreadedTask 1 [import_file file1] FINISHED) Tj (>) Tj T* ET
+BT 1 0 0 1 0 17.71 Tm 12 TL /F3 10 Tf 0 0 0 rg (i) Tj (>) Tj ( .output 1) Tj T* (<) Tj (ThreadedTask 1 [import_file file1] FINISHED) Tj (>) Tj T* ET
 Q
 Q
 Q
@@ -13334,7 +13297,7 @@ Q
 q
 1 0 0 1 62.69291 517.4236 cm
 q
-BT 1 0 0 1 0 16.82 Tm 1.045868 Tw 12 TL /F1 10 Tf 0 0 0 rg (You can even skip the number argument: then ) Tj /F4 10 Tf (.output ) Tj /F1 10 Tf (will the return the output of the last launched) Tj T* 0 Tw (command \(the special commands like .output do not count\).) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm 1.045868 Tw 12 TL /F1 10 Tf 0 0 0 rg (You can even skip the number argument: then ) Tj /F3 10 Tf (.output ) Tj /F1 10 Tf (will the return the output of the last launched) Tj T* 0 Tw (command \(the special commands like .output do not count\).) Tj T* ET
 Q
 Q
 q
@@ -13358,7 +13321,7 @@ q
 n -6 -6 468.6898 60 re B*
 Q
 q
-BT 1 0 0 1 0 41.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (i) Tj (>) Tj ( import_file file2) Tj T* (<) Tj (ThreadedTask 5 [import_file file2] RUNNING) Tj (>) Tj  T* (i) Tj (>) Tj ( import_file file3) Tj T* (<) Tj (ThreadedTask 6 [import_file file3] RUNNING) Tj (>) Tj T* ET
+BT 1 0 0 1 0 41.71 Tm 12 TL /F3 10 Tf 0 0 0 rg (i) Tj (>) Tj ( import_file file2) Tj T* (<) Tj (ThreadedTask 5 [import_file file2] RUNNING) Tj (>) Tj  T* (i) Tj (>) Tj ( import_file file3) Tj T* (<) Tj (ThreadedTask 6 [import_file file3] RUNNING) Tj (>) Tj T* ET
 Q
 Q
 Q
@@ -13367,7 +13330,7 @@ Q
 q
 1 0 0 1 62.69291 410.2236 cm
 q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (The ) Tj /F4 10 Tf (.list ) Tj /F1 10 Tf (command displays all the running tasks:) Tj T* ET
+BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (The ) Tj /F3 10 Tf (.list ) Tj /F1 10 Tf (command displays all the running tasks:) Tj T* ET
 Q
 Q
 q
@@ -13384,7 +13347,7 @@ q
 n -6 -6 468.6898 48 re B*
 Q
 q
-BT 1 0 0 1 0 29.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (i) Tj (>) Tj ( .list) Tj T* (<) Tj (ThreadedTask 5 [import_file file2] RUNNING) Tj (>) Tj  T* (<) Tj (ThreadedTask 6 [import_file file3] RUNNING) Tj (>) Tj T* ET
+BT 1 0 0 1 0 29.71 Tm 12 TL /F3 10 Tf 0 0 0 rg (i) Tj (>) Tj ( .list) Tj T* (<) Tj (ThreadedTask 5 [import_file file2] RUNNING) Tj (>) Tj  T* (<) Tj (ThreadedTask 6 [import_file file3] RUNNING) Tj (>) Tj T* ET
 Q
 Q
 Q
@@ -13411,7 +13374,7 @@ q
 n -6 -6 468.6898 84 re B*
 Q
 q
-BT 1 0 0 1 0 65.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (i) Tj (>) Tj ( .kill 5) Tj T* (<) Tj (ThreadedTask 5 [import_file file2] TOBEKILLED) Tj (>) Tj  T* (# wait a bit ...) Tj T* (closing the file) Tj T* (i) Tj (>) Tj ( .output 5) Tj T* (<) Tj (ThreadedTask 5 [import_file file2] KILLED) Tj (>) Tj T* ET
+BT 1 0 0 1 0 65.71 Tm 12 TL /F3 10 Tf 0 0 0 rg (i) Tj (>) Tj ( .kill 5) Tj T* (<) Tj (ThreadedTask 5 [import_file file2] TOBEKILLED) Tj (>) Tj  T* (# wait a bit ...) Tj T* (closing the file) Tj T* (i) Tj (>) Tj ( .output 5) Tj T* (<) Tj (ThreadedTask 5 [import_file file2] KILLED) Tj (>) Tj T* ET
 Q
 Q
 Q
@@ -13420,7 +13383,7 @@ Q
 q
 1 0 0 1 62.69291 147.8236 cm
 q
-BT 1 0 0 1 0 76.82 Tm 1.100542 Tw 12 TL /F1 10 Tf 0 0 0 rg (You should notice that since at the Python level it is impossible to kill a thread, the ) Tj /F4 10 Tf (.kill ) Tj /F1 10 Tf (commands) Tj T* 0 Tw 1.793984 Tw (works by setting the status of the task to ) Tj /F4 10 Tf (TOBEKILLED) Tj /F1 10 Tf (. Internally the generator corresponding to the) Tj T* 0 Tw .632927 Tw (command is executed in the thread and the status is checked at each iteration: when the status become) Tj T* 0 Tw 2.578443 Tw /F4 10 Tf (TOBEKILLED ) Tj /F1 10 Tf (a ) Tj /F4 10 Tf (GeneratorExit ) Tj /F1 10 Tf (exception is raised and the thread terminates \(softly, so that the) Tj T* 0 Tw 2.328651 Tw /F4 10 Tf (finally ) Tj /F1 10 Tf (clause is honored\). In our example the generator is yielding back control once every 100) Tj T* 0 Tw 1.152619 Tw (iterations, i.e. every two seconds \(not much\). In order to get a responsive interface it is a good idea to) Tj T* 0 Tw (yield more often, for instance every 10 iterations \(i.e. 5 times per second\), as in the following code:) Tj T* ET
+BT 1 0 0 1 0 76.82 Tm 1.100542 Tw 12 TL /F1 10 Tf 0 0 0 rg (You should notice that since at the Python level it is impossible to kill a thread, the ) Tj /F3 10 Tf (.kill ) Tj /F1 10 Tf (commands) Tj T* 0 Tw 1.793984 Tw (works by setting the status of the task to ) Tj /F3 10 Tf (TOBEKILLED) Tj /F1 10 Tf (. Internally the generator corresponding to the) Tj T* 0 Tw .632927 Tw (command is executed in the thread and the status is checked at each iteration: when the status become) Tj T* 0 Tw 2.578443 Tw /F3 10 Tf (TOBEKILLED ) Tj /F1 10 Tf (a ) Tj /F3 10 Tf (GeneratorExit ) Tj /F1 10 Tf (exception is raised and the thread terminates \(softly, so that the) Tj T* 0 Tw 2.328651 Tw /F3 10 Tf (finally ) Tj /F1 10 Tf (clause is honored\). In our example the generator is yielding back control once every 100) Tj T* 0 Tw 1.152619 Tw (iterations, i.e. every two seconds \(not much\). In order to get a responsive interface it is a good idea to) Tj T* 0 Tw (yield more often, for instance every 10 iterations \(i.e. 5 times per second\), as in the following code:) Tj T* ET
 Q
 Q
 q
@@ -13438,7 +13401,7 @@ n -6 -6 468.6898 48 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 29.71 Tm /F4 10 Tf 12 TL (import time) Tj T* (import plac) Tj T*  T* ET
+BT 1 0 0 1 0 29.71 Tm /F3 10 Tf 12 TL (import time) Tj T* (import plac) Tj T*  T* ET
 Q
 Q
 Q
@@ -13476,7 +13439,7 @@ n -6 -6 468.6898 240 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 221.71 Tm /F4 10 Tf 12 TL (class FakeImporter\(object\):) Tj T* (    "A fake importer with an import_file command") Tj T* (    thcommands = ['import_file']) Tj T* (    def __init__\(self, dsn\):) Tj T* (        self.dsn = dsn) Tj T* (    def import_file\(self, fname\):) Tj T* (        "Import a file into the database") Tj T* (        try:) Tj T* (            for n in range\(10000\):) Tj T* (                time.sleep\(.02\)) Tj T* (                if n % 100 == 99: # every two seconds) Tj T* (                    yield 'Imported %d lines' % \(n+1\)) Tj T* (                if n % 10 == 9: # every 0.2 seconds) Tj T* (                    yield # go back and check the TOBEKILLED status) Tj T* (        finally:) Tj T* (            print\('closing the file'\)) Tj T*  T* (if __name__ == '__main__':) Tj T* (    plac.Interpreter.call\(FakeImporter\)) Tj T* ET
+BT 1 0 0 1 0 221.71 Tm /F3 10 Tf 12 TL (class FakeImporter\(object\):) Tj T* (    "A fake importer with an import_file command") Tj T* (    thcommands = ['import_file']) Tj T* (    def __init__\(self, dsn\):) Tj T* (        self.dsn = dsn) Tj T* (    def import_file\(self, fname\):) Tj T* (        "Import a file into the database") Tj T* (        try:) Tj T* (            for n in range\(10000\):) Tj T* (                time.sleep\(.02\)) Tj T* (                if n % 100 == 99: # every two seconds) Tj T* (                    yield 'Imported %d lines' % \(n+1\)) Tj T* (                if n % 10 == 9: # every 0.2 seconds) Tj T* (                    yield # go back and check the TOBEKILLED status) Tj T* (        finally:) Tj T* (            print\('closing the file'\)) Tj T*  T* (if __name__ == '__main__':) Tj T* (    plac.Interpreter.call\(FakeImporter\)) Tj T* ET
 Q
 Q
 Q
@@ -13507,13 +13470,13 @@ Q
 q
 1 0 0 1 62.69291 403.8236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 BT 1 0 0 1 0 2 Tm  T* ET
 q
 1 0 0 1 20 0 cm
 q
 0 0 0 rg
-BT 1 0 0 1 0 5.71 Tm /F4 10 Tf 12 TL (thcommands = ['import_file']) Tj T* ET
+BT 1 0 0 1 0 5.71 Tm /F3 10 Tf 12 TL (thcommands = ['import_file']) Tj T* ET
 Q
 Q
 q
@@ -13535,12 +13498,12 @@ Q
 q
 1 0 0 1 62.69291 367.8236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 BT 1 0 0 1 0 2 Tm  T* ET
 q
 1 0 0 1 20 0 cm
 q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F4 10 Tf 0 0 0 rg (mpcommands = ['import_file']) Tj /F1 10 Tf (.) Tj T* ET
+BT 1 0 0 1 0 4.82 Tm 12 TL /F3 10 Tf 0 0 0 rg (mpcommands = ['import_file']) Tj /F1 10 Tf (.) Tj T* ET
 Q
 Q
 q
@@ -13570,7 +13533,7 @@ q
 n -6 -6 468.6898 132 re B*
 Q
 q
-BT 1 0 0 1 0 113.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (i) Tj (>) Tj ( import_file file3) Tj T* (<) Tj (MPTask 1 [import_file file3] SUBMITTED) Tj (>) Tj  T* (i) Tj (>) Tj ( .kill 1) Tj T* (<) Tj (MPTask 1 [import_file file3] RUNNING) Tj (>) Tj  T* (closing the file) Tj T* (i) Tj (>) Tj ( .o 1) Tj T* (<) Tj (MPTask 1 [import_file file3] KILLED) Tj (>) Tj  T* (Imported 100 lines) Tj T* (Imported 200 lines) Tj T* (i) Tj (>) Tj T* ET
+BT 1 0 0 1 0 113.71 Tm 12 TL /F3 10 Tf 0 0 0 rg (i) Tj (>) Tj ( import_file file3) Tj T* (<) Tj (MPTask 1 [import_file file3] SUBMITTED) Tj (>) Tj  T* (i) Tj (>) Tj ( .kill 1) Tj T* (<) Tj (MPTask 1 [import_file file3] RUNNING) Tj (>) Tj  T* (closing the file) Tj T* (i) Tj (>) Tj ( .o 1) Tj T* (<) Tj (MPTask 1 [import_file file3] KILLED) Tj (>) Tj  T* (Imported 100 lines) Tj T* (Imported 200 lines) Tj T* (i) Tj (>) Tj T* ET
 Q
 Q
 Q
@@ -13586,7 +13549,7 @@ Q
 q
 1 0 0 1 62.69291 98.62362 cm
 q
-BT 1 0 0 1 0 28.82 Tm .128935 Tw 12 TL /F1 10 Tf 0 0 0 rg (On the plus side, when using processes you do not need to worry about killing a command: they are killed ) Tj T* 0 Tw .466412 Tw (immediately using a SIGTERM signal, and there is not a ) Tj /F4 10 Tf (TOBEKILLED ) Tj /F1 10 Tf (mechanism. Moreover, the killing ) Tj T* 0 Tw 1.50229 Tw (is guaranteed to be soft: internally a command receiving a SIGTERM raises a ) Tj /F4 10 Tf (TerminatedProcess) Tj T* 0 Tw ET
+BT 1 0 0 1 0 28.82 Tm .128935 Tw 12 TL /F1 10 Tf 0 0 0 rg (On the plus side, when using processes you do not need to worry about killing a command: they are killed ) Tj T* 0 Tw .466412 Tw (immediately using a SIGTERM signal, and there is not a ) Tj /F3 10 Tf (TOBEKILLED ) Tj /F1 10 Tf (mechanism. Moreover, the killing ) Tj T* 0 Tw 1.50229 Tw (is guaranteed to be soft: internally a command receiving a SIGTERM raises a ) Tj /F3 10 Tf (TerminatedProcess) Tj T* 0 Tw ET
 Q
 Q
 q
@@ -13629,7 +13592,7 @@ Q
 q
 1 0 0 1 62.69291 591.0236 cm
 q
-BT 1 0 0 1 0 88.82 Tm 1.895542 Tw 12 TL /F1 10 Tf 0 0 .501961 rg (plac ) Tj 0 0 0 rg (acts as a command-line task launcher and can be used as the base to build a GUI-based task) Tj T* 0 Tw .38561 Tw (launcher and task monitor. To this aim the interpreter class provides a ) Tj /F4 10 Tf (.submit ) Tj /F1 10 Tf (method which returns a) Tj T* 0 Tw 1.792339 Tw (task object and a ) Tj /F4 10 Tf (.tasks ) Tj /F1 10 Tf (method returning the list of all the tasks submitted to the interpreter. The) Tj T* 0 Tw .373516 Tw /F4 10 Tf (submit ) Tj /F1 10 Tf (method does not start the task and thus it is nonblocking. Each task has an ) Tj /F4 10 Tf (.outlist ) Tj /F1 10 Tf (attribute) Tj T* 0 Tw .106098 Tw (which is a list storing the value yielded by the generator underlying the task \(the ) Tj /F4 10 Tf (None ) Tj /F1 10 Tf (values are skipped) Tj T* 0 Tw .633318 Tw (though\): the ) Tj /F4 10 Tf (.outlist ) Tj /F1 10 Tf (grows as the task runs and more values are yielded. Accessing the ) Tj /F4 10 Tf (.outlist) Tj T* 0 Tw 1.051654 Tw /F1 10 Tf (is nonblocking and can be done freely. Finally there is a ) Tj /F4 10 Tf (.result ) Tj /F1 10 Tf (property which waits for the task to) Tj T* 0 Tw (finish and returns the last yielded value or raises an exception.) Tj T* ET
+BT 1 0 0 1 0 88.82 Tm 1.895542 Tw 12 TL /F1 10 Tf 0 0 .501961 rg (plac ) Tj 0 0 0 rg (acts as a command-line task launcher and can be used as the base to build a GUI-based task) Tj T* 0 Tw .38561 Tw (launcher and task monitor. To this aim the interpreter class provides a ) Tj /F3 10 Tf (.submit ) Tj /F1 10 Tf (method which returns a) Tj T* 0 Tw 1.792339 Tw (task object and a ) Tj /F3 10 Tf (.tasks ) Tj /F1 10 Tf (method returning the list of all the tasks submitted to the interpreter. The) Tj T* 0 Tw .373516 Tw /F3 10 Tf (submit ) Tj /F1 10 Tf (method does not start the task and thus it is nonblocking. Each task has an ) Tj /F3 10 Tf (.outlist ) Tj /F1 10 Tf (attribute) Tj T* 0 Tw .106098 Tw (which is a list storing the value yielded by the generator underlying the task \(the ) Tj /F3 10 Tf (None ) Tj /F1 10 Tf (values are skipped) Tj T* 0 Tw .633318 Tw (though\): the ) Tj /F3 10 Tf (.outlist ) Tj /F1 10 Tf (grows as the task runs and more values are yielded. Accessing the ) Tj /F3 10 Tf (.outlist) Tj T* 0 Tw 1.051654 Tw /F1 10 Tf (is nonblocking and can be done freely. Finally there is a ) Tj /F3 10 Tf (.result ) Tj /F1 10 Tf (property which waits for the task to) Tj T* 0 Tw (finish and returns the last yielded value or raises an exception.) Tj T* ET
 Q
 Q
 q
@@ -13654,7 +13617,7 @@ n -6 -6 468.6898 360 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 341.71 Tm /F4 10 Tf 12 TL (from Tkinter import *) Tj T* (from importer3 import FakeImporter) Tj T*  T* (def taskwidget\(root, task, tick=500\):) Tj T* (    "A Label widget showing the output of a task every 500 ms") Tj T* (    sv = StringVar\(root\)) Tj T* (    lb = Label\(root, textvariable=sv\)) Tj T* (    def show_outlist\(\):) Tj T* (        try:) Tj T* (            out = task.outlist[-1]) Tj T* (        except IndexError: # no output yet) Tj T* (            out = '') Tj T* (        sv.set\('%s %s' % \(task, out\)\)) Tj T* (        root.after\(tick, show_outlist\)) Tj T* (    root.after\(0, show_outlist\)) Tj T* (    return lb) Tj T*  T* (def monitor\(tasks\):) Tj T* (    root = Tk\(\)) Tj T* (    for task in tasks:) Tj T* (        task.run\(\)) Tj T* (        taskwidget\(root, task\).pack\(\)) Tj T* (    root.mainloop\(\)) Tj T*  T* (if __name__ == '__main__':) Tj T* (    import plac) Tj T* (    with plac.Interpreter\(plac.call\(FakeImporter\)\) as i:) Tj T* (        tasks = [i.submit\('import_file f1'\), i.submit\('import_file f2'\)]) Tj T* (        monitor\(tasks\)) Tj T* ET
+BT 1 0 0 1 0 341.71 Tm /F3 10 Tf 12 TL (from Tkinter import *) Tj T* (from importer3 import FakeImporter) Tj T*  T* (def taskwidget\(root, task, tick=500\):) Tj T* (    "A Label widget showing the output of a task every 500 ms") Tj T* (    sv = StringVar\(root\)) Tj T* (    lb = Label\(root, textvariable=sv\)) Tj T* (    def show_outlist\(\):) Tj T* (        try:) Tj T* (            out = task.outlist[-1]) Tj T* (        except IndexError: # no output yet) Tj T* (            out = '') Tj T* (        sv.set\('%s %s' % \(task, out\)\)) Tj T* (        root.after\(tick, show_outlist\)) Tj T* (    root.after\(0, show_outlist\)) Tj T* (    return lb) Tj T*  T* (def monitor\(tasks\):) Tj T* (    root = Tk\(\)) Tj T* (    for task in tasks:) Tj T* (        task.run\(\)) Tj T* (        taskwidget\(root, task\).pack\(\)) Tj T* (    root.mainloop\(\)) Tj T*  T* (if __name__ == '__main__':) Tj T* (    import plac) Tj T* (    with plac.Interpreter\(plac.call\(FakeImporter\)\) as i:) Tj T* (        tasks = [i.submit\('import_file f1'\), i.submit\('import_file f2'\)]) Tj T* (        monitor\(tasks\)) Tj T* ET
 Q
 Q
 Q
@@ -13686,7 +13649,7 @@ Q
 q
 1 0 0 1 62.69291 633.0236 cm
 q
-BT 1 0 0 1 0 100.82 Tm 1.174751 Tw 12 TL /F1 10 Tf 0 0 .501961 rg (plac ) Tj 0 0 0 rg (is certainly not intended as a tool for parallel computing, but still you can use it to launch a set of) Tj T* 0 Tw .494269 Tw (commands and to collect the results, similarly to the MapReduce pattern recently popularized by Google.) Tj T* 0 Tw .329431 Tw (In order to give an example, I will consider the "Hello World" of parallel computing, i.e. the computation of) Tj T* 0 Tw .229431 Tw (pi with independent processes. There is a huge number of algorithms to compute pi; here I will describe a) Tj T* 0 Tw .30683 Tw (trivial one chosen for simplicity, not per efficienty. The trick is to consider the first quadrant of a circle with) Tj T* 0 Tw .102488 Tw (radius 1 and to extract a number of points ) Tj /F4 10 Tf (\(x, y\) ) Tj /F1 10 Tf (with ) Tj /F4 10 Tf (x ) Tj /F1 10 Tf (and ) Tj /F4 10 Tf (y ) Tj /F1 10 Tf (random variables in the interval ) Tj /F4 10 Tf ([0,1]) Tj /F1 10 Tf (.) Tj T* 0 Tw .743876 Tw (The probability of extracting a number inside the quadrant \(i.e. with ) Tj /F4 10 Tf (x^2 + y^2 < 1) Tj /F1 10 Tf (\) is proportional to) Tj T* 0 Tw .725251 Tw (the area of the quadrant \(i.e. ) Tj /F4 10 Tf (pi/4) Tj /F1 10 Tf (\). The value of ) Tj /F4 10 Tf (pi ) Tj /F1 10 Tf (therefore can be extracted by multiplying by 4 the) Tj T* 0 Tw (ratio between the number of points in the quadrant versus the total number of points ) Tj /F4 10 Tf (N) Tj /F1 10 Tf (, for ) Tj /F4 10 Tf (N ) Tj /F1 10 Tf (large:) Tj T* ET
+BT 1 0 0 1 0 100.82 Tm 1.174751 Tw 12 TL /F1 10 Tf 0 0 .501961 rg (plac ) Tj 0 0 0 rg (is certainly not intended as a tool for parallel computing, but still you can use it to launch a set of) Tj T* 0 Tw .494269 Tw (commands and to collect the results, similarly to the MapReduce pattern recently popularized by Google.) Tj T* 0 Tw .329431 Tw (In order to give an example, I will consider the "Hello World" of parallel computing, i.e. the computation of) Tj T* 0 Tw .229431 Tw (pi with independent processes. There is a huge number of algorithms to compute pi; here I will describe a) Tj T* 0 Tw .30683 Tw (trivial one chosen for simplicity, not per efficienty. The trick is to consider the first quadrant of a circle with) Tj T* 0 Tw .102488 Tw (radius 1 and to extract a number of points ) Tj /F3 10 Tf (\(x, y\) ) Tj /F1 10 Tf (with ) Tj /F3 10 Tf (x ) Tj /F1 10 Tf (and ) Tj /F3 10 Tf (y ) Tj /F1 10 Tf (random variables in the interval ) Tj /F3 10 Tf ([0,1]) Tj /F1 10 Tf (.) Tj T* 0 Tw .743876 Tw (The probability of extracting a number inside the quadrant \(i.e. with ) Tj /F3 10 Tf (x^2 + y^2 < 1) Tj /F1 10 Tf (\) is proportional to) Tj T* 0 Tw .725251 Tw (the area of the quadrant \(i.e. ) Tj /F3 10 Tf (pi/4) Tj /F1 10 Tf (\). The value of ) Tj /F3 10 Tf (pi ) Tj /F1 10 Tf (therefore can be extracted by multiplying by 4 the) Tj T* 0 Tw (ratio between the number of points in the quadrant versus the total number of points ) Tj /F3 10 Tf (N) Tj /F1 10 Tf (, for ) Tj /F3 10 Tf (N ) Tj /F1 10 Tf (large:) Tj T* ET
 Q
 Q
 q
@@ -13703,7 +13666,7 @@ q
 n -6 -6 468.6898 96 re B*
 Q
 q
-BT 1 0 0 1 0 77.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (def calc_pi\(N\):) Tj T* (    inside = 0) Tj T* (    for j in xrange\(N\):) Tj T* (        x, y = random\(\), random\(\)) Tj T* (        if x*x + y*y ) Tj (<) Tj ( 1:) Tj T* (            inside += 1) Tj T* (    return \(4.0 * inside\) / N) Tj T* ET
+BT 1 0 0 1 0 77.71 Tm 12 TL /F3 10 Tf 0 0 0 rg (def calc_pi\(N\):) Tj T* (    inside = 0) Tj T* (    for j in xrange\(N\):) Tj T* (        x, y = random\(\), random\(\)) Tj T* (        if x*x + y*y ) Tj (<) Tj ( 1:) Tj T* (            inside += 1) Tj T* (    return \(4.0 * inside\) / N) Tj T* ET
 Q
 Q
 Q
@@ -13719,7 +13682,7 @@ Q
 q
 1 0 0 1 62.69291 429.8236 cm
 q
-BT 1 0 0 1 0 16.82 Tm .313984 Tw 12 TL /F1 10 Tf 0 0 0 rg (Here is a script implementing the algorithm and working in three different modes \(parallel mode, threaded) Tj T* 0 Tw (mode and sequential mode\) depending on a ) Tj /F4 10 Tf (mode ) Tj /F1 10 Tf (option:) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm .313984 Tw 12 TL /F1 10 Tf 0 0 0 rg (Here is a script implementing the algorithm and working in three different modes \(parallel mode, threaded) Tj T* 0 Tw (mode and sequential mode\) depending on a ) Tj /F3 10 Tf (mode ) Tj /F1 10 Tf (option:) Tj T* ET
 Q
 Q
 q
@@ -13736,7 +13699,7 @@ q
 n -6 -6 468.6898 324 re B*
 Q
 q
-BT 1 0 0 1 0 305.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (from __future__ import with_statement) Tj T* (from random import random) Tj T* (import multiprocessing) Tj T* (import plac) Tj T*  T* (class PiCalculator\(object\):) Tj T* (    """Compute pi in parallel with threads or processes""") Tj T* (    ) Tj T* (    @plac.annotations\() Tj T* (        npoints=\('number of integration points', 'positional', None, int\),) Tj T* (        mode=\('sequential|parallel|threaded', 'option', 'm', str, 'SPT'\)\)) Tj T* (    def __init__\(self, npoints, mode='S'\):) Tj T* (        self.npoints = npoints) Tj T* (        if mode == 'P':) Tj T* (            self.mpcommands = ['calc_pi']) Tj T* (        elif mode == 'T':) Tj T* (            self.thcommands = ['calc_pi']) Tj T* (        elif mode == 'S':) Tj T* (            self.commands = ['calc_pi']) Tj T* (        self.n_cpu = multiprocessing.cpu_count\(\)) Tj T* (    ) Tj T* (    def submit_tasks\(self\):) Tj T* (        self.i = plac.Interpreter\(self\).__enter__\(\)            ) Tj T* (        return [self.i.submit\('calc_pi %d' % \(self.npoints / self.n_cpu\)\)) Tj T* (                for _ in range\(self.n_cpu\)]) Tj T*  T* ET
+BT 1 0 0 1 0 305.71 Tm 12 TL /F3 10 Tf 0 0 0 rg (from __future__ import with_statement) Tj T* (from random import random) Tj T* (import multiprocessing) Tj T* (import plac) Tj T*  T* (class PiCalculator\(object\):) Tj T* (    """Compute pi in parallel with threads or processes""") Tj T* (    ) Tj T* (    @plac.annotations\() Tj T* (        npoints=\('number of integration points', 'positional', None, int\),) Tj T* (        mode=\('sequential|parallel|threaded', 'option', 'm', str, 'SPT'\)\)) Tj T* (    def __init__\(self, npoints, mode='S'\):) Tj T* (        self.npoints = npoints) Tj T* (        if mode == 'P':) Tj T* (            self.mpcommands = ['calc_pi']) Tj T* (        elif mode == 'T':) Tj T* (            self.thcommands = ['calc_pi']) Tj T* (        elif mode == 'S':) Tj T* (            self.commands = ['calc_pi']) Tj T* (        self.n_cpu = multiprocessing.cpu_count\(\)) Tj T* (    ) Tj T* (    def submit_tasks\(self\):) Tj T* (        self.i = plac.Interpreter\(self\).__enter__\(\)            ) Tj T* (        return [self.i.submit\('calc_pi %d' % \(self.npoints / self.n_cpu\)\)) Tj T* (                for _ in range\(self.n_cpu\)]) Tj T*  T* ET
 Q
 Q
 Q
@@ -13773,7 +13736,7 @@ q
 n -6 -6 468.6898 456 re B*
 Q
 q
-BT 1 0 0 1 0 437.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (    def close\(self\):) Tj T* (        self.i.close\(\)) Tj T*  T* (    @plac.annotations\() Tj T* (        npoints=\('npoints', 'positional', None, int\)\)) Tj T* (    def calc_pi\(self, npoints\):) Tj T* (        counts = 0) Tj T* (        for j in xrange\(npoints\):) Tj T* (            n, r = divmod\(j, 1000000\)) Tj T* (            if r == 0:) Tj T* (                yield '%dM iterations' % n) Tj T* (            x, y = random\(\), random\(\)) Tj T* (            if x*x + y*y ) Tj (<) Tj ( 1:) Tj T* (                counts += 1) Tj T* (        yield \(4.0 * counts\)/npoints) Tj T*  T* (    def run\(self\):) Tj T* (        tasks = self.i.tasks\(\)) Tj T* (        for t in tasks:) Tj T* (            t.run\(\)) Tj T* (        try:) Tj T* (            total = 0) Tj T* (            for task in tasks:) Tj T* (                total += task.result) Tj T* (        except: # the task was killed) Tj T* (            print tasks) Tj T* (            return) Tj T* (        return total / self.n_cpu) Tj T*  T* (if __name__ == '__main__':) Tj T* (    pc = plac.call\(PiCalculator\)) Tj T* (    pc.submit_tasks\(\)) Tj T* (    try:) Tj T* (        import time; t0 = time.time\(\)) Tj T* (        print '%f in %f seconds ' % \(pc.run\(\), time.time\(\) - t0\)) Tj T* (    finally:) Tj T* (        pc.close\(\)) Tj T* ET
+BT 1 0 0 1 0 437.71 Tm 12 TL /F3 10 Tf 0 0 0 rg (    def close\(self\):) Tj T* (        self.i.close\(\)) Tj T*  T* (    @plac.annotations\() Tj T* (        npoints=\('npoints', 'positional', None, int\)\)) Tj T* (    def calc_pi\(self, npoints\):) Tj T* (        counts = 0) Tj T* (        for j in xrange\(npoints\):) Tj T* (            n, r = divmod\(j, 1000000\)) Tj T* (            if r == 0:) Tj T* (                yield '%dM iterations' % n) Tj T* (            x, y = random\(\), random\(\)) Tj T* (            if x*x + y*y ) Tj (<) Tj ( 1:) Tj T* (                counts += 1) Tj T* (        yield \(4.0 * counts\)/npoints) Tj T*  T* (    def run\(self\):) Tj T* (        tasks = self.i.tasks\(\)) Tj T* (        for t in tasks:) Tj T* (            t.run\(\)) Tj T* (        try:) Tj T* (            total = 0) Tj T* (            for task in tasks:) Tj T* (                total += task.result) Tj T* (        except: # the task was killed) Tj T* (            print tasks) Tj T* (            return) Tj T* (        return total / self.n_cpu) Tj T*  T* (if __name__ == '__main__':) Tj T* (    pc = plac.call\(PiCalculator\)) Tj T* (    pc.submit_tasks\(\)) Tj T* (    try:) Tj T* (        import time; t0 = time.time\(\)) Tj T* (        print '%f in %f seconds ' % \(pc.run\(\), time.time\(\) - t0\)) Tj T* (    finally:) Tj T* (        pc.close\(\)) Tj T* ET
 Q
 Q
 Q
@@ -13782,7 +13745,7 @@ Q
 q
 1 0 0 1 62.69291 227.8236 cm
 q
-BT 1 0 0 1 0 64.82 Tm .381797 Tw 12 TL /F1 10 Tf 0 0 0 rg (Notice the ) Tj /F4 10 Tf (submit_tasks ) Tj /F1 10 Tf (method, which instantiates and initializes a ) Tj /F4 10 Tf (plac.Interpreter ) Tj /F1 10 Tf (object and) Tj T* 0 Tw 3.38152 Tw (submits a number of commands corresponding to the number of available CPUs. The ) Tj /F4 10 Tf (calc_pi) Tj T* 0 Tw 3.796651 Tw /F1 10 Tf (command yield a log message every million of interactions, just to monitor the progress of the) Tj T* 0 Tw 1.751318 Tw (computation. The ) Tj /F4 10 Tf (run ) Tj /F1 10 Tf (method starts all the submitted commands in parallel and sums the results. It) Tj T* 0 Tw 1.17104 Tw (returns the average value of ) Tj /F4 10 Tf (pi ) Tj /F1 10 Tf (after the slowest CPU has finished its job \(if the CPUs are equal and) Tj T* 0 Tw (equally busy they should finish more or less at the same time\).) Tj T* ET
+BT 1 0 0 1 0 64.82 Tm .381797 Tw 12 TL /F1 10 Tf 0 0 0 rg (Notice the ) Tj /F3 10 Tf (submit_tasks ) Tj /F1 10 Tf (method, which instantiates and initializes a ) Tj /F3 10 Tf (plac.Interpreter ) Tj /F1 10 Tf (object and) Tj T* 0 Tw 3.38152 Tw (submits a number of commands corresponding to the number of available CPUs. The ) Tj /F3 10 Tf (calc_pi) Tj T* 0 Tw 3.796651 Tw /F1 10 Tf (command yield a log message every million of interactions, just to monitor the progress of the) Tj T* 0 Tw 1.751318 Tw (computation. The ) Tj /F3 10 Tf (run ) Tj /F1 10 Tf (method starts all the submitted commands in parallel and sums the results. It) Tj T* 0 Tw 1.17104 Tw (returns the average value of ) Tj /F3 10 Tf (pi ) Tj /F1 10 Tf (after the slowest CPU has finished its job \(if the CPUs are equal and) Tj T* 0 Tw (equally busy they should finish more or less at the same time\).) Tj T* ET
 Q
 Q
 q
@@ -13807,7 +13770,7 @@ n -6 -6 468.6898 84 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 65.71 Tm /F4 10 Tf 12 TL ($ python picalculator.py -mP 10000000) Tj T* (3.141904 in 5.744545 seconds) Tj T* ($ python picalculator.py -mT 10000000) Tj T* (3.141272 in 13.875645 seconds) Tj T* ($ python picalculator.py -mS 10000000) Tj T* (3.141586 in 11.353841 seconds) Tj T* ET
+BT 1 0 0 1 0 65.71 Tm /F3 10 Tf 12 TL ($ python picalculator.py -mP 10000000) Tj T* (3.141904 in 5.744545 seconds) Tj T* ($ python picalculator.py -mT 10000000) Tj T* (3.141272 in 13.875645 seconds) Tj T* ($ python picalculator.py -mS 10000000) Tj T* (3.141586 in 11.353841 seconds) Tj T* ET
 Q
 Q
 Q
@@ -13827,7 +13790,7 @@ endobj
 % 'R454': class PDFStream 
 454 0 obj
 % page stream
-<< /Length 5571 >>
+<< /Length 5007 >>
 stream
 1 0 0 1 0 0 cm BT /F1 12 Tf 14.4 TL ET
 q
@@ -13838,19 +13801,46 @@ BT 1 0 0 1 0 16.82 Tm /F1 10 Tf 12 TL 1.711751 Tw (As you see using processes on
 Q
 Q
 q
-1 0 0 1 62.69291 711.0236 cm
+1 0 0 1 62.69291 675.0236 cm
+q
+BT 1 0 0 1 0 52.82 Tm .167765 Tw 12 TL /F1 10 Tf 0 0 0 rg (Since the pattern submit a bunch of tasks, starts them and collect the results is so common, ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (provides) Tj T* 0 Tw .493828 Tw (an utility function ) Tj /F3 10 Tf (runp\(genseq, mode='p', start=True\) ) Tj /F1 10 Tf (to start a bunch a generators and return) Tj T* 0 Tw .411488 Tw (a list of task objects. By default ) Tj /F3 10 Tf (runp ) Tj /F1 10 Tf (use processes, but you can use threads by passing ) Tj /F3 10 Tf (t ) Tj /F1 10 Tf (as mode. If) Tj T* 0 Tw .382339 Tw (you do not wont to start the tasks, you can say so \() Tj /F3 10 Tf (start=False) Tj /F1 10 Tf (\). With ) Tj /F3 10 Tf (runp ) Tj /F1 10 Tf (the picalculator becomes) Tj T* 0 Tw (a one-liner:) Tj T* ET
+Q
+Q
+q
+1 0 0 1 62.69291 642.4159 cm
+q
+q
+.976496 0 0 .976496 0 0 cm
+q
+1 0 0 1 6.6 6.758862 cm
+q
+.662745 .662745 .662745 RG
+.5 w
+.960784 .960784 .862745 rg
+n -6 -6 480 24 re B*
+Q
+q
+0 0 0 rg
+BT 1 0 0 1 0 5.71 Tm /F3 10 Tf 12 TL (sum\(task.result for task in plac.runp\(calc_pi\(N\) for i in range\(ncpus\)\)\)/ncpus) Tj T* ET
+Q
+Q
+Q
+Q
+Q
+q
+1 0 0 1 62.69291 612.4159 cm
 q
 BT 1 0 0 1 0 7.23 Tm 18 TL /F2 15 Tf 0 0 0 rg (The plac server) Tj T* ET
 Q
 Q
 q
-1 0 0 1 62.69291 597.0236 cm
+1 0 0 1 62.69291 498.4159 cm
 q
-BT 1 0 0 1 0 100.82 Tm 1.258443 Tw 12 TL /F1 10 Tf 0 0 0 rg (A command-line oriented interface can be easily converted into a socket-based interface. Starting from) Tj T* 0 Tw .930574 Tw (release 0.7 plac features a builtin server which is able to accept commands from multiple clients and to) Tj T* 0 Tw .994692 Tw (execute them. The server works by instantiating a separate interpreter for each client, so that if a client) Tj T* 0 Tw 1.08784 Tw (interpreter dies for any reason the other interpreters keep working. To avoid external dependencies the) Tj T* 0 Tw .872209 Tw (server is based on the ) Tj /F4 10 Tf (asynchat ) Tj /F1 10 Tf (module in the standard library, but it would not be difficult to replace) Tj T* 0 Tw 2.386412 Tw (the server with a different one \(for instance, a Twisted server\). Since ) Tj /F4 10 Tf (asynchat) Tj /F1 10 Tf (-based servers are) Tj T* 0 Tw .755984 Tw (asynchronous, any blocking command in the interpreter should be run in a separated process or thread.) Tj T* 0 Tw 1.157633 Tw (The default port for the ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (server is 2199, and the command to signal end-of-connection is EOF. For) Tj T* 0 Tw (instance, here is how you could manage remote import on a database \(say a SQLite db\):) Tj T* ET
+BT 1 0 0 1 0 100.82 Tm 1.258443 Tw 12 TL /F1 10 Tf 0 0 0 rg (A command-line oriented interface can be easily converted into a socket-based interface. Starting from) Tj T* 0 Tw .930574 Tw (release 0.7 plac features a builtin server which is able to accept commands from multiple clients and to) Tj T* 0 Tw .994692 Tw (execute them. The server works by instantiating a separate interpreter for each client, so that if a client) Tj T* 0 Tw 1.08784 Tw (interpreter dies for any reason the other interpreters keep working. To avoid external dependencies the) Tj T* 0 Tw .872209 Tw (server is based on the ) Tj /F3 10 Tf (asynchat ) Tj /F1 10 Tf (module in the standard library, but it would not be difficult to replace) Tj T* 0 Tw 2.386412 Tw (the server with a different one \(for instance, a Twisted server\). Since ) Tj /F3 10 Tf (asynchat) Tj /F1 10 Tf (-based servers are) Tj T* 0 Tw .755984 Tw (asynchronous, any blocking command in the interpreter should be run in a separated process or thread.) Tj T* 0 Tw 1.157633 Tw (The default port for the ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (server is 2199, and the command to signal end-of-connection is EOF. For) Tj T* 0 Tw (instance, here is how you could manage remote import on a database \(say a SQLite db\):) Tj T* ET
 Q
 Q
 q
-1 0 0 1 62.69291 467.8236 cm
+1 0 0 1 62.69291 369.2159 cm
 q
 q
 1 0 0 1 0 0 cm
@@ -13864,20 +13854,20 @@ n -6 -6 468.6898 120 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 101.71 Tm /F4 10 Tf 12 TL (import plac) Tj T* (from importer2 import FakeImporter) Tj T*  T* (def main\(port=2199\):) Tj T* (    main = FakeImporter\('dsn'\)) Tj T* (    plac.Interpreter\(main\).start_server\(port\)) Tj T* (    ) Tj T* (if __name__ == '__main__':) Tj T* (   plac.call\(main\)) Tj T* ET
+BT 1 0 0 1 0 101.71 Tm /F3 10 Tf 12 TL (import plac) Tj T* (from importer2 import FakeImporter) Tj T*  T* (def main\(port=2199\):) Tj T* (    main = FakeImporter\('dsn'\)) Tj T* (    plac.Interpreter\(main\).start_server\(port\)) Tj T* (    ) Tj T* (if __name__ == '__main__':) Tj T* (   plac.call\(main\)) Tj T* ET
 Q
 Q
 Q
 Q
 Q
 q
-1 0 0 1 62.69291 447.8236 cm
+1 0 0 1 62.69291 349.2159 cm
 q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (You can connect to the server with ) Tj /F4 10 Tf (telnet ) Tj /F1 10 Tf (on port 2199, as follows:) Tj T* ET
+BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (You can connect to the server with ) Tj /F3 10 Tf (telnet ) Tj /F1 10 Tf (on port 2199, as follows:) Tj T* ET
 Q
 Q
 q
-1 0 0 1 62.69291 270.6236 cm
+1 0 0 1 62.69291 172.0159 cm
 q
 q
 1 0 0 1 0 0 cm
@@ -13890,34 +13880,51 @@ q
 n -6 -6 468.6898 168 re B*
 Q
 q
-BT 1 0 0 1 0 149.71 Tm 12 TL /F4 10 Tf 0 0 0 rg ($ telnet localhost 2199) Tj T* (Trying ::1...) Tj T* (Trying 127.0.0.1...) Tj T* (Connected to localhost.) Tj T* (Escape character is '^]'.) Tj T* (i) Tj (>) Tj ( import_file f1) Tj T* (i) Tj (>) Tj ( .list) Tj T* (<) Tj (ThreadedTask 1 [import_file f1] RUNNING) Tj (>) Tj  T* (i) Tj (>) Tj ( .out) Tj T* (Imported 100 lines) Tj T* (Imported 200 lines) Tj T* (i) Tj (>) Tj ( EOF) Tj T* (Connection closed by foreign host.) Tj T* ET
+BT 1 0 0 1 0 149.71 Tm 12 TL /F3 10 Tf 0 0 0 rg ($ telnet localhost 2199) Tj T* (Trying ::1...) Tj T* (Trying 127.0.0.1...) Tj T* (Connected to localhost.) Tj T* (Escape character is '^]'.) Tj T* (i) Tj (>) Tj ( import_file f1) Tj T* (i) Tj (>) Tj ( .list) Tj T* (<) Tj (ThreadedTask 1 [import_file f1] RUNNING) Tj (>) Tj  T* (i) Tj (>) Tj ( .out) Tj T* (Imported 100 lines) Tj T* (Imported 200 lines) Tj T* (i) Tj (>) Tj ( EOF) Tj T* (Connection closed by foreign host.) Tj T* ET
 Q
 Q
 Q
 Q
 Q
 q
-1 0 0 1 62.69291 240.6236 cm
+1 0 0 1 62.69291 142.0159 cm
 q
 BT 1 0 0 1 0 7.23 Tm 18 TL /F2 15 Tf 0 0 0 rg (Summary) Tj T* ET
 Q
 Q
 q
-1 0 0 1 62.69291 198.6236 cm
+1 0 0 1 62.69291 100.0159 cm
 q
 BT 1 0 0 1 0 28.82 Tm 2.203318 Tw 12 TL /F1 10 Tf 0 0 0 rg (Once ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (claimed to be the easiest command-line arguments parser in the world. Having read this) Tj T* 0 Tw .673322 Tw (document you may think that it is not so easy after all. But it is a false impression. Actually the rules are) Tj T* 0 Tw (quite simple:) Tj T* ET
 Q
 Q
 q
-1 0 0 1 62.69291 192.6236 cm
+1 0 0 1 62.69291 94.01593 cm
 Q
 q
-1 0 0 1 62.69291 192.6236 cm
+1 0 0 1 62.69291 94.01593 cm
 Q
 q
-1 0 0 1 62.69291 174.6236 cm
+1 0 0 1 56.69291 56.69291 cm
+q
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 235.3849 0 Td (43) Tj T* -235.3849 0 Td ET
+Q
+Q
+ 
+endstream
+
+endobj
+% 'R455': class PDFStream 
+455 0 obj
+% page stream
+<< /Length 6620 >>
+stream
+1 0 0 1 0 0 cm BT /F1 12 Tf 14.4 TL ET
+q
+1 0 0 1 62.69291 747.0236 cm
+0 0 0 rg
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 3 cm
 q
@@ -13928,22 +13935,22 @@ Q
 q
 1 0 0 1 23 3 cm
 q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (if you want to implement a command-line script, use ) Tj /F4 10 Tf (plac.call) Tj /F1 10 Tf (;) Tj T* ET
+BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (if you want to implement a command-line script, use ) Tj /F3 10 Tf (plac.call) Tj /F1 10 Tf (;) Tj T* ET
 Q
 Q
 q
 Q
 Q
 q
-1 0 0 1 62.69291 174.6236 cm
+1 0 0 1 62.69291 747.0236 cm
 Q
 q
-1 0 0 1 62.69291 174.6236 cm
+1 0 0 1 62.69291 747.0236 cm
 Q
 q
-1 0 0 1 62.69291 114.6236 cm
+1 0 0 1 62.69291 687.0236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 45 cm
 q
@@ -13954,7 +13961,7 @@ Q
 q
 1 0 0 1 23 45 cm
 q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (if you want to implement a command interpreter, use ) Tj /F4 10 Tf (plac.Interpreter) Tj /F1 10 Tf (:) Tj T* ET
+BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (if you want to implement a command interpreter, use ) Tj /F3 10 Tf (plac.Interpreter) Tj /F1 10 Tf (:) Tj T* ET
 Q
 Q
 q
@@ -13966,7 +13973,7 @@ Q
 q
 1 0 0 1 23 21 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 3 cm
 q
@@ -13977,7 +13984,7 @@ Q
 q
 1 0 0 1 23 3 cm
 q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (for an interactive interpreter, call the ) Tj /F4 10 Tf (.interact ) Tj /F1 10 Tf (method;) Tj T* ET
+BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (for an interactive interpreter, call the ) Tj /F3 10 Tf (.interact ) Tj /F1 10 Tf (method;) Tj T* ET
 Q
 Q
 q
@@ -13992,7 +13999,7 @@ Q
 q
 1 0 0 1 23 3 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 3 cm
 q
@@ -14003,7 +14010,7 @@ Q
 q
 1 0 0 1 23 3 cm
 q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (for an batch interpreter, call the ) Tj /F4 10 Tf (.execute ) Tj /F1 10 Tf (method;) Tj T* ET
+BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (for an batch interpreter, call the ) Tj /F3 10 Tf (.execute ) Tj /F1 10 Tf (method;) Tj T* ET
 Q
 Q
 q
@@ -14019,32 +14026,15 @@ q
 Q
 Q
 q
-1 0 0 1 62.69291 114.6236 cm
-Q
-q
-1 0 0 1 62.69291 114.6236 cm
+1 0 0 1 62.69291 687.0236 cm
 Q
 q
-1 0 0 1 56.69291 56.69291 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 235.3849 0 Td (43) Tj T* -235.3849 0 Td ET
-Q
+1 0 0 1 62.69291 687.0236 cm
 Q
- 
-endstream
-
-endobj
-% 'R455': class PDFStream 
-455 0 obj
-% page stream
-<< /Length 5394 >>
-stream
-1 0 0 1 0 0 cm BT /F1 12 Tf 14.4 TL ET
 q
-1 0 0 1 62.69291 735.0236 cm
+1 0 0 1 62.69291 657.0236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 15 cm
 q
@@ -14055,22 +14045,22 @@ Q
 q
 1 0 0 1 23 3 cm
 q
-BT 1 0 0 1 0 16.82 Tm 5.126647 Tw 12 TL /F1 10 Tf 0 0 0 rg (for testing call the ) Tj /F4 10 Tf (Interpreter.check ) Tj /F1 10 Tf (method in the appropriate context or use the) Tj T* 0 Tw /F4 10 Tf (Interpreter.doctest ) Tj /F1 10 Tf (feature;) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm 5.126647 Tw 12 TL /F1 10 Tf 0 0 0 rg (for testing call the ) Tj /F3 10 Tf (Interpreter.check ) Tj /F1 10 Tf (method in the appropriate context or use the) Tj T* 0 Tw /F3 10 Tf (Interpreter.doctest ) Tj /F1 10 Tf (feature;) Tj T* ET
 Q
 Q
 q
 Q
 Q
 q
-1 0 0 1 62.69291 735.0236 cm
+1 0 0 1 62.69291 657.0236 cm
 Q
 q
-1 0 0 1 62.69291 735.0236 cm
+1 0 0 1 62.69291 657.0236 cm
 Q
 q
-1 0 0 1 62.69291 705.0236 cm
+1 0 0 1 62.69291 627.0236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 15 cm
 q
@@ -14081,22 +14071,22 @@ Q
 q
 1 0 0 1 23 3 cm
 q
-BT 1 0 0 1 0 16.82 Tm 1.356457 Tw 12 TL /F1 10 Tf 0 0 0 rg (if you need to go at a lower level, you may need to call the ) Tj /F4 10 Tf (Interpreter.send ) Tj /F1 10 Tf (method which) Tj T* 0 Tw (returns a \(finished\) ) Tj /F4 10 Tf (Task ) Tj /F1 10 Tf (object.) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm 1.356457 Tw 12 TL /F1 10 Tf 0 0 0 rg (if you need to go at a lower level, you may need to call the ) Tj /F3 10 Tf (Interpreter.send ) Tj /F1 10 Tf (method which) Tj T* 0 Tw (returns a \(finished\) ) Tj /F3 10 Tf (Task ) Tj /F1 10 Tf (object.) Tj T* ET
 Q
 Q
 q
 Q
 Q
 q
-1 0 0 1 62.69291 705.0236 cm
+1 0 0 1 62.69291 627.0236 cm
 Q
 q
-1 0 0 1 62.69291 705.0236 cm
+1 0 0 1 62.69291 627.0236 cm
 Q
 q
-1 0 0 1 62.69291 675.0236 cm
+1 0 0 1 62.69291 597.0236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 15 cm
 q
@@ -14107,22 +14097,22 @@ Q
 q
 1 0 0 1 23 3 cm
 q
-BT 1 0 0 1 0 16.82 Tm 1.469269 Tw 12 TL /F1 10 Tf 0 0 0 rg (long running command can be executed in the background as threads or processes: just declare) Tj T* 0 Tw (them in the lists ) Tj /F4 10 Tf (thcommands ) Tj /F1 10 Tf (and ) Tj /F4 10 Tf (mpcommands ) Tj /F1 10 Tf (respectively.) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm 1.469269 Tw 12 TL /F1 10 Tf 0 0 0 rg (long running command can be executed in the background as threads or processes: just declare) Tj T* 0 Tw (them in the lists ) Tj /F3 10 Tf (thcommands ) Tj /F1 10 Tf (and ) Tj /F3 10 Tf (mpcommands ) Tj /F1 10 Tf (respectively.) Tj T* ET
 Q
 Q
 q
 Q
 Q
 q
-1 0 0 1 62.69291 675.0236 cm
+1 0 0 1 62.69291 597.0236 cm
 Q
 q
-1 0 0 1 62.69291 675.0236 cm
+1 0 0 1 62.69291 597.0236 cm
 Q
 q
-1 0 0 1 62.69291 645.0236 cm
+1 0 0 1 62.69291 567.0236 cm
 0 0 0 rg
-BT /F3 10 Tf 12 TL ET
+BT /F1 10 Tf 12 TL ET
 q
 1 0 0 1 6 15 cm
 q
@@ -14133,49 +14123,49 @@ Q
 q
 1 0 0 1 23 3 cm
 q
-BT 1 0 0 1 0 16.82 Tm 2.171647 Tw 12 TL /F1 10 Tf 0 0 0 rg (the ) Tj /F4 10 Tf (.start_server ) Tj /F1 10 Tf (method starts an asynchronous server on the given port number \(default) Tj T* 0 Tw (2199\)) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm 2.171647 Tw 12 TL /F1 10 Tf 0 0 0 rg (the ) Tj /F3 10 Tf (.start_server ) Tj /F1 10 Tf (method starts an asynchronous server on the given port number \(default) Tj T* 0 Tw (2199\)) Tj T* ET
 Q
 Q
 q
 Q
 Q
 q
-1 0 0 1 62.69291 645.0236 cm
+1 0 0 1 62.69291 567.0236 cm
 Q
 q
-1 0 0 1 62.69291 645.0236 cm
+1 0 0 1 62.69291 567.0236 cm
 Q
 q
-1 0 0 1 62.69291 627.0236 cm
+1 0 0 1 62.69291 549.0236 cm
 q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (Moreover, remember that ) Tj /F4 10 Tf (plac_runner.py ) Tj /F1 10 Tf (is your friend.) Tj T* ET
+BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (Moreover, remember that ) Tj /F3 10 Tf (plac_runner.py ) Tj /F1 10 Tf (is your friend.) Tj T* ET
 Q
 Q
 q
-1 0 0 1 62.69291 598.6772 cm
+1 0 0 1 62.69291 520.6772 cm
 n 0 14.17323 m 469.8898 14.17323 l S
 Q
 q
-1 0 0 1 62.69291 568.6772 cm
+1 0 0 1 62.69291 490.6772 cm
 q
 BT 1 0 0 1 0 7.23 Tm 18 TL /F2 15 Tf 0 0 0 rg (Appendix: custom annotation objects) Tj T* ET
 Q
 Q
 q
-1 0 0 1 62.69291 538.6772 cm
+1 0 0 1 62.69291 460.6772 cm
 q
-BT 1 0 0 1 0 16.82 Tm .578651 Tw 12 TL /F1 10 Tf 0 0 0 rg (Internally ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (uses an ) Tj /F4 10 Tf (Annotation ) Tj /F1 10 Tf (class to convert the tuples in the function signature into annotation) Tj T* 0 Tw (objects, i.e. objects with six attributes ) Tj /F4 10 Tf (help, kind, short, type, choices, metavar) Tj /F1 10 Tf (.) Tj T* ET
+BT 1 0 0 1 0 16.82 Tm .578651 Tw 12 TL /F1 10 Tf 0 0 0 rg (Internally ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (uses an ) Tj /F3 10 Tf (Annotation ) Tj /F1 10 Tf (class to convert the tuples in the function signature into annotation) Tj T* 0 Tw (objects, i.e. objects with six attributes ) Tj /F3 10 Tf (help, kind, short, type, choices, metavar) Tj /F1 10 Tf (.) Tj T* ET
 Q
 Q
 q
-1 0 0 1 62.69291 508.6772 cm
+1 0 0 1 62.69291 430.6772 cm
 q
 0 0 0 rg
 BT 1 0 0 1 0 16.82 Tm /F1 10 Tf 12 TL .083735 Tw (Advanced users can implement their own annotation objects. For instance, here is an example of how you) Tj T* 0 Tw (could implement annotations for positional arguments:) Tj T* ET
 Q
 Q
 q
-1 0 0 1 62.69291 379.4772 cm
+1 0 0 1 62.69291 301.4772 cm
 q
 q
 1 0 0 1 0 0 cm
@@ -14189,21 +14179,21 @@ n -6 -6 468.6898 120 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 101.71 Tm /F4 10 Tf 12 TL (# annotations.py) Tj T* (class Positional\(object\):) Tj T* (    def __init__\(self, help='', type=None, choices=None, metavar=None\):) Tj T* (        self.help = help) Tj T* (        self.kind = 'positional') Tj T* (        self.abbrev = None) Tj T* (        self.type = type) Tj T* (        self.choices = choices) Tj T* (        self.metavar = metavar) Tj T* ET
+BT 1 0 0 1 0 101.71 Tm /F3 10 Tf 12 TL (# annotations.py) Tj T* (class Positional\(object\):) Tj T* (    def __init__\(self, help='', type=None, choices=None, metavar=None\):) Tj T* (        self.help = help) Tj T* (        self.kind = 'positional') Tj T* (        self.abbrev = None) Tj T* (        self.type = type) Tj T* (        self.choices = choices) Tj T* (        self.metavar = metavar) Tj T* ET
 Q
 Q
 Q
 Q
 Q
 q
-1 0 0 1 62.69291 359.4772 cm
+1 0 0 1 62.69291 281.4772 cm
 q
 0 0 0 rg
 BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL (You can use such annotations objects as follows:) Tj T* ET
 Q
 Q
 q
-1 0 0 1 62.69291 182.2772 cm
+1 0 0 1 62.69291 104.2772 cm
 q
 q
 1 0 0 1 0 0 cm
@@ -14217,35 +14207,7 @@ n -6 -6 468.6898 168 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 149.71 Tm /F4 10 Tf 12 TL (# example11.py) Tj T* (import plac) Tj T* (from annotations import Positional) Tj T*  T* (@plac.annotations\() Tj T* (    i=Positional\("This is an int", int\),) Tj T* (    n=Positional\("This is a float", float\),) Tj T* (    rest=Positional\("Other arguments"\)\)) Tj T* (def main\(i, n, *rest\):) Tj T* (    print\(i, n, rest\)) Tj T*  T* (if __name__ == '__main__':) Tj T* (    import plac; plac.call\(main\)) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 162.2772 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL (Here is the usage message you get:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 93.07717 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 60 re B*
-Q
-q
-0 0 0 rg
-BT 1 0 0 1 0 41.71 Tm /F4 10 Tf 12 TL (usage: example11.py [-h] i n [rest [rest ...]]) Tj T*  T* (positional arguments:) Tj T* (  i           This is an int) Tj T* ET
+BT 1 0 0 1 0 149.71 Tm /F3 10 Tf 12 TL (# example11.py) Tj T* (import plac) Tj T* (from annotations import Positional) Tj T*  T* (@plac.annotations\() Tj T* (    i=Positional\("This is an int", int\),) Tj T* (    n=Positional\("This is a float", float\),) Tj T* (    rest=Positional\("Other arguments"\)\)) Tj T* (def main\(i, n, *rest\):) Tj T* (    print\(i, n, rest\)) Tj T*  T* (if __name__ == '__main__':) Tj T* (    import plac; plac.call\(main\)) Tj T* ET
 Q
 Q
 Q
@@ -14265,11 +14227,18 @@ endobj
 % 'R456': class PDFStream 
 456 0 obj
 % page stream
-<< /Length 1103 >>
+<< /Length 1367 >>
 stream
 1 0 0 1 0 0 cm BT /F1 12 Tf 14.4 TL ET
 q
-1 0 0 1 62.69291 691.8236 cm
+1 0 0 1 62.69291 753.0236 cm
+q
+0 0 0 rg
+BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL (Here is the usage message you get:) Tj T* ET
+Q
+Q
+q
+1 0 0 1 62.69291 623.8236 cm
 q
 q
 1 0 0 1 0 0 cm
@@ -14279,20 +14248,20 @@ q
 .662745 .662745 .662745 RG
 .5 w
 .960784 .960784 .862745 rg
-n -6 -6 468.6898 72 re B*
+n -6 -6 468.6898 120 re B*
 Q
 q
 0 0 0 rg
-BT 1 0 0 1 0 53.71 Tm /F4 10 Tf 12 TL (  n           This is a float) Tj T* (  rest        Other arguments) Tj T*  T* (optional arguments:) Tj T* (  -h, --help  show this help message and exit) Tj T* ET
+BT 1 0 0 1 0 101.71 Tm /F3 10 Tf 12 TL (usage: example11.py [-h] i n [rest [rest ...]]) Tj T*  T* (positional arguments:) Tj T* (  i           This is an int) Tj T* (  n           This is a float) Tj T* (  rest        Other arguments) Tj T*  T* (optional arguments:) Tj T* (  -h, --help  show this help message and exit) Tj T* ET
 Q
 Q
 Q
 Q
 Q
 q
-1 0 0 1 62.69291 647.8236 cm
+1 0 0 1 62.69291 579.8236 cm
 q
-BT 1 0 0 1 0 28.82 Tm .713516 Tw 12 TL /F1 10 Tf 0 0 0 rg (You can go on and define ) Tj /F4 10 Tf (Option ) Tj /F1 10 Tf (and ) Tj /F4 10 Tf (Flag ) Tj /F1 10 Tf (classes, if you like. Using custom annotation objects you) Tj T* 0 Tw .17528 Tw (could do advanced things like extracting the annotations from a configuration file or from a database, but I) Tj T* 0 Tw (expect such use cases to be quite rare: the default mechanism should work pretty well for most users.) Tj T* ET
+BT 1 0 0 1 0 28.82 Tm .713516 Tw 12 TL /F1 10 Tf 0 0 0 rg (You can go on and define ) Tj /F3 10 Tf (Option ) Tj /F1 10 Tf (and ) Tj /F3 10 Tf (Flag ) Tj /F1 10 Tf (classes, if you like. Using custom annotation objects you) Tj T* 0 Tw .17528 Tw (could do advanced things like extracting the annotations from a configuration file or from a database, but I) Tj T* 0 Tw (expect such use cases to be quite rare: the default mechanism should work pretty well for most users.) Tj T* ET
 Q
 Q
 q
@@ -14674,515 +14643,515 @@ xref
 0 503
 0000000000 65535 f
 0000000113 00000 n
-0000000258 00000 n
-0000000423 00000 n
+0000000246 00000 n
+0000000411 00000 n
 0000000598 00000 n
-0000000779 00000 n
-0000001031 00000 n
-0000001281 00000 n
-0000001539 00000 n
-0000001698 00000 n
-0000002030 00000 n
-0000002271 00000 n
-0000002512 00000 n
-0000002754 00000 n
-0000002996 00000 n
-0000003238 00000 n
-0000003481 00000 n
-0000003725 00000 n
-0000003969 00000 n
-0000004213 00000 n
-0000004457 00000 n
-0000004701 00000 n
-0000004945 00000 n
-0000005189 00000 n
-0000005433 00000 n
-0000005677 00000 n
-0000005921 00000 n
-0000006165 00000 n
-0000006409 00000 n
-0000006653 00000 n
-0000006897 00000 n
-0000007141 00000 n
-0000007385 00000 n
-0000007629 00000 n
-0000007873 00000 n
-0000008117 00000 n
-0000008361 00000 n
-0000008605 00000 n
-0000008849 00000 n
-0000009093 00000 n
-0000009337 00000 n
-0000009581 00000 n
-0000009825 00000 n
-0000010069 00000 n
-0000010313 00000 n
-0000010557 00000 n
-0000010801 00000 n
-0000011045 00000 n
-0000011289 00000 n
-0000011533 00000 n
-0000011777 00000 n
-0000012021 00000 n
-0000012265 00000 n
-0000012509 00000 n
-0000012753 00000 n
-0000012997 00000 n
-0000013241 00000 n
-0000013485 00000 n
-0000013729 00000 n
-0000013973 00000 n
-0000014217 00000 n
-0000014461 00000 n
-0000014705 00000 n
-0000014949 00000 n
-0000015193 00000 n
-0000015437 00000 n
-0000015681 00000 n
-0000015925 00000 n
-0000016169 00000 n
-0000016413 00000 n
-0000016657 00000 n
-0000016901 00000 n
-0000017145 00000 n
-0000017389 00000 n
-0000017633 00000 n
-0000017877 00000 n
-0000018121 00000 n
-0000018365 00000 n
-0000018609 00000 n
-0000018853 00000 n
-0000019081 00000 n
-0000020020 00000 n
-0000020282 00000 n
-0000020545 00000 n
-0000020795 00000 n
-0000021044 00000 n
-0000021310 00000 n
-0000021562 00000 n
-0000021812 00000 n
-0000022064 00000 n
-0000022314 00000 n
-0000022566 00000 n
-0000022816 00000 n
-0000023068 00000 n
-0000023319 00000 n
-0000023558 00000 n
-0000023738 00000 n
-0000024173 00000 n
-0000024434 00000 n
-0000024698 00000 n
-0000024947 00000 n
-0000025200 00000 n
-0000025453 00000 n
-0000025705 00000 n
-0000025956 00000 n
-0000026209 00000 n
-0000026447 00000 n
-0000026844 00000 n
-0000027094 00000 n
-0000027347 00000 n
-0000027585 00000 n
-0000027926 00000 n
-0000028180 00000 n
-0000028434 00000 n
-0000028706 00000 n
-0000029047 00000 n
-0000029301 00000 n
-0000029591 00000 n
-0000029881 00000 n
-0000030135 00000 n
-0000030373 00000 n
-0000030718 00000 n
-0000031017 00000 n
-0000031271 00000 n
-0000031509 00000 n
-0000031840 00000 n
-0000032094 00000 n
-0000032348 00000 n
-0000032600 00000 n
-0000032852 00000 n
-0000033104 00000 n
-0000033358 00000 n
-0000033595 00000 n
-0000033961 00000 n
-0000034260 00000 n
-0000034514 00000 n
-0000034762 00000 n
-0000035026 00000 n
-0000035367 00000 n
-0000035621 00000 n
-0000035859 00000 n
-0000036190 00000 n
-0000036429 00000 n
-0000036750 00000 n
-0000037002 00000 n
-0000037241 00000 n
-0000037572 00000 n
-0000037825 00000 n
-0000038077 00000 n
-0000038329 00000 n
-0000038581 00000 n
-0000038835 00000 n
-0000039087 00000 n
-0000039339 00000 n
-0000039593 00000 n
-0000039847 00000 n
-0000040099 00000 n
-0000040353 00000 n
-0000040605 00000 n
-0000040843 00000 n
-0000041284 00000 n
-0000041538 00000 n
-0000041817 00000 n
-0000042071 00000 n
-0000042325 00000 n
-0000042603 00000 n
-0000042882 00000 n
-0000043136 00000 n
-0000043388 00000 n
-0000043706 00000 n
-0000043960 00000 n
-0000044249 00000 n
-0000044501 00000 n
-0000044753 00000 n
-0000044992 00000 n
-0000045443 00000 n
-0000045697 00000 n
-0000045951 00000 n
-0000046210 00000 n
-0000046467 00000 n
-0000046719 00000 n
-0000046973 00000 n
-0000047231 00000 n
-0000047483 00000 n
-0000047741 00000 n
-0000047995 00000 n
-0000048248 00000 n
-0000048509 00000 n
-0000048763 00000 n
-0000049017 00000 n
-0000049271 00000 n
-0000049525 00000 n
-0000049777 00000 n
-0000050029 00000 n
-0000050282 00000 n
-0000050536 00000 n
-0000050790 00000 n
-0000051044 00000 n
-0000051298 00000 n
-0000051577 00000 n
-0000051830 00000 n
-0000052120 00000 n
-0000052374 00000 n
-0000052685 00000 n
-0000052937 00000 n
-0000053189 00000 n
-0000053478 00000 n
-0000053730 00000 n
-0000053967 00000 n
-0000054608 00000 n
-0000054866 00000 n
-0000055120 00000 n
-0000055376 00000 n
-0000055630 00000 n
-0000055889 00000 n
-0000056251 00000 n
-0000056495 00000 n
-0000056739 00000 n
-0000056984 00000 n
-0000057229 00000 n
-0000057474 00000 n
-0000057719 00000 n
-0000057965 00000 n
-0000058211 00000 n
-0000058457 00000 n
-0000058703 00000 n
-0000058949 00000 n
-0000059195 00000 n
-0000059441 00000 n
-0000059687 00000 n
-0000059933 00000 n
-0000060179 00000 n
-0000060425 00000 n
-0000060671 00000 n
-0000060917 00000 n
-0000061163 00000 n
-0000061409 00000 n
-0000061655 00000 n
-0000061901 00000 n
-0000062147 00000 n
-0000062393 00000 n
-0000062639 00000 n
-0000062885 00000 n
-0000063131 00000 n
-0000063377 00000 n
-0000063623 00000 n
-0000063869 00000 n
-0000064115 00000 n
-0000064361 00000 n
-0000064607 00000 n
-0000064853 00000 n
-0000065099 00000 n
-0000065345 00000 n
-0000065591 00000 n
-0000065837 00000 n
-0000066083 00000 n
-0000066329 00000 n
-0000066575 00000 n
-0000066821 00000 n
-0000067067 00000 n
-0000067313 00000 n
-0000067559 00000 n
-0000067805 00000 n
-0000068051 00000 n
-0000068297 00000 n
-0000068543 00000 n
-0000068789 00000 n
-0000069035 00000 n
-0000069281 00000 n
-0000069527 00000 n
-0000069773 00000 n
-0000070019 00000 n
-0000070265 00000 n
-0000070511 00000 n
-0000070757 00000 n
-0000071003 00000 n
-0000071249 00000 n
-0000071495 00000 n
-0000071741 00000 n
-0000071987 00000 n
-0000072233 00000 n
-0000072479 00000 n
-0000072725 00000 n
-0000072971 00000 n
-0000073217 00000 n
-0000073447 00000 n
-0000074458 00000 n
-0000074712 00000 n
-0000074966 00000 n
-0000075220 00000 n
-0000075474 00000 n
-0000075728 00000 n
-0000075973 00000 n
-0000076227 00000 n
-0000076481 00000 n
-0000076735 00000 n
-0000076989 00000 n
-0000077248 00000 n
-0000077669 00000 n
-0000077908 00000 n
-0000078214 00000 n
-0000078513 00000 n
-0000078767 00000 n
-0000079021 00000 n
-0000079275 00000 n
-0000079537 00000 n
-0000079791 00000 n
-0000080054 00000 n
-0000080307 00000 n
-0000080555 00000 n
-0000080946 00000 n
-0000081200 00000 n
-0000081454 00000 n
-0000081707 00000 n
-0000081945 00000 n
-0000082296 00000 n
-0000082570 00000 n
-0000082824 00000 n
-0000083078 00000 n
-0000083317 00000 n
-0000083668 00000 n
-0000083922 00000 n
-0000084176 00000 n
-0000084422 00000 n
-0000084748 00000 n
-0000085032 00000 n
-0000085331 00000 n
-0000085585 00000 n
-0000085843 00000 n
-0000086097 00000 n
-0000086365 00000 n
-0000086619 00000 n
-0000086858 00000 n
-0000087229 00000 n
-0000087490 00000 n
-0000087751 00000 n
-0000088003 00000 n
-0000088256 00000 n
-0000088508 00000 n
-0000088762 00000 n
-0000089016 00000 n
-0000089270 00000 n
-0000089524 00000 n
-0000089764 00000 n
-0000090175 00000 n
-0000090412 00000 n
-0000090733 00000 n
-0000090972 00000 n
-0000091278 00000 n
-0000091577 00000 n
-0000091815 00000 n
-0000092136 00000 n
-0000092390 00000 n
-0000092663 00000 n
-0000092902 00000 n
-0000093243 00000 n
-0000093497 00000 n
-0000093736 00000 n
-0000094052 00000 n
-0000094351 00000 n
-0000094605 00000 n
-0000094863 00000 n
-0000095194 00000 n
-0000095433 00000 n
-0000095754 00000 n
-0000095993 00000 n
-0000096299 00000 n
-0000096598 00000 n
-0000096852 00000 n
-0000097091 00000 n
-0000097422 00000 n
-0000097661 00000 n
-0000097967 00000 n
-0000098252 00000 n
-0000098416 00000 n
-0000098630 00000 n
-0000098759 00000 n
-0000099013 00000 n
-0000099210 00000 n
-0000099424 00000 n
-0000099638 00000 n
-0000099864 00000 n
-0000100066 00000 n
-0000100275 00000 n
-0000100472 00000 n
-0000100675 00000 n
-0000100876 00000 n
-0000101094 00000 n
-0000101295 00000 n
-0000101509 00000 n
-0000101704 00000 n
-0000101902 00000 n
-0000102138 00000 n
-0000102318 00000 n
-0000102542 00000 n
-0000102752 00000 n
-0000102951 00000 n
-0000103153 00000 n
-0000103361 00000 n
-0000103566 00000 n
-0000103766 00000 n
-0000103965 00000 n
-0000104175 00000 n
-0000104388 00000 n
-0000104594 00000 n
-0000104796 00000 n
-0000105019 00000 n
-0000105246 00000 n
-0000105459 00000 n
-0000105659 00000 n
-0000105851 00000 n
-0000106036 00000 n
-0000106584 00000 n
-0000109681 00000 n
-0000119378 00000 n
-0000125466 00000 n
-0000130017 00000 n
-0000134170 00000 n
-0000138174 00000 n
-0000143296 00000 n
-0000147717 00000 n
-0000152736 00000 n
-0000158684 00000 n
-0000162939 00000 n
-0000167340 00000 n
-0000171005 00000 n
-0000175405 00000 n
-0000182103 00000 n
-0000188470 00000 n
-0000196135 00000 n
-0000204440 00000 n
-0000208856 00000 n
-0000218554 00000 n
-0000224071 00000 n
-0000228242 00000 n
-0000234153 00000 n
-0000240252 00000 n
-0000245932 00000 n
-0000250331 00000 n
-0000254759 00000 n
-0000259619 00000 n
-0000264256 00000 n
-0000269533 00000 n
-0000274287 00000 n
-0000278955 00000 n
-0000284039 00000 n
-0000288033 00000 n
-0000293790 00000 n
-0000298776 00000 n
-0000303504 00000 n
-0000308728 00000 n
-0000313591 00000 n
-0000317446 00000 n
-0000322216 00000 n
-0000325678 00000 n
-0000331352 00000 n
-0000336849 00000 n
-0000338059 00000 n
-0000338806 00000 n
-0000338885 00000 n
-0000338964 00000 n
-0000339043 00000 n
-0000339122 00000 n
-0000339201 00000 n
-0000339280 00000 n
-0000339359 00000 n
-0000339438 00000 n
-0000339517 00000 n
-0000339597 00000 n
-0000339677 00000 n
-0000339757 00000 n
-0000339837 00000 n
-0000339917 00000 n
-0000339997 00000 n
-0000340077 00000 n
-0000340157 00000 n
-0000340237 00000 n
-0000340317 00000 n
-0000340397 00000 n
-0000340477 00000 n
-0000340557 00000 n
-0000340637 00000 n
-0000340717 00000 n
-0000340797 00000 n
-0000340877 00000 n
-0000340957 00000 n
-0000341037 00000 n
-0000341117 00000 n
-0000341197 00000 n
-0000341277 00000 n
-0000341357 00000 n
-0000341437 00000 n
-0000341517 00000 n
-0000341597 00000 n
-0000341677 00000 n
-0000341757 00000 n
-0000341837 00000 n
-0000341917 00000 n
-0000341997 00000 n
-0000342077 00000 n
-0000342157 00000 n
-0000342237 00000 n
-0000342317 00000 n
+0000000850 00000 n
+0000001100 00000 n
+0000001358 00000 n
+0000001517 00000 n
+0000001849 00000 n
+0000002089 00000 n
+0000002330 00000 n
+0000002572 00000 n
+0000002814 00000 n
+0000003056 00000 n
+0000003299 00000 n
+0000003543 00000 n
+0000003787 00000 n
+0000004031 00000 n
+0000004275 00000 n
+0000004519 00000 n
+0000004763 00000 n
+0000005007 00000 n
+0000005251 00000 n
+0000005495 00000 n
+0000005739 00000 n
+0000005983 00000 n
+0000006227 00000 n
+0000006471 00000 n
+0000006715 00000 n
+0000006959 00000 n
+0000007203 00000 n
+0000007447 00000 n
+0000007691 00000 n
+0000007935 00000 n
+0000008179 00000 n
+0000008423 00000 n
+0000008667 00000 n
+0000008911 00000 n
+0000009155 00000 n
+0000009399 00000 n
+0000009643 00000 n
+0000009887 00000 n
+0000010131 00000 n
+0000010375 00000 n
+0000010619 00000 n
+0000010863 00000 n
+0000011107 00000 n
+0000011351 00000 n
+0000011595 00000 n
+0000011839 00000 n
+0000012083 00000 n
+0000012327 00000 n
+0000012571 00000 n
+0000012815 00000 n
+0000013059 00000 n
+0000013303 00000 n
+0000013547 00000 n
+0000013791 00000 n
+0000014035 00000 n
+0000014279 00000 n
+0000014523 00000 n
+0000014767 00000 n
+0000015011 00000 n
+0000015255 00000 n
+0000015499 00000 n
+0000015743 00000 n
+0000015987 00000 n
+0000016231 00000 n
+0000016475 00000 n
+0000016719 00000 n
+0000016963 00000 n
+0000017207 00000 n
+0000017451 00000 n
+0000017695 00000 n
+0000017939 00000 n
+0000018183 00000 n
+0000018427 00000 n
+0000018671 00000 n
+0000018899 00000 n
+0000019837 00000 n
+0000020099 00000 n
+0000020362 00000 n
+0000020612 00000 n
+0000020861 00000 n
+0000021127 00000 n
+0000021379 00000 n
+0000021629 00000 n
+0000021881 00000 n
+0000022131 00000 n
+0000022383 00000 n
+0000022633 00000 n
+0000022885 00000 n
+0000023136 00000 n
+0000023375 00000 n
+0000023555 00000 n
+0000023990 00000 n
+0000024251 00000 n
+0000024515 00000 n
+0000024764 00000 n
+0000025016 00000 n
+0000025269 00000 n
+0000025521 00000 n
+0000025772 00000 n
+0000026025 00000 n
+0000026263 00000 n
+0000026659 00000 n
+0000026909 00000 n
+0000027162 00000 n
+0000027400 00000 n
+0000027741 00000 n
+0000027995 00000 n
+0000028249 00000 n
+0000028521 00000 n
+0000028862 00000 n
+0000029116 00000 n
+0000029406 00000 n
+0000029696 00000 n
+0000029950 00000 n
+0000030188 00000 n
+0000030533 00000 n
+0000030832 00000 n
+0000031086 00000 n
+0000031324 00000 n
+0000031655 00000 n
+0000031909 00000 n
+0000032163 00000 n
+0000032415 00000 n
+0000032667 00000 n
+0000032919 00000 n
+0000033173 00000 n
+0000033410 00000 n
+0000033776 00000 n
+0000034075 00000 n
+0000034329 00000 n
+0000034577 00000 n
+0000034841 00000 n
+0000035182 00000 n
+0000035436 00000 n
+0000035674 00000 n
+0000036005 00000 n
+0000036244 00000 n
+0000036565 00000 n
+0000036817 00000 n
+0000037056 00000 n
+0000037387 00000 n
+0000037640 00000 n
+0000037892 00000 n
+0000038144 00000 n
+0000038396 00000 n
+0000038650 00000 n
+0000038902 00000 n
+0000039154 00000 n
+0000039408 00000 n
+0000039662 00000 n
+0000039914 00000 n
+0000040168 00000 n
+0000040420 00000 n
+0000040658 00000 n
+0000041099 00000 n
+0000041353 00000 n
+0000041636 00000 n
+0000041890 00000 n
+0000042144 00000 n
+0000042426 00000 n
+0000042709 00000 n
+0000042963 00000 n
+0000043215 00000 n
+0000043533 00000 n
+0000043787 00000 n
+0000044076 00000 n
+0000044328 00000 n
+0000044580 00000 n
+0000044819 00000 n
+0000045270 00000 n
+0000045524 00000 n
+0000045778 00000 n
+0000046037 00000 n
+0000046294 00000 n
+0000046546 00000 n
+0000046800 00000 n
+0000047058 00000 n
+0000047310 00000 n
+0000047568 00000 n
+0000047822 00000 n
+0000048075 00000 n
+0000048336 00000 n
+0000048590 00000 n
+0000048844 00000 n
+0000049098 00000 n
+0000049352 00000 n
+0000049604 00000 n
+0000049856 00000 n
+0000050109 00000 n
+0000050363 00000 n
+0000050617 00000 n
+0000050871 00000 n
+0000051125 00000 n
+0000051408 00000 n
+0000051661 00000 n
+0000051951 00000 n
+0000052205 00000 n
+0000052516 00000 n
+0000052768 00000 n
+0000053020 00000 n
+0000053309 00000 n
+0000053561 00000 n
+0000053798 00000 n
+0000054439 00000 n
+0000054697 00000 n
+0000054951 00000 n
+0000055207 00000 n
+0000055461 00000 n
+0000055720 00000 n
+0000056082 00000 n
+0000056326 00000 n
+0000056570 00000 n
+0000056815 00000 n
+0000057060 00000 n
+0000057305 00000 n
+0000057550 00000 n
+0000057796 00000 n
+0000058042 00000 n
+0000058288 00000 n
+0000058534 00000 n
+0000058780 00000 n
+0000059026 00000 n
+0000059272 00000 n
+0000059518 00000 n
+0000059764 00000 n
+0000060010 00000 n
+0000060256 00000 n
+0000060502 00000 n
+0000060748 00000 n
+0000060994 00000 n
+0000061240 00000 n
+0000061486 00000 n
+0000061732 00000 n
+0000061978 00000 n
+0000062224 00000 n
+0000062470 00000 n
+0000062716 00000 n
+0000062962 00000 n
+0000063208 00000 n
+0000063454 00000 n
+0000063700 00000 n
+0000063946 00000 n
+0000064192 00000 n
+0000064438 00000 n
+0000064684 00000 n
+0000064930 00000 n
+0000065176 00000 n
+0000065422 00000 n
+0000065668 00000 n
+0000065914 00000 n
+0000066160 00000 n
+0000066406 00000 n
+0000066652 00000 n
+0000066898 00000 n
+0000067144 00000 n
+0000067390 00000 n
+0000067636 00000 n
+0000067882 00000 n
+0000068128 00000 n
+0000068374 00000 n
+0000068620 00000 n
+0000068866 00000 n
+0000069112 00000 n
+0000069358 00000 n
+0000069604 00000 n
+0000069850 00000 n
+0000070096 00000 n
+0000070342 00000 n
+0000070588 00000 n
+0000070834 00000 n
+0000071080 00000 n
+0000071326 00000 n
+0000071572 00000 n
+0000071818 00000 n
+0000072064 00000 n
+0000072310 00000 n
+0000072556 00000 n
+0000072802 00000 n
+0000073048 00000 n
+0000073278 00000 n
+0000074289 00000 n
+0000074543 00000 n
+0000074797 00000 n
+0000075051 00000 n
+0000075305 00000 n
+0000075559 00000 n
+0000075804 00000 n
+0000076058 00000 n
+0000076312 00000 n
+0000076566 00000 n
+0000076820 00000 n
+0000077079 00000 n
+0000077500 00000 n
+0000077739 00000 n
+0000078045 00000 n
+0000078344 00000 n
+0000078598 00000 n
+0000078852 00000 n
+0000079106 00000 n
+0000079368 00000 n
+0000079622 00000 n
+0000079885 00000 n
+0000080138 00000 n
+0000080386 00000 n
+0000080777 00000 n
+0000081031 00000 n
+0000081285 00000 n
+0000081538 00000 n
+0000081776 00000 n
+0000082127 00000 n
+0000082401 00000 n
+0000082655 00000 n
+0000082909 00000 n
+0000083148 00000 n
+0000083499 00000 n
+0000083753 00000 n
+0000084007 00000 n
+0000084253 00000 n
+0000084579 00000 n
+0000084863 00000 n
+0000085162 00000 n
+0000085416 00000 n
+0000085674 00000 n
+0000085928 00000 n
+0000086196 00000 n
+0000086450 00000 n
+0000086689 00000 n
+0000087060 00000 n
+0000087321 00000 n
+0000087582 00000 n
+0000087834 00000 n
+0000088087 00000 n
+0000088339 00000 n
+0000088593 00000 n
+0000088847 00000 n
+0000089101 00000 n
+0000089355 00000 n
+0000089595 00000 n
+0000090006 00000 n
+0000090243 00000 n
+0000090564 00000 n
+0000090803 00000 n
+0000091109 00000 n
+0000091408 00000 n
+0000091646 00000 n
+0000091967 00000 n
+0000092221 00000 n
+0000092494 00000 n
+0000092733 00000 n
+0000093074 00000 n
+0000093328 00000 n
+0000093567 00000 n
+0000093883 00000 n
+0000094182 00000 n
+0000094436 00000 n
+0000094694 00000 n
+0000095025 00000 n
+0000095264 00000 n
+0000095585 00000 n
+0000095824 00000 n
+0000096130 00000 n
+0000096429 00000 n
+0000096683 00000 n
+0000096937 00000 n
+0000097176 00000 n
+0000097517 00000 n
+0000097756 00000 n
+0000098062 00000 n
+0000098347 00000 n
+0000098511 00000 n
+0000098725 00000 n
+0000098854 00000 n
+0000099108 00000 n
+0000099305 00000 n
+0000099519 00000 n
+0000099733 00000 n
+0000099959 00000 n
+0000100161 00000 n
+0000100370 00000 n
+0000100567 00000 n
+0000100770 00000 n
+0000100971 00000 n
+0000101189 00000 n
+0000101390 00000 n
+0000101604 00000 n
+0000101799 00000 n
+0000101997 00000 n
+0000102233 00000 n
+0000102413 00000 n
+0000102637 00000 n
+0000102847 00000 n
+0000103046 00000 n
+0000103248 00000 n
+0000103456 00000 n
+0000103661 00000 n
+0000103861 00000 n
+0000104060 00000 n
+0000104270 00000 n
+0000104483 00000 n
+0000104689 00000 n
+0000104891 00000 n
+0000105114 00000 n
+0000105341 00000 n
+0000105554 00000 n
+0000105754 00000 n
+0000105946 00000 n
+0000106131 00000 n
+0000106679 00000 n
+0000109776 00000 n
+0000119473 00000 n
+0000125561 00000 n
+0000130112 00000 n
+0000134265 00000 n
+0000138269 00000 n
+0000143391 00000 n
+0000147812 00000 n
+0000152831 00000 n
+0000159106 00000 n
+0000163464 00000 n
+0000167865 00000 n
+0000171530 00000 n
+0000175930 00000 n
+0000182628 00000 n
+0000188995 00000 n
+0000196660 00000 n
+0000204965 00000 n
+0000209381 00000 n
+0000219079 00000 n
+0000224596 00000 n
+0000228767 00000 n
+0000234678 00000 n
+0000240777 00000 n
+0000246457 00000 n
+0000250856 00000 n
+0000255284 00000 n
+0000260144 00000 n
+0000264390 00000 n
+0000269667 00000 n
+0000274421 00000 n
+0000279089 00000 n
+0000284173 00000 n
+0000288167 00000 n
+0000293924 00000 n
+0000298910 00000 n
+0000303638 00000 n
+0000308862 00000 n
+0000313725 00000 n
+0000317580 00000 n
+0000322350 00000 n
+0000325812 00000 n
+0000330922 00000 n
+0000337645 00000 n
+0000339119 00000 n
+0000339866 00000 n
+0000339945 00000 n
+0000340024 00000 n
+0000340103 00000 n
+0000340182 00000 n
+0000340261 00000 n
+0000340340 00000 n
+0000340419 00000 n
+0000340498 00000 n
+0000340577 00000 n
+0000340657 00000 n
+0000340737 00000 n
+0000340817 00000 n
+0000340897 00000 n
+0000340977 00000 n
+0000341057 00000 n
+0000341137 00000 n
+0000341217 00000 n
+0000341297 00000 n
+0000341377 00000 n
+0000341457 00000 n
+0000341537 00000 n
+0000341617 00000 n
+0000341697 00000 n
+0000341777 00000 n
+0000341857 00000 n
+0000341937 00000 n
+0000342017 00000 n
+0000342097 00000 n
+0000342177 00000 n
+0000342257 00000 n
+0000342337 00000 n
+0000342417 00000 n
+0000342497 00000 n
+0000342577 00000 n
+0000342657 00000 n
+0000342737 00000 n
+0000342817 00000 n
+0000342897 00000 n
+0000342977 00000 n
+0000343057 00000 n
+0000343137 00000 n
+0000343217 00000 n
+0000343297 00000 n
+0000343377 00000 n
 trailer
 << /ID 
  % ReportLab generated PDF document -- digest (http://www.reportlab.com) 
- [(A\305\006\345,=\244\353v\354H\363\3127\016\356) (A\305\006\345,=\244\353v\354H\363\3127\016\356)] 
+ [(2\('\264\241\002;.\314\364\027\211\243\375\026\035) (2\('\264\241\002;.\314\364\027\211\243\375\026\035)] 
 
  /Info 374 0 R
  /Root 373 0 R
  /Size 503 >>
 startxref
-342366
+343426
 %%EOF
diff --git a/plac/doc/plac_adv.html b/plac/doc/plac_adv.html
deleted file mode 100644
index d2716fa..0000000
--- a/plac/doc/plac_adv.html
+++ /dev/null
@@ -1,1934 +0,0 @@
-<?xml version="1.0" encoding="utf-8" ?>
-<!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" xml:lang="en" lang="en">
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
-<title>Advanced usages of plac</title>
-<meta name="author" content="Michele Simionato" />
-<meta name="date" content="August 2010" />
-<style type="text/css">
-
-.first {
-  margin-top: 0 }
-
-.last {
-  margin-bottom: 0 }
-
-a.toc-backref {
-  text-decoration: none ;
-  color: black }
-
-dd {
-  margin-bottom: 0.5em }
-
-div.abstract {
-  margin: 2em 5em }
-
-div.abstract p.topic-title {
-  font-weight: bold ;
-  text-align: center }
-
-div.attention, div.caution, div.danger, div.error, div.hint,
-div.important, div.note, div.tip, div.warning {
-  margin: 2em ;
-  border: medium outset ;
-  padding: 1em }
-
-div.attention p.admonition-title, div.caution p.admonition-title,
-div.danger p.admonition-title, div.error p.admonition-title,
-div.warning p.admonition-title {
-  color: red ;
-  font-weight: bold ;
-  font-family: sans-serif }
-
-div.hint p.admonition-title, div.important p.admonition-title,
-div.note p.admonition-title, div.tip p.admonition-title {
-  font-weight: bold ;
-  font-family: sans-serif }
-
-div.dedication {
-  margin: 2em 5em ;
-  text-align: center ;
-  font-style: italic }
-
-div.dedication p.topic-title {
-  font-weight: bold ;
-  font-style: normal }
-
-div.figure {
-  margin-left: 2em }
-
-div.footer, div.header {
-  font-size: smaller }
-
-div.system-messages {
-  margin: 5em }
-
-div.system-messages h1 {
-  color: red }
-
-div.system-message {
-  border: medium outset ;
-  padding: 1em }
-
-div.system-message p.system-message-title {
-  color: red ;
-  font-weight: bold }
-
-div.topic {
-  margin: 2em }
-
-hr {
-  width: 75% }
-
-ol.simple, ul.simple {
-  margin-bottom: 1em }
-
-ol.arabic {
-  list-style: decimal }
-
-ol.loweralpha {
-  list-style: lower-alpha }
-
-ol.upperalpha {
-  list-style: upper-alpha }
-
-ol.lowerroman {
-  list-style: lower-roman }
-
-ol.upperroman {
-  list-style: upper-roman }
-
-p.caption {
-  font-style: italic }
-
-p.credits {
-  font-style: italic ;
-  font-size: smaller }
-
-p.label {
-  white-space: nowrap }
-
-p.topic-title {
-  font-weight: bold }
-
-pre.address {
-  margin-bottom: 0 ;
-  margin-top: 0 ;
-  font-family: serif ;
-  font-size: 100% }
-
-pre.line-block {
-  font-family: serif ;
-  font-size: 100% }
-
-pre.literal-block, pre.doctest-block {
-  background-color: #eeeeee }
-
-span.classifier {
-  font-family: sans-serif ;
-  font-style: oblique }
-
-span.classifier-delimiter {
-  font-family: sans-serif ;
-  font-weight: bold }
-
-span.interpreted {
-  font-family: sans-serif }
-
-span.option-argument {
-  font-style: italic }
-
-span.pre {
-  white-space: pre }
-
-span.problematic {
-  color: red }
-
-table {
-  margin-top: 0.5em ;
-  margin-bottom: 0.5em }
-
-table.citation {
-  border-left: solid thin gray ;
-  padding-left: 0.5ex }
-
-table.docinfo {
-  margin: 2em 4em }
-
-table.footnote {
-  border-left: solid thin black ;
-  padding-left: 0.5ex }
-
-td, th {
-  padding-left: 0.5em ;
-  padding-right: 0.5em ;
-  vertical-align: top }
-
-th.docinfo-name, th.field-name {
-  font-weight: bold ;
-  text-align: left ;
-  white-space: nowrap }
-
-h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
-  font-size: 100% }
-
-tt {
-  background-color: #eeeeee }
-
-ul.auto-toc {
-  list-style-type: none }
-
-
-/*
-Additional styles for "modern"-style of DocFactory.
-
-:Author: Gunnar Schwant
-:Contact: g.schwant@gmx.de
-*/
-
-.first {
-  font-size: 10pt }
-
-.last {
-  font-size: 10pt }
-
-a {
-  text-decoration: none }
-
-a.reference {
-  color: #00009F }
-
-a:hover {
-  background-color: #00009F ;
-  color: white }
-
-body {
-  font-family: arial,helvetica,univers ;
-  font-size: 10pt ;
-  padding-top: 0.6cm ;
-  margin-left:0.5cm ;
-  margin-right:0.5cm ;
-  margin-bottom:0.5cm }
-
-dd {
-  font-size: 10pt ;
-  padding-top: 0.1cm
-}
-
-dt {
-  font-size: 10pt ;
-  font-weight: bold ;
-  background-color: #6FC7FB ;
-  padding-left: 0.1cm ;
-  padding-top: 0.1cm ;
-  padding-bottom: 0.1cm }
-
-div.abstract {
-  font-size: 10pt }
-
-div.abstract p.topic-title {
-  font-size: 10pt }
-
-div.attention, div.caution, div.danger, div.error, div.hint,
-div.important, div.note, div.tip, div.warning {
-  font-size: 10pt }
-
-div.attention p.admonition-title, div.caution p.admonition-title,
-div.danger p.admonition-title, div.error p.admonition-title,
-div.warning p.admonition-title, div.hint p.admonition-title, 
-div.important p.admonition-title, div.note p.admonition-title, 
-div.tip p.admonition-title {
-  margin-top: 0em ;
-  font-size: 12pt ;
-  font-family: arial,helvetica,univers }
-
-div.dedication {
-  font-size: 10pt }
-
-div.dedication p.topic-title {
-  font-size: 10pt }
-
-div.figure {
-  font-size: 10pt }
-
-div.footer, div.header {
-  font-size: 8pt }
-
-div.system-messages {
-  font-size: 10pt }
-
-div.system-messages h1 {
-  font-size: 12pt }
-
-div.system-message {
-  font-size: 10pt }
-
-div.system-message p.system-message-title {
-  font-size: 10pt }
-
-div.topic {
-  font-size: 10pt }
-
-h1, h2, h3, h4, h5, h6 {
-  padding-top: 0.5cm ;
-  page-break-after: avoid ;
-  font-family: arial,helvetica,univers }
-
-h1 {
-  font-size: 18pt }
-
-h1.title {
-  color: white ;
-  background-color: #00009F ;
-  padding-top: 0cm }
-
-h2 {
-  font-size: 16pt }
-
-h2.subtitle {
-  padding-top: 0cm }
-
-h3 {
-  font-size: 14pt }
-
-h4 {
-  font-size: 12pt }
-
-h5, h6 {
-  font-size: 10pt }
-
-hr {
-  width: 100%;
-  page-break-after: always }
-
-li {
-  padding-top: 1mm ;
-  padding-bottom: 1mm }
-
-ol.simple, ul.simple {
-  font-size: 10pt }
-
-ol.arabic {
-  font-size: 10pt }
-
-ol.loweralpha {
-  font-size: 10pt }
-
-ol.upperalpha {
-  font-size: 10pt }
-
-ol.lowerroman {
-  font-size: 10pt }
-
-ol.upperroman {
-  font-size: 10pt }
-
-p.caption {
-  font-size: 10pt }
-
-p.credits {
-  font-style: italic ;
-  font-size: 8pt }
-
-p.label {
-  font-size: 10pt }
-
-p.topic-title {
-  font-size: 10pt }
-
-pre.address {
-  font-family: arial,helvetica,univers ;
-  font-size: 10pt }
-
-pre.line-block {
-  font-size: 10pt }
-
-pre.literal-block, pre.doctest-block {
-  border-width: 1pt ;
-  border-style: solid ;
-  border-color: #999999 ;
-  color: #0000C0 ;
-  background-color: #ffffe0 ;
-  font-size: 9pt }
-
-span.classifier {
-  font-size: 10pt ;
-  font-family: arial,helvetica,univers }
-
-span.classifier-delimiter {
-  font-size: 10pt ;
-  font-family: arial,helvetica,univers }
-
-span.field-argument {
-  font-size: 10pt }
-
-span.interpreted {
-  font-size: 10pt ;
-  font-family: arial,helvetica,univers }
-
-span.option-argument {
-  font-size: 10pt }
-
-span.problematic {
-  font-size: 10pt }
-
-table {
-  font-size: 10pt ;
-  border-collapse: collapse ;
-  border-width: 1.5pt ;
-  border-color: #003366 }
-
-table.citation {
-  font-size: 10pt }
-
-table.docinfo {
-  font-size: 10pt }
-
-table.footnote {
-  font-size: 8pt ;
-  text-align: left }
-
-table.table {
-  width: 100% }
-
-th {
-  border-width: 1.5pt }
-
-td {
-  border-width: 1pt }
-
-td, th {
-  font-size: 10pt ;
-  border-style: thin ;
-  border-color: #003366 }
-
-td.docinfo-name, th.field-name {
-  font-size: 10pt }
-
-h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
-  font-size: 10pt }
-
-</style>
-</head>
-<body>
-<div class="document" id="advanced-usages-of-plac">
-<h1 class="title">Advanced usages of plac</h1>
-<table class="docinfo" frame="void" rules="none">
-<col class="docinfo-name" />
-<col class="docinfo-content" />
-<tbody valign="top">
-<tr><th class="docinfo-name">Author:</th>
-<td>Michele Simionato</td></tr>
-<tr class="field"><th class="docinfo-name">E-mail:</th><td class="field-body"><a class="reference external" href="mailto:michele.simionato&#64;gmail.com">michele.simionato&#64;gmail.com</a></td>
-</tr>
-<tr><th class="docinfo-name">Date:</th>
-<td>August 2010</td></tr>
-<tr class="field"><th class="docinfo-name">Download page:</th><td class="field-body"><a class="reference external" href="http://pypi.python.org/pypi/plac">http://pypi.python.org/pypi/plac</a></td>
-</tr>
-<tr class="field"><th class="docinfo-name">Project page:</th><td class="field-body"><a class="reference external" href="http://micheles.googlecode.com/hg/plac/doc/plac.html">http://micheles.googlecode.com/hg/plac/doc/plac.html</a></td>
-</tr>
-<tr class="field"><th class="docinfo-name">Installation:</th><td class="field-body"><tt class="docutils literal">easy_install <span class="pre">-U</span> plac</tt></td>
-</tr>
-<tr class="field"><th class="docinfo-name">License:</th><td class="field-body">BSD license</td>
-</tr>
-<tr class="field"><th class="docinfo-name">Requires:</th><td class="field-body">Python 2.5+</td>
-</tr>
-</tbody>
-</table>
-<p><em>The present document discusses a few of the advanced use
-cases for plac. It shows how to write interactive and non-interactive
-interpreters with plac, and how to use plac for testing and scripting a generic
-application. It assumes you have already read an understood the
-basic documentation.</em></p>
-<div class="contents topic" id="contents">
-<p class="topic-title first">Contents</p>
-<ul class="simple">
-<li><a class="reference internal" href="#introduction" id="id1">Introduction</a></li>
-<li><a class="reference internal" href="#from-scripts-to-interactive-applications" id="id2">From scripts to interactive applications</a></li>
-<li><a class="reference internal" href="#testing-a-plac-application" id="id3">Testing a plac application</a></li>
-<li><a class="reference internal" href="#plac-easy-tests" id="id4">Plac easy tests</a></li>
-<li><a class="reference internal" href="#plac-batch-scripts" id="id5">Plac batch scripts</a></li>
-<li><a class="reference internal" href="#implementing-subcommands" id="id6">Implementing subcommands</a></li>
-<li><a class="reference internal" href="#plac-interpreter-call" id="id7">plac.Interpreter.call</a></li>
-<li><a class="reference internal" href="#readline-support" id="id8">Readline support</a></li>
-<li><a class="reference internal" href="#the-plac-runner" id="id9">The plac runner</a></li>
-<li><a class="reference internal" href="#a-non-class-based-example" id="id10">A non class-based example</a></li>
-<li><a class="reference internal" href="#writing-your-own-plac-runner" id="id11">Writing your own plac runner</a></li>
-<li><a class="reference internal" href="#long-running-commands" id="id12">Long running commands</a></li>
-<li><a class="reference internal" href="#threaded-commands" id="id13">Threaded commands</a></li>
-<li><a class="reference internal" href="#running-commands-as-external-processes" id="id14">Running commands as external processes</a></li>
-<li><a class="reference internal" href="#managing-the-output-of-concurrent-commands" id="id15">Managing the output of concurrent commands</a></li>
-<li><a class="reference internal" href="#parallel-computing-with-plac" id="id16">Parallel computing with plac</a></li>
-<li><a class="reference internal" href="#the-plac-server" id="id17">The plac server</a></li>
-<li><a class="reference internal" href="#summary" id="id18">Summary</a></li>
-<li><a class="reference internal" href="#appendix-custom-annotation-objects" id="id19">Appendix: custom annotation objects</a></li>
-</ul>
-</div>
-<div class="section" id="introduction">
-<h1><a class="toc-backref" href="#id1">Introduction</a></h1>
-<p>One of the design goals of <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> is to make it dead easy to write a
-scriptable and testable interface for an application.  You can use
-<a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> whenever you have an API with strings in input and strings in
-output, and that includes a <em>huge</em> domain of applications.</p>
-<p>A string-oriented interface is a scriptable interface by
-construction. That means that you can define a command language for
-your application and that it is possible to write scripts which are
-interpretable by <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> and can be run as batch scripts.</p>
-<p>Actually, at the most general level, you can see <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> as a generic tool to
-write domain specific languages (DSL). With <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> you
-can test your application interactively as well as with batch
-scripts, and even with the analogous of Python doctests for your
-defined language.</p>
-<p>You can easily replace the <tt class="docutils literal">cmd</tt> module of the standard library and
-you could easily write an application like <a class="reference external" href="http://twill.idyll.org/">twill</a> with <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a>. Or you
-could use it to script your building procedure. <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> also supports
-parallel execution of multiple commands and can be used as
-task manager and monitor. It is also quite easy to build a GUI
-or a Web application on top of <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a>. When speaking of things
-you can do with <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a>, your imagination is the only limit!</p>
-</div>
-<div class="section" id="from-scripts-to-interactive-applications">
-<h1><a class="toc-backref" href="#id2">From scripts to interactive applications</a></h1>
-<p>Command-line scripts have many advantages, but they are no substitute
-for interactive applications.
-In particular, if you have a script with a large startup time which must be run
-multiple times, it is best to turn it into an interactive application,
-so that the startup is performed only once.  <tt class="docutils literal">plac</tt> provides an
-<tt class="docutils literal">Interpreter</tt> class just for this purpose.</p>
-<p>The <tt class="docutils literal">Interpreter</tt> class wraps the main function of a script and
-provides an <tt class="docutils literal">.interact</tt> method to start an interactive interpreter
-reading commands from the console.</p>
-<p>For instance, you can define an interactive interpreter on top of the
-<tt class="docutils literal">ishelve</tt> script introduced in the <a class="reference external" href="http://micheles.googlecode.com/hg/plac/doc/plac.html">basic documentation</a> as
-follows:</p>
-<pre class="literal-block">
-# shelve_interpreter.py
-import plac, ishelve
-
-&#64;plac.annotations(
-    interactive=('start interactive interface', 'flag'),
-    subcommands='the commands of the underlying ishelve interpreter')
-def main(interactive, *subcommands):
-    &quot;&quot;&quot;
-    This script works both interactively and non-interactively.
-    Use .help to see the internal commands.
-    &quot;&quot;&quot;
-    if interactive:
-        plac.Interpreter(ishelve.main).interact()
-    else:
-        for out in plac.call(ishelve.main, subcommands):
-            print(out)
-
-if __name__ == '__main__':
-    plac.call(main)
-
-</pre>
-<p>A trick has been used here: the ishelve command-line interface has been
-hidden inside an external interface. They are distinct: for instance
-the external interface recognizes the <tt class="docutils literal"><span class="pre">-h/--help</span></tt> flag whereas the
-internal interface only recognizes the <tt class="docutils literal">.help</tt> command:</p>
-<pre class="literal-block">
-$ python shelve_interpreter.py -h
-</pre>
-<pre class="literal-block">
-usage: shelve_interpreter.py [-h] [-interactive]
-                             [subcommands [subcommands ...]]
-
-    This script works both interactively and non-interactively.
-    Use .help to see the internal commands.
-    
-
-positional arguments:
-  subcommands   the commands of the underlying ishelve interpreter
-
-optional arguments:
-  -h, --help    show this help message and exit
-  -interactive  start interactive interface
-
-</pre>
-<p>Thanks to this ingenuous trick, the script can be run both interactively
-and non-interactively:</p>
-<pre class="literal-block">
-$ python shelve_interpreter.py .clear # non-interactive use
-cleared the shelve
-</pre>
-<p>Here is an usage session:</p>
-<pre class="literal-block">
-$ python shelve_interpreter.py -i # interactive use
-A simple interface to a shelve. Use .help to see the available commands.
-i&gt; .help
-Commands: .help, .showall, .clear, .delete
-&lt;param&gt; ...
-&lt;param=value&gt; ...
-i&gt; a=1
-setting a=1
-i&gt; a
-1
-i&gt; b=2
-setting b=2
-i&gt; a b
-1
-2
-i&gt; .del a
-deleted a
-i&gt; a
-a: not found
-i&gt; .show
-b=2
-i&gt; [CTRL-D]
-</pre>
-<p>The <tt class="docutils literal">.interact</tt> method
-reads commands from the console and send them to the
-underlying interpreter, until the user send a CTRL-D
-command (CTRL-Z in Windows). There is a default
-argument <tt class="docutils literal"><span class="pre">prompt='i&gt;</span> '</tt> which
-can be used to change the prompt. The text displayed at the beginning
-of the interactive session is the docstring of the main function.
-<tt class="docutils literal">plac</tt> also understands command abbreviations: in this example
-<tt class="docutils literal">del</tt> is an abbreviation for <tt class="docutils literal">delete</tt>. In case of ambiguous
-abbreviations <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> raises a <tt class="docutils literal">NameError</tt>.</p>
-<p>Finally I must notice that the <tt class="docutils literal">plac.Interpreter</tt> is available only if you
-are using a recent version of Python (&gt;= 2.5), because it is a context
-manager object which uses extended generators internally.</p>
-</div>
-<div class="section" id="testing-a-plac-application">
-<h1><a class="toc-backref" href="#id3">Testing a plac application</a></h1>
-<p>You can conveniently test your application in interactive mode.
-However manual testing is a poor substitute for automatic testing.</p>
-<p>In principle, one could write automatic tests for the
-<tt class="docutils literal">ishelve</tt> application by using <tt class="docutils literal">plac.call</tt> directly:</p>
-<pre class="literal-block">
-# test_ishelve.py
-import plac, ishelve
-
-def test():
-    assert plac.call(ishelve.main, ['.clear']) == ['cleared the shelve']
-    assert plac.call(ishelve.main, ['a=1']) == ['setting a=1']
-    assert plac.call(ishelve.main, ['a']) == ['1']
-    assert plac.call(ishelve.main, ['.delete=a']) == ['deleted a']
-    assert plac.call(ishelve.main, ['a']) == ['a: not found']
-
-if __name__ == '__main__':
-    test()
-
-</pre>
-<p>However, using <tt class="docutils literal">plac.call</tt> is not especially nice. The big
-issue is that <tt class="docutils literal">plac.call</tt> responds to invalid input by printing an
-error message on stderr and by raising a <tt class="docutils literal">SystemExit</tt>: this is
-certainly not a nice thing to do in a test.</p>
-<p>As a consequence of this behavior it is impossible to test for invalid
-commands, unless you wrap the <tt class="docutils literal">SystemExit</tt> exception by
-hand each time (a possibly you do something with the error message in
-stderr too). Luckily, <tt class="docutils literal">plac</tt> offers a better testing support through
-the <tt class="docutils literal">check</tt> method of <tt class="docutils literal">Interpreter</tt> objects:</p>
-<pre class="literal-block">
-# test_ishelve_more.py
-from __future__ import with_statement
-import plac, ishelve
-
-def test():
-    with plac.Interpreter(ishelve.main) as i:
-        i.check('.clear', 'cleared the shelve')
-        i.check('a=1', 'setting a=1')
-        i.check('a', '1')
-        i.check('.delete=a', 'deleted a')
-        i.check('a', 'a: not found')
-
-</pre>
-<p>The method <tt class="docutils literal">.check(given_input, expected_output)</tt> works on strings
-and raises an <tt class="docutils literal">AssertionError</tt> if the output produced by the
-interpreter is different from the expected output for the given input.
-Notice that <tt class="docutils literal">AssertionError</tt> is catched by tools like <tt class="docutils literal">py.test</tt> and
-<tt class="docutils literal">nosetests</tt> and actually <tt class="docutils literal">plac</tt> tests are intended to be run with
-such tools.</p>
-<p>Interpreters offer a minor syntactic advantage with respect to calling
-<tt class="docutils literal">plac.call</tt> directly, but they offer a <em>major</em> semantic advantage when things
-go wrong (read exceptions): an <tt class="docutils literal">Interpreter</tt> object internally invokes
-something like <tt class="docutils literal">plac.call</tt>, but it wraps all exceptions, so that <tt class="docutils literal">i.check</tt>
-is guaranteed not to raise any exception except <tt class="docutils literal">AssertionError</tt>.</p>
-<p>Even the <tt class="docutils literal">SystemExit</tt> exception is captured and you can write your test as</p>
-<blockquote>
-<tt class="docutils literal"><span class="pre">i.check('-cler',</span> 'SystemExit: unrecognized arguments: <span class="pre">-cler')</span></tt></blockquote>
-<p>without risk of exiting from the Python interpreter.</p>
-<p>There is a second advantage of interpreters: if the main function contains some
-initialization code and finalization code
-(<tt class="docutils literal">__enter__</tt> and <tt class="docutils literal">__exit__</tt> functions) they will be run only
-once at the beginning and at the end of the interpreter loop.
-<tt class="docutils literal">plac.call</tt> instead ignores the initialization/finalization code.</p>
-</div>
-<div class="section" id="plac-easy-tests">
-<h1><a class="toc-backref" href="#id4">Plac easy tests</a></h1>
-<p>Writing your tests in terms of <tt class="docutils literal">Interpreter.check</tt> is certainly an
-improvement over writing them in terms of <tt class="docutils literal">plac.call</tt>, but they
-are still too low-level for my taste. The <tt class="docutils literal">Interpreter</tt> class provides
-support for doctest-style tests, a.k.a. <em>plac easy tests</em>.</p>
-<p>By using plac easy tests you can cut and paste your interactive session and
-turn it into a runnable automatics test.
-Consider for instance the following file <tt class="docutils literal">ishelve.placet</tt> (the <tt class="docutils literal">.placet</tt>
-extension is a mnemonic for plac easy tests):</p>
-<pre class="literal-block">
-#!ishelve.py
-i&gt; .clear # start from a clean state
-cleared the shelve
-i&gt; a=1
-setting a=1
-i&gt; a
-1
-i&gt; .del a
-deleted a
-i&gt; a
-a: not found
-i&gt; .cler # spelling error
-.cler: not found
-
-</pre>
-<p>Notice the precence of the shebang line containing the name of the
-<a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> tool to test (a <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> tool is just a Python module with a
-function called <tt class="docutils literal">main</tt>). The shebang is ignored by the interpreter
-(it looks like a comment to it) but it is there so that external
-tools (say a test runner) can infer the plac interpreter
-to use to test the file.</p>
-<p>You can test <tt class="docutils literal">ishelve.placet</tt> file by calling the
-<tt class="docutils literal">.doctest</tt> method of the interpreter, as in this example:</p>
-<pre class="literal-block">
-$ python -c&quot;import plac, ishelve
-plac.Interpreter(ishelve.main).doctest(open('ishelve.placet'), verbose=True)&quot;
-</pre>
-<p>Internally <tt class="docutils literal">Interpreter.doctests</tt> invokes something like <tt class="docutils literal">Interpreter.check</tt>
-multiple times inside the same context and compare the output with the
-expected output: if even a check fails, the whole test fail.</p>
-<p>You should realize tha the easy tests supported by <tt class="docutils literal">plac</tt> are <em>not</em>
-unittests: they are functional tests. They model then user interaction and the
-order of the operations generally matters.  The single subtests in a
-<tt class="docutils literal">.placet</tt> file are not independent and it makes sense to exit
-immediately at the first failure.</p>
-<p>The support for doctests in <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> comes nearly for free, thanks to the
-<a class="reference external" href="http://docs.python.org/library/shlex.html">shlex</a> module in the standard library, which is able to parse simple
-languages as the ones you can implement with <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a>. In particular,
-thanks to <a class="reference external" href="http://docs.python.org/library/shlex.html">shlex</a>, <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> is able to recognize comments (the default
-comment character is <tt class="docutils literal">#</tt>), escape sequences and more. Look at the
-<a class="reference external" href="http://docs.python.org/library/shlex.html">shlex</a> documentation if you need to customize how the language is
-interpreted. For more flexibility, it is even possible to pass to the
-interpreter a custom split function with signature <tt class="docutils literal">split(line,
-commentchar)</tt>.</p>
-<p>In addition, I have implemented from scratch some support for line number
-recognition, so that if a test fail you get the line number of the
-failing command. This is especially useful if your tests are
-stored in external files, even if plac easy tests does not need to be in
-a file: you can just pass to the <tt class="docutils literal">.doctest</tt> method a list of
-strings corresponding to the lines of the file.</p>
-<p>At the present <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> does not use any code from the doctest
-module, but the situation may change in the future (it would be nice
-if <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> could reuse doctests directives like ELLIPSIS).</p>
-<p>It is straighforward to integrate your <tt class="docutils literal">.placet</tt> tests with standard
-testing tools. For instance, you can integrate your doctests with <tt class="docutils literal">nose</tt>
-or <tt class="docutils literal">py.test</tt> as follow:</p>
-<pre class="literal-block">
-import os, shlex, plac
-
-def test_doct():
-   &quot;&quot;&quot;
-   Find all the doctests in the current directory and run them with the
-   corresponding plac interpreter (the shebang rules!)
-   &quot;&quot;&quot;
-   placets = [f for f in os.listdir('.') if f.endswith('.placet')]
-   for placet in placets:
-       lines = list(open(placet))
-       assert lines[0].startswith('#!'), 'Missing or incorrect shebang line!'
-       firstline = lines[0][2:] # strip the shebang
-       main = plac.import_main(*shlex.split(firstline))
-       yield plac.Interpreter(main).doctest, lines[1:]
-</pre>
-<p>Here you should notice that usage of <tt class="docutils literal">plac.import_main</tt>, an utility
-which is able to import the main function of the script specified in
-the shebang line. You can use both the full path name of the
-tool, or a relative path name. In this case the runner look at the
-environment variable <tt class="docutils literal">PLACPATH</tt> and it searches
-the plac tool in the directories specified there (<tt class="docutils literal">PLACPATH</tt> is just
-a string containing directory names separated by colons). If the variable
-<tt class="docutils literal">PLACPATH</tt> is not defined, it just looks in the current directory.
-If the plac tool is not found, an <tt class="docutils literal">ImportError</tt> is raised.</p>
-</div>
-<div class="section" id="plac-batch-scripts">
-<h1><a class="toc-backref" href="#id5">Plac batch scripts</a></h1>
-<p>It is pretty easy to realize that an interactive interpreter can
-also be used to run batch scripts: instead of reading the commands from
-the console, it is enough to read the commands from a file.
-<a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> interpreters provide an <tt class="docutils literal">.execute</tt> method to perform just that.</p>
-<p>There is just a subtle point to notice: whereas in an interactive loop
-one wants to manage all exceptions, a batch script should not in the
-background in case of unexpected errors. The implementation of
-<tt class="docutils literal">Interpreter.execute</tt> makes sure that any error raised by
-<tt class="docutils literal">plac.call</tt> internally is re-raised.  In other words, <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a>
-interpreters <em>wrap the errors, but does not eat them</em>: the errors are
-always accessible and can be re-raised on demand.</p>
-<p>The exception is the case of invalid commands, which are skipped.
-Consider for instance the following batch file, which contains a
-mispelled command (<tt class="docutils literal">.dl</tt> instead of <tt class="docutils literal">.del</tt>):</p>
-<pre class="literal-block">
-#!ishelve.py
-.clear 
-a=1 b=2
-.show
-.del a
-.dl b
-.show
-
-</pre>
-<p>If you execute the batch file, the interpreter will print a <tt class="docutils literal">.dl: not found</tt>
-at the <tt class="docutils literal">.dl</tt> line and will continue:</p>
-<pre class="literal-block">
-$ python -c &quot;import plac, ishelve
-plac.Interpreter(ishelve.main).execute(open('ishelve.plac'), verbose=True)&quot;
-i&gt; .clear
-cleared the shelve
-i&gt; a=1 b=2
-setting a=1
-setting b=2
-i&gt; .show
-b=2
-a=1
-i&gt; .del a
-deleted a
-i&gt; .dl b
-2
-.dl: not found
-i&gt; .show
-b=2
-</pre>
-<p>The <tt class="docutils literal">verbose</tt> flag is there to show the lines which are being interpreted
-(prefixed by <tt class="docutils literal">i&gt;</tt>). This is done on purpose, so that you can cut and paste
-the output of the batch script and turn it into a <tt class="docutils literal">.placet</tt> test
-(cool, isn't it?).</p>
-</div>
-<div class="section" id="implementing-subcommands">
-<h1><a class="toc-backref" href="#id6">Implementing subcommands</a></h1>
-<p>When I discussed the <tt class="docutils literal">ishelve</tt> implementation in the <a class="reference external" href="http://micheles.googlecode.com/hg/plac/doc/plac.html">basic
-documentation</a>, I said that it looked like a poor man implementation
-of an object system as a chain of elifs; I also said that <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> was
-able to do much better than that.  Here I will substantiate my claim.</p>
-<p><a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> is actually able to infer a set of subparsers from a
-generic container of commands.  This is useful if you want to
-implement <em>subcommands</em> (a familiar example of a command-line
-application featuring subcommands is subversion).</p>
-<p>Technically a container of commands is any object with a <tt class="docutils literal">.commands</tt> attribute
-listing a set of functions or methods which are valid commands. A command
-container may have initialization/finalization hooks (<tt class="docutils literal">__enter__/__exit__</tt>)
-and dispatch hooks (<tt class="docutils literal">__missing__</tt>, invoked for invalid command names).
-Moreover, only when using command containers <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> is able to provide
-automatic autocompletion of commands.</p>
-<p>The shelve interface can be rewritten in an object-oriented way as follows:</p>
-<pre class="literal-block">
-# ishelve2.py
-import shelve, os, sys, plac
-
-class ShelveInterface(object):
-    &quot;A minimal interface over a shelve object.&quot;
-    commands = 'set', 'show', 'showall', 'delete'
-    &#64;plac.annotations(
-        configfile=('path name of the shelve', 'option'))
-    def __init__(self, configfile):
-        self.configfile = configfile or '~/conf.shelve'
-        self.fname = os.path.expanduser(self.configfile)
-        self.__doc__ += '\nOperating on %s.\n.help to see '\
-            'the available commands.\n'  % self.fname
-    def __enter__(self):
-        self.sh = shelve.open(self.fname)
-        return self
-    def __exit__(self, etype, exc, tb):
-        self.sh.close()
-    def set(self, name, value):
-        &quot;set name value&quot;
-        yield 'setting %s=%s' % (name, value)
-        self.sh[name] = value
-    def show(self, *names):
-        &quot;show given parameters&quot;
-        for name in names:
-            yield '%s = %s' % (name, self.sh[name]) # no error checking
-    def showall(self):
-        &quot;show all parameters&quot;
-        for name in self.sh:
-            yield '%s = %s' % (name, self.sh[name])
-    def delete(self, name=None):
-        &quot;delete given parameter (or everything)&quot;
-        if name is None:
-            yield 'deleting everything'
-            self.sh.clear()
-        else:
-            yield 'deleting %s' % name
-            del self.sh[name] # no error checking
-
-main = ShelveInterface # useful for the tests
-
-if __name__ == '__main__':
-    plac.Interpreter(plac.call(ShelveInterface)).interact()
-
-</pre>
-<p><tt class="docutils literal">plac.Interpreter</tt> objects wrap context manager objects
-consistently.  In other words, if you wrap an object with
-<tt class="docutils literal">__enter__</tt> and <tt class="docutils literal">__exit__</tt> methods, they are invoked in the right
-order (<tt class="docutils literal">__enter__</tt> before the interpreter loop starts and
-<tt class="docutils literal">__exit__</tt> after the interpreter loop ends, both in the regular and
-in the exceptional case). In our example, the methods <tt class="docutils literal">__enter__</tt>
-and <tt class="docutils literal">__exit__</tt> make sure the the shelve is opened and closed
-correctly even in the case of exceptions. Notice that I have not
-implemented any error checking in the <tt class="docutils literal">show</tt> and <tt class="docutils literal">delete</tt> methods
-on purpose, to verify that <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> works correctly in the presence of
-exceptions.</p>
-<p>When working with command containers, <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> automatically adds two
-special commands to the set of provided commands: <tt class="docutils literal">.help</tt>
-and <tt class="docutils literal">.last_tb</tt>. The <tt class="docutils literal">.help</tt> command is the easier to understand:
-when invoked without arguments it displays the list of available commands
-with the same formatting of the <a class="reference external" href="http://docs.python.org/library/cmd.html">cmd</a> module; when invoked with the name of
-a command it displays the usage message for that command.
-The <tt class="docutils literal">.last_tb</tt> command is useful when debugging: in case of errors,
-it allows you to display the traceback of the last executed command.</p>
-<p>Here is a session of usage on an Unix-like operating system:</p>
-<pre class="literal-block">
-$ python ishelve2.py
-A minimal interface over a shelve object.
-Operating on /home/micheles/conf.shelve.
-.help to see the available commands.
-i&gt; .help
-
-special commands
-================
-.help .last_tb
-
-custom commands
-===============
-delete  set  show  showall
-
-i&gt; delete
-deleting everything
-i&gt; set a pippo
-setting a=pippo
-i&gt; set b lippo
-setting b=lippo
-i&gt; showall
-b = lippo
-a = pippo
-i&gt; show a b
-a = pippo
-b = lippo
-i&gt; del a
-deleting a
-i&gt; showall
-b = lippo
-i&gt; delete a
-deleting a
-KeyError: 'a'
-i&gt; .last_tb
- File &quot;/usr/local/lib/python2.6/dist-packages/plac-0.6.0-py2.6.egg/plac_ext.py&quot;, line 190, in _wrap
-    for value in genobj:
-  File &quot;./ishelve2.py&quot;, line 37, in delete
-    del self.sh[name] # no error checking
-  File &quot;/usr/lib/python2.6/shelve.py&quot;, line 136, in __delitem__
-    del self.dict[key]
-i&gt;
-</pre>
-<p>Notice that in interactive mode the traceback is hidden, unless
-you pass the <tt class="docutils literal">verbose</tt> flag to the <tt class="docutils literal">Interpreter.interact</tt> method.</p>
-</div>
-<div class="section" id="plac-interpreter-call">
-<h1><a class="toc-backref" href="#id7">plac.Interpreter.call</a></h1>
-<p>At the core of <tt class="docutils literal">plac</tt> there is the <tt class="docutils literal">call</tt> function which invokes
-a callable with the list of the arguments passed at the command-line
-(<tt class="docutils literal">sys.argv[1:]</tt>). Thanks to <tt class="docutils literal">plac.call</tt> you can launch your module
-by simply adding the lines:</p>
-<pre class="literal-block">
-if __name__ == '__main__':
-    plac.call(main)
-</pre>
-<p>Everything works fine if <tt class="docutils literal">main</tt> is a simple callable performing some
-action; however, in many cases, one has a <tt class="docutils literal">main</tt> &quot;function&quot; which
-is a actually a factory returning a command container object. For
-instance, in my second shelve example the main function is the class
-<tt class="docutils literal">ShelveInterface</tt>, and the two lines needed to run the module are
-a bit ugly:</p>
-<pre class="literal-block">
-if __name__ == '__main__':
-   plac.Interpreter(plac.call(ShelveInterface)).interact()
-</pre>
-<p>Moreover, now the program runs, but only in interactive mode, i.e.
-it is not possible to run it as a script. It would be nice instead
-to be able to specify the command to execute on the command-line
-and have the interpreter start, execute the command and finish
-properly (I mean by calling <tt class="docutils literal">__enter__</tt> and <tt class="docutils literal">__exit__</tt>)
-without needing user input. The the script could be called from
-a batch shell script working in the background.
-In order to provide such functionality <tt class="docutils literal">plac.Interpreter</tt> provides
-a classmethod named <tt class="docutils literal">.call</tt> which takes the factory, instantiates
-it with the arguments read from the command line, wraps the resulting
-container object as an interpreter and runs it with the rest arguments
-found in the command line. Here is the code to turn the <tt class="docutils literal">ShelveInterface</tt>
-into a script</p>
-<pre class="literal-block">
-# ishelve3.py
-from ishelve2 import ShelveInterface as main
-
-if __name__ == '__main__':
-    import plac; plac.Interpreter.call(main)
-
-</pre>
-<p>and here are a few examples of usage:</p>
-<pre class="literal-block">
-$ python ishelve3.py -h
-usage: ishelve3.py [-h] [-i] [-configfile CONFIGFILE] [args [args ...]]
-
-positional arguments:
-  args
-
-optional arguments:
-  -h, --help            show this help message and exit
-  -i, --interact        start interactive interpreter
-  -configfile CONFIGFILE
-                        path name of the shelve
-
-$ python ishelve3.py set a 1
-setting a=1
-$ python ishelve3.py show a
-a = 1
-</pre>
-<p>If you pass the <tt class="docutils literal"><span class="pre">-i</span></tt> flag in the command line, then the
-script will enter in interactive mode and ask the user
-for the commands to execute:</p>
-<pre class="literal-block">
-$ python ishelve3.py -i
-A minimal interface over a shelve object.
-Operating on /home/micheles/conf.shelve.
-.help to see the available commands.
-
-i&gt;
-</pre>
-<p>In a sense, I have closed the circle: at the beginning of this
-document I discussed how to turn a script into an interactive
-application (the <tt class="docutils literal">shelve_interpreter.py</tt> example), whereas here I
-have show how to turn an interactive application into a script.</p>
-<p>The complete signature of <tt class="docutils literal">plac.Interpreter.call</tt> is the following:</p>
-<pre class="literal-block">
-call(factory, arglist=sys.argv[1:],
-     commentchar='#', split=shlex.split,
-     stdin=sys.stdin, prompt='i&gt; ', verbose=False)
-</pre>
-<p>The factory must have a fixed number of positional arguments (no
-default arguments, no varargs, no kwargs), otherwise a <tt class="docutils literal">TypeError</tt>
-is raised: the reason is that we want to be able to distinguish the
-command-line arguments needed to instantiate the factory from the rest
-arguments that must be sent to the corresponding interpreter object.
-It is also possible to specify a list of arguments different from
-<tt class="docutils literal">sys.argv[1:]</tt> (useful in tests), the character to be recognized as
-a comment, the splitting function, the input source and the prompt to
-use while in interactive mode, and a verbose flag.</p>
-</div>
-<div class="section" id="readline-support">
-<h1><a class="toc-backref" href="#id8">Readline support</a></h1>
-<p>Starting from release 0.6 <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> offers full readline support. That
-means that if your Python was compiled with readline support you get
-autocompletion and persistent command history for free.  By default
-all commands are autocomplete in a case sensitive way.  If you want to
-add new words to the autocompletion set, or you want to change the
-location of the <tt class="docutils literal">.history</tt> file, or to change the case sensitivity,
-the way to go is to pass a <tt class="docutils literal">plac.ReadlineInput</tt> object to the
-interpreter.  Here is an example, assuming you want to build a
-database interface understanding SQL commands:</p>
-<pre class="literal-block">
-import os, plac
-from sqlalchemy.ext.sqlsoup import SqlSoup
-
-SQLKEYWORDS = set(['select', 'from', 'inner', 'join', 'outer', 'left', 'right']
-                  ) # and many others
-DBTABLES = set(['table1', 'table2']) # you can read them from the db schema
-
-COMPLETIONS = SQLKEYWORDS | DBTABLES
-
-class SqlInterface(object):
-    commands = ['SELECT']
-    def __init__(self, dsn):
-        self.soup = SqlSoup(dsn)
-    def SELECT(self, argstring):
-        sql = 'SELECT ' + argstring
-        for row in self.soup.bind.execute(sql):
-            yield str(row) # the formatting can be much improved
-
-rl_input = plac.ReadlineInput(
-    COMPLETIONS, histfile=os.path.expanduser('~/.sql_interface.history'), 
-    case_sensitive=False)
-
-def split_on_first_space(line, commentchar):
-    return line.strip().split(' ', 1) # ignoring comments
-    
-if __name__ == '__main__':
-    plac.Interpreter.call(SqlInterface, split=split_on_first_space,
-                          stdin=rl_input, prompt='sql&gt; ')
-
-</pre>
-<p>Here is an example of usage:</p>
-<pre class="literal-block">
-$ python sql_interface.py &lt;some dsn&gt;
-sql&gt; SELECT a.* FROM TABLE1 AS a INNER JOIN TABLE2 AS b ON a.id = b.id
-...
-</pre>
-<p>You can check that entering just <tt class="docutils literal">sel</tt> and pressing TAB the readline library
-completes the <tt class="docutils literal">SELECT</tt> keyword for you and makes it upper case; idem for
-<tt class="docutils literal">FROM</tt>, <tt class="docutils literal">INNER</tt>, <tt class="docutils literal">JOIN</tt> and even for the names of the tables. An
-obvious improvement is to read the names of the tables by introspecting
-the database: actually you can even read the names of the views and of
-the columns, and have full autocompletion. All the entered commands
-and recorded and saved in the file <tt class="docutils literal"><span class="pre">~/.sql_interface.history</span></tt> when
-exiting from the command-line interface.</p>
-<p>If the readline library is not available, my suggestion is to use the
-<a class="reference external" href="http://freshmeat.net/projects/rlwrap/">rlwrap</a> tool which provides similar features, at least on Unix-like
-platforms. <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> should also work fine on Windows with the <a class="reference external" href="http://ipython.scipy.org/moin/PyReadline/Intro">pyreadline</a>
-library (I do not use Windows, so this part is very little tested: I
-tried it only once and it worked, but your mileage may vary).
-For people worried about licenses, I will notice that <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> uses the
-readline library only if available, it does not include it and it does
-not rely on it in any fundamental way, so that the <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> licence does
-not need to be the GPL (actually it is a BSD
-do-whatever-you-want-with-it licence).</p>
-<p>The interactive mode of <tt class="docutils literal">plac</tt> can be used as a replacement of the
-<a class="reference external" href="http://docs.python.org/library/cmd.html">cmd</a> module in the standard library. It is actually better than <a class="reference external" href="http://docs.python.org/library/cmd.html">cmd</a>:
-for instance, the <tt class="docutils literal">.help</tt> command is more powerful, since it
-provides information about the arguments accepted by the given command:</p>
-<pre class="literal-block">
-i&gt; .help set
-usage:  set name value
-
-set name value
-
-positional arguments:
-  name
-  value
-
-i&gt; .help delete
-usage:  delete [name]
-
-delete given parameter (or everything)
-
-positional arguments:
-  name
-
-i&gt; .help show
-usage:  show [names [names ...]]
-
-show given parameters
-
-positional arguments:
-  names
-</pre>
-<p>As you can imagine, the help message is provided by the underlying <a class="reference external" href="http://argparse.googlecode.com">argparse</a>
-subparser (there is a subparser for each command). <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> commands accept
-options, flags, varargs, keyword arguments, arguments with defaults,
-arguments with a fixed number of choices, type conversion and all the
-features provided of <a class="reference external" href="http://argparse.googlecode.com">argparse</a> which should be reimplemented from scratch
-using <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a>.</p>
-<p>Moreover at the moment <tt class="docutils literal">plac</tt> also understands command abbreviations.
-However, this feature may disappear in
-future releases. It was meaningful in the past, when <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> did not support
-readline.</p>
-<p>Notice that if an abbreviation is ambiguous, <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> warns you:</p>
-<pre class="literal-block">
-i&gt; sh
-NameError: Ambiguous command 'sh': matching ['showall', 'show']
-</pre>
-</div>
-<div class="section" id="the-plac-runner">
-<h1><a class="toc-backref" href="#id9">The plac runner</a></h1>
-<p>The distribution of <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> includes a runner script named <tt class="docutils literal">plac_runner.py</tt>,
-which will be installed in a suitable directory in your system by <a class="reference external" href="http://docs.python.org/distutils/">distutils</a>
-(say in <tt class="docutils literal">\usr\local\bin\plac_runner.py</tt> in a Unix-like operative system).
-The runner provides many facilities to run <tt class="docutils literal">.plac</tt> scripts and
-<tt class="docutils literal">.placet</tt> files, as well as Python modules containg a <tt class="docutils literal">main</tt>
-object, which can be a function, a command container object or
-even a command container class.</p>
-<p>For instance, suppose you want to execute a script containing commands
-defined in the <tt class="docutils literal">ishelve2</tt> module like the following one:</p>
-<pre class="literal-block">
-#!ishelve2.py:ShelveInterface -c ~/conf.shelve
-set a 1
-del a
-del a # intentional error
-
-</pre>
-<p>The first line of the <tt class="docutils literal">.plac</tt> script contains the name of the
-python module containing the plac interpreter and the arguments
-which must be passed to its main function in order to be able
-to instantiate an interpreter object. In this case I appended
-<tt class="docutils literal">:ShelveInterface</tt> to the name of the module to specify the
-object that must be imported: if not specified, by default the
-object named 'main' is imported.
-The other lines contains commands.
-You can run the script as follows:</p>
-<pre class="literal-block">
-$ plac_runner.py --batch ishelve2.plac
-setting a=1
-deleting a
-Traceback (most recent call last):
-  ...
-_bsddb.DBNotFoundError: (-30988, 'DB_NOTFOUND: No matching key/data pair found')
-</pre>
-<p>The last command intentionally contained an error, to show that the
-plac runner does not eat the traceback.</p>
-<p>The runner can also be used to run Python modules in interactive
-mode and non-interactive mode. If you put this alias in your bashrc</p>
-<blockquote>
-<tt class="docutils literal">alias <span class="pre">plac=&quot;plac_runner.py&quot;</span></tt></blockquote>
-<p>(or you define a suitable <tt class="docutils literal">plac.bat</tt> script in Windows) you can
-run the <tt class="docutils literal">ishelve2.py</tt> script in interactive mode as
-follows:</p>
-<pre class="literal-block">
-$ plac -i ishelve2.py
-A minimal interface over a shelve object.
-Operating on /home/micheles/conf.shelve.
-.help to see the available commands.
-
-i&gt; del
-deleting everything
-i&gt; set a 1
-setting a=1
-i&gt; set b 2
-setting b=2
-i&gt; show b
-b = 2
-</pre>
-<p>Now you can cut and paste the interactive session an turns into into
-a <tt class="docutils literal">.placet</tt> file like the following:</p>
-<pre class="literal-block">
-#!ishelve2.py:ShelveInterface -configfile=~/test.shelve
-i&gt; del
-deleting everything
-i&gt; set a 1
-setting a=1
-i&gt; set b 2
-setting b=2
-i&gt; show a
-a = 1
-
-</pre>
-<p>Notice that the first line specifies a test database
-<tt class="docutils literal">~/test.shelve</tt>, to avoid clobbering your default shelve. If you
-mispell the arguments in the first line plac will give you an
-<a class="reference external" href="http://argparse.googlecode.com">argparse</a> error message (just try).</p>
-<p>You can run placets following the shebang convention directly with
-the plac runner:</p>
-<pre class="literal-block">
-$ plac --test ishelve2.placet
-run 1 plac test(s)
-</pre>
-<p>If you want to see the output of the tests, pass the <tt class="docutils literal"><span class="pre">-v/--verbose</span></tt> flag.
-Notice that he runner ignore the extension, so you can actually use any
-extension your like, but <em>it relies on the first line of the file to invoke
-the corresponding plac tool with the given arguments</em>.</p>
-<p>The plac runner does not provide any test discovery facility,
-but you can use standard Unix tools to help. For instance, you can
-run all the <tt class="docutils literal">.placet</tt> files into a directory and its subdirectories
-as follows:</p>
-<pre class="literal-block">
-$ find . -name \*.placet | xargs plac_runner.py -t
-</pre>
-<p>The plac runner expects the main function of your script to
-return a plac tool, i.e. a function or an object with a <tt class="docutils literal">.commands</tt>
-attribute. It this is not the case the runner gracefully exits.</p>
-<p>It also works in non-interactive mode, if you call it as</p>
-<blockquote>
-<tt class="docutils literal">$ plac module.py args ...</tt></blockquote>
-<p>Here is an example:</p>
-<pre class="literal-block">
-$ plac ishelve.py a=1
-setting a=1
-$ plac ishelve.py .show
-a=1
-</pre>
-<p>Notice that in non-interactive mode the runner just invokes <tt class="docutils literal">plac.call</tt>
-on the <tt class="docutils literal">main</tt> object of the Python module.</p>
-</div>
-<div class="section" id="a-non-class-based-example">
-<h1><a class="toc-backref" href="#id10">A non class-based example</a></h1>
-<p><a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> does not force you to use classes to define command containers.
-Even a simple function can be a valid command container, it is
-enough to add to it a <tt class="docutils literal">.commands</tt> attribute and possibly
-<tt class="docutils literal">__enter__</tt> and/or <tt class="docutils literal">__exit__</tt> attributes.</p>
-<p>In particular, a Python module is a perfect container of commands. As an
-example, consider the following module implementing a fake Version
-Control System:</p>
-<pre class="literal-block">
-&quot;A Fake Version Control System&quot;
-
-import plac
-
-commands = 'checkout', 'commit', 'status'
-
-&#64;plac.annotations(url='url of the source code')
-def checkout(url):
-    &quot;A fake checkout command&quot;
-    return ('checkout ', url)
-
-&#64;plac.annotations(message=('commit message', 'option'))
-def commit(message):
-    &quot;A fake commit command&quot;
-    return ('commit ', message)
-
-&#64;plac.annotations(quiet=('summary information', 'flag', 'q'))
-def status(quiet):
-    &quot;A fake status command&quot;
-    return ('status ', quiet)
-
-def __missing__(name):
-    return 'Command %r does not exist' % name
-
-def __exit__(etype, exc, tb):
-    &quot;Will be called automatically at the end of the call/cmdloop&quot;
-    if etype in (None, GeneratorExit): # success
-        print('ok')
-
-main = __import__(__name__) # the module imports itself!
-
-</pre>
-<p>Notice that I have defined both an <tt class="docutils literal">__exit__</tt> hook and a <tt class="docutils literal">__missing__</tt>
-hook, invoked for non-existing commands.
-The real trick here is the line <tt class="docutils literal">main = __import__(__name__)</tt>, which
-define <tt class="docutils literal">main</tt> to be an alias for the current module.</p>
-<p>The <tt class="docutils literal">vcs</tt> module does not contain an <tt class="docutils literal">if __name__ == '__main__'</tt>
-block, but you can still run it through the plac runner
-(try <tt class="docutils literal">plac vcs.py <span class="pre">-h</span></tt>):</p>
-<pre class="literal-block">
-usage: plac_runner.py vcs.py [-h] {status,commit,checkout} ...
-
-A Fake Version Control System
-
-optional arguments:
-  -h, --help            show this help message and exit
-
-subcommands:
-  {status,commit,checkout}
-                        -h to get additional help
-
-</pre>
-<p>You can get help for the subcommands by postponing <tt class="docutils literal"><span class="pre">-h</span></tt> after the
-name of the command:</p>
-<pre class="literal-block">
-$ plac vcs.py status -h
-usage: vcs.py status [-h] [-q]
-
-A fake status command
-
-optional arguments:
-  -h, --help   show this help message and exit
-  -q, --quiet  summary information
-</pre>
-<p>Notice how the docstring of the command is automatically shown in
-usage message, as well as the documentation for the sub flag <tt class="docutils literal"><span class="pre">-q</span></tt>.</p>
-<p>Here is an example of a non-interactive session:</p>
-<pre class="literal-block">
-$ plac vcs.py check url
-checkout
-url
-$ plac vcs.py st -q
-status
-True
-$ plac vcs.py co
-commit
-None
-</pre>
-<p>and here is an interactive session:</p>
-<pre class="literal-block">
-$ plac -i vcs.py
-usage: plac_runner.py vcs.py [-h] {status,commit,checkout} ...
-i&gt; check url
-checkout
-url
-i&gt; st -q
-status
-True
-i&gt; co
-commit
-None
-i&gt; sto
-Command 'sto' does not exist
-i&gt; [CTRL-D]
-ok
-</pre>
-<p>Notice the invocation of the <tt class="docutils literal">__missing__</tt> hook for non-existing commands.
-Notice also that the <tt class="docutils literal">__exit__</tt> hook gets called only in interactive
-mode.</p>
-<p>If the commands are completely independent, a module is a good fit for
-a method container. In other situations, it is best to use a custom
-class.</p>
-</div>
-<div class="section" id="writing-your-own-plac-runner">
-<h1><a class="toc-backref" href="#id11">Writing your own plac runner</a></h1>
-<p>The runner included in the <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> distribution is intentionally kept
-small (around 50 lines of code) so that you can study it and write
-your own runner if want to. If you need to go to such level
-of detail, you should know that the most important method of
-the <tt class="docutils literal">Interpreter</tt> class is the <tt class="docutils literal">.send</tt> method, which takes
-strings in input and returns a four-tuple with attributes
-<tt class="docutils literal">.str</tt>, <tt class="docutils literal">.etype</tt>, <tt class="docutils literal">.exc</tt> and <tt class="docutils literal">.tb</tt>:</p>
-<ul class="simple">
-<li><tt class="docutils literal">.str</tt> is the output of the command, if successful (a string);</li>
-<li><tt class="docutils literal">.etype</tt> is the class of the exception, if the command fail;</li>
-<li><tt class="docutils literal">.exc</tt> is the exception instance;</li>
-<li><tt class="docutils literal">.tb</tt> is the traceback.</li>
-</ul>
-<p>Moreover the <tt class="docutils literal">__str__</tt> representation of the output object is redefined
-to return the output string if the command was successful or the error
-message if the command failed (actually it returns the error message
-preceded by the name of the exception class).</p>
-<p>For instance, if you send a mispelled option to
-the interpreter a <tt class="docutils literal">SystemExit</tt> will be trapped:</p>
-<pre class="doctest-block">
-&gt;&gt;&gt; import plac
-&gt;&gt;&gt; from ishelve import ishelve
-&gt;&gt;&gt; with plac.Interpreter(ishelve) as i:
-...     print(i.send('.cler'))
-...
-SystemExit: unrecognized arguments: .cler
-</pre>
-<p>It is important to invoke the <tt class="docutils literal">.send</tt> method inside the context manager,
-otherwise you will get a <tt class="docutils literal">RuntimeError</tt>.</p>
-<p>For instance, suppose you want to implement a graphical runner for a
-plac-based interpreter with two text widgets: one to enter the commands
-and one to display the results. Suppose you want to display the errors
-with tracebacks in red. You will need to code something like that
-(pseudocode follows):</p>
-<pre class="literal-block">
-input_widget = WidgetReadingInput()
-output_widget = WidgetDisplayingOutput()
-
-def send(interpreter, line):
-    out = interpreter.send(line)
-    if out.tb: # there was an error
-        output_widget.display(out.tb, color='red')
-    else:
-        output_widget.display(out.str)
-
-main = plac.import_main(tool_path) # get the main object
-
-with plac.Interpreter(main) as i:
-   def callback(event):
-      if event.user_pressed_ENTER():
-           send(i, input_widget.last_line)
-   input_widget.addcallback(callback)
-   gui_mainloop.start()
-</pre>
-<p>You can adapt the pseudocode to your GUI toolkit of choice and you can
-also change the file associations in such a way that clicking on a
-plac tool file the graphical user interface starts.</p>
-<p>An example of GUI program built on top of <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> is given later on, in the
-paragraph <em>Managing the output of concurrent commands</em> (using Tkinter
-for simplicity and portability).</p>
-<p>There is a final <em>caveat</em>: since the plac interpreter loop is
-implemented via extended generators, plac interpreters are single threaded: you
-will get an error if you <tt class="docutils literal">.send</tt> commands from separated threads.
-You can circumvent the problem by using a queue. If EXIT is a sentinel
-value to signal exiting from the interpreter look, you can write code
-like this:</p>
-<pre class="literal-block">
-with interpreter:
-    for input_value in iter(input_queue.get, EXIT):
-        output_queue.put(interpreter.send(input_value))
-</pre>
-<p>The same trick also work for processes; you could run the interpreter
-loop in a separate process and send commands to it via the Queue
-class provided by the <a class="reference external" href="http://docs.python.org/library/multiprocessing.html">multiprocessing</a> module.</p>
-</div>
-<div class="section" id="long-running-commands">
-<h1><a class="toc-backref" href="#id12">Long running commands</a></h1>
-<p>As we saw, by default a <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> interpreter blocks until
-the command terminates. This is an issue, in the sense that it makes
-the interactive experience quite painful for long running commands. An
-example is better than a thousand words, so consider the following
-fake importer:</p>
-<pre class="literal-block">
-import time
-import plac
-
-class FakeImporter(object):
-    &quot;A fake importer with an import_file command&quot;
-    commands = ['import_file']
-    def __init__(self, dsn):
-        self.dsn = dsn
-    def import_file(self, fname):
-        &quot;Import a file into the database&quot;
-        try:
-            for n in range(10000):
-                time.sleep(.01)
-                if n % 100 == 99:
-                    yield 'Imported %d lines' % (n+1)
-        finally:
-            print('closing the file')
-
-if __name__ == '__main__':
-    plac.Interpreter.call(FakeImporter)
-
-</pre>
-<p>If you run the <tt class="docutils literal">import_file</tt> command, you will have to wait for 200 seconds
-before entering a new command:</p>
-<pre class="literal-block">
-$ python importer1.py dsn
-A fake importer with an import_file command
-i&gt; import_file file1
-... &lt;wait 3+ minutes&gt;
-Imported 100 lines
-Imported 200 lines
-Imported 300 lines
-...
-Imported 10000 lines
-closing the file
-</pre>
-<p>Being unable to enter any other command is quite annoying: in such situation one
-would like to run the long running commands in the background, to keep
-the interface responsive. <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> provides two ways to reach this goal: threads
-and processes.</p>
-</div>
-<div class="section" id="threaded-commands">
-<h1><a class="toc-backref" href="#id13">Threaded commands</a></h1>
-<p>The most familiar way to execute a task in the background (even if not
-necessarily the best way) is to run it into a separated thread. In our
-example it is sufficient to replace the line</p>
-<blockquote>
-<tt class="docutils literal">commands = ['import_file']</tt></blockquote>
-<p>with</p>
-<blockquote>
-<tt class="docutils literal">thcommands = ['import_file']</tt></blockquote>
-<p>to tell to the <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> interpreter that the command <tt class="docutils literal">import_file</tt> should be
-run into a separated thread. Here is an example session:</p>
-<pre class="literal-block">
-i&gt; import_file file1
-&lt;ThreadedTask 1 [import_file file1] RUNNING&gt;
-</pre>
-<p>The import task started in a separated thread. You can see the
-progress of the task by using the special command <tt class="docutils literal">.output</tt>:</p>
-<pre class="literal-block">
-i&gt; .output 1
-&lt;ThreadedTask 1 [import_file file1] RUNNING&gt;
-Imported 100 lines
-Imported 200 lines
-</pre>
-<p>If you look after a while, you will get more lines of output:</p>
-<pre class="literal-block">
-i&gt; .output 1
-&lt;ThreadedTask 1 [import_file file1] RUNNING&gt;
-Imported 100 lines
-Imported 200 lines
-Imported 300 lines
-Imported 400 lines
-</pre>
-<p>If you look after a time long enough, the task will be finished:</p>
-<pre class="literal-block">
-i&gt; .output 1
-&lt;ThreadedTask 1 [import_file file1] FINISHED&gt;
-</pre>
-<p>You can even skip the number argument: then <tt class="docutils literal">.output</tt> will the return
-the output of the last launched command (the special commands like .output
-do not count).</p>
-<p>You can launch many tasks one after the other:</p>
-<pre class="literal-block">
-i&gt; import_file file2
-&lt;ThreadedTask 5 [import_file file2] RUNNING&gt;
-i&gt; import_file file3
-&lt;ThreadedTask 6 [import_file file3] RUNNING&gt;
-</pre>
-<p>The <tt class="docutils literal">.list</tt> command displays all the running tasks:</p>
-<pre class="literal-block">
-i&gt; .list
-&lt;ThreadedTask 5 [import_file file2] RUNNING&gt;
-&lt;ThreadedTask 6 [import_file file3] RUNNING&gt;
-</pre>
-<p>It is even possible to kill a task:</p>
-<pre class="literal-block">
-i&gt; .kill 5
-&lt;ThreadedTask 5 [import_file file2] TOBEKILLED&gt;
-# wait a bit ...
-closing the file
-i&gt; .output 5
-&lt;ThreadedTask 5 [import_file file2] KILLED&gt;
-</pre>
-<p>You should notice that since at the Python level it is impossible to kill
-a thread, the <tt class="docutils literal">.kill</tt> commands works by setting the status of the task to
-<tt class="docutils literal">TOBEKILLED</tt>. Internally the generator corresponding to the command
-is executed in the thread and the status is checked at each iteration:
-when the status become <tt class="docutils literal">TOBEKILLED</tt> a <tt class="docutils literal">GeneratorExit</tt> exception is
-raised and the thread terminates (softly, so that the <tt class="docutils literal">finally</tt> clause
-is honored). In our example the generator is yielding
-back control once every 100 iterations, i.e. every two seconds (not much).
-In order to get a responsive interface it is a good idea to yield more
-often, for instance every 10 iterations (i.e. 5 times per second),
-as in the following code:</p>
-<pre class="literal-block">
-import time
-import plac
-
-class FakeImporter(object):
-    &quot;A fake importer with an import_file command&quot;
-    thcommands = ['import_file']
-    def __init__(self, dsn):
-        self.dsn = dsn
-    def import_file(self, fname):
-        &quot;Import a file into the database&quot;
-        try:
-            for n in range(10000):
-                time.sleep(.02)
-                if n % 100 == 99: # every two seconds
-                    yield 'Imported %d lines' % (n+1)
-                if n % 10 == 9: # every 0.2 seconds
-                    yield # go back and check the TOBEKILLED status
-        finally:
-            print('closing the file')
-
-if __name__ == '__main__':
-    plac.Interpreter.call(FakeImporter)
-
-</pre>
-</div>
-<div class="section" id="running-commands-as-external-processes">
-<h1><a class="toc-backref" href="#id14">Running commands as external processes</a></h1>
-<p>Threads are not loved much in the Python world and actually most people
-prefer to use processes instead. For this reason <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> provides the
-option to execute long running commands as external processes. Unfortunately
-the current implementation only works in Unix-like operating systems
-(including Mac OS X) because it relies on fork via the <a class="reference external" href="http://docs.python.org/library/multiprocessing.html">multiprocessing</a>
-module.</p>
-<p>In our example, to enable the feature it is sufficient to replace the line</p>
-<blockquote>
-<tt class="docutils literal">thcommands = ['import_file']</tt></blockquote>
-<p>with</p>
-<blockquote>
-<tt class="docutils literal">mpcommands = ['import_file']</tt>.</blockquote>
-<p>The user experience is exactly the same as with threads and you will not see any
-difference at the user interface level:</p>
-<pre class="literal-block">
-i&gt; import_file file3
-&lt;MPTask 1 [import_file file3] SUBMITTED&gt;
-i&gt; .kill 1
-&lt;MPTask 1 [import_file file3] RUNNING&gt;
-closing the file
-i&gt; .o 1
-&lt;MPTask 1 [import_file file3] KILLED&gt;
-Imported 100 lines
-Imported 200 lines
-i&gt;
-</pre>
-<p>Still, using processes is quite different than using threads: in
-particular, when using processes you can only yield pickleable values
-and you cannot re-raise an exception first raised in a different
-process, because traceback objects are not pickleable. Moreover,
-you cannot rely on automatic sharing of your objects.</p>
-<p>On the plus side, when using processes you do not need to worry about
-killing a command: they are killed immediately using a SIGTERM signal,
-and there is not a <tt class="docutils literal">TOBEKILLED</tt> mechanism. Moreover, the killing is
-guaranteed to be soft: internally a command receiving a SIGTERM raises
-a <tt class="docutils literal">TerminatedProcess</tt> exception which is trapped in the generator
-loop, so that the command is closed properly.</p>
-<p>Using processes allows to take full advantage of multicore machines
-and it is safer than using threads, so it is the recommended approach
-unless you are working on Windows.</p>
-</div>
-<div class="section" id="managing-the-output-of-concurrent-commands">
-<h1><a class="toc-backref" href="#id15">Managing the output of concurrent commands</a></h1>
-<p><a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> acts as a command-line task launcher and can be used as the base
-to build a GUI-based task launcher and task monitor. To this aim the
-interpreter class provides a <tt class="docutils literal">.submit</tt> method which returns a task
-object and a <tt class="docutils literal">.tasks</tt> method returning the list of all the tasks
-submitted to the interpreter.  The <tt class="docutils literal">submit</tt> method does not start the task
-and thus it is nonblocking.
-Each task has an <tt class="docutils literal">.outlist</tt> attribute which is a list
-storing the value yielded by the generator underlying the task (the
-<tt class="docutils literal">None</tt> values are skipped though): the <tt class="docutils literal">.outlist</tt> grows as the
-task runs and more values are yielded. Accessing the <tt class="docutils literal">.outlist</tt> is
-nonblocking and can be done freely.
-Finally there is a <tt class="docutils literal">.result</tt>
-property which waits for the task to finish and returns the last yielded
-value or raises an exception.</p>
-<p>Here is some example code to visualize the output of the FakeImporter
-in Tkinter (I chose Tkinter because it is easy to use and it is
-in the standard library, but you can use any GUI):</p>
-<pre class="literal-block">
-from Tkinter import *
-from importer3 import FakeImporter
-
-def taskwidget(root, task, tick=500):
-    &quot;A Label widget showing the output of a task every 500 ms&quot;
-    sv = StringVar(root)
-    lb = Label(root, textvariable=sv)
-    def show_outlist():
-        try:
-            out = task.outlist[-1]
-        except IndexError: # no output yet
-            out = ''
-        sv.set('%s %s' % (task, out))
-        root.after(tick, show_outlist)
-    root.after(0, show_outlist)
-    return lb
-
-def monitor(tasks):
-    root = Tk()
-    for task in tasks:
-        task.run()
-        taskwidget(root, task).pack()
-    root.mainloop()
-
-if __name__ == '__main__':
-    import plac
-    with plac.Interpreter(plac.call(FakeImporter)) as i:
-        tasks = [i.submit('import_file f1'), i.submit('import_file f2')]
-        monitor(tasks)
-
-</pre>
-</div>
-<div class="section" id="parallel-computing-with-plac">
-<h1><a class="toc-backref" href="#id16">Parallel computing with plac</a></h1>
-<p><a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> is certainly not intended as a tool for parallel computing, but
-still you can use it to launch a set of commands and to collect the
-results, similarly to the MapReduce pattern recently popularized by
-Google.  In order to give an example, I will consider the &quot;Hello
-World&quot; of parallel computing, i.e. the computation of pi with
-independent processes.  There is a huge number of algorithms to
-compute pi; here I will describe a trivial one chosen for simplicity,
-not per efficienty. The trick is to consider the first quadrant of a
-circle with radius 1 and to extract a number of points <tt class="docutils literal">(x, y)</tt> with
-<tt class="docutils literal">x</tt> and <tt class="docutils literal">y</tt> random variables in the interval <tt class="docutils literal">[0,1]</tt>. The
-probability of extracting a number inside the quadrant (i.e. with
-<tt class="docutils literal">x^2 + y^2 &lt; 1</tt>) is proportional to the area of the quadrant
-(i.e. <tt class="docutils literal">pi/4</tt>). The value of <tt class="docutils literal">pi</tt> therefore can be extracted by
-multiplying by 4 the ratio between the number of points in the
-quadrant versus the total number of points <tt class="docutils literal">N</tt>, for <tt class="docutils literal">N</tt> large:</p>
-<pre class="literal-block">
-def calc_pi(N):
-    inside = 0
-    for j in xrange(N):
-        x, y = random(), random()
-        if x*x + y*y &lt; 1:
-            inside += 1
-    return (4.0 * inside) / N
-</pre>
-<p>The algorithm is trivially parallelizable: if you have n CPUs, you can
-compute pi n times with N/n iterations, sum the results and divide the total
-by n. I have a Macbook with two cores, therefore I would expect a speedup
-factor of 2 with respect to a sequential computation. Moreover, I would
-expect a threaded computation to be even slower than a sequential
-computation, due to the GIL and the scheduling overhead.</p>
-<p>Here is a script implementing the algorithm and working in three different
-modes (parallel mode, threaded mode and sequential mode) depending on a
-<tt class="docutils literal">mode</tt> option:</p>
-<pre class="literal-block">
-from __future__ import with_statement
-from random import random
-import multiprocessing
-import plac
-
-class PiCalculator(object):
-    &quot;&quot;&quot;Compute pi in parallel with threads or processes&quot;&quot;&quot;
-    
-    &#64;plac.annotations(
-        npoints=('number of integration points', 'positional', None, int),
-        mode=('sequential|parallel|threaded', 'option', 'm', str, 'SPT'))
-    def __init__(self, npoints, mode='S'):
-        self.npoints = npoints
-        if mode == 'P':
-            self.mpcommands = ['calc_pi']
-        elif mode == 'T':
-            self.thcommands = ['calc_pi']
-        elif mode == 'S':
-            self.commands = ['calc_pi']
-        self.n_cpu = multiprocessing.cpu_count()
-    
-    def submit_tasks(self):
-        self.i = plac.Interpreter(self).__enter__()            
-        return [self.i.submit('calc_pi %d' % (self.npoints / self.n_cpu))
-                for _ in range(self.n_cpu)]
-
-    def close(self):
-        self.i.close()
-
-    &#64;plac.annotations(
-        npoints=('npoints', 'positional', None, int))
-    def calc_pi(self, npoints):
-        counts = 0
-        for j in xrange(npoints):
-            n, r = divmod(j, 1000000)
-            if r == 0:
-                yield '%dM iterations' % n
-            x, y = random(), random()
-            if x*x + y*y &lt; 1:
-                counts += 1
-        yield (4.0 * counts)/npoints
-
-    def run(self):
-        tasks = self.i.tasks()
-        for t in tasks:
-            t.run()
-        try:
-            total = 0
-            for task in tasks:
-                total += task.result
-        except: # the task was killed
-            print tasks
-            return
-        return total / self.n_cpu
-
-if __name__ == '__main__':
-    pc = plac.call(PiCalculator)
-    pc.submit_tasks()
-    try:
-        import time; t0 = time.time()
-        print '%f in %f seconds ' % (pc.run(), time.time() - t0)
-    finally:
-        pc.close()
-
-</pre>
-<p>Notice the <tt class="docutils literal">submit_tasks</tt> method, which instantiates and initializes a
-<tt class="docutils literal">plac.Interpreter</tt> object and submits a number of commands corresponding
-to the number of available CPUs. The <tt class="docutils literal">calc_pi</tt> command yield a log
-message every million of interactions, just to monitor the progress of
-the computation. The <tt class="docutils literal">run</tt> method starts all the submitted commands
-in parallel and sums the results. It returns the average value of <tt class="docutils literal">pi</tt>
-after the slowest CPU has finished its job (if the CPUs are equal and
-equally busy they should finish more or less at the same time).</p>
-<p>Here are the results on my old Macbook with Ubuntu 10.04 and Python 2.6,
-for 10 million of iterations:</p>
-<pre class="literal-block">
-$ python picalculator.py -mP 10000000
-3.141904 in 5.744545 seconds
-$ python picalculator.py -mT 10000000
-3.141272 in 13.875645 seconds
-$ python picalculator.py -mS 10000000
-3.141586 in 11.353841 seconds
-</pre>
-<p>As you see using processes one gets a 2x speedup indeed, where the threaded
-mode is some 20% slower than the sequential mode.</p>
-</div>
-<div class="section" id="the-plac-server">
-<h1><a class="toc-backref" href="#id17">The plac server</a></h1>
-<p>A command-line oriented interface can be easily converted into a
-socket-based interface. Starting from release 0.7 plac features
-a builtin server which is able to accept commands from multiple
-clients and to execute them. The server works by instantiating
-a separate interpreter for each client, so that if a client interpreter
-dies for any reason the other interpreters keep working.
-To avoid external dependencies the server is based on the <tt class="docutils literal">asynchat</tt>
-module in the standard library, but it would not be difficult to
-replace the server with a different one (for instance, a Twisted server).
-Since <tt class="docutils literal">asynchat</tt>-based servers are asynchronous, any blocking command
-in the interpreter should be run in a separated process or thread.
-The default port for the <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> server is 2199, and the command to
-signal end-of-connection is EOF.
-For instance, here is how you could manage remote import on a database
-(say a SQLite db):</p>
-<pre class="literal-block">
-import plac
-from importer2 import FakeImporter
-
-def main(port=2199):
-    main = FakeImporter('dsn')
-    plac.Interpreter(main).start_server(port)
-    
-if __name__ == '__main__':
-   plac.call(main)
-
-</pre>
-<p>You can connect to the server with <tt class="docutils literal">telnet</tt> on port 2199, as follows:</p>
-<pre class="literal-block">
-$ telnet localhost 2199
-Trying ::1...
-Trying 127.0.0.1...
-Connected to localhost.
-Escape character is '^]'.
-i&gt; import_file f1
-i&gt; .list
-&lt;ThreadedTask 1 [import_file f1] RUNNING&gt;
-i&gt; .out
-Imported 100 lines
-Imported 200 lines
-i&gt; EOF
-Connection closed by foreign host.
-</pre>
-</div>
-<div class="section" id="summary">
-<h1><a class="toc-backref" href="#id18">Summary</a></h1>
-<p>Once <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> claimed to be the easiest command-line arguments parser
-in the world. Having read this document you may think that it is not
-so easy after all. But it is a false impression. Actually the
-rules are quite simple:</p>
-<ol class="arabic simple">
-<li>if you want to implement a command-line script, use <tt class="docutils literal">plac.call</tt>;</li>
-<li>if you want to implement a command interpreter, use <tt class="docutils literal">plac.Interpreter</tt>:<ul>
-<li>for an interactive interpreter, call the <tt class="docutils literal">.interact</tt> method;</li>
-<li>for an batch interpreter, call the <tt class="docutils literal">.execute</tt> method;</li>
-</ul>
-</li>
-<li>for testing call the <tt class="docutils literal">Interpreter.check</tt> method in the appropriate context
-or use the <tt class="docutils literal">Interpreter.doctest</tt> feature;</li>
-<li>if you need to go at a lower level, you may need to call the
-<tt class="docutils literal">Interpreter.send</tt> method which returns a (finished) <tt class="docutils literal">Task</tt> object.</li>
-<li>long running command can be executed in the background as threads or
-processes: just declare them in the lists <tt class="docutils literal">thcommands</tt> and <tt class="docutils literal">mpcommands</tt>
-respectively.</li>
-<li>the <tt class="docutils literal">.start_server</tt> method starts an asynchronous server on the
-given port number (default 2199)</li>
-</ol>
-<p>Moreover, remember that <tt class="docutils literal">plac_runner.py</tt> is your friend.</p>
-</div>
-<hr class="docutils" />
-<div class="section" id="appendix-custom-annotation-objects">
-<h1><a class="toc-backref" href="#id19">Appendix: custom annotation objects</a></h1>
-<p>Internally <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> uses an <tt class="docutils literal">Annotation</tt> class to convert the tuples
-in the function signature into annotation objects, i.e. objects with
-six attributes <tt class="docutils literal">help, kind, short, type, choices, metavar</tt>.</p>
-<p>Advanced users can implement their own annotation objects.
-For instance, here is an example of how you could implement annotations for
-positional arguments:</p>
-<pre class="literal-block">
-# annotations.py
-class Positional(object):
-    def __init__(self, help='', type=None, choices=None, metavar=None):
-        self.help = help
-        self.kind = 'positional'
-        self.abbrev = None
-        self.type = type
-        self.choices = choices
-        self.metavar = metavar
-
-</pre>
-<p>You can use such annotations objects as follows:</p>
-<pre class="literal-block">
-# example11.py
-import plac
-from annotations import Positional
-
-&#64;plac.annotations(
-    i=Positional(&quot;This is an int&quot;, int),
-    n=Positional(&quot;This is a float&quot;, float),
-    rest=Positional(&quot;Other arguments&quot;))
-def main(i, n, *rest):
-    print(i, n, rest)
-
-if __name__ == '__main__':
-    import plac; plac.call(main)
-
-</pre>
-<p>Here is the usage message you get:</p>
-<pre class="literal-block">
-usage: example11.py [-h] i n [rest [rest ...]]
-
-positional arguments:
-  i           This is an int
-  n           This is a float
-  rest        Other arguments
-
-optional arguments:
-  -h, --help  show this help message and exit
-
-</pre>
-<p>You can go on and define <tt class="docutils literal">Option</tt> and <tt class="docutils literal">Flag</tt> classes, if you like.
-Using custom annotation objects you could do advanced things like extracting the
-annotations from a configuration file or from a database, but I expect such
-use cases to be quite rare: the default mechanism should work
-pretty well for most users.</p>
-</div>
-</div>
-</body>
-</html>
diff --git a/plac/doc/plac_adv.pdf b/plac/doc/plac_adv.pdf
deleted file mode 100644
index 4661702..0000000
--- a/plac/doc/plac_adv.pdf
+++ /dev/null
@@ -1,6813 +0,0 @@
-%PDF-1.3
-%���� ReportLab Generated PDF document http://www.reportlab.com
-% 'BasicFonts': class PDFDictionary 
-1 0 obj
-% The standard fonts dictionary
-<< /F1 2 0 R
- /F2 3 0 R
- /F3 4 0 R
- /F4 8 0 R
- /F5 9 0 R >>
-endobj
-% 'F1': class PDFType1Font 
-2 0 obj
-% Font Helvetica
-<< /BaseFont /Helvetica
- /Encoding /WinAnsiEncoding
- /Name /F1
- /Subtype /Type1
- /Type /Font >>
-endobj
-% 'F2': class PDFType1Font 
-3 0 obj
-% Font Helvetica-Bold
-<< /BaseFont /Helvetica-Bold
- /Encoding /WinAnsiEncoding
- /Name /F2
- /Subtype /Type1
- /Type /Font >>
-endobj
-% 'F3': class PDFType1Font 
-4 0 obj
-% Font Times-Roman
-<< /BaseFont /Times-Roman
- /Encoding /WinAnsiEncoding
- /Name /F3
- /Subtype /Type1
- /Type /Font >>
-endobj
-% 'Annot.NUMBER1': class PDFDictionary 
-5 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (mailto:michele.simionato@gmail.com) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 153.7323
- 707.5936
- 526.5827
- 719.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER2': class PDFDictionary 
-6 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 153.7323
- 677.5936
- 526.5827
- 689.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER3': class PDFDictionary 
-7 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://micheles.googlecode.com/hg/plac/doc/plac.html) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 153.7323
- 650.5936
- 526.5827
- 662.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'F4': class PDFType1Font 
-8 0 obj
-% Font Courier
-<< /BaseFont /Courier
- /Encoding /WinAnsiEncoding
- /Name /F4
- /Subtype /Type1
- /Type /Font >>
-endobj
-% 'F5': class PDFType1Font 
-9 0 obj
-% Font Helvetica-Oblique
-<< /BaseFont /Helvetica-Oblique
- /Encoding /WinAnsiEncoding
- /Name /F5
- /Subtype /Type1
- /Type /Font >>
-endobj
-% 'Annot.NUMBER4': class LinkAnnotation 
-10 0 obj
-<< /Border [ 0
- 0
- 0 ]
- /Contents ()
- /Dest [ 50 0 R
- /XYZ
- 62.69291
- 164.0236
- 0 ]
- /Rect [ 62.69291
- 506.5936
- 121.0229
- 518.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER5': class LinkAnnotation 
-11 0 obj
-<< /Border [ 0
- 0
- 0 ]
- /Contents ()
- /Dest [ 50 0 R
- /XYZ
- 62.69291
- 164.0236
- 0 ]
- /Rect [ 527.0227
- 506.5936
- 532.5827
- 518.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER6': class LinkAnnotation 
-12 0 obj
-<< /Border [ 0
- 0
- 0 ]
- /Contents ()
- /Dest [ 60 0 R
- /XYZ
- 62.69291
- 609.0236
- 0 ]
- /Rect [ 62.69291
- 488.5936
- 249.4129
- 500.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER7': class LinkAnnotation 
-13 0 obj
-<< /Border [ 0
- 0
- 0 ]
- /Contents ()
- /Dest [ 60 0 R
- /XYZ
- 62.69291
- 609.0236
- 0 ]
- /Rect [ 527.0227
- 488.5936
- 532.5827
- 500.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER8': class LinkAnnotation 
-14 0 obj
-<< /Border [ 0
- 0
- 0 ]
- /Contents ()
- /Dest [ 62 0 R
- /XYZ
- 62.69291
- 151.4236
- 0 ]
- /Rect [ 62.69291
- 470.5936
- 184.9529
- 482.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER9': class LinkAnnotation 
-15 0 obj
-<< /Border [ 0
- 0
- 0 ]
- /Contents ()
- /Dest [ 62 0 R
- /XYZ
- 62.69291
- 151.4236
- 0 ]
- /Rect [ 527.0227
- 470.5936
- 532.5827
- 482.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER10': class LinkAnnotation 
-16 0 obj
-<< /Border [ 0
- 0
- 0 ]
- /Contents ()
- /Dest [ 74 0 R
- /XYZ
- 62.69291
- 765.0236
- 0 ]
- /Rect [ 62.69291
- 452.5936
- 134.4029
- 464.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER11': class LinkAnnotation 
-17 0 obj
-<< /Border [ 0
- 0
- 0 ]
- /Contents ()
- /Dest [ 74 0 R
- /XYZ
- 62.69291
- 765.0236
- 0 ]
- /Rect [ 527.0227
- 452.5936
- 532.5827
- 464.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER12': class LinkAnnotation 
-18 0 obj
-<< /Border [ 0
- 0
- 0 ]
- /Contents ()
- /Dest [ 77 0 R
- /XYZ
- 62.69291
- 461.8485
- 0 ]
- /Rect [ 62.69291
- 434.5936
- 148.2829
- 446.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER13': class LinkAnnotation 
-19 0 obj
-<< /Border [ 0
- 0
- 0 ]
- /Contents ()
- /Dest [ 77 0 R
- /XYZ
- 62.69291
- 461.8485
- 0 ]
- /Rect [ 527.0227
- 434.5936
- 532.5827
- 446.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER14': class LinkAnnotation 
-20 0 obj
-<< /Border [ 0
- 0
- 0 ]
- /Contents ()
- /Dest [ 82 0 R
- /XYZ
- 62.69291
- 539.8236
- 0 ]
- /Rect [ 62.69291
- 416.5936
- 201.0529
- 428.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER15': class LinkAnnotation 
-21 0 obj
-<< /Border [ 0
- 0
- 0 ]
- /Contents ()
- /Dest [ 82 0 R
- /XYZ
- 62.69291
- 539.8236
- 0 ]
- /Rect [ 527.0227
- 416.5936
- 532.5827
- 428.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER16': class LinkAnnotation 
-22 0 obj
-<< /Border [ 0
- 0
- 0 ]
- /Contents ()
- /Dest [ 87 0 R
- /XYZ
- 62.69291
- 460.0769
- 0 ]
- /Rect [ 62.69291
- 398.5936
- 154.9529
- 410.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER17': class LinkAnnotation 
-23 0 obj
-<< /Border [ 0
- 0
- 0 ]
- /Contents ()
- /Dest [ 87 0 R
- /XYZ
- 62.69291
- 460.0769
- 0 ]
- /Rect [ 527.0227
- 398.5936
- 532.5827
- 410.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER18': class LinkAnnotation 
-24 0 obj
-<< /Border [ 0
- 0
- 0 ]
- /Contents ()
- /Dest [ 95 0 R
- /XYZ
- 62.69291
- 765.0236
- 0 ]
- /Rect [ 62.69291
- 380.5936
- 144.3729
- 392.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER19': class LinkAnnotation 
-25 0 obj
-<< /Border [ 0
- 0
- 0 ]
- /Contents ()
- /Dest [ 95 0 R
- /XYZ
- 62.69291
- 765.0236
- 0 ]
- /Rect [ 521.4627
- 380.5936
- 532.5827
- 392.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER20': class LinkAnnotation 
-26 0 obj
-<< /Border [ 0
- 0
- 0 ]
- /Contents ()
- /Dest [ 106 0 R
- /XYZ
- 62.69291
- 240.6236
- 0 ]
- /Rect [ 62.69291
- 362.5936
- 137.7129
- 374.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER21': class LinkAnnotation 
-27 0 obj
-<< /Border [ 0
- 0
- 0 ]
- /Contents ()
- /Dest [ 106 0 R
- /XYZ
- 62.69291
- 240.6236
- 0 ]
- /Rect [ 521.4627
- 362.5936
- 532.5827
- 374.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER22': class LinkAnnotation 
-28 0 obj
-<< /Border [ 0
- 0
- 0 ]
- /Contents ()
- /Dest [ 110 0 R
- /XYZ
- 62.69291
- 371.4236
- 0 ]
- /Rect [ 62.69291
- 344.5936
- 193.8529
- 356.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER23': class LinkAnnotation 
-29 0 obj
-<< /Border [ 0
- 0
- 0 ]
- /Contents ()
- /Dest [ 110 0 R
- /XYZ
- 62.69291
- 371.4236
- 0 ]
- /Rect [ 521.4627
- 344.5936
- 532.5827
- 356.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER24': class LinkAnnotation 
-30 0 obj
-<< /Border [ 0
- 0
- 0 ]
- /Contents ()
- /Dest [ 113 0 R
- /XYZ
- 62.69291
- 384.6236
- 0 ]
- /Rect [ 62.69291
- 326.5936
- 201.6029
- 338.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER25': class LinkAnnotation 
-31 0 obj
-<< /Border [ 0
- 0
- 0 ]
- /Contents ()
- /Dest [ 113 0 R
- /XYZ
- 62.69291
- 384.6236
- 0 ]
- /Rect [ 521.4627
- 326.5936
- 532.5827
- 338.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER26': class LinkAnnotation 
-32 0 obj
-<< /Border [ 0
- 0
- 0 ]
- /Contents ()
- /Dest [ 117 0 R
- /XYZ
- 62.69291
- 211.4236
- 0 ]
- /Rect [ 62.69291
- 308.5936
- 182.7029
- 320.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER27': class LinkAnnotation 
-33 0 obj
-<< /Border [ 0
- 0
- 0 ]
- /Contents ()
- /Dest [ 117 0 R
- /XYZ
- 62.69291
- 211.4236
- 0 ]
- /Rect [ 521.4627
- 308.5936
- 532.5827
- 320.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER28': class LinkAnnotation 
-34 0 obj
-<< /Border [ 0
- 0
- 0 ]
- /Contents ()
- /Dest [ 120 0 R
- /XYZ
- 62.69291
- 318.6236
- 0 ]
- /Rect [ 62.69291
- 290.5936
- 163.2729
- 302.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER29': class LinkAnnotation 
-35 0 obj
-<< /Border [ 0
- 0
- 0 ]
- /Contents ()
- /Dest [ 120 0 R
- /XYZ
- 62.69291
- 318.6236
- 0 ]
- /Rect [ 521.4627
- 290.5936
- 532.5827
- 302.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER30': class LinkAnnotation 
-36 0 obj
-<< /Border [ 0
- 0
- 0 ]
- /Contents ()
- /Dest [ 124 0 R
- /XYZ
- 62.69291
- 475.8236
- 0 ]
- /Rect [ 62.69291
- 272.5936
- 266.0929
- 284.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER31': class LinkAnnotation 
-37 0 obj
-<< /Border [ 0
- 0
- 0 ]
- /Contents ()
- /Dest [ 124 0 R
- /XYZ
- 62.69291
- 475.8236
- 0 ]
- /Rect [ 521.4627
- 272.5936
- 532.5827
- 284.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER32': class LinkAnnotation 
-38 0 obj
-<< /Border [ 0
- 0
- 0 ]
- /Contents ()
- /Dest [ 126 0 R
- /XYZ
- 62.69291
- 675.0236
- 0 ]
- /Rect [ 62.69291
- 254.5936
- 283.8229
- 266.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER33': class LinkAnnotation 
-39 0 obj
-<< /Border [ 0
- 0
- 0 ]
- /Contents ()
- /Dest [ 126 0 R
- /XYZ
- 62.69291
- 675.0236
- 0 ]
- /Rect [ 521.4627
- 254.5936
- 532.5827
- 266.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER34': class LinkAnnotation 
-40 0 obj
-<< /Border [ 0
- 0
- 0 ]
- /Contents ()
- /Dest [ 128 0 R
- /XYZ
- 62.69291
- 765.0236
- 0 ]
- /Rect [ 62.69291
- 236.5936
- 197.7329
- 248.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER35': class LinkAnnotation 
-41 0 obj
-<< /Border [ 0
- 0
- 0 ]
- /Contents ()
- /Dest [ 128 0 R
- /XYZ
- 62.69291
- 765.0236
- 0 ]
- /Rect [ 521.4627
- 236.5936
- 532.5827
- 248.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER36': class LinkAnnotation 
-42 0 obj
-<< /Border [ 0
- 0
- 0 ]
- /Contents ()
- /Dest [ 132 0 R
- /XYZ
- 62.69291
- 729.0236
- 0 ]
- /Rect [ 62.69291
- 218.5936
- 136.0629
- 230.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER37': class LinkAnnotation 
-43 0 obj
-<< /Border [ 0
- 0
- 0 ]
- /Contents ()
- /Dest [ 132 0 R
- /XYZ
- 62.69291
- 729.0236
- 0 ]
- /Rect [ 521.4627
- 218.5936
- 532.5827
- 230.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER38': class LinkAnnotation 
-44 0 obj
-<< /Border [ 0
- 0
- 0 ]
- /Contents ()
- /Dest [ 132 0 R
- /XYZ
- 62.69291
- 255.6236
- 0 ]
- /Rect [ 62.69291
- 200.5936
- 108.2629
- 212.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER39': class LinkAnnotation 
-45 0 obj
-<< /Border [ 0
- 0
- 0 ]
- /Contents ()
- /Dest [ 132 0 R
- /XYZ
- 62.69291
- 255.6236
- 0 ]
- /Rect [ 521.4627
- 200.5936
- 532.5827
- 212.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER40': class LinkAnnotation 
-46 0 obj
-<< /Border [ 0
- 0
- 0 ]
- /Contents ()
- /Dest [ 134 0 R
- /XYZ
- 62.69291
- 586.6772
- 0 ]
- /Rect [ 62.69291
- 182.5936
- 241.6029
- 194.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER41': class LinkAnnotation 
-47 0 obj
-<< /Border [ 0
- 0
- 0 ]
- /Contents ()
- /Dest [ 134 0 R
- /XYZ
- 62.69291
- 586.6772
- 0 ]
- /Rect [ 521.4627
- 182.5936
- 532.5827
- 194.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER42': class PDFDictionary 
-48 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 185.4471
- 128.5936
- 207.1062
- 140.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER43': class PDFDictionary 
-49 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 177.6784
- 116.5936
- 199.6123
- 128.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Page1': class PDFPage 
-50 0 obj
-% Page dictionary
-<< /Annots [ 5 0 R
- 6 0 R
- 7 0 R
- 10 0 R
- 11 0 R
- 12 0 R
- 13 0 R
- 14 0 R
- 15 0 R
- 16 0 R
- 17 0 R
- 18 0 R
- 19 0 R
- 20 0 R
- 21 0 R
- 22 0 R
- 23 0 R
- 24 0 R
- 25 0 R
- 26 0 R
- 27 0 R
- 28 0 R
- 29 0 R
- 30 0 R
- 31 0 R
- 32 0 R
- 33 0 R
- 34 0 R
- 35 0 R
- 36 0 R
- 37 0 R
- 38 0 R
- 39 0 R
- 40 0 R
- 41 0 R
- 42 0 R
- 43 0 R
- 44 0 R
- 45 0 R
- 46 0 R
- 47 0 R
- 48 0 R
- 49 0 R ]
- /Contents 159 0 R
- /MediaBox [ 0
- 0
- 595.2756
- 841.8898 ]
- /Parent 158 0 R
- /Resources << /Font 1 0 R
- /ProcSet [ /PDF
- /Text
- /ImageB
- /ImageC
- /ImageI ] >>
- /Rotate 0
- /Trans <<  >>
- /Type /Page >>
-endobj
-% 'Annot.NUMBER44': class PDFDictionary 
-51 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 62.69291
- 732.5936
- 83.81291
- 744.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER45': class PDFDictionary 
-52 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 278.4678
- 714.5936
- 300.0328
- 726.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER46': class PDFDictionary 
-53 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 117.3573
- 702.5936
- 138.5845
- 714.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER47': class PDFDictionary 
-54 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://twill.idyll.org/) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 82.74466
- 660.5936
- 104.4564
- 672.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER48': class PDFDictionary 
-55 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 127.2882
- 660.5936
- 145.6282
- 672.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER49': class PDFDictionary 
-56 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 410.1674
- 660.5936
- 433.5592
- 672.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER50': class PDFDictionary 
-57 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 265.9578
- 636.5936
- 284.2978
- 648.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER51': class PDFDictionary 
-58 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 487.7492
- 636.5936
- 506.0892
- 648.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER52': class PDFDictionary 
-59 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://micheles.googlecode.com/hg/plac/doc/plac.html) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 62.69291
- 477.5936
- 157.1829
- 489.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Page2': class PDFPage 
-60 0 obj
-% Page dictionary
-<< /Annots [ 51 0 R
- 52 0 R
- 53 0 R
- 54 0 R
- 55 0 R
- 56 0 R
- 57 0 R
- 58 0 R
- 59 0 R ]
- /Contents 160 0 R
- /MediaBox [ 0
- 0
- 595.2756
- 841.8898 ]
- /Parent 158 0 R
- /Resources << /Font 1 0 R
- /ProcSet [ /PDF
- /Text
- /ImageB
- /ImageC
- /ImageI ] >>
- /Rotate 0
- /Trans <<  >>
- /Type /Page >>
-endobj
-% 'Annot.NUMBER53': class PDFDictionary 
-61 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 383.9329
- 196.9936
- 405.0529
- 208.9936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Page3': class PDFPage 
-62 0 obj
-% Page dictionary
-<< /Annots [ 61 0 R ]
- /Contents 161 0 R
- /MediaBox [ 0
- 0
- 595.2756
- 841.8898 ]
- /Parent 158 0 R
- /Resources << /Font 1 0 R
- /ProcSet [ /PDF
- /Text
- /ImageB
- /ImageC
- /ImageI ] >>
- /Rotate 0
- /Trans <<  >>
- /Type /Page >>
-endobj
-% 'Page4': class PDFPage 
-63 0 obj
-% Page dictionary
-<< /Contents 162 0 R
- /MediaBox [ 0
- 0
- 595.2756
- 841.8898 ]
- /Parent 158 0 R
- /Resources << /Font 1 0 R
- /ProcSet [ /PDF
- /Text
- /ImageB
- /ImageC
- /ImageI ] >>
- /Rotate 0
- /Trans <<  >>
- /Type /Page >>
-endobj
-% 'Annot.NUMBER54': class PDFDictionary 
-64 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 370.6785
- 466.3936
- 392.4956
- 478.3936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER55': class PDFDictionary 
-65 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 455.8742
- 466.3936
- 477.6913
- 478.3936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER56': class PDFDictionary 
-66 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 185.9351
- 251.6093
- 207.4695
- 263.6093 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER57': class PDFDictionary 
-67 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://docs.python.org/library/shlex.html) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 369.8905
- 251.6093
- 396.425
- 263.6093 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER58': class PDFDictionary 
-68 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 408.8916
- 239.6093
- 427.2316
- 251.6093 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER59': class PDFDictionary 
-69 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://docs.python.org/library/shlex.html) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 62.69291
- 227.6093
- 86.03291
- 239.6093 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER60': class PDFDictionary 
-70 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 92.4689
- 227.6093
- 114.4649
- 239.6093 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER61': class PDFDictionary 
-71 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://docs.python.org/library/shlex.html) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 149.3204
- 215.6093
- 176.9472
- 227.6093 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER62': class PDFDictionary 
-72 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 129.6923
- 119.6093
- 151.4655
- 131.6093 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER63': class PDFDictionary 
-73 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 173.8529
- 107.6093
- 194.9729
- 119.6093 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Page5': class PDFPage 
-74 0 obj
-% Page dictionary
-<< /Annots [ 64 0 R
- 65 0 R
- 66 0 R
- 67 0 R
- 68 0 R
- 69 0 R
- 70 0 R
- 71 0 R
- 72 0 R
- 73 0 R ]
- /Contents 163 0 R
- /MediaBox [ 0
- 0
- 595.2756
- 841.8898 ]
- /Parent 158 0 R
- /Resources << /Font 1 0 R
- /ProcSet [ /PDF
- /Text
- /ImageB
- /ImageC
- /ImageI ] >>
- /Rotate 0
- /Trans <<  >>
- /Type /Page >>
-endobj
-% 'Annot.NUMBER64': class PDFDictionary 
-75 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 460.388
- 414.4185
- 482.0127
- 426.4185 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER65': class PDFDictionary 
-76 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 95.32996
- 348.4185
- 116.857
- 360.4185 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Page6': class PDFPage 
-77 0 obj
-% Page dictionary
-<< /Annots [ 75 0 R
- 76 0 R ]
- /Contents 164 0 R
- /MediaBox [ 0
- 0
- 595.2756
- 841.8898 ]
- /Parent 158 0 R
- /Resources << /Font 1 0 R
- /ProcSet [ /PDF
- /Text
- /ImageB
- /ImageC
- /ImageI ] >>
- /Rotate 0
- /Trans <<  >>
- /Type /Page >>
-endobj
-% 'Annot.NUMBER66': class PDFDictionary 
-78 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://micheles.googlecode.com/hg/plac/doc/plac.html) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 316.3528
- 504.3936
- 409.2453
- 516.3936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER67': class PDFDictionary 
-79 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 419.1694
- 492.3936
- 440.4061
- 504.3936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER68': class PDFDictionary 
-80 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 62.69291
- 462.3936
- 84.70395
- 474.3936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER69': class PDFDictionary 
-81 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 293.2359
- 384.3936
- 316.4697
- 396.3936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Page7': class PDFPage 
-82 0 obj
-% Page dictionary
-<< /Annots [ 78 0 R
- 79 0 R
- 80 0 R
- 81 0 R ]
- /Contents 165 0 R
- /MediaBox [ 0
- 0
- 595.2756
- 841.8898 ]
- /Parent 158 0 R
- /Resources << /Font 1 0 R
- /ProcSet [ /PDF
- /Text
- /ImageB
- /ImageC
- /ImageI ] >>
- /Rotate 0
- /Trans <<  >>
- /Type /Page >>
-endobj
-% 'Annot.NUMBER70': class PDFDictionary 
-83 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 431.7904
- 399.3936
- 453.7245
- 411.3936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER71': class PDFDictionary 
-84 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 255.5885
- 369.3936
- 278.2757
- 381.3936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER72': class PDFDictionary 
-85 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://docs.python.org/library/cmd.html) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 513.6927
- 345.3936
- 532.1846
- 357.3936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Page8': class PDFPage 
-86 0 obj
-% Page dictionary
-<< /Annots [ 83 0 R
- 84 0 R
- 85 0 R ]
- /Contents 166 0 R
- /MediaBox [ 0
- 0
- 595.2756
- 841.8898 ]
- /Parent 158 0 R
- /Resources << /Font 1 0 R
- /ProcSet [ /PDF
- /Text
- /ImageB
- /ImageC
- /ImageI ] >>
- /Rotate 0
- /Trans <<  >>
- /Type /Page >>
-endobj
-% 'Page9': class PDFPage 
-87 0 obj
-% Page dictionary
-<< /Contents 167 0 R
- /MediaBox [ 0
- 0
- 595.2756
- 841.8898 ]
- /Parent 158 0 R
- /Resources << /Font 1 0 R
- /ProcSet [ /PDF
- /Text
- /ImageB
- /ImageC
- /ImageI ] >>
- /Rotate 0
- /Trans <<  >>
- /Type /Page >>
-endobj
-% 'Page10': class PDFPage 
-88 0 obj
-% Page dictionary
-<< /Contents 168 0 R
- /MediaBox [ 0
- 0
- 595.2756
- 841.8898 ]
- /Parent 158 0 R
- /Resources << /Font 1 0 R
- /ProcSet [ /PDF
- /Text
- /ImageB
- /ImageC
- /ImageI ] >>
- /Rotate 0
- /Trans <<  >>
- /Type /Page >>
-endobj
-% 'Annot.NUMBER73': class PDFDictionary 
-89 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 179.0529
- 729.5936
- 201.1953
- 741.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER74': class PDFDictionary 
-90 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://freshmeat.net/projects/rlwrap/) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 377.8504
- 149.6007
- 409.861
- 161.6007 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER75': class PDFDictionary 
-91 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 242.4466
- 137.6007
- 263.7922
- 149.6007 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER76': class PDFDictionary 
-92 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://ipython.scipy.org/moin/PyReadline/Intro) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 456.2271
- 137.6007
- 505.3627
- 149.6007 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER77': class PDFDictionary 
-93 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 363.1739
- 113.6007
- 386.5004
- 125.6007 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER78': class PDFDictionary 
-94 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 479.7508
- 101.6007
- 501.4627
- 113.6007 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Page11': class PDFPage 
-95 0 obj
-% Page dictionary
-<< /Annots [ 89 0 R
- 90 0 R
- 91 0 R
- 92 0 R
- 93 0 R
- 94 0 R ]
- /Contents 169 0 R
- /MediaBox [ 0
- 0
- 595.2756
- 841.8898 ]
- /Parent 158 0 R
- /Resources << /Font 1 0 R
- /ProcSet [ /PDF
- /Text
- /ImageB
- /ImageC
- /ImageI ] >>
- /Rotate 0
- /Trans <<  >>
- /Type /Page >>
-endobj
-% 'Annot.NUMBER79': class PDFDictionary 
-96 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://docs.python.org/library/cmd.html) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 366.9454
- 738.5936
- 388.8033
- 750.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER80': class PDFDictionary 
-97 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://docs.python.org/library/cmd.html) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 170.8855
- 726.5936
- 189.7755
- 738.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER81': class PDFDictionary 
-98 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://argparse.googlecode.com) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 390.8027
- 385.3936
- 435.0027
- 397.3936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER82': class PDFDictionary 
-99 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 213.451
- 373.3936
- 237.5255
- 385.3936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER83': class PDFDictionary 
-100 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://argparse.googlecode.com) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 114.9429
- 349.3936
- 157.1829
- 361.3936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER84': class PDFDictionary 
-101 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 385.0429
- 349.3936
- 403.3829
- 361.3936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER85': class PDFDictionary 
-102 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 350.6129
- 319.3936
- 371.7329
- 331.3936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER86': class PDFDictionary 
-103 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 256.6729
- 301.3936
- 277.7929
- 313.3936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER87': class PDFDictionary 
-104 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 149.5469
- 205.1936
- 172.1982
- 217.1936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER88': class PDFDictionary 
-105 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://docs.python.org/distutils/) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 224.3178
- 193.1936
- 260.8853
- 205.1936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Page12': class PDFPage 
-106 0 obj
-% Page dictionary
-<< /Annots [ 96 0 R
- 97 0 R
- 98 0 R
- 99 0 R
- 100 0 R
- 101 0 R
- 102 0 R
- 103 0 R
- 104 0 R
- 105 0 R ]
- /Contents 170 0 R
- /MediaBox [ 0
- 0
- 595.2756
- 841.8898 ]
- /Parent 158 0 R
- /Resources << /Font 1 0 R
- /ProcSet [ /PDF
- /Text
- /ImageB
- /ImageC
- /ImageI ] >>
- /Rotate 0
- /Trans <<  >>
- /Type /Page >>
-endobj
-% 'Page13': class PDFPage 
-107 0 obj
-% Page dictionary
-<< /Contents 171 0 R
- /MediaBox [ 0
- 0
- 595.2756
- 841.8898 ]
- /Parent 158 0 R
- /Resources << /Font 1 0 R
- /ProcSet [ /PDF
- /Text
- /ImageB
- /ImageC
- /ImageI ] >>
- /Rotate 0
- /Trans <<  >>
- /Type /Page >>
-endobj
-% 'Annot.NUMBER89': class PDFDictionary 
-108 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://argparse.googlecode.com) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 381.1529
- 744.5936
- 423.3929
- 756.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER90': class PDFDictionary 
-109 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 62.69291
- 335.9936
- 84.72012
- 347.9936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Page14': class PDFPage 
-110 0 obj
-% Page dictionary
-<< /Annots [ 108 0 R
- 109 0 R ]
- /Contents 172 0 R
- /MediaBox [ 0
- 0
- 595.2756
- 841.8898 ]
- /Parent 158 0 R
- /Resources << /Font 1 0 R
- /ProcSet [ /PDF
- /Text
- /ImageB
- /ImageC
- /ImageI ] >>
- /Rotate 0
- /Trans <<  >>
- /Type /Page >>
-endobj
-% 'Page15': class PDFPage 
-111 0 obj
-% Page dictionary
-<< /Contents 173 0 R
- /MediaBox [ 0
- 0
- 595.2756
- 841.8898 ]
- /Parent 158 0 R
- /Resources << /Font 1 0 R
- /ProcSet [ /PDF
- /Text
- /ImageB
- /ImageC
- /ImageI ] >>
- /Rotate 0
- /Trans <<  >>
- /Type /Page >>
-endobj
-% 'Annot.NUMBER91': class PDFDictionary 
-112 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 182.479
- 349.1936
- 203.7662
- 361.1936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Page16': class PDFPage 
-113 0 obj
-% Page dictionary
-<< /Annots [ 112 0 R ]
- /Contents 174 0 R
- /MediaBox [ 0
- 0
- 595.2756
- 841.8898 ]
- /Parent 158 0 R
- /Resources << /Font 1 0 R
- /ProcSet [ /PDF
- /Text
- /ImageB
- /ImageC
- /ImageI ] >>
- /Rotate 0
- /Trans <<  >>
- /Type /Page >>
-endobj
-% 'Annot.NUMBER92': class PDFDictionary 
-114 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 255.1228
- 382.1936
- 276.5028
- 394.1936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER93': class PDFDictionary 
-115 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://docs.python.org/library/multiprocessing.html) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 295.0229
- 226.9936
- 367.2629
- 238.9936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER94': class PDFDictionary 
-116 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 179.1295
- 175.9936
- 201.6839
- 187.9936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Page17': class PDFPage 
-117 0 obj
-% Page dictionary
-<< /Annots [ 114 0 R
- 115 0 R
- 116 0 R ]
- /Contents 175 0 R
- /MediaBox [ 0
- 0
- 595.2756
- 841.8898 ]
- /Parent 158 0 R
- /Resources << /Font 1 0 R
- /ProcSet [ /PDF
- /Text
- /ImageB
- /ImageC
- /ImageI ] >>
- /Rotate 0
- /Trans <<  >>
- /Type /Page >>
-endobj
-% 'Annot.NUMBER95': class PDFDictionary 
-118 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 414.8874
- 346.1936
- 436.9487
- 358.1936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER96': class PDFDictionary 
-119 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 122.7054
- 199.1936
- 145.2085
- 211.1936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Page18': class PDFPage 
-120 0 obj
-% Page dictionary
-<< /Annots [ 118 0 R
- 119 0 R ]
- /Contents 176 0 R
- /MediaBox [ 0
- 0
- 595.2756
- 841.8898 ]
- /Parent 158 0 R
- /Resources << /Font 1 0 R
- /ProcSet [ /PDF
- /Text
- /ImageB
- /ImageC
- /ImageI ] >>
- /Rotate 0
- /Trans <<  >>
- /Type /Page >>
-endobj
-% 'Page19': class PDFPage 
-121 0 obj
-% Page dictionary
-<< /Contents 177 0 R
- /MediaBox [ 0
- 0
- 595.2756
- 841.8898 ]
- /Parent 158 0 R
- /Resources << /Font 1 0 R
- /ProcSet [ /PDF
- /Text
- /ImageB
- /ImageC
- /ImageI ] >>
- /Rotate 0
- /Trans <<  >>
- /Type /Page >>
-endobj
-% 'Annot.NUMBER97': class PDFDictionary 
-122 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 183.3657
- 428.3936
- 207.8364
- 440.3936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER98': class PDFDictionary 
-123 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://docs.python.org/library/multiprocessing.html) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 254.9929
- 404.3936
- 327.2329
- 416.3936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Page20': class PDFPage 
-124 0 obj
-% Page dictionary
-<< /Annots [ 122 0 R
- 123 0 R ]
- /Contents 178 0 R
- /MediaBox [ 0
- 0
- 595.2756
- 841.8898 ]
- /Parent 158 0 R
- /Resources << /Font 1 0 R
- /ProcSet [ /PDF
- /Text
- /ImageB
- /ImageC
- /ImageI ] >>
- /Rotate 0
- /Trans <<  >>
- /Type /Page >>
-endobj
-% 'Annot.NUMBER99': class PDFDictionary 
-125 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 62.69291
- 639.5936
- 85.70846
- 651.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Page21': class PDFPage 
-126 0 obj
-% Page dictionary
-<< /Annots [ 125 0 R ]
- /Contents 179 0 R
- /MediaBox [ 0
- 0
- 595.2756
- 841.8898 ]
- /Parent 158 0 R
- /Resources << /Font 1 0 R
- /ProcSet [ /PDF
- /Text
- /ImageB
- /ImageC
- /ImageI ] >>
- /Rotate 0
- /Trans <<  >>
- /Type /Page >>
-endobj
-% 'Annot.NUMBER100': class PDFDictionary 
-127 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 62.69291
- 729.5936
- 84.98766
- 741.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Page22': class PDFPage 
-128 0 obj
-% Page dictionary
-<< /Annots [ 127 0 R ]
- /Contents 180 0 R
- /MediaBox [ 0
- 0
- 595.2756
- 841.8898 ]
- /Parent 158 0 R
- /Resources << /Font 1 0 R
- /ProcSet [ /PDF
- /Text
- /ImageB
- /ImageC
- /ImageI ] >>
- /Rotate 0
- /Trans <<  >>
- /Type /Page >>
-endobj
-% 'Page23': class PDFPage 
-129 0 obj
-% Page dictionary
-<< /Contents 181 0 R
- /MediaBox [ 0
- 0
- 595.2756
- 841.8898 ]
- /Parent 158 0 R
- /Resources << /Font 1 0 R
- /ProcSet [ /PDF
- /Text
- /ImageB
- /ImageC
- /ImageI ] >>
- /Rotate 0
- /Trans <<  >>
- /Type /Page >>
-endobj
-% 'Annot.NUMBER101': class PDFDictionary 
-130 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 172.4311
- 609.5936
- 194.7087
- 621.5936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Annot.NUMBER102': class PDFDictionary 
-131 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 91.57623
- 220.1936
- 114.8995
- 232.1936 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Page24': class PDFPage 
-132 0 obj
-% Page dictionary
-<< /Annots [ 130 0 R
- 131 0 R ]
- /Contents 182 0 R
- /MediaBox [ 0
- 0
- 595.2756
- 841.8898 ]
- /Parent 158 0 R
- /Resources << /Font 1 0 R
- /ProcSet [ /PDF
- /Text
- /ImageB
- /ImageC
- /ImageI ] >>
- /Rotate 0
- /Trans <<  >>
- /Type /Page >>
-endobj
-% 'Annot.NUMBER103': class PDFDictionary 
-133 0 obj
-<< /A << /S /URI
- /Type /Action
- /URI (http://pypi.python.org/pypi/plac) >>
- /Border [ 0
- 0
- 0 ]
- /Rect [ 106.6216
- 551.2472
- 128.3202
- 563.2472 ]
- /Subtype /Link
- /Type /Annot >>
-endobj
-% 'Page25': class PDFPage 
-134 0 obj
-% Page dictionary
-<< /Annots [ 133 0 R ]
- /Contents 183 0 R
- /MediaBox [ 0
- 0
- 595.2756
- 841.8898 ]
- /Parent 158 0 R
- /Resources << /Font 1 0 R
- /ProcSet [ /PDF
- /Text
- /ImageB
- /ImageC
- /ImageI ] >>
- /Rotate 0
- /Trans <<  >>
- /Type /Page >>
-endobj
-% 'Page26': class PDFPage 
-135 0 obj
-% Page dictionary
-<< /Contents 184 0 R
- /MediaBox [ 0
- 0
- 595.2756
- 841.8898 ]
- /Parent 158 0 R
- /Resources << /Font 1 0 R
- /ProcSet [ /PDF
- /Text
- /ImageB
- /ImageC
- /ImageI ] >>
- /Rotate 0
- /Trans <<  >>
- /Type /Page >>
-endobj
-% 'R136': class PDFCatalog 
-136 0 obj
-% Document Root
-<< /Outlines 138 0 R
- /PageLabels 185 0 R
- /PageMode /UseNone
- /Pages 158 0 R
- /Type /Catalog >>
-endobj
-% 'R137': class PDFInfo 
-137 0 obj
-<< /Author (Michele Simionato)
- /CreationDate (D:20100826065902-01'00')
- /Keywords ()
- /Producer (ReportLab http://www.reportlab.com)
- /Subject (\(unspecified\))
- /Title (Advanced usages of plac) >>
-endobj
-% 'R138': class PDFOutlines 
-138 0 obj
-<< /Count 19
- /First 139 0 R
- /Last 157 0 R
- /Type /Outlines >>
-endobj
-% 'Outline.0': class OutlineEntryObject 
-139 0 obj
-<< /Dest [ 50 0 R
- /XYZ
- 62.69291
- 164.0236
- 0 ]
- /Next 140 0 R
- /Parent 138 0 R
- /Title (Introduction) >>
-endobj
-% 'Outline.1': class OutlineEntryObject 
-140 0 obj
-<< /Dest [ 60 0 R
- /XYZ
- 62.69291
- 609.0236
- 0 ]
- /Next 141 0 R
- /Parent 138 0 R
- /Prev 139 0 R
- /Title (From scripts to interactive applications) >>
-endobj
-% 'Outline.2': class OutlineEntryObject 
-141 0 obj
-<< /Dest [ 62 0 R
- /XYZ
- 62.69291
- 151.4236
- 0 ]
- /Next 142 0 R
- /Parent 138 0 R
- /Prev 140 0 R
- /Title (Testing a plac application) >>
-endobj
-% 'Outline.3': class OutlineEntryObject 
-142 0 obj
-<< /Dest [ 74 0 R
- /XYZ
- 62.69291
- 765.0236
- 0 ]
- /Next 143 0 R
- /Parent 138 0 R
- /Prev 141 0 R
- /Title (Plac easy tests) >>
-endobj
-% 'Outline.4': class OutlineEntryObject 
-143 0 obj
-<< /Dest [ 77 0 R
- /XYZ
- 62.69291
- 461.8485
- 0 ]
- /Next 144 0 R
- /Parent 138 0 R
- /Prev 142 0 R
- /Title (Plac batch scripts) >>
-endobj
-% 'Outline.5': class OutlineEntryObject 
-144 0 obj
-<< /Dest [ 82 0 R
- /XYZ
- 62.69291
- 539.8236
- 0 ]
- /Next 145 0 R
- /Parent 138 0 R
- /Prev 143 0 R
- /Title (Implementing subcommands) >>
-endobj
-% 'Outline.6': class OutlineEntryObject 
-145 0 obj
-<< /Dest [ 87 0 R
- /XYZ
- 62.69291
- 460.0769
- 0 ]
- /Next 146 0 R
- /Parent 138 0 R
- /Prev 144 0 R
- /Title (plac.Interpreter.call) >>
-endobj
-% 'Outline.7': class OutlineEntryObject 
-146 0 obj
-<< /Dest [ 95 0 R
- /XYZ
- 62.69291
- 765.0236
- 0 ]
- /Next 147 0 R
- /Parent 138 0 R
- /Prev 145 0 R
- /Title (Readline support) >>
-endobj
-% 'Outline.8': class OutlineEntryObject 
-147 0 obj
-<< /Dest [ 106 0 R
- /XYZ
- 62.69291
- 240.6236
- 0 ]
- /Next 148 0 R
- /Parent 138 0 R
- /Prev 146 0 R
- /Title (The plac runner) >>
-endobj
-% 'Outline.9': class OutlineEntryObject 
-148 0 obj
-<< /Dest [ 110 0 R
- /XYZ
- 62.69291
- 371.4236
- 0 ]
- /Next 149 0 R
- /Parent 138 0 R
- /Prev 147 0 R
- /Title (A non class-based example) >>
-endobj
-% 'Outline.10': class OutlineEntryObject 
-149 0 obj
-<< /Dest [ 113 0 R
- /XYZ
- 62.69291
- 384.6236
- 0 ]
- /Next 150 0 R
- /Parent 138 0 R
- /Prev 148 0 R
- /Title (Writing your own plac runner) >>
-endobj
-% 'Outline.11': class OutlineEntryObject 
-150 0 obj
-<< /Dest [ 117 0 R
- /XYZ
- 62.69291
- 211.4236
- 0 ]
- /Next 151 0 R
- /Parent 138 0 R
- /Prev 149 0 R
- /Title (Long running commands) >>
-endobj
-% 'Outline.12': class OutlineEntryObject 
-151 0 obj
-<< /Dest [ 120 0 R
- /XYZ
- 62.69291
- 318.6236
- 0 ]
- /Next 152 0 R
- /Parent 138 0 R
- /Prev 150 0 R
- /Title (Threaded commands) >>
-endobj
-% 'Outline.13': class OutlineEntryObject 
-152 0 obj
-<< /Dest [ 124 0 R
- /XYZ
- 62.69291
- 475.8236
- 0 ]
- /Next 153 0 R
- /Parent 138 0 R
- /Prev 151 0 R
- /Title (Running commands as external processes) >>
-endobj
-% 'Outline.14': class OutlineEntryObject 
-153 0 obj
-<< /Dest [ 126 0 R
- /XYZ
- 62.69291
- 675.0236
- 0 ]
- /Next 154 0 R
- /Parent 138 0 R
- /Prev 152 0 R
- /Title (Managing the output of concurrent commands) >>
-endobj
-% 'Outline.15': class OutlineEntryObject 
-154 0 obj
-<< /Dest [ 128 0 R
- /XYZ
- 62.69291
- 765.0236
- 0 ]
- /Next 155 0 R
- /Parent 138 0 R
- /Prev 153 0 R
- /Title (Parallel computing with plac) >>
-endobj
-% 'Outline.16': class OutlineEntryObject 
-155 0 obj
-<< /Dest [ 132 0 R
- /XYZ
- 62.69291
- 729.0236
- 0 ]
- /Next 156 0 R
- /Parent 138 0 R
- /Prev 154 0 R
- /Title (The plac server) >>
-endobj
-% 'Outline.17': class OutlineEntryObject 
-156 0 obj
-<< /Dest [ 132 0 R
- /XYZ
- 62.69291
- 255.6236
- 0 ]
- /Next 157 0 R
- /Parent 138 0 R
- /Prev 155 0 R
- /Title (Summary) >>
-endobj
-% 'Outline.18': class OutlineEntryObject 
-157 0 obj
-<< /Dest [ 134 0 R
- /XYZ
- 62.69291
- 586.6772
- 0 ]
- /Parent 138 0 R
- /Prev 156 0 R
- /Title (Appendix: custom annotation objects) >>
-endobj
-% 'R158': class PDFPages 
-158 0 obj
-% page tree
-<< /Count 26
- /Kids [ 50 0 R
- 60 0 R
- 62 0 R
- 63 0 R
- 74 0 R
- 77 0 R
- 82 0 R
- 86 0 R
- 87 0 R
- 88 0 R
- 95 0 R
- 106 0 R
- 107 0 R
- 110 0 R
- 111 0 R
- 113 0 R
- 117 0 R
- 120 0 R
- 121 0 R
- 124 0 R
- 126 0 R
- 128 0 R
- 129 0 R
- 132 0 R
- 134 0 R
- 135 0 R ]
- /Type /Pages >>
-endobj
-% 'R159': class PDFStream 
-159 0 obj
-% page stream
-<< /Length 9186 >>
-stream
-1 0 0 1 0 0 cm BT /F1 12 Tf 14.4 TL ET
-q
-1 0 0 1 62.69291 741.0236 cm
-q
-BT 1 0 0 1 0 9.64 Tm 114.9049 0 Td 24 TL /F2 20 Tf 0 0 0 rg (Advanced usages of plac) Tj T* -114.9049 0 Td ET
-Q
-Q
-q
-1 0 0 1 62.69291 716.0236 cm
-0 0 0 rg
-BT /F3 10 Tf 12 TL ET
-q
-1 0 0 1 6 3 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F2 10 Tf 12 TL 36.93937 0 Td (Author:) Tj T* -36.93937 0 Td ET
-Q
-Q
-q
-1 0 0 1 91.03937 3 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL (Michele Simionato) Tj T* ET
-Q
-Q
-q
-Q
-Q
-q
-1 0 0 1 62.69291 701.0236 cm
-0 0 0 rg
-BT /F3 10 Tf 12 TL ET
-q
-1 0 0 1 6 3 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F2 10 Tf 12 TL 39.69937 0 Td (E-mail:) Tj T* -39.69937 0 Td ET
-Q
-Q
-q
-1 0 0 1 91.03937 3 cm
-q
-0 0 .501961 rg
-0 0 .501961 RG
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL (michele.simionato@gmail.com) Tj T* ET
-Q
-Q
-q
-Q
-Q
-q
-1 0 0 1 62.69291 686.0236 cm
-0 0 0 rg
-BT /F3 10 Tf 12 TL ET
-q
-1 0 0 1 6 3 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F2 10 Tf 12 TL 48.03937 0 Td (Date:) Tj T* -48.03937 0 Td ET
-Q
-Q
-q
-1 0 0 1 91.03937 3 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL (August 2010) Tj T* ET
-Q
-Q
-q
-Q
-Q
-q
-1 0 0 1 62.69291 659.0236 cm
-0 0 0 rg
-BT /F3 10 Tf 12 TL ET
-q
-1 0 0 1 6 3 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 16.82 Tm /F2 10 Tf 12 TL 25.25937 0 Td (Download) Tj T* 21.11 0 Td (page:) Tj T* -46.36937 0 Td ET
-Q
-Q
-q
-1 0 0 1 91.03937 15 cm
-q
-0 0 .501961 rg
-0 0 .501961 RG
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL (http://pypi.python.org/pypi/plac) Tj T* ET
-Q
-Q
-q
-Q
-Q
-q
-1 0 0 1 62.69291 644.0236 cm
-0 0 0 rg
-BT /F3 10 Tf 12 TL ET
-q
-1 0 0 1 6 3 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F2 10 Tf 12 TL 9.68937 0 Td (Project page:) Tj T* -9.68937 0 Td ET
-Q
-Q
-q
-1 0 0 1 91.03937 3 cm
-q
-0 0 .501961 rg
-0 0 .501961 RG
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL (http://micheles.googlecode.com/hg/plac/doc/plac.html) Tj T* ET
-Q
-Q
-q
-Q
-Q
-q
-1 0 0 1 62.69291 629.0236 cm
-0 0 0 rg
-BT /F3 10 Tf 12 TL ET
-q
-1 0 0 1 6 3 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F2 10 Tf 12 TL 16.91937 0 Td (Installation:) Tj T* -16.91937 0 Td ET
-Q
-Q
-q
-1 0 0 1 91.03937 3 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 5.71 Tm /F4 10 Tf 12 TL (easy_install -U plac) Tj T* ET
-Q
-Q
-q
-Q
-Q
-q
-1 0 0 1 62.69291 614.0236 cm
-0 0 0 rg
-BT /F3 10 Tf 12 TL ET
-q
-1 0 0 1 6 3 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F2 10 Tf 12 TL 32.46937 0 Td (License:) Tj T* -32.46937 0 Td ET
-Q
-Q
-q
-1 0 0 1 91.03937 3 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL (BSD license) Tj T* ET
-Q
-Q
-q
-Q
-Q
-q
-1 0 0 1 62.69291 599.0236 cm
-0 0 0 rg
-BT /F3 10 Tf 12 TL ET
-q
-1 0 0 1 6 3 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F2 10 Tf 12 TL 26.91937 0 Td (Requires:) Tj T* -26.91937 0 Td ET
-Q
-Q
-q
-1 0 0 1 91.03937 3 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL (Python 2.5+) Tj T* ET
-Q
-Q
-q
-Q
-Q
-q
-1 0 0 1 62.69291 557.0236 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 28.82 Tm /F5 10 Tf 12 TL 2.399986 Tw (The present document discusses a few of the advanced use cases for plac. It shows how to write) Tj T* 0 Tw 2.164651 Tw (interactive and non-interactive interpreters with plac, and how to use plac for testing and scripting a) Tj T* 0 Tw (generic application. It assumes you have already read an understood the basic documentation.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 524.0236 cm
-q
-BT 1 0 0 1 0 8.435 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (Contents) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 176.0236 cm
-0 0 0 rg
-BT /F3 10 Tf 12 TL ET
-q
-1 0 0 1 0 327 cm
-q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F2 10 Tf 0 0 .501961 rg (Introduction) Tj T* ET
-Q
-Q
-q
-1 0 0 1 397.8898 327 cm
-q
-0 0 .501961 rg
-0 0 .501961 RG
-BT 1 0 0 1 0 4.82 Tm /F2 10 Tf 12 TL 66.44 0 Td (1) Tj T* -66.44 0 Td ET
-Q
-Q
-q
-1 0 0 1 0 309 cm
-q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F2 10 Tf 0 0 .501961 rg (From scripts to interactive applications) Tj T* ET
-Q
-Q
-q
-1 0 0 1 397.8898 309 cm
-q
-0 0 .501961 rg
-0 0 .501961 RG
-BT 1 0 0 1 0 4.82 Tm /F2 10 Tf 12 TL 66.44 0 Td (2) Tj T* -66.44 0 Td ET
-Q
-Q
-q
-1 0 0 1 0 291 cm
-q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F2 10 Tf 0 0 .501961 rg (Testing a plac application) Tj T* ET
-Q
-Q
-q
-1 0 0 1 397.8898 291 cm
-q
-0 0 .501961 rg
-0 0 .501961 RG
-BT 1 0 0 1 0 4.82 Tm /F2 10 Tf 12 TL 66.44 0 Td (3) Tj T* -66.44 0 Td ET
-Q
-Q
-q
-1 0 0 1 0 273 cm
-q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F2 10 Tf 0 0 .501961 rg (Plac easy tests) Tj T* ET
-Q
-Q
-q
-1 0 0 1 397.8898 273 cm
-q
-0 0 .501961 rg
-0 0 .501961 RG
-BT 1 0 0 1 0 4.82 Tm /F2 10 Tf 12 TL 66.44 0 Td (5) Tj T* -66.44 0 Td ET
-Q
-Q
-q
-1 0 0 1 0 255 cm
-q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F2 10 Tf 0 0 .501961 rg (Plac batch scripts) Tj T* ET
-Q
-Q
-q
-1 0 0 1 397.8898 255 cm
-q
-0 0 .501961 rg
-0 0 .501961 RG
-BT 1 0 0 1 0 4.82 Tm /F2 10 Tf 12 TL 66.44 0 Td (6) Tj T* -66.44 0 Td ET
-Q
-Q
-q
-1 0 0 1 0 237 cm
-q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F2 10 Tf 0 0 .501961 rg (Implementing subcommands) Tj T* ET
-Q
-Q
-q
-1 0 0 1 397.8898 237 cm
-q
-0 0 .501961 rg
-0 0 .501961 RG
-BT 1 0 0 1 0 4.82 Tm /F2 10 Tf 12 TL 66.44 0 Td (7) Tj T* -66.44 0 Td ET
-Q
-Q
-q
-1 0 0 1 0 219 cm
-q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F2 10 Tf 0 0 .501961 rg (plac.Interpreter.call) Tj T* ET
-Q
-Q
-q
-1 0 0 1 397.8898 219 cm
-q
-0 0 .501961 rg
-0 0 .501961 RG
-BT 1 0 0 1 0 4.82 Tm /F2 10 Tf 12 TL 66.44 0 Td (9) Tj T* -66.44 0 Td ET
-Q
-Q
-q
-1 0 0 1 0 201 cm
-q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F2 10 Tf 0 0 .501961 rg (Readline support) Tj T* ET
-Q
-Q
-q
-1 0 0 1 397.8898 201 cm
-q
-0 0 .501961 rg
-0 0 .501961 RG
-BT 1 0 0 1 0 4.82 Tm /F2 10 Tf 12 TL 60.88 0 Td (11) Tj T* -60.88 0 Td ET
-Q
-Q
-q
-1 0 0 1 0 183 cm
-q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F2 10 Tf 0 0 .501961 rg (The plac runner) Tj T* ET
-Q
-Q
-q
-1 0 0 1 397.8898 183 cm
-q
-0 0 .501961 rg
-0 0 .501961 RG
-BT 1 0 0 1 0 4.82 Tm /F2 10 Tf 12 TL 60.88 0 Td (12) Tj T* -60.88 0 Td ET
-Q
-Q
-q
-1 0 0 1 0 165 cm
-q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F2 10 Tf 0 0 .501961 rg (A non class-based example) Tj T* ET
-Q
-Q
-q
-1 0 0 1 397.8898 165 cm
-q
-0 0 .501961 rg
-0 0 .501961 RG
-BT 1 0 0 1 0 4.82 Tm /F2 10 Tf 12 TL 60.88 0 Td (14) Tj T* -60.88 0 Td ET
-Q
-Q
-q
-1 0 0 1 0 147 cm
-q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F2 10 Tf 0 0 .501961 rg (Writing your own plac runner) Tj T* ET
-Q
-Q
-q
-1 0 0 1 397.8898 147 cm
-q
-0 0 .501961 rg
-0 0 .501961 RG
-BT 1 0 0 1 0 4.82 Tm /F2 10 Tf 12 TL 60.88 0 Td (16) Tj T* -60.88 0 Td ET
-Q
-Q
-q
-1 0 0 1 0 129 cm
-q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F2 10 Tf 0 0 .501961 rg (Long running commands) Tj T* ET
-Q
-Q
-q
-1 0 0 1 397.8898 129 cm
-q
-0 0 .501961 rg
-0 0 .501961 RG
-BT 1 0 0 1 0 4.82 Tm /F2 10 Tf 12 TL 60.88 0 Td (17) Tj T* -60.88 0 Td ET
-Q
-Q
-q
-1 0 0 1 0 111 cm
-q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F2 10 Tf 0 0 .501961 rg (Threaded commands) Tj T* ET
-Q
-Q
-q
-1 0 0 1 397.8898 111 cm
-q
-0 0 .501961 rg
-0 0 .501961 RG
-BT 1 0 0 1 0 4.82 Tm /F2 10 Tf 12 TL 60.88 0 Td (18) Tj T* -60.88 0 Td ET
-Q
-Q
-q
-1 0 0 1 0 93 cm
-q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F2 10 Tf 0 0 .501961 rg (Running commands as external processes) Tj T* ET
-Q
-Q
-q
-1 0 0 1 397.8898 93 cm
-q
-0 0 .501961 rg
-0 0 .501961 RG
-BT 1 0 0 1 0 4.82 Tm /F2 10 Tf 12 TL 60.88 0 Td (20) Tj T* -60.88 0 Td ET
-Q
-Q
-q
-1 0 0 1 0 75 cm
-q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F2 10 Tf 0 0 .501961 rg (Managing the output of concurrent commands) Tj T* ET
-Q
-Q
-q
-1 0 0 1 397.8898 75 cm
-q
-0 0 .501961 rg
-0 0 .501961 RG
-BT 1 0 0 1 0 4.82 Tm /F2 10 Tf 12 TL 60.88 0 Td (21) Tj T* -60.88 0 Td ET
-Q
-Q
-q
-1 0 0 1 0 57 cm
-q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F2 10 Tf 0 0 .501961 rg (Parallel computing with plac) Tj T* ET
-Q
-Q
-q
-1 0 0 1 397.8898 57 cm
-q
-0 0 .501961 rg
-0 0 .501961 RG
-BT 1 0 0 1 0 4.82 Tm /F2 10 Tf 12 TL 60.88 0 Td (22) Tj T* -60.88 0 Td ET
-Q
-Q
-q
-1 0 0 1 0 39 cm
-q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F2 10 Tf 0 0 .501961 rg (The plac server) Tj T* ET
-Q
-Q
-q
-1 0 0 1 397.8898 39 cm
-q
-0 0 .501961 rg
-0 0 .501961 RG
-BT 1 0 0 1 0 4.82 Tm /F2 10 Tf 12 TL 60.88 0 Td (24) Tj T* -60.88 0 Td ET
-Q
-Q
-q
-1 0 0 1 0 21 cm
-q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F2 10 Tf 0 0 .501961 rg (Summary) Tj T* ET
-Q
-Q
-q
-1 0 0 1 397.8898 21 cm
-q
-0 0 .501961 rg
-0 0 .501961 RG
-BT 1 0 0 1 0 4.82 Tm /F2 10 Tf 12 TL 60.88 0 Td (24) Tj T* -60.88 0 Td ET
-Q
-Q
-q
-1 0 0 1 0 3 cm
-q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F2 10 Tf 0 0 .501961 rg (Appendix: custom annotation objects) Tj T* ET
-Q
-Q
-q
-1 0 0 1 397.8898 3 cm
-q
-0 0 .501961 rg
-0 0 .501961 RG
-BT 1 0 0 1 0 4.82 Tm /F2 10 Tf 12 TL 60.88 0 Td (25) Tj T* -60.88 0 Td ET
-Q
-Q
-q
-Q
-Q
-q
-1 0 0 1 62.69291 143.0236 cm
-q
-BT 1 0 0 1 0 8.435 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (Introduction) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 101.0236 cm
-q
-BT 1 0 0 1 0 28.82 Tm .539036 Tw 12 TL /F1 10 Tf 0 0 0 rg (One of the design goals of ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (is to make it dead easy to write a scriptable and testable interface for an) Tj T* 0 Tw .813876 Tw (application. You can use ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (whenever you have an API with strings in input and strings in output, and) Tj T* 0 Tw (that includes a ) Tj /F5 10 Tf (huge ) Tj /F1 10 Tf (domain of applications.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 56.69291 56.69291 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 238.1649 0 Td (1) Tj T* -238.1649 0 Td ET
-Q
-Q
- 
-endstream
-
-endobj
-% 'R160': class PDFStream 
-160 0 obj
-% page stream
-<< /Length 5450 >>
-stream
-1 0 0 1 0 0 cm BT /F1 12 Tf 14.4 TL ET
-q
-1 0 0 1 62.69291 729.0236 cm
-q
-BT 1 0 0 1 0 28.82 Tm 1.756651 Tw 12 TL /F1 10 Tf 0 0 0 rg (A string-oriented interface is a scriptable interface by construction. That means that you can define a) Tj T* 0 Tw .918735 Tw (command language for your application and that it is possible to write scripts which are interpretable by) Tj T* 0 Tw 0 0 .501961 rg (plac ) Tj 0 0 0 rg (and can be run as batch scripts.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 687.0236 cm
-q
-BT 1 0 0 1 0 28.82 Tm .444987 Tw 12 TL /F1 10 Tf 0 0 0 rg (Actually, at the most general level, you can see ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (as a generic tool to write domain specific languages) Tj T* 0 Tw .107209 Tw (\(DSL\). With ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (you can test your application interactively as well as with batch scripts, and even with the) Tj T* 0 Tw (analogous of Python doctests for your defined language.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 621.0236 cm
-q
-BT 1 0 0 1 0 52.82 Tm .694104 Tw 12 TL /F1 10 Tf 0 0 0 rg (You can easily replace the ) Tj /F4 10 Tf (cmd ) Tj /F1 10 Tf (module of the standard library and you could easily write an application) Tj T* 0 Tw 2.271751 Tw (like ) Tj 0 0 .501961 rg (twill ) Tj 0 0 0 rg (with ) Tj 0 0 .501961 rg (plac) Tj 0 0 0 rg (. Or you could use it to script your building procedure. ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (also supports parallel) Tj T* 0 Tw .907765 Tw (execution of multiple commands and can be used as task manager and monitor. It is also quite easy to) Tj T* 0 Tw 1.483488 Tw (build a GUI or a Web application on top of ) Tj 0 0 .501961 rg (plac) Tj 0 0 0 rg (. When speaking of things you can do with ) Tj 0 0 .501961 rg (plac) Tj 0 0 0 rg (, your) Tj T* 0 Tw (imagination is the only limit!) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 588.0236 cm
-q
-BT 1 0 0 1 0 8.435 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (From scripts to interactive applications) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 534.0236 cm
-q
-BT 1 0 0 1 0 40.82 Tm 1.300751 Tw 12 TL /F1 10 Tf 0 0 0 rg (Command-line scripts have many advantages, but they are no substitute for interactive applications. In) Tj T* 0 Tw .088171 Tw (particular, if you have a script with a large startup time which must be run multiple times, it is best to turn it) Tj T* 0 Tw 4.582126 Tw (into an interactive application, so that the startup is performed only once. ) Tj /F4 10 Tf (plac ) Tj /F1 10 Tf (provides an) Tj T* 0 Tw /F4 10 Tf (Interpreter ) Tj /F1 10 Tf (class just for this purpose.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 504.0236 cm
-q
-BT 1 0 0 1 0 16.82 Tm 1.293984 Tw 12 TL /F1 10 Tf 0 0 0 rg (The ) Tj /F4 10 Tf (Interpreter ) Tj /F1 10 Tf (class wraps the main function of a script and provides an ) Tj /F4 10 Tf (.interact ) Tj /F1 10 Tf (method to) Tj T* 0 Tw (start an interactive interpreter reading commands from the console.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 474.0236 cm
-q
-BT 1 0 0 1 0 16.82 Tm 1.49436 Tw 12 TL /F1 10 Tf 0 0 0 rg (For instance, you can define an interactive interpreter on top of the ) Tj /F4 10 Tf (ishelve ) Tj /F1 10 Tf (script introduced in the) Tj T* 0 Tw 0 0 .501961 rg (basic documentation ) Tj 0 0 0 rg (as follows:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 224.8236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 240 re B*
-Q
-q
-0 0 0 rg
-BT 1 0 0 1 0 221.71 Tm /F4 10 Tf 12 TL (# shelve_interpreter.py) Tj T* (import plac, ishelve) Tj T*  T* (@plac.annotations\() Tj T* (    interactive=\('start interactive interface', 'flag'\),) Tj T* (    subcommands='the commands of the underlying ishelve interpreter'\)) Tj T* (def main\(interactive, *subcommands\):) Tj T* (    """) Tj T* (    This script works both interactively and non-interactively.) Tj T* (    Use .help to see the internal commands.) Tj T* (    """) Tj T* (    if interactive:) Tj T* (        plac.Interpreter\(ishelve.main\).interact\(\)) Tj T* (    else:) Tj T* (        for out in plac.call\(ishelve.main, subcommands\):) Tj T* (            print\(out\)) Tj T*  T* (if __name__ == '__main__':) Tj T* (    plac.call\(main\)) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 180.8236 cm
-q
-BT 1 0 0 1 0 28.82 Tm 2.200651 Tw 12 TL /F1 10 Tf 0 0 0 rg (A trick has been used here: the ishelve command-line interface has been hidden inside an external) Tj T* 0 Tw .917674 Tw (interface. They are distinct: for instance the external interface recognizes the ) Tj /F4 10 Tf (-h/--help ) Tj /F1 10 Tf (flag whereas) Tj T* 0 Tw (the internal interface only recognizes the ) Tj /F4 10 Tf (.help ) Tj /F1 10 Tf (command:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 147.6236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 24 re B*
-Q
-q
-0 0 0 rg
-BT 1 0 0 1 0 5.71 Tm /F4 10 Tf 12 TL ($ python shelve_interpreter.py -h) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 90.42362 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 48 re B*
-Q
-q
-0 0 0 rg
-BT 1 0 0 1 0 29.71 Tm /F4 10 Tf 12 TL (usage: shelve_interpreter.py [-h] [-interactive]) Tj T* (                             [subcommands [subcommands ...]]) Tj T*  T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 56.69291 56.69291 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 238.1649 0 Td (2) Tj T* -238.1649 0 Td ET
-Q
-Q
- 
-endstream
-
-endobj
-% 'R161': class PDFStream 
-161 0 obj
-% page stream
-<< /Length 4041 >>
-stream
-1 0 0 1 0 0 cm BT /F1 12 Tf 14.4 TL ET
-q
-1 0 0 1 62.69291 631.8236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 132 re B*
-Q
-q
-0 0 0 rg
-BT 1 0 0 1 0 113.71 Tm /F4 10 Tf 12 TL (    This script works both interactively and non-interactively.) Tj T* (    Use .help to see the internal commands.) Tj T* (    ) Tj T*  T* (positional arguments:) Tj T* (  subcommands   the commands of the underlying ishelve interpreter) Tj T*  T* (optional arguments:) Tj T* (  -h, --help    show this help message and exit) Tj T* (  -interactive  start interactive interface) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 611.8236 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL (Thanks to this ingenuous trick, the script can be run both interactively and non-interactively:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 566.6236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 36 re B*
-Q
-q
-0 0 0 rg
-BT 1 0 0 1 0 17.71 Tm /F4 10 Tf 12 TL ($ python shelve_interpreter.py .clear # non-interactive use) Tj T* (cleared the shelve) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 546.6236 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL (Here is an usage session:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 261.4236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 276 re B*
-Q
-q
-BT 1 0 0 1 0 257.71 Tm 12 TL /F4 10 Tf 0 0 0 rg ($ python shelve_interpreter.py -i # interactive use) Tj T* (A simple interface to a shelve. Use .help to see the available commands.) Tj T* (i) Tj (>) Tj ( .help) Tj T* (Commands: .help, .showall, .clear, .delete) Tj T* (<) Tj (param) Tj (>) Tj ( ...) Tj T* (<) Tj (param=value) Tj (>) Tj ( ...) Tj T* (i) Tj (>) Tj ( a=1) Tj T* (setting a=1) Tj T* (i) Tj (>) Tj ( a) Tj T* (1) Tj T* (i) Tj (>) Tj ( b=2) Tj T* (setting b=2) Tj T* (i) Tj (>) Tj ( a b) Tj T* (1) Tj T* (2) Tj T* (i) Tj (>) Tj ( .del a) Tj T* (deleted a) Tj T* (i) Tj (>) Tj ( a) Tj T* (a: not found) Tj T* (i) Tj (>) Tj ( .show) Tj T* (b=2) Tj T* (i) Tj (>) Tj ( [CTRL-D]) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 193.4236 cm
-q
-BT 1 0 0 1 0 52.82 Tm .256412 Tw 12 TL /F1 10 Tf 0 0 0 rg (The ) Tj /F4 10 Tf (.interact ) Tj /F1 10 Tf (method reads commands from the console and send them to the underlying interpreter,) Tj T* 0 Tw .065984 Tw (until the user send a CTRL-D command \(CTRL-Z in Windows\). There is a default argument ) Tj /F4 10 Tf (prompt='i) Tj (>) Tj T* 0 Tw .41832 Tw (' ) Tj /F1 10 Tf (which can be used to change the prompt. The text displayed at the beginning of the interactive session) Tj T* 0 Tw 1.407126 Tw (is the docstring of the main function. ) Tj /F4 10 Tf (plac ) Tj /F1 10 Tf (also understands command abbreviations: in this example) Tj T* 0 Tw /F4 10 Tf (del ) Tj /F1 10 Tf (is an abbreviation for ) Tj /F4 10 Tf (delete) Tj /F1 10 Tf (. In case of ambiguous abbreviations ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (raises a ) Tj /F4 10 Tf (NameError) Tj /F1 10 Tf (.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 163.4236 cm
-q
-BT 1 0 0 1 0 16.82 Tm .847045 Tw 12 TL /F1 10 Tf 0 0 0 rg (Finally I must notice that the ) Tj /F4 10 Tf (plac.Interpreter ) Tj /F1 10 Tf (is available only if you are using a recent version of) Tj T* 0 Tw (Python \() Tj (>) Tj (= 2.5\), because it is a context manager object which uses extended generators internally.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 130.4236 cm
-q
-BT 1 0 0 1 0 8.435 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (Testing a plac application) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 100.4236 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 16.82 Tm /F1 10 Tf 12 TL 3.034269 Tw (You can conveniently test your application in interactive mode. However manual testing is a poor) Tj T* 0 Tw (substitute for automatic testing.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 56.69291 56.69291 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 238.1649 0 Td (3) Tj T* -238.1649 0 Td ET
-Q
-Q
- 
-endstream
-
-endobj
-% 'R162': class PDFStream 
-162 0 obj
-% page stream
-<< /Length 5561 >>
-stream
-1 0 0 1 0 0 cm BT /F1 12 Tf 14.4 TL ET
-q
-1 0 0 1 62.69291 753.0236 cm
-q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (In principle, one could write automatic tests for the ) Tj /F4 10 Tf (ishelve ) Tj /F1 10 Tf (application by using ) Tj /F4 10 Tf (plac.call ) Tj /F1 10 Tf (directly:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 587.8236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 156 re B*
-Q
-q
-0 0 0 rg
-BT 1 0 0 1 0 137.71 Tm /F4 10 Tf 12 TL (# test_ishelve.py) Tj T* (import plac, ishelve) Tj T*  T* (def test\(\):) Tj T* (    assert plac.call\(ishelve.main, ['.clear']\) == ['cleared the shelve']) Tj T* (    assert plac.call\(ishelve.main, ['a=1']\) == ['setting a=1']) Tj T* (    assert plac.call\(ishelve.main, ['a']\) == ['1']) Tj T* (    assert plac.call\(ishelve.main, ['.delete=a']\) == ['deleted a']) Tj T* (    assert plac.call\(ishelve.main, ['a']\) == ['a: not found']) Tj T*  T* (if __name__ == '__main__':) Tj T* (    test\(\)) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 543.8236 cm
-q
-BT 1 0 0 1 0 28.82 Tm .390651 Tw 12 TL /F1 10 Tf 0 0 0 rg (However, using ) Tj /F4 10 Tf (plac.call ) Tj /F1 10 Tf (is not especially nice. The big issue is that ) Tj /F4 10 Tf (plac.call ) Tj /F1 10 Tf (responds to invalid) Tj T* 0 Tw 1.249987 Tw (input by printing an error message on stderr and by raising a ) Tj /F4 10 Tf (SystemExit) Tj /F1 10 Tf (: this is certainly not a nice) Tj T* 0 Tw (thing to do in a test.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 501.8236 cm
-q
-BT 1 0 0 1 0 28.82 Tm 1.616457 Tw 12 TL /F1 10 Tf 0 0 0 rg (As a consequence of this behavior it is impossible to test for invalid commands, unless you wrap the) Tj T* 0 Tw .259985 Tw /F4 10 Tf (SystemExit ) Tj /F1 10 Tf (exception by hand each time \(a possibly you do something with the error message in stderr) Tj T* 0 Tw (too\). Luckily, ) Tj /F4 10 Tf (plac ) Tj /F1 10 Tf (offers a better testing support through the ) Tj /F4 10 Tf (check ) Tj /F1 10 Tf (method of ) Tj /F4 10 Tf (Interpreter ) Tj /F1 10 Tf (objects:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 348.6236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 144 re B*
-Q
-q
-0 0 0 rg
-BT 1 0 0 1 0 125.71 Tm /F4 10 Tf 12 TL (# test_ishelve_more.py) Tj T* (from __future__ import with_statement) Tj T* (import plac, ishelve) Tj T*  T* (def test\(\):) Tj T* (    with plac.Interpreter\(ishelve.main\) as i:) Tj T* (        i.check\('.clear', 'cleared the shelve'\)) Tj T* (        i.check\('a=1', 'setting a=1'\)) Tj T* (        i.check\('a', '1'\)) Tj T* (        i.check\('.delete=a', 'deleted a'\)) Tj T* (        i.check\('a', 'a: not found'\)) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 292.6236 cm
-q
-BT 1 0 0 1 0 40.82 Tm 6.299974 Tw 12 TL /F1 10 Tf 0 0 0 rg (The method ) Tj /F4 10 Tf (.check\(given_input, expected_output\) ) Tj /F1 10 Tf (works on strings and raises an) Tj T* 0 Tw .971318 Tw /F4 10 Tf (AssertionError ) Tj /F1 10 Tf (if the output produced by the interpreter is different from the expected output for the) Tj T* 0 Tw 2.186905 Tw (given input. Notice that ) Tj /F4 10 Tf (AssertionError ) Tj /F1 10 Tf (is catched by tools like ) Tj /F4 10 Tf (py.test ) Tj /F1 10 Tf (and ) Tj /F4 10 Tf (nosetests ) Tj /F1 10 Tf (and) Tj T* 0 Tw (actually ) Tj /F4 10 Tf (plac ) Tj /F1 10 Tf (tests are intended to be run with such tools.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 238.6236 cm
-q
-BT 1 0 0 1 0 40.82 Tm .239984 Tw 12 TL /F1 10 Tf 0 0 0 rg (Interpreters offer a minor syntactic advantage with respect to calling ) Tj /F4 10 Tf (plac.call ) Tj /F1 10 Tf (directly, but they offer a) Tj T* 0 Tw .96748 Tw /F5 10 Tf (major ) Tj /F1 10 Tf (semantic advantage when things go wrong \(read exceptions\): an ) Tj /F4 10 Tf (Interpreter ) Tj /F1 10 Tf (object internally) Tj T* 0 Tw 1.181318 Tw (invokes something like ) Tj /F4 10 Tf (plac.call) Tj /F1 10 Tf (, but it wraps all exceptions, so that ) Tj /F4 10 Tf (i.check ) Tj /F1 10 Tf (is guaranteed not to) Tj T* 0 Tw (raise any exception except ) Tj /F4 10 Tf (AssertionError) Tj /F1 10 Tf (.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 220.6236 cm
-q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (Even the ) Tj /F4 10 Tf (SystemExit ) Tj /F1 10 Tf (exception is captured and you can write your test as) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 214.6236 cm
-Q
-q
-1 0 0 1 62.69291 202.6236 cm
-0 0 0 rg
-BT /F3 10 Tf 12 TL ET
-BT 1 0 0 1 0 2 Tm  T* ET
-q
-1 0 0 1 20 0 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 5.71 Tm /F4 10 Tf 12 TL (i.check\('-cler', 'SystemExit: unrecognized arguments: -cler'\)) Tj T* ET
-Q
-Q
-q
-Q
-Q
-q
-1 0 0 1 62.69291 202.6236 cm
-Q
-q
-1 0 0 1 62.69291 184.6236 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL (without risk of exiting from the Python interpreter.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 142.6236 cm
-q
-BT 1 0 0 1 0 28.82 Tm 1.422651 Tw 12 TL /F1 10 Tf 0 0 0 rg (There is a second advantage of interpreters: if the main function contains some initialization code and) Tj T* 0 Tw .454651 Tw (finalization code \() Tj /F4 10 Tf (__enter__ ) Tj /F1 10 Tf (and ) Tj /F4 10 Tf (__exit__ ) Tj /F1 10 Tf (functions\) they will be run only once at the beginning and) Tj T* 0 Tw (at the end of the interpreter loop. ) Tj /F4 10 Tf (plac.call ) Tj /F1 10 Tf (instead ignores the initialization/finalization code.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 56.69291 56.69291 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 238.1649 0 Td (4) Tj T* -238.1649 0 Td ET
-Q
-Q
- 
-endstream
-
-endobj
-% 'R163': class PDFStream 
-163 0 obj
-% page stream
-<< /Length 6149 >>
-stream
-1 0 0 1 0 0 cm BT /F1 12 Tf 14.4 TL ET
-q
-1 0 0 1 62.69291 744.0236 cm
-q
-BT 1 0 0 1 0 8.435 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (Plac easy tests) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 702.0236 cm
-q
-BT 1 0 0 1 0 28.82 Tm 1.517126 Tw 12 TL /F1 10 Tf 0 0 0 rg (Writing your tests in terms of ) Tj /F4 10 Tf (Interpreter.check ) Tj /F1 10 Tf (is certainly an improvement over writing them in) Tj T* 0 Tw 1.807318 Tw (terms of ) Tj /F4 10 Tf (plac.call) Tj /F1 10 Tf (, but they are still too low-level for my taste. The ) Tj /F4 10 Tf (Interpreter ) Tj /F1 10 Tf (class provides) Tj T* 0 Tw (support for doctest-style tests, a.k.a. ) Tj /F5 10 Tf (plac easy tests) Tj /F1 10 Tf (.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 660.0236 cm
-q
-BT 1 0 0 1 0 28.82 Tm 2.142209 Tw 12 TL /F1 10 Tf 0 0 0 rg (By using plac easy tests you can cut and paste your interactive session and turn it into a runnable) Tj T* 0 Tw .519213 Tw (automatics test. Consider for instance the following file ) Tj /F4 10 Tf (ishelve.placet ) Tj /F1 10 Tf (\(the ) Tj /F4 10 Tf (.placet ) Tj /F1 10 Tf (extension is a) Tj T* 0 Tw (mnemonic for plac easy tests\):) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 482.8236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 168 re B*
-Q
-q
-BT 1 0 0 1 0 149.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (#!ishelve.py) Tj T* (i) Tj (>) Tj ( .clear # start from a clean state) Tj T* (cleared the shelve) Tj T* (i) Tj (>) Tj ( a=1) Tj T* (setting a=1) Tj T* (i) Tj (>) Tj ( a) Tj T* (1) Tj T* (i) Tj (>) Tj ( .del a) Tj T* (deleted a) Tj T* (i) Tj (>) Tj ( a) Tj T* (a: not found) Tj T* (i) Tj (>) Tj ( .cler # spelling error) Tj T* (.cler: not found) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 426.8236 cm
-q
-BT 1 0 0 1 0 40.82 Tm .697132 Tw 12 TL /F1 10 Tf 0 0 0 rg (Notice the precence of the shebang line containing the name of the ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (tool to test \(a ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (tool is just a) Tj T* 0 Tw 1.511751 Tw (Python module with a function called ) Tj /F4 10 Tf (main) Tj /F1 10 Tf (\). The shebang is ignored by the interpreter \(it looks like a) Tj T* 0 Tw .487608 Tw (comment to it\) but it is there so that external tools \(say a test runner\) can infer the plac interpreter to use) Tj T* 0 Tw (to test the file.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 396.8236 cm
-q
-BT 1 0 0 1 0 16.82 Tm 2.419984 Tw 12 TL /F1 10 Tf 0 0 0 rg (You can test ) Tj /F4 10 Tf (ishelve.placet ) Tj /F1 10 Tf (file by calling the ) Tj /F4 10 Tf (.doctest ) Tj /F1 10 Tf (method of the interpreter, as in this) Tj T* 0 Tw (example:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 352.0393 cm
-q
-q
-.988825 0 0 .988825 0 0 cm
-q
-1 0 0 1 6.6 6.674587 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 474 36 re B*
-Q
-q
-0 0 0 rg
-BT 1 0 0 1 0 17.71 Tm /F4 10 Tf 12 TL ($ python -c"import plac, ishelve) Tj T* (plac.Interpreter\(ishelve.main\).doctest\(open\('ishelve.placet'\), verbose=True\)") Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 308.0393 cm
-q
-BT 1 0 0 1 0 28.82 Tm 4.007109 Tw 12 TL /F1 10 Tf 0 0 0 rg (Internally ) Tj /F4 10 Tf (Interpreter.doctests ) Tj /F1 10 Tf (invokes something like ) Tj /F4 10 Tf (Interpreter.check ) Tj /F1 10 Tf (multiple times) Tj T* 0 Tw .226654 Tw (inside the same context and compare the output with the expected output: if even a check fails, the whole) Tj T* 0 Tw (test fail.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 266.0393 cm
-q
-BT 1 0 0 1 0 28.82 Tm .175868 Tw 12 TL /F1 10 Tf 0 0 0 rg (You should realize tha the easy tests supported by ) Tj /F4 10 Tf (plac ) Tj /F1 10 Tf (are ) Tj /F5 10 Tf (not ) Tj /F1 10 Tf (unittests: they are functional tests. They) Tj T* 0 Tw 1.22936 Tw (model then user interaction and the order of the operations generally matters. The single subtests in a) Tj T* 0 Tw /F4 10 Tf (.placet ) Tj /F1 10 Tf (file are not independent and it makes sense to exit immediately at the first failure.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 188.0393 cm
-q
-BT 1 0 0 1 0 64.82 Tm .414431 Tw 12 TL /F1 10 Tf 0 0 0 rg (The support for doctests in ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (comes nearly for free, thanks to the ) Tj 0 0 .501961 rg (shlex ) Tj 0 0 0 rg (module in the standard library,) Tj T* 0 Tw .352765 Tw (which is able to parse simple languages as the ones you can implement with ) Tj 0 0 .501961 rg (plac) Tj 0 0 0 rg (. In particular, thanks to) Tj T* 0 Tw .875984 Tw 0 0 .501961 rg (shlex) Tj 0 0 0 rg (, ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (is able to recognize comments \(the default comment character is ) Tj /F4 10 Tf (#) Tj /F1 10 Tf (\), escape sequences and) Tj T* 0 Tw 1.50686 Tw (more. Look at the ) Tj 0 0 .501961 rg (shlex ) Tj 0 0 0 rg (documentation if you need to customize how the language is interpreted. For) Tj T* 0 Tw 2.794985 Tw (more flexibility, it is even possible to pass to the interpreter a custom split function with signature) Tj T* 0 Tw /F4 10 Tf (split\(line, commentchar\)) Tj /F1 10 Tf (.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 134.0393 cm
-q
-BT 1 0 0 1 0 40.82 Tm .136654 Tw 12 TL /F1 10 Tf 0 0 0 rg (In addition, I have implemented from scratch some support for line number recognition, so that if a test fail) Tj T* 0 Tw .042093 Tw (you get the line number of the failing command. This is especially useful if your tests are stored in external) Tj T* 0 Tw .610898 Tw (files, even if plac easy tests does not need to be in a file: you can just pass to the ) Tj /F4 10 Tf (.doctest ) Tj /F1 10 Tf (method a) Tj T* 0 Tw (list of strings corresponding to the lines of the file.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 104.0393 cm
-q
-BT 1 0 0 1 0 16.82 Tm .653145 Tw 12 TL /F1 10 Tf 0 0 0 rg (At the present ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (does not use any code from the doctest module, but the situation may change in the) Tj T* 0 Tw (future \(it would be nice if ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (could reuse doctests directives like ELLIPSIS\).) Tj T* ET
-Q
-Q
-q
-1 0 0 1 56.69291 56.69291 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 238.1649 0 Td (5) Tj T* -238.1649 0 Td ET
-Q
-Q
- 
-endstream
-
-endobj
-% 'R164': class PDFStream 
-164 0 obj
-% page stream
-<< /Length 5253 >>
-stream
-1 0 0 1 0 0 cm BT /F1 12 Tf 14.4 TL ET
-q
-1 0 0 1 62.69291 741.0236 cm
-q
-BT 1 0 0 1 0 16.82 Tm 1.447318 Tw 12 TL /F1 10 Tf 0 0 0 rg (It is straighforward to integrate your ) Tj /F4 10 Tf (.placet ) Tj /F1 10 Tf (tests with standard testing tools. For instance, you can) Tj T* 0 Tw (integrate your doctests with ) Tj /F4 10 Tf (nose ) Tj /F1 10 Tf (or ) Tj /F4 10 Tf (py.test ) Tj /F1 10 Tf (as follow:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 553.8485 cm
-q
-q
-.988825 0 0 .988825 0 0 cm
-q
-1 0 0 1 6.6 6.674587 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 474 180 re B*
-Q
-q
-0 0 0 rg
-BT 1 0 0 1 0 161.71 Tm /F4 10 Tf 12 TL (import os, shlex, plac) Tj T*  T* (def test_doct\(\):) Tj T* (   """) Tj T* (   Find all the doctests in the current directory and run them with the) Tj T* (   corresponding plac interpreter \(the shebang rules!\)) Tj T* (   """) Tj T* (   placets = [f for f in os.listdir\('.'\) if f.endswith\('.placet'\)]) Tj T* (   for placet in placets:) Tj T* (       lines = list\(open\(placet\)\)) Tj T* (       assert lines[0].startswith\('#!'\), 'Missing or incorrect shebang line!') Tj T* (       firstline = lines[0][2:] # strip the shebang) Tj T* (       main = plac.import_main\(*shlex.split\(firstline\)\)) Tj T* (       yield plac.Interpreter\(main\).doctest, lines[1:]) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 473.8485 cm
-q
-BT 1 0 0 1 0 64.82 Tm 1.44811 Tw 12 TL /F1 10 Tf 0 0 0 rg (Here you should notice that usage of ) Tj /F4 10 Tf (plac.import_main) Tj /F1 10 Tf (, an utility which is able to import the main) Tj T* 0 Tw .775703 Tw (function of the script specified in the shebang line. You can use both the full path name of the tool, or a) Tj T* 0 Tw .87686 Tw (relative path name. In this case the runner look at the environment variable ) Tj /F4 10 Tf (PLACPATH ) Tj /F1 10 Tf (and it searches) Tj T* 0 Tw 1.900651 Tw (the plac tool in the directories specified there \() Tj /F4 10 Tf (PLACPATH ) Tj /F1 10 Tf (is just a string containing directory names) Tj T* 0 Tw .56332 Tw (separated by colons\). If the variable ) Tj /F4 10 Tf (PLACPATH ) Tj /F1 10 Tf (is not defined, it just looks in the current directory. If the) Tj T* 0 Tw (plac tool is not found, an ) Tj /F4 10 Tf (ImportError ) Tj /F1 10 Tf (is raised.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 440.8485 cm
-q
-BT 1 0 0 1 0 8.435 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (Plac batch scripts) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 398.8485 cm
-q
-BT 1 0 0 1 0 28.82 Tm .772093 Tw 12 TL /F1 10 Tf 0 0 0 rg (It is pretty easy to realize that an interactive interpreter can also be used to run batch scripts: instead of) Tj T* 0 Tw .504692 Tw (reading the commands from the console, it is enough to read the commands from a file. ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (interpreters) Tj T* 0 Tw (provide an ) Tj /F4 10 Tf (.execute ) Tj /F1 10 Tf (method to perform just that.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 332.8485 cm
-q
-BT 1 0 0 1 0 52.82 Tm .098935 Tw 12 TL /F1 10 Tf 0 0 0 rg (There is just a subtle point to notice: whereas in an interactive loop one wants to manage all exceptions, a) Tj T* 0 Tw 3.866412 Tw (batch script should not in the background in case of unexpected errors. The implementation of) Tj T* 0 Tw .103059 Tw /F4 10 Tf (Interpreter.execute ) Tj /F1 10 Tf (makes sure that any error raised by ) Tj /F4 10 Tf (plac.call ) Tj /F1 10 Tf (internally is re-raised. In other) Tj T* 0 Tw .407045 Tw (words, ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (interpreters ) Tj /F5 10 Tf (wrap the errors, but does not eat them) Tj /F1 10 Tf (: the errors are always accessible and can) Tj T* 0 Tw (be re-raised on demand.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 302.8485 cm
-q
-BT 1 0 0 1 0 16.82 Tm 1.239318 Tw 12 TL /F1 10 Tf 0 0 0 rg (The exception is the case of invalid commands, which are skipped. Consider for instance the following) Tj T* 0 Tw (batch file, which contains a mispelled command \() Tj /F4 10 Tf (.dl ) Tj /F1 10 Tf (instead of ) Tj /F4 10 Tf (.del) Tj /F1 10 Tf (\):) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 197.6485 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 96 re B*
-Q
-q
-0 0 0 rg
-BT 1 0 0 1 0 77.71 Tm /F4 10 Tf 12 TL (#!ishelve.py) Tj T* (.clear ) Tj T* (a=1 b=2) Tj T* (.show) Tj T* (.del a) Tj T* (.dl b) Tj T* (.show) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 165.6485 cm
-q
-BT 1 0 0 1 0 16.82 Tm 1.939461 Tw 12 TL /F1 10 Tf 0 0 0 rg (If you execute the batch file, the interpreter will print a ) Tj /F4 10 Tf (.dl: not found ) Tj /F1 10 Tf (at the ) Tj /F4 10 Tf (.dl ) Tj /F1 10 Tf (line and will) Tj T* 0 Tw (continue:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 96.44848 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 60 re B*
-Q
-q
-BT 1 0 0 1 0 41.71 Tm 12 TL /F4 10 Tf 0 0 0 rg ($ python -c "import plac, ishelve) Tj T* (plac.Interpreter\(ishelve.main\).execute\(open\('ishelve.plac'\), verbose=True\)") Tj T* (i) Tj (>) Tj ( .clear) Tj T* (cleared the shelve) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 56.69291 56.69291 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 238.1649 0 Td (6) Tj T* -238.1649 0 Td ET
-Q
-Q
- 
-endstream
-
-endobj
-% 'R165': class PDFStream 
-165 0 obj
-% page stream
-<< /Length 4316 >>
-stream
-1 0 0 1 0 0 cm BT /F1 12 Tf 14.4 TL ET
-q
-1 0 0 1 62.69291 595.8236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 168 re B*
-Q
-q
-BT 1 0 0 1 0 149.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (i) Tj (>) Tj ( a=1 b=2) Tj T* (setting a=1) Tj T* (setting b=2) Tj T* (i) Tj (>) Tj ( .show) Tj T* (b=2) Tj T* (a=1) Tj T* (i) Tj (>) Tj ( .del a) Tj T* (deleted a) Tj T* (i) Tj (>) Tj ( .dl b) Tj T* (2) Tj T* (.dl: not found) Tj T* (i) Tj (>) Tj ( .show) Tj T* (b=2) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 551.8236 cm
-q
-BT 1 0 0 1 0 28.82 Tm .159988 Tw 12 TL /F1 10 Tf 0 0 0 rg (The ) Tj /F4 10 Tf (verbose ) Tj /F1 10 Tf (flag is there to show the lines which are being interpreted \(prefixed by ) Tj /F4 10 Tf (i) Tj (>) Tj /F1 10 Tf (\). This is done on) Tj T* 0 Tw 1.359988 Tw (purpose, so that you can cut and paste the output of the batch script and turn it into a ) Tj /F4 10 Tf (.placet ) Tj /F1 10 Tf (test) Tj T* 0 Tw (\(cool, isn't it?\).) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 518.8236 cm
-q
-BT 1 0 0 1 0 8.435 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (Implementing subcommands) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 476.8236 cm
-q
-BT 1 0 0 1 0 28.82 Tm 1.182485 Tw 12 TL /F1 10 Tf 0 0 0 rg (When I discussed the ) Tj /F4 10 Tf (ishelve ) Tj /F1 10 Tf (implementation in the ) Tj 0 0 .501961 rg (basic documentation) Tj 0 0 0 rg (, I said that it looked like a) Tj T* 0 Tw .116655 Tw (poor man implementation of an object system as a chain of elifs; I also said that ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (was able to do much) Tj T* 0 Tw (better than that. Here I will substantiate my claim.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 434.8236 cm
-q
-BT 1 0 0 1 0 28.82 Tm .89104 Tw 12 TL /F1 10 Tf 0 0 .501961 rg (plac ) Tj 0 0 0 rg (is actually able to infer a set of subparsers from a generic container of commands. This is useful if) Tj T* 0 Tw 3.125814 Tw (you want to implement ) Tj /F5 10 Tf (subcommands ) Tj /F1 10 Tf (\(a familiar example of a command-line application featuring) Tj T* 0 Tw (subcommands is subversion\).) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 368.8236 cm
-q
-BT 1 0 0 1 0 52.82 Tm .015868 Tw 12 TL /F1 10 Tf 0 0 0 rg (Technically a container of commands is any object with a ) Tj /F4 10 Tf (.commands ) Tj /F1 10 Tf (attribute listing a set of functions or) Tj T* 0 Tw 2.550888 Tw (methods which are valid commands. A command container may have initialization/finalization hooks) Tj T* 0 Tw 2.55664 Tw (\() Tj /F4 10 Tf (__enter__/__exit__) Tj /F1 10 Tf (\) and dispatch hooks \() Tj /F4 10 Tf (__missing__) Tj /F1 10 Tf (, invoked for invalid command names\).) Tj T* 0 Tw 2.113828 Tw (Moreover, only when using command containers ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (is able to provide automatic autocompletion of) Tj T* 0 Tw (commands.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 350.8236 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL (The shelve interface can be rewritten in an object-oriented way as follows:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 89.62362 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 252 re B*
-Q
-q
-0 0 0 rg
-BT 1 0 0 1 0 233.71 Tm /F4 10 Tf 12 TL (# ishelve2.py) Tj T* (import shelve, os, sys, plac) Tj T*  T* (class ShelveInterface\(object\):) Tj T* (    "A minimal interface over a shelve object.") Tj T* (    commands = 'set', 'show', 'showall', 'delete') Tj T* (    @plac.annotations\() Tj T* (        configfile=\('path name of the shelve', 'option'\)\)) Tj T* (    def __init__\(self, configfile\):) Tj T* (        self.configfile = configfile or '~/conf.shelve') Tj T* (        self.fname = os.path.expanduser\(self.configfile\)) Tj T* (        self.__doc__ += '\\nOperating on %s.\\n.help to see '\\) Tj T* (            'the available commands.\\n'  % self.fname) Tj T* (    def __enter__\(self\):) Tj T* (        self.sh = shelve.open\(self.fname\)) Tj T* (        return self) Tj T* (    def __exit__\(self, etype, exc, tb\):) Tj T* (        self.sh.close\(\)) Tj T* (    def set\(self, name, value\):) Tj T* (        "set name value") Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 56.69291 56.69291 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 238.1649 0 Td (7) Tj T* -238.1649 0 Td ET
-Q
-Q
- 
-endstream
-
-endobj
-% 'R166': class PDFStream 
-166 0 obj
-% page stream
-<< /Length 4288 >>
-stream
-1 0 0 1 0 0 cm BT /F1 12 Tf 14.4 TL ET
-q
-1 0 0 1 62.69291 475.8236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 288 re B*
-Q
-q
-0 0 0 rg
-BT 1 0 0 1 0 269.71 Tm /F4 10 Tf 12 TL (        yield 'setting %s=%s' % \(name, value\)) Tj T* (        self.sh[name] = value) Tj T* (    def show\(self, *names\):) Tj T* (        "show given parameters") Tj T* (        for name in names:) Tj T* (            yield '%s = %s' % \(name, self.sh[name]\) # no error checking) Tj T* (    def showall\(self\):) Tj T* (        "show all parameters") Tj T* (        for name in self.sh:) Tj T* (            yield '%s = %s' % \(name, self.sh[name]\)) Tj T* (    def delete\(self, name=None\):) Tj T* (        "delete given parameter \(or everything\)") Tj T* (        if name is None:) Tj T* (            yield 'deleting everything') Tj T* (            self.sh.clear\(\)) Tj T* (        else:) Tj T* (            yield 'deleting %s' % name) Tj T* (            del self.sh[name] # no error checking) Tj T*  T* (main = ShelveInterface # useful for the tests) Tj T*  T* (if __name__ == '__main__':) Tj T* (    plac.Interpreter\(plac.call\(ShelveInterface\)\).interact\(\)) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 383.8236 cm
-q
-BT 1 0 0 1 0 76.82 Tm .885366 Tw 12 TL /F4 10 Tf 0 0 0 rg (plac.Interpreter ) Tj /F1 10 Tf (objects wrap context manager objects consistently. In other words, if you wrap an) Tj T* 0 Tw 2.323828 Tw (object with ) Tj /F4 10 Tf (__enter__ ) Tj /F1 10 Tf (and ) Tj /F4 10 Tf (__exit__ ) Tj /F1 10 Tf (methods, they are invoked in the right order \() Tj /F4 10 Tf (__enter__) Tj T* 0 Tw .23528 Tw /F1 10 Tf (before the interpreter loop starts and ) Tj /F4 10 Tf (__exit__ ) Tj /F1 10 Tf (after the interpreter loop ends, both in the regular and in) Tj T* 0 Tw 1.916412 Tw (the exceptional case\). In our example, the methods ) Tj /F4 10 Tf (__enter__ ) Tj /F1 10 Tf (and ) Tj /F4 10 Tf (__exit__ ) Tj /F1 10 Tf (make sure the the) Tj T* 0 Tw .339398 Tw (shelve is opened and closed correctly even in the case of exceptions. Notice that I have not implemented) Tj T* 0 Tw .814104 Tw (any error checking in the ) Tj /F4 10 Tf (show ) Tj /F1 10 Tf (and ) Tj /F4 10 Tf (delete ) Tj /F1 10 Tf (methods on purpose, to verify that ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (works correctly in) Tj T* 0 Tw (the presence of exceptions.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 305.8236 cm
-q
-BT 1 0 0 1 0 64.82 Tm 1.567126 Tw 12 TL /F1 10 Tf 0 0 0 rg (When working with command containers, ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (automatically adds two special commands to the set of) Tj T* 0 Tw 1.176136 Tw (provided commands: ) Tj /F4 10 Tf (.help ) Tj /F1 10 Tf (and ) Tj /F4 10 Tf (.last_tb) Tj /F1 10 Tf (. The ) Tj /F4 10 Tf (.help ) Tj /F1 10 Tf (command is the easier to understand: when) Tj T* 0 Tw .39811 Tw (invoked without arguments it displays the list of available commands with the same formatting of the ) Tj 0 0 .501961 rg (cmd) Tj T* 0 Tw 1.19561 Tw 0 0 0 rg (module; when invoked with the name of a command it displays the usage message for that command.) Tj T* 0 Tw 2.33686 Tw (The ) Tj /F4 10 Tf (.last_tb ) Tj /F1 10 Tf (command is useful when debugging: in case of errors, it allows you to display the) Tj T* 0 Tw (traceback of the last executed command.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 287.8236 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL (Here is a session of usage on an Unix-like operating system:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 98.62362 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 180 re B*
-Q
-q
-BT 1 0 0 1 0 161.71 Tm 12 TL /F4 10 Tf 0 0 0 rg ($ python ishelve2.py) Tj T* (A minimal interface over a shelve object.) Tj T* (Operating on /home/micheles/conf.shelve.) Tj T* (.help to see the available commands.) Tj T* (i) Tj (>) Tj ( .help) Tj T*  T* (special commands) Tj T* (================) Tj T* (.help .last_tb) Tj T*  T* (custom commands) Tj T* (===============) Tj T* (delete  set  show  showall) Tj T*  T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 56.69291 56.69291 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 238.1649 0 Td (8) Tj T* -238.1649 0 Td ET
-Q
-Q
- 
-endstream
-
-endobj
-% 'R167': class PDFStream 
-167 0 obj
-% page stream
-<< /Length 5042 >>
-stream
-1 0 0 1 0 0 cm BT /F1 12 Tf 14.4 TL ET
-q
-1 0 0 1 62.69291 504.0769 cm
-q
-q
-.773863 0 0 .773863 0 0 cm
-q
-1 0 0 1 6.6 8.528639 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 606 336 re B*
-Q
-q
-BT 1 0 0 1 0 317.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (i) Tj (>) Tj ( delete) Tj T* (deleting everything) Tj T* (i) Tj (>) Tj ( set a pippo) Tj T* (setting a=pippo) Tj T* (i) Tj (>) Tj ( set b lippo) Tj T* (setting b=lippo) Tj T* (i) Tj (>) Tj ( showall) Tj T* (b = lippo) Tj T* (a = pippo) Tj T* (i) Tj (>) Tj ( show a b) Tj T* (a = pippo) Tj T* (b = lippo) Tj T* (i) Tj (>) Tj ( del a) Tj T* (deleting a) Tj T* (i) Tj (>) Tj ( showall) Tj T* (b = lippo) Tj T* (i) Tj (>) Tj ( delete a) Tj T* (deleting a) Tj T* (KeyError: 'a') Tj T* (i) Tj (>) Tj ( .last_tb) Tj T* ( File "/usr/local/lib/python2.6/dist-packages/plac-0.6.0-py2.6.egg/plac_ext.py", line 190, in _wrap) Tj T* (    for value in genobj:) Tj T* (  File "./ishelve2.py", line 37, in delete) Tj T* (    del self.sh[name] # no error checking) Tj T* (  File "/usr/lib/python2.6/shelve.py", line 136, in __delitem__) Tj T* (    del self.dict[key]) Tj T* (i) Tj (>) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 472.0769 cm
-q
-BT 1 0 0 1 0 16.82 Tm 2.571235 Tw 12 TL /F1 10 Tf 0 0 0 rg (Notice that in interactive mode the traceback is hidden, unless you pass the ) Tj /F4 10 Tf (verbose ) Tj /F1 10 Tf (flag to the) Tj T* 0 Tw /F4 10 Tf (Interpreter.interact ) Tj /F1 10 Tf (method.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 439.0769 cm
-q
-BT 1 0 0 1 0 8.435 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (plac.Interpreter.call) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 397.0769 cm
-q
-BT 1 0 0 1 0 28.82 Tm 1.066303 Tw 12 TL /F1 10 Tf 0 0 0 rg (At the core of ) Tj /F4 10 Tf (plac ) Tj /F1 10 Tf (there is the ) Tj /F4 10 Tf (call ) Tj /F1 10 Tf (function which invokes a callable with the list of the arguments) Tj T* 0 Tw .937674 Tw (passed at the command-line \() Tj /F4 10 Tf (sys.argv[1:]) Tj /F1 10 Tf (\). Thanks to ) Tj /F4 10 Tf (plac.call ) Tj /F1 10 Tf (you can launch your module by) Tj T* 0 Tw (simply adding the lines:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 351.8769 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 36 re B*
-Q
-q
-0 0 0 rg
-BT 1 0 0 1 0 17.71 Tm /F4 10 Tf 12 TL (if __name__ == '__main__':) Tj T* (    plac.call\(main\)) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 295.8769 cm
-q
-BT 1 0 0 1 0 40.82 Tm .50436 Tw 12 TL /F1 10 Tf 0 0 0 rg (Everything works fine if ) Tj /F4 10 Tf (main ) Tj /F1 10 Tf (is a simple callable performing some action; however, in many cases, one) Tj T* 0 Tw .087633 Tw (has a ) Tj /F4 10 Tf (main ) Tj /F1 10 Tf ("function" which is a actually a factory returning a command container object. For instance, in) Tj T* 0 Tw .573318 Tw (my second shelve example the main function is the class ) Tj /F4 10 Tf (ShelveInterface) Tj /F1 10 Tf (, and the two lines needed) Tj T* 0 Tw (to run the module are a bit ugly:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 250.6769 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 36 re B*
-Q
-q
-0 0 0 rg
-BT 1 0 0 1 0 17.71 Tm /F4 10 Tf 12 TL (if __name__ == '__main__':) Tj T* (   plac.Interpreter\(plac.call\(ShelveInterface\)\).interact\(\)) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 146.6769 cm
-q
-BT 1 0 0 1 0 88.82 Tm .435227 Tw 12 TL /F1 10 Tf 0 0 0 rg (Moreover, now the program runs, but only in interactive mode, i.e. it is not possible to run it as a script. It) Tj T* 0 Tw .721098 Tw (would be nice instead to be able to specify the command to execute on the command-line and have the) Tj T* 0 Tw 4.08229 Tw (interpreter start, execute the command and finish properly \(I mean by calling ) Tj /F4 10 Tf (__enter__ ) Tj /F1 10 Tf (and) Tj T* 0 Tw .427633 Tw /F4 10 Tf (__exit__) Tj /F1 10 Tf (\) without needing user input. The the script could be called from a batch shell script working in) Tj T* 0 Tw 2.26816 Tw (the background. In order to provide such functionality ) Tj /F4 10 Tf (plac.Interpreter ) Tj /F1 10 Tf (provides a classmethod) Tj T* 0 Tw 1.173318 Tw (named ) Tj /F4 10 Tf (.call ) Tj /F1 10 Tf (which takes the factory, instantiates it with the arguments read from the command line,) Tj T* 0 Tw 1.517045 Tw (wraps the resulting container object as an interpreter and runs it with the rest arguments found in the) Tj T* 0 Tw (command line. Here is the code to turn the ) Tj /F4 10 Tf (ShelveInterface ) Tj /F1 10 Tf (into a script) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 89.47694 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 48 re B*
-Q
-q
-0 0 0 rg
-BT 1 0 0 1 0 29.71 Tm /F4 10 Tf 12 TL (# ishelve3.py) Tj T* (from ishelve2 import ShelveInterface as main) Tj T*  T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 56.69291 56.69291 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 238.1649 0 Td (9) Tj T* -238.1649 0 Td ET
-Q
-Q
- 
-endstream
-
-endobj
-% 'R168': class PDFStream 
-168 0 obj
-% page stream
-<< /Length 4064 >>
-stream
-1 0 0 1 0 0 cm BT /F1 12 Tf 14.4 TL ET
-q
-1 0 0 1 62.69291 727.8236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 36 re B*
-Q
-q
-0 0 0 rg
-BT 1 0 0 1 0 17.71 Tm /F4 10 Tf 12 TL (if __name__ == '__main__':) Tj T* (    import plac; plac.Interpreter.call\(main\)) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 707.8236 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL (and here are a few examples of usage:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 494.6236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 204 re B*
-Q
-q
-0 0 0 rg
-BT 1 0 0 1 0 185.71 Tm /F4 10 Tf 12 TL ($ python ishelve3.py -h) Tj T* (usage: ishelve3.py [-h] [-i] [-configfile CONFIGFILE] [args [args ...]]) Tj T*  T* (positional arguments:) Tj T* (  args) Tj T*  T* (optional arguments:) Tj T* (  -h, --help            show this help message and exit) Tj T* (  -i, --interact        start interactive interpreter) Tj T* (  -configfile CONFIGFILE) Tj T* (                        path name of the shelve) Tj T*  T* ($ python ishelve3.py set a 1) Tj T* (setting a=1) Tj T* ($ python ishelve3.py show a) Tj T* (a = 1) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 462.6236 cm
-q
-BT 1 0 0 1 0 16.82 Tm .079989 Tw 12 TL /F1 10 Tf 0 0 0 rg (If you pass the ) Tj /F4 10 Tf (-i ) Tj /F1 10 Tf (flag in the command line, then the script will enter in interactive mode and ask the user) Tj T* 0 Tw (for the commands to execute:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 369.4236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 84 re B*
-Q
-q
-BT 1 0 0 1 0 65.71 Tm 12 TL /F4 10 Tf 0 0 0 rg ($ python ishelve3.py -i) Tj T* (A minimal interface over a shelve object.) Tj T* (Operating on /home/micheles/conf.shelve.) Tj T* (.help to see the available commands.) Tj T*  T* (i) Tj (>) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 325.4236 cm
-q
-BT 1 0 0 1 0 28.82 Tm .221417 Tw 12 TL /F1 10 Tf 0 0 0 rg (In a sense, I have closed the circle: at the beginning of this document I discussed how to turn a script into) Tj T* 0 Tw .784147 Tw (an interactive application \(the ) Tj /F4 10 Tf (shelve_interpreter.py ) Tj /F1 10 Tf (example\), whereas here I have show how to) Tj T* 0 Tw (turn an interactive application into a script.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 307.4236 cm
-q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (The complete signature of ) Tj /F4 10 Tf (plac.Interpreter.call ) Tj /F1 10 Tf (is the following:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 250.2236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 48 re B*
-Q
-q
-BT 1 0 0 1 0 29.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (call\(factory, arglist=sys.argv[1:],) Tj T* (     commentchar='#', split=shlex.split,) Tj T* (     stdin=sys.stdin, prompt='i) Tj (>) Tj ( ', verbose=False\)) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 170.2236 cm
-q
-BT 1 0 0 1 0 64.82 Tm 1.756651 Tw 12 TL /F1 10 Tf 0 0 0 rg (The factory must have a fixed number of positional arguments \(no default arguments, no varargs, no) Tj T* 0 Tw 1.87881 Tw (kwargs\), otherwise a ) Tj /F4 10 Tf (TypeError ) Tj /F1 10 Tf (is raised: the reason is that we want to be able to distinguish the) Tj T* 0 Tw .829984 Tw (command-line arguments needed to instantiate the factory from the rest arguments that must be sent to) Tj T* 0 Tw 2.609984 Tw (the corresponding interpreter object. It is also possible to specify a list of arguments different from) Tj T* 0 Tw .513318 Tw /F4 10 Tf (sys.argv[1:] ) Tj /F1 10 Tf (\(useful in tests\), the character to be recognized as a comment, the splitting function, the) Tj T* 0 Tw (input source and the prompt to use while in interactive mode, and a verbose flag.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 56.69291 56.69291 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 235.3849 0 Td (10) Tj T* -235.3849 0 Td ET
-Q
-Q
- 
-endstream
-
-endobj
-% 'R169': class PDFStream 
-169 0 obj
-% page stream
-<< /Length 5082 >>
-stream
-1 0 0 1 0 0 cm BT /F1 12 Tf 14.4 TL ET
-q
-1 0 0 1 62.69291 744.0236 cm
-q
-BT 1 0 0 1 0 8.435 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (Readline support) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 666.0236 cm
-q
-BT 1 0 0 1 0 64.82 Tm 1.022485 Tw 12 TL /F1 10 Tf 0 0 0 rg (Starting from release 0.6 ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (offers full readline support. That means that if your Python was compiled) Tj T* 0 Tw 2.120697 Tw (with readline support you get autocompletion and persistent command history for free. By default all) Tj T* 0 Tw .144104 Tw (commands are autocomplete in a case sensitive way. If you want to add new words to the autocompletion) Tj T* 0 Tw .116488 Tw (set, or you want to change the location of the ) Tj /F4 10 Tf (.history ) Tj /F1 10 Tf (file, or to change the case sensitivity, the way to) Tj T* 0 Tw .18436 Tw (go is to pass a ) Tj /F4 10 Tf (plac.ReadlineInput ) Tj /F1 10 Tf (object to the interpreter. Here is an example, assuming you want) Tj T* 0 Tw (to build a database interface understanding SQL commands:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 321.2307 cm
-q
-q
-.96447 0 0 .96447 0 0 cm
-q
-1 0 0 1 6.6 6.843137 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 486 348 re B*
-Q
-q
-BT 1 0 0 1 0 329.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (import os, plac) Tj T* (from sqlalchemy.ext.sqlsoup import SqlSoup) Tj T*  T* (SQLKEYWORDS = set\(['select', 'from', 'inner', 'join', 'outer', 'left', 'right']) Tj T* (                  \) # and many others) Tj T* (DBTABLES = set\(['table1', 'table2']\) # you can read them from the db schema) Tj T*  T* (COMPLETIONS = SQLKEYWORDS | DBTABLES) Tj T*  T* (class SqlInterface\(object\):) Tj T* (    commands = ['SELECT']) Tj T* (    def __init__\(self, dsn\):) Tj T* (        self.soup = SqlSoup\(dsn\)) Tj T* (    def SELECT\(self, argstring\):) Tj T* (        sql = 'SELECT ' + argstring) Tj T* (        for row in self.soup.bind.execute\(sql\):) Tj T* (            yield str\(row\) # the formatting can be much improved) Tj T*  T* (rl_input = plac.ReadlineInput\() Tj T* (    COMPLETIONS, histfile=os.path.expanduser\('~/.sql_interface.history'\), ) Tj T* (    case_sensitive=False\)) Tj T*  T* (def split_on_first_space\(line, commentchar\):) Tj T* (    return line.strip\(\).split\(' ', 1\) # ignoring comments) Tj T* (    ) Tj T* (if __name__ == '__main__':) Tj T* (    plac.Interpreter.call\(SqlInterface, split=split_on_first_space,) Tj T* (                          stdin=rl_input, prompt='sql) Tj (>) Tj ( '\)) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 301.2307 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL (Here is an example of usage:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 244.0307 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 48 re B*
-Q
-q
-BT 1 0 0 1 0 29.71 Tm 12 TL /F4 10 Tf 0 0 0 rg ($ python sql_interface.py ) Tj (<) Tj (some dsn) Tj (>) Tj  T* (sql) Tj (>) Tj ( SELECT a.* FROM TABLE1 AS a INNER JOIN TABLE2 AS b ON a.id = b.id) Tj T* (...) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 164.0307 cm
-q
-BT 1 0 0 1 0 64.82 Tm 1.951318 Tw 12 TL /F1 10 Tf 0 0 0 rg (You can check that entering just ) Tj /F4 10 Tf (sel ) Tj /F1 10 Tf (and pressing TAB the readline library completes the ) Tj /F4 10 Tf (SELECT) Tj T* 0 Tw .797356 Tw /F1 10 Tf (keyword for you and makes it upper case; idem for ) Tj /F4 10 Tf (FROM) Tj /F1 10 Tf (, ) Tj /F4 10 Tf (INNER) Tj /F1 10 Tf (, ) Tj /F4 10 Tf (JOIN ) Tj /F1 10 Tf (and even for the names of the) Tj T* 0 Tw .256235 Tw (tables. An obvious improvement is to read the names of the tables by introspecting the database: actually) Tj T* 0 Tw 1.616654 Tw (you can even read the names of the views and of the columns, and have full autocompletion. All the) Tj T* 0 Tw 2.047251 Tw (entered commands and recorded and saved in the file ) Tj /F4 10 Tf (~/.sql_interface.history ) Tj /F1 10 Tf (when exiting) Tj T* 0 Tw (from the command-line interface.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 98.03071 cm
-q
-BT 1 0 0 1 0 52.82 Tm 2.010574 Tw 12 TL /F1 10 Tf 0 0 0 rg (If the readline library is not available, my suggestion is to use the ) Tj 0 0 .501961 rg (rlwrap ) Tj 0 0 0 rg (tool which provides similar ) Tj T* 0 Tw .22561 Tw (features, at least on Unix-like platforms. ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (should also work fine on Windows with the ) Tj 0 0 .501961 rg (pyreadline ) Tj 0 0 0 rg (library ) Tj T* 0 Tw .389989 Tw (\(I do not use Windows, so this part is very little tested: I tried it only once and it worked, but your mileage ) Tj T* 0 Tw 2.206457 Tw (may vary\). For people worried about licenses, I will notice that ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (uses the readline library only if ) Tj T* 0 Tw .591894 Tw (available, it does not include it and it does not rely on it in any fundamental way, so that the ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (licence) Tj T* 0 Tw ET
-Q
-Q
-q
-1 0 0 1 56.69291 56.69291 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 235.3849 0 Td (11) Tj T* -235.3849 0 Td ET
-Q
-Q
- 
-endstream
-
-endobj
-% 'R170': class PDFStream 
-170 0 obj
-% page stream
-<< /Length 4532 >>
-stream
-1 0 0 1 0 0 cm BT /F1 12 Tf 14.4 TL ET
-q
-1 0 0 1 62.69291 753.0236 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL (does not need to be the GPL \(actually it is a BSD do-whatever-you-want-with-it licence\).) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 711.0236 cm
-q
-BT 1 0 0 1 0 28.82 Tm .187882 Tw 12 TL /F1 10 Tf 0 0 0 rg (The interactive mode of ) Tj /F4 10 Tf (plac ) Tj /F1 10 Tf (can be used as a replacement of the ) Tj 0 0 .501961 rg (cmd ) Tj 0 0 0 rg (module in the standard library. It) Tj T* 0 Tw 2.730651 Tw (is actually better than ) Tj 0 0 .501961 rg (cmd) Tj 0 0 0 rg (: for instance, the ) Tj /F4 10 Tf (.help ) Tj /F1 10 Tf (command is more powerful, since it provides) Tj T* 0 Tw (information about the arguments accepted by the given command:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 401.8236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 300 re B*
-Q
-q
-BT 1 0 0 1 0 281.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (i) Tj (>) Tj ( .help set) Tj T* (usage:  set name value) Tj T*  T* (set name value) Tj T*  T* (positional arguments:) Tj T* (  name) Tj T* (  value) Tj T*  T* (i) Tj (>) Tj ( .help delete) Tj T* (usage:  delete [name]) Tj T*  T* (delete given parameter \(or everything\)) Tj T*  T* (positional arguments:) Tj T* (  name) Tj T*  T* (i) Tj (>) Tj ( .help show) Tj T* (usage:  show [names [names ...]]) Tj T*  T* (show given parameters) Tj T*  T* (positional arguments:) Tj T* (  names) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 345.8236 cm
-q
-BT 1 0 0 1 0 40.82 Tm 1.959985 Tw 12 TL /F1 10 Tf 0 0 0 rg (As you can imagine, the help message is provided by the underlying ) Tj 0 0 .501961 rg (argparse ) Tj 0 0 0 rg (subparser \(there is a) Tj T* 0 Tw 2.954524 Tw (subparser for each command\). ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (commands accept options, flags, varargs, keyword arguments,) Tj T* 0 Tw .719318 Tw (arguments with defaults, arguments with a fixed number of choices, type conversion and all the features) Tj T* 0 Tw (provided of ) Tj 0 0 .501961 rg (argparse ) Tj 0 0 0 rg (which should be reimplemented from scratch using ) Tj 0 0 .501961 rg (plac) Tj 0 0 0 rg (.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 315.8236 cm
-q
-BT 1 0 0 1 0 16.82 Tm 1.78248 Tw 12 TL /F1 10 Tf 0 0 0 rg (Moreover at the moment ) Tj /F4 10 Tf (plac ) Tj /F1 10 Tf (also understands command abbreviations. However, this feature may) Tj T* 0 Tw (disappear in future releases. It was meaningful in the past, when ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (did not support readline.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 297.8236 cm
-q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (Notice that if an abbreviation is ambiguous, ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (warns you:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 252.6236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 36 re B*
-Q
-q
-BT 1 0 0 1 0 17.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (i) Tj (>) Tj ( sh) Tj T* (NameError: Ambiguous command 'sh': matching ['showall', 'show']) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 219.6236 cm
-q
-BT 1 0 0 1 0 8.435 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (The plac runner) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 153.6236 cm
-q
-BT 1 0 0 1 0 52.82 Tm 1.531318 Tw 12 TL /F1 10 Tf 0 0 0 rg (The distribution of ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (includes a runner script named ) Tj /F4 10 Tf (plac_runner.py) Tj /F1 10 Tf (, which will be installed in a) Tj T* 0 Tw .44748 Tw (suitable directory in your system by ) Tj 0 0 .501961 rg (distutils ) Tj 0 0 0 rg (\(say in ) Tj /F4 10 Tf (\\usr\\local\\bin\\plac_runner.py ) Tj /F1 10 Tf (in a Unix-like) Tj T* 0 Tw .680651 Tw (operative system\). The runner provides many facilities to run ) Tj /F4 10 Tf (.plac ) Tj /F1 10 Tf (scripts and ) Tj /F4 10 Tf (.placet ) Tj /F1 10 Tf (files, as well) Tj T* 0 Tw 1.47311 Tw (as Python modules containg a ) Tj /F4 10 Tf (main ) Tj /F1 10 Tf (object, which can be a function, a command container object or) Tj T* 0 Tw (even a command container class.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 123.6236 cm
-q
-BT 1 0 0 1 0 16.82 Tm 1.994269 Tw 12 TL /F1 10 Tf 0 0 0 rg (For instance, suppose you want to execute a script containing commands defined in the ) Tj /F4 10 Tf (ishelve2) Tj T* 0 Tw /F1 10 Tf (module like the following one:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 56.69291 56.69291 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 235.3849 0 Td (12) Tj T* -235.3849 0 Td ET
-Q
-Q
- 
-endstream
-
-endobj
-% 'R171': class PDFStream 
-171 0 obj
-% page stream
-<< /Length 4227 >>
-stream
-1 0 0 1 0 0 cm BT /F1 12 Tf 14.4 TL ET
-q
-1 0 0 1 62.69291 703.8236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 60 re B*
-Q
-q
-0 0 0 rg
-BT 1 0 0 1 0 41.71 Tm /F4 10 Tf 12 TL (#!ishelve2.py:ShelveInterface -c ~/conf.shelve) Tj T* (set a 1) Tj T* (del a) Tj T* (del a # intentional error) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 635.8236 cm
-q
-BT 1 0 0 1 0 52.82 Tm .575868 Tw 12 TL /F1 10 Tf 0 0 0 rg (The first line of the ) Tj /F4 10 Tf (.plac ) Tj /F1 10 Tf (script contains the name of the python module containing the plac interpreter) Tj T* 0 Tw 2.327209 Tw (and the arguments which must be passed to its main function in order to be able to instantiate an) Tj T* 0 Tw .202485 Tw (interpreter object. In this case I appended ) Tj /F4 10 Tf (:ShelveInterface ) Tj /F1 10 Tf (to the name of the module to specify the) Tj T* 0 Tw 1.030574 Tw (object that must be imported: if not specified, by default the object named 'main' is imported. The other) Tj T* 0 Tw (lines contains commands. You can run the script as follows:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 546.6505 cm
-q
-q
-.952737 0 0 .952737 0 0 cm
-q
-1 0 0 1 6.6 6.927412 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 492 84 re B*
-Q
-q
-0 0 0 rg
-BT 1 0 0 1 0 65.71 Tm /F4 10 Tf 12 TL ($ plac_runner.py --batch ishelve2.plac) Tj T* (setting a=1) Tj T* (deleting a) Tj T* (Traceback \(most recent call last\):) Tj T* (  ...) Tj T* (_bsddb.DBNotFoundError: \(-30988, 'DB_NOTFOUND: No matching key/data pair found'\)) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 514.6505 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 16.82 Tm /F1 10 Tf 12 TL 2.79186 Tw (The last command intentionally contained an error, to show that the plac runner does not eat the) Tj T* 0 Tw (traceback.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 484.6505 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 16.82 Tm /F1 10 Tf 12 TL .437633 Tw (The runner can also be used to run Python modules in interactive mode and non-interactive mode. If you) Tj T* 0 Tw (put this alias in your bashrc) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 478.6505 cm
-Q
-q
-1 0 0 1 62.69291 466.6505 cm
-0 0 0 rg
-BT /F3 10 Tf 12 TL ET
-BT 1 0 0 1 0 2 Tm  T* ET
-q
-1 0 0 1 20 0 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 5.71 Tm /F4 10 Tf 12 TL (alias plac="plac_runner.py") Tj T* ET
-Q
-Q
-q
-Q
-Q
-q
-1 0 0 1 62.69291 466.6505 cm
-Q
-q
-1 0 0 1 62.69291 436.6505 cm
-q
-BT 1 0 0 1 0 16.82 Tm 2.955318 Tw 12 TL /F1 10 Tf 0 0 0 rg (\(or you define a suitable ) Tj /F4 10 Tf (plac.bat ) Tj /F1 10 Tf (script in Windows\) you can run the ) Tj /F4 10 Tf (ishelve2.py ) Tj /F1 10 Tf (script in) Tj T* 0 Tw (interactive mode as follows:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 259.4505 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 168 re B*
-Q
-q
-BT 1 0 0 1 0 149.71 Tm 12 TL /F4 10 Tf 0 0 0 rg ($ plac -i ishelve2.py) Tj T* (A minimal interface over a shelve object.) Tj T* (Operating on /home/micheles/conf.shelve.) Tj T* (.help to see the available commands.) Tj T*  T* (i) Tj (>) Tj ( del) Tj T* (deleting everything) Tj T* (i) Tj (>) Tj ( set a 1) Tj T* (setting a=1) Tj T* (i) Tj (>) Tj ( set b 2) Tj T* (setting b=2) Tj T* (i) Tj (>) Tj ( show b) Tj T* (b = 2) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 239.4505 cm
-q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (Now you can cut and paste the interactive session an turns into into a ) Tj /F4 10 Tf (.placet ) Tj /F1 10 Tf (file like the following:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 110.2505 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 120 re B*
-Q
-q
-BT 1 0 0 1 0 101.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (#!ishelve2.py:ShelveInterface -configfile=~/test.shelve) Tj T* (i) Tj (>) Tj ( del) Tj T* (deleting everything) Tj T* (i) Tj (>) Tj ( set a 1) Tj T* (setting a=1) Tj T* (i) Tj (>) Tj ( set b 2) Tj T* (setting b=2) Tj T* (i) Tj (>) Tj ( show a) Tj T* (a = 1) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 56.69291 56.69291 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 235.3849 0 Td (13) Tj T* -235.3849 0 Td ET
-Q
-Q
- 
-endstream
-
-endobj
-% 'R172': class PDFStream 
-172 0 obj
-% page stream
-<< /Length 5347 >>
-stream
-1 0 0 1 0 0 cm BT /F1 12 Tf 14.4 TL ET
-q
-1 0 0 1 62.69291 741.0236 cm
-q
-BT 1 0 0 1 0 16.82 Tm 2.145697 Tw 12 TL /F1 10 Tf 0 0 0 rg (Notice that the first line specifies a test database ) Tj /F4 10 Tf (~/test.shelve) Tj /F1 10 Tf (, to avoid clobbering your default) Tj T* 0 Tw (shelve. If you mispell the arguments in the first line plac will give you an ) Tj 0 0 .501961 rg (argparse ) Tj 0 0 0 rg (error message \(just try\).) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 723.0236 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL (You can run placets following the shebang convention directly with the plac runner:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 677.8236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 36 re B*
-Q
-q
-0 0 0 rg
-BT 1 0 0 1 0 17.71 Tm /F4 10 Tf 12 TL ($ plac --test ishelve2.placet) Tj T* (run 1 plac test\(s\)) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 633.8236 cm
-q
-BT 1 0 0 1 0 28.82 Tm .32104 Tw 12 TL /F1 10 Tf 0 0 0 rg (If you want to see the output of the tests, pass the ) Tj /F4 10 Tf (-v/--verbose ) Tj /F1 10 Tf (flag. Notice that he runner ignore the) Tj T* 0 Tw .24856 Tw (extension, so you can actually use any extension your like, but ) Tj /F5 10 Tf (it relies on the first line of the file to invoke) Tj T* 0 Tw (the corresponding plac tool with the given arguments) Tj /F1 10 Tf (.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 603.8236 cm
-q
-BT 1 0 0 1 0 16.82 Tm .537209 Tw 12 TL /F1 10 Tf 0 0 0 rg (The plac runner does not provide any test discovery facility, but you can use standard Unix tools to help.) Tj T* 0 Tw (For instance, you can run all the ) Tj /F4 10 Tf (.placet ) Tj /F1 10 Tf (files into a directory and its subdirectories as follows:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 570.6236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 24 re B*
-Q
-q
-0 0 0 rg
-BT 1 0 0 1 0 5.71 Tm /F4 10 Tf 12 TL ($ find . -name \\*.placet | xargs plac_runner.py -t) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 538.6236 cm
-q
-BT 1 0 0 1 0 16.82 Tm .760988 Tw 12 TL /F1 10 Tf 0 0 0 rg (The plac runner expects the main function of your script to return a plac tool, i.e. a function or an object) Tj T* 0 Tw (with a ) Tj /F4 10 Tf (.commands ) Tj /F1 10 Tf (attribute. It this is not the case the runner gracefully exits.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 520.6236 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL (It also works in non-interactive mode, if you call it as) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 514.6236 cm
-Q
-q
-1 0 0 1 62.69291 502.6236 cm
-0 0 0 rg
-BT /F3 10 Tf 12 TL ET
-BT 1 0 0 1 0 2 Tm  T* ET
-q
-1 0 0 1 20 0 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 5.71 Tm /F4 10 Tf 12 TL ($ plac module.py args ...) Tj T* ET
-Q
-Q
-q
-Q
-Q
-q
-1 0 0 1 62.69291 502.6236 cm
-Q
-q
-1 0 0 1 62.69291 484.6236 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL (Here is an example:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 415.4236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 60 re B*
-Q
-q
-0 0 0 rg
-BT 1 0 0 1 0 41.71 Tm /F4 10 Tf 12 TL ($ plac ishelve.py a=1) Tj T* (setting a=1) Tj T* ($ plac ishelve.py .show) Tj T* (a=1) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 383.4236 cm
-q
-BT 1 0 0 1 0 16.82 Tm .01561 Tw 12 TL /F1 10 Tf 0 0 0 rg (Notice that in non-interactive mode the runner just invokes ) Tj /F4 10 Tf (plac.call ) Tj /F1 10 Tf (on the ) Tj /F4 10 Tf (main ) Tj /F1 10 Tf (object of the Python) Tj T* 0 Tw (module.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 350.4236 cm
-q
-BT 1 0 0 1 0 8.435 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (A non class-based example) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 308.4236 cm
-q
-BT 1 0 0 1 0 28.82 Tm .907209 Tw 12 TL /F1 10 Tf 0 0 .501961 rg (plac ) Tj 0 0 0 rg (does not force you to use classes to define command containers. Even a simple function can be a) Tj T* 0 Tw 1.796651 Tw (valid command container, it is enough to add to it a ) Tj /F4 10 Tf (.commands ) Tj /F1 10 Tf (attribute and possibly ) Tj /F4 10 Tf (__enter__) Tj T* 0 Tw /F1 10 Tf (and/or ) Tj /F4 10 Tf (__exit__ ) Tj /F1 10 Tf (attributes.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 278.4236 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 16.82 Tm /F1 10 Tf 12 TL .327485 Tw (In particular, a Python module is a perfect container of commands. As an example, consider the following) Tj T* 0 Tw (module implementing a fake Version Control System:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 89.22362 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 180 re B*
-Q
-q
-0 0 0 rg
-BT 1 0 0 1 0 161.71 Tm /F4 10 Tf 12 TL ("A Fake Version Control System") Tj T*  T* (import plac) Tj T*  T* (commands = 'checkout', 'commit', 'status') Tj T*  T* (@plac.annotations\(url='url of the source code'\)) Tj T* (def checkout\(url\):) Tj T* (    "A fake checkout command") Tj T* (    return \('checkout ', url\)) Tj T*  T* (@plac.annotations\(message=\('commit message', 'option'\)\)) Tj T* (def commit\(message\):) Tj T* (    "A fake commit command") Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 56.69291 56.69291 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 235.3849 0 Td (14) Tj T* -235.3849 0 Td ET
-Q
-Q
- 
-endstream
-
-endobj
-% 'R173': class PDFStream 
-173 0 obj
-% page stream
-<< /Length 3894 >>
-stream
-1 0 0 1 0 0 cm BT /F1 12 Tf 14.4 TL ET
-q
-1 0 0 1 62.69291 559.8236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 204 re B*
-Q
-q
-0 0 0 rg
-BT 1 0 0 1 0 185.71 Tm /F4 10 Tf 12 TL (    return \('commit ', message\)) Tj T*  T* (@plac.annotations\(quiet=\('summary information', 'flag', 'q'\)\)) Tj T* (def status\(quiet\):) Tj T* (    "A fake status command") Tj T* (    return \('status ', quiet\)) Tj T*  T* (def __missing__\(name\):) Tj T* (    return 'Command %r does not exist' % name) Tj T*  T* (def __exit__\(etype, exc, tb\):) Tj T* (    "Will be called automatically at the end of the call/cmdloop") Tj T* (    if etype in \(None, GeneratorExit\): # success) Tj T* (        print\('ok'\)) Tj T*  T* (main = __import__\(__name__\) # the module imports itself!) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 515.8236 cm
-q
-BT 1 0 0 1 0 28.82 Tm .431318 Tw 12 TL /F1 10 Tf 0 0 0 rg (Notice that I have defined both an ) Tj /F4 10 Tf (__exit__ ) Tj /F1 10 Tf (hook and a ) Tj /F4 10 Tf (__missing__ ) Tj /F1 10 Tf (hook, invoked for non-existing) Tj T* 0 Tw .592651 Tw (commands. The real trick here is the line ) Tj /F4 10 Tf (main = __import__\(__name__\)) Tj /F1 10 Tf (, which define ) Tj /F4 10 Tf (main ) Tj /F1 10 Tf (to be) Tj T* 0 Tw (an alias for the current module.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 485.8236 cm
-q
-BT 1 0 0 1 0 16.82 Tm 1.259986 Tw 12 TL /F1 10 Tf 0 0 0 rg (The ) Tj /F4 10 Tf (vcs ) Tj /F1 10 Tf (module does not contain an ) Tj /F4 10 Tf (if __name__ == '__main__' ) Tj /F1 10 Tf (block, but you can still run it) Tj T* 0 Tw (through the plac runner \(try ) Tj /F4 10 Tf (plac vcs.py -h) Tj /F1 10 Tf (\):) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 344.6236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 132 re B*
-Q
-q
-0 0 0 rg
-BT 1 0 0 1 0 113.71 Tm /F4 10 Tf 12 TL (usage: plac_runner.py vcs.py [-h] {status,commit,checkout} ...) Tj T*  T* (A Fake Version Control System) Tj T*  T* (optional arguments:) Tj T* (  -h, --help            show this help message and exit) Tj T*  T* (subcommands:) Tj T* (  {status,commit,checkout}) Tj T* (                        -h to get additional help) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 324.6236 cm
-q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (You can get help for the subcommands by postponing ) Tj /F4 10 Tf (-h ) Tj /F1 10 Tf (after the name of the command:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 207.4236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 108 re B*
-Q
-q
-0 0 0 rg
-BT 1 0 0 1 0 89.71 Tm /F4 10 Tf 12 TL ($ plac vcs.py status -h) Tj T* (usage: vcs.py status [-h] [-q]) Tj T*  T* (A fake status command) Tj T*  T* (optional arguments:) Tj T* (  -h, --help   show this help message and exit) Tj T* (  -q, --quiet  summary information) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 175.4236 cm
-q
-BT 1 0 0 1 0 16.82 Tm 2.064985 Tw 12 TL /F1 10 Tf 0 0 0 rg (Notice how the docstring of the command is automatically shown in usage message, as well as the) Tj T* 0 Tw (documentation for the sub flag ) Tj /F4 10 Tf (-q) Tj /F1 10 Tf (.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 157.4236 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL (Here is an example of a non-interactive session:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 100.2236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 48 re B*
-Q
-q
-0 0 0 rg
-BT 1 0 0 1 0 29.71 Tm /F4 10 Tf 12 TL ($ plac vcs.py check url) Tj T* (checkout) Tj T* (url) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 56.69291 56.69291 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 235.3849 0 Td (15) Tj T* -235.3849 0 Td ET
-Q
-Q
- 
-endstream
-
-endobj
-% 'R174': class PDFStream 
-174 0 obj
-% page stream
-<< /Length 5650 >>
-stream
-1 0 0 1 0 0 cm BT /F1 12 Tf 14.4 TL ET
-q
-1 0 0 1 62.69291 679.8236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 84 re B*
-Q
-q
-0 0 0 rg
-BT 1 0 0 1 0 65.71 Tm /F4 10 Tf 12 TL ($ plac vcs.py st -q) Tj T* (status) Tj T* (True) Tj T* ($ plac vcs.py co) Tj T* (commit) Tj T* (None) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 659.8236 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL (and here is an interactive session:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 458.6236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 192 re B*
-Q
-q
-BT 1 0 0 1 0 173.71 Tm 12 TL /F4 10 Tf 0 0 0 rg ($ plac -i vcs.py) Tj T* (usage: plac_runner.py vcs.py [-h] {status,commit,checkout} ...) Tj T* (i) Tj (>) Tj ( check url) Tj T* (checkout) Tj T* (url) Tj T* (i) Tj (>) Tj ( st -q) Tj T* (status) Tj T* (True) Tj T* (i) Tj (>) Tj ( co) Tj T* (commit) Tj T* (None) Tj T* (i) Tj (>) Tj ( sto) Tj T* (Command 'sto' does not exist) Tj T* (i) Tj (>) Tj ( [CTRL-D]) Tj T* (ok) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 426.6236 cm
-q
-BT 1 0 0 1 0 16.82 Tm 2.986905 Tw 12 TL /F1 10 Tf 0 0 0 rg (Notice the invocation of the ) Tj /F4 10 Tf (__missing__ ) Tj /F1 10 Tf (hook for non-existing commands. Notice also that the) Tj T* 0 Tw /F4 10 Tf (__exit__ ) Tj /F1 10 Tf (hook gets called only in interactive mode.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 396.6236 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 16.82 Tm /F1 10 Tf 12 TL 1.614104 Tw (If the commands are completely independent, a module is a good fit for a method container. In other) Tj T* 0 Tw (situations, it is best to use a custom class.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 363.6236 cm
-q
-BT 1 0 0 1 0 8.435 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (Writing your own plac runner) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 309.6236 cm
-q
-BT 1 0 0 1 0 40.82 Tm .167209 Tw 12 TL /F1 10 Tf 0 0 0 rg (The runner included in the ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (distribution is intentionally kept small \(around 50 lines of code\) so that you) Tj T* 0 Tw .081294 Tw (can study it and write your own runner if want to. If you need to go to such level of detail, you should know) Tj T* 0 Tw .42061 Tw (that the most important method of the ) Tj /F4 10 Tf (Interpreter ) Tj /F1 10 Tf (class is the ) Tj /F4 10 Tf (.send ) Tj /F1 10 Tf (method, which takes strings in) Tj T* 0 Tw (input and returns a four-tuple with attributes ) Tj /F4 10 Tf (.str) Tj /F1 10 Tf (, ) Tj /F4 10 Tf (.etype) Tj /F1 10 Tf (, ) Tj /F4 10 Tf (.exc ) Tj /F1 10 Tf (and ) Tj /F4 10 Tf (.tb) Tj /F1 10 Tf (:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 303.6236 cm
-Q
-q
-1 0 0 1 62.69291 303.6236 cm
-Q
-q
-1 0 0 1 62.69291 285.6236 cm
-0 0 0 rg
-BT /F3 10 Tf 12 TL ET
-q
-1 0 0 1 6 3 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 10.5 0 Td (\177) Tj T* -10.5 0 Td ET
-Q
-Q
-q
-1 0 0 1 23 3 cm
-q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F4 10 Tf 0 0 0 rg (.str ) Tj /F1 10 Tf (is the output of the command, if successful \(a string\);) Tj T* ET
-Q
-Q
-q
-Q
-Q
-q
-1 0 0 1 62.69291 285.6236 cm
-Q
-q
-1 0 0 1 62.69291 285.6236 cm
-Q
-q
-1 0 0 1 62.69291 267.6236 cm
-0 0 0 rg
-BT /F3 10 Tf 12 TL ET
-q
-1 0 0 1 6 3 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 10.5 0 Td (\177) Tj T* -10.5 0 Td ET
-Q
-Q
-q
-1 0 0 1 23 3 cm
-q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F4 10 Tf 0 0 0 rg (.etype ) Tj /F1 10 Tf (is the class of the exception, if the command fail;) Tj T* ET
-Q
-Q
-q
-Q
-Q
-q
-1 0 0 1 62.69291 267.6236 cm
-Q
-q
-1 0 0 1 62.69291 267.6236 cm
-Q
-q
-1 0 0 1 62.69291 249.6236 cm
-0 0 0 rg
-BT /F3 10 Tf 12 TL ET
-q
-1 0 0 1 6 3 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 10.5 0 Td (\177) Tj T* -10.5 0 Td ET
-Q
-Q
-q
-1 0 0 1 23 3 cm
-q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F4 10 Tf 0 0 0 rg (.exc ) Tj /F1 10 Tf (is the exception instance;) Tj T* ET
-Q
-Q
-q
-Q
-Q
-q
-1 0 0 1 62.69291 249.6236 cm
-Q
-q
-1 0 0 1 62.69291 249.6236 cm
-Q
-q
-1 0 0 1 62.69291 231.6236 cm
-0 0 0 rg
-BT /F3 10 Tf 12 TL ET
-q
-1 0 0 1 6 3 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 10.5 0 Td (\177) Tj T* -10.5 0 Td ET
-Q
-Q
-q
-1 0 0 1 23 3 cm
-q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F4 10 Tf 0 0 0 rg (.tb ) Tj /F1 10 Tf (is the traceback.) Tj T* ET
-Q
-Q
-q
-Q
-Q
-q
-1 0 0 1 62.69291 231.6236 cm
-Q
-q
-1 0 0 1 62.69291 231.6236 cm
-Q
-q
-1 0 0 1 62.69291 189.6236 cm
-q
-BT 1 0 0 1 0 28.82 Tm .937485 Tw 12 TL /F1 10 Tf 0 0 0 rg (Moreover the ) Tj /F4 10 Tf (__str__ ) Tj /F1 10 Tf (representation of the output object is redefined to return the output string if the) Tj T* 0 Tw 2.686651 Tw (command was successful or the error message if the command failed \(actually it returns the error) Tj T* 0 Tw (message preceded by the name of the exception class\).) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 171.6236 cm
-q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (For instance, if you send a mispelled option to the interpreter a ) Tj /F4 10 Tf (SystemExit ) Tj /F1 10 Tf (will be trapped:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 90.42362 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 72 re B*
-Q
-q
-BT 1 0 0 1 0 53.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (>) Tj (>) Tj (>) Tj ( import plac) Tj T* (>) Tj (>) Tj (>) Tj ( from ishelve import ishelve) Tj T* (>) Tj (>) Tj (>) Tj ( with plac.Interpreter\(ishelve\) as i:) Tj T* (...     print\(i.send\('.cler'\)\)) Tj T* (...) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 56.69291 56.69291 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 235.3849 0 Td (16) Tj T* -235.3849 0 Td ET
-Q
-Q
- 
-endstream
-
-endobj
-% 'R175': class PDFStream 
-175 0 obj
-% page stream
-<< /Length 5042 >>
-stream
-1 0 0 1 0 0 cm BT /F1 12 Tf 14.4 TL ET
-q
-1 0 0 1 62.69291 739.8236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 24 re B*
-Q
-q
-BT 1 0 0 1 0 5.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (SystemExit: unrecognized arguments: .cler) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 707.8236 cm
-q
-BT 1 0 0 1 0 16.82 Tm 2.90561 Tw 12 TL /F1 10 Tf 0 0 0 rg (It is important to invoke the ) Tj /F4 10 Tf (.send ) Tj /F1 10 Tf (method inside the context manager, otherwise you will get a) Tj T* 0 Tw /F4 10 Tf (RuntimeError) Tj /F1 10 Tf (.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 665.8236 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 28.82 Tm /F1 10 Tf 12 TL .29311 Tw (For instance, suppose you want to implement a graphical runner for a plac-based interpreter with two text) Tj T* 0 Tw 1.548221 Tw (widgets: one to enter the commands and one to display the results. Suppose you want to display the) Tj T* 0 Tw (errors with tracebacks in red. You will need to code something like that \(pseudocode follows\):) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 428.6236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 228 re B*
-Q
-q
-0 0 0 rg
-BT 1 0 0 1 0 209.71 Tm /F4 10 Tf 12 TL (input_widget = WidgetReadingInput\(\)) Tj T* (output_widget = WidgetDisplayingOutput\(\)) Tj T*  T* (def send\(interpreter, line\):) Tj T* (    out = interpreter.send\(line\)) Tj T* (    if out.tb: # there was an error) Tj T* (        output_widget.display\(out.tb, color='red'\)) Tj T* (    else:) Tj T* (        output_widget.display\(out.str\)) Tj T*  T* (main = plac.import_main\(tool_path\) # get the main object) Tj T*  T* (with plac.Interpreter\(main\) as i:) Tj T* (   def callback\(event\):) Tj T* (      if event.user_pressed_ENTER\(\):) Tj T* (           send\(i, input_widget.last_line\)) Tj T* (   input_widget.addcallback\(callback\)) Tj T* (   gui_mainloop.start\(\)) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 396.6236 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 16.82 Tm /F1 10 Tf 12 TL .102765 Tw (You can adapt the pseudocode to your GUI toolkit of choice and you can also change the file associations) Tj T* 0 Tw (in such a way that clicking on a plac tool file the graphical user interface starts.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 366.6236 cm
-q
-BT 1 0 0 1 0 16.82 Tm .259988 Tw 12 TL /F1 10 Tf 0 0 0 rg (An example of GUI program built on top of ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (is given later on, in the paragraph ) Tj /F5 10 Tf (Managing the output of) Tj T* 0 Tw (concurrent commands ) Tj /F1 10 Tf (\(using Tkinter for simplicity and portability\).) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 312.6236 cm
-q
-BT 1 0 0 1 0 40.82 Tm 2.090651 Tw 12 TL /F1 10 Tf 0 0 0 rg (There is a final ) Tj /F5 10 Tf (caveat) Tj /F1 10 Tf (: since the plac interpreter loop is implemented via extended generators, plac) Tj T* 0 Tw .988651 Tw (interpreters are single threaded: you will get an error if you ) Tj /F4 10 Tf (.send ) Tj /F1 10 Tf (commands from separated threads.) Tj T* 0 Tw .947882 Tw (You can circumvent the problem by using a queue. If EXIT is a sentinel value to signal exiting from the) Tj T* 0 Tw (interpreter look, you can write code like this:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 255.4236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 48 re B*
-Q
-q
-0 0 0 rg
-BT 1 0 0 1 0 29.71 Tm /F4 10 Tf 12 TL (with interpreter:) Tj T* (    for input_value in iter\(input_queue.get, EXIT\):) Tj T* (        output_queue.put\(interpreter.send\(input_value\)\)) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 223.4236 cm
-q
-BT 1 0 0 1 0 16.82 Tm .106098 Tw 12 TL /F1 10 Tf 0 0 0 rg (The same trick also work for processes; you could run the interpreter loop in a separate process and send) Tj T* 0 Tw (commands to it via the Queue class provided by the ) Tj 0 0 .501961 rg (multiprocessing ) Tj 0 0 0 rg (module.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 190.4236 cm
-q
-BT 1 0 0 1 0 8.435 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (Long running commands) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 148.4236 cm
-q
-BT 1 0 0 1 0 28.82 Tm 1.434431 Tw 12 TL /F1 10 Tf 0 0 0 rg (As we saw, by default a ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (interpreter blocks until the command terminates. This is an issue, in the) Tj T* 0 Tw 1.201318 Tw (sense that it makes the interactive experience quite painful for long running commands. An example is) Tj T* 0 Tw (better than a thousand words, so consider the following fake importer:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 91.22362 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 48 re B*
-Q
-q
-0 0 0 rg
-BT 1 0 0 1 0 29.71 Tm /F4 10 Tf 12 TL (import time) Tj T* (import plac) Tj T*  T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 56.69291 56.69291 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 235.3849 0 Td (17) Tj T* -235.3849 0 Td ET
-Q
-Q
- 
-endstream
-
-endobj
-% 'R176': class PDFStream 
-176 0 obj
-% page stream
-<< /Length 4422 >>
-stream
-1 0 0 1 0 0 cm BT /F1 12 Tf 14.4 TL ET
-q
-1 0 0 1 62.69291 547.8236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 216 re B*
-Q
-q
-0 0 0 rg
-BT 1 0 0 1 0 197.71 Tm /F4 10 Tf 12 TL (class FakeImporter\(object\):) Tj T* (    "A fake importer with an import_file command") Tj T* (    commands = ['import_file']) Tj T* (    def __init__\(self, dsn\):) Tj T* (        self.dsn = dsn) Tj T* (    def import_file\(self, fname\):) Tj T* (        "Import a file into the database") Tj T* (        try:) Tj T* (            for n in range\(10000\):) Tj T* (                time.sleep\(.01\)) Tj T* (                if n % 100 == 99:) Tj T* (                    yield 'Imported %d lines' % \(n+1\)) Tj T* (        finally:) Tj T* (            print\('closing the file'\)) Tj T*  T* (if __name__ == '__main__':) Tj T* (    plac.Interpreter.call\(FakeImporter\)) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 515.8236 cm
-q
-BT 1 0 0 1 0 16.82 Tm 1.466457 Tw 12 TL /F1 10 Tf 0 0 0 rg (If you run the ) Tj /F4 10 Tf (import_file ) Tj /F1 10 Tf (command, you will have to wait for 200 seconds before entering a new) Tj T* 0 Tw (command:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 374.6236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 132 re B*
-Q
-q
-BT 1 0 0 1 0 113.71 Tm 12 TL /F4 10 Tf 0 0 0 rg ($ python importer1.py dsn) Tj T* (A fake importer with an import_file command) Tj T* (i) Tj (>) Tj ( import_file file1) Tj T* (... ) Tj (<) Tj (wait 3+ minutes) Tj (>) Tj  T* (Imported 100 lines) Tj T* (Imported 200 lines) Tj T* (Imported 300 lines) Tj T* (...) Tj T* (Imported 10000 lines) Tj T* (closing the file) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 330.6236 cm
-q
-BT 1 0 0 1 0 28.82 Tm .96832 Tw 12 TL /F1 10 Tf 0 0 0 rg (Being unable to enter any other command is quite annoying: in such situation one would like to run the) Tj T* 0 Tw .941318 Tw (long running commands in the background, to keep the interface responsive. ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (provides two ways to) Tj T* 0 Tw (reach this goal: threads and processes.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 297.6236 cm
-q
-BT 1 0 0 1 0 8.435 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (Threaded commands) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 267.6236 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 16.82 Tm /F1 10 Tf 12 TL .317988 Tw (The most familiar way to execute a task in the background \(even if not necessarily the best way\) is to run) Tj T* 0 Tw (it into a separated thread. In our example it is sufficient to replace the line) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 261.6236 cm
-Q
-q
-1 0 0 1 62.69291 249.6236 cm
-0 0 0 rg
-BT /F3 10 Tf 12 TL ET
-BT 1 0 0 1 0 2 Tm  T* ET
-q
-1 0 0 1 20 0 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 5.71 Tm /F4 10 Tf 12 TL (commands = ['import_file']) Tj T* ET
-Q
-Q
-q
-Q
-Q
-q
-1 0 0 1 62.69291 249.6236 cm
-Q
-q
-1 0 0 1 62.69291 231.6236 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL (with) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 225.6236 cm
-Q
-q
-1 0 0 1 62.69291 213.6236 cm
-0 0 0 rg
-BT /F3 10 Tf 12 TL ET
-BT 1 0 0 1 0 2 Tm  T* ET
-q
-1 0 0 1 20 0 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 5.71 Tm /F4 10 Tf 12 TL (thcommands = ['import_file']) Tj T* ET
-Q
-Q
-q
-Q
-Q
-q
-1 0 0 1 62.69291 213.6236 cm
-Q
-q
-1 0 0 1 62.69291 183.6236 cm
-q
-BT 1 0 0 1 0 16.82 Tm 1.38311 Tw 12 TL /F1 10 Tf 0 0 0 rg (to tell to the ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (interpreter that the command ) Tj /F4 10 Tf (import_file ) Tj /F1 10 Tf (should be run into a separated thread.) Tj T* 0 Tw (Here is an example session:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 138.4236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 36 re B*
-Q
-q
-BT 1 0 0 1 0 17.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (i) Tj (>) Tj ( import_file file1) Tj T* (<) Tj (ThreadedTask 1 [import_file file1] RUNNING) Tj (>) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 106.4236 cm
-q
-BT 1 0 0 1 0 16.82 Tm .595777 Tw 12 TL /F1 10 Tf 0 0 0 rg (The import task started in a separated thread. You can see the progress of the task by using the special) Tj T* 0 Tw (command ) Tj /F4 10 Tf (.output) Tj /F1 10 Tf (:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 56.69291 56.69291 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 235.3849 0 Td (18) Tj T* -235.3849 0 Td ET
-Q
-Q
- 
-endstream
-
-endobj
-% 'R177': class PDFStream 
-177 0 obj
-% page stream
-<< /Length 4933 >>
-stream
-1 0 0 1 0 0 cm BT /F1 12 Tf 14.4 TL ET
-q
-1 0 0 1 62.69291 703.8236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 60 re B*
-Q
-q
-BT 1 0 0 1 0 41.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (i) Tj (>) Tj ( .output 1) Tj T* (<) Tj (ThreadedTask 1 [import_file file1] RUNNING) Tj (>) Tj  T* (Imported 100 lines) Tj T* (Imported 200 lines) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 683.8236 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL (If you look after a while, you will get more lines of output:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 590.6236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 84 re B*
-Q
-q
-BT 1 0 0 1 0 65.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (i) Tj (>) Tj ( .output 1) Tj T* (<) Tj (ThreadedTask 1 [import_file file1] RUNNING) Tj (>) Tj  T* (Imported 100 lines) Tj T* (Imported 200 lines) Tj T* (Imported 300 lines) Tj T* (Imported 400 lines) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 570.6236 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL (If you look after a time long enough, the task will be finished:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 525.4236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 36 re B*
-Q
-q
-BT 1 0 0 1 0 17.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (i) Tj (>) Tj ( .output 1) Tj T* (<) Tj (ThreadedTask 1 [import_file file1] FINISHED) Tj (>) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 493.4236 cm
-q
-BT 1 0 0 1 0 16.82 Tm 1.045868 Tw 12 TL /F1 10 Tf 0 0 0 rg (You can even skip the number argument: then ) Tj /F4 10 Tf (.output ) Tj /F1 10 Tf (will the return the output of the last launched) Tj T* 0 Tw (command \(the special commands like .output do not count\).) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 475.4236 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL (You can launch many tasks one after the other:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 406.2236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 60 re B*
-Q
-q
-BT 1 0 0 1 0 41.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (i) Tj (>) Tj ( import_file file2) Tj T* (<) Tj (ThreadedTask 5 [import_file file2] RUNNING) Tj (>) Tj  T* (i) Tj (>) Tj ( import_file file3) Tj T* (<) Tj (ThreadedTask 6 [import_file file3] RUNNING) Tj (>) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 386.2236 cm
-q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (The ) Tj /F4 10 Tf (.list ) Tj /F1 10 Tf (command displays all the running tasks:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 329.0236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 48 re B*
-Q
-q
-BT 1 0 0 1 0 29.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (i) Tj (>) Tj ( .list) Tj T* (<) Tj (ThreadedTask 5 [import_file file2] RUNNING) Tj (>) Tj  T* (<) Tj (ThreadedTask 6 [import_file file3] RUNNING) Tj (>) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 309.0236 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL (It is even possible to kill a task:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 215.8236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 84 re B*
-Q
-q
-BT 1 0 0 1 0 65.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (i) Tj (>) Tj ( .kill 5) Tj T* (<) Tj (ThreadedTask 5 [import_file file2] TOBEKILLED) Tj (>) Tj  T* (# wait a bit ...) Tj T* (closing the file) Tj T* (i) Tj (>) Tj ( .output 5) Tj T* (<) Tj (ThreadedTask 5 [import_file file2] KILLED) Tj (>) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 123.8236 cm
-q
-BT 1 0 0 1 0 76.82 Tm 1.100542 Tw 12 TL /F1 10 Tf 0 0 0 rg (You should notice that since at the Python level it is impossible to kill a thread, the ) Tj /F4 10 Tf (.kill ) Tj /F1 10 Tf (commands) Tj T* 0 Tw 1.793984 Tw (works by setting the status of the task to ) Tj /F4 10 Tf (TOBEKILLED) Tj /F1 10 Tf (. Internally the generator corresponding to the) Tj T* 0 Tw .632927 Tw (command is executed in the thread and the status is checked at each iteration: when the status become) Tj T* 0 Tw 2.578443 Tw /F4 10 Tf (TOBEKILLED ) Tj /F1 10 Tf (a ) Tj /F4 10 Tf (GeneratorExit ) Tj /F1 10 Tf (exception is raised and the thread terminates \(softly, so that the) Tj T* 0 Tw 2.328651 Tw /F4 10 Tf (finally ) Tj /F1 10 Tf (clause is honored\). In our example the generator is yielding back control once every 100) Tj T* 0 Tw 1.152619 Tw (iterations, i.e. every two seconds \(not much\). In order to get a responsive interface it is a good idea to) Tj T* 0 Tw (yield more often, for instance every 10 iterations \(i.e. 5 times per second\), as in the following code:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 56.69291 56.69291 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 235.3849 0 Td (19) Tj T* -235.3849 0 Td ET
-Q
-Q
- 
-endstream
-
-endobj
-% 'R178': class PDFStream 
-178 0 obj
-% page stream
-<< /Length 4294 >>
-stream
-1 0 0 1 0 0 cm BT /F1 12 Tf 14.4 TL ET
-q
-1 0 0 1 62.69291 487.8236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 276 re B*
-Q
-q
-0 0 0 rg
-BT 1 0 0 1 0 257.71 Tm /F4 10 Tf 12 TL (import time) Tj T* (import plac) Tj T*  T* (class FakeImporter\(object\):) Tj T* (    "A fake importer with an import_file command") Tj T* (    thcommands = ['import_file']) Tj T* (    def __init__\(self, dsn\):) Tj T* (        self.dsn = dsn) Tj T* (    def import_file\(self, fname\):) Tj T* (        "Import a file into the database") Tj T* (        try:) Tj T* (            for n in range\(10000\):) Tj T* (                time.sleep\(.02\)) Tj T* (                if n % 100 == 99: # every two seconds) Tj T* (                    yield 'Imported %d lines' % \(n+1\)) Tj T* (                if n % 10 == 9: # every 0.2 seconds) Tj T* (                    yield # go back and check the TOBEKILLED status) Tj T* (        finally:) Tj T* (            print\('closing the file'\)) Tj T*  T* (if __name__ == '__main__':) Tj T* (    plac.Interpreter.call\(FakeImporter\)) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 454.8236 cm
-q
-BT 1 0 0 1 0 8.435 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (Running commands as external processes) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 400.8236 cm
-q
-BT 1 0 0 1 0 40.82 Tm 2.30686 Tw 12 TL /F1 10 Tf 0 0 0 rg (Threads are not loved much in the Python world and actually most people prefer to use processes) Tj T* 0 Tw 3.350697 Tw (instead. For this reason ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (provides the option to execute long running commands as external) Tj T* 0 Tw .632706 Tw (processes. Unfortunately the current implementation only works in Unix-like operating systems \(including) Tj T* 0 Tw (Mac OS X\) because it relies on fork via the ) Tj 0 0 .501961 rg (multiprocessing ) Tj 0 0 0 rg (module.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 382.8236 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL (In our example, to enable the feature it is sufficient to replace the line) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 376.8236 cm
-Q
-q
-1 0 0 1 62.69291 364.8236 cm
-0 0 0 rg
-BT /F3 10 Tf 12 TL ET
-BT 1 0 0 1 0 2 Tm  T* ET
-q
-1 0 0 1 20 0 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 5.71 Tm /F4 10 Tf 12 TL (thcommands = ['import_file']) Tj T* ET
-Q
-Q
-q
-Q
-Q
-q
-1 0 0 1 62.69291 364.8236 cm
-Q
-q
-1 0 0 1 62.69291 346.8236 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL (with) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 340.8236 cm
-Q
-q
-1 0 0 1 62.69291 328.8236 cm
-0 0 0 rg
-BT /F3 10 Tf 12 TL ET
-BT 1 0 0 1 0 2 Tm  T* ET
-q
-1 0 0 1 20 0 cm
-q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F4 10 Tf 0 0 0 rg (mpcommands = ['import_file']) Tj /F1 10 Tf (.) Tj T* ET
-Q
-Q
-q
-Q
-Q
-q
-1 0 0 1 62.69291 328.8236 cm
-Q
-q
-1 0 0 1 62.69291 298.8236 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 16.82 Tm /F1 10 Tf 12 TL .772619 Tw (The user experience is exactly the same as with threads and you will not see any difference at the user) Tj T* 0 Tw (interface level:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 157.6236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 132 re B*
-Q
-q
-BT 1 0 0 1 0 113.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (i) Tj (>) Tj ( import_file file3) Tj T* (<) Tj (MPTask 1 [import_file file3] SUBMITTED) Tj (>) Tj  T* (i) Tj (>) Tj ( .kill 1) Tj T* (<) Tj (MPTask 1 [import_file file3] RUNNING) Tj (>) Tj  T* (closing the file) Tj T* (i) Tj (>) Tj ( .o 1) Tj T* (<) Tj (MPTask 1 [import_file file3] KILLED) Tj (>) Tj  T* (Imported 100 lines) Tj T* (Imported 200 lines) Tj T* (i) Tj (>) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 101.6236 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 40.82 Tm /F1 10 Tf 12 TL 1.201318 Tw (Still, using processes is quite different than using threads: in particular, when using processes you can) Tj T* 0 Tw 2.313318 Tw (only yield pickleable values and you cannot re-raise an exception first raised in a different process,) Tj T* 0 Tw 1.445697 Tw (because traceback objects are not pickleable. Moreover, you cannot rely on automatic sharing of your) Tj T* 0 Tw (objects.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 56.69291 56.69291 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 235.3849 0 Td (20) Tj T* -235.3849 0 Td ET
-Q
-Q
- 
-endstream
-
-endobj
-% 'R179': class PDFStream 
-179 0 obj
-% page stream
-<< /Length 4183 >>
-stream
-1 0 0 1 0 0 cm BT /F1 12 Tf 14.4 TL ET
-q
-1 0 0 1 62.69291 717.0236 cm
-q
-BT 1 0 0 1 0 40.82 Tm .128935 Tw 12 TL /F1 10 Tf 0 0 0 rg (On the plus side, when using processes you do not need to worry about killing a command: they are killed) Tj T* 0 Tw .466412 Tw (immediately using a SIGTERM signal, and there is not a ) Tj /F4 10 Tf (TOBEKILLED ) Tj /F1 10 Tf (mechanism. Moreover, the killing) Tj T* 0 Tw 1.50229 Tw (is guaranteed to be soft: internally a command receiving a SIGTERM raises a ) Tj /F4 10 Tf (TerminatedProcess) Tj T* 0 Tw /F1 10 Tf (exception which is trapped in the generator loop, so that the command is closed properly.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 687.0236 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 16.82 Tm /F1 10 Tf 12 TL .242927 Tw (Using processes allows to take full advantage of multicore machines and it is safer than using threads, so) Tj T* 0 Tw (it is the recommended approach unless you are working on Windows.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 654.0236 cm
-q
-BT 1 0 0 1 0 8.435 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (Managing the output of concurrent commands) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 552.0236 cm
-q
-BT 1 0 0 1 0 88.82 Tm 1.895542 Tw 12 TL /F1 10 Tf 0 0 .501961 rg (plac ) Tj 0 0 0 rg (acts as a command-line task launcher and can be used as the base to build a GUI-based task) Tj T* 0 Tw .38561 Tw (launcher and task monitor. To this aim the interpreter class provides a ) Tj /F4 10 Tf (.submit ) Tj /F1 10 Tf (method which returns a) Tj T* 0 Tw 1.792339 Tw (task object and a ) Tj /F4 10 Tf (.tasks ) Tj /F1 10 Tf (method returning the list of all the tasks submitted to the interpreter. The) Tj T* 0 Tw .373516 Tw /F4 10 Tf (submit ) Tj /F1 10 Tf (method does not start the task and thus it is nonblocking. Each task has an ) Tj /F4 10 Tf (.outlist ) Tj /F1 10 Tf (attribute) Tj T* 0 Tw .106098 Tw (which is a list storing the value yielded by the generator underlying the task \(the ) Tj /F4 10 Tf (None ) Tj /F1 10 Tf (values are skipped) Tj T* 0 Tw .633318 Tw (though\): the ) Tj /F4 10 Tf (.outlist ) Tj /F1 10 Tf (grows as the task runs and more values are yielded. Accessing the ) Tj /F4 10 Tf (.outlist) Tj T* 0 Tw 1.051654 Tw /F1 10 Tf (is nonblocking and can be done freely. Finally there is a ) Tj /F4 10 Tf (.result ) Tj /F1 10 Tf (property which waits for the task to) Tj T* 0 Tw (finish and returns the last yielded value or raises an exception.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 522.0236 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 16.82 Tm /F1 10 Tf 12 TL .014692 Tw (Here is some example code to visualize the output of the FakeImporter in Tkinter \(I chose Tkinter because) Tj T* 0 Tw (it is easy to use and it is in the standard library, but you can use any GUI\):) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 152.8236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 360 re B*
-Q
-q
-0 0 0 rg
-BT 1 0 0 1 0 341.71 Tm /F4 10 Tf 12 TL (from Tkinter import *) Tj T* (from importer3 import FakeImporter) Tj T*  T* (def taskwidget\(root, task, tick=500\):) Tj T* (    "A Label widget showing the output of a task every 500 ms") Tj T* (    sv = StringVar\(root\)) Tj T* (    lb = Label\(root, textvariable=sv\)) Tj T* (    def show_outlist\(\):) Tj T* (        try:) Tj T* (            out = task.outlist[-1]) Tj T* (        except IndexError: # no output yet) Tj T* (            out = '') Tj T* (        sv.set\('%s %s' % \(task, out\)\)) Tj T* (        root.after\(tick, show_outlist\)) Tj T* (    root.after\(0, show_outlist\)) Tj T* (    return lb) Tj T*  T* (def monitor\(tasks\):) Tj T* (    root = Tk\(\)) Tj T* (    for task in tasks:) Tj T* (        task.run\(\)) Tj T* (        taskwidget\(root, task\).pack\(\)) Tj T* (    root.mainloop\(\)) Tj T*  T* (if __name__ == '__main__':) Tj T* (    import plac) Tj T* (    with plac.Interpreter\(plac.call\(FakeImporter\)\) as i:) Tj T* (        tasks = [i.submit\('import_file f1'\), i.submit\('import_file f2'\)]) Tj T* (        monitor\(tasks\)) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 56.69291 56.69291 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 235.3849 0 Td (21) Tj T* -235.3849 0 Td ET
-Q
-Q
- 
-endstream
-
-endobj
-% 'R180': class PDFStream 
-180 0 obj
-% page stream
-<< /Length 4670 >>
-stream
-1 0 0 1 0 0 cm BT /F1 12 Tf 14.4 TL ET
-q
-1 0 0 1 62.69291 744.0236 cm
-q
-BT 1 0 0 1 0 8.435 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (Parallel computing with plac) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 630.0236 cm
-q
-BT 1 0 0 1 0 100.82 Tm 1.174751 Tw 12 TL /F1 10 Tf 0 0 .501961 rg (plac ) Tj 0 0 0 rg (is certainly not intended as a tool for parallel computing, but still you can use it to launch a set of) Tj T* 0 Tw .494269 Tw (commands and to collect the results, similarly to the MapReduce pattern recently popularized by Google.) Tj T* 0 Tw .329431 Tw (In order to give an example, I will consider the "Hello World" of parallel computing, i.e. the computation of) Tj T* 0 Tw .229431 Tw (pi with independent processes. There is a huge number of algorithms to compute pi; here I will describe a) Tj T* 0 Tw .30683 Tw (trivial one chosen for simplicity, not per efficienty. The trick is to consider the first quadrant of a circle with) Tj T* 0 Tw .102488 Tw (radius 1 and to extract a number of points ) Tj /F4 10 Tf (\(x, y\) ) Tj /F1 10 Tf (with ) Tj /F4 10 Tf (x ) Tj /F1 10 Tf (and ) Tj /F4 10 Tf (y ) Tj /F1 10 Tf (random variables in the interval ) Tj /F4 10 Tf ([0,1]) Tj /F1 10 Tf (.) Tj T* 0 Tw .743876 Tw (The probability of extracting a number inside the quadrant \(i.e. with ) Tj /F4 10 Tf (x^2 + y^2 < 1) Tj /F1 10 Tf (\) is proportional to) Tj T* 0 Tw .725251 Tw (the area of the quadrant \(i.e. ) Tj /F4 10 Tf (pi/4) Tj /F1 10 Tf (\). The value of ) Tj /F4 10 Tf (pi ) Tj /F1 10 Tf (therefore can be extracted by multiplying by 4 the) Tj T* 0 Tw (ratio between the number of points in the quadrant versus the total number of points ) Tj /F4 10 Tf (N) Tj /F1 10 Tf (, for ) Tj /F4 10 Tf (N ) Tj /F1 10 Tf (large:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 524.8236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 96 re B*
-Q
-q
-BT 1 0 0 1 0 77.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (def calc_pi\(N\):) Tj T* (    inside = 0) Tj T* (    for j in xrange\(N\):) Tj T* (        x, y = random\(\), random\(\)) Tj T* (        if x*x + y*y ) Tj (<) Tj ( 1:) Tj T* (            inside += 1) Tj T* (    return \(4.0 * inside\) / N) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 456.8236 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 52.82 Tm /F1 10 Tf 12 TL .046654 Tw (The algorithm is trivially parallelizable: if you have n CPUs, you can compute pi n times with N/n iterations,) Tj T* 0 Tw 1.122488 Tw (sum the results and divide the total by n. I have a Macbook with two cores, therefore I would expect a) Tj T* 0 Tw 2.347984 Tw (speedup factor of 2 with respect to a sequential computation. Moreover, I would expect a threaded) Tj T* 0 Tw 2.827984 Tw (computation to be even slower than a sequential computation, due to the GIL and the scheduling) Tj T* 0 Tw (overhead.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 426.8236 cm
-q
-BT 1 0 0 1 0 16.82 Tm .313984 Tw 12 TL /F1 10 Tf 0 0 0 rg (Here is a script implementing the algorithm and working in three different modes \(parallel mode, threaded) Tj T* 0 Tw (mode and sequential mode\) depending on a ) Tj /F4 10 Tf (mode ) Tj /F1 10 Tf (option:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 93.62362 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 324 re B*
-Q
-q
-BT 1 0 0 1 0 305.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (from __future__ import with_statement) Tj T* (from random import random) Tj T* (import multiprocessing) Tj T* (import plac) Tj T*  T* (class PiCalculator\(object\):) Tj T* (    """Compute pi in parallel with threads or processes""") Tj T* (    ) Tj T* (    @plac.annotations\() Tj T* (        npoints=\('number of integration points', 'positional', None, int\),) Tj T* (        mode=\('sequential|parallel|threaded', 'option', 'm', str, 'SPT'\)\)) Tj T* (    def __init__\(self, npoints, mode='S'\):) Tj T* (        self.npoints = npoints) Tj T* (        if mode == 'P':) Tj T* (            self.mpcommands = ['calc_pi']) Tj T* (        elif mode == 'T':) Tj T* (            self.thcommands = ['calc_pi']) Tj T* (        elif mode == 'S':) Tj T* (            self.commands = ['calc_pi']) Tj T* (        self.n_cpu = multiprocessing.cpu_count\(\)) Tj T* (    ) Tj T* (    def submit_tasks\(self\):) Tj T* (        self.i = plac.Interpreter\(self\).__enter__\(\)            ) Tj T* (        return [self.i.submit\('calc_pi %d' % \(self.npoints / self.n_cpu\)\)) Tj T* (                for _ in range\(self.n_cpu\)]) Tj T*  T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 56.69291 56.69291 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 235.3849 0 Td (22) Tj T* -235.3849 0 Td ET
-Q
-Q
- 
-endstream
-
-endobj
-% 'R181': class PDFStream 
-181 0 obj
-% page stream
-<< /Length 3359 >>
-stream
-1 0 0 1 0 0 cm BT /F1 12 Tf 14.4 TL ET
-q
-1 0 0 1 62.69291 307.8236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 456 re B*
-Q
-q
-BT 1 0 0 1 0 437.71 Tm 12 TL /F4 10 Tf 0 0 0 rg (    def close\(self\):) Tj T* (        self.i.close\(\)) Tj T*  T* (    @plac.annotations\() Tj T* (        npoints=\('npoints', 'positional', None, int\)\)) Tj T* (    def calc_pi\(self, npoints\):) Tj T* (        counts = 0) Tj T* (        for j in xrange\(npoints\):) Tj T* (            n, r = divmod\(j, 1000000\)) Tj T* (            if r == 0:) Tj T* (                yield '%dM iterations' % n) Tj T* (            x, y = random\(\), random\(\)) Tj T* (            if x*x + y*y ) Tj (<) Tj ( 1:) Tj T* (                counts += 1) Tj T* (        yield \(4.0 * counts\)/npoints) Tj T*  T* (    def run\(self\):) Tj T* (        tasks = self.i.tasks\(\)) Tj T* (        for t in tasks:) Tj T* (            t.run\(\)) Tj T* (        try:) Tj T* (            total = 0) Tj T* (            for task in tasks:) Tj T* (                total += task.result) Tj T* (        except: # the task was killed) Tj T* (            print tasks) Tj T* (            return) Tj T* (        return total / self.n_cpu) Tj T*  T* (if __name__ == '__main__':) Tj T* (    pc = plac.call\(PiCalculator\)) Tj T* (    pc.submit_tasks\(\)) Tj T* (    try:) Tj T* (        import time; t0 = time.time\(\)) Tj T* (        print '%f in %f seconds ' % \(pc.run\(\), time.time\(\) - t0\)) Tj T* (    finally:) Tj T* (        pc.close\(\)) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 227.8236 cm
-q
-BT 1 0 0 1 0 64.82 Tm .381797 Tw 12 TL /F1 10 Tf 0 0 0 rg (Notice the ) Tj /F4 10 Tf (submit_tasks ) Tj /F1 10 Tf (method, which instantiates and initializes a ) Tj /F4 10 Tf (plac.Interpreter ) Tj /F1 10 Tf (object and) Tj T* 0 Tw 3.38152 Tw (submits a number of commands corresponding to the number of available CPUs. The ) Tj /F4 10 Tf (calc_pi) Tj T* 0 Tw 3.796651 Tw /F1 10 Tf (command yield a log message every million of interactions, just to monitor the progress of the) Tj T* 0 Tw 1.751318 Tw (computation. The ) Tj /F4 10 Tf (run ) Tj /F1 10 Tf (method starts all the submitted commands in parallel and sums the results. It) Tj T* 0 Tw 1.17104 Tw (returns the average value of ) Tj /F4 10 Tf (pi ) Tj /F1 10 Tf (after the slowest CPU has finished its job \(if the CPUs are equal and) Tj T* 0 Tw (equally busy they should finish more or less at the same time\).) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 209.8236 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL (Here are the results on my old Macbook with Ubuntu 10.04 and Python 2.6, for 10 million of iterations:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 116.6236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 84 re B*
-Q
-q
-0 0 0 rg
-BT 1 0 0 1 0 65.71 Tm /F4 10 Tf 12 TL ($ python picalculator.py -mP 10000000) Tj T* (3.141904 in 5.744545 seconds) Tj T* ($ python picalculator.py -mT 10000000) Tj T* (3.141272 in 13.875645 seconds) Tj T* ($ python picalculator.py -mS 10000000) Tj T* (3.141586 in 11.353841 seconds) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 56.69291 56.69291 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 235.3849 0 Td (23) Tj T* -235.3849 0 Td ET
-Q
-Q
- 
-endstream
-
-endobj
-% 'R182': class PDFStream 
-182 0 obj
-% page stream
-<< /Length 5577 >>
-stream
-1 0 0 1 0 0 cm BT /F1 12 Tf 14.4 TL ET
-q
-1 0 0 1 62.69291 741.0236 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 16.82 Tm /F1 10 Tf 12 TL 1.711751 Tw (As you see using processes one gets a 2x speedup indeed, where the threaded mode is some 20%) Tj T* 0 Tw (slower than the sequential mode.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 708.0236 cm
-q
-BT 1 0 0 1 0 8.435 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (The plac server) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 594.0236 cm
-q
-BT 1 0 0 1 0 100.82 Tm 1.258443 Tw 12 TL /F1 10 Tf 0 0 0 rg (A command-line oriented interface can be easily converted into a socket-based interface. Starting from) Tj T* 0 Tw .930574 Tw (release 0.7 plac features a builtin server which is able to accept commands from multiple clients and to) Tj T* 0 Tw .994692 Tw (execute them. The server works by instantiating a separate interpreter for each client, so that if a client) Tj T* 0 Tw 1.08784 Tw (interpreter dies for any reason the other interpreters keep working. To avoid external dependencies the) Tj T* 0 Tw .872209 Tw (server is based on the ) Tj /F4 10 Tf (asynchat ) Tj /F1 10 Tf (module in the standard library, but it would not be difficult to replace) Tj T* 0 Tw 2.386412 Tw (the server with a different one \(for instance, a Twisted server\). Since ) Tj /F4 10 Tf (asynchat) Tj /F1 10 Tf (-based servers are) Tj T* 0 Tw .755984 Tw (asynchronous, any blocking command in the interpreter should be run in a separated process or thread.) Tj T* 0 Tw 1.157633 Tw (The default port for the ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (server is 2199, and the command to signal end-of-connection is EOF. For) Tj T* 0 Tw (instance, here is how you could manage remote import on a database \(say a SQLite db\):) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 464.8236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 120 re B*
-Q
-q
-0 0 0 rg
-BT 1 0 0 1 0 101.71 Tm /F4 10 Tf 12 TL (import plac) Tj T* (from importer2 import FakeImporter) Tj T*  T* (def main\(port=2199\):) Tj T* (    main = FakeImporter\('dsn'\)) Tj T* (    plac.Interpreter\(main\).start_server\(port\)) Tj T* (    ) Tj T* (if __name__ == '__main__':) Tj T* (   plac.call\(main\)) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 444.8236 cm
-q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (You can connect to the server with ) Tj /F4 10 Tf (telnet ) Tj /F1 10 Tf (on port 2199, as follows:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 267.6236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 168 re B*
-Q
-q
-BT 1 0 0 1 0 149.71 Tm 12 TL /F4 10 Tf 0 0 0 rg ($ telnet localhost 2199) Tj T* (Trying ::1...) Tj T* (Trying 127.0.0.1...) Tj T* (Connected to localhost.) Tj T* (Escape character is '^]'.) Tj T* (i) Tj (>) Tj ( import_file f1) Tj T* (i) Tj (>) Tj ( .list) Tj T* (<) Tj (ThreadedTask 1 [import_file f1] RUNNING) Tj (>) Tj  T* (i) Tj (>) Tj ( .out) Tj T* (Imported 100 lines) Tj T* (Imported 200 lines) Tj T* (i) Tj (>) Tj ( EOF) Tj T* (Connection closed by foreign host.) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 234.6236 cm
-q
-BT 1 0 0 1 0 8.435 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (Summary) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 192.6236 cm
-q
-BT 1 0 0 1 0 28.82 Tm 2.203318 Tw 12 TL /F1 10 Tf 0 0 0 rg (Once ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (claimed to be the easiest command-line arguments parser in the world. Having read this) Tj T* 0 Tw .673322 Tw (document you may think that it is not so easy after all. But it is a false impression. Actually the rules are) Tj T* 0 Tw (quite simple:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 186.6236 cm
-Q
-q
-1 0 0 1 62.69291 186.6236 cm
-Q
-q
-1 0 0 1 62.69291 168.6236 cm
-0 0 0 rg
-BT /F3 10 Tf 12 TL ET
-q
-1 0 0 1 6 3 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 5.66 0 Td (1.) Tj T* -5.66 0 Td ET
-Q
-Q
-q
-1 0 0 1 23 3 cm
-q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (if you want to implement a command-line script, use ) Tj /F4 10 Tf (plac.call) Tj /F1 10 Tf (;) Tj T* ET
-Q
-Q
-q
-Q
-Q
-q
-1 0 0 1 62.69291 168.6236 cm
-Q
-q
-1 0 0 1 62.69291 168.6236 cm
-Q
-q
-1 0 0 1 62.69291 108.6236 cm
-0 0 0 rg
-BT /F3 10 Tf 12 TL ET
-q
-1 0 0 1 6 45 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 5.66 0 Td (2.) Tj T* -5.66 0 Td ET
-Q
-Q
-q
-1 0 0 1 23 45 cm
-q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (if you want to implement a command interpreter, use ) Tj /F4 10 Tf (plac.Interpreter) Tj /F1 10 Tf (:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 23 39 cm
-Q
-q
-1 0 0 1 23 39 cm
-Q
-q
-1 0 0 1 23 21 cm
-0 0 0 rg
-BT /F3 10 Tf 12 TL ET
-q
-1 0 0 1 6 3 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 10.5 0 Td (\177) Tj T* -10.5 0 Td ET
-Q
-Q
-q
-1 0 0 1 23 3 cm
-q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (for an interactive interpreter, call the ) Tj /F4 10 Tf (.interact ) Tj /F1 10 Tf (method;) Tj T* ET
-Q
-Q
-q
-Q
-Q
-q
-1 0 0 1 23 21 cm
-Q
-q
-1 0 0 1 23 21 cm
-Q
-q
-1 0 0 1 23 3 cm
-0 0 0 rg
-BT /F3 10 Tf 12 TL ET
-q
-1 0 0 1 6 3 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 10.5 0 Td (\177) Tj T* -10.5 0 Td ET
-Q
-Q
-q
-1 0 0 1 23 3 cm
-q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (for an batch interpreter, call the ) Tj /F4 10 Tf (.execute ) Tj /F1 10 Tf (method;) Tj T* ET
-Q
-Q
-q
-Q
-Q
-q
-1 0 0 1 23 3 cm
-Q
-q
-1 0 0 1 23 3 cm
-Q
-q
-Q
-Q
-q
-1 0 0 1 62.69291 108.6236 cm
-Q
-q
-1 0 0 1 62.69291 108.6236 cm
-Q
-q
-1 0 0 1 56.69291 56.69291 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 235.3849 0 Td (24) Tj T* -235.3849 0 Td ET
-Q
-Q
- 
-endstream
-
-endobj
-% 'R183': class PDFStream 
-183 0 obj
-% page stream
-<< /Length 5397 >>
-stream
-1 0 0 1 0 0 cm BT /F1 12 Tf 14.4 TL ET
-q
-1 0 0 1 62.69291 735.0236 cm
-0 0 0 rg
-BT /F3 10 Tf 12 TL ET
-q
-1 0 0 1 6 15 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 5.66 0 Td (3.) Tj T* -5.66 0 Td ET
-Q
-Q
-q
-1 0 0 1 23 3 cm
-q
-BT 1 0 0 1 0 16.82 Tm 5.126647 Tw 12 TL /F1 10 Tf 0 0 0 rg (for testing call the ) Tj /F4 10 Tf (Interpreter.check ) Tj /F1 10 Tf (method in the appropriate context or use the) Tj T* 0 Tw /F4 10 Tf (Interpreter.doctest ) Tj /F1 10 Tf (feature;) Tj T* ET
-Q
-Q
-q
-Q
-Q
-q
-1 0 0 1 62.69291 735.0236 cm
-Q
-q
-1 0 0 1 62.69291 735.0236 cm
-Q
-q
-1 0 0 1 62.69291 705.0236 cm
-0 0 0 rg
-BT /F3 10 Tf 12 TL ET
-q
-1 0 0 1 6 15 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 5.66 0 Td (4.) Tj T* -5.66 0 Td ET
-Q
-Q
-q
-1 0 0 1 23 3 cm
-q
-BT 1 0 0 1 0 16.82 Tm 1.356457 Tw 12 TL /F1 10 Tf 0 0 0 rg (if you need to go at a lower level, you may need to call the ) Tj /F4 10 Tf (Interpreter.send ) Tj /F1 10 Tf (method which) Tj T* 0 Tw (returns a \(finished\) ) Tj /F4 10 Tf (Task ) Tj /F1 10 Tf (object.) Tj T* ET
-Q
-Q
-q
-Q
-Q
-q
-1 0 0 1 62.69291 705.0236 cm
-Q
-q
-1 0 0 1 62.69291 705.0236 cm
-Q
-q
-1 0 0 1 62.69291 675.0236 cm
-0 0 0 rg
-BT /F3 10 Tf 12 TL ET
-q
-1 0 0 1 6 15 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 5.66 0 Td (5.) Tj T* -5.66 0 Td ET
-Q
-Q
-q
-1 0 0 1 23 3 cm
-q
-BT 1 0 0 1 0 16.82 Tm 1.469269 Tw 12 TL /F1 10 Tf 0 0 0 rg (long running command can be executed in the background as threads or processes: just declare) Tj T* 0 Tw (them in the lists ) Tj /F4 10 Tf (thcommands ) Tj /F1 10 Tf (and ) Tj /F4 10 Tf (mpcommands ) Tj /F1 10 Tf (respectively.) Tj T* ET
-Q
-Q
-q
-Q
-Q
-q
-1 0 0 1 62.69291 675.0236 cm
-Q
-q
-1 0 0 1 62.69291 675.0236 cm
-Q
-q
-1 0 0 1 62.69291 645.0236 cm
-0 0 0 rg
-BT /F3 10 Tf 12 TL ET
-q
-1 0 0 1 6 15 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 5.66 0 Td (6.) Tj T* -5.66 0 Td ET
-Q
-Q
-q
-1 0 0 1 23 3 cm
-q
-BT 1 0 0 1 0 16.82 Tm 2.171647 Tw 12 TL /F1 10 Tf 0 0 0 rg (the ) Tj /F4 10 Tf (.start_server ) Tj /F1 10 Tf (method starts an asynchronous server on the given port number \(default) Tj T* 0 Tw (2199\)) Tj T* ET
-Q
-Q
-q
-Q
-Q
-q
-1 0 0 1 62.69291 645.0236 cm
-Q
-q
-1 0 0 1 62.69291 645.0236 cm
-Q
-q
-1 0 0 1 62.69291 627.0236 cm
-q
-BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (Moreover, remember that ) Tj /F4 10 Tf (plac_runner.py ) Tj /F1 10 Tf (is your friend.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 598.6772 cm
-n 0 14.17323 m 469.8898 14.17323 l S
-Q
-q
-1 0 0 1 62.69291 565.6772 cm
-q
-BT 1 0 0 1 0 8.435 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (Appendix: custom annotation objects) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 535.6772 cm
-q
-BT 1 0 0 1 0 16.82 Tm .578651 Tw 12 TL /F1 10 Tf 0 0 0 rg (Internally ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (uses an ) Tj /F4 10 Tf (Annotation ) Tj /F1 10 Tf (class to convert the tuples in the function signature into annotation) Tj T* 0 Tw (objects, i.e. objects with six attributes ) Tj /F4 10 Tf (help, kind, short, type, choices, metavar) Tj /F1 10 Tf (.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 505.6772 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 16.82 Tm /F1 10 Tf 12 TL .083735 Tw (Advanced users can implement their own annotation objects. For instance, here is an example of how you) Tj T* 0 Tw (could implement annotations for positional arguments:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 376.4772 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 120 re B*
-Q
-q
-0 0 0 rg
-BT 1 0 0 1 0 101.71 Tm /F4 10 Tf 12 TL (# annotations.py) Tj T* (class Positional\(object\):) Tj T* (    def __init__\(self, help='', type=None, choices=None, metavar=None\):) Tj T* (        self.help = help) Tj T* (        self.kind = 'positional') Tj T* (        self.abbrev = None) Tj T* (        self.type = type) Tj T* (        self.choices = choices) Tj T* (        self.metavar = metavar) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 356.4772 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL (You can use such annotations objects as follows:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 179.2772 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 168 re B*
-Q
-q
-0 0 0 rg
-BT 1 0 0 1 0 149.71 Tm /F4 10 Tf 12 TL (# example11.py) Tj T* (import plac) Tj T* (from annotations import Positional) Tj T*  T* (@plac.annotations\() Tj T* (    i=Positional\("This is an int", int\),) Tj T* (    n=Positional\("This is a float", float\),) Tj T* (    rest=Positional\("Other arguments"\)\)) Tj T* (def main\(i, n, *rest\):) Tj T* (    print\(i, n, rest\)) Tj T*  T* (if __name__ == '__main__':) Tj T* (    import plac; plac.call\(main\)) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 159.2772 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL (Here is the usage message you get:) Tj T* ET
-Q
-Q
-q
-1 0 0 1 62.69291 90.07717 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 60 re B*
-Q
-q
-0 0 0 rg
-BT 1 0 0 1 0 41.71 Tm /F4 10 Tf 12 TL (usage: example11.py [-h] i n [rest [rest ...]]) Tj T*  T* (positional arguments:) Tj T* (  i           This is an int) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 56.69291 56.69291 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 235.3849 0 Td (25) Tj T* -235.3849 0 Td ET
-Q
-Q
- 
-endstream
-
-endobj
-% 'R184': class PDFStream 
-184 0 obj
-% page stream
-<< /Length 1103 >>
-stream
-1 0 0 1 0 0 cm BT /F1 12 Tf 14.4 TL ET
-q
-1 0 0 1 62.69291 691.8236 cm
-q
-q
-1 0 0 1 0 0 cm
-q
-1 0 0 1 6.6 6.6 cm
-q
-.662745 .662745 .662745 RG
-.5 w
-.960784 .960784 .862745 rg
-n -6 -6 468.6898 72 re B*
-Q
-q
-0 0 0 rg
-BT 1 0 0 1 0 53.71 Tm /F4 10 Tf 12 TL (  n           This is a float) Tj T* (  rest        Other arguments) Tj T*  T* (optional arguments:) Tj T* (  -h, --help  show this help message and exit) Tj T* ET
-Q
-Q
-Q
-Q
-Q
-q
-1 0 0 1 62.69291 647.8236 cm
-q
-BT 1 0 0 1 0 28.82 Tm .713516 Tw 12 TL /F1 10 Tf 0 0 0 rg (You can go on and define ) Tj /F4 10 Tf (Option ) Tj /F1 10 Tf (and ) Tj /F4 10 Tf (Flag ) Tj /F1 10 Tf (classes, if you like. Using custom annotation objects you) Tj T* 0 Tw .17528 Tw (could do advanced things like extracting the annotations from a configuration file or from a database, but I) Tj T* 0 Tw (expect such use cases to be quite rare: the default mechanism should work pretty well for most users.) Tj T* ET
-Q
-Q
-q
-1 0 0 1 56.69291 56.69291 cm
-q
-0 0 0 rg
-BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 235.3849 0 Td (26) Tj T* -235.3849 0 Td ET
-Q
-Q
- 
-endstream
-
-endobj
-% 'R185': class PDFPageLabels 
-185 0 obj
-% Document Root
-<< /Nums [ 0
- 186 0 R
- 1
- 187 0 R
- 2
- 188 0 R
- 3
- 189 0 R
- 4
- 190 0 R
- 5
- 191 0 R
- 6
- 192 0 R
- 7
- 193 0 R
- 8
- 194 0 R
- 9
- 195 0 R
- 10
- 196 0 R
- 11
- 197 0 R
- 12
- 198 0 R
- 13
- 199 0 R
- 14
- 200 0 R
- 15
- 201 0 R
- 16
- 202 0 R
- 17
- 203 0 R
- 18
- 204 0 R
- 19
- 205 0 R
- 20
- 206 0 R
- 21
- 207 0 R
- 22
- 208 0 R
- 23
- 209 0 R
- 24
- 210 0 R
- 25
- 211 0 R ] >>
-endobj
-% 'R186': class PDFPageLabel 
-186 0 obj
-% None
-<< /S /D
- /St 1 >>
-endobj
-% 'R187': class PDFPageLabel 
-187 0 obj
-% None
-<< /S /D
- /St 2 >>
-endobj
-% 'R188': class PDFPageLabel 
-188 0 obj
-% None
-<< /S /D
- /St 3 >>
-endobj
-% 'R189': class PDFPageLabel 
-189 0 obj
-% None
-<< /S /D
- /St 4 >>
-endobj
-% 'R190': class PDFPageLabel 
-190 0 obj
-% None
-<< /S /D
- /St 5 >>
-endobj
-% 'R191': class PDFPageLabel 
-191 0 obj
-% None
-<< /S /D
- /St 6 >>
-endobj
-% 'R192': class PDFPageLabel 
-192 0 obj
-% None
-<< /S /D
- /St 7 >>
-endobj
-% 'R193': class PDFPageLabel 
-193 0 obj
-% None
-<< /S /D
- /St 8 >>
-endobj
-% 'R194': class PDFPageLabel 
-194 0 obj
-% None
-<< /S /D
- /St 9 >>
-endobj
-% 'R195': class PDFPageLabel 
-195 0 obj
-% None
-<< /S /D
- /St 10 >>
-endobj
-% 'R196': class PDFPageLabel 
-196 0 obj
-% None
-<< /S /D
- /St 11 >>
-endobj
-% 'R197': class PDFPageLabel 
-197 0 obj
-% None
-<< /S /D
- /St 12 >>
-endobj
-% 'R198': class PDFPageLabel 
-198 0 obj
-% None
-<< /S /D
- /St 13 >>
-endobj
-% 'R199': class PDFPageLabel 
-199 0 obj
-% None
-<< /S /D
- /St 14 >>
-endobj
-% 'R200': class PDFPageLabel 
-200 0 obj
-% None
-<< /S /D
- /St 15 >>
-endobj
-% 'R201': class PDFPageLabel 
-201 0 obj
-% None
-<< /S /D
- /St 16 >>
-endobj
-% 'R202': class PDFPageLabel 
-202 0 obj
-% None
-<< /S /D
- /St 17 >>
-endobj
-% 'R203': class PDFPageLabel 
-203 0 obj
-% None
-<< /S /D
- /St 18 >>
-endobj
-% 'R204': class PDFPageLabel 
-204 0 obj
-% None
-<< /S /D
- /St 19 >>
-endobj
-% 'R205': class PDFPageLabel 
-205 0 obj
-% None
-<< /S /D
- /St 20 >>
-endobj
-% 'R206': class PDFPageLabel 
-206 0 obj
-% None
-<< /S /D
- /St 21 >>
-endobj
-% 'R207': class PDFPageLabel 
-207 0 obj
-% None
-<< /S /D
- /St 22 >>
-endobj
-% 'R208': class PDFPageLabel 
-208 0 obj
-% None
-<< /S /D
- /St 23 >>
-endobj
-% 'R209': class PDFPageLabel 
-209 0 obj
-% None
-<< /S /D
- /St 24 >>
-endobj
-% 'R210': class PDFPageLabel 
-210 0 obj
-% None
-<< /S /D
- /St 25 >>
-endobj
-% 'R211': class PDFPageLabel 
-211 0 obj
-% None
-<< /S /D
- /St 26 >>
-endobj
-xref
-0 212
-0000000000 65535 f
-0000000113 00000 n
-0000000257 00000 n
-0000000422 00000 n
-0000000597 00000 n
-0000000778 00000 n
-0000001030 00000 n
-0000001280 00000 n
-0000001538 00000 n
-0000001699 00000 n
-0000001893 00000 n
-0000002135 00000 n
-0000002377 00000 n
-0000002619 00000 n
-0000002861 00000 n
-0000003103 00000 n
-0000003346 00000 n
-0000003589 00000 n
-0000003832 00000 n
-0000004075 00000 n
-0000004318 00000 n
-0000004561 00000 n
-0000004804 00000 n
-0000005047 00000 n
-0000005290 00000 n
-0000005533 00000 n
-0000005776 00000 n
-0000006020 00000 n
-0000006264 00000 n
-0000006508 00000 n
-0000006752 00000 n
-0000006996 00000 n
-0000007240 00000 n
-0000007484 00000 n
-0000007728 00000 n
-0000007972 00000 n
-0000008216 00000 n
-0000008460 00000 n
-0000008704 00000 n
-0000008948 00000 n
-0000009192 00000 n
-0000009436 00000 n
-0000009680 00000 n
-0000009924 00000 n
-0000010168 00000 n
-0000010412 00000 n
-0000010656 00000 n
-0000010900 00000 n
-0000011143 00000 n
-0000011395 00000 n
-0000011632 00000 n
-0000012325 00000 n
-0000012577 00000 n
-0000012829 00000 n
-0000013081 00000 n
-0000013324 00000 n
-0000013576 00000 n
-0000013828 00000 n
-0000014080 00000 n
-0000014332 00000 n
-0000014589 00000 n
-0000014979 00000 n
-0000015216 00000 n
-0000015519 00000 n
-0000015816 00000 n
-0000016068 00000 n
-0000016320 00000 n
-0000016572 00000 n
-0000016832 00000 n
-0000017084 00000 n
-0000017345 00000 n
-0000017596 00000 n
-0000017857 00000 n
-0000018109 00000 n
-0000018346 00000 n
-0000018745 00000 n
-0000018996 00000 n
-0000019232 00000 n
-0000019559 00000 n
-0000019831 00000 n
-0000020083 00000 n
-0000020335 00000 n
-0000020572 00000 n
-0000020917 00000 n
-0000021169 00000 n
-0000021421 00000 n
-0000021665 00000 n
-0000021986 00000 n
-0000022269 00000 n
-0000022566 00000 n
-0000022818 00000 n
-0000023074 00000 n
-0000023326 00000 n
-0000023592 00000 n
-0000023844 00000 n
-0000024082 00000 n
-0000024445 00000 n
-0000024704 00000 n
-0000024963 00000 n
-0000025213 00000 n
-0000025464 00000 n
-0000025715 00000 n
-0000025968 00000 n
-0000026221 00000 n
-0000026474 00000 n
-0000026727 00000 n
-0000026967 00000 n
-0000027359 00000 n
-0000027657 00000 n
-0000027908 00000 n
-0000028147 00000 n
-0000028463 00000 n
-0000028761 00000 n
-0000028999 00000 n
-0000029319 00000 n
-0000029572 00000 n
-0000029844 00000 n
-0000030083 00000 n
-0000030423 00000 n
-0000030676 00000 n
-0000030915 00000 n
-0000031231 00000 n
-0000031529 00000 n
-0000031782 00000 n
-0000032040 00000 n
-0000032370 00000 n
-0000032609 00000 n
-0000032930 00000 n
-0000033169 00000 n
-0000033475 00000 n
-0000033774 00000 n
-0000034028 00000 n
-0000034267 00000 n
-0000034598 00000 n
-0000034837 00000 n
-0000035143 00000 n
-0000035428 00000 n
-0000035592 00000 n
-0000035846 00000 n
-0000035975 00000 n
-0000036151 00000 n
-0000036371 00000 n
-0000036577 00000 n
-0000036772 00000 n
-0000036970 00000 n
-0000037174 00000 n
-0000037375 00000 n
-0000037571 00000 n
-0000037767 00000 n
-0000037974 00000 n
-0000038184 00000 n
-0000038387 00000 n
-0000038586 00000 n
-0000038806 00000 n
-0000039030 00000 n
-0000039240 00000 n
-0000039437 00000 n
-0000039626 00000 n
-0000039811 00000 n
-0000040162 00000 n
-0000049451 00000 n
-0000055004 00000 n
-0000059148 00000 n
-0000064812 00000 n
-0000071064 00000 n
-0000076420 00000 n
-0000080839 00000 n
-0000085230 00000 n
-0000090375 00000 n
-0000094542 00000 n
-0000099727 00000 n
-0000104362 00000 n
-0000108692 00000 n
-0000114142 00000 n
-0000118139 00000 n
-0000123892 00000 n
-0000129037 00000 n
-0000133562 00000 n
-0000138598 00000 n
-0000142995 00000 n
-0000147281 00000 n
-0000152054 00000 n
-0000155516 00000 n
-0000161196 00000 n
-0000166696 00000 n
-0000167906 00000 n
-0000168368 00000 n
-0000168447 00000 n
-0000168526 00000 n
-0000168605 00000 n
-0000168684 00000 n
-0000168763 00000 n
-0000168842 00000 n
-0000168921 00000 n
-0000169000 00000 n
-0000169079 00000 n
-0000169159 00000 n
-0000169239 00000 n
-0000169319 00000 n
-0000169399 00000 n
-0000169479 00000 n
-0000169559 00000 n
-0000169639 00000 n
-0000169719 00000 n
-0000169799 00000 n
-0000169879 00000 n
-0000169959 00000 n
-0000170039 00000 n
-0000170119 00000 n
-0000170199 00000 n
-0000170279 00000 n
-0000170359 00000 n
-trailer
-<< /ID 
- % ReportLab generated PDF document -- digest (http://www.reportlab.com) 
- [(sBo\373\214D1\203\267\213\235\214h\027V\257) (sBo\373\214D1\203\267\213\235\214h\027V\257)] 
-
- /Info 137 0 R
- /Root 136 0 R
- /Size 212 >>
-startxref
-170408
-%%EOF
diff --git a/plac/doc/plac_adv.txt b/plac/doc/plac_adv.txt
index 4ae3d19..c2f723c 100644
--- a/plac/doc/plac_adv.txt
+++ b/plac/doc/plac_adv.txt
@@ -1101,6 +1101,16 @@ for 10 million of iterations::
 As you see using processes one gets a 2x speedup indeed, where the threaded
 mode is some 20% slower than the sequential mode.
 
+Since the pattern submit a bunch of tasks, starts them and collect the
+results is so common, plac_ provides an utility function 
+``runp(genseq, mode='p', start=True)`` to start
+a bunch a generators and return a list of task objects. By default
+``runp`` use processes, but you can use threads by passing ``mode='t'``.
+If you do not wont to start the tasks, you can say so (``start=False``).
+With ``runp`` the parallel pi calculation becomes a one-liner::
+
+    sum(task.result for task in plac.runp(calc_pi(N) for i in range(ncpus)))/ncpus
+
 The plac server
 -------------------------------------------------------
 
diff --git a/plac/plac.py b/plac/plac.py
index 2cc9fc4..adfab85 100644
--- a/plac/plac.py
+++ b/plac/plac.py
@@ -27,9 +27,9 @@
 See doc/plac.pdf, doc/plac_adv.pdf for the documentation.
 """
 
-__version__ = '0.7.2'
+__version__ = '0.7.3'
 
 from plac_core import *
 
 if sys.version >= '2.5':
-    from plac_ext import Interpreter, import_main, ReadlineInput, stdout
+    from plac_ext import Interpreter, import_main, ReadlineInput, stdout, runp
diff --git a/plac/plac_ext.py b/plac/plac_ext.py
index e01a484..cb7cccd 100644
--- a/plac/plac_ext.py
+++ b/plac/plac_ext.py
@@ -250,6 +250,8 @@ class BaseTask(object):
         self.wait()
         if self.exc:
             raise self.etype, self.exc, self.tb or None
+        if not self.outlist:
+            return None
         return self.outlist[-1]
 
     def __repr__(self):
@@ -863,3 +865,32 @@ class Interpreter(object):
     def stop_server(self, wait=0.0):
         "Stops the asyncore server, possibly after a given number of seconds"
         threading.Timer(wait, asyncore.socket_map.clear).start()
+
+#################################### runp #####################################
+
+class _TaskLauncher(object):
+    "Helper for runp"
+    def __init__(self, genseq, mode):
+        if mode == 'p':
+            self.mpcommands = ['rungen']
+        else:
+            self.thcommands = ['rungen']
+        self.genlist = list(genseq)
+    def rungen(self, i):
+        for out in self.genlist[int(i) - 1]:
+            yield out
+
+def runp(genseq, mode='p', start=True):
+    """Run a sequence of generators in parallel. Mode can be 'p' (use processes)
+    or 't' (use threads). Return a list of running task objects. If start is
+    False, the tasks are only submitted and not automatically started.
+    """
+    assert mode in 'pt', mode
+    launcher = _TaskLauncher(genseq, mode)
+    inter = Interpreter(launcher).__enter__()
+    for i in range(len(launcher.genlist)):
+        inter.submit('rungen %d' % (i + 1))
+    if start:
+        for task in inter.tasks():
+            task.run()
+    return inter.tasks()
author	micheles <micheles@micheles-laptop>	2010-08-31 07:58:27 +0200
committer	micheles <micheles@micheles-laptop>	2010-08-31 07:58:27 +0200
commit	13ef00b3231dd71e331e34891bea6345e5b96097 (patch)
tree	804fee4adaae672ef4bd7fb1a60b856e20691556
parent	e1e09b354cf2924ed4dbad0c4776a61f4355d1b0 (diff)
download	micheles-13ef00b3231dd71e331e34891bea6345e5b96097.tar.gz