cmd2 4.2.2__tar.gz → 4.2.3__tar.gz

{cmd2-4.2.2 → cmd2-4.2.3}/.pre-commit-config.yaml

@@ -7,6 +7,7 @@ repos:
       - id: check-merge-conflict
       - id: check-toml
       - id: check-yaml
+        exclude: mkdocs.yml
       - id: detect-private-key
       - id: end-of-file-fixer
       - id: fix-byte-order-marker
@@ -14,7 +15,7 @@ repos:
       - id: trailing-whitespace
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.16.3"
+    rev: "v0.16.5"
     hooks:
       - id: ruff-format
         args: [--config=ruff.toml]
@@ -30,7 +31,7 @@ repos:
           - prettier-plugin-toml@2.0.6
 
   - repo: https://github.com/crate-ci/typos
-    rev: v1.49.0
+    rev: v1.50.0
     hooks:
       - id: typos
         exclude: |

cmd2-4.2.3/AGENTS.md

@@ -0,0 +1,40 @@
+# Instructions for AI Agents
+
+This file provides context and instructions for the agentic AI tools when working with this Python
+project, which utilizes `uv` for environment and package management.
+
+## General Instructions
+
+- **Environment Management:** Prefer using `uv` for all Python environment management tasks.
+- **Package Installation:** Always use `uv` to install packages and ensure they are installed within
+  the project's virtual environment.
+- **Running Scripts/Commands:**
+    - To run Python scripts within the project's virtual environment, use `uv run ...`.
+    - To run programs directly from a PyPI package (installing it on the fly if necessary), use
+      `uvx ...` (shortcut for `uv tool run`).
+- **New Dependencies:** If a new dependency is required, please state the reason for its inclusion.
+- Do not commit spec, plan, or markdown documents to git without asking first.
+- Save plans to `~/.superpowers/plans/` instead of the project directory.
+
+## Python Code Standards
+
+To ensure Python code adheres to required standards, the following commands **must** be run before
+creating or modifying any `.py` files:
+
+```bash
+make check
+```
+
+To run unit tests use the following command:
+
+```bash
+make test
+```
+
+To make sure the documentation builds properly, use the following command:
+
+```bash
+make docs-test
+```
+
+All 3 of the above commands should be run prior to committing code.

{cmd2-4.2.2 → cmd2-4.2.3}/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 4.2.3 (September 2, 2026)
+
+- Bug Fixes
+    - Fix some links which were broken when published to PyPI
+- Enhancements
+    - Converted `BoundCommandFunc` and `UnboundCommandFunc` TypeAliases in `types.py` to Protocol
+      classes for stricter type checking on `cmd2` command method references
+
 ## 4.2.2 (August 25, 2026)
 
 - Documentation Improvements

{cmd2-4.2.2 → cmd2-4.2.3}/Makefile

@@ -20,6 +20,8 @@ check: ## Run code quality tools.
 	@uv run prek run -a
 	@echo "🚀 Static type checking: Running ty"
 	@uv run ty check
+	@echo "🚀 Static type checking: Running mypy"
+	@uv run mypy .
 
 .PHONY: format
 format: ## Perform ruff formatting
@@ -29,8 +31,17 @@ format: ## Perform ruff formatting
 lint: ## Perform ruff linting
 	@uv run ruff check --fix
 
+.PHONY: mypy
+mypy: ## Perform type checking using mypy
+	@uv run mypy .
+
+.PHONY: ty
+ty: ## Perform type checking using ty
+	@uv run ty check
+
 .PHONY: typecheck
-typecheck: ## Perform type checking
+typecheck: ## Perform type checking using both mypy and ty
+	@uv run mypy .
 	@uv run ty check
 
 .PHONY: test

