Removed terminal_utils.py.

Added documentation for completion.py.

Author: kmvanbrunt

.github/CODEOWNERS

@@ -31,7 +31,8 @@ cmd2/argparse_*.py         @kmvanbrunt @anselor
 cmd2/clipboard.py          @tleonhardt
 cmd2/cmd2.py               @tleonhardt @kmvanbrunt
 cmd2/colors.py             @tleonhardt @kmvanbrunt
-cmd2/command_definition.py @anselor
+cmd2/command_definition.py @anselor @kmvanbrunt
+cmd2/completion.py         @kmvanbrunt
 cmd2/constants.py          @tleonhardt @kmvanbrunt
 cmd2/decorators.py         @kmvanbrunt @anselor
 cmd2/exceptions.py         @kmvanbrunt @anselor
@@ -43,7 +44,6 @@ cmd2/py_bridge.py          @kmvanbrunt
 cmd2/rich_utils.py         @kmvanbrunt
 cmd2/string_utils.py       @kmvanbrunt
 cmd2/styles.py             @tleonhardt @kmvanbrunt
-cmd2/terminal_utils.py     @kmvanbrunt
 cmd2/transcript.py         @tleonhardt
 cmd2/utils.py              @tleonhardt @kmvanbrunt
 

CHANGELOG.md

@@ -48,6 +48,7 @@ shell, and the option for a persistent bottom bar that can display realtime stat
       `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.
 - Enhancements
     - New `cmd2.Cmd` parameters
         - **auto_suggest**: (boolean) if `True`, provide fish shell style auto-suggestions. These

cmd2/completion.py

@@ -1,4 +1,4 @@
-"""Provides classes and functions related to completion."""
+"""Provides classes and functions related to command-line completion."""
 
 import re
 import sys

docs/api/completion.md

@@ -0,0 +1,3 @@
+# cmd2.completion
+
+::: cmd2.completion

docs/api/index.md

@@ -18,6 +18,7 @@ incremented according to the [Semantic Version Specification](https://semver.org
 - [cmd2.colors](./colors.md) - StrEnum of all color names supported by the Rich library
 - [cmd2.command_definition](./command_definition.md) - supports the definition of commands in
   separate classes to be composed into cmd2.Cmd
+- [cmd2.completion](./completion.md) - classes and functions related to command-line completion
 - [cmd2.constants](./constants.md) - constants used in `cmd2`
 - [cmd2.decorators](./decorators.md) - decorators for `cmd2` commands
 - [cmd2.exceptions](./exceptions.md) - custom `cmd2` exceptions
@@ -30,6 +31,5 @@ incremented according to the [Semantic Version Specification](https://semver.org
 - [cmd2.rich_utils](./rich_utils.md) - common utilities to support Rich in cmd2 applications
 - [cmd2.string_utils](./string_utils.md) - string utility functions
 - [cmd2.styles](./styles.md) - cmd2-specific Rich styles and a StrEnum of their corresponding names
-- [cmd2.terminal_utils](./terminal_utils.md) - support for terminal control escape sequences
 - [cmd2.transcript](./transcript.md) - functions and classes for running and validating transcripts
 - [cmd2.utils](./utils.md) - various utility classes and functions

docs/api/terminal_utils.md

@@ -121,7 +121,6 @@ following sections:
 - [cmd2.colors][]
 - [cmd2.rich_utils][]
 - [cmd2.string_utils][]
-- [cmd2.terminal_utils][]
 
 The [color.py](https://github.com/python-cmd2/cmd2/blob/main/examples/color.py) example demonstrates
 all colors available to your `cmd2` application.

docs/features/generating_output.md

@@ -63,8 +63,7 @@ The major things users should be aware of when upgrading to 3.x are detailed in
 #### ansi
 
 The functionality within the `cmd2.ansi` module has either been removed or changed to be based on
-`rich` and moved to one of the new modules: [cmd2.string_utils][], [cmd2.styles][], or
-[cmd2.terminal_utils][].
+`rich` and moved to one of the new modules: [cmd2.string_utils][] or [cmd2.styles][].
 
 To ease the migration path from `cmd2` 2.x to 3.x, we have created the `cmd2-ansi` module which is a
 backport of the `cmd2.ansi` module present in `cmd2` 2.7.0 in a standalone fashion. Relevant links:
@@ -147,18 +146,6 @@ This includes functions for styling, aligning, and quoting/un-quoting text. See
 [getting_started.py](https://github.com/python-cmd2/cmd2/blob/main/examples/getting_started.py)
 example for a demonstration of how to use the common [cmd2.string_utils.stylize][] function.
 
-#### terminal_utils
-
-Support for terminal control escape sequences for things like setting the window title and
-asynchronous alerts has been moved from `cmd2.ansi` to the new [cmd2.terminal_utils][] module.
-
-This isn't really intended to be used by end users, but is used by higher-level functionality that
-is intended to be used by end users such as [cmd2.Cmd.set_window_title][] and
-[cmd2.Cmd.async_alert][].
-
-See [async_printing.py](https://github.com/python-cmd2/cmd2/blob/main/examples/async_printing.py)
-for an example of how to use this functionality in a `cmd2` application.
-
 ### Argparse HelpFormatter classes
 
 `cmd2` now has 5 different Argparse HelpFormatter classes, all of which are based on the

docs/upgrades.md

@@ -200,6 +200,7 @@ nav:
       - api/clipboard.md
       - api/colors.md
       - api/command_definition.md
+      - api/completion.md
       - api/constants.md
       - api/decorators.md
       - api/exceptions.md
@@ -211,7 +212,6 @@ nav:
       - api/rich_utils.md
       - api/string_utils.md
       - api/styles.md
-      - api/terminal_utils.md
       - api/transcript.md
       - api/utils.md
   - Version Upgrades: