Merge branch '3.0.0' into rich_phase_1

Author: kmvanbrunt

.github/CONTRIBUTING.md

@@ -89,7 +89,7 @@ $ pip freeze | grep pyperclip
 
 If your versions are lower than the prerequisite versions, you should update.
 
-If you do not already have Python installed on your machine, we recommend using [uv](https://github.com/astral-sh/uv)  
+If you do not already have Python installed on your machine, we recommend using [uv](https://github.com/astral-sh/uv)
 for all of your Python needs because it is extremely fast, meets all Python installation and packaging needs, and works
 on all platforms (Windows, Mac, and Linux). You can install `uv` using instructions at the link above.
 
@@ -222,7 +222,13 @@ To create a virtual environment and install everything needed for `cmd2` develop
 from a GitHub checkout:
 
 ```sh
-uv venv
+make install
+```
+
+To install the recommended Git pre-commit hooks for auto-formatting locally, do the following:
+
+```sh
+uv run pre-commit run -a
 ```
 
 To create a new virtualenv, using a specific version of Python you have installed, use the

.github/workflows/doc.yml

@@ -12,7 +12,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest]
-        python-version: ["3.12"]
+        python-version: ["3.13"]
       fail-fast: false
     runs-on: ${{ matrix.os }}
     steps:
@@ -21,11 +21,11 @@ jobs:
           # Only a single commit is fetched by default, for the ref/SHA that triggered the workflow.
           # Set fetch-depth: 0 to fetch all history for all branches and tags.
           fetch-depth: 0 # Needed for setuptools_scm to work correctly
-      - name: Set up Python
-        uses: actions/setup-python@v5 # https://github.com/actions/setup-python
+      - name: Install uv and set the python version
+        uses: astral-sh/setup-uv@v5
         with:
           python-version: ${{ matrix.python-version }}
-      - name: Install python prerequisites
-        run: pip install -U --user pip setuptools setuptools-scm griffe_typingdoc mkdocs-include-markdown-plugin mkdocs-macros-plugin mkdocs-material mkdocstrings[python] . plugins/ext_test
+      - name: Install the project
+        run: uv sync --group docs
       - name: MkDocs documentation build
-        run: mkdocs build
+        run: uv run mkdocs build -s

.github/workflows/format.yml

@@ -16,5 +16,5 @@ jobs:
           # Only a single commit is fetched by default, for the ref/SHA that triggered the workflow.
           # Set fetch-depth: 0 to fetch all history for all branches and tags.
           fetch-depth: 0 # Needed for setuptools_scm to work correctly
-      - run: pip install --user ruff
+      - uses: astral-sh/ruff-action@v3
       - run: ruff format --check

.github/workflows/lint.yml

@@ -16,5 +16,5 @@ jobs:
           # Only a single commit is fetched by default, for the ref/SHA that triggered the workflow.
           # Set fetch-depth: 0 to fetch all history for all branches and tags.
           fetch-depth: 0 # Needed for setuptools_scm to work correctly
-      - run: pip install --user ruff
+      - uses: astral-sh/ruff-action@v3
       - run: ruff check --output-format=github .

.github/workflows/mypy.yml

@@ -12,12 +12,15 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4 # https://github.com/actions/checkout
-      - uses: actions/setup-python@v5 # https://github.com/actions/setup-python
         with:
-          python-version: 3.13
-          allow-prereleases: true
           # Only a single commit is fetched by default, for the ref/SHA that triggered the workflow.
           # Set fetch-depth: 0 to fetch all history for all branches and tags.
           fetch-depth: 0 # Needed for setuptools_scm to work correctly
-      - run: pip install -U --user pip mypy pyperclip rich rich-argparse wcwidth
-      - run: mypy .
+      - name: Install uv and set the python version
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: 3.13
+      - name: Install the project
+        run: uv sync --group validate
+      - name: Run mypy static type checker
+        run: uv run mypy .

.gitignore

@@ -54,4 +54,4 @@ uv.lock
 # Node/npm used for installing Prettier locally to override the outdated version that is bundled with the VSCode extension
 node_modules/
 package-lock.json
-package.json
+package.json

.pre-commit-config.yaml

@@ -0,0 +1,22 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: "v5.0.0"
+    hooks:
+      - id: check-case-conflict
+      - id: check-merge-conflict
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: "v0.9.2"
+    hooks:
+      - id: ruff-format
+        args: [--config=pyproject.toml]
+
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: "v3.1.0"
+    hooks:
+      - id: prettier
+        additional_dependencies:
+          - prettier@3.4.2
+          - prettier-plugin-toml@2.0.1

.prettierignore

@@ -1,2 +1,2 @@
 # Markdown documentation files with non-standards syntax for mkdocstrings that Prettier should not auto-format
-docs/features/initialization.md
+docs/features/initialization.md

.readthedocs.yaml

@@ -4,27 +4,23 @@
 # Required
 version: 2
 
-# Set the OS, Python version and other tools you might need
-build:
-  os: ubuntu-24.04
-  tools:
-    python: "3"
-
-# Build documentation in the "docs/" directory with MkDocs
-mkdocs:
-  configuration: mkdocs.yml
-
 # Optionally build your docs in additional formats such as PDF and ePub
 # formats:
 #   - pdf
 #   - epub
 formats: all
 
-# Optional but recommended, declare the Python requirements required to build your documentation
-# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
-python:
-  install:
-    - method: pip
-      path: .
-      extra_requirements:
-        - docs
+# Build documentation in the "docs/" directory with MkDocs
+mkdocs:
+  configuration: mkdocs.yml
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+  jobs:
+    install:
+      - pip install .
+      - pip install dependency-groups
+      - pip-install-dependency-groups docs

Makefile

@@ -0,0 +1,67 @@
+# Simple Makefile for use with a uv-based development environment
+.PHONY: install
+install: ## Install the virtual environment
+	@echo "🚀 Creating virtual environment"
+	@uv sync
+
+.PHONY: check
+check: ## Run code quality tools.
+	@echo "🚀 Checking lock file consistency with 'pyproject.toml'"
+	@uv lock --locked
+	@echo "🚀 Linting code: Running pre-commit"
+	@uv run pre-commit run -a
+	@echo "🚀 Static type checking: Running mypy"
+	@uv run mypy
+
+.PHONY: test
+test: ## Test the code with pytest.
+	@echo "🚀 Testing code: Running pytest"
+	@uv run python -m pytest --cov --cov-config=pyproject.toml --cov-report=xml tests
+	@uv run python -m pytest --cov --cov-config=pyproject.toml --cov-report=xml tests_isolated
+
+.PHONY: docs-test
+docs-test: ## Test if documentation can be built without warnings or errors
+	@uv run mkdocs build -s
+
+.PHONY: docs
+docs: ## Build and serve the documentation
+	@uv run mkdocs serve
+
+.PHONY: build
+build: clean-build ## Build wheel file
+	@echo "🚀 Creating wheel file"
+	@uvx --from build pyproject-build --installer uv
+
+.PHONY: clean-build
+clean-build: ## Clean build artifacts
+	@echo "🚀 Removing build artifacts"
+	@uv run python -c "import shutil; import os; shutil.rmtree('dist') if os.path.exists('dist') else None"
+
+.PHONY: tag
+tag: ## Add a Git tag and push it to origin with syntax: make tag TAG=tag_name
+	@echo "🚀 Creating git tag: ${TAG}"
+	@git tag -a ${TAG} -m ""
+	@echo "🚀 Pushing tag to origin: ${TAG}"
+	@git push origin ${TAG}
+
+.PHONY: validate-tag
+validate-tag: ## Check to make sure that a tag exists for the current HEAD and it looks like a valid version number
+	@echo "🚀 Validating version tag"
+	@uv run inv validatetag
+
+.PHONY: publish-test
+publish-test: validate-tag build ## Test publishing a release to PyPI.
+	@echo "🚀 Publishing: Dry run."
+	@uvx twine upload --repository testpypi dist/*
+
+.PHONY: publish
+publish: validate-tag build ## Publish a release to PyPI.
+	@echo "🚀 Publishing."
+	@uvx twine upload dist/*
+
+.PHONY: help
+help:
+	@uv run python -c "import re; \
+	[[print(f'\033[36m{m[0]:<20}\033[0m {m[1]}') for m in re.findall(r'^([a-zA-Z_-]+):.*?## (.*)$$', open(makefile).read(), re.M)] for makefile in ('$(MAKEFILE_LIST)').strip().split()]"
+
+.DEFAULT_GOAL := help

Pipfile

@@ -29,7 +29,7 @@ setuptools-scm = "*"
 mkdocs-include-markdown-plugin = "*"
 mkdocs-macros-plugin = "*"
 mkdocs-material = "*"
-mkdocstrings[python] = "*"
+mkdocstrings= {version = "*", extras = ["python"]}
 twine = ">=1.11"
 
 [pipenv]

examples/scripts/nested.txt

@@ -1,3 +1,2 @@
 !echo "Doing a relative run script"
 _relative_run_script script.txt
-

examples/tmux_launch.sh

@@ -33,4 +33,4 @@ if [ $# -eq 1 ]
 fi
 
 tmux new-session -s "tmux window demo" -n "$FIRST_COMMAND" "$FIRST_COMMAND ;read" \; \
-  new-window -n "$SECOND_COMMAND" "$SECOND_COMMAND ; read" \; previous-window
+  new-window -n "$SECOND_COMMAND" "$SECOND_COMMAND ; read" \; previous-window

examples/tmux_split.sh

@@ -31,4 +31,4 @@ fi
 
 tmux new-session -s "tmux split pane demo" "$FIRST_COMMAND ; read" \; \
   split-window "$SECOND_COMMAND ; read" \; \
-  select-layout even-vertical
+  select-layout even-vertical

pyproject.toml

@@ -1,5 +1,5 @@
 [build-system]
-requires = ["build", "setuptools>=64", "setuptools-scm>=8"]
+requires = ["build>=1.2.1", "setuptools>=64", "setuptools-scm>=8"]
 build-backend = "setuptools.build_meta"
 
 [project]
@@ -34,59 +34,72 @@ classifiers = [
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]
 dependencies = [
-    "gnureadline; platform_system == 'Darwin'",
-    "pyperclip",
-    "pyreadline3; platform_system == 'Windows'",
-    "rich-argparse",
-    "wcwidth",
+    "gnureadline>=8; platform_system == 'Darwin'",
+    "pyperclip>=1.8",
+    "pyreadline3>=3.4; platform_system == 'Windows'",
+    "rich-argparse>=1.4",
+    "wcwidth>=0.2.10",
 ]
 
-[project.optional-dependencies]
-build = ["build", "setuptools", "setuptools-scm"]
+[dependency-groups]
+build = ["build>=1.2.1", "setuptools>=64", "setuptools-scm>=8"]
 dev = [
-    "black",
-    "codecov",
-    "griffe-typingdoc",
-    "invoke",
-    "mkdocs-include-markdown-plugin",
-    "mkdocs-macros-plugin",
-    "mkdocs-material",
-    "mkdocstrings[python]",
-    "mypy",
-    "pytest",
-    "pytest-cov",
-    "pytest-mock",
-    "ruff",
-    "twine",
+    "black>=24",
+    "codecov>=2",
+    "griffe-typingdoc>=0.2",
+    "invoke>=2",
+    "mkdocs-include-markdown-plugin>=6",
+    "mkdocs-macros-plugin>=1",
+    "mkdocs-material>=8",
+    "mkdocstrings[python]>=0.26",
+    "mypy>=1.12",
+    "pre-commit>=2.20.0",
+    "pytest>=7",
+    "pytest-cov>=4",
+    "pytest-mock>=3.14",
+    "ruff>=0.9",
+    "twine>=6",
 ]
 docs = [
-    "black",
-    "griffe-typingdoc",
-    "mkdocs-include-markdown-plugin",
-    "mkdocs-macros-plugin",
-    "mkdocs-material",
-    "mkdocstrings[python]",
-    "setuptools",
-    "setuptools_scm",
+    "black>=24",
+    "griffe-typingdoc>=0.2",
+    "mkdocs-include-markdown-plugin>=6",
+    "mkdocs-macros-plugin>=1",
+    "mkdocs-material>=8",
+    "mkdocstrings[python]>=0.26",
+    "setuptools>=64",
+    "setuptools_scm>=8",
 ]
-test = ["codecov", "coverage", "pytest", "pytest-cov", "pytest-mock"]
-validate = ["mypy", "ruff", "types-setuptools"]
+plugins = ["cmd2-ext-test"]
+test = [
+    "codecov>=2",
+    "coverage>=7",
+    "pytest>=7",
+    "pytest-cov>=4",
+    "pytest-mock>=3.14",
+]
+validate = ["mypy>=1.12", "ruff>=0.9", "types-setuptools>=69"]
 
 [tool.mypy]
 disallow_incomplete_defs = true
 disallow_untyped_calls = true
 disallow_untyped_defs = true
 exclude = [
+    "^.git/",
+    "^.venv/",
     "^build/",          # .build directory
     "^docs/",           # docs directory
+    "^dist/",
     "^examples/",       # examples directory
     "^plugins/*",       # plugins directory
     "^noxfile\\.py$",   # nox config file
     "setup\\.py$",      # any files named setup.py
+    "^site/",
     "^tasks\\.py$",     # tasks.py invoke config file
     "^tests/",          # tests directory
     "^tests_isolated/", # tests_isolated directory
 ]
+files = ['.']
 show_column_numbers = true
 show_error_codes = true
 show_error_context = true
@@ -274,25 +287,7 @@ packages = ["cmd2"]
 [tool.setuptools_scm]
 
 [tool.uv]
-dev-dependencies = [
-    "black",
-    "build",
-    "cmd2-ext-test",
-    "codecov",
-    "griffe-typingdoc",
-    "invoke",
-    "mkdocs-include-markdown-plugin",
-    "mkdocs-macros-plugin",
-    "mkdocs-material",
-    "mkdocstrings[python]",
-    "mypy",
-    "pytest",
-    "pytest-cov",
-    "pytest-mock",
-    "ruff",
-    "ruff",
-    "twine",
-]
+default-groups = ["build", "dev", "plugins"]
 
 [tool.uv.sources]
 cmd2-ext-test = { path = "plugins/ext_test", editable = true }