Add pyrefly type checking. by AndreasBackx · Pull Request #3412 · pallets/click

AndreasBackx · 2026-05-08T22:14:10Z

This adds pyrefly to the type checking. I'm working on a lot of typing improvements and it's helpful to have a third one because it's sometimes not really clear why pyright is saying typing is wrong. It already is saying some things are incorrect which I'm planning to look into.

I hope it's not going to lead to a conflict of typing issues, and if so, we can review this more closely in the future.

As of writing I've not fixed the typing issues, but I'll publish the PR once done.

kdeldycke · 2026-05-09T08:57:54Z

Typing is not my forte. In my projects I just fire up a mypy and try to make it happy. Waiting for ty to mature a bit and I'll switch to it in the future.

So I'll let other give feedback on that topic and I'll just follow the movement! 😁

davidism · 2026-05-09T14:48:15Z

I'd prefer to stick to mypy for now. If we're still testing with pyright, we can remove that; it was added when I thought we needed to test with all of them. But really, we just need to test with mypy for our own code, and pyright --verifytypes to know that we export complete types for others to use in their code.

I know pyrefly is working on an export verifcation as well, but I tried last month and both its type checking and verifcation weren't ready yet. Same with ty. I'm really interested in those two, but prefer we wait for now. mypy, for all its quirks, is very mature and actively maintained.

davidism · 2026-05-09T14:51:41Z

Regarding static typing in general, remember: annotations are there to serve us and our users, not the other way around. Click (and all of Pallets) predates static typing, and we would design it differently today to be better typed. So if we're doing something weird and typing can't express it (or it's too complicated to figure out), you're fine adding # type: ignore[error code] comments to insist that a return type is what we say it is, that a use of an argument is correct, etc.

AndreasBackx · 2026-05-09T19:30:20Z

Wasn't expecting the comments just yet. 😅 I was primarily using this to experiment a bit on where we could improve typing. It's very neat to see where we could make the typing experience Click offers better, and also make it less of a pain to use inside of the codebase. So far it's teaching and frustrating me, as I'm expecting certain typing to be possible (as someone who uses Rust quite a bit) and then it seems to not be possible.

My current struggle is trying to plug through the binary/text file modes without having to repeat if "b" in mode everywhere and casting. There's fairly little that I can find on this and how others solve it.

I'll see where my experimentation gets me. But I'm not expecting all that much just yet.

So far Pyrefly is easier to use than pyright:

No waiting multiple seconds to type check the codebase.
Actually readable output from the CLI.

And mypy seems to sometimes not be as strict as pyright nor pyrefly, I've found it to be useful to see what the different ones say.

Regardless of where the typing experimentation goes, I do think it'd be useful to have multiple type checkers available. It sometimes helps to see how each one of them views a problem, even when we only care about a single one (mypy). Would we be able to have pyrefly and ty added and available via uvx pyrefly/ty which would make this easier (but not enabled in CI/tox)?

davidism · 2026-05-09T19:38:14Z

Yeah it's fine to add config for it and use it to figure things out, just don't want to require it in CI yet.

Rowlando13 · 2026-05-09T19:42:13Z

I am interested to see where this goes. I switched to pyrefly mostly because the Language server works better in vscode.

jorenham

Yay Pyrefly 🎉.

I took a quick look and left some comments; hope you don't mind.

jorenham · 2026-05-18T13:11:31Z

+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version-file: pyproject.toml


There's no need for setup-python if you're using setup-uv

jorenham · 2026-05-18T13:13:57Z

+) -> tuple[t.IO[bytes], bool]: ...
+
+
+@t.overload
+def open_stream(
+    filename: str | os.PathLike[str],
+    mode: OpenTextMode = "r",
+    encoding: str | None = None,
+    errors: str | None = "strict",
+    atomic: bool = False,
+) -> tuple[t.IO[str], bool]: ...
+
+
+def open_stream(


nit: those newlines here aren't necessary, and makes things easier to read IMO.

Suggested change

) -> tuple[t.IO[bytes], bool]: ...

@t.overload

def open_stream(

filename: str | os.PathLike[str],

mode: OpenTextMode = "r",

encoding: str | None = None,

errors: str | None = "strict",

atomic: bool = False,

) -> tuple[t.IO[str], bool]: ...

def open_stream(

) -> tuple[t.IO[bytes], bool]: ...

@t.overload

def open_stream(

filename: str | os.PathLike[str],

mode: OpenTextMode = "r",

encoding: str | None = None,

errors: str | None = "strict",

atomic: bool = False,

) -> tuple[t.IO[str], bool]: ...

