Python 3.11-3.15 foundation: refreshed dependencies, modern toolchain, CI and trusted publishing (0.7.0)

.github/workflows/docs.yaml

@@ -1,35 +1,36 @@
-name: Deploy docs to GitHub Pages 
+name: Deploy docs to GitHub Pages
+
 on:
   push:
     branches:
       - main
     paths:
       - 'docs/**'
+      - 'mkdocs.yaml'
+      - '.github/workflows/docs.yaml'
   workflow_dispatch:
 
+concurrency:
+  group: docs
+  cancel-in-progress: false
+
 permissions:
   contents: write
+
 jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - name: Configure Git Credentials
         run: |
           git config user.name github-actions[bot]
           git config user.email 41898282+github-actions[bot]@users.noreply.github.com
-      - uses: actions/setup-python@v5
-        with:
-          python-version: 3.x
-      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
-      - uses: actions/cache@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.3.0
         with:
-          key: mkdocs-material-${{ env.cache_id }}
-          path: .cache
-          restore-keys: |
-            mkdocs-material-
-      - run: |
-          python -m pip install --upgrade pip
-          python -m pip install uv
-          uv sync --group=docs
-      - run: uv run mkdocs gh-deploy --force
+          enable-cache: true
+      - name: Build and deploy
+        run: uv run --locked --only-group docs mkdocs gh-deploy --force
+        env:
+          MKDOCS_GIT_COMMITTERS_APIKEY: ${{ github.token }}

.github/workflows/publish.yaml