{cmd2-4.2.2 → cmd2-4.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cmd2
-Version: 4.2.2
+Version: 4.2.3
 Summary: cmd2 - quickly build feature-rich and user-friendly interactive command line applications in Python
 Author: cmd2 Contributors
 License-Expression: MIT
@@ -27,7 +27,7 @@ Requires-Dist: rich>=15.0.0
 Requires-Dist: rich-argparse>=1.7.2
 Dynamic: license-file
 
-<h1 align="center">cmd2 : immersive interactive command line applications</h1>
+<h1 align="center">cmd2: build feature-rich command-line applications in Python</h1>
 
 [![Latest Version](https://img.shields.io/pypi/v/cmd2.svg?style=flat-square&label=latest%20stable%20version)](https://pypi.python.org/pypi/cmd2/)
 [![Tests](https://github.com/python-cmd2/cmd2/actions/workflows/tests.yml/badge.svg)](https://github.com/python-cmd2/cmd2/actions/workflows/tests.yml)
@@ -36,77 +36,145 @@ Dynamic: license-file
 <a href="https://discord.gg/RpVG6tk"><img src="https://img.shields.io/badge/chat-on%20discord-7289da.svg" alt="Chat"></a>
 
 <p align="center">
-  <a href="#the-developers-toolbox">Developer's Toolbox</a> •
-  <a href="#philosophy">Philosophy</a> •
+  <a href="#quick-start">Quick start</a> •
+  <a href="#why-cmd2">Why cmd2?</a> •
   <a href="#installation">Installation</a> •
   <a href="#documentation">Documentation</a> •
-  <a href="#tutorials">Tutorials</a> •
-  <a href="#hello-world">Hello World</a> •
-  <a href="#projects-using-cmd2">Projects using cmd2</a> •
+  <a href="#projects-using-cmd2">Projects using cmd2</a>
 </p>
 
-[![Screenshot](https://raw.githubusercontent.com/python-cmd2/cmd2/main/cmd2.png)](https://youtu.be/DDU_JH6cFsA)
+`cmd2` makes it quick to build powerful, polished command-line applications and REPLs in Python.
+Start with a subclass of the standard library's
+[`cmd.Cmd`](https://docs.python.org/3/library/cmd.html), then add commands while `cmd2` handles the
+details that make an application pleasant to build and use: argument parsing, generated help, tab
+completion, command history, scripting, output styling, and much more.
 
-cmd2 is a tool for building interactive command line applications in Python. Its goal is to make it
-quick and easy for developers to build feature-rich and user-friendly interactive command line
-applications. It provides a simple API which is an extension of Python's built-in
-[cmd](https://docs.python.org/3/library/cmd.html) module. cmd2 provides a wealth of features on top
-of cmd to make your life easier and eliminates much of the boilerplate code which would be necessary
-when using cmd.
+You can use `cmd2` for a small internal tool and grow the same application into an extensible,
+scriptable interface without replacing the framework or writing the usual CLI boilerplate.
 
-> :warning: **If you are upgrading from an older version of `cmd2`, both `3.x` and `4.x` have some
-> significant backwards incompatibilities from previous versions. Please see the
-> [CHANGELOG](./CHANGELOG.md) for info on what has changed and the
-> [Migration Guide](https://cmd2.readthedocs.io/en/latest/upgrades/) for tips on upgrading from an
-> older version of `cmd2` to `4.x`**
+## Quick start
 
-## The developers toolbox
+Install `cmd2`:
 
-![system schema](https://raw.githubusercontent.com/python-cmd2/cmd2/main/.github/images/graph.drawio.png)
+```bash
+pip install cmd2
+```
+
+Then create `app.py`:
+
+```python
+from typing import Annotated
+
+import cmd2
+from cmd2.annotated import Argument, Option
 
-When creating solutions developers have no shortage of tools to create rich and smart user
-interfaces. System administrators have long been duct taping together brittle workflows based on a
-menagerie of simple command line tools created by strangers on github and the guy down the hall.
-Unfortunately, when CLIs become significantly complex the ease of command discoverability tends to
-fade quickly. On the other hand, Web and traditional desktop GUIs are first in class when it comes
-to easily discovering functionality. The price we pay for beautifully colored displays is complexity
-required to aggregate disparate applications into larger systems. `cmd2` fills the niche between
-high [ease of command discovery](https://clig.dev/#ease-of-discovery) applications and smart
-workflow automation systems.
 
-The `cmd2` framework provides a great mixture of both worlds. Application designers can easily
-create complex applications and rely on the cmd2 library to offer effortless user facing help and
-extensive tab completion. When users become comfortable with functionality, cmd2 turns into a
-feature rich library enabling a smooth transition to full automation. If designed with enough
-forethought, a well implemented cmd2 application can serve as a boutique workflow tool. `cmd2` pulls
-off this flexibility based on two pillars of philosophy:
+class App(cmd2.Cmd):
+    """A small interactive application."""
 
-- Tab Completion
-- Automation Transition
+    @cmd2.with_annotated
+    def do_greet(
+        self,
+        name: Annotated[str, Argument(help_text="person to greet")],
+        count: Annotated[int, Option(help_text="number of greetings")] = 1,
+    ) -> None:
+        """Greet a person."""
+        for _ in range(count):
+            self.poutput(f"Hello, {name}!")
 
-## Philosophy
 
-<a href="https://imgflip.com/i/63h03x"><img src="https://i.imgflip.com/63h03x.jpg" title="made at imgflip.com" width="70%" height="%70"/></a>
+if __name__ == "__main__":
+    App().cmdloop()
+```
 
-Deep extensive tab completion and help text generation based on the argparse library create the
-first pillar of 'ease of command discovery'. The following is a list of features in this category.
+`cmd2` supports [Typer](https://typer.tiangolo.com/)-style syntax for specifying command arguments
+with type annotations. In this example, `@cmd2.with_annotated` turns `name` and `count` into a
+positional argument and an option.
 
-- Great tab completion of commands, subcommands, file system paths, and shell commands.
-- Custom tab completion for user designed commands via simple function overloading.
-- Tab completion from `persistent_history_file` sources added with very little friction.
-- Automatic tab completion of `argparse` flags and optional arguments.
-- Path completion easily enabled.
-- When all else fails, custom tab completion based on `choices_provider` can fill any gaps.
+Run it with `python app.py`. Your new `greet` command already has input validation, generated help,
+and tab completion for its options. The application also includes discoverable help, command
+history, aliases, macros, scripting, shell integration, and other built-in commands.
 
-<a href="https://imgflip.com/i/66t0y0"><img src="https://i.imgflip.com/66t0y0.jpg" title="made at imgflip.com" width="70%" height="70%"/></a>
+```console
+(Cmd) help greet
+Usage: greet [-h] [--count COUNT] name
 
-cmd2 creates the second pillar of 'ease of transition to automation' through alias/macro creation,
-command line argument parsing and execution of cmd2 scripting.
+(Cmd) greet --count 2 Ada
+Hello, Ada!
+Hello, Ada!
+```
 
-- Flexible alias and macro creation for quick abstraction of commands.
-- Text file scripting of your application with `run_script` (`@`) and `_relative_run_script` (`@@`)
-- Powerful and flexible built-in Python scripting of your application using the `run_pyscript`
-  command
+[![Animated demonstration of the cmd2 quick-start application](https://raw.githubusercontent.com/python-cmd2/cmd2/main/docs/assets/cmd2-readme-demo.gif)](https://raw.githubusercontent.com/python-cmd2/cmd2/main/docs/assets/cmd2-readme-demo.gif)
+
+See the [getting started tutorial](https://cmd2.readthedocs.io/en/latest/examples/getting_started/)
+to build a more complete application.
+
+## Why cmd2?
+
+### Build more with less code
+
+- Define commands as Python methods and use familiar
+  [`argparse`](https://cmd2.readthedocs.io/en/latest/features/argument_processing/) parsers for
+  arguments and subcommands. A single parser definition drives validation, help, and completion.
+- Render Rich tables and other styled objects, with consistent helpers for
+  [normal output, errors, warnings, and paging](https://cmd2.readthedocs.io/en/latest/features/generating_output/).
+- Organize large applications into independently testable and dynamically loadable
+  [CommandSets](https://cmd2.readthedocs.io/en/latest/features/modular_commands/), and customize the
+  command lifecycle with [hooks](https://cmd2.readthedocs.io/en/latest/features/hooks/).
+- Integrate existing Python code, shell tools, or asynchronous work instead of restructuring your
+  application around the framework.
+- Run on Windows, macOS, and Linux with a pure-Python package and a small dependency footprint.
+
+### Give users a capable interface from day one
+
+- **Tab completion:** provide context-aware completion for commands, subcommands, options, choices,
+  file paths, and custom data sources, with descriptive hints for completion candidates. Learn more
+  about [completion](https://cmd2.readthedocs.io/en/latest/features/completion/).
+- **History:** search, edit, rerun, save, and optionally persist previously entered commands. Users
+  also get familiar navigation and reverse search such as <kbd>Ctrl</kbd>+<kbd>R</kbd>. Learn more
+  about [history](https://cmd2.readthedocs.io/en/latest/features/history/).
+- **Unicode:** accept Unicode in commands, arguments, file names, and output, and run UTF-8 command
+  scripts for applications used in any language. Learn more about
+  [command scripts](https://cmd2.readthedocs.io/en/latest/features/scripting/#command-scripts).
+- **Shell shortcuts and hotkeys:** use familiar Readline-style keyboard shortcuts for navigating and
+  editing the command line, including Emacs-style bindings provided by `prompt-toolkit`. Learn more
+  about [keyboard shortcuts](https://cmd2.readthedocs.io/en/latest/features/history/#for-users).
+- **Help:** generate discoverable, categorized help for commands, subcommands, and arguments
+  directly from their argument parsers. Learn more about
+  [help](https://cmd2.readthedocs.io/en/latest/features/help/).
+- **Rich UI/UX:** offer syntax highlighting, Fish-style history suggestions, multiline input,
+  configurable prompts, completion menus, themes, and an optional bottom toolbar. Learn more about
+  [prompts and toolbars](https://cmd2.readthedocs.io/en/latest/features/prompt/) and
+  [themes](https://cmd2.readthedocs.io/en/latest/features/theme/).
+
+### Grow from exploration to automation
+
+- **Shell scripting:** automate the same commands users run interactively by passing them as command
+  arguments or standard input from shell scripts. Learn more about
+  [automating cmd2 applications](https://cmd2.readthedocs.io/en/latest/features/os/#automating-cmd2-apps-from-other-cliclu-tools).
+- **Python scripting:** run Python scripts inside the application for loops, branching, complex
+  control flow, and integration with the application's commands and data. Learn more about
+  [Python scripts](https://cmd2.readthedocs.io/en/latest/features/scripting/#python-scripts).
+- **Run shell commands:** execute operating-system commands without leaving the application, using
+  the built-in `shell` command or its `!` shortcut. Learn more about
+  [OS integration](https://cmd2.readthedocs.io/en/latest/features/os/#executing-os-commands-from-within-cmd2).
+- **Redirect output:** send command output to files or the clipboard, or pipe it through one or more
+  shell commands. Learn more about
+  [output redirection and pipes](https://cmd2.readthedocs.io/en/latest/features/redirection/).
+- **Aliases, macros, and shortcuts:** let users customize names, parameterized commands, and terse
+  shortcuts for repetitive workflows without changing the application. Learn more about
+  [aliases, macros, and shortcuts](https://cmd2.readthedocs.io/en/latest/features/shortcuts_aliases_macros/).
+- **Startup scripts:** initialize an application consistently by running saved commands every time
+  it starts. Learn more about
+  [startup commands and scripts](https://cmd2.readthedocs.io/en/latest/features/startup_commands/).
+- **Embedded Python and IPython shells:** drop into an interactive Python or IPython session for
+  experimentation, debugging, object introspection, and access to application state. Learn more
+  about
+  [embedded Python shells](https://cmd2.readthedocs.io/en/latest/features/embedded_python_shells/).
+- **Color, style, and tables:** produce readable output with Rich colors and styles, custom themes,
+  paging, and flexible table layouts. Learn more about
+  [generating output](https://cmd2.readthedocs.io/en/latest/features/generating_output/) and
+  [creating tables](https://cmd2.readthedocs.io/en/latest/features/table_creation/).
 
 ## Installation
 
@@ -120,17 +188,21 @@ cmd2 works with Python 3.11+ on Windows, macOS, and Linux. It is pure Python cod
 dependencies. It works with both conventional CPython and free-threaded variants.
 
 For information on other installation options, see
-[Installation Instructions](https://cmd2.readthedocs.io/en/latest/overview/installation.html) in the
+[Installation Instructions](https://cmd2.readthedocs.io/en/latest/overview/installation/) in the
 cmd2 documentation.
 
-## Documentation
-
-The latest documentation for cmd2 can be read online here: https://cmd2.readthedocs.io/en/latest/
+<!-- prettier-ignore -->
+> [!IMPORTANT]
+> Upgrading from an older release? Versions 3.x and 4.x include significant
+> backwards-incompatible changes. Review the [changelog](https://github.com/python-cmd2/cmd2/blob/main/CHANGELOG.md)
+> and [migration guide](https://cmd2.readthedocs.io/en/latest/upgrades/) before upgrading.
 
-It is available in HTML, PDF, and ePub formats.
+## Documentation
 
-The best way to learn the cmd2 api is to delve into the example applications located in source under
-examples.
+Read the [latest documentation](https://cmd2.readthedocs.io/en/latest/) online or download it in
+HTML, PDF, and ePub formats. The
+[`examples`](https://github.com/python-cmd2/cmd2/tree/main/examples) directory contains focused,
+runnable demonstrations of individual features.
 
 ## Tutorials
 
@@ -145,29 +217,6 @@ examples.
     - Advanced cookiecutter template with external plugin support :
       https://github.com/jayrod/cookiecutter-python-cmd2-ext-plug
 
-## Hello World
-
-```python
-#!/usr/bin/env python
-"""A simple cmd2 application."""
-import cmd2
-
-
-class FirstApp(cmd2.Cmd):
-    """A simple cmd2 application."""
-
-    def do_hello_world(self, _: cmd2.Statement):
-        self.poutput('Hello World')
-
-
-if __name__ == '__main__':
-    import sys
-
-    c = FirstApp()
-    sys.exit(c.cmdloop())
-
-```
-
 ## Found a bug?
 
 If you think you've found a bug, please first read through the open