diff options
Diffstat (limited to 'plac/doc/plac.html')
| -rw-r--r-- | plac/doc/plac.html | 200 |
1 files changed, 109 insertions, 91 deletions
diff --git a/plac/doc/plac.html b/plac/doc/plac.html index b470ffe..a0c738c 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.7: http://docutils.sourceforge.net/" /> +<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" /> <title></title> <style type="text/css"> @@ -415,7 +415,7 @@ h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt { <div class="section" id="plac-parsing-the-command-line-the-easy-way"> -<h1><a class="toc-backref" href="#id17">Plac: Parsing the Command Line the Easy Way</a></h1> +<h1><a class="toc-backref" href="#id15">Plac: Parsing the Command Line the Easy Way</a></h1> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> @@ -424,7 +424,7 @@ h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt { </tr> <tr class="field"><th class="field-name">E-mail:</th><td class="field-body"><a class="reference external" href="mailto:michele.simionato@gmail.com">michele.simionato@gmail.com</a></td> </tr> -<tr class="field"><th class="field-name">Date:</th><td class="field-body">August 2010</td> +<tr class="field"><th class="field-name">Date:</th><td class="field-body">June 2011</td> </tr> <tr class="field"><th class="field-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> @@ -441,50 +441,50 @@ h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt { <div class="contents topic" id="contents"> <p class="topic-title first">Contents</p> <ul class="simple"> -<li><a class="reference internal" href="#plac-parsing-the-command-line-the-easy-way" id="id17">Plac: Parsing the Command Line the Easy Way</a><ul> -<li><a class="reference internal" href="#the-importance-of-scaling-down" id="id18">The importance of scaling down</a></li> -<li><a class="reference internal" href="#scripts-with-required-arguments" id="id19">Scripts with required arguments</a></li> -<li><a class="reference internal" href="#scripts-with-default-arguments" id="id20">Scripts with default arguments</a></li> -<li><a class="reference internal" href="#scripts-with-options-and-smart-options" id="id21">Scripts with options (and smart options)</a></li> -<li><a class="reference internal" href="#scripts-with-flags" id="id22">Scripts with flags</a></li> -<li><a class="reference internal" href="#plac-for-python-2-x-users" id="id23">plac for Python 2.X users</a></li> -<li><a class="reference internal" href="#more-features" id="id24">More features</a></li> -<li><a class="reference internal" href="#a-realistic-example" id="id25">A realistic example</a></li> -<li><a class="reference internal" href="#keyword-arguments" id="id26">Keyword arguments</a></li> -<li><a class="reference internal" href="#final-example-a-shelve-interface" id="id27">Final example: a shelve interface</a></li> -<li><a class="reference internal" href="#plac-vs-argparse" id="id28">plac vs argparse</a></li> -<li><a class="reference internal" href="#plac-vs-the-rest-of-the-world" id="id29">plac vs the rest of the world</a></li> -<li><a class="reference internal" href="#the-future" id="id30">The future</a></li> -<li><a class="reference internal" href="#trivia-the-story-behind-the-name" id="id31">Trivia: the story behind the name</a></li> +<li><a class="reference internal" href="#plac-parsing-the-command-line-the-easy-way" id="id15">Plac: Parsing the Command Line the Easy Way</a><ul> +<li><a class="reference internal" href="#the-importance-of-scaling-down" id="id16">The importance of scaling down</a></li> +<li><a class="reference internal" href="#scripts-with-required-arguments" id="id17">Scripts with required arguments</a></li> +<li><a class="reference internal" href="#scripts-with-default-arguments" id="id18">Scripts with default arguments</a></li> +<li><a class="reference internal" href="#scripts-with-options-and-smart-options" id="id19">Scripts with options (and smart options)</a></li> +<li><a class="reference internal" href="#scripts-with-flags" id="id20">Scripts with flags</a></li> +<li><a class="reference internal" href="#plac-for-python-2-x-users" id="id21">plac for Python 2.X users</a></li> +<li><a class="reference internal" href="#more-features" id="id22">More features</a></li> +<li><a class="reference internal" href="#a-realistic-example" id="id23">A realistic example</a></li> +<li><a class="reference internal" href="#keyword-arguments" id="id24">Keyword arguments</a></li> +<li><a class="reference internal" href="#final-example-a-shelve-interface" id="id25">Final example: a shelve interface</a></li> +<li><a class="reference internal" href="#plac-vs-argparse" id="id26">plac vs argparse</a></li> +<li><a class="reference internal" href="#plac-vs-the-rest-of-the-world" id="id27">plac vs the rest of the world</a></li> +<li><a class="reference internal" href="#the-future" id="id28">The future</a></li> +<li><a class="reference internal" href="#trivia-the-story-behind-the-name" id="id29">Trivia: the story behind the name</a></li> </ul> </li> -<li><a class="reference internal" href="#advanced-usages-of-plac" id="id32">Advanced usages of plac</a><ul> -<li><a class="reference internal" href="#introduction" id="id33">Introduction</a></li> -<li><a class="reference internal" href="#from-scripts-to-interactive-applications" id="id34">From scripts to interactive applications</a></li> -<li><a class="reference internal" href="#testing-a-plac-application" id="id35">Testing a plac application</a></li> -<li><a class="reference internal" href="#plac-easy-tests" id="id36">Plac easy tests</a></li> -<li><a class="reference internal" href="#plac-batch-scripts" id="id37">Plac batch scripts</a></li> -<li><a class="reference internal" href="#implementing-subcommands" id="id38">Implementing subcommands</a></li> -<li><a class="reference internal" href="#plac-interpreter-call" id="id39">plac.Interpreter.call</a></li> -<li><a class="reference internal" href="#readline-support" id="id40">Readline support</a></li> -<li><a class="reference internal" href="#the-plac-runner" id="id41">The plac runner</a></li> -<li><a class="reference internal" href="#a-non-class-based-example" id="id42">A non class-based example</a></li> -<li><a class="reference internal" href="#writing-your-own-plac-runner" id="id43">Writing your own plac runner</a></li> -<li><a class="reference internal" href="#long-running-commands" id="id44">Long running commands</a></li> -<li><a class="reference internal" href="#threaded-commands" id="id45">Threaded commands</a></li> -<li><a class="reference internal" href="#running-commands-as-external-processes" id="id46">Running commands as external processes</a></li> -<li><a class="reference internal" href="#managing-the-output-of-concurrent-commands" id="id47">Managing the output of concurrent commands</a></li> -<li><a class="reference internal" href="#monitor-support" id="id48">Monitor support</a></li> -<li><a class="reference internal" href="#parallel-computing-with-plac" id="id49">Parallel computing with plac</a></li> -<li><a class="reference internal" href="#the-plac-server" id="id50">The plac server</a></li> -<li><a class="reference internal" href="#summary" id="id51">Summary</a></li> -<li><a class="reference internal" href="#appendix-custom-annotation-objects" id="id52">Appendix: custom annotation objects</a></li> +<li><a class="reference internal" href="#advanced-usages-of-plac" id="id30">Advanced usages of plac</a><ul> +<li><a class="reference internal" href="#introduction" id="id31">Introduction</a></li> +<li><a class="reference internal" href="#from-scripts-to-interactive-applications" id="id32">From scripts to interactive applications</a></li> +<li><a class="reference internal" href="#testing-a-plac-application" id="id33">Testing a plac application</a></li> +<li><a class="reference internal" href="#plac-easy-tests" id="id34">Plac easy tests</a></li> +<li><a class="reference internal" href="#plac-batch-scripts" id="id35">Plac batch scripts</a></li> +<li><a class="reference internal" href="#implementing-subcommands" id="id36">Implementing subcommands</a></li> +<li><a class="reference internal" href="#plac-interpreter-call" id="id37">plac.Interpreter.call</a></li> +<li><a class="reference internal" href="#readline-support" id="id38">Readline support</a></li> +<li><a class="reference internal" href="#the-plac-runner" id="id39">The plac runner</a></li> +<li><a class="reference internal" href="#a-non-class-based-example" id="id40">A non class-based example</a></li> +<li><a class="reference internal" href="#writing-your-own-plac-runner" id="id41">Writing your own plac runner</a></li> +<li><a class="reference internal" href="#long-running-commands" id="id42">Long running commands</a></li> +<li><a class="reference internal" href="#threaded-commands" id="id43">Threaded commands</a></li> +<li><a class="reference internal" href="#running-commands-as-external-processes" id="id44">Running commands as external processes</a></li> +<li><a class="reference internal" href="#managing-the-output-of-concurrent-commands" id="id45">Managing the output of concurrent commands</a></li> +<li><a class="reference internal" href="#monitor-support" id="id46">Monitor support</a></li> +<li><a class="reference internal" href="#parallel-computing-with-plac" id="id47">Parallel computing with plac</a></li> +<li><a class="reference internal" href="#the-plac-server" id="id48">The plac server</a></li> +<li><a class="reference internal" href="#summary" id="id49">Summary</a></li> +<li><a class="reference internal" href="#appendix-custom-annotation-objects" id="id50">Appendix: custom annotation objects</a></li> </ul> </li> </ul> </div> <div class="section" id="the-importance-of-scaling-down"> -<h2><a class="toc-backref" href="#id18">The importance of scaling down</a></h2> +<h2><a class="toc-backref" href="#id16">The importance of scaling down</a></h2> <p>There is no want of command line arguments parsers in the Python world. The standard library alone contains three different modules: <a class="reference external" href="http://docs.python.org/library/getopt.html">getopt</a> (from the stone age), @@ -525,7 +525,7 @@ is designed to be simple to use and extremely concise, as the examples below will show.</p> </div> <div class="section" id="scripts-with-required-arguments"> -<h2><a class="toc-backref" href="#id19">Scripts with required arguments</a></h2> +<h2><a class="toc-backref" href="#id17">Scripts with required arguments</a></h2> <p>Let me start with the simplest possible thing: a script that takes a single argument and does something to it. It cannot get simpler than that, unless you consider a script without command-line @@ -616,7 +616,7 @@ optional arguments: This is only the tip of the iceberg: <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> is able to do much more than that.</p> </div> <div class="section" id="scripts-with-default-arguments"> -<h2><a class="toc-backref" href="#id20">Scripts with default arguments</a></h2> +<h2><a class="toc-backref" href="#id18">Scripts with default arguments</a></h2> <p>The need to have suitable defaults for command-line scripts is quite common. For instance I have encountered this use case at work hundreds of times:</p> @@ -743,7 +743,7 @@ optional arguments: I will show in the next paragraphs.</p> </div> <div class="section" id="scripts-with-options-and-smart-options"> -<h2><a class="toc-backref" href="#id21">Scripts with options (and smart options)</a></h2> +<h2><a class="toc-backref" href="#id19">Scripts with options (and smart options)</a></h2> <p>It is surprising how few command-line scripts with options I have written over the years (probably less than a hundred), compared to the number of scripts with positional arguments I wrote (certainly more @@ -867,7 +867,7 @@ executing 'select * from table' on dsn </pre> </div> <div class="section" id="scripts-with-flags"> -<h2><a class="toc-backref" href="#id22">Scripts with flags</a></h2> +<h2><a class="toc-backref" href="#id20">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> if they are absent. Here is an example:</p> @@ -916,7 +916,7 @@ the one-character abbreviation for options, since it does not make sense to compose them.</p> </div> <div class="section" id="plac-for-python-2-x-users"> -<h2><a class="toc-backref" href="#id23">plac for Python 2.X users</a></h2> +<h2><a class="toc-backref" href="#id21">plac for Python 2.X users</a></h2> <p>I do not use Python 3. At work we are just starting to think about migrating to Python 2.6. It will take years before we think to migrate to Python 3. I am pretty much sure most Pythonistas @@ -952,7 +952,7 @@ X >= 4 and I will use the <tt class="docutils literal">plac.annotations</tt> 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"> -<h2><a class="toc-backref" href="#id24">More features</a></h2> +<h2><a class="toc-backref" href="#id22">More features</a></h2> <p>One of the goals of <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> is to have a learning curve of <em>minutes</em> for its core features, compared to the learning curve of <em>hours</em> of <a class="reference external" href="http://argparse.googlecode.com">argparse</a>. In order to reach this goal, I have <em>not</em> sacrificed all @@ -1071,7 +1071,7 @@ line as soon as available, whereas the default behaviour is to print all the lines together and the end of the computation.</p> </div> <div class="section" id="a-realistic-example"> -<h2><a class="toc-backref" href="#id25">A realistic example</a></h2> +<h2><a class="toc-backref" href="#id23">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 @@ -1135,7 +1135,7 @@ optional arguments: <p>You can check for yourself that the script works.</p> </div> <div class="section" id="keyword-arguments"> -<h2><a class="toc-backref" href="#id26">Keyword arguments</a></h2> +<h2><a class="toc-backref" href="#id24">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">"name=value"</tt> in the @@ -1195,7 +1195,7 @@ is a consequence of the way the argument names are managed in function calls by the Python language.</p> </div> <div class="section" id="final-example-a-shelve-interface"> -<h2><a class="toc-backref" href="#id27">Final example: a shelve interface</a></h2> +<h2><a class="toc-backref" href="#id25">Final example: a shelve interface</a></h2> <p>Here is a less trivial example for the keyword arguments feature. The use case is the following: suppose we have stored the configuration parameters of a given application into a Python shelve @@ -1317,7 +1317,7 @@ ishelve.py: error: unrecognized arguments: .cler </pre> </div> <div class="section" id="plac-vs-argparse"> -<h2><a class="toc-backref" href="#id28">plac vs argparse</a></h2> +<h2><a class="toc-backref" href="#id26">plac vs argparse</a></h2> <p><a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> is opinionated and by design it does not try to make available all of the features of <a class="reference external" href="http://argparse.googlecode.com">argparse</a> in an easy way. In particular you should be aware of the following limitations/differences (the @@ -1415,7 +1415,7 @@ adding such options to the <tt class="docutils literal">main</tt> function for y attribute.</p> </div> <div class="section" id="plac-vs-the-rest-of-the-world"> -<h2><a class="toc-backref" href="#id29">plac vs the rest of the world</a></h2> +<h2><a class="toc-backref" href="#id27">plac vs the rest of the world</a></h2> <p>Originally <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> boasted about being "the easiest command-line arguments parser in the world". Since then, people started pointing out to me various projects which are based on the same idea @@ -1437,12 +1437,15 @@ easier than <a class="reference external" href="http://pypi.python.org/pypi/plac library and as such it shares many features with the module <a class="reference external" href="http://packages.python.org/cmd2/">cmd2</a> by Catherine Devlin. However, this is completely coincidental, since I became aware of the <a class="reference external" href="http://packages.python.org/cmd2/">cmd2</a> module only after writing <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a>.</p> -<p>Command-line argument parsers keep coming out; between the newcomers -I will notice <a class="reference external" href="https://github.com/pulp/marrow.script">marrow.script</a> by Alice Bevan-McGregor, which is quite -similar to <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> in spirit, but does not rely on <a class="reference external" href="http://argparse.googlecode.com">argparse</a> at all.</p> +<p>Command-line argument parsers keep coming out; between the newcomers I +will notice <a class="reference external" href="https://github.com/pulp/marrow.script">marrow.script</a> by Alice Bevan-McGregor, which is quite +similar to <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> in spirit, but does not rely on <a class="reference external" href="http://argparse.googlecode.com">argparse</a> at all. +<a class="reference external" href="http://packages.python.org/argh">Argh</a> by Andrey Mikhaylenko is also worth mentioning: it is also based +on <a class="reference external" href="http://argparse.googlecode.com">argparse</a>, it came after <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> and I must give credit to the author +for the choice of the name, much funnier than plac!</p> </div> <div class="section" id="the-future"> -<h2><a class="toc-backref" href="#id30">The future</a></h2> +<h2><a class="toc-backref" href="#id28">The future</a></h2> <p>Currently the core of <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> is around 200 lines of code, not counting blanks, comments and docstrings. I do not plan to extend the core much in the future. The idea is to keep the module short: it is and it should @@ -1463,7 +1466,7 @@ they require Python 2.5 to work, whereas <tt class="docutils literal">plac_core. Python 2.3.</p> </div> <div class="section" id="trivia-the-story-behind-the-name"> -<h2><a class="toc-backref" href="#id31">Trivia: the story behind the name</a></h2> +<h2><a class="toc-backref" href="#id29">Trivia: the story behind the name</a></h2> <p>The <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> project started very humbly: I just wanted to make easy_installable my old <a class="reference external" href="http://code.activestate.com/recipes/278844-parsing-the-command-line/">optionparse</a> recipe, and to publish it on PyPI. The original name of <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> was optionparser and the idea behind it was @@ -1488,13 +1491,14 @@ a <a class="reference external" href="http://pypi.python.org/pypi/Clap/0.7">Clap <p>Having little imagination, I decided to rename everything again to plac, an anagram of clap: since it is a non-existing English name, I hope nobody will steal it from me!</p> -<p>That's all, I hope you will enjoy working with <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a>!</p> +<p>That concludes the section about the basic usage of <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a>. You are now ready to +read about the advanced usage.</p> </div> </div> <div class="section" id="advanced-usages-of-plac"> -<h1><a class="toc-backref" href="#id32">Advanced usages of plac</a></h1> +<h1><a class="toc-backref" href="#id30">Advanced usages of plac</a></h1> <div class="section" id="introduction"> -<h2><a class="toc-backref" href="#id33">Introduction</a></h2> +<h2><a class="toc-backref" href="#id31">Introduction</a></h2> <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 @@ -1517,7 +1521,7 @@ or a Web application on top of <a class="reference external" href="http://pypi.p 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"> -<h2><a class="toc-backref" href="#id34">From scripts to interactive applications</a></h2> +<h2><a class="toc-backref" href="#id32">From scripts to interactive applications</a></h2> <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 @@ -1621,7 +1625,7 @@ are using a recent version of Python (>= 2.5), because it is a context manager object which uses extended generators internally.</p> </div> <div class="section" id="testing-a-plac-application"> -<h2><a class="toc-backref" href="#id35">Testing a plac application</a></h2> +<h2><a class="toc-backref" href="#id33">Testing a plac application</a></h2> <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 @@ -1686,7 +1690,7 @@ 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"> -<h2><a class="toc-backref" href="#id36">Plac easy tests</a></h2> +<h2><a class="toc-backref" href="#id34">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 @@ -1779,7 +1783,7 @@ a string containing directory names separated by colons). If the variable 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"> -<h2><a class="toc-backref" href="#id37">Plac batch scripts</a></h2> +<h2><a class="toc-backref" href="#id35">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. @@ -1831,7 +1835,7 @@ the output of the batch script and turn it into a <tt class="docutils literal">. (cool, isn't it?).</p> </div> <div class="section" id="implementing-subcommands"> -<h2><a class="toc-backref" href="#id38">Implementing subcommands</a></h2> +<h2><a class="toc-backref" href="#id36">Implementing subcommands</a></h2> <p>When I discussed the <tt class="docutils literal">ishelve</tt> implementation in the <a class="reference external" href="http://plac.googlecode.com/hg/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 @@ -1859,7 +1863,7 @@ class ShelveInterface(object): 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 '\ + self.__doc__ += '\nOperating on %s.\nUse help to see '\ 'the available commands.\n' % self.fname def __enter__(self): self.sh = shelve.open(self.fname) @@ -1891,6 +1895,7 @@ main = ShelveInterface # useful for the tests if __name__ == '__main__': plac.Interpreter.call(ShelveInterface) + </pre> <p><tt class="docutils literal">plac.Interpreter</tt> objects wrap context manager objects consistently. In other words, if you wrap an object with @@ -1904,8 +1909,8 @@ implemented any error checking in the <tt class="docutils literal">show</tt> and 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">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. @@ -1916,12 +1921,12 @@ it allows you to display the traceback of the last executed command.</p> $ python ishelve2.py A minimal interface over a shelve object. Operating on /home/micheles/conf.shelve. -.help to see the available commands. -i> .help +Use help to see the available commands. +i> help special commands ================ -.help .last_tb +last_tb custom commands =============== @@ -1957,9 +1962,21 @@ i> </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> +<p>CHANGED IN VERSION 0.9: if you have an old version of <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> the +<tt class="docutils literal">help</tt> command must be prefixed with a dot, i.e. you must write +<tt class="docutils literal">.help</tt>. The old behavior was more consistent in my opinion, since +it made it clear that the <tt class="docutils literal">help</tt> command was special and threated +differently from the regular commands. However many users complained against +the dot, so I changed it to make them happy. Starting from release 0.9 +the <tt class="docutils literal">help</tt> command is just an alias for <tt class="docutils literal"><span class="pre">--help</span></tt>, in the +sense that there is a preprocessor step replacing <tt class="docutils literal">help</tt> with <tt class="docutils literal"><span class="pre">--help</span></tt> +in the argument list. +Notice that if you implement a custom <tt class="docutils literal">help</tt> command in the commander class +the preprocessor will be automatically disabled: passing <tt class="docutils literal">help</tt> +will call the custom help command, just as you would expect.</p> </div> <div class="section" id="plac-interpreter-call"> -<h2><a class="toc-backref" href="#id39">plac.Interpreter.call</a></h2> +<h2><a class="toc-backref" href="#id37">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 a callable with the list of 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 @@ -2025,7 +2042,7 @@ for the commands to execute:</p> $ python ishelve3.py -i A minimal interface over a shelve object. Operating on /home/micheles/conf.shelve. -.help to see the available commands. +Use help to see the available commands. i> </pre> @@ -2050,7 +2067,7 @@ 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"> -<h2><a class="toc-backref" href="#id40">Readline support</a></h2> +<h2><a class="toc-backref" href="#id38">Readline support</a></h2> <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 @@ -2064,7 +2081,8 @@ database interface understanding SQL commands:</p> import os, plac from sqlalchemy.ext.sqlsoup import SqlSoup -SQLKEYWORDS = set(['select', 'from', 'inner', 'join', 'outer', 'left', 'right'] +SQLKEYWORDS = set(['help', 'select', 'from', + 'inner', 'join', 'outer', 'left', 'right'] ) # and many others DBTABLES = set(['table1', 'table2']) # you can read them from the db schema @@ -2117,10 +2135,10 @@ 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 +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> .help set +i> help set usage: set name value set name value @@ -2129,15 +2147,15 @@ positional arguments: name value -i> .help delete +i> help delete usage: delete [name] delete given parameter (or everything) positional arguments: - name + name [None] -i> .help show +i> help show usage: show [names [names ...]] show given parameters @@ -2162,7 +2180,7 @@ NameError: Ambiguous command 'sh': matching ['showall', 'show'] </pre> </div> <div class="section" id="the-plac-runner"> -<h2><a class="toc-backref" href="#id41">The plac runner</a></h2> +<h2><a class="toc-backref" href="#id39">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>, 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). @@ -2272,7 +2290,7 @@ a=1 on the <tt class="docutils literal">main</tt> object of the Python module.</p> </div> <div class="section" id="a-non-class-based-example"> -<h2><a class="toc-backref" href="#id42">A non class-based example</a></h2> +<h2><a class="toc-backref" href="#id40">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 @@ -2387,7 +2405,7 @@ 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"> -<h2><a class="toc-backref" href="#id43">Writing your own plac runner</a></h2> +<h2><a class="toc-backref" href="#id41">Writing your own plac runner</a></h2> <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 @@ -2464,7 +2482,7 @@ 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"> -<h2><a class="toc-backref" href="#id44">Long running commands</a></h2> +<h2><a class="toc-backref" href="#id42">Long running commands</a></h2> <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 @@ -2513,7 +2531,7 @@ the interface responsive. <a class="reference external" href="http://pypi.python and processes.</p> </div> <div class="section" id="threaded-commands"> -<h2><a class="toc-backref" href="#id45">Threaded commands</a></h2> +<h2><a class="toc-backref" href="#id43">Threaded commands</a></h2> <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> @@ -2619,7 +2637,7 @@ if __name__ == '__main__': </pre> </div> <div class="section" id="running-commands-as-external-processes"> -<h2><a class="toc-backref" href="#id46">Running commands as external processes</a></h2> +<h2><a class="toc-backref" href="#id44">Running commands as external processes</a></h2> <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 @@ -2662,7 +2680,7 @@ 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"> -<h2><a class="toc-backref" href="#id47">Managing the output of concurrent commands</a></h2> +<h2><a class="toc-backref" href="#id45">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 @@ -2713,7 +2731,7 @@ if __name__ == '__main__': </pre> </div> <div class="section" id="monitor-support"> -<h2><a class="toc-backref" href="#id48">Monitor support</a></h2> +<h2><a class="toc-backref" href="#id46">Monitor support</a></h2> <p>Starting from release 0.8 <a class="reference external" href="http://pypi.python.org/pypi/plac">plac</a> provides builtin support for monitoring the output of concurrent commands, at least for platforms where multiprocessing is fully supported. You can define your own monitor @@ -2752,7 +2770,7 @@ of the command. Notice that if <tt class="docutils literal">Tkinter</tt> is not on your system the <tt class="docutils literal">TkMonitor</tt> class will not be available.</p> </div> <div class="section" id="parallel-computing-with-plac"> -<h2><a class="toc-backref" href="#id49">Parallel computing with plac</a></h2> +<h2><a class="toc-backref" href="#id47">Parallel computing with plac</a></h2> <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 popularized by @@ -2887,7 +2905,7 @@ shows another couple of examples of usage, including how to show the results of the running computation on a <tt class="docutils literal">TkMonitor</tt>.</p> </div> <div class="section" id="the-plac-server"> -<h2><a class="toc-backref" href="#id50">The plac server</a></h2> +<h2><a class="toc-backref" href="#id48">The plac server</a></h2> <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 @@ -2933,7 +2951,7 @@ Connection closed by foreign host. </pre> </div> <div class="section" id="summary"> -<h2><a class="toc-backref" href="#id51">Summary</a></h2> +<h2><a class="toc-backref" href="#id49">Summary</a></h2> <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 @@ -2959,7 +2977,7 @@ given port number (default 2199)</li> </div> <hr class="docutils" /> <div class="section" id="appendix-custom-annotation-objects"> -<h2><a class="toc-backref" href="#id52">Appendix: custom annotation objects</a></h2> +<h2><a class="toc-backref" href="#id50">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 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> |