Initial commit of cmd2-ansi code

tleonhardt · tleonhardt · commit a585cf07328c · 2025-09-26T00:33:38.000-04:00
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
diff --git a/.github/workflows/quality.yml b/.github/workflows/quality.yml
@@ -0,0 +1,33 @@
+# For documentation on GitHub Actions Workflows, see:
+# https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions
+name: Quality
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0 # Needed for setuptools_scm to work correctly
+
+      - uses: actions/cache@v4
+        with:
+          path: ~/.cache/pre-commit
+          key: pre-commit-${{ hashFiles('.pre-commit-config.yaml') }}
+      - name: Install uv and set the python version
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.13"
+      - name: Install the project
+        run: uv sync --group quality
+      - name: Run pre-commit
+        run: uv run pre-commit run -a --show-diff-on-failure
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -0,0 +1,39 @@
+# For documentation on GitHub Actions Workflows, see:
+# https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions
+name: Tests
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+  push:
+    branches: [main]
+
+jobs:
+  tests:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14", "3.14t"]
+      fail-fast: false
+
+    runs-on: ${{ matrix.os }}
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - name: Check out
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0 # Needed for setuptools_scm to work correctly
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          allow-prereleases: true
+      - name: Install the project
+        run: uv sync --all-extras --dev
+
+      - name: Run tests
+        run: uv run python -Xutf8 -m pytest tests
diff --git a/.github/workflows/typecheck.yml b/.github/workflows/typecheck.yml
@@ -0,0 +1,35 @@
+# For documentation on GitHub Actions Workflows, see:
+# https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions
+name: TypeCheck
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  type-check:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+      fail-fast: false
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - name: Check out
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0 # Needed for setuptools_scm to work correctly
+
+      - name: Install uv and set the python version
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Check typing
+        run: uv run mypy .
diff --git a/.gitignore b/.gitignore
@@ -98,7 +98,7 @@ ipython_config.py
 #   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
 #   This is especially recommended for binary packages to ensure reproducibility, and is more
 #   commonly ignored for libraries.
-#uv.lock
+uv.lock
 
 # poetry
 #   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
@@ -182,9 +182,9 @@ cython_debug/
 .abstra/
 
 # Visual Studio Code
-#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
 #  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
-#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  and can be added to the global gitignore or merged into this file. However, if you prefer,
 #  you could uncomment the following to ignore the entire vscode folder
 # .vscode/
 
@@ -205,3 +205,13 @@ cython_debug/
 marimo/_static/
 marimo/_lsp/
 __marimo__/
