pre-commit: Add ty for Python type hints

[cclauss]

Describe your change:

Ty is much faster than mypy and better maintained.

• https://docs.astral.sh/ty

• https://github.com/astral-sh/ty-pre-commit

• Add an algorithm?

• Fix a bug or typo in an existing algorithm?

• Add or change doctests? -- Note: Please avoid changing both code and tests in a single pull request.

• Add type checking to pre-commit?

Checklist:

• I have read CONTRIBUTING.md.
• This pull request is all my own work -- I have not plagiarized.
• I know that pull requests will not be merged if they fail the automated tests.
• This PR only changes one algorithm file. To ease review, please open separate PRs for separate algorithms.
• All new Python files are placed inside an existing directory.
• All filenames are in all lowercase characters with no spaces or dashes.
• All functions and variable names follow Python naming conventions.
• All function parameters and return values are annotated with Python type hints.
• All functions have doctests that pass the automated testing.
• All new algorithms include at least one URL that points to Wikipedia or another similar explanation.
• If this pull request resolves one or more open issues, then the description above includes the issue number(s) with a closing keyword: "Fixes #ISSUE-NUMBER".

@priya-sundaram-dev, your review please. Like:

• Type-check the entire codebase with ty, with lots of rules ignored priya-sundaram-dev/whoosh#120

[priya-sundaram-dev]

Happy to review — and glad to see ty coming to this repo. 🙂

The good: the structure is exactly what I'd recommend, and it mirrors what worked well in whoosh — land ty with a conservative [tool.ty] block that ignores the noisy rules up front (unresolved-import, no-matching-overload, invalid-parameter-default, …), then un-ignore them one at a time as the codebase gets annotated. On whoosh I track that as a "gradually un-ignore" issue so each rule flip is its own small, reviewable PR (priya-sundaram-dev/whoosh#121). I'd suggest opening the equivalent tracking issue here so the ignore list is visibly temporary rather than permanent.

The failure is not type errors. Reading the pre-commit.ci log, every other hook passes and ty fails at provisioning, not analysis:

Failed to download .../cpython-3.14.7+20260901-...-freethreaded-install_only_stripped.tar.gz … dns error … Temporary failure in name resolution

Because requires-python = ">=3.14", ty resolves the target to 3.14 and, not finding a matching interpreter in pre-commit.ci's sandbox, tries to fetch a managed CPython from python-build-standalone. pre-commit.ci runs hooks without network, so that download can't succeed — it's an environment wall, not your config.

Two ways forward (either works):

1. Stop ty from downloading an interpreter by pointing it at the one pre-commit.ci already provides, e.g.

   - repo: https://github.com/astral-sh/ty-pre-commit
     rev: v0.0.78
     hooks:
       - id: ty
         args: [--python, python3]

   --python is ty's documented escape hatch for "environment in an unusual location," and it skips the managed-interpreter fetch. This is the least-friction fix if the sandbox's Python satisfies the resolver.

