prefect

sphinx

trio

flake8

PR #28677 ecosystem summary

Analyzed head: 2c45369306.

The 27 diagnostic changes reflect stricter checking of generic bounds and constraints, improved inference after class narrowing, and changes to recovery after failed specialization. Spark, discord.py, and rotki pass unrestricted caller type variables to operations that require more specific types; the PR catches those missing guarantees. Tanjun loses three false positives because narrowed class arguments retain their intersections. The remaining return-message changes follow failed generic calls, including aiohttp's existing union-bound receiver limitation. All retained changes are expected; none blocks review.

Diagnostic changes (12 unsound-return-statement; 8 invalid-argument-type; 5 no-matching-overload; 1 invalid-return-type; 1 unused-type-ignore-comment)

1. Optional keys require both overload paths to be valid (5 no-matching-overload; 4 unsound-return-statement)

Spark forwards optional key functions to heapq.nlargest, heapq.nsmallest, and heapq.merge. The overload accepting a key works with arbitrary elements, but the key=None overload requires comparable elements. The implementation's unconstrained element variable does not establish that requirement. The PR rejects these calls instead of accepting the unchecked None path; the failed calls also produce Unknown, adding warnings where that result is returned as a precise collection type.

The two overloads below show the same distinction with a smaller bound: the None overload requires int elements, while the other overload accepts any element type. An unconstrained caller variable cannot satisfy both possibilities.

Optional overload selection (5 no-matching-overload; 4 unsound-return-statement).

from typing import Protocol, TypeVar, overload
T = TypeVar('T')

class Items(Protocol[T]):
    first: T
B = TypeVar('B', bound=int)

@overload
def select(items: Items[T], key: int) -> Items[T]:
    ...

@overload
def select(items: Items[B], key: None) -> Items[B]:
    ...

def select(items, key):
    ...

def wrapper(a: Items[T], key: int | None) -> Items[T]:
    # Merge base: no diagnostic
    # PR: [no-matching-overload] No overload of function `select` matches arguments
    # PR: [unsound-return-statement] Unsound return statement: `Unknown` is not a subtype of `Items[T@wrapper]`
    return select(a, key)

2. Caller type variables must guarantee callee bounds (3 invalid-argument-type; 3 unsound-return-statement; 1 unused-type-ignore-comment)

Spark passes hashable keys to bisect_left and sorted, which require comparable keys, and passes an ordering callback to RDD.keyBy, which requires hashable results. Hashability and comparability do not imply each other. The merge base accepted these calls by treating the caller's type variable as though it could be narrowed to satisfy the callee; the PR checks the caller's declared guarantee and rejects them. At the bisect_left call, failed overload resolution produces Unknown, which also adds a warning to each of the two return branches.

The caller below accepts arbitrary T, while locate requires a variable bounded by int. The PR rejects that missing guarantee; the return warning follows from the failed overload call.

Bounded overload and return recovery (3 invalid-argument-type; 2 unsound-return-statement).

from typing import Protocol, TypeVar, overload
T = TypeVar('T')

class Items(Protocol[T]):
    first: T
B = TypeVar('B', bound=int)

@overload
def locate(a: Items[B]) -> int:
    ...

@overload
def locate(a: Items[B], hi: int) -> int:
    ...

def locate(a, hi=None):
    ...

def wrapper(bounds: Items[T]) -> int:
    # Merge base: no diagnostic
    # PR: [invalid-argument-type] Argument to function `locate` is incorrect: Argument type `T@wrapper` does not satisfy upper bound `int` of type variable `B`
    # PR: [unsound-return-statement] Unsound return statement: `Unknown` is not a subtype of `int`
    return locate(bounds)

Discord's sequence proxy permits arbitrary element types but sorts them without a key. The merge base incorrectly accepted an unrestricted caller type variable where sorting requires comparable values. The PR rejects that specialization, making the existing blanket ignore necessary and producing an Unknown result that triggers a return warning. Restricting the element type to comparable values, or providing an appropriately typed key, satisfies the sorting requirement.

The reduced example expresses the sorting function's relevant bound and the collection's structural element relationship locally. Returning a single element instead of a list preserves the same failed specialization and return-warning behavior.

Ignored bound violation followed by an unsound return (1 unsound-return-statement; 1 unused-type-ignore-comment).

from typing import Protocol, TypeVar

class SupportsLT(Protocol):
    def __lt__(self, other: object, /) -> bool: ...

T = TypeVar("T", covariant=True)

class Source(Protocol[T]):
    def get(self) -> T: ...

C = TypeVar("C", bound="SupportsLT")

def ordered_values(items: Source[C]) -> C:
    raise NotImplementedError

