Skip to main content

Typing for Python Developers

A 5‑Minute Tour with Pyrefly.

Goal: In five minutes you'll know how Python's static type system infers, defines, and composes types—and you'll have copy‑paste snippets to start using right away.

If you are new to Python, check out our Python Typing for New Developers guide.

Python's type system allows you to annotate variables so you, your teammates and your type checker can find bugs before you run your code. Think of it as documentation that's automatically validated and will help your IDE help you.

TL;DR

  • Catch bugs before running the code.
  • Improve editor autocomplete & refactors.
  • Turn your code into living documentation.

Types with Inference​

Static analyzers can often infer types from your code—no annotations required. Pyrefly takes this a step further.

# Basic Inference answer = 42 reveal_type(answer) # hover to reveal type fruits = ["apple", "banana", "cherry"] scores = {"math": 95, "science": 90} def greet(name): return f"Hello, {name}!" message = greet("World")

Where Inference Shines ✨​

  • Constant assignments (answer = 42 -> int)
  • List/tuple/dict literals with uniform elements (names = ["A", "B"] -> list[str])
  • Return types if parameter types are annotated:
def add(a: int, b: int): # ✅ param annotations return a + b # 🔍 return inferred -> int

When to Add Hints​

  • Public APIs (library or service boundaries)
  • Mixed collections (list[int | str])
  • Callable signatures (decorators, callbacks)

Define Types Inline​

The Basics​

Python's built-in types can be used to write many type hints.

# Example: Basic Types from typing import reveal_type age: int = 5 reveal_type(age) # revealed type: Literal[5] age = "oops" name: str = "John" reveal_type(name) # revealed type: Literal['John'] numbers: list[int] = [1, 2, 3] reveal_type(numbers) # revealed type: list[int] names: list[str] = ["John", "Jane"] reveal_type(names) # revealed type: list[str] person: dict[str, str] = {"name": "John", "age": "30"} reveal_type(person) # revealed type: dict[str, str] is_admin: bool = True reveal_type(is_admin) # revealed type: Literal[True]

Functions​

Defining the parameter and return types for a function doesn't just help prevent bugs, but it makes it easier to navigate in other files. You don't always need to define a return type - we'll do our best to infer it for you! We can't always get it right and an explicit return type will help your IDE navigate faster and more accurately.

# Example: Functions from typing import reveal_type def greet(name: str) -> str: return f"Hello, {name}!" greet("Pyrefly") def whatDoesThisFunctionReturnAgain(a: int, b: int): return a + b reveal_type(whatDoesThisFunctionReturnAgain(2, 3)) # revealed type: int

Advanced Types​

Composing Types​

The real power comes from composing smaller pieces into richer shapes.

Unions & Optional​

# Union and Optional Types from typing import Optional def to_int(data: str | bytes | None) -> Optional[int]: if data is None: return None if isinstance(data, bytes): data = data.decode() return int(data)

Generics​

Generics allow you to define reusable functions and classes that work with multiple types. This feature enables you to write more flexible and adaptable code.

# Example: Generic Classes from typing import reveal_type class C[T]: def __init__(self, x: T): self.x = x def box(self) -> list[T]: return [self.x] c = C(0) reveal_type(c.box()) # revealed type: list[int]

Protocols​

Protocols enable structural typing, which allows you to define interfaces without explicit inheritance. This feature helps you write more modular and composable code.

# Example: Structural Typing with Protocols from typing import Iterable, Protocol class Writer(Protocol): def write(self) -> None: ... class GoodWorld: def write(self) -> None: print("Hello world!") class BadWorld: pass def f(writer: Writer): pass f(GoodWorld()) # OK f(BadWorld()) # ERROR!

Structural Types​

Python also employs a structural type system, often referred to as "duck typing." This concept is based on the idea that if two objects have the same shape or attributes, they can be treated as being of the same type.

Dataclasses​

Dataclasses allow you to create type-safe data structures while minimizing boilerplate.

# Example: Dataclasses from dataclasses import dataclass @dataclass class Point: x: float y: float Point(x=0.0, y=0.0) # OK Point(x=0.0, y="oops") # ERROR!

TypedDict​

Typed dictionaries enable you to define dictionaries with specific key-value types. This feature lets you bring type safety to ad-hoc dictionary structures without major refactoring.

# Example: TypedDict from typing import TypedDict class Movie(TypedDict): name: str year: int good_movie: Movie = {"name": "Toy Story", "year": 1995} # OK bad_movie: Movie = {"name": "The Room", "year": "2003"} # ERROR!

Overloads​

Overloads allow you to define multiple function signatures for a single function. Like generics, this feature helps you write more flexible and adaptable code.

# Example: Overloads from typing import overload, reveal_type @overload def f(x: int) -> int: ... @overload def f(x: str) -> str: ... def f(x: int | str) -> int | str: return x reveal_type(f(0)) # revealed type: int reveal_type(f("")) # revealed type: str

Typing Features and PEPS available in each Python Version​

See the full list of features available in the Python type system here.

Key Highlights Summary:​

  • Inference: Python's static analyzers can infer types from your code, reducing the need for explicit annotations. This feature enhances code readability and helps catch bugs early.
  • Defining Types: You can define types inline using Python's built-in types, which aids in documentation and improves IDE support.
  • Advanced Types: The guide covers advanced concepts like composing types, using unions and optionals, generics, protocols, and structural types like dataclasses and TypedDict.
  • Practical Examples: The guide includes examples of functions, generic classes, structural typing with protocols, and more, demonstrating how to apply these concepts in real-world scenarios.