Prefer unions over overloads

[twoertwein]

overloads are sometimes used in places where a union would be a "better" annotation.

Here is an example from the work-in-progress pandas-stubs:

    @overload
    def agg(self, arg: str, *args, **kwargs) -> DataFrame: ...
    @overload
    def agg(self, arg: Dict, *args, **kwargs) -> DataFrame: ...
    @overload
    def agg(self, arg: FuncType, *args, **kwargs) -> DataFrame: ...

which could be re-written as

    def agg(self, arg: str | Dict | FuncType, *args, **kwargs) -> DataFrame: ...

Not only is this much shorter but it also covers the case where the first argument is a union type (not covered by the overloads).

[AlexWaygood]

Hmm, it's a nice idea, but it might be tricky to implement. You'd probably need to "collect" FunctionDef nodes decorated with @overload while visiting the AST, and store information about whether they're inside sys.version_info or sys.platform branches. Then, after the tree has been visited, you could go through the collected overloads for each function by a certain name within each sys.version_info/sys.platform branch, and determine whether any overloads are redundant.

So it might be possible, but also might be a little complicated. Are you interested in working on it?

[twoertwein]

Are you interested in working on it?

I'm sorry, that would be too complicated for me.

[AlexWaygood]

You've already nerd-sniped me into thinking through a possible design, so I'm not saying "no" ;)

[twoertwein]

unrelated: some of the flake8-pyi rules are also applicable to py files, for example, this overload-union case. It would be great if flake8-pyi can work on pyi files and on py files with a reduced subset of checks.

[AlexWaygood]

unrelated: some of the flake8-pyi rules are also applicable to py files, for example, this overload-union case. It would be great if flake8-pyi can work on pyi files and on py files with a reduced subset of checks.

Yeah, we're aware, this has come up a few times:

• Callables whose return value is ignored #237 (comment)
• Can you check .py files too? #118
• Port typeshed's tests/check_new_syntax.py here #80 (comment)

The core dev team for this plugin is the same as the core dev team for typeshed, though, so this always ends up being somewhat low priority for us to fix :) PRs welcome!

[AlexWaygood]

I had a look at implementing this, but I think it would just be unreasonably complicated for us to do here, sorry. The machinery we'd have to build to properly analyse overloaded functions (and to distinguish between different overloads inside different sys.version_info and sys.platform checks) feels like it would excessively duplicate work that type checkers already do when analysing a file.

Mypy or pyright might be interested -- you could always try filing a feature request with one of them.