2. Run ty where there is network — a dedicated GitHub Actions job — and add it to ci.skip so pre-commit.ci doesn't try:

   ci:
     skip: [ty]

   This is the split I use on whoosh (I run the whole pre-commit suite, ty included, in an Actions pre-commit job precisely so hooks that need network/interpreters aren't at the mercy of a sandbox). It's the most robust, at the cost of ty not running on the fast pre-commit.ci path.

I'd try option 1 first; fall back to option 2 if the resolver still insists on a 3.14 download. Everything else in the diff (hook reordering, the urlretrieve import tidy) looks clean. Ping me once CI is green and I'm glad to re-review.

[cclauss]

This branch passes:
% uv audit
% uv check
% uv format

[priya-sundaram-dev]

Thanks for adding args: [--python, python3] — that's the right instinct, but the pre-commit.ci run still fails at the same spot, and the log confirms why:

ty.......................................................................Failed
- hook id: ty
- exit code: 2
error: Request failed after 3 retries in 10.3s
  Caused by: Failed to download .../cpython-3.14.7+20260901-...-freethreaded-install_only_stripped.tar.gz
  Caused by: dns error: Temporary failure in name resolution

--python python3 only points ty at an interpreter if a compatible one is already present. pre-commit.ci's runner doesn't ship 3.14, and this project's requires-python >= 3.14 makes ty try to fetch a managed python-build-standalone build — which the no-network sandbox can't reach. So it will keep failing there regardless of the arg.

The clean fix is the same pattern you already use for uv-lock two lines above: skip it on pre-commit.ci and run it where the network is available.

ci:
  skip: [uv-lock, ty]

…and add a tiny CI job (network is available in Actions, so ty can download 3.14 there):

  ty:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: astral-sh/setup-uv@v6
      - run: uvx ty check

This is exactly the split I landed in whoosh (whoosh#120 runs ty in Actions, whoosh#133 tracks the pre-commit.ci side) — keeps the hook available for local pre-commit run while unblocking the PR gate. Happy to open the workflow PR against your branch if that's useful.

[priya-sundaram-dev]

Good news — the pre-commit.ci half is fixed now (ci.skip: [ty, uv-lock] is exactly right). The remaining red is the new Actions ruff_and_ty job, and it's a different problem: uvx ty check runs ty in an isolated ephemeral env that's detached from the project, so it sees neither the dependencies nor the right Python version. Two tells in the log:

• 64 of 69 errors are unresolved-import (numpy, httpx, pytest, …) — those packages simply aren't installed in the uvx env, so ty can't resolve them.
• web_programming/instagram_crawler.py:56 reports "Multiple exception types must be parenthesized on Python 3.13" — ty is targeting the runner's interpreter, not the requires-python >= 3.14 from pyproject.toml.

Both go away if ty runs inside the synced project venv instead of an isolated one:

- uses: astral-sh/setup-uv@v7
- run: uvx ruff check --output-format=github
- run: uv sync
- run: uv run --with ty ty check --output-format=github

uv sync installs the deps and pins Python 3.14 into .venv; uv run points ty at that env, so imports resolve and the version target is correct.

A nice side effect: once ty can actually see the dependencies, you can drop the blanket rules.unresolved-import/unresolved-attribute ignores in [tool.ty] — those currently mask real typos. That leaves just the handful of genuine findings (scripts/validate_solutions.py loader-is-None, the recaptcha_verification.py print overload), which fit the conservative per-rule ignore list we used in whoosh and can be un-ignored one at a time — same gradual approach as your structure here.

Happy to open a PR against your branch with the workflow change + the trimmed [tool.ty] if that's useful.

[priya-sundaram-dev]

Real progress — pre-commit.ci is green and the Actions job now correctly does uv sync + uv run --with=ty. One anomaly is left though, and it's the whole ballgame:

Almost every red diagnostic is on a rule you've already set to "ignore" in [tool.ty]. Of the 45 errors:

status	rules	count
already ignored in [tool.ty]	unresolved-attribute (24), invalid-argument-type (8), unresolved-import (5), no-matching-overload (2), unsupported-operator, not-subscriptable, invalid-return-type	42
genuinely un-ignored	unknown-argument + missing-argument (both web_programming/reddit.py:45, httpx HTTPError), invalid-syntax (instagram_crawler.py)	3

So ty isn't applying your project [tool.ty] config in this invocation — otherwise those 42 would vanish and you'd be left with just the 3. Two things are conspiring:

1. Config root / version. whoosh runs ty via the pinned astral-sh/ty-pre-commit (rev v0.0.74) with an explicit path (ty check src/whoosh), and the identical rules.x = "ignore" inline form is honored. Here --with=ty pulls unpinned latest ty and passes no path. Pinning (--with=ty==0.0.74, or whatever rev matches a ty-pre-commit you'd add) and anchoring the path (ty check .) makes config discovery deterministic.
2. uv sync picked the free-threaded interpreter. The module-resolution info lines point at .../python3.14t/site-packages — requires-python >= 3.14 let uv default to 3.14t, where pytest/django/httpx stubs don't resolve (hence some of the unresolved-imports). uv sync -p 3.14 pins the GIL build.

Once config is honored, the only true findings are the httpx HTTPError(response=...) call in reddit.py (its signature is HTTPError(message)) and the 3.13-vs-3.14 parenthesized-except in instagram_crawler.py — both a one-line fix or a scoped # ty: ignore, same gradual approach as whoosh#121.

Still happy to push this (pinned ty + ty check . + -p 3.14) as a PR onto pre-commit-ty if that's easier than another round-trip.

[priya-sundaram-dev]

This is real progress — the env fix landed. uv run --with=beautifulsoup4,pytest,ty now resolves third-party deps, so the failure mode has flipped from config noise to mostly genuine type findings. Two things left to make the signal clean, plus one real bug ty caught for free.

1. Close the last env gaps (5× unresolved-import)
The search paths in the log show the synced venv resolved to free-threaded python3.14t (.venv/lib/python3.14t/...). Two symptoms fall out of that:

• maths/test_factorial.py + scripts/validate_solutions.py report pytest/first-party maths.factorial as unresolved — the repo root isn't a source root and some wheels are thin on 3.14t.
• recaptcha_verification.py → django.contrib.auth / django.shortcuts unresolved (django simply isn't in --with).

Fix: pin the non-freethreaded interpreter and add django:

uv run -p 3.14 --with=beautifulsoup4,pytest,django,ty ty check --output-format=github

(-p 3.14 gets you full-fat wheels; add . to the source roots so first-party imports resolve.)

2. The remaining ~35 are genuine and are basically one class: bs4 Tag | None
soup.find(...) returns Tag | None, and the code immediately does .get()/.attrs/.text/[...] on it. ty is correctly flagging latent AttributeError-on-missing-element paths. All the downstream invalid-argument-type / no-matching-overload / invalid-return-type errors fall out of the same str | AttributeValueList | None unions bs4 returns.

That's too many real fixes to bundle into a "just add ty" PR — and in places like open_google_results.py the code already wraps the chain in try/except AttributeError, so a code change isn't even wanted. So land ty now with unresolved-attribute (+ the bs4 union rules) per-rule-ignored in [tool.ty], and open a tracking issue to burn them down file-by-file. That keeps this PR green + mergeable while preserving the signal — same gradual-un-ignore model we're using in whoosh#121.

3. One genuine bug to fix in this PR (one line)
web_programming/reddit.py:42:

raise httpx.HTTPError(response=response)

httpx.HTTPError.__init__ takes a positional message, not response — this would raise TypeError at runtime on an HTTP 429, masking the real error. Either drop it (the preceding response.raise_for_status() already covers non-2xx) or:

raise httpx.HTTPError(f"Rate limited (HTTP 429): {response.url}")

Nice concrete "ty caught a live bug" line for the PR description.

Happy to push any of these onto the branch if useful.

[cclauss]

3. One genuine bug to fix in this PR (one line)
   web_programming/reddit.py:42:

    response.raise_for_status()
    if response.status_code == 429:
        raise httpx.HTTPError(response=response)

I do not think the code on line 42 will ever be run.

If we have a response.raise_for_status(), no code catches that exception, so execution stops with an error.
If we do not have a response.raise_for_status(), the response.status_code will not be 429.

---

Priya, can you please create a separate pull request that replaces this one?

Would we be better off excluding files or ignoring rules?

[priya-sundaram-dev]

On the genuine bug: you're right, that branch is dead — raise_for_status() already raises for 429, so if response.status_code == 429 is unreachable, and httpx.HTTPError(response=...) would itself TypeError (no response param) if it ever ran, which is exactly the unknown-argument/missing-argument ty flags. Shipped the one-line fix separately as #15176 so it can land independently of the ty rollout.

Exclude files vs. ignore rules — I'd ignore rules, not exclude files.

The two options aren't equivalent:

• exclude turns a file completely dark. ty stops checking it for everything, including the rules that currently pass. A real bug introduced later in an excluded file (a typo'd attribute, a bad call) goes unreported forever. You also have to keep the exclude list in sync as files move.
• Ignoring a rule keeps every file checked for every other rule. You only silence the specific diagnostic that's too noisy today, and you get a clean, monotonic path forward: un-ignore one rule at a time as the annotations improve, and CI tells you the moment a newly-typed area lets you tighten. That's the model I run on whoosh (Tracking: gradually un-ignore ty rules as the codebase gets typed priya-sundaram-dev/whoosh#121) and it's worked well — the ignore list only ever shrinks.

So my recommendation for the replacement PR:

1. Config, not file-level suppression. Add ty to pre-commit + the Actions job, and put the noisy rules under [tool.ty.rules] as "ignore" (the unresolved-attribute / invalid-argument-type / unresolved-import / overload families that dominate the current output). Land it green, then peel rules off over time.
2. Reserve exclude for the genuinely un-typeable handful — the dynamic crawlers (web_programming/instagram_crawler.py etc.) where the value being scraped is Any by nature and stubbing it fights the point of the example. A 2–3 file exclude list is fine; a broad one isn't.
3. Keep the from __future__ import annotations cleanup as its own PR. It's ~280 mechanical file edits and orthogonal to wiring up ty — bundling it makes this PR unreviewable and any ty-config tweak forces a re-review of 287 files. Splitting it lets the config land fast and the cleanup be a boring rubber-stamp.

Happy to open the config-only replacement PR along those lines if you'd like — say the word and I'll base it on the [tool.ty] snapshot and the exclude short-list above.