@@ -0,0 +1,57 @@
+name: Publish to PyPI
+
+# Publishes with PyPI trusted publishing (OIDC) - no API token is stored in the repository.
+# One-time setup on https://pypi.org/manage/project/cliffy/settings/publishing/ :
+#   owner: jaykv, repository: cliffy, workflow: publish.yaml, environment: pypi
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.3.0
+      - name: Build sdist and wheel
+        run: uv build
+      - name: Check the release tag matches the package version
+        run: |
+          version="$(uv version --short)"
+          tag="${GITHUB_REF_NAME#v}"
+          if [ "$version" != "$tag" ]; then
+            echo "::error::release tag '$GITHUB_REF_NAME' does not match pyproject version '$version'"
+            exit 1
+          fi
+      - name: Smoke test the wheel
+        run: uv run --isolated --no-project --with dist/*.whl cli --version
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    name: Upload to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/cliffy/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.3.0
+      - name: Publish
+        run: uv publish --trusted-publishing always dist/*

.github/workflows/python-app.yaml

@@ -1,74 +1,69 @@
-name: Python library with uv
+name: CI
 
-env:
-  COLUMNS: 120
-
 on:
   push:
+    branches:
+      - main
     paths:
       - 'cliffy/**'
       - 'tests/**'
       - 'examples/**'
       - '!examples/generated/**'
+      - 'pyproject.toml'
+      - 'uv.lock'
+      - 'Makefile'
+      - '.github/workflows/python-app.yaml'
+  pull_request:
+    paths:
+      - 'cliffy/**'
+      - 'tests/**'
+      - 'examples/**'
+      - '!examples/generated/**'
+      - 'pyproject.toml'
+      - 'uv.lock'
+      - 'Makefile'
+      - '.github/workflows/python-app.yaml'
   workflow_dispatch:
-
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
 
 permissions:
   contents: read
 
+env:
+  COLUMNS: 120
+  # the environment is synced once, explicitly; `uv run` inside the Makefile must not re-resolve it
+  UV_NO_SYNC: 1
+
 jobs:
-  build:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
     strategy:
+      fail-fast: false
       matrix:
-        extras: [true, false]
-        python-version: [ "3.13", "3.12", "3.11", "3.10", "3.9" ]
-        os: [ubuntu-latest] # windows-latest , macos-latest
-        isMain:
-          - ${{ contains(github.ref, 'main') }}
-        isTag:
-          - ${{ startsWith(github.ref, 'refs/heads/v') }}
-        exclude:
-          # - isMain: false
-          #   os: windows-latest
-          - isMain: false
-            extras: false
-          # - isTag: true
-          #   os: windows-latest
-          - isTag: true
-            extras: false
-    defaults:
-      run:
-        shell: bash
-    runs-on: ${{ matrix.os }}
+        python-version: ["3.11", "3.12", "3.13", "3.14", "3.15"]
     steps:
-    - uses: actions/checkout@v4
-    - name: Install uv
-      uses: astral-sh/setup-uv@v5
-      with:
-        python-version: ${{ matrix.python-version }}
-        enable-cache: true
-        cache-suffix: ${{ matrix.extras }}
-    - name: Install library
-      run: uv sync
-      if: ${{ matrix.extras == false }}
-    - name: Install library
-      run: uv sync --all-extras
-      if: ${{ matrix.extras }}
-    - name: Code quality
-      run: |
-        uv run make lint
-    - name: Test with pytest
-      if: github.ref != 'refs/heads/main' || matrix.python-version != '3.13'
-      run: |
-        uv run make test
-    - name: Test with pytest + coverage
-      if: github.ref == 'refs/heads/main' && matrix.python-version == '3.13'
-      run: |
-        uv run make test-cov
-    - name: Coverage report
-      if: github.ref == 'refs/heads/main' && matrix.python-version == '3.13'
-      uses: codecov/codecov-action@v5
-      with:
-        token: ${{ secrets.CODECOV_TOKEN }}
-    - name: Minimize uv cache
-      run: uv cache prune --ci
+      - uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.3.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+      - name: Install library
+        run: uv sync --locked --all-extras
+      - name: Code quality
+        run: make lint
+      - name: Test with pytest
+        if: github.ref != 'refs/heads/main' || matrix.python-version != '3.15'
+        run: make test
+      - name: Test with pytest + coverage
+        if: github.ref == 'refs/heads/main' && matrix.python-version == '3.15'
+        run: make test-cov
+      - name: Coverage report
+        if: github.ref == 'refs/heads/main' && matrix.python-version == '3.15'
+        uses: codecov/codecov-action@v7
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}

.gitignore

@@ -83,8 +83,6 @@ target/
 profile_default/
 ipython_config.py
 
-# pyenv
-.python-version
 
 # pipenv
 #   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
@@ -134,3 +132,18 @@ dmypy.json
 *.code-workspace
 .vscode
 .DS_Store
+
+# ruff
+.ruff_cache/
+
+# uv
+.uv-cache/
+
+# cliffy: CLIs loaded into the working tree and their metadata
+cliffy/clis/
+cliffy/metadata/
+
+# cliffy: test build outputs
+test-builds/
+test-manifest-builds/
+test-manifest-builds-response/

.python-version

@@ -0,0 +1 @@
+3.13

Makefile

@@ -1,12 +1,13 @@
-check: format lint test clean
-
 SOURCE_FILES=cliffy tests
+GENERATE_DEPS=requests "six<1.0.0" keyring
+
+check: format lint test clean
 
 install:
-	uv sync --frozen --all-extras --group dev --group docs
+	uv sync --frozen --all-extras --group docs
 
 sync:
-	uv sync --all-extras --group dev --group docs
+	uv sync --all-extras --group docs
 
 test:
 	uv run pytest --cov --cov-config=pyproject.toml -vv --capture=tee-sys -n auto
@@ -15,9 +16,9 @@ test-cov:
 	uv run pytest --cov --cov-config=pyproject.toml --cov-branch --cov-report=xml -vv --capture=tee-sys -n auto
 
 clean:
-	rm -rf build/ dist/ *.egg-info .*_cache test-builds test-manifest-builds
-	find . -name '*.pyc' -type f -exec rm -rf {} +
-	find . -name '__pycache__' -exec rm -rf {} +
+	rm -rf build/ dist/ site/ *.egg-info .*_cache coverage.xml test-builds test-manifest-builds test-manifest-builds-response
+	find . -name '*.pyc' -type f -not -path './.venv/*' -exec rm -f {} +
+	find . -name '__pycache__' -not -path './.venv/*' -prune -exec rm -rf {} +
 
 package: clean
 	uv build
@@ -26,34 +27,35 @@ publish: package
 	uv publish
 
 format:
-	uv run ruff format --exclude=cliffy/clis ${SOURCE_FILES}
+	uv run ruff format ${SOURCE_FILES}
 	uv run ruff check ${SOURCE_FILES} --fix
 
 lint:
-	uv run ruff format --check --diff ${SOURCE_FILES} --exclude=cliffy/clis
+	uv run ruff format --check --diff ${SOURCE_FILES}
 	uv run ruff check ${SOURCE_FILES}
 	uv run mypy cliffy --strict
 	uv run mypy tests
 
 docs-serve:
-	uv run mkdocs serve
-
-shell:
-	source .venv/bin/activate
-
-generate-clis: 
-	pip install requests "six<1.0.0" rich keyring
-	cli load examples/*.yaml
+	uv run --group docs mkdocs serve
+
+# The example manifests declare requirements that are not cliffy dependencies. They have to be
+# installed into the project environment (not a `uv run --with` overlay), because cliffy validates
+# `requires` against `pip freeze`. `uv sync` in generate-cleanup removes them again.
+generate-clis:
+	uv pip install ${GENERATE_DEPS}
+	uv run --no-sync cli load examples/*.yaml
 	cp cliffy/clis/*.py examples/generated/
 
 generate-all: generate-clis generate-schema generate-cleanup
 	@echo "~ done"
 
 generate-cleanup:
-	pip uninstall -y requests six rich keyring
-	cli rm-all
+	uv run --no-sync cli rm-all
+	uv sync --all-extras --group docs
 
 generate-schema:
-	python -m cliffy.manifest --json-schema > examples/cliffy_schema.json
+	uv run python -m cliffy.manifest --json-schema > examples/cliffy_schema.json
 
-.PHONY: test clean
+.PHONY: check install sync test test-cov clean package publish format lint docs-serve \
+	generate-clis generate-all generate-cleanup generate-schema