Replace readline with prompt-toolkit in documentation and such

Author: tleonhardt

.github/CONTRIBUTING.md

@@ -61,15 +61,13 @@ Nearly all project configuration, including for dependencies and quality tools i
 
 See the `dependencies` list under the `[project]` heading in [pyproject.toml](../pyproject.toml).
 
-| Prerequisite                                               | Minimum Version | Purpose                                                |
-| ---------------------------------------------------------- | --------------- | ------------------------------------------------------ |
-| [python](https://www.python.org/downloads/)                | `3.10`          | Python programming language                            |
-| [pyperclip](https://github.com/asweigart/pyperclip)        | `1.8`           | Cross-platform clipboard functions                     |
-| [rich](https://github.com/Textualize/rich)                 | `14.1.0`        | Add rich text and beautiful formatting in the terminal |
-| [rich-argparse](https://github.com/hamdanal/rich-argparse) | `1.7.1`         | A rich-enabled help formatter for argparse             |
-
-> `macOS` and `Windows` each have an extra dependency to ensure they have a viable alternative to
-> [readline](https://tiswww.case.edu/php/chet/readline/rltop.html) available.
+| Prerequisite                                                              | Minimum Version | Purpose                                                |
+| ------------------------------------------------------------------------- | --------------- | ------------------------------------------------------ |
+| [prompt-toolkit](https://github.com/prompt-toolkit/python-prompt-toolkit) | `3.0.52`        | Replacement for GNU `readline` that is cross-platform  |
+| [python](https://www.python.org/downloads/)                               | `3.10`          | Python programming language                            |
+| [pyperclip](https://github.com/asweigart/pyperclip)                       | `1.8`           | Cross-platform clipboard functions                     |
+| [rich](https://github.com/Textualize/rich)                                | `14.1.0`        | Add rich text and beautiful formatting in the terminal |
+| [rich-argparse](https://github.com/hamdanal/rich-argparse)                | `1.7.1`         | A rich-enabled help formatter for argparse             |
 
 > Python 3.10 depends on [backports.strenum](https://github.com/clbarnes/backports.strenum) to use
 > the `enum.StrEnum` class introduced in Python 3.11.

cmd2/terminal_utils.py

@@ -96,7 +96,7 @@ def async_alert_str(*, terminal_columns: int, prompt: str, line: str, cursor_off
 
     :param terminal_columns: terminal width (number of columns)
     :param prompt: current onscreen prompt
-    :param line: current contents of the Readline line buffer
+    :param line: current contents of the prompt-toolkit line buffer
     :param cursor_offset: the offset of the current cursor position within line
     :param alert_msg: the message to display to the user
     :return: the correct string so that the alert message appears to the user to be printed above the current line.

docs/examples/getting_started.md

@@ -266,8 +266,10 @@ persist between invocations of your application, you'll need to do a little work
 
 Users can access command history using two methods:
 
-- The [readline](https://docs.python.org/3/library/readline.html) library which provides a Python
-  interface to the [GNU readline library](https://en.wikipedia.org/wiki/GNU_Readline)
+- The [prompt-toolkit](https://github.com/prompt-toolkit/python-prompt-toolkit) library which
+  provides a pure Python replacement for the
+  [GNU readline library](https://en.wikipedia.org/wiki/GNU_Readline) which is fully cross-platform
+  compatible
 - The `history` command which is built-in to `cmd2`
 
 From the prompt in a `cmd2`-based application, you can press `Control-p` to move to the previously

docs/features/completion.md

@@ -20,8 +20,8 @@ from `cmd2.Cmd`:
 complete_foo = cmd2.Cmd.path_complete
 ```
 
-This will effectively define the `complete_foo` readline completer method in your class and make it
-utilize the same path completion logic as the built-in commands.
+This will effectively define the `complete_foo` prompt-toolkit completer method in your class and
+make it utilize the same path completion logic as the built-in commands.
 
 The built-in logic allows for a few more advanced path completion capabilities, such as cases where
 you only want to match directories. Suppose you have a custom command `bar` implemented by the

docs/features/history.md

@@ -4,10 +4,10 @@
 
 The `cmd` module from the Python standard library includes `readline` history.
 
-[cmd2.Cmd][] offers the same `readline` capabilities, but also maintains its own data structures for
-the history of all commands entered by the user. When the class is initialized, it creates an
-instance of the [cmd2.history.History][] class (which is a subclass of `list`) as
-`cmd2.Cmd.history`.
+[cmd2.Cmd][] offers the same `readline` capabilitie via use of `prompt-toolkit`, but also maintains
+its own data structures for the history of all commands entered by the user. When the class is
+initialized, it creates an instance of the [cmd2.history.History][] class (which is a subclass of
+`list`) as `cmd2.Cmd.history`.
 
 Each time a command is executed (this gets complex, see
 [Command Processing Loop](./hooks.md#command-processing-loop) for exactly when) the parsed
@@ -20,9 +20,9 @@ this format instead of plain text to preserve the complete `cmd2.Statement` obje
 
 !!! note
 
-    `readline` saves everything you type, whether it is a valid command or not. `cmd2` only saves input to internal history if the command parses successfully and is a valid command. This design choice was intentional, because the contents of history can be saved to a file as a script, or can be re-run. Not saving invalid input reduces unintentional errors when doing so.
+    `prompt-toolkit` saves everything you type, whether it is a valid command or not. `cmd2` only saves input to internal history if the command parses successfully and is a valid command. This design choice was intentional, because the contents of history can be saved to a file as a script, or can be re-run. Not saving invalid input reduces unintentional errors when doing so.
 
-    However, this design choice causes an inconsistency between the `readline` history and the `cmd2` history when you enter an invalid command: it is saved to the `readline` history, but not to the `cmd2` history.
+    However, this design choice causes an inconsistency between the `prompt-toolkit` history and the `cmd2` history when you enter an invalid command: it is saved to the `prompt-toolkit` history, but not to the `cmd2` history.
 
 The `cmd2.Cmd.history` attribute, the `cmd2.history.History` class, and the
 [cmd2.history.HistoryItem][] class are all part of the public API for `cmd2.Cmd`. You could use
@@ -34,13 +34,13 @@ built-in `history` command works).
 You can use the :arrow_up: up and :arrow_down: down arrow keys to move through the history of
 previously entered commands.
 
-If the `readline` module is installed, you can press `Control-p` to move to the previously entered
-command, and `Control-n` to move to the next command. You can also search through the command
-history using `Control-r`.
+You can press `Control-p` to move to the previously entered command, and `Control-n` to move to the
+next command. You can also search through the command history using `Control-r`.
 
 You can refer to the [readline cheat sheet](http://readline.kablamo.org/emacs.html) or you can dig
-into the [GNU Readline User Manual](http://man7.org/linux/man-pages/man3/readline.3.html) for all
-the details, including instructions for customizing the key bindings.
+into the
+[Prompt Toolkit User Manual](https://python-prompt-toolkit.readthedocs.io/en/stable/pages/advanced_topics/key_bindings.html)
+for all the details, including instructions for customizing the key bindings.
 
 `cmd2` makes a third type of history access available with the `history` command. Each time the user
 enters a command, `cmd2` saves the input. The `history` command lets you do interesting things with

docs/features/prompt.md

@@ -31,8 +31,8 @@ for an example of dynamically updating the prompt.
 `cmd2` provides these functions to provide asynchronous feedback to the user without interfering
 with the command line. This means the feedback is provided to the user when they are still entering
 text at the prompt. To use this functionality, the application must be running in a terminal that
-supports [VT100](https://en.wikipedia.org/wiki/VT100) control characters and `readline`. Linux, Mac,
-and Windows 10 and greater all support these.
+supports [VT100](https://en.wikipedia.org/wiki/VT100) control characters. Linux, Mac, and Windows 10
+and greater all support these.
 
 - [cmd2.Cmd.async_alert][]
 - [cmd2.Cmd.async_update_prompt][]

docs/migrating/why.md

@@ -32,10 +32,10 @@ top-notch interactive command-line experience for their users.
 After switching from [cmd][cmd] to `cmd2`, your application will have the following new features and
 capabilities, without you having to do anything:
 
-- More robust [History](../features/history.md). Both [cmd][cmd] and `cmd2` have readline history,
-  but `cmd2` also has a robust `history` command which allows you to edit prior commands in a text
-  editor of your choosing, re-run multiple commands at a time, save prior commands as a script to be
-  executed later, and much more.
+- More robust [History](../features/history.md). Both [cmd][cmd] and `cmd2` have readline-style
+  history, but `cmd2` also has a robust `history` command which allows you to edit prior commands in
+  a text editor of your choosing, re-run multiple commands at a time, save prior commands as a
+  script to be executed later, and much more.
 - Users can redirect output to a file or pipe it to some other operating system command. You did
   remember to use `self.stdout` instead of `sys.stdout` in all of your print functions, right? If
   you did, then this will work out of the box. If you didn't, you'll have to go back and fix them.

docs/overview/installation.md

@@ -88,36 +88,3 @@ If you wish to permanently uninstall `cmd2`, this can also easily be done with
 [pip](https://pypi.org/project/pip):
 
     $ pip uninstall cmd2
-
-## readline Considerations
-
-`cmd2` heavily relies on Python's built-in
-[readline](https://docs.python.org/3/library/readline.html) module for its tab completion
-capabilities. Tab completion for `cmd2` applications is only tested against :simple-gnu:
-[GNU Readline](https://tiswww.case.edu/php/chet/readline/rltop.html) or libraries fully compatible
-with it. It does not work properly with the :simple-netbsd: NetBSD
-[Editline](http://thrysoee.dk/editline/) library (`libedit`) which is similar, but not identical to
-GNU Readline. `cmd2` will disable all tab-completion support if an incompatible version of
-`readline` is found.
-
-When installed using `pip`, `uv`, or similar Python packaging tool on either `macOS` or `Windows`,
-`cmd2` will automatically install a compatible version of readline.
-
-Most Linux operating systems come with a compatible version of readline. However, if you are using a
-tool like `uv` to install Python on your system and configure a virtual environment, `uv` installed
-versions of Python come with `libedit`. If you are using `cmd2` on Linux with a version of Python
-installed via `uv`, you will likely need to manually add the `gnureadline` Python module to your
-`uv` virtual environment.
-
-```sh
-uv pip install gnureadline
-```
-
-macOS comes with the [libedit](http://thrysoee.dk/editline/) library which is similar, but not
-identical, to GNU Readline. Tab completion for `cmd2` applications is only tested against GNU
-Readline. In this case you just need to install the `gnureadline` Python package which is statically
-linked against GNU Readline:
-
-```shell
-$ pip install -U gnureadline
-```

docs/overview/integrating.md

@@ -13,16 +13,3 @@ We recommend that you follow the advice given by the Python Packaging User Guide
 [install_requires](https://packaging.python.org/discussions/install-requires-vs-requirements/). By
 setting an upper bound on the allowed version, you can ensure that your project does not
 inadvertently get installed with an incompatible future version of `cmd2`.
-
-## OS Considerations
-
-If you would like to use [Tab Completion](../features/completion.md), then you need a compatible
-version of [readline](https://tiswww.case.edu/php/chet/readline/rltop.html) installed on your
-operating system (OS). `cmd2` forces a sane install of `readline` on both `Windows` and `macOS`, but
-does not do so on `Linux`. If for some reason, you have a version of Python on a Linux OS who's
-built-in `readline` module is based on the
-[Editline Library (libedit)](https://www.thrysoee.dk/editline/) instead of `readline`, you will need
-to manually add a dependency on `gnureadline`. Make sure to include the following dependency in your
-`pyproject.toml` or `setup.py`:
-
-    'gnureadline'

pyproject.toml

@@ -30,7 +30,7 @@ classifiers = [
 ]
 dependencies = [
     "backports.strenum; python_version == '3.10'",
-    "prompt-toolkit>=3.0.48",
+    "prompt-toolkit>=3.0.52",
     "pyperclip>=1.8.2",
     "rich>=14.1.0",
     "rich-argparse>=1.7.1",