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_COLOR support (see no-color.org).

  • Automatic platform support honoring conventions for Windows and macOS.

  • Extensions to the standard logging module.

  • 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 to detailed but 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

On this page
Show Source