`inconsistent-overload` false positives with `Unpack[TypedDict]`

[dangotbanned]

Describe the Bug

pyrefly reports inconsistent-overload for every overload.

But pyright, mypy and ty ¹ accept them:

Show code

from typing import *


class A: ...
class B: ...
class C(Protocol):
    def member(self) -> str: ...

T = TypeVar("T")

class ExcludeC(TypedDict, total=False):
    pass_through: bool
    only_a: bool
    only_c: Literal[False]
    include_c: Literal[False] | None

class OnlyC(TypedDict, total=False):
    pass_through: bool
    only_a: bool
    only_c: Required[Literal[True]]
    include_c: bool | None

class IncludeC(TypedDict, total=False):
    pass_through: bool
    only_a: bool
    only_c: Literal[False]
    include_c: Required[Literal[True]]

class IncludeB(TypedDict, total=False):
    pass_through: bool
    only_a: Literal[False]
    only_c: Literal[False]
    include_c: bool | None

class IncludeABC(TypedDict, total=False):
    pass_through: bool
    only_a: Literal[False]
    only_c: Literal[False]
    include_c: Required[Literal[True]]

class PassThrough(TypedDict, total=False):
    pass_through: Required[Literal[True]]
    only_a: bool
    only_c: bool
    include_c: bool | None


@overload
def func(obj: A, **kwds: Unpack[ExcludeC]) -> A: ...
@overload
def func(obj: C, **kwds: Unpack[OnlyC]) -> C: ...
@overload
def func(obj: C, **kwds: Unpack[IncludeC]) -> C: ...
@overload
def func(obj: B, **kwds: Unpack[IncludeB]) -> B: ...
@overload
def func(obj: A | C, **kwds: Unpack[IncludeC]) -> A | C: ...
@overload
def func(obj: A | B | C, **kwds: Unpack[IncludeABC]) -> A | B | C: ...
@overload
def func(obj: T, **kwds: Unpack[PassThrough]) -> T: ...
def func(
    obj: A | B | C | T,
    *,
    pass_through: bool = False,
    only_a: bool = False,
    only_c: bool = False,
    include_c: bool | None = None,
) -> A | B | C | T:
    raise NotImplementedError

That example is a minimized version of narwhals.from_native:

• src/narwhals/translate.py#L122-L181
• src/narwhals/_translate.py#L192-L323

If there is an issue, the diagnostic should point towards what is missing.
The current output is 1x of these per overload 😳:

Implementation signature

(obj: A | B | C | T, *, pass_through: bool = False, only_a: bool = False, only_c: bool = False, include_c: bool | None = None) -> A | B | C | T

does not accept all arguments that overload signature

(obj: A, **kwds: Unpack[ExcludeC]) -> A accepts [inconsistent-overload]

Sandbox Link

https://pyrefly.org/sandbox/?project=N4IgZglgNgpgziAXKOBDAdgEwEYHsAeAdAA4CeS4ATrgLYAEALqcROgOZ0Q3G6UN0AqADroRIgMZRUcOHQCCiOoWVjR6SdNkAhRcsKqJUmXQDCACgAK1BrnG4oASkQi6ruphhg6NGDWwxKMzgYKDAHOgBaAD46OAZKXRU1EQAVOgBeOhTmGAA1VEChEBSihwN1I1kAUXxJAFcPc2ziGEwAEQhxBgAaRlwGVCh0gDFB4KcXN2JNAH0GAAtqOrZ5xTx7SddcdChSGdQ13A30Nzpt3ZnxRQAZCAYAwYBtUahggF1NzgqGmEubu4eUGeYxgbzoAB86AA5bYwcoaYwAeR2pCaOXanR6fQGQxe42cJymswWSxWh2Op3OewOdHWUE%2BVL%2BdAASjAAI51CCUVqPW73ShPFKUOqgj6E1yseoeJl0iHQ2Hwyp0ACS30aZmarQ6XV6NhxIxBE3FdGmMjmi1wy1WtKO9ONjJpdIZKKZfMBwNeoM%2BkqgPyZrI5XJ5boFQKFIreYtUCNkqqlMC0GvR2qxesGBs9RtOprg5tJ1qd9pdNJDTzxXqLFyudFLQPLYtOPr91dlkJh6DhyQqmhVapgci0aJaGJ12PT5azRLNJMtZJtFLcDv%2B-LLIIbi5d1drHve3r7-vZnO5mF5ANDj3DosVPYsmhSFqtSeHKd1-XHhoJ2eJD7nAaPwbPQVhSvStqXJO1KU3cC93jGVbTldtO1UAABXAADcAigXBUEwEQPC8MA6nUMxcGwAArRQ5F6AQBAAawAd0wOBFAAVXQaZxFox4anjEw3nCaJ5ESfR0FQjDKCwnC8M8OhCOI0iKNMai6MY5i6DYjiuORXY%2BIEmITGEkQxMw7DcKwGS5PEEjyMUExlIYpjWPY1BOMeONfUafjIn0wzRPQkypPMgiiKshTFC0ezVKczS3L7LQvMEnQlCSYyJNM6Tgvkmz5DlOzBBUxz1Oc1z3J%2BXTvJyyEDOSkTUsksz8NkkLrMUuQ5S0XLIsKjSXK40qPAHcrBLayEOqq3y6vSoKmqyxSUi6tSetc28ZHvfMEpiFJfMayyzAZbKRroMbTDlebPgEbpPhzPNZwLeDMnLS7QP2cCMjoR7nSrV6HpBJ7G33Ft4LbWE3sQp69Mqo7ctOz83AFCBgnlBhlW4WAfHQe5MCqShqEoEQQG6EAyG5MBdkIGwaCgCgAGI6AsUgSd2WIMBwAg6DsdBIDYOoBQYCBthE2mAGUYBgOh5gYBhiGYgB6GXic8MneDYGWYHQGXMFsOAZY5rmedQPnthl2TeDoVA0NQaBUGwWB2e2PXef5k5cGIQ30DgESyAWbYInEuAnbeooAGZCAARgAJiKERHgCXG4DFIiuB4PhWgiTAgy6CAMLegByCA2HQXgYBzkRC4YCJuUDY8IlomBSAiFzxHgWRMhz%2BiCnQEv0BAABfQmXL5jDhmgGAKDQLA8CIMhe6AA

(Only applicable for extension issues) IDE Information

No response

Footnotes

1. I've included ty for completeness, but I think it is missing support for at least 1 feature here ↩

[yangdanny97]

This one is a bit weird, I think strictly speaking this is not safe and Pyrefly is correct to flag it. TypedDict subtyping allows for extra keys, so it's easy to smuggle an extra key into the function and cause it to crash at runtime

For example:

class WithExtraKeys(TypedDict, total=False):
    pass_through: Required[Literal[True]]
    only_a: bool
    only_c: bool
    include_c: bool | None
    aaaaaa: int
x: WithExtraKeys = {"aaaaaa": True, "pass_through": True}
y: PassThrough = x
func(object(), **y) # runtime crash: func() got an unexpected keyword argument 'aaaaaa'

The unpacked typeddict kwargs is approximately equivalent to keyword args for each of the typeddict's keys, plus **kwargs: object

I'm not sure why mypy, pyright, and ty do not flag this for overloads, but do flag it for other types of subtyping/assignability. Perhaps this is a FN on their end & narwhals code can be adjusted.

What do you think?

[yangdanny97]

cc @MarcoGorelli for input

[dangotbanned]

@yangdanny97 would using closed=True change the behavior for pyrefly (or any other type checkers)?

• https://typing.python.org/en/latest/spec/typeddict.html#openness

We don't need the TypedDicts at runtime, and can use the typing_extensions backport if needed

[dangotbanned]

TypedDict subtyping allows for extra keys, so it's easy to smuggle an extra key into the function and cause it to crash at runtime

We do have coverage for this, with mypy and pyright matching the runtime:

• https://github.com/narwhals-dev/narwhals/blob/1d75ff05c814ea316e36d01673d27badb29c8e2b/tests/translate/from_native_test.py#L478-L485

Edit: although maybe that would look different if we had some correct args too 😅

[yangdanny97]

I think it should work with a closed typeddict based on this comment documenting the unsoundness of TypedDicts, but unfortunately Pyrefly still doesn't like that. Should be an easy fix tho

[dangotbanned]

Thanks @yangdanny97, I'll open an issue later in narwhals to track changing these defs to use closed=True.

Note to self: still need to see how this plays with other type checkers and whether there are runtime issues to solve with narwhals._typing compat.py (e.g. mkdocstrings).

---

@dangotbanned
If there is an issue, the diagnostic should point towards what is missing.

I believe there's room for improvement here, considering

@yangdanny97
The unpacked typeddict kwargs is approximately equivalent to keyword args for each of the typeddict's keys, plus **kwargs: object

I may have been able to get there (eventually) if the overload signatures were displayed in their unpacked form.
But if the diagnostic mentioned openness; I definitely would've understood sooner 😄

[dangotbanned]

Another thing you might consider is what version of python is being targeted.

Technically I shouldn't have the option of closed in (3.12-3.14), so the unsoundness may be a pragmatic choice by other type checkers.

I know that mypy/pyright do this for other features like @dataclass_transform interacting with __replace__ only after 3.13. That could explain this issue?

[yangdanny97]

Hmm, I thought that closed was available via typing_extensions for earlier versions. Typeddict may be different from dataclasses here because they can't be instantiated and mostly exist for the type checker's benefit.

As part of the fix, I've also updated the error message to say: "Callable without **kwargs cannot be assigned to callable with **kwargs: Unpack[{td}], because {td} is not closed and may have additional unknown keys"

[dangotbanned]

Hmm, I thought that closed was available via typing_extensions for earlier versions.

Oh it is, but these TypedDicts are declared at runtime currently - and we don't have a dependency on typing_extensions.

But that's something for me to tackle 😄