Modernize tooling: uv, ruff, ty and Python 3.13+

Adopt the same project setup as the observ repo:

- Require Python 3.13+ and drop the `tomli` dependency in favour of
  stdlib `tomllib`. Unpin `keyring` (~=24.3 -> >=25.6) and `shellingham`.
- Switch the build backend from flit to hatchling and move dev
  dependencies from an optional-dependencies extra to PEP 735
  dependency groups (dev/ruff/ty), with uv as the package manager.
- Derive `__version__` from package metadata so the version is declared
  in one place only.
- Extend the ruff lint selection (isort, flake8-debugger, flake8-print)
  and drop the ignores that no longer apply.
- Add ty type checking and a pre-commit config running format, lint,
  typecheck and tests. Annotate `error()` as `NoReturn`, which is what
  it always was and what ty needs to see to narrow correctly.
- Reorganize CI into separate lint, typecheck, test, build and publish
  jobs driven by uv, upgrade all actions to their latest versions and
  pin third-party actions by commit SHA. Tests now run on Python 3.13
  and 3.14; the matrix stays on Windows because the suite needs an OS
  keyring that unlocks unattended.
- Document the development workflow and the 3.13+ requirement in the
  README.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nTpsbs48Pcky9GVthXnWv

Author: claude

.github/workflows/ci.yml

@@ -5,144 +5,120 @@ on:
     branches:
       - master
     tags:
-      - 'v*'
+      - "v*"
   pull_request:
     branches:
       - master
 
+# Cancel in-flight runs when newer commits are pushed to the same
+# branch/PR, but never cancel a tag run mid-publish.
 concurrency:
-  group: CI-${{ github.ref }}
-  cancel-in-progress: true
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ !startsWith(github.ref, 'refs/tags/') }}
 
 jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          enable-cache: true
+          cache-dependency-glob: "pyproject.toml"
+      - name: Install only ruff
+        run: uv sync --only-group ruff
+      - name: Lint
+        run: uv run --no-sync ruff check --output-format=github .
+      - name: Format
+        run: uv run --no-sync ruff format --check .
 
-  lint-build:
-    name: Linting
+  typecheck:
+    name: Typecheck
     runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
     steps:
-    - uses: actions/checkout@v4
-    - name: Set up Python
-      uses: actions/setup-python@v5
-      with:
-        python-version: 3.12
-    - name: Install dependencies
-      run: |
-          python -m pip install --upgrade pip
-          pip install ruff
-    - name: Ruff lint
-      run: |
-          ruff check --output-format=github .
-    - name: Ruff format
-      run: |
-          ruff format --check .
+      - uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          enable-cache: true
+          cache-dependency-glob: "pyproject.toml"
+      - name: Install only ty
+        run: uv sync --only-group ty
+      - name: Typecheck
+        run: uv run --no-sync ty check
 
-  test-builds:
-    name: ${{ matrix.name }}
+  test:
+    name: Test on ${{ matrix.name }}
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
       matrix:
         include:
-          - name: Test py39
-            os: windows-latest
-            pyversion: '3.9'
-          - name: Test py310
-            os: windows-latest
-            pyversion: '3.10'
-          - name: Test py311
-            os: windows-latest
-            pyversion: '3.11'
-          - name: Test py312
+          # the test suite exercises a real OS keyring, which is only
+          # available unattended on Windows runners
+          - name: Windows py313
             os: windows-latest
-            pyversion: '3.12'
-          - name: Test py313
+            pyversion: "3.13"
+          - name: Windows py314
             os: windows-latest
-            pyversion: '3.13'
+            pyversion: "3.14"
     steps:
-    - uses: actions/checkout@v4
-    - name: Set up Python ${{ matrix.pyversion }}
-      uses: actions/setup-python@v5
-      with:
-        python-version: ${{ matrix.pyversion }}
-    - name: Install package and dev dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install .[dev]
-        rm -r keycmd
-    - name: Unit tests
-      run: |
-        pytest -v tests --cov=keycmd --cov-report=term-missing
+      - uses: actions/checkout@v7
+      - name: Install uv and Python ${{ matrix.pyversion }}
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          python-version: ${{ matrix.pyversion }}
+          enable-cache: true
+          cache-dependency-glob: "pyproject.toml"
+          cache-suffix: py${{ matrix.pyversion }}
+      - name: Install dependencies
+        run: uv sync
+      - name: Test
+        run: uv run --no-sync pytest -v --cov=keycmd --cov-report=term-missing tests
 
