cmd2

What's Changed

• Fix ty unresolved-attribute warnings and add mypy back by @tleonhardt in #1737
• Update ruff to version 0.16.5 by @tleonhardt in #1738
• Bump github/codeql-action from 4.37.8 to 4.37.9 by @dependabot[bot] in #1740
• Update readme by @tleonhardt in #1739

Full Changelog: 4.2.2...4.2.3

• Documentation Improvements
  • Improved documentation in attempt at making some recommended best-practices more discoverable
  • Fixed the broken cmd_as_argument example

• Enhancements
  • Added bracketed paste support so multiple pasted commands execute sequentially and multiline commands continue as expected.
• Bug Fixes
  • Enabled Ctrl-Z suspension at the prompt

• Enhancements
  • @with_annotated argument groups can now contain an ArgumentBlock's arguments. A Group member names a command-line argument, and a block expands into one argument per field, so its fields are named: Group("host", "port").
• Breaking Changes
  • A Group member now names an argument rather than a parameter. The two differ only for an ArgumentBlock parameter, which is expanded away and has no argument of its own: Group("conn") now raises ValueError pointing at the block's fields. It previously produced an empty argument group in groups= and a KeyError in mutually_exclusive_groups=.
  • Whether a Group member exists is now validated when the parser is built rather than at decoration time, because a block's field names cannot be known without resolving its type hint, and resolving hints eagerly would break forward-referenced annotations. A typo in a member name still raises ValueError, but on first use of that command rather than at class definition. The spec-shape rules (a member listed twice, a member in two groups, required=True on a plain group, the mutex nesting rules) are unaffected and still hard-fail at decoration time.
