Remove Pyright: stub generation can move to pyrefly stubgen, but needs pyrefly >= 1.2.0 #2391

Background

Following #2368, Pyrefly is the primary type checker (make check-types → check-pyrefly) and pyrefly-baseline.json is down to {"errors": []}. Pyright, however, is still fully wired in:

There are two independent blockers to removing it. This issue tracks the first, which is now understood; the second is noted at the bottom.

Blocker 1: stub generation (investigated)

make pyright-typings shells out to pyright --createstub for folium, uvicorn, and seaborn, so Pyright can't be dropped until stub generation is replaced. (matplotlib stubs come from a git clone of microsoft/python-type-stubs and are unaffected.)

pyrefly stubgen is a viable replacement, but only on an unreleased version.

What was verified

Generated stubs for all three packages with each tool, swapped them into typings/, and ran both checkers:

Two distinct stubgen bugs account for the failures.

1. __all__ is dropped from emitted stubs (7 of the 10 errors)

uvicorn/supervisors/__init__.pyi loses __all__ = ["Multiprocess", "ChangeReload"]. Per the typing spec, a name imported in a stub via from X import Y is not re-exported unless it appears in __all__ or is written from X import Y as Y, so shiny/_uvicorn.py:14 fails with "Multiprocess" is unknown import symbol.

This is systemic, not uvicorn-specific: 0 of the stubs generated by 1.1.1 contained __all__, against 17 from Pyright across the 18 source modules that define it.

Fixed upstream in meta/pyrefly#3924, closed 2026-06-26 (commit 9752acc). Pyrefly 1.1.1 shipped 2026-06-18, so the fix has never appeared in a stable release — it's only in 1.2.0.dev*. With 1.2.0.dev3, __all__ coverage matches or beats Pyright (seaborn: 13 in source, 12 from Pyright, 13 from stubgen).

2. Private symbols are dropped while public aliases still reference them (remaining 3 errors)

uvicorn/_types.py defines:

class _WebSocketReceiveEventBytes(TypedDict): ...
class _WebSocketReceiveEventText(TypedDict): ...
WebSocketReceiveEvent = _WebSocketReceiveEventBytes | _WebSocketReceiveEventText

stubgen emits the public alias but omits both underscore-prefixed classes, leaving dangling references that resolve to Unknown and trip Pyright strict's reportUnknownVariableType in shiny/_uvicorn.py and shiny/_main/_run.py.

Passing --include-private works around this. I don't see an upstream issue for it — worth filing separately.

Proposed change, once pyrefly 1.2.0 is stable

Bump to pyrefly>=1.2.0 and replace the three typings/* recipes in Makefile:59-67. Resolve package paths without hardcoding a Python version (verified working):

typings/folium:
	@echo "Creating folium stubs"
	pyrefly stubgen "$$(python -c "import importlib.util as u,os;print(os.path.dirname(u.find_spec('folium').origin))")" \
		-o typings/folium --include-private

Runtime is comparable — roughly 7-9s per package.

Note

pyrefly check reported 0 errors (207 suppressed) in every configuration above, including the two broken ones. Pyrefly does not enforce the stub re-export rule, so it cannot detect this class of stub degradation; Pyright was the only thing that caught either bug. That's an argument for keeping the Pyright CI job for a while even after stubgen lands, rather than removing it in the same PR.

Blocker 2: shinylive typings (not yet investigated)

.github/workflows/pytest.yaml:71-73 says the separate Pyright job stays "until shinylive's typings are validated under Pyrefly." That's independent of stub generation and is the blocker that actually gates removal today. It needs its own investigation.

Suggested sequencing

• File the --include-private bug upstream. Update 9/1: Skipping for now
• Wait for pyrefly 1.2.0 stable; migrate pyright-typings → pyrefly stubgen. Pyright is then no longer required to run Pyrefly, though its CI job can stay. (chore: use pyrefly for type stubs #2479)
• Investigate and resolve the shinylive typings question.
• Remove the Pyright job, pyrightconfig.json, and the dev dependency.
• Convert # pyright: ignore → # pyrefly: ignore (preferring specific rule codes), then flip permissive-ignores = false — as already noted in pyproject.toml:228.
• Update the docs that still name Pyright as the type checker: CLAUDE.md:23,100,128-129,175, .github/copilot-instructions.md:64,85,294,317, .claude/skills/port-from-bslib/SKILL.md:338.