python / python/mypy

Unexpected Overloading overlap if String Literal is used within Sequence/Iterable/Collection

Open
#15,035 6 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

bug topic-overloads
Dominant language
Python
Stars
20.6k
Forks
3.3k
PR merge metrics
PR metrics pending

Description

Bug Report

If I have a function that accepts a String Literal and Sequence of String Literal and want to overload this function for these two cases, mypy always returns:

Overloaded function signatures 1 and 2 overlap with incompatible return types [misc]

from typing import overload, Literal

@overload
def over(bar: Literal["bar"]) -> int:  # Overloaded function signatures 1 and 2 overlap with incompatible return types  [misc]
    ...

@overload
def over(bar: Sequence[Literal["foo"]]) -> str:
    ...   

def over(bar: Literal["bar"]|Sequence[Literal["foo"]]) -> str|int:
    if bar == "bar":
        return 0
    return ", ".join(bar)
    

To Reproduce
https://mypy-play.net/?mypy=latest&python=3.11&gist=d28d528c0765dc0a4a004c360a4008a4

Expected Behavior

No error, as if we would use a list instead:

@overload
def load(bar: Literal["bar"]) -> int:
    ...

@overload
def load(bar: list[Literal["foo"]]) -> str:
    ...   

def load(bar: Literal["bar"]|list[Literal["foo"]]) -> str|int:
    if bar == "bar":
        return 0
    return ", ".join(bar)

Actual Behavior
Mypy returns:

Overloaded function signatures 1 and 2 overlap with incompatible return types [misc]

Your Environment

MyPy playground....

  • Mypy version used: 1.20
  • Mypy command-line flags: none
  • Mypy configuration options from mypy.ini (and other config files): none
  • Python version used: tested with 3.10 and 3.11

Note
I am aware that a str is also a Sequence[str]. But as we using literals here, this shouldn't matter.

This is only an issue for mypy if used with overloads, it works correctly if simply used within a function

# Simple example, that if we use Sequences and Literals, mypy
# can determine stuff correctly
def foo(bar: Literal["bar"]|Sequence[Literal["foo"]]) -> None:
    return None
    
    
foo("bar")  # okay
foo(["foo"]) # okay
foo("foo") # not okay - as expected
foo(["bar"]) # not okay - as expected

Note that pyright does detect the overloads correctly (kind of).

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by running the linked mypy-play reproduction and compare the overload examples using Sequence, Iterable, Collection, and list with the final function-call checks. Trace the overload compatibility and Literal handling involved in the reported diagnostic. Done means the valid String Literal and sequence overloads no longer produce an incompatible-overlap error while the invalid calls remain rejected.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
compilers, devtools
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.