Article illustration 1

For years, Python developers wrestled with a frustrating class of bugs: functions whose return types change based on input values. Consider the notorious open() function, which returns IO[bytes] for 'rb' mode but IO[str] for 'r' mode. This forces cumbersome runtime checks and type guards—until now.

The Union Type Trap

from typing import Union

def open_file(filename: str, mode: str) -> Union[IO[str], IO[bytes]]:
    return open(filename, mode)

As author Nikita Sobolev notes, this pattern leads to constant type ambiguity: "We end up with a lot of conditions, unneeded casts, and guards." The core issue? Standard type hints can't express relationships between input values and output types.

Enter Dependent Types: Literal and @overload

Python's solution lies in two powerful tools:

  1. Literal: Pins variables to specific values
  2. @overload: Defines multiple type signatures
from typing import overload, IO
from typing_extensions import Literal

@overload
def open_file(filename: str, mode: Literal['r']) -> IO[str]: ...

@overload
def open_file(filename: str, mode: Literal['rb']) -> IO[bytes]: ...

def open_file(filename: str, mode: str) -> IO[Any]:
    return open(filename, mode)

Now, static checkers like MyPy infer precise return types:

reveal_type(open_file('data.txt', 'r'))   # => IO[str]
reveal_type(open_file('data.txt', 'rb'))  # => IO[bytes]

Why This Matters

  • Eliminates Runtime Surprises: No more AttributeError when mixing str and bytes operations
  • Refactoring Confidence: Type checkers validate logic paths during development
  • Documentation as Code: Overload signatures explicitly map inputs to outputs

Key Implementation Details

  • Literal Values: Only work with primitives (str, int, bool, etc.), not complex types
  • Final Variables: Constants implicitly match Literals:
    from typing import Final
READ_MODE: Final = 'r'
open_file('log.txt', READ_MODE)  # Correctly inferred as IO[str]
  • Fallback Required: Always include a generic @overload for unexpected inputs

The Road Ahead

While current dependent typing has limitations—no support for containers or custom classes—the Python typing ecosystem evolves rapidly. As projects like MyPy enhance their inference engines, these patterns will become indispensable for mission-critical systems.

"Dependent types solve the problem of ambiguous returns. We supply specific values, receive specific types, and make code safer." — Nikita Sobolev

For developers building robust applications, mastering these features marks the difference between hoping code works and knowing it does. Start small with high-risk functions like I/O operations, and watch entire categories of bugs vanish.

Source: Adapted from Simple Dependent Types in Python by Nikita Sobolev.