def copied(items: Source[T]) -> T:
    # Merge base: [unused-type-ignore-comment] Unused blanket `type: ignore` directive
    # PR: no diagnostic
    result = ordered_values(items)  # type: ignore
    # Merge base: no diagnostic
    # PR: [unsound-return-statement] Unsound return statement: `Unknown` is not a subtype of `T@copied`
    return result

3. Failed receiver specializations discard partial results (4 unsound-return-statement)

These calls already violate a receiver's type-variable bound: Spark's methods require hashable keys, but their callers accept unrestricted key types. The PR no longer carries a partially inferred key type through the failed specialization. The existing argument errors remain; recovery with Unknown adds one return warning and changes three existing return warnings. These are expected consequences of rejecting the invalid specializations, rather than newly rejected valid calls.

Chained and single receiver calls (3 unsound-return-statement).

The two RDD chains previously returned RDD[T | Unknown]; they now return RDD[Unknown]. The clustering call previously kept its caller's key type despite the bound failure; losing that unsupported specialization adds its return warning. This example uses an int bound to isolate the same requirement. Both versions also report the unchanged invalid-argument-type error at each call.

from typing import Generic, TypeVar
T = TypeVar('T')
T_co = TypeVar('T_co', covariant=True)
K = TypeVar('K', bound=int)

class Batch(Generic[T_co]):

    def only_ints(self: 'Batch[K]') -> 'Batch[K]':
        raise NotImplementedError

    def checked_twice(self: 'Batch[T]') -> 'Batch[T]':
        # Merge base: [unsound-return-statement] "Unsound return statement: `Batch[T@checked_twice | Unknown]` is not a subtype of `Batch[T@checked_twice]`"
        # PR: [unsound-return-statement] "Unsound return statement: `Batch[Unknown]` is not a subtype of `Batch[T@checked_twice]`"
        return self.only_ints().only_ints()

def checked(batch: "Batch[T]") -> "Batch[T]":
    # Merge base: no unsound-return-statement warning
    # PR: [unsound-return-statement] "Unsound return statement: `Batch[Unknown]` is not a subtype of `Batch[T@checked]`"
    return batch.only_ints()

A result that was already partly unknown (1 unsound-return-statement).

In the regression model, the callback's result was already unknown because the annotated model type has no predict method. The PR additionally discards the unsupported key specialization: DStream[tuple[K, Unknown]] becomes DStream[tuple[Unknown, Unknown]]. The invalid receiver and missing attribute errors are unchanged in this reduced example.

from typing import Generic, TypeVar
T_co = TypeVar('T_co', covariant=True)
K = TypeVar('K')
BoundK = TypeVar('BoundK', bound=int)
U = TypeVar('U')

class Batch(Generic[T_co]):

    def with_value(self: 'Batch[tuple[BoundK, object]]', f: U) -> 'Batch[tuple[BoundK, U]]':
        raise NotImplementedError

def unchecked(model: object, batch: 'Batch[tuple[K, object]]') -> 'Batch[tuple[K, float]]':
    # Merge base: [unsound-return-statement] "Unsound return statement: `Batch[tuple[K@unchecked, Unknown]]` is not a subtype of `Batch[tuple[K@unchecked, float]]`"
    # PR: [unsound-return-statement] "Unsound return statement: `Batch[tuple[Unknown, Unknown]]` is not a subtype of `Batch[tuple[K@unchecked, float]]`"
    return batch.with_value(model.predict)

4. Constrained callees require guarantees from their generic callers (2 invalid-argument-type; 1 unsound-return-statement)

Rotki forwards a collection of addresses and an address lookup callback from a class whose address type variable is unconstrained to a helper that permits only four specific address types. The merge base accepts this call, although the caller's annotation does not guarantee any permitted address type. The PR rejects both arguments. Recovery replaces the inferred address type within the result with Unknown, which also produces the return warning. These are expected diagnostics for the missing constraint in the caller's annotation.

The reduced example preserves the collection's readable element type and the callback's accepted argument type as two protocols. A may be any type, so selecting C = A is not valid for every caller of run.

Caller and callee constraints (2 invalid-argument-type; 1 unsound-return-statement).

from typing import Protocol

class Source[T](Protocol):
    def value(self) -> T: ...

class Consumer[T](Protocol):
    def __call__(self, address: T) -> None: ...

def run[A](source: Source[A], consumer: Consumer[A]) -> A:
    # Merge base: no diagnostic
    # PR: [unsound-return-statement] Unsound return statement: `Unknown` is not a subtype of `A@run`
    return decode(
        # Merge base: no diagnostic
        # PR: [invalid-argument-type] Argument to function `decode` is incorrect: Argument type `A@run` does not satisfy constraints (`int`, `str`) of type variable `C`
        source,
        # Merge base: no diagnostic
        # PR: [invalid-argument-type] Argument to function `decode` is incorrect: Argument type `A@run` does not satisfy constraints (`int`, `str`) of type variable `C`
        consumer,
    )

