Checking Sphinx with Pyrefly

[stroxler]

We noticed a run of bug reports from @AA-Turner on Pyrefly from testing on Sphinx, thanks for these!

Would you be interested in us focusing effort toward making Pyrefly usable on Sphinx?

If so, filing and fixing the bugs (as well as discussing situations where Pyrefly currently objects to the existing patterns) is something we'd be happy to take on, and we could use this issue both to link the Pyrefly bug reports and track progress.

Thanks again for the bug reports so far! At this stage I think the top overall issue is improving overload support, which we hope to re-focus on in the next week or two.

[AA-Turner]

Thanks @stroxler, would love to help with this!

cc frequent typing contributors @danieleades @adamtheturtle

Also cross-referencing the pyrefly quickstart for Sphinx I wrote up in facebook/pyrefly#285 (comment). Edit: I've opened #13579 to add the pyrefly.toml configuration file.

A

[danieleades]

Thanks @stroxler, would love to help with this!

cc frequent typing contributors @danieleades @adamtheturtle

Also cross-referencing the pyrefly quickstart for Sphinx I wrote up in facebook/pyrefly#285 (comment). Edit: I've opened #13579 to add the pyrefly.toml configuration file.

A

With regard to the quickstart, this (or something like it) should work too:

uv run --with pyrefly pyrefly check

Which translates to "run pyrefly check in my environment with 'pyrefly' added"

[stroxler]

Awesome, thanks!

I have a backlog of issues to work on coming out of PyCon, but my hope is to soon start focusing on a couple of key projects to drive Pyrefly bugfixes and features. I intend to make Sphinx one of them - it seems like a great codebase and for the most part less prone to edge cases than (for example) tools in the Pytorch ecosystem.

I expect to need some discussion here when I run into cases we aren't sure about supporting.

---

Just as an example of where I expect to need some back-and-forth with you, one thing I noticed right off the bat was the use of a with statement to set attributes:

        with (
            open(output_text, 'w', encoding='utf-8') as self.txt_outfile,
            open(output_json, 'w', encoding='utf-8') as self.json_outfile,
        ):
            ... code calls methods, which can then implicitly get context managers via `self` ...

in linkcheck.py in the CheckExternalLinksBuilder.finish method. That's not something we expected to support; I can see why it would be useful but it's the sort of thing that I'd want to double-check with you before adding. I think there's an argument that it's better to pass context explicitly