diff options
| -rw-r--r-- | NEWS | 8 | ||||
| -rw-r--r-- | README | 110 | ||||
| -rw-r--r-- | debian/changelog | 4 | ||||
| -rw-r--r-- | debian/source/format | 2 | ||||
| -rw-r--r-- | setup.py | 2 |
5 files changed, 15 insertions, 111 deletions
@@ -1,6 +1,14 @@ NEWS for cliapp =============== +Version 0.12, released 2011-05-29 +--------------------------------- + +* The new option `--generate-manpage` allows one to fill in the OPTIONS + section of a manpage. +* `cliapp` now supports **subcommands**, e.g., "git help". +* API documentation is now formatted using Sphinx. + Version 0.11, released 2011-03-21 --------------------------------- @@ -1,123 +1,19 @@ README for cliapp ================= -cliapp is a Python framework for Unix-like command line programs, -which typically have the following characteristics: - -* non-interactive -* the programs read input files, or the standard input -* each line of input is processed individually -* output is to the standard output -* there are various options to modify how the program works -* certain options are common to all: --help, --version - -Programs like the above are often used as _filters_ in a pipeline. +cliapp is a Python framework for Unix-like command line programs. The scaffoling to set up a command line parser, open each input file, read each line of input, etc, is the same in each program. Only the logic of what to do with each line differs. -cliapp is not restricted to line-based filters, but is a more -general framework. It provides ways for its users to override -most behavior. For example: - -* you can treat command line arguments as URLs, or record identfiers - in a database, or whatever you like -* you can read input files in whatever chunks you like, or not at all, - rather than forcing a line-based paradigm - -There are plans to support plugins, configuration files, logging, etc, -as well. Despite all the flexibility, writing simple line-based filters -will remain very straightforward. The point is to get the framework to -do all the usual things, and avoid repeating code across users of the -framework. - +See the API documentation on the `doc` subdirectory for details +(or see <http://code.liw.fi/cliapp/docs/> for a pre-formatted version). Example ------- See the file `example.py` for an example of how to use the framework. - -Walkthrough ------------ - -Every application should be a class that subclasses `cliapp.Application`. -The subclass should provide specific methods. Read the documentation -for the `cliapp.Application` class to see all methods, but a rough -summary is here: - -* the `settings` attribute is the `cliapp.Settings` instance used by - the application -* override `add_settings` to add new settings for the application -* override `process_*` methods to override various stages in how - arguments and input files are processed -* override `process_args` to decide how each argument is processed; - by default, this called `process_inputs` -* `process_inputs` calls `process_input` (note singular) for each - argument, or on `-` to process standard input if no files are named - on the command line -* `process_input` calls `open_input` to open each file, then calls - `process_input_line` for each input line -* `process_input_line` does nothing, by default - -This cascade of overrideable methods is started by the `run` -method, which also sets up logging, loads configuration files, -parses the command line, and handles reporting of exceptions. -It can also run the rest of the code under the Python profiler, -if the appropriate environment variable is set. - - -Subcommands ------------ - -Sometimes a command line tool needs to support subcommands. -For example, version control tools often do this: -`git commit`, `git clone`, etc. To do this with cliapp, -you need to add methods with names like `cmd_commit` and -`cmd_clone`: - - class VersionControlTool(cliapp.Application): - - def cmd_commit(self, args): - pass - def cmd_clone(self, args): - pass - -If any such methods exist, cliapp automatically supports -subcommands. The name of the method, without the `cmd_` prefix, -forms the name of the subcommand. Any underscores in the method -name get converted to dashes in the command line. Case is -preserved. - -All options are global, not specific to the subcommand. -All non-option arguments are passed to the method in its only -argument. - -Subcommands are implemented by the `process_args` method. -If you override that method, you need to support subcommands -yourself (perhaps by calling the `cliapp` implementation). - - -Manual pages ------------- - -A high quality manual page probably needs to be written from -scratch. For example, the description of each option in a manual -page should usually be longer than what is suitable for -`--help` output. However, it is tedious to write option -descriptions many times. - -`cliapp` provides a way to fill in a manual page template, in -**troff**(1) format, with information about all options. This -allows you to write the rest of the manual page without having -to remember to update all options. This is a compromise between -ease-of-development and manual page quality. - -To use this, use the `--generate-manpage=TEMPLATE` option, -where `TEMPLATE` is the name of the template file. See -`example.1` for an example. - - Legalese -------- diff --git a/debian/changelog b/debian/changelog index 2b8e165..0a5157f 100644 --- a/debian/changelog +++ b/debian/changelog @@ -1,8 +1,8 @@ -python-cliapp (0.12) UNRELEASED; urgency=low +python-cliapp (0.12-1) unstable; urgency=low * Upload for Debian. (Closes: #628017) - -- Lars Wirzenius <liw@liw.fi> Thu, 26 May 2011 13:53:19 +0100 + -- Lars Wirzenius <liw@liw.fi> Sun, 29 May 2011 15:31:20 +0100 python-cliapp (0.11) squeeze; urgency=low diff --git a/debian/source/format b/debian/source/format index 89ae9db..163aaf8 100644 --- a/debian/source/format +++ b/debian/source/format @@ -1 +1 @@ -3.0 (native) +3.0 (quilt) @@ -20,7 +20,7 @@ from distutils.core import setup, Extension import cliapp setup(name='cliapp', - version=cliapp.version, + version=cliapp.__version__, description='Framework for Unix command line applications', author='Lars Wirzenius', author_email='liw@liw.fi', |