Release Notes (v2.7.1)#
September 28, 2023
The v2.7.1 release includes major new features along with numerous fixes and improvements.
Automatic rich colorization of usage text with
NO_COLORsupport (see no-color.org).Automatic platform support honoring conventions for Windows and macOS.
Extensions to the standard
loggingmodule.Expose major features in top-level API.
Various fixes and improvements.
Features#
Rich colorization of usage text#
We’ve added a new cmdkit.ansi module to provide a facility for applying ANSI
color support to CmdKit projects. With this comes a new syntax-highlighting feature
for usage and help text, cmdkit.ansi.colorize_usage().
This feature has been added by default to the cmdkit.cli.Interface class
as a default syntax-highlighter. These changes are backwards compatible in terms of
the API. You can provide your own alternate highlighter implementation, or disable
the behavior altogether.
We are also abiding by the community NO_COLOR convention (see no-color.org).
This also works for stderr; in this context though we are speaking of stdout.
If the output stream is not connect to a TTY, colorization is disabled automatically.
Colorization is disabled in the presents of the NO_COLOR environment variable.
This can be forcibly overriden by defining a FORCE_COLOR environment variable.
Developers should use the cmdkit.ansi.STDOUT_COLOR and
cmdkit.ansi.STDERR_COLOR boolean globals to decide whether to apply colorization.
The cmdkit.ansi.colorize_usage() feature automatically abides by this.
Platform specific conventions#
We’ve added a new cmdkit.platform module that provides an AppContext
class which defines useful default behavior with no boilerplate necessary.
Building off the idea behind the from_local() builder method
of the Configuration class, we want to automatically deduce the appropriate
file system paths on not just Posix/Linux, but macOS and Windows as well.
For example, instead of using ~/.myapp.toml for the user-level configuration file path, on
Windows it would be more conventional to have this path as %APPDATA%\MyApp\Config.toml.
We abide by both the %APPDATA% as well as the acceptable use of capitalization.
We’ve extended the Configuration class with a new
from_context() builder method to create an extremely concise
syntax for this sort of conventional application behavior.
See the full-hello.py example
in the Tutorial section.
Built-in Logging extensions#
Python’s builtin logging module is the de facto standard logging interface and allows for
control of logging even for third-party packages not controlled by the developer.
It has a few notable missing features and attributes that might be useful to an application developer. For example, additional granularity of logging levels, additional attributes such as the hostname of the machine you are running on, rich color support, etc.
All of these can be modified easily enough. The new cmdkit.logging module applies these
additional features and behaviors by extending the Logger and LogRecord
class.
Worth mentioning is the new logging_styles dictionary contained named
formats (such as default, short, detailed, detailed-compact, and system). These
named formats allow for easily switching between what can be failure complicated definition
strings.
Available styles include:
default(colorized level, module name)short(colorized level name only)detailed(colorized time stamp, hostname, level name, module name)detailed-compact(colorized relative time stamp, short hostname, level name, relative module name)system(similar todetailedbut without colorization and includes application UUID).
Top-level API#
Instead of needing to make multiple imports to submodules for every feature within cmdkit, all major features/classes are not exposed at the top-level.
Instead of
from cmdkit.app import Application, exit_status
from cmdkit.cli import Interface
The following is now supported
from cmdkit import Application, Interface, exit_status