• Bug Fixes
  • Fixed @with_annotated(base_command=True) not listing its subcommands under the positional arguments section of the parent command's --help, unlike argparse and Cmd2ArgumentParser. They were placed in an untitled section of their own instead. Passing subcommand_title or subcommand_description still gives the subcommands a dedicated section (#1715).
  • Fix @with_annotated decorator so using ArgumentBlock works with groups (#1718).
  • Fixed bug where already sorted choices_provider results were being re-sorted (#1727).

What's Changed

• Updated getting_started.py example to remove multi-line command usage by @tleonhardt in #1713
• [Settable] description argument can now be rich text by @neoniobium in #1712
• Removed redundant ipython import which slowed application startup time by @kmvanbrunt in #1717

New Contributors

• @neoniobium made their first contribution in #1712

Full Changelog: 4.1.1...4.1.2

What's Changed

• Fixed mypy 2.2.0 failures by @tleonhardt in #1709
• Added ability to use Rich renderables as alert messages. by @kmvanbrunt in #1710

Full Changelog: 4.1.0...4.1.1

• Breaking Changes
  • Renamed the bottom_toolbar argument in Cmd.__init__() to enable_bottom_toolbar. It is also now strictly an __init__ parameter and not an instance attribute.
  • complete_in_thread is now strictly an __init__ parameter and not an instance attribute of Cmd.
  • get_rprompt() is now only called if the enable_rprompt argument in Cmd.__init__() is set to True.
• Bug Fixes
  • Fixed type hinting so that methods decorated with with_annotated no longer trigger spurious mypy errors and preserve their original signature.
  • Fixed cmd2 bypassing NO_COLOR and allow_style when setting prompt-toolkit's color depth.
• Enhancements
  • New cmd2.Cmd parameters
    • complete_in_thread: (boolean) if True, then completion will run in a separate thread. If False then completion runs in the main thread and causes it to block if slow. Defaults to True.
    • refresh_interval: (float) How often, in seconds, to automatically refresh the UI. Defaults to 0.0. This is used for bottom toolbars and right prompts which have dynamic content needing to be refreshed at regular intervals and not just when a key is pressed.
  • Improved getting_started.py example
    • Shows how to properly and safely use a background thread to update the bottom toolbar with dynamic content
    • Demonstrates how to use the @with_argparser and @with_argument_block decorators for parsing command arguments
• Experimental features
  • @with_annotated now supports frozenset[T] collection parameters, alongside the existing list[T], set[T], and tuple[T, ...] collection types.
  • @with_annotated mutually exclusive groups now accept a title/description to render the group as a titled help section (argparse's one supported nesting, a mutex inside an argument group), declared in one place with no paired groups= entry.
  • @with_annotated now validates groups / mutually_exclusive_groups specs eagerly at decoration time, so a misconfigured group (a member that names no parameter, a parameter placed in two groups, a mutex group spanning or partially overlapping argument groups, a titled section declared in two places, or Group(required=True) on a plain group) hard-fails when the class is defined instead of being deferred to first command use where the error was swallowed. The checks read parameter names only, so forward-referenced annotations still decorate cleanly.
  • Argument/Option accept a new allow_unknown_entry flag for Enum parameters. When set, a command-line token matched by neither a member value nor name is routed through the enum's own _missing_ hook, so an enum can resolve aliases, alternate spellings, or special keywords. A token that _missing_ declines (returns None) is still rejected.
  • @with_annotated now supports a union of Enum subclasses (e.g. EnumA | EnumB). Each member keeps its own converter and a token resolves to the first member that accepts it, so when two members share a representation the earlier one in the union wins. A member whose _missing_ raises on a token declines it (the next member is still tried) rather than aborting the union, and a merged "choose from ..." error is raised only when every member declines. Unions containing a Literal or any non-Enum member are still rejected as ambiguous.
  • Argument/Option accept new converter and preprocess hooks for custom string conversion, giving @with_annotated parity with a hand-built add_argument(type=...) (a raw type= in the metadata is still rejected). converter is a Callable[[str], Any] that replaces the inferred type= converter; because it owns the conversion, the annotation may be any type (an otherwise unsupported type like datetime, or an otherwise-ambiguous multi-member union like int | str, becomes legal) and the inferred choices/completer are dropped. preprocess is a Callable[[str], str] that runs before the inferred converter, transforming the raw token while keeping the inferred type=/choices/completer (e.g. preprocess=str.lower on an Enum). The two are mutually exclusive on one parameter and neither may be combined with a value-less action.
  • @with_annotated now supports reusable argument blocks: a parameter typed with a @dataclass that subclasses the new cmd2.ArgumentBlock trait expands each field into a flat command-line argument, and the parsed values are reconstructed into a dataclass instance passed to the command, letting several commands reuse the same fields without duplication. See the annotated documentation.
  • A command can share an argument block with its subcommands via cmd2_base_args / cmd2_parent_args parameters, passing parent-level options down without redeclaring them.

Summary

cmd2 now has a dependency on prompt-toolkit which serves as a pure-Python cross-platform replacement for GNU Readline. Previously, cmd2 had used different readline dependencies on each Operating System (OS) which was at times a very frustrating developer and user experience due to small inconsistencies in these different readline libraries. Now we have consistent cross-platform support for tab-completion, user terminal input, and history. Additionally, this opens up some cool advanced features such as support for syntax highlighting of user input while typing, auto-suggestions similar to those provided by the fish shell, and the option for a persistent bottom bar that can display realtime status updates while the prompt is displayed.

Details

• Breaking Changes
  • Removed all use of readline built-in module and underlying platform libraries
  • Deleted cmd2.rl_utils module which dealt with importing the proper readline module for each platform and provided utility functions related to readline
  • Added a dependency on prompt-toolkit and a new cmd2.pt_utils module with supporting utilities
  • Dropped support for Python 3.10. cmd2 now requires Python 3.11 or later
  • Removed Transcript Testing feature set along with the history -t option for generating transcript files and the cmd2.transcript module
    • This was an extremely brittle regression testing framework which should never have been built into cmd2
    • We recommend using pytest for unit and integration tests and Robot Framework for acceptance tests. Both of these frameworks can be used to create tests which are far more reliable and less brittle.
  • Async specific: prompt-toolkit starts its own asyncio event loop in every cmd2 application
    • Removed cmd2.Cmd.terminal_lock as it is no longer required to support things like cmd2.Cmd.async_alert
    • Removed cmd2.Cmd.async_refresh_prompt and cmd2.Cmd.need_prompt_refresh as they are no longer needed
  • completer functions must now return a cmd2.Completions object instead of list[str].
  • choices_provider functions must now return a cmd2.Choices object instead of list[str].
  • An argparse argument's descriptive_headers field is now called table_columns.
  • CompletionItem.descriptive_data is now called CompletionItem.table_data.
  • Removed DEFAULT_DESCRIPTIVE_HEADERS. This means you must define table_columns when using CompletionItem.table_data data.
  • Cmd.default_sort_key moved to utils.DEFAULT_STR_SORT_KEY.
  • Moved completion state data, which previously resided in Cmd, into other classes.
    • Cmd.matches_sorted -> Completions.is_sorted and Choices.is_sorted
    • Cmd.completion_hint -> Completions.hint
    • Cmd.formatted_completions -> Completions.table (Now a Rich Table)
    • Cmd.allow_appended_space/allow_closing_quote -> Completions.allow_finalization
  • Removed Cmd.matches_delimited since it's no longer used.
  • Removed flag_based_complete and index_based_complete functions since their functionality is already provided in arpgarse-based completion.
  • Changed Statement.multiline_command from a string to a bool.
  • Made Statement.arg_list a property which generates the list on-demand.
  • Renamed Statement.output to Statement.redirector.
  • Renamed Statement.output_to to Statement.redirect_to.
  • Removed Statement.pipe_to since it can be handled by Statement.redirector and Statement.redirect_to.
  • Changed StatementParser.parse_command_only() to return a PartialStatement object.
  • Renamed Macro.arg_list to Macro.args.
  • Removed terminal_utils.py since prompt-toolkit provides this functionality.
  • Replaced async_alert() and async_update_prompt() with a single function called add_alert(). This new function is thread-safe and does not require you to acquire a mutex before calling it like the previous functions did.
  • Removed Cmd.default_to_shell.
  • Removed Cmd.ruler since cmd2 no longer uses it.
  • All parsers used with cmd2 commands must be an instance of Cmd2ArgumentParser or a child class of it.
  • Renamed set_default_argument_parser_type() to set_default_argument_parser().
  • Renamed set_default_ap_completer_type() to set_default_argparse_completer().
  • Removed set_ap_completer_type() and get_ap_completer_type() since completer_class is now a public member of Cmd2ArgumentParser.
  • Moved set_parser_prog() to Cmd2ArgumentParser.update_prog().
  • Renamed cmd2_handler to cmd2_subcommand_func in the argparse.Namespace for clarity.
  • Removed Cmd2AttributeWrapper class. argparse.Namespace objects passed to command functions now contain direct attributes for cmd2_statement and cmd2_subcommand_func.
  • Renamed cmd2/command_definition.py to cmd2/command_set.py.
  • Removed Cmd.doc_header and the with_default_category decorator. Help categorization is now driven by the DEFAULT_CATEGORY class variable (see Simplified command categorization in the Enhancements section below for details).
  • Removed Cmd.undoc_header since all commands are now considered categorized.
  • Renamed Cmd.cmd_func() to Cmd.get_command_func().
  • cmd2 no longer sets a default title for a subparsers group. If you desire a title, you will need to pass one in like this parser.add_subparsers(title="subcommands"). This is standard argparse behavior.
  • TextGroup now implements HelpFormatterRenderable (see Enhancements section below for more details).
    • Removed formatter_creator parameter from TextGroup.__init__().
    • Removed Cmd2ArgumentParser.create_text_group() method.
  • argparse and Rich integration refactoring:
    • Renamed argparse_custom module to argparse_utils.
    • Moved the following classes from argparse_utils to rich_utils:
      • Cmd2HelpFormatter
      • ArgumentDefaultsCmd2HelpFormatter
      • MetavarTypeCmd2HelpFormatter
      • RawDescriptionCmd2HelpFormatter
      • RawTextCmd2HelpFormatter
      • TextGroup
    • Replaced the global APP_THEME constant in rich_utils.py with get_theme(), reset_theme(), and update_theme() functions in theme.py to support lazy initialization and safer in-place updates of the theme.
  • Renamed Cmd._command_parsers to Cmd.command_parsers.
  • Removed RichPrintKwargs TypedDict in favor of using Mapping[str, Any], allowing for greater flexibility in passing keyword arguments to console.print() calls.
  • Removed always_show_hint settable as it provided a poor user experience with prompt-toolkit
  • cmd2 redirection only captures output directed to self.stdout (e.g., via self.poutput()). Standard print() calls write directly to sys.stdout and are not captured. However, print() calls within pyscripts and the interactive Python shell are treated as command output and sent to self.stdout, allowing them to be captured.
  • Verbose help table descriptions are no longer generated from help function output. The system now relies exclusively on command function docstrings.
  • Removed feedback_to_output settable and changed cmd2.Cmd.pfeedback to always print to self.stdout
  • Removed Cmd.parseline() since it was unused and merely wrapped StatementParser.parse_command_only().
• Enhancements
  • New cmd2.Cmd parameters
    • auto_suggest: (boolean) if True, provide fish shell style auto-suggestions. These are grayed-out hints based on history. User can press right-arrow key to accept the provided suggestion.
    • bottom toolbar: (boolean) if True, present a persistent bottom toolbar capable of displaying realtime status information while the prompt is displayed, see the cmd2.Cmd2.get_bottom_toolbar method that can be overridden as well as the updated getting_started.py example
  • New cmd2.Cmd methods
    • get_bottom_toolbar: populates bottom toolbar if bottom_toolbar is True
    • get_rprompt: override to populate right prompt
    • pre_prompt: hook method that is called before the prompt is displayed, but after
      prompt-toolkit event loop has started
    • read_secret: read secrets like passwords without displaying them to the terminal
    • ppretty: a cmd2-compatible replacement for rich.pretty.pprint()
  • New settables:
    • max_column_completion_results: (int) Maximum number of completion results to display in a single column
    • traceback_show_locals: (bool) Display local variables in tracebacks
  • cmd2.Cmd.select has been revamped to use the choice function from prompt-toolkit when both stdin and stdout are TTYs
  • Add support for Python 3.15 by fixing various bugs related to internal argparse changes
  • Added common_prefix method to cmd2.string_utils module as a replacement for os.path.commonprefix since that is now deprecated in Python 3.15
  • Simplified command categorization:
    • By default, all commands in a class are grouped under its DEFAULT_CATEGORY.
    • Individual commands can still be manually moved using the with_category() decorator.
    • For more details and examples, see the Help documentation and the examples/default_categories.py file.
  • CommandSet is now a generic class, which allows developers to parameterize it with their specific cmd2.Cmd subclass (e.g.,class MyCommandSet(CommandSet[MyApp]):). This provides full type hints and IDE autocompletion for self._cmd without needing to override and cast the property.
  • Added traceback_kwargs attribute to allow customization of Rich-based tracebacks.
  • Added HelpFormatterRenderable protocol and HelpContent type alias to support context-aware help content in argparse.
  • The print() function available in a pyscript writes to self.stdout and respects the allow_style setting. It also supports printing Rich objects.
  • Added Cmd2ArgumentParser.output_to() context manager to temporarily set the output stream during argparse operations. This is helpful for directing output for functions like parse_args(), which default to sys.stdout and lack a file argument.
  • Added ability to customize prompt-toolkit completion menu colors by overriding the following fields in the cmd2 theme:
    • Cmd2Style.COMPLETION_MENU - Base style for the entire completion menu container (sets the background)
    • Cmd2Style.COMPLETION_MENU_COMPLETION -Style for an individual, non-selected completion item
    • Cmd2Style.COMPLETION_MENU_CURRENT - Style for the currently selected completion item
    • Cmd2Style.COMPLETION_MENU_META - Style for "meta" information shown alongside a completion
    • Cmd2Style.COMPLETION_MENU_META_CURRENT- Style for meta info of current item
  • Updated set command to consolidate its confirmation output into a single, colorized line. The confirmation now uses pfeedback(), allowing it to be silenced when the quiet settable is enabled.
  • alias and macro subcommands for create and delete now output their non-essential success case output using pfeedback
• Experimental features
  • New @with_annotated decorator, a type-hint-driven alternative to @with_argparse that builds the parser automatically from a command's signature (positional/option inference, enum/literal/path/collection handling, subcommands, groups, mutex). See the annotated_example.py example for demonstration of usage.
    • This feature allows declaring cmd2 command parameters using type hints using syntax essentially identical to that used by Typer
    • You use declarative syntax to define the arguments a command takes and the @with_annotated decorator builds an argparse parser for you

What's Changed

• feat: Experimental annotated argparse by @KelvinChung2000 in #1666
• Refactor and standardize argparse-related naming and metadata by @kmvanbrunt in #1670

• Breaking Changes
  • Renamed set_default_argument_parser_type() to set_default_argument_parser().
  • Renamed set_default_ap_completer_type() to set_default_argparse_completer().
  • Renamed cmd2_subcmd_handler to cmd2_subcommand_func in the argparse.Namespace for clarity.

New Contributors

• @KelvinChung2000 made their first contribution in #1666

Full Changelog: 4.0.0-rc1...4.0.0-rc2

What's Changed

• Add styles to theme for prompt-toolkit completion styles by @tleonhardt in #1653
• Removed feedback_to_output settable and made pfeedback() consistent by @bambu in #1647
• Refactor internal naming to _cmd_app and remove legacy parseline() method by @kmvanbrunt in #1659
• Added LRU caching of converted prompt-toolkit styles and colors. by @kmvanbrunt in #1657
• Added monkey patch to handle argparse deepcopy issue introduced in Python 3.15.0b1. by @kmvanbrunt in #1662
• Added prompt-toolkit version of the app theme which remains synchronized when theme is updated. by @kmvanbrunt in #1661
• Added ability to incrementally update the theme. by @kmvanbrunt in #1664
• Expanded subcommand management API. by @kmvanbrunt in #1663
• Made traceback_width a Settable.
• Drop support for Python 3.10 by @tleonhardt in #1665

Full Changelog: 4.0.0-b6...4.0.0-rc1

What's Changed

• Quick fixes 4.x by @kmvanbrunt in #1651
• Remove always_show_hint settable by @tleonhardt in #1652
• Overhauled redirection and output capturing by @kmvanbrunt in #1654
• Fixed default value for traceback_show_locals. by @kmvanbrunt in #1655

• Breaking Changes
  • Removed always_show_hint settable as it provided a poor user experience with
    prompt-toolkit
  • cmd2 redirection only captures output directed to self.stdout (e.g., via
    self.poutput()). Standard print() calls write directly to sys.stdout and are not
    captured. However, print() calls within pyscripts and the interactive Python shell are
    treated as command output and sent to self.stdout, allowing them to be captured.
  • Verbose help table descriptions are no longer generated from help function output. The system
    now relies exclusively on command function docstrings.
• Enhancements
  • Added HelpFormatterRenderable protocol and HelpContent type alias to support context-aware
    help content in argparse.
  • The print() function available in a pyscript writes to self.stdout and respects the
    allow_style setting. It also supports printing Rich objects.
  • Added Cmd2ArgumentParser.output_to() context manager to temporarily set the output stream
    during argparse operations. This is helpful for directing output for functions like
    parse_args(), which default to sys.stdout and lack a file argument.
• Bug Fixes
  • Fixed ArgparseCompleter.print_help() not passing file stream to recursive call.
  • Fixed issue where constants.REDIRECTION_TOKENS was being mutated.

Full Changelog: 4.0.0-b5...4.0.0-b6

• Bug Fixes
  • Fixed ArgparseCompleter.print_help() not passing file stream to recursive call.
  • Fixed issue where constants.REDIRECTION_TOKENS was being mutated.

• Bug Fixes
  • Fixed issue where Rich stripped colors from text in test environments where TERM=dumb.

• Enhancements

  • Moved cmd2-specific printing logic from Cmd.print_to() into Cmd2BaseConsole.print() and Cmd2BaseConsole.log(). This removes need to pass a console object to Cmd.print_to().
  • Addressed a bug in rich.console.Console where complex renderables (like Table and Rule) may not receive formatting settings passed to console.print() and console.log().

• Breaking Changes

  • Renamed the destination parameter of Cmd.print_to() back to file since you can no longer pass in a console.

• Enhancements

  • Added ability to pass a console object to Cmd.print_to(). This provides support for things like wrapping a print_to() call in a console.status() or console.capture() context manager.

• Breaking Changes

  • Renamed the file parameter of Cmd.print_to() to destination to support file-like objects and console objects.
  • Cmd2BaseConsole(file) argument is now a keyword-only argument to be consistent with the rich.console.Console class.

• Bug Fixes
  • Updated rich_utils.ANSI_STYLE_SEQUENCE_RE to only match ANSI SGR (Select Graphic Rendition) sequences for text styling. It previously also matched DEC Private Mode sequences.

• Bug Fixes
  • The async_alert and async_prompt_update methods of cmd2.Cmd now respect the current value of the allow_style settable
    • If allow_style is NEVER, all style-related ANSI escape codes will be stripped to ensure plain text output

• Bug Fixes

  • Fixed incompatibilities with Python 3.14.3.

• Potentially Breaking Changes

  • To avoid future incompatibilities with argparse, we removed most of our overridden help functions. This should not break an application, but it could affect unit tests which parse help text.

• Bug Fixes
  • Fixed issue where delimiter_complete() could cause more matches than display matches
  • Fixed issue where CommandSet registration did not respect disabled categories

• Bug Fixes
  • Fixed missing typing-extensions dependency for Python 3.10

• Bug Fixes
  • Fixed bug where rich-argparse was not coloring cmd2's custom nargs formatting

• Potentially Breaking Changes
  • cmd2 no longer has a dependency on cmd and cmd2.Cmd no longer inherits from cmd.Cmd
    • We don't think this should impact users, but there is theoretically a possibility
    • This opens the door for more impactful changes in the next major release

Summary

cmd2 now has a dependency on rich for rich text and pretty formatting in the terminal. Previously, cmd2 had a large amount of custom code for this purpose that predated the existence of rich. This opens the door to even more beautiful cmd2 applications. To get the most out of the new capabilities, we encourage you to spend a little bit of time reading the rich documentation.

Details

• Breaking Changes

  • Refactored and modernized styling and utility modules:
    • Removed the legacy table_creator.py module in favor of rich tables (see the rich_tables.py example for more info)
    • Moved all string-related functions from utils.py to a new string_utils.py module
      • Removed redundant string from some of the names so quote_string is now just quote and quote_string_if_needed is now quote_if_needed
    • Consolidated all string styling functions from ansi.py into string_utils.py
    • Replaced all text style enums from ansi.py with modern rich styles
    • Renamed ansi.py to terminal_utils.py to better reflect its purpose
  • Dropped support for Python 3.9. cmd2 now requires Python 3.10 or later
  • Replaced Settable.get_value() and Settable.set_value() methods with a more Pythonic value property
  • Removed redundant setting of a parser's prog value in the with_argparser() decorator, as this is now handled centrally in Cmd._build_parser()
  • The auto_load_commands argument to cmd2.Cmd.__init__ now defaults to False
  • argparse_custom module breaking changes:
    • descriptive_header: str replaced with descriptive_headers: Sequence[str | rich.Column]
      • Applies to parameter name when adding an argument to a parser as well as set_descriptive_headers and get_descriptive_headers
    • CompletionItem.description: str changed to CompletionItem.descriptive_data: Sequence[str | rich.Column]
  • decorators module breaking changes:
    • _set_parser_prog renamed to set_parser_prog (without the leading underscore) and moved to argparse_custom module
  • Renamed history --output_file to --output-file to follow common command-line practices
  • cmd2.Cmd.ppretty method removed - rich has more and better options for pretty printing, see the pretty_print.py example for a demonstration of pretty-printing JSON data

• Enhancements

  • Enhanced all print methods (poutput(), perror(), ppaged(), etc.) to natively render rich objects, enabling beautiful and complex output
  • Simplified the process for setting a custom parser for cmd2's built-in commands. See the custom_parser.py example for an updated guide
  • Introduced Cmd.macro_arg_complete() for tab-completing macro arguments, with default path completion that can be easily customized
  • Added colors.py and styles.py to provide easy access to rich color names and manage cmd2-specific style definitions using StrEnum (see the colors.py example for a demonstration of all colors available to your cmd2 application)
  • Added ability to create a custom theme for a cmd2 application using rich_utils.set_theme (see the rich_theme.py example for more info)
  • Consolidated multiple redundant examples into a few more comprehensive ones, see:
    • argparse_example.py
    • command_sets.py
    • getting_started.py
  • Optimized performance of terminal fixup during command finalization by replacing stty sane with termios.tcsetattr

• Bug Fixes

  • Fixed a redirection bug where cmd2 could unintentionally overwrite an application's sys.stdout

• Migration Aids - these will help you iteratively migrate to cmd2 3.x in stages

  • Published new cmd2-ansi module which is a backport of the cmd2.ansi module present in cmd2 2.7.0
  • Published new cmd2-table module which is a backport of the cmd2.table_creator module present in cmd2 2.7.0

• Enhancements
  • Integrated rich-argparse with cmd2's default argparse help formatter (Cmd2HelpFormatter).

• Enhancements

  • Added explicit support for free-threaded versions of Python, starting with version 3.14

• Bug Fixes

  • Restored code to set a parser's prog value in the with_argparser decorator. This is to preserve backward compatibility in the cmd2 2.0 family. This functionality will be removed in cmd2 3.0.0.

• Bug Fixes
  • Fixed bug that prevented cmd2 from working with from __future__ import annotations

• Breaking Change
  • cmd2 2.6 supports Python 3.9+ (removed support for Python 3.8)
• Enhancements
  • Added support for Python 3.14
  • Added new Cmd.ppretty() method for pretty printing arbitrary Python data structures
  • Clarified help text for -t/--transcript argument to the history command

• Bug Fixes
  • Fixed duplicated parameter tables in API documentation.

• Bug Fixes
  • Fixed docstring style for MkDocs API documentation so parameters are displayed properly.

• Bug Fixes
  • Fixed 'index out of range' error when passing no arguments to an argparse-based command function.

• Bug Fixes
  • Rolled back undocumented changes to printing functions introduced in 2.5.0.

• Bug Fixes
  • Fixed issue where argument parsers for overridden commands were not being created.
  • Fixed issue where Cmd.ppaged() was not writing to the passed in destination.

• Bug Fixes
  • Fixed type hint for with_default_category decorator which caused type checkers to mistype a subclass of CommandSet as a plain CommandSet.

• Bug Fixes
  • Fixed type hints for passing a class method to with_argparser and as_subcommand_to.
  • Fixed issue where set command was not always printing a settable's current value.

• Bug Fixes
  • Fixed ZeroDivisionError in async_alert() when shutil.get_terminal_size().columns is 0.

• Enhancements
  • Changed CommandSet._cmd to a read-only property which never returns None because it is meant to be called after the CommandSet is registered. This addresses type checker errors that occurred if CommandSet._cmd wasn't cast or checked if None before use.

• Bug Fixes
  • Fixed default pytest execution when not using cmd2's custom invoke command via inv pytest

• Bug Fixes
  • Fixed readline bug when using ipy command with gnureadline and Python 3.13

• Breaking Change
  • cmd2 2.5 supports Python 3.8+ (removed support for Python 3.6 and 3.7)
• Bug Fixes
  • Fixed issue where persistent history file was not saved upon SIGHUP and SIGTERM signals.
  • Multiline commands are no longer fragmented in up-arrow history.
  • Fixed bug where async_alert() overwrites readline's incremental and non-incremental search prompts.
    • This fix introduces behavior where an updated prompt won't display after an aborted search until a user presses Enter. See async_printing.py example for how to handle this case using Cmd.need_prompt_refresh() and Cmd.async_refresh_prompt().
• Enhancements
  • Removed dependency on attrs and replaced with dataclasses
  • add allow_clipboard initialization parameter and attribute to disable ability to add output to the operating system clipboard
  • Updated unit tests to be Python 3.13 compliant.
  • Fall back to bz2 compression of history file when lzma is not installed.
  • Added settable called scripts_add_to_history which determines whether scripts and pyscripts add commands to history.
• Deletions (potentially breaking changes)
  • Removed apply_style from Cmd.pwarning().

• Bug Fixes
  • Fixed ValueError caused when passing Cmd.columnize() strings wider than display_width.
• Enhancements
  • Renamed utils.str_to_bool() -> utils.to_bool().
  • Enhanced utils.to_bool() so that it accepts and converts bool, int, and float in addition to str.

• Enhancements
  • Updated argparse decorator to remove annotations when the docstring is used for a command's help text.
  • Updated unit test to be Python 3.11 compliant.

• Bug Fixes
  • Fixed value for ansi.Bg.YELLOW.
  • Fixed unit tests for ansi.allow_style.
• Enhancements
  • async_alert() raises a RuntimeError if called from the main thread.

• Bug Fixes
  • Fixed issue in ansi.async_alert_str() which would raise IndexError if prompt was blank.
  • Fixed issue where tab completion was quoting argparse flags in some cases.
• Enhancements
  • Added broader exception handling when enabling clipboard functionality via pyperclip.
  • Added PassThroughException to __init__.py imports.
  • cmd2 now uses pyreadline3 when running any version of Python on Windows
  • Improved memory usage in certain use cases of tables (e.g. nested colored tables)
• Deletions (potentially breaking changes)
  • Deleted cmd2.fg and cmd2.bg which were deprecated in 2.3.0. Use cmd2.Fg and cmd2.Bg instead.

• Enhancements
  • Added clearer exception handling to BorderedTable and SimpleTable.

• Bug Fixes
  • Fixed issue where a ns_provider could be passed None instead of its correct cmd2.Cmd or CommandSet value.

• Bug Fixes
  • Fixed issue introduced in 2.3.0 with AlternatingTable, BorderedTable, and SimpleTable that caused header alignment settings to be overridden by data alignment settings.
• Enhancements
  • CompletionItems now saves the original object from which it creates a string.
  • Using CompletionItems as argparse choices is fully supported. cmd2 patched argparse to compare input to the original value instead of the CompletionItems instance.
  • ArgparseCompleter now does the following if a list of CompletionItems was created with numerical types:
    • Sorts completion hints numerically
    • Right-aligns the left-most column in completion hint table

• Bug Fixes
  • Fixed AttributeError in rl_get_prompt() when prompt is None.
  • Fixed bug where using choices on a Settable didn't verify that a valid choice had been entered.
  • Fixed bug introduced in cmd2 2.0.0 in which select() converts return values to strings. It should never have converted return values.
• Enhancements
  • Added settings to Column class which prevent a table from overriding existing styles in header and/or data text. This allows for things like nesting an AlternatingTable in another AlternatingTable.
  • AlternatingTable no longer automatically applies background color to borders. This was done to improve appearance since the background color extended beyond the borders of the table.
  • Added ability to colorize all aspects of AlternatingTable, BorderedTable, and SimpleTable.
  • Added support for 8-bit/256-colors with the cmd2.EightBitFg and cmd2.EightBitBg classes.
  • Added support for 24-bit/RGB colors with the cmd2.RgbFg and cmd2.RgbBg classes.
  • Removed dependency on colorama.
  • Changed type of ansi.allow_style from a string to an ansi.AllowStyle Enum class.
• Deprecations
  • Deprecated cmd2.fg. Use cmd2.Fg instead.
  • Deprecated cmd2.bg. Use cmd2.Bg instead.
• Breaking Changes
  • To support the color upgrade, all cmd2 colors now inherit from either ansi.FgColor or ansi.BgColor. Therefore, ansi.style() no longer accepts colors as strings.

• Bug Fixes
  • Fixed extra space appended to each alias by "alias list" command
• Enhancements
  • New function set_default_ap_completer_type() allows developer to extend and modify the behavior of ArgparseCompleter.
  • Added ArgumentParser.get_ap_completer_type() and ArgumentParser.set_ap_completer_type(). These methods allow developers to enable custom tab completion behavior for a given parser by using a custom ArgparseCompleter-based class.
  • Added ap_completer_type keyword arg to Cmd2ArgumentParser.__init__() which saves a call to set_ap_completer_type(). This keyword will also work with add_parser() when creating subcommands if the base command's parser is a Cmd2ArgumentParser.
  • New function register_argparse_argument_parameter() allows developers to specify custom parameters to be passed to the argparse parser's add_argument() method. These parameters will become accessible in the resulting argparse Action object when modifying ArgparseCompleter behavior.
  • Using SimpleTable in the output for the following commands to improve appearance.
    • help
    • set (command and tab completion of Settables)
    • alias tab completion
    • macro tab completion
  • Tab completion of CompletionItems now includes divider row comprised of Cmd.ruler character.
  • Removed --verbose flag from set command since descriptions always show now.
  • All cmd2 built-in commands now populate self.last_result.
  • Argparse tab completer will complete remaining flag names if there are no more positionals to complete.
  • Updated async_alert() to account for self.prompt not matching Readline's current prompt.
• Deletions (potentially breaking changes)
  • Deleted set_choices_provider() and set_completer() which were deprecated in 2.1.2
• Breaking Changes
  • Renamed set_default_argument_parser() to set_default_argument_parser_type()

• Enhancements
  • Added the following accessor methods for cmd2-specific attributes to the argparse.Action class
    • get_choices_callable()
    • set_choices_provider()
    • set_completer()
    • get_descriptive_header()
    • set_descriptive_header()
    • get_nargs_range()
    • set_nargs_range()
    • get_suppress_tab_hint()
    • set_suppress_tab_hint()
• Deprecations
  • Now that set_choices_provider() and set_completer() have been added as methods to the argparse.Action class, the standalone functions of the same name will be removed in version 2.2.0. To update to the new convention, do the following:
    • Change set_choices_provider(action, provider) to action.set_choices_provider(provider)
    • Change set_completer(action, completer) to action.set_completer(completer)

• Bug Fixes
  • Fixed handling of argparse's default options group name which was changed in Python 3.10
• Enhancements
  • Restored plugins and tests_isolated directories to tarball published to PyPI for cmd2 release