-  release-build:
-    name: Build release on ubuntu-latest
+  build:
+    name: Build and test wheel
     runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
     steps:
-      - uses: actions/checkout@v4
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: 3.12
-      - name: Install dev dependencies
-        run: |
-          python -m pip install --upgrade pip
-          pip install -U flit build twine
-      - name: Create source distribution
-        run: |
-          python -m build -n -s
-      - name: Build wheel
-        run: |
-          python -m build -n -w
-      - name: Test sdist
-        shell: bash
-        run: |
-          rm -rf ./keycmd
-          pushd $HOME
-          pip install $GITHUB_WORKSPACE/dist/*.tar.gz
-          python -c "import keycmd; print(keycmd.__version__)"
-          popd
-          # don't run tests, we just want to know if the sdist can be installed
-          pip uninstall -y keycmd
-          git reset --hard HEAD
+      - uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+      - name: Build sdist and wheel
+        run: uv build
       - name: Twine check
-        run: |
-          twine check dist/*
-      - name: Upload distributions
-        uses: actions/upload-artifact@v4
+        run: uvx twine check dist/*
+      - name: Upload wheel artifact
+        uses: actions/upload-artifact@v7
         with:
           path: dist
           name: dist
 
   publish:
-    name: Publish release to Github and Pypi
+    name: Publish to Github and Pypi
     runs-on: ubuntu-latest
-    needs: [test-builds, release-build]
+    needs: [lint, typecheck, test, build]
     if: success() && startsWith(github.ref, 'refs/tags/v')
+    permissions:
+      contents: write
     steps:
-    - uses: actions/checkout@v4
-    - name: Set up Python
-      uses: actions/setup-python@v5
-      with:
-        python-version: 3.12
-    - name: Download assets
-      uses: actions/download-artifact@v4
-      with:
-        name: dist
-        path: dist
-    - name: Release
-      uses: softprops/action-gh-release@v2
-      with:
-        token: ${{ secrets.GITHUB_TOKEN }}
-        files: |
-          dist/*.tar.gz
-          dist/*.whl
-        draft: true
-        prerelease: false
-    - name: Publish to PyPI
-      uses: pypa/gh-action-pypi-publish@release/v1
-      with:
-        user: __token__
-        password: ${{ secrets.PYPI_PASSWORD }}
+      - name: Download wheel artifact
+        uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist
+      - name: Release to GitHub
+        uses: softprops/action-gh-release@718ea10b132b3b2eba29c1007bb80653f286566b # v3.0.1
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          files: |
+            dist/*.tar.gz
+            dist/*.whl
+          draft: true
+          prerelease: false
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          user: __token__
+          password: ${{ secrets.PYPI_PASSWORD }}

.gitignore

@@ -1,4 +1,10 @@
-.ruff_cache
+*.egg-info/
 *.pyc
 __pycache__
+.vscode
+.coverage
+.ruff_cache
+.pytest_cache
+.venv
 dist
+uv.lock

.pre-commit-config.yaml

@@ -0,0 +1,28 @@
+repos:
+  - repo: local
+    hooks:
+      - id: ruff (format)
+        name: Format
+        entry: uv run ruff format
+        language: system
+        types: [python]
+        require_serial: true
+      - id: ruff (lint)
+        name: Lint
+        entry: uv run ruff check --fix
+        language: system
+        types: [python]
+        require_serial: true
+      - id: ty
+        name: Typecheck
+        entry: uv run ty check
+        language: system
+        types: [python]
+        pass_filenames: false
+        require_serial: true
+      - id: pytest
+        name: Test
+        entry: uv run pytest tests
+        language: system
+        types: [python]
+        pass_filenames: false

README.md

@@ -18,12 +18,20 @@ The most common use case is to load credentials for package managers such as pip
 
 ## Installation
 
+`keycmd` requires Python 3.13 or newer.
+
 > **Note**
 > If you're intending to install `keycmd` in a WSL or pyenv environment, you'll have to skip ahead to the specific installation instructions for those environments.
 
 ### Global installation
 
-Install `keycmd` from pypi using `pip install keycmd`, or whatever alternative python package manager you prefer.
+Since `keycmd` is a command line tool, the recommended way to install it is with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install keycmd
+```
+
+This installs `keycmd` into its own isolated environment and puts the executable on your `PATH`. Alternatively, install it from pypi using `pip install keycmd`, or whatever alternative python package manager you prefer.
 
 Note that the executable `keycmd` has to be installed to a folder that is on your `PATH` environment variable, or the command won't be available globally. Assuming you were able to run `pip` just now, the `keycmd` executable should end up in the exact same location and everything should be fine.
 
@@ -42,7 +50,7 @@ Run the following commands one by one to install keycmd into its own standalone
 
 ```bash
 # run the following commands one by one
-pyenv virtualenv 3.9 keycmd
+pyenv virtualenv 3.13 keycmd
 pyenv activate keycmd
 pip install keycmd
 pathToKeycmd=$(python -c 'import sys; from pathlib import Path; print(Path(sys.executable).parent / "keycmd")')
@@ -388,3 +396,28 @@ aSdtIG5vdCB0aGF0IHN0dXBpZCA6KQ==
 Since keycmd uses keyring as its backend, you're not limited to just working with OS keyrings. 🤯 Any keyring backend will work with keycmd. No special configuration required!
 
 See the [third party backends](https://github.com/jaraco/keyring/#third-party-backends) list for all options.
+
+## Development
+
+This project uses [uv](https://docs.astral.sh/uv/) for dependency management, [ruff](https://docs.astral.sh/ruff/) for linting and formatting, and [ty](https://docs.astral.sh/ty/) for type checking.
+
+```bash
+# create the virtual environment and install all dependencies
+uv sync
+
+# install the git hooks that run the checks below on every commit
+uv run pre-commit install
+
+# lint, format, typecheck and test
+uv run ruff check --fix
+uv run ruff format
+uv run ty check
+uv run pytest tests
+```
+
+Note that the test suite exercises a real OS keyring, so it needs a keyring backend that can be unlocked without user interaction. On Windows that works out of the box, which is why CI runs the tests there. On other platforms you can point keyring at a file-based backend instead:
+
+```bash
+uv run --with keyrings.alt pytest tests
+# with PYTHON_KEYRING_BACKEND=keyrings.alt.file.PlaintextKeyring set in your environment
+```

keycmd/__init__.py

@@ -1 +1,3 @@
-__version__ = "0.7.0"
+from importlib.metadata import version
+
+__version__ = version("keycmd")

keycmd/cli.py

@@ -1,6 +1,5 @@
 import argparse
-
-import tomli
+import tomllib
 
 from . import __version__
 from .conf import load_conf
@@ -43,7 +42,7 @@ def main(args=None):
 
     try:
         conf = load_conf()
-    except tomli.TOMLDecodeError as err:
+    except tomllib.TOMLDecodeError as err:
         error(err)
     env = get_env(conf)
 

keycmd/conf.py

@@ -1,8 +1,7 @@
+import tomllib
 from pathlib import Path
 from pprint import pformat
 
-import tomli
-
 from .logs import vlog
 
 # exposed for testing
@@ -13,9 +12,9 @@ def load_toml(path):
     """Load a toml file"""
     with path.open("rb") as fh:
         try:
-            return tomli.load(fh)
-        except tomli.TOMLDecodeError as err:
-            raise tomli.TOMLDecodeError(f"invalid TOML in {path}:\n{err}") from err
+            return tomllib.load(fh)
+        except tomllib.TOMLDecodeError as err:
+            raise tomllib.TOMLDecodeError(f"invalid TOML in {path}:\n{err}") from err
 
 
 def load_pyproj(path):

keycmd/logs.py

@@ -1,4 +1,5 @@
 import sys
+from typing import NoReturn
 
 _verbose = False
 
@@ -21,7 +22,7 @@ def vlog(msg):
         print(f"keycmd: {msg}")
 
 
-def error(msg):
+def error(msg) -> NoReturn:
     log(f"error: {msg}", err=True)
     sys.exit(1)