|
| 1 | +# cmd2 Major Versions Upgrades |
| 2 | + |
| 3 | +## Upgrading to cmd2 3.x from 2.x |
| 4 | + |
| 5 | +For details about all of the changes in the 3.0.0 release, please refer to |
| 6 | +[CHANGELOG.md](https://github.com/python-cmd2/cmd2/blob/main/CHANGELOG.md). |
| 7 | + |
| 8 | +The biggest change from 2.x to 3.x is that `cmd2` now has a dependency on |
| 9 | +[rich](https://github.com/Textualize/rich). Accordingly, `cmd2` now relies on `rich` for beautiful |
| 10 | +text styling and formatting within the terminal. As such, a good chunk of custom code has been |
| 11 | +removed from `cmd2` and other things have either moved or altered to be based on `rich`. |
| 12 | + |
| 13 | +The major things users should be aware of when upgrading to 3.x are detailed in subsections below. |
| 14 | + |
| 15 | +### Deleted Modules |
| 16 | + |
| 17 | +#### ansi |
| 18 | + |
| 19 | +The functionality within the `cmd2.ansi` module has either been removed or changed to be based on |
| 20 | +`rich` and moved to one of the new modules: [cmd2.string_utils][], [cmd2.styles][], or |
| 21 | +[cmd2.terminal_utils][]. |
| 22 | + |
| 23 | +#### table_creator |
| 24 | + |
| 25 | +The `cmd2.table_creator` module no longer exists. Please see rich's documentation on |
| 26 | +[Tables](https://rich.readthedocs.io/en/latest/tables.html) for more information. The |
| 27 | +[rich_tables.py](https://github.com/python-cmd2/cmd2/blob/main/examples/rich_tables.py) example |
| 28 | +demonstrates how to use `rich` tables in a `cmd2` application. |
| 29 | + |
| 30 | +`rich` tables offer a degree of power and flexibility that are superior to what `cmd2` previously |
| 31 | +offered. We apologize for this backwards incompatibility, but the APIs were fundamentally different |
| 32 | +and we could not figure out a way to create a backwards-compatibility wrapper. |
| 33 | + |
| 34 | +### Added modules |
| 35 | + |
| 36 | +#### colors |
| 37 | + |
| 38 | +The new [cmd2.colors][] module provides the convenient [cmd2.colors.Color][] `StrEnum` class for |
| 39 | +`rich` color names. This allows you to use tab-completable constants in your code instead of magic |
| 40 | +strings to represent the precise color you want. |
| 41 | + |
| 42 | +See the |
| 43 | +[getting_started.py](https://github.com/python-cmd2/cmd2/blob/main/examples/getting_started.py) for |
| 44 | +a basic example of using the `Color` class to choose colors for stylizing your output. |
| 45 | +Alternatively, see the [color.py](https://github.com/python-cmd2/cmd2/blob/main/examples/color.py) |
| 46 | +example for a visual demonstration of all supported colors. |
| 47 | + |
| 48 | +#### rich_utils |
| 49 | + |
| 50 | +The new [cmd2.rich_utils][] module provides common utility classes and functions for supporting the |
| 51 | +use of `rich` within `cmd2` applications. Most of what is here is not intended to be user-facing. |
| 52 | + |
| 53 | +The one thing many `cmd2` application developers will likely be interested in using is the |
| 54 | +[cmd2.rich_utils.set_theme][] function. See the |
| 55 | +[rich_theme.py](https://github.com/python-cmd2/cmd2/blob/main/examples/rich_theme.py) example for a |
| 56 | +demonstration for how to set a theme (color scheme) for your app. |
| 57 | + |
| 58 | +#### styles |
| 59 | + |
| 60 | +Default styles for how something like an error message should be displayed are now located in the |
| 61 | +new [cmd2.styles][] module and they are now based on `rich` styles. |
| 62 | + |
| 63 | +Previously `cmd2` default styles were in the `cmd2.ansi` module. |
| 64 | + |
| 65 | +See |
| 66 | +[argparse_completion.py](https://github.com/python-cmd2/cmd2/blob/main/examples/argparse_completion.py) |
| 67 | +for an example on how you can leverage these default styles in your `cmd2` application to maintain a |
| 68 | +consistent look in feel. |
| 69 | + |
| 70 | +#### string_utils |
| 71 | + |
| 72 | +Various string utility functions have been moved from the `cmd2.ansi` module to the new |
| 73 | +[cmd2.string_utils][] module. |
| 74 | + |
| 75 | +This includes functions for styling, aligning, and quoting/un-quoting text. See the |
| 76 | +[getting_started.py](https://github.com/python-cmd2/cmd2/blob/main/examples/getting_started.py) |
| 77 | +example for a demonstration of how to use the common [cmd2.string_utils.stylize][] function. |
| 78 | + |
| 79 | +#### terminal_utils |
| 80 | + |
| 81 | +Support for terminal control escape sequences for things like setting the window title and |
| 82 | +asynchronous alerts has been moved from `cmd2.ansi` to the new [cmd2.terminal_utils][] module. |
| 83 | + |
| 84 | +This isn't really intended to be used by end users, but is used by higher-level functionality that |
| 85 | +is intended to be used by end users such as [cmd2.Cmd.set_window_title][] and |
| 86 | +[cmd2.Cmd.async_alert][]. |
| 87 | + |
| 88 | +See [async_printing.py](https://github.com/python-cmd2/cmd2/blob/main/examples/async_printing.py) |
| 89 | +for an example of how to use this functionality in a `cmd2` application. |
| 90 | + |
| 91 | +### Argparse HelpFormatter classes |
| 92 | + |
| 93 | +`cmd2` now has 5 different Argparse HelpFormatter classes, all of which are based on the |
| 94 | +`RichHelpFormatter` class from [rich-argparse](https://github.com/hamdanal/rich-argparse). |
| 95 | + |
| 96 | +- [Cmd2HelpFormatter][cmd2.argparse_custom.Cmd2HelpFormatter] |
| 97 | +- [ArgumentDefaultsCmd2HelpFormatter][cmd2.argparse_custom.ArgumentDefaultsCmd2HelpFormatter] |
| 98 | +- [MetavarTypeCmd2HelpFormatter][cmd2.argparse_custom.MetavarTypeCmd2HelpFormatter] |
| 99 | +- [RawDescriptionCmd2HelpFormatter][cmd2.argparse_custom.RawDescriptionCmd2HelpFormatter] |
| 100 | +- [RawTextCmd2HelpFormatter][cmd2.argparse_custom.RawTextCmd2HelpFormatter] |
| 101 | + |
| 102 | +Previously the default `Cmd2HelpFormatter` class inherited from `argparse.RawTextHelpFormatter`, |
| 103 | +however it now inherits from `argparse.HelpFormatter`. If you want RawText behavior, then pass |
| 104 | +`formatter_class=RawTextCmd2HelpFormatter` to your parser. |
| 105 | + |
| 106 | +The benefit is that your `cmd2` applications now have more aesthetically pleasing help which |
| 107 | +includes color to make it quicker and easier to visually parse help text. This works for all |
| 108 | +supported versions of Python. |
0 commit comments