// A2.5 · ~30 min · Advanced
After this lesson you can give a function one signature per argument type with @overload, predict how mypy narrows a union after isinstance, None checks and match, and write a TypeIs predicate that narrows both branches.
You will be able to
Warm-up · Activity 1 of 7
def find(items: list[str], name: str) -> int | None:
return items.index(name) if name in items else None
print(find(["a"], "a") + 1)Predict · Activity 2 of 7
def double(value: int | str) -> int | str:
return value * 2
print(double(3) + 1)Practice · Activity 3 of 7
@____
def double(value: int) -> int: ...
@overload
def double(value: str) -> str: ...
def double(value: int | str) -> int | str:
return value * 2Practice · Activity 4 of 7
def f(v: int | str | None) -> None:
if isinstance(v, int):
pass
elif v is None:
pass
else:
reveal_type(v)Practice · Activity 5 of 7
Brain teaser · Activity 6 of 7
from typing import TypeIs
def is_short(value: object) -> TypeIs[str]:
return isinstance(value, str) and len(value) < 5
def show(value: str | int) -> None:
if is_short(value):
print("short text", value)
else:
reveal_type(value)Apply · Activity 7 of 7
Check your work against this list
Read the worked example, then write the exercises. Your code runs in your browser or on your computer and is never uploaded.
Worked example
double has two overloads, so double(value) + 1 type-checks once value is known to be an int. is_pair is a TypeIs predicate. describe narrows its four-way union step by step: is None, then is_pair, then isinstance, and what is left must be a str. The program passes mypy --strict.
main.py
from typing import TypeIs, get_overloads, overload
@overload
def double(value: int) -> int: ...
@overload
def double(value: str) -> str: ...
def double(value: int | str) -> int | str:
return value * 2
def is_pair(value: object) -> TypeIs[tuple[int, int]]:
return isinstance(value, tuple) and len(value) == 2 and all(isinstance(x, int) for x in value)
def describe(value: int | str | tuple[int, int] | None) -> str:
if value is None:
return "nothing"
if is_pair(value):
left, right = value
return f"pair summing to {left + right}"
if isinstance(value, int):
return f"number {double(value) + 1}"
return f"text {double(value).upper()}"
for value in (20, "ab", (3, 4), None):
print(describe(value))
print(len(get_overloads(double)))
Run it with
python main.pyOutput
number 41
text ABAB
pair summing to 7
nothing
2Tab indents and Shift+Tab outdents. To leave the editor with the keyboard, press Esc, then Tab.
The first run downloads Python for your browser (up to 6.5 MB) and keeps it cached. Your code stays on your device.
Exercise 1 of 2
to_int turns a str into an int and passes None through. With its union signature, mypy rejects total(), which only ever passes strings. Add two @overload stubs, str to int and None to None, above the implementation, so that total() type-checks. Keep the implementation as it is.
Tab indents and Shift+Tab outdents. To leave the editor with the keyboard, press Esc, then Tab.
The first run downloads Python for your browser (up to 6.5 MB) and keeps it cached. Your code stays on your device.
Put @overload and a def with the same name above the implementation, twice. The stub bodies are just ...
Write None, not NoneType, in the second stub: def to_int(value: None) -> None: ...
The implementation keeps its union signature and no decorator; it must be the last definition.
One way to solve it. Yours can look different and still pass the checks.
from typing import overload
@overload
def to_int(value: str) -> int: ...
@overload
def to_int(value: None) -> None: ...
def to_int(value: str | None) -> int | None:
if value is None:
return None
return int(value)
def total(texts: list[str]) -> int:
return sum(to_int(text) for text in texts)
Install Python 3.14 or newer. Save these files in one folder, open a terminal in that folder, and run the commands below.
main.py
from typing import overload
def to_int(value: str | None) -> int | None:
if value is None:
return None
return int(value)
def total(texts: list[str]) -> int:
return sum(to_int(text) for text in texts)
test_main.py
from typing import get_overloads, get_type_hints
from main import to_int, total
def test_overloads():
"""to_int has two overloads above the implementation: str to int and None to None"""
stubs = [stub for stub in get_overloads(to_int) if stub.__code__.co_firstlineno < to_int.__code__.co_firstlineno]
got = [(get_type_hints(stub)["value"], get_type_hints(stub)["return"]) for stub in stubs]
assert sorted(got, key=repr) == sorted([(str, int), (type(None), type(None))], key=repr), f"the overloads are {got!r}"
def test_values():
"""to_int("42") is 42 and to_int(None) is None"""
got = to_int("42"), to_int(None)
assert got == (42, None), f"to_int gave {got!r}"
def test_total():
"""total adds the numbers"""
got = total(["1", "2", "39"])
assert got == 42, f"total returned {got!r}"
On macOS and Linux, type python3 wherever these commands say python, as in the first lesson.
Run the program:
python main.pyRun the checks (needs learnrun.py in the same folder):
python learnrun.py testExercise 2 of 2
A config value is a str, an int or a list[str]. Change is_text_list to return TypeIs[list[str]] instead of TypeGuard, so both branches narrow. Then finish render: a list is joined with ", ", an int is formatted with thousands separators (f"{value:,}"), and a str is returned as it is, with no str() call: mypy should know it is a str.
Tab indents and Shift+Tab outdents. To leave the editor with the keyboard, press Esc, then Tab.
The first run downloads Python for your browser (up to 6.5 MB) and keeps it cached. Your code stays on your device.
Only the return annotation of is_text_list changes: -> TypeIs[list[str]].
After the list case, add if isinstance(value, int): return f"{value:,}".
With TypeGuard, return value at the end would be an error, because mypy would still see str | int | list[str]. With TypeIs, only str is left.
One way to solve it. Yours can look different and still pass the checks.
from typing import TypeGuard, TypeIs
type Value = str | int | list[str]
def is_text_list(value: Value) -> TypeIs[list[str]]:
return isinstance(value, list)
def render(value: Value) -> str:
if is_text_list(value):
return ", ".join(value)
if isinstance(value, int):
return f"{value:,}"
return value
Install Python 3.14 or newer. Save these files in one folder, open a terminal in that folder, and run the commands below.
main.py
from typing import TypeGuard, TypeIs
type Value = str | int | list[str]
def is_text_list(value: Value) -> TypeGuard[list[str]]:
return isinstance(value, list)
def render(value: Value) -> str:
if is_text_list(value):
return ", ".join(value)
return str(value)
test_main.py
from typing import TypeIs, get_origin, get_type_hints
from main import is_text_list, render
def test_typeis():
"""is_text_list is annotated to return TypeIs[...]"""
got = get_type_hints(is_text_list)["return"]
assert get_origin(got) is TypeIs, f"is_text_list returns {got!r}, expected TypeIs[list[str]]"
def test_list():
"""A list is joined with a comma and a space"""
got = render(["a", "b"])
assert got == "a, b", f"render(['a', 'b']) returned {got!r}"
def test_int():
"""An int gets thousands separators"""
got = render(1234567)
assert got == "1,234,567", f"render(1234567) returned {got!r}"
def test_str():
"""A str comes back unchanged"""
got = render("debug")
assert got == "debug", f"render('debug') returned {got!r}"
On macOS and Linux, type python3 wherever these commands say python, as in the first lesson.
Run the program:
python main.pyRun the checks (needs learnrun.py in the same folder):
python learnrun.py testfrom typing import overload
@overload
def double(value: int) -> int: ...
@overload
def double(value: str) -> str: ...
print(double(3))
What Python prints
NotImplementedError: You should not call an overloaded function. A series of @overload-decorated functions outside a stub module should always be followed by an implementation that is not @overload-ed.Why, and the fix
The stubs are only signatures. Add one definition without @overload, after the stubs, that handles every case: def double(value: int | str) -> int | str: return value * 2. mypy reports the missing implementation too: An overloaded function outside a stub file must have an implementation [no-overload-impl].
from typing import overload
@overload
def to_int(value: str) -> int: ...
@overload
def to_int(value: None) -> None: ...
def to_int(value: str | None) -> int | None:
return int(value)
print(to_int(None))
What Python prints
TypeError: int() argument must be a string, a bytes-like object or a real number, not 'NoneType'Why, and the fix
The overloads promise that to_int(None) returns None, but the implementation never checks. Narrow first: if value is None: return None, then return int(value). mypy catches this: it reports the return line with an [arg-type] error, because int() does not accept str | None.
from typing import TypeIs
def is_short(value: object) -> TypeIs[str]:
return isinstance(value, str) and len(value) < 5
def show(value: str | int) -> None:
if is_short(value):
print("short text", value)
else:
print(value + 1)
show(41)
show("a longer text")
What Python prints
TypeError: can only concatenate str (not "int") to strWhy, and the fix
mypy accepts value + 1, because TypeIs[str] says a False result means "not a str". is_short also returns False for long strings, so that promise is broken. Keep the predicate exact (return isinstance(value, str)) and test the length separately, or use a plain bool return, which narrows nothing.
Python in the browser: Pyodide 314.0.7, MPL-2.0. Licence and source
5 questions, no hints. Score 80% or more to complete the lesson.
Finish every activity above to unlock the exit ticket.