Widening generic types when calling methods in context.

[randolf-scholz]

I am wondering if there is a general recipe to annotate methods that return a new instance, so that it allows widening the type based on the outer context.

Question: Is it possible, in the current type system as of python 3.14, to annotate this method:

def join(dict_a, dict_b):
     return dict_a | dict_b

such that the following test passes without type errors

from typing import assert_type, reveal_type

def test(left: dict[int, int], right: dict[str, int]) -> None:
    # without outer context, the type is precise
    reveal_type(join(left, right))  # dict[int | str, int]
    assert_type(join(left, right), dict[int | str, int])
    # outer context allows widening
    x: dict[str | int, int] = join(left, right)
    y: dict[str | int | list, int] = join(left, right)
    z: dict[object, int] = join(left, right)

Context

Consider the following example:

x: dict[int, int] = {0:0, 1:0}
y: dict[str, int] = {"a":0, "b":0}
                                   # mypy | pyright | ty | pyrefly | zuban
a: dict[object, int] = x | y       # ❌️   | ❌️      | ❌️ | ❌️      | ❌️
b: dict[object, int] = {**x, **y}  # ❌️   | ✅️      | ✅️ | ✅️      | ✅️️

According to PEP 584 – Add Union Operators To dict, x | y is essentially equivalent to {**x, **y}, so the first surprise here is that the type checkers except for mypy accept one but not the other. This can be due to special casing of the literal constructor.

However, it raises the question of how to communicate to the type checker when a method returns a new instance, and widening the type is OK.

My Attempt

The best I could come up with was adding a "slack-variable" to the output, but it doesn't work. I hoped that a type checker would infer K :> object if necessary, and so allow y: dict[object, int] = join(left, right), but none of the type checkers I tested allows this. Only ty seems to partially accept this, but requires getting rid of the default K=Never and consequently emits dict[Unknown | int | str, Unknown | int on the reveal_type

from typing import Never, assert_type, reveal_type

def join[K1, V1, K2, V2, K=Never, V=Never](
    left: dict[K1, V1],
    right: dict[K2, V2],
) -> dict[K | K1 | K2, V | V1 | V2]:
    return dict(left | right)

def test(left: dict[int, int], right: dict[str, int]) -> None:
    # without outer context, the type is precise
    reveal_type(join(left, right))  # dict[int | str, int]
    assert_type(join(left, right), dict[int | str, int])
    # outer context allows widening
    x: dict[str | int, int] = join(left, right)
    y: dict[str | int | list, int] = join(left, right)
    z: dict[object, int] = join(left, right)

My current thinking is that this possibly requires HKT (#548), or more specifically lower bounding a TypeVar by another TypeVar, so that for example the join method could be typed as:

def join[K1, V1, K2, V2, K :> K1|K2, V :> V1|V2](
    left: dict[K1, V1],
    right: dict[K2, V2]
) -> dict[K, V]: ...

[cleonaia]

I think the key issue is that Python's current typing system doesn't provide a general way to infer a wider return type from the expected type at the call site.

For this example, I'd keep join()'s return type precise and widen it explicitly when needed:

from typing import cast

y = cast(dict[str | int | list, int], join(left, right))

This works as a workaround, but cast doesn't perform any runtime validation, so the caller must ensure the result is compatible with the target type.

Ideally, the type system would allow the return type's type variables to be inferred from both the arguments and the expected return type. That would preserve the precise dict[int | str, int] result when no context is provided, while allowing a wider type when the surrounding context requires it.

[randolf-scholz]

Of course one can solve this by adding cast or # type: ignore at each and every call-site where the problem occurs, but my question was whether this problem can be solved at the function definition.

The real motivation for this problem is when you have code like fn(dict1 | dict2) or fn(list1 + list2) that get rejected despite being formally correct.

I still think lower bounds are the correct solution #674

But slack variables could indeed solve that problem with todays typing spec, the only issue is that no type-checker really supports them as far as I can tell.

• ENH: Support slack variables (lower bound emulation) facebook/pyrefly#2220
• Support usage of slack variables (lower bound emulation) microsoft/pyright#11245
• ENH: Support slack variables (lower bound emulation) astral-sh/ty#2615
• ENH: Support slack variables (lower bound emulation) mypy#20648

[cleonaia]

I think the issue is partly due to dict being invariant. With left: dict[K1, V1], the argument types constrain the type variables, so the expected return type can't necessarily widen them.

One possible workaround is to accept a covariant protocol instead, since we're only reading from the inputs:

from collections.abc import Iterable
from itertools import chain
from typing import Protocol

class SupportsItems[K, V](Protocol):
    def items(self) -> Iterable[tuple[K, V]]: ...

def join[K, V](
    left: SupportsItems[K, V],
    right: SupportsItems[K, V],
) -> dict[K, V]:
    return dict(chain(left.items(), right.items()))

This may work for x, y, and z in your example. Pyright should infer dict[int | str, int] without an expected type, although mypy may infer object instead.

It doesn't solve the | and + cases in typeshed itself, so I think lower bounds (#674) or proper slack-variable support would still be needed for a general solution.