NEWS for cliapp
===============


Version 0.23, released 2011-12-18
---------------------------------

* Back off from using the `logging.NullHandler` class, since that exists
  only in Python 2.7, and we want to support 2.6 too.

Version 0.22, released 2011-12-03
---------------------------------

* The `runcmd` and `runcmd_unchecked` methods have had an API change: the
  `stdin` argument is now called `feed_stdin`. This is so that callers may
  use `stdin` to control how the `subprocess.Popen` module sets up the
  child program's standard input.
* Syslog support has been added. Use `--log=syslog`.

Version 0.21, released 2011-10-02
---------------------------------

* License changed to GPL version 2 or later.

Version 0.20, released 2011-09-17
---------------------------------

* `cliapp(5)` manual page added, to explain in one place how applications
  built on cliapp will parse command lines and configuration files.
* The manual pages can now specify how the non-option arguments are formatted,
  in manual pages, including for each subcommand separately.

Version 0.19, released 2011-09-04
---------------------------------

* Subcommand descriptions are formatted more prettily, in --help output.
* When a string list setting is set in a configuration file, any use of
  the corresponding option overrides the value from the configuration
  file, rather than appending to it.

Version 0.18, released 2011-08-24
---------------------------------

* New `cliapp.Settings.dump_config` method, which can be useful, for example,
  if an application wants to save its configuration, or log it at startup.

Version 0.17, released 2011-08-22
---------------------------------

* Give more humane error messages for IOError and OSError exceptions.
* The `runcmd` and `runcmd_unchecked` methods now allow overriding
  the standard output and error redirections.
* Memory profiling statistics can now be logged by the application,
  by calling the `cliapp.Application.dump_memory_profile` method.
  The `--dump-memory-profile` setting is provided by the user to 
  specify how the profiling is done: simple RSS memory size, and
  meliae and heapy Python memory profilers are supported.

Version 0.16, released 2011-08-19
---------------------------------

* An EPIPE error when writing to stdout is suppressed. This avoids a Python
  stack trace or other error when user pipes output to, say, less, and 
  quits less before the application finishes writing everything to stdout.
* Improve description of --log. (Thanks, Tapani Tarvainen.)

Version 0.15.1, released 2011-08-03
-----------------------------------

* Fix parsing of string list options: their values were being added
  twice so `-foo=bar` would result in `settings['foo']` having the
  values `['bar', 'bar']`. Oops. As a result, the `parse_args` method
  has a new keyword argument, `configs_only`, which it should pass
  onto `Settings.parse_args`.
* The argument names for the `process_input_line` method have been
  improved.

Version 0.15, released 2011-08-02
---------------------------------

* `cliapp.Application` now has a `subcommands` attribute, which is a
  directory mapping subcommand names to the functions that implement
  them. This provides an alternative way to define new subcommands,
  which may be useful in plugin-based applications.
* New method `cliapp.Application.runcmd_unchecked`.
* There are some new options provided by defaults:
  - `--list-config-files` lists the config files the application will try
    to read
  - `--config=FILE` adds a file to the list of configuration files to be
    read
  - `--no-default-configs` prevents any of the default configuration files
    from being used; any `--config` options used after this one will still
    be read
* Parsing of string list values in config files has been fixed. INI files
  have no standard syntax for presenting files (maybe JSON would be a 
  better option), but I invented something. How very clever of me.
  At the same time, `--dump-config` now formats string list values
  properly.
* Default values for string lists work better now: the default is used,
  unless the user specifies some values, in which only the values from
  the user are used.

Version 0.14, released 2011-07-20
---------------------------------

* Start and end of program are now logged. This makes it easier to read
  log files.
* Commands run by the `runcmd` method are now logged.
* Bugfix: `runcmd` now passes extra arguments to `subprocess.Popen`.
* A `Settings.require` method is added, so that it's easy to fail if the
  user has failed the give an option that is required in a given situation.
  (Mandatory options are a bit weird, but sometimes they happen.)
* Subcommands may now be added explicitly, using the 
  `Application.add_subcommand` method. This is helpful for applications that
  support plugins, for example.

Version 0.13, released 2011-06-18
---------------------------------

* Change default log level to be `debug`. Nothing is logged unless the
  user requests it, and if they do, they probably want to debug something,
  so this seems like the natural default.
* Log files are now rotated. See options --log-max, --log-keep.
* Log files are formatted in a nicer way now.
* Now registered with PyPI.
* String list settings now have a more sensible handling of default values.
  Previously the default value would always be used and user-supplied
  values would be appended to the default. Now user-supplied values
  replace the default value entirely.
* The old API for adding settings (`self.settings.add_string_setting` etc)
  is gone. This should not bother anyone, since I am the only known user
  of cliapp so far, and I've fixed my stuff already.
* A `metavar` is provided if caller does not provide one. This fixes
  `--generate-manpage` issue where an option would be documented as not
  having an argument unless `metavar` was set explicitly.
* `cliapp.Application.runcmd` runs external programs and captures their
  standard output.
* The option parser is now created in a separate method than the one that
  uses it. This allows applications to modify the option parser in whatever
  way they want.
* Only the basename of a program (from `sys.argv[0]`) is used when
  determining `progname`. This fixes a problem where config files
  could not be found because `progname` contained slashes.

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
---------------------------------

* `pydoc cliapp` now works more usefully, and includes documentation for
  the various classes exported, not just a list of packages.
* Bugfix: if user specifies no log file, logging no longer happens to
  the standard output. This prevents exceptions from being reported twice.
* Log format now includes timestamps.
* New settings can now be added using shorter method names:
  `self.settings.string` rather than `self.settins.add_string_setting`.
  The old method names continue to work.

Version 0.10, released 2011-03-21
--------------------------------

* The `metavar` argument for `optparse.OptionParser` can now be set for
  settings. This makes for prettier `--help` output.
* The default value for integer settings is now 0, not `None`.
* [[README]] now has some more documentation of how to use the framework.

Version 0.9, released 2011-03-21
--------------------------------

* Bugfix: Boolean options now work correctly, even in --help output.

Version 0.8, released 2011-03-20
--------------------------------

* Bugfix: duplicate option names in --help output fixed.
* Exception handling has been improved: stack traces are now logged, and
  there's a `cliapp.AppException` base class for application exceptions,
  which will cause an error message to be written out, but no stack trace.
  All other exceptions cause a stack trace, so as to make it easier to debug
  things.

Version 0.7, released 2011-03-12
--------------------------------

* Add configuration file support.
* API change: all settings are now in a class of their own, and are accessed
  via `app.settings`, e.g., `app.settings['output']`. See the `cliapp.Settings`
  class. This change breaks old code, sorry. But since I am still the only
  user, nobody minds.
* The callback setting type is now gone.
* Application name can now be set via the Application class's initializer
  (optional `progname` argument), or by assigning to 
  `cliapp.Settings.progname`. If not set explicitly, it is set from
  `sys.argv[0]`.

Version 0.6, released 2011-02-19
--------------------------------

* New option types: list of strings, choice of strings, callback.
* New standard option: --dump-setting-names.
* Python profiling support: automatically if the right environment variable
  is set. If the process's argv[0] is 'foo', and 'FOO_PROFILE' is set, then
  profiling happens.
* Documentation improvments.

Version 0.5, released 2011-02-13
--------------------------------

* Catches exceptions and prints error message, instead of having the Python
  interpreter do a stack trace.
* Support more traditional Unix command line filter behavior: read from
  stdin if no arguments are given, or a dash ('-') is given as the filename.
* Count files and lines in files.
* New options: --output, --log, --log-level.


Version 0.4, released 2011-01-30
--------------------------------

* Bugfix: Subclasses can now actually set the application version, so
  that --version works.