+
+# Node stuff for prettier formatting
+node_modules/
+package-lock.json
+
+# macOS
+.DS_Store
+
+# VSCode
+.vscode
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -0,0 +1,25 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: "v6.0.0"
+    hooks:
+      - id: check-case-conflict
+      - id: check-merge-conflict
+      - id: check-toml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: "v0.13.1"
+    hooks:
+      - id: ruff-format
+        args: [--config=ruff.toml]
+      - id: ruff-check
+        args: [--config=ruff.toml, --fix, --exit-non-zero-on-fix]
+
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: "v3.1.0"
+    hooks:
+      - id: prettier
+        additional_dependencies:
+          - prettier@3.6.2
+          - prettier-plugin-toml@2.0.6
diff --git a/.prettierignore b/.prettierignore
@@ -0,0 +1 @@
+# Add any files or directories which should be exempted from prettier formatting
diff --git a/.prettierrc b/.prettierrc
@@ -0,0 +1,12 @@
+{
+  "printWidth": 100,
+  "proseWrap": "always",
+  "overrides": [
+    {
+      "files": "*.md",
+      "options": {
+        "tabWidth": 4
+      }
+    }
+  ]
+}
diff --git a/GEMINI.md b/GEMINI.md
@@ -0,0 +1,32 @@
+# Instructions for Gemini CLI in a `uv` Python project
+
+This `GEMINI.md` file provides context and instructions for the Gemini CLI 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.
+
+## 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
+```
+
+Both of the above commands should be run prior to committing code.
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -0,0 +1,7 @@
+include LICENSE README.md pyproject.toml ruff.toml
+recursive-include examples *
+recursive-include tests *
+prune .github
+prune build
+exclude .github .gitignore
+global-exclude htmlcov/** .coverage* __pycache__/** .gitignore
diff --git a/Makefile b/Makefile
@@ -0,0 +1,78 @@
+# Simple Makefile for use with a uv-based development environment
+.PHONY: install
+install: ## Install the virtual environment with dependencies
+	@echo "🚀 Creating uv Python virtual environment"
+	@uv python install 3.13
+	@uv sync --python=3.13
+	@echo "🚀 Installing Git pre-commit hooks locally"
+	@uv run pre-commit install
+	@echo "🚀 Installing Prettier using npm"
+	@npm install -q --no-fund --include=dev
+
+.PHONY: check
+check: ## Run code quality tools.
+	@echo "🚀 Checking lock file consistency with 'pyproject.toml'"
+	@uv lock --locked
+	@echo "🚀 Linting code and documentation: Running pre-commit"
+	@uv run pre-commit run -a
+	@echo "🚀 Static type checking: Running mypy"
+	@uv run mypy
+
+.PHONY: format
+format: ## Perform ruff formatting
+	@uv run ruff format
+
+.PHONY: lint
+lint: ## Perform ruff linting
+	@uv run ruff check --fix
+
+.PHONY: typecheck
+typecheck: ## Perform type checking
+	@uv run mypy
+
+.PHONY: test
+test: ## Test the code with pytest.
+	@echo "🚀 Testing code: Running pytest"
+	@uv run python -Xutf8 -m pytest tests
+
+.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: publish-test
+publish-test: build ## Test publishing a release to PyPI.
+	@echo "🚀 Publishing: Dry run."
+	@uvx twine upload --repository testpypi dist/*
+
+.PHONY: publish
+publish: 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
diff --git a/README.md b/README.md
@@ -1,2 +1,9 @@
-# cmd2-ansi
-Backport of cmd2.ansi module from cmd2 2.7.0 to ease migration to cmd2 3.x
+<h1 align="center">cmd2-ansi : Backport of cmd2.ansi module from cmd2 2.7.0 to ease migration to cmd2 3.x</h1>
+
+[![Latest Version](https://img.shields.io/pypi/v/cmd2-ansi.svg?style=flat-square&label=latest%20stable%20version)](https://pypi.python.org/pypi/cmd2-ansi/)
+[![GitHub Actions](https://github.com/python-cmd2/cmd2-ansi/workflows/Tests/badge.svg)](https://github.com/python-cmd2/cmd2-ansi/actions?query=workflow%3ATests)
+
+cmd2-ansi is a backport of the cmd2.ansi module from cmd2 2.7.0. It exists to ease the migration
+from cmd2 2.x to cmd2 3.x. In cmd2 3.x, there is a dependency on
+[rich](https://github.com/Textualize/rich) which has great support for creating pretty ansi
+formatting.
diff --git a/cmd2_ansi/__init__.py b/cmd2_ansi/__init__.py
@@ -0,0 +1,24 @@
+"""Import certain things for backwards compatibility."""
+
+from .ansi import (
+    Bg,
+    EightBitBg,
+    EightBitFg,
+    Fg,
+    RgbBg,
+    RgbFg,
+    TextStyle,
+    style,
+)
+
+__all__: list[str] = [  # noqa: RUF022
+    # ANSI Exports
+    'Bg',
+    'Fg',
+    'EightBitBg',
+    'EightBitFg',
+    'RgbBg',
+    'RgbFg',
+    'TextStyle',
+    'style',
+]
diff --git a/cmd2_ansi/ansi.py b/cmd2_ansi/ansi.py
diff --git a/package.json b/package.json
diff --git a/pyproject.toml b/pyproject.toml
diff --git a/ruff.toml b/ruff.toml
diff --git a/tests/__init__.py b/tests/__init__.py
diff --git a/tests/test_ansi.py b/tests/test_ansi.py

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+# Add any files or directories which should be exempted from prettier formatting`