def open_stream(

(btw, I like these overloads)

jorenham · 2026-05-18T13:15:48Z

        return getattr(self._f, name)

-    def __enter__(self) -> _AtomicFile:
+    def __enter__(self) -> _AtomicFile[AnyStr]:


Suggested change

def __enter__(self) -> _AtomicFile[AnyStr]:

def __enter__(self) -> t.Self:

jorenham · 2026-05-18T13:19:01Z

+class _AtomicFile(t.IO[AnyStr], t.Generic[AnyStr]):
+    def __init__(self, f: t.IO[AnyStr], tmp_filename: str, real_filename: str) -> None:
+        self._f: t.IO[AnyStr] = f


It's almost always better to avoid using AnyStr if you can (there are differences between how type-checkers treat it because it's very underspecified in the typing spec). And here, you can parametrize the entire f type, i.e. with

_FileT_co = t.TypeVar("_FileT_co", bound=t.IO[Any], covariant=True)

This way you capture more typing information, avoid issues with invariance, and avoid having to deal with the awkward AnyStr.

jorenham · 2026-05-18T13:19:35Z

+    from typing_extensions import Buffer
+
+    class _MSVCRTModule(t.Protocol):
+        def get_osfhandle(self, fd: int) -> int: ...


nit:

Suggested change

def get_osfhandle(self, fd: int) -> int: ...

def get_osfhandle(self, fd: int, /) -> int: ...

jorenham · 2026-05-18T13:21:30Z



-ShellCompleteType = t.TypeVar("ShellCompleteType", bound="type[ShellComplete]")
+ShellCompleteType = t.TypeVar("ShellCompleteType", bound="ShellComplete")


nit: Now that it's no longer bound to a type, the name isn't accurate anymore. The type variable naming convention is to use private (underscore-prefixed) naming and a T as suffix.

jorenham · 2026-05-18T13:22:59Z

 def secho(
    message: t.Any | None = None,
-    file: t.IO[t.AnyStr] | None = None,
+    file: t.TextIO | t.BinaryIO | None = None,


t.TextIO | t.BinaryIOis a bit stricter (narrower) thant.IO`, which might lead to false positives.

Suggested change

file: t.TextIO | t.BinaryIO | None = None,

file: t.IO[Any] | None = None,

jorenham · 2026-05-18T13:24:24Z



-class File(ParamType[t.IO[t.Any]]):
+class File(ParamType[t.IO[AnyStr]], t.Generic[AnyStr, OpenFileMode]):


Same as above; it's better to parametrize this using a covariant type variable with bound=t.IO[Any]

jorenham · 2026-05-18T13:27:48Z



-class File(ParamType[t.IO[t.Any]]):
+class File(ParamType[t.IO[AnyStr]], t.Generic[AnyStr, OpenFileMode]):


I would strongly recommend against using OpenFileMode here: Pyright, for example, tends to upcasts Literal string values to str when used in generics, so this can lead to unexpected and different outcomes between type-checkers.

If I were in you should, I'd instead use a TypeVar(..., bound=bytes | str) here, and update the __init__ overloads accordingly.

Add pyrefly type checking.

c1b419d

kdeldycke added the typing label May 9, 2026

kdeldycke requested review from Rowlando13 and davidism May 9, 2026 08:55

kdeldycke added the github_actions Pull requests that update GitHub Actions code label May 9, 2026

AndreasBackx added 7 commits May 9, 2026 18:27

Improve winconsole pyrefly typing

e1f1797

Improve help option cache typing

2203c59

Improve shell completion class typing

513f72c

Improve usage error context typing

2f16bf1

Improve terminal and testing typing

a703361

Add proper AnyStr usage in File types.

b4ca68a

Temporary improvements: AnyStr and OpenFileMode

e6cfbbf

jorenham reviewed May 18, 2026

View reviewed changes

	def __enter__(self) -> _AtomicFile[AnyStr]:
	def __enter__(self) -> t.Self:

	def get_osfhandle(self, fd: int) -> int: ...
	def get_osfhandle(self, fd: int, /) -> int: ...



		ShellCompleteType = t.TypeVar("ShellCompleteType", bound="type[ShellComplete]")
		ShellCompleteType = t.TypeVar("ShellCompleteType", bound="ShellComplete")

	file: t.TextIO \| t.BinaryIO \| None = None,
	file: t.IO[Any] \| None = None,



		class File(ParamType[t.IO[t.Any]]):
		class File(ParamType[t.IO[AnyStr]], t.Generic[AnyStr, OpenFileMode]):

Uh oh!

Conversation

AndreasBackx commented May 8, 2026

Uh oh!

kdeldycke commented May 9, 2026

Uh oh!

davidism commented May 9, 2026

Uh oh!

davidism commented May 9, 2026

Uh oh!

AndreasBackx commented May 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

davidism commented May 9, 2026

Uh oh!

Rowlando13 commented May 9, 2026

Uh oh!

jorenham left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

AndreasBackx commented May 9, 2026 •

edited

Loading