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:
+          - [email protected]
+          - [email protected]

.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