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


Version 1.20120630
------------------

* New version numbering scheme: `API.DATE`.
* cliapp now logs the command line and all settings, and the environment
  variables when the application starts. This helps when debugging problems 
  other people are having.
* The `cliapp.runcmd` and `cliapp.runcmd_unchecked` functions are now
  callable without having a `cliapp.Application` instance. This makes
  it easier to use them in large programs.
* All types of settings can now have a `group` keyword argument for
  grouping them in the `--help` output.

Version 0.29, released 2012-05-09
---------------------------------

* Pointless error message about exit code of an application removed.
  It is one of the mysteries of the universe why this ever made sense
  at all.

Version 0.28, released 2012-05-08
---------------------------------

* Log files are now created using a 0600 file mode by default. The new
  option `--log-mode` can be used to change that.
* Logging can now be disabled using `--log=none`. This is useful for
  overriding on the command a logging setting from a configuration file.
* `for name in settings` and `settings.keys()` now work, making the settings
  class act more like an object. Thanks to Jannis Pohlmann for giving the
  inpiration for this change.
* Settingses can now be grouped, using the new keyword argment `group` to
  the various methods to add a new setting. The grouping affects `--help`
  output only. The value to `group` is the title of the group.
* There is now a plugin system included in cliapp.

Version 0.27, released 2012-02-17
---------------------------------

* Bug fix: The `runcmd` and `runcmd_unchecked` methods now properly add the
  name of the program that failed to execute to the error message. This
  did not always happen previously, depending on race conditions on getting
  errors from a child process.

Version 0.26, released 2012-02-11
---------------------------------

* `cliapp.Settings` now allows access to all sections in configuration 
  files. The new `as_cp` method returns a `ConfigParser` instance, which  
  is set to the current value of every registered setting, in the `config` 
  section, plus any additional sections in the configuration files that
  have been read.

Version 0.25.2, released 2012-02-08
---------------------------------

* Fixed another bug in the process pipelining support. This time it was
  a silly Python optional argument handling problem.

Version 0.25.1, released 2012-02-08
---------------------------------

* Fix bug in the process pipelining support.

Version 0.25, released 2012-02-06
---------------------------------

* Improved error message for when executing a non-existent command.
* `cliapp.Application.runcmd` and `runcmd_unchecked` can now execute a
  pipeline.
* New overrideable methods `cliapp.Application.setup` and `cleanup` make
  it easier to add code to be run just before and after `process_args`.

Version 0.24, released 2012-01-14
---------------------------------

* Show the subcommand synopsis in --help output.
* Bug fix: setting a boolean setting to false in a configuration file now
  works. Thanks to Richard Maw for the bug report.

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.