Modernize tooling: uv, ruff, ty, Python 3.13+ and full typing (#31)

* 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

* Fully annotate the package and enforce it

Annotate every function, parameter and module-level variable in
`keycmd`, and ship a `py.typed` marker so downstream consumers get the
types too.

Typing the config surface required describing its shape, so the
[keys] and [aliases] tables are now `TypedDict`s. `load_conf` casts to
that shape at the boundary where user authored TOML enters the program,
which is where the promise is actually made.

Enforcement, so this does not decay:

- ruff's `ANN` rules require annotations (the test suite is exempt).
- ty's off-by-default rules are enabled: `missing-type-argument`,
  `possibly-missing-attribute`, `possibly-missing-import`,
  `possibly-unresolved-reference` and `division-by-zero`. Suppressions
  must name a rule and must be needed (`blanket-ignore-comment`,
  `unused-ignore-comment`).
- CI and pre-commit run `ty check --error-on-warning`, so warn-level
  diagnostics fail rather than scroll by.

Two fixes fell out of making the types honest:

- `shell.exec` passed `env=None` straight to `os.execvpe`, which
  requires a mapping and would have raised `TypeError`. It now falls
  back to `os.environ`, matching what the subprocess branch already did.
- `creds.get_env` bound both the loop variable and the looked up key
  data to the name `key`, so the two had different types under one name.
  They are now `key`/`data` and `src`/`alias_src`.

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

* Install runtime dependencies in the typecheck job

`uv sync --only-group ty` installs ty but not the project, so ty could
not resolve the `keyring` and `shellingham` imports and failed with
`unresolved-import`.

The pattern was copied from observ, where it is correct because that
project has no runtime dependencies. keycmd has two, so the typecheck
job needs the project installed as well. It still skips the rest of the
dev group.

The lint job keeps using `--only-group ruff`: ruff is purely syntactic
and needs nothing installed to resolve.

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

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: Korijn

.github/workflows/ci.yml

@@ -5,144 +5,122 @@ 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"
+      # ty needs the runtime dependencies installed to resolve their
+      # imports, so this installs the project itself, unlike the lint job
+      - name: Install ty and runtime dependencies
+        run: uv sync --no-default-groups --group ty
+      - name: Typecheck
+        run: uv run --no-sync ty check --output-format=github --error-on-warning
 
-  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 --error-on-warning
+        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,30 @@ 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.
+
+The `keycmd` package is fully annotated and ships a `py.typed` marker, so the types are available to anything that imports it. Ruff's `ANN` rules keep it that way; the test suite is exempt.
+
+```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,14 +1,14 @@
 import argparse
-
-import tomli
+import tomllib
+from collections.abc import Sequence
 
 from . import __version__
 from .conf import load_conf
 from .creds import get_env
 from .logs import error, log, set_verbose
 from .shell import run_cmd, run_shell
 
-cli = argparse.ArgumentParser(
+cli: argparse.ArgumentParser = argparse.ArgumentParser(
     prog="keycmd",
 )
 cli.add_argument(
@@ -30,26 +30,26 @@
 cli.add_argument("command", nargs=argparse.REMAINDER, help="command to run")
 
 
-def main(args=None):
+def main(args: Sequence[str] | None = None) -> None:
     """CLI entrypoint"""
-    args = cli.parse_args(args=args)
+    parsed = cli.parse_args(args=args)
 
-    if args.verbose:
+    if parsed.verbose:
         set_verbose()
 
-    if args.version:
+    if parsed.version:
         log(f"v{__version__}")
         return
 
     try:
         conf = load_conf()
-    except tomli.TOMLDecodeError as err:
+    except tomllib.TOMLDecodeError as err:
         error(err)
     env = get_env(conf)
 
-    if args.shell:
+    if parsed.shell:
         run_shell(env=env)
-    elif args.command:
-        run_cmd(args.command, env=env)
+    elif parsed.command:
+        run_cmd(parsed.command, env=env)
     else:
         error("missing command argument")