def decode[C: (int, str)](source: Source[C], consumer: Consumer[C]) -> C:
    raise NotImplementedError

5. Class narrowing survives generic inference (3 invalid-argument-type)

Tanjun checks that an enum class subclasses float, int, or str before passing its members to a choice constructor constrained to those types. The merge base loses that narrowing while specializing the generic __members__ property: the int branch produces a mapping of E | int instead of E & int. The PR preserves the intersection, so all three branches satisfy the choice constraint and the false positives disappear.

The reduced example replaces enum member lookup with a generic function accepting a class. After issubclass, member(enum_type) has type T | int on the merge base and T & int on the PR. The same narrowing behavior accounts for the original float and str branches.

Existing ty issues: ty#3557

A narrowed class passed through a generic helper (3 invalid-argument-type).

from typing import TypeVar

T = TypeVar("T")

def member(cls: type[T]) -> T:
    raise NotImplementedError

C = TypeVar('C', int, str)

def choices_for(enum_type: type[T]) -> None:
    if issubclass(enum_type, int):
        # Merge base: [invalid-argument-type] Argument to function `accept_choice` is incorrect: Argument type `T@choices_for | int` does not satisfy constraints (`int`, `str`) of type variable `C`
        # PR: no diagnostic
        accept_choice(member(enum_type))


def accept_choice(value: C) -> None: ...

6. Recovery after an invalid union-bounded method call (1 invalid-return-type)

Aiohttp awaits __aenter__ on a type variable bounded by two response classes. Both revisions already report invalid receiver arguments because of ty's existing limitation when calling methods through a type variable with a union bound. The return diagnostic now contains ClientResponse | Unknown instead of ClientResponse | _RetType_co: the failed generic receiver specialization no longer contributes the outer type variable to the awaited result. This changes recovery after an existing error without adding a diagnostic or fixing the receiver limitation.

Existing ty issues: ty#2585

Awaited result after a failed generic receiver specialization (1 invalid-return-type).

The websocket method's bounded S expresses the relevant behavior of its original Self annotation.

from typing import TypeVar

class Response:
    async def __aenter__(self) -> "Response":
        return self

S = TypeVar("S", bound="WebSocket")

class WebSocket:
    async def __aenter__(self: S) -> S:
        return self

T = TypeVar("T", bound="Response | WebSocket")

async def enter(response: T) -> T:
    # Merge base: [invalid-return-type] Return type does not match returned value: expected `T@enter`, found `Response | T@enter`
    # PR: [invalid-return-type] Return type does not match returned value: expected `T@enter`, found `Response | Unknown`
    return await response.__aenter__()

Reproduction

• Detailed report: ecosystem-analyzer report
• Actions run: run 35934561574, attempt 1
• Ruff comparison: f7e27e81a0b461eded62452aeb270747db4eb139 to 2af9c314d3cfe7f8dcb5039f2356d1b2220b2372
• ecosystem-analyzer: a31ef389f3cc304b59623df7fe4b068419a323a4
• mypy-primer: 3058720299b812c393ad926bcca96eede20fa683
• Dependency cutoff: 2026-09-23T23:38:00Z
• Project Python interpreter: 3.11 for all five projects. Effective analysis targets from project configuration: Tanjun 3.11; aiohttp 3.10; discord.py 3.8; rotki 3.14; Spark 3.11.
• Python target platform: linux for all five projects.
• Execution environment: Linux x86_64 containers with Python 3.11.16 and uv 0.12.11, using the exact CI profiling binaries. The containers use Debian 13 under Docker emulation on macOS; CI used Ubuntu 24.04 x86_64. Checker settings: TY_UV=scripts, UV_LOCKED=1, RUST_BACKTRACE=1, UV_NO_BUILD=1, UV_NO_BINARY=0, and the captured PR configuration installed as user-level configuration.
• Checker deadline: 180 seconds, matching the analyzer's default dev profile with prebuilt profiling binaries.
• Project analysis mode: Tanjun and aiohttp non-strict; discord.py, rotki, and Spark strict.
• Comparison method: run each pinned project's mypy-primer command against both binaries with its Linux virtualenv, original project configuration, and --output-format concise. Strict projects additionally use --config analysis.strict-equality-semantics=true --config analysis.strict-generic-narrowing=true. Isolated examples preserve each project's effective Python target and strictness settings.