1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453
|
NEWS for cliapp
===============
Version 1.20140719
------------------
* The way logging is set up has been split into smaller methods, to
allow overriding better. See `setup_logging_handler_for_file`,
`setup_logging_formatter_for_file`, and
`setup_logging_formatter_for_syslog`.
* Plugins no longer need to define a `disable` method: the default
implementation is now a no-op, instead of raising
`NotImplementedError`.
Bug fixes:
* When getting help for a subcommand, cliapp would crash saying
`get_help_text_formatter` couldn't be found. This has been fixed.
Version 1.20140315
------------------
* Portability patch to disable VmRSS reporting on non-Linux platforms.
The code assumed that /proc/self/status exists, but that's only true
on Linux. Patch from Itamar Turner-Trauring.
* `cliapp` now logs the current working directory, uid, effective uid,
gid, and effective gid at startup.
* `cliapp` (`Settings.load_configs`) now reports an unknown
variable in a configuration file with a nice error message, rather
than a stack trace.
* A new method, `cliapp.Application.get_subcommand_help_formatter`
allows overriding how the full help text for a subcommand is to be
formatted. This can be useful for allowing help texts be marked up
in, say, Markdown.
* The `cliapp.Settings.require` method now accepts many setting names,
and check for all of them. Patch by Stephen Judd.
Version 1.20130808
------------------
* Bug fix to cliapp.runcmd pipeline handling: the pipeline now returns
failure if any of the processes fails, rather than only the last one.
Found and reported by Richard Maw.
* Fix a problem in the pipeline code in runcmd. Reported and fix provided
by Richard Maw.
Version 1.20130613
------------------
* cliapp(5) now mentions subcommands and the automatic subcommand
"help".
* `ssh_runcmd` now has the `tty` keyword argument to enable ssh
allocation of pseudo-TTYs. Patch from Jannis Pohlmann.
* The `help` subcommand now writes a useful error message, instead of
a stack trace, if given an unknown subcommand. Reported by Rob Taylor.
Version 1.20130424
------------------
* The API documentation has been split into more than one page.
Bug fixes:
* `cliapp.runcmd` no longer dies from the `SIGWINCH` signal.
Version 1.20130313
------------------
* Add `cliapp.Application.compute_setting_values` method. This allows
the application to have settings with values that are computed after
configuration files and the command line are parsed.
* Cliapp now logs the Python version at startup, to aid debugging.
* `cliapp.runcmd` now logs much less during execution of a command. The
verbose logging was useful while developing pipeline support, but has
now not been useful for months.
* More default settings and options have an option group now, making
`--help` output prettier.
* The `--help` output and the output of the `help` subcommand now only
list summaries for subcommands. The full documentation for a subcommand
can be seen by giving the name of the subcommand to `help`.
* Logging setup is now more overrideable. The `setup_logging` method
calls `setup_logging_handler_for_syslog`,
`setup_logging_handler_for_syslog`, or
`setup_logging_handler_to_file`, and the last one calls
`setup_logging_format` and `setup_logging_timestamp` to create the
format strings for messages and timestamps. This allows applications
to add, for example, more detailed timestamps easily.
* The process and system CPU times, and those of the child processes,
and the process wall clock duration, are now logged when the memory
profiling information is logged.
* Subcommands added with `add_subcommand` may now have aliases.
Subcommands defined using `Application` class methods named `cmd_*`
cannot have aliases.
* Settings and subcommands may now be hidden from `--help` and `help`
output. New option `--help-all` and new subcommand `help-all` show
everything.
* cliapp(5) now explains how `--generate-manpage` is used. Thanks to
Enrico Zini for the suggestion.
* New function `cliapp.ssh_runcmd` for executing a command remotely
over ssh. The function automatically shell-quotes the argv array
given to it so that arguments with spaces and other shell meta-characters
work over ssh.
* New function `cliapp.shell_quote` quotes strings for passing as shell
arguments.
* `cliapp.runcmd` now has a new keyword argument: `log_error`. If set to
false, errors are not logged. Defaults to true.
Bug fixes:
* The process title is now set only if `/proc/self/comm` exists.
Previously, on the kernel in Debian squeeze (2.6.32), setting the
process title would fail, and the error would be logged to the
terminal. Reported by William Boughton.
* A setting may no longer have a default value of None.
Version 1.20121216
------------------
* Options in option groups are now included in manual page SYNOPSIS and
OPTIONS sections.
* `--log=syslog` message format improvement by Daniel Silverstone.
No longer includes a timestamp, since syslog adds it anyway. Also,
the process name is now set on Linux.
* Make the default subcommand argument synopsis be an empty string, instead
of None. Reported by Sam Thursfield.
* Meliae memory dumping support has been fixed. Reported by Joey Hess.
* Memory profiling reports can now be done at minimum intervals in
seconds, rather than every time the code asks for them. This can
reduce the overhead of memory profiling quite a lot.
* If there are any subcommands, cliapp now adds a subcommand called `help`,
unless one already exists.
* For every boolean setting foo, there will no be a --no-foo option to be
used on the command line.
Version 1.20120929
------------------
* Print error messages from `SystemExit` exceptions. As a side effect,
this fixes the problem that an unknown subcommand would not cause an
error message to be printed.
* Fix a busy-wait problem when `runcmd` runs a command with both
standard output and error redirected to files and there was nothing
to feed to its standard input (i.e., `runcmd` didn't need to write
to the command, or read any of its output). This problem was found
and fixed during work done for Codethink Limited.
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.
|