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

Author: claude

.github/workflows/ci.yml

@@ -47,7 +47,7 @@ jobs:
       - name: Install only ty
         run: uv sync --only-group ty
       - name: Typecheck
-        run: uv run --no-sync ty check
+        run: uv run --no-sync ty check --output-format=github --error-on-warning
 
   test:
     name: Test on ${{ matrix.name }}

.pre-commit-config.yaml

@@ -15,7 +15,7 @@ repos:
         require_serial: true
       - id: ty
         name: Typecheck
-        entry: uv run ty check
+        entry: uv run ty check --error-on-warning
         language: system
         types: [python]
         pass_filenames: false

README.md

@@ -401,6 +401,8 @@ See the [third party backends](https://github.com/jaraco/keyring/#third-party-ba
 
 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

keycmd/cli.py

@@ -1,13 +1,14 @@
 import argparse
 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(
@@ -29,14 +30,14 @@
 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
 
@@ -46,9 +47,9 @@ def main(args=None):
         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")

keycmd/conf.py

@@ -1,14 +1,40 @@
 import tomllib
 from pathlib import Path
 from pprint import pformat
+from typing import Any, Literal, NotRequired, TypedDict, cast, overload
 
 from .logs import vlog
 
+
+class KeyConf(TypedDict):
+    """A single entry of the [keys] table"""
+
+    credential: str
+    username: str
+    b64: NotRequired[bool]
+    format: NotRequired[str]
+
+
+class AliasConf(TypedDict):
+    """A single entry of the [aliases] table"""
+
+    key: str
+    b64: NotRequired[bool]
+    format: NotRequired[str]
+
+
+class Conf(TypedDict):
+    """The merged keycmd configuration"""
+
+    keys: dict[str, KeyConf]
+    aliases: NotRequired[dict[str, AliasConf]]
+
+
 # exposed for testing
-USERPROFILE = "~"
+USERPROFILE: str | Path = "~"
 
 
-def load_toml(path):
+def load_toml(path: Path) -> dict[str, Any]:
     """Load a toml file"""
     with path.open("rb") as fh:
         try:
@@ -17,17 +43,25 @@ def load_toml(path):
             raise tomllib.TOMLDecodeError(f"invalid TOML in {path}:\n{err}") from err
 
 
-def load_pyproj(path):
+def load_pyproj(path: Path) -> dict[str, Any]:
     """Load [tool.keycmd] from a pyproject.toml file"""
     data = load_toml(path)
     return data.get("tool", {}).get("keycmd", {})
 
 
-def find_file(fname, first_only=True):
+@overload
+def find_file(fname: str, first_only: Literal[True] = True) -> Path | None: ...
+
+
+@overload
+def find_file(fname: str, first_only: Literal[False]) -> list[Path]: ...
+
+
+def find_file(fname: str, first_only: bool = True) -> Path | list[Path] | None:
     """Find a file by walking up the filesystem, starting at cwd"""
     cur = Path.cwd()
     home = Path.home()
-    results = []
+    results: list[Path] = []
     while True:
         candidate = cur / fname
         if candidate.is_file():
@@ -51,14 +85,15 @@ def find_file(fname, first_only=True):
         # be loaded and merged
         results.reverse()
         return results
+    return None
 
 
-def defaults():
+def defaults() -> dict[str, Any]:
     """Generate the default config"""
     return {"keys": {}}
 
 
-def merge_conf(a, b):
+def merge_conf(a: dict[str, Any], b: dict[str, Any]) -> dict[str, Any]:
     """
     Merges two deep dictionary structures.
     All other datatypes are simply overwritten
@@ -73,7 +108,7 @@ def merge_conf(a, b):
     return a
 
 
-def load_conf():
+def load_conf() -> Conf:
     """
     Load merged configuration from the following files:
     - defaults()
@@ -106,4 +141,6 @@ def load_conf():
 
     vlog(f"merged config:\n{pformat(conf)}")
 
-    return conf
+    # the config is user authored, so this is a statement of the shape keycmd
+    # expects rather than a guarantee; get_env reports violations as user errors
+    return cast(Conf, conf)

keycmd/creds.py

@@ -3,15 +3,27 @@
 
 import keyring
 
+from .conf import Conf
 from .logs import error, vlog
 
+# credential, username, password, apply_b64, format string
+KeyData = tuple[str, str, str, bool, str | None]
 
-def b64(value):
+
+def b64(value: str) -> str:
     """Convert a string to its base64 representation"""
     return base64.b64encode(value.encode("utf-8")).decode("utf-8")
 
 
-def expose(env, key, credential, username, password, apply_b64, format_string):
+def expose(
+    env: dict[str, str],
+    key: str,
+    credential: str,
+    username: str,
+    password: str,
+    apply_b64: bool,
+    format_string: str | None,
+) -> None:
     if format_string:
         password = format_string.format(
             credential=credential,
@@ -23,11 +35,11 @@ def expose(env, key, credential, username, password, apply_b64, format_string):
     env[key] = password
 
 
-def get_env(conf):
+def get_env(conf: Conf) -> dict[str, str]:
     """Load credentials from the OS keyring according to user configuration"""
     env = environ.copy()
 
-    key_data = {}
+    key_data: dict[str, KeyData] = {}
     for key, src in conf["keys"].items():
         password = keyring.get_password(src["credential"], src["username"])
         if password is None:
@@ -53,17 +65,17 @@ def get_env(conf):
             f" (b64: {apply_b64}, format: {format_string})"
         )
 
-    for alias, src in conf.get("aliases", {}).items():
-        key = key_data.get(src["key"])
-        if key is None:
-            error(f"MISSING alias key {src['key']}")
+    for alias, alias_src in conf.get("aliases", {}).items():
+        data = key_data.get(alias_src["key"])
+        if data is None:
+            error(f"MISSING alias key {alias_src['key']}")
         # re-use base data but replace apply_b64 and format_string
-        credential, username, password, _, _ = key
-        apply_b64 = src.get("b64", False)
-        format_string = src.get("format")
+        credential, username, password, _, _ = data
+        apply_b64 = alias_src.get("b64", False)
+        format_string = alias_src.get("format")
         expose(env, alias, credential, username, password, apply_b64, format_string)
         vlog(
-            f"aliasing {src['key']}"
+            f"aliasing {alias_src['key']}"
             f" as environment variable {alias}"
             f" (b64: {apply_b64}, format: {format_string})"
         )

keycmd/logs.py

@@ -1,31 +1,31 @@
 import sys
 from typing import NoReturn
 
-_verbose = False
+_verbose: bool = False
 
 
-def set_verbose(verbose=True):
+def set_verbose(verbose: bool = True) -> None:
     global _verbose
     _verbose = verbose
 
 
-def log(msg, err=False):
-    msg = f"keycmd: {msg}"
+def log(msg: object, err: bool = False) -> None:
+    line = f"keycmd: {msg}"
     if err:
-        print(msg, file=sys.stderr)
+        print(line, file=sys.stderr)
     else:
-        print(msg)
+        print(line)
 
 
-def vlog(msg):
+def vlog(msg: object) -> None:
     if _verbose:
         print(f"keycmd: {msg}")
 
 
-def error(msg) -> NoReturn:
+def error(msg: object) -> NoReturn:
     log(f"error: {msg}", err=True)
     sys.exit(1)
 
 
-def vwarn(msg):
+def vwarn(msg: object) -> None:
     vlog(f"warning: {msg}")

keycmd/py.typed

@@ -1,19 +1,23 @@
 import os
+from collections.abc import Mapping, Sequence
 from pathlib import Path
 from pprint import pformat
 from subprocess import run
 from sys import exit
+from typing import NoReturn
 
 from shellingham import ShellDetectionFailure, detect_shell
 
 from .logs import vlog, vwarn
 
-USE_SUBPROCESS = False  # exposed for testing
-IS_WINDOWS = os.name == "nt"
-IS_POSIX = os.name == "posix"
+USE_SUBPROCESS: bool = False  # exposed for testing
+IS_WINDOWS: bool = os.name == "nt"
+IS_POSIX: bool = os.name == "posix"
 
 
-def exec(args, env):
+def exec(args: list[str], env: Mapping[str, str] | None = None) -> NoReturn:
+    if env is None:
+        env = os.environ
     if USE_SUBPROCESS or IS_WINDOWS:
         # windows does not support process replacement
         # as well as posix systems do
@@ -25,7 +29,7 @@ def exec(args, env):
     os.execvpe(args[0], args, env)
 
 
-def get_shell():
+def get_shell() -> tuple[str, str]:
     """Use shellingham to detect the shell that invoked
     this Python process"""
     try:
@@ -43,15 +47,15 @@ def get_shell():
     return shell_name, shell_path
 
 
-def run_shell(env=None):
+def run_shell(env: Mapping[str, str] | None = None) -> NoReturn:
     """Open an interactive shell for the user to interact
     with."""
     shell_name, shell_path = get_shell()
     vlog(f"spawning subshell: {shell_name}")
     exec([shell_path], env)
 
 
-def run_cmd(cmd, env=None):
+def run_cmd(cmd: Sequence[str], env: Mapping[str, str] | None = None) -> NoReturn:
     """Run a one-off command in a shell."""
     shell_name, shell_path = get_shell()
     if shell_name == "cmd":

keycmd/shell.py

@@ -8,6 +8,7 @@ readme = "README.md"
 license = "MIT"
 license-files = ["LICENSE"]
 keywords = ["keyring", "secrets", "credentials", "environment"]
+classifiers = ["Typing :: Typed"]
 dependencies = [
     "keyring>=25.6",
     "shellingham>=1.5.4",
@@ -50,6 +51,7 @@ select = [
     "I",   # isort imports
     "N",   # pep8-naming
     "B",   # flake8-bugbear
+    "ANN", # flake8-annotations
     "T10", # flake8-debugger
     "T20", # flake8-print
     "RUF", # ruff
@@ -58,10 +60,23 @@ select = [
 [tool.ruff.lint.per-file-ignores]
 # command line tool that reports through print
 "keycmd/logs.py" = ["T201"]
+# the package is fully annotated, the test suite is not
+"tests/*" = ["ANN"]
 
 [tool.ty.src]
 include = ["keycmd"]
 
+[tool.ty.rules]
+# rules that are off by default, enabled because the package is fully typed
+missing-type-argument = "error"
+possibly-missing-attribute = "error"
+possibly-missing-import = "error"
+possibly-unresolved-reference = "error"
+division-by-zero = "error"
+# suppressions have to name the rule they suppress, and have to be needed
+blanket-ignore-comment = "error"
+unused-ignore-comment = "error"
+
 [tool.ty.environment]
 # Match the oldest supported Python version (requires-python), so
 # that the type checker catches use of newer typing features