DEV Community: Cardamom Code

Python Type Annotations (part 3)

Dag Brattli — Sun, 10 Aug 2025 05:59:28 +0000

Python Type Annotations is a tutorial in 3 parts: Part 1 | Part 2 | Part 3 (this post)

Variance in Generics
Covariance
Contravariance
Invariance
References

Variance in Generics

Variance in generics refers to how subtyping relationships behave when they are wrapped in a generic container or function. E.g. if Cat is a subclass of Animal, then subtype polymorphism which you may already be familiar with, explains how a Cat can transform (morph) into, and be used in place of an Animal. In a similar way, variance tells us how e.g. a set[Cat] can transform (vary) and be used in place of a set[Animal] or vice versa.

There are three types of variance:

Covariance enables you to use a more specific type than originally specified. Example: If Cat is a subclass of Animal, you can assign an instance of Iterable[Cat] to a variable of type Iterable[Animal].
Contravariance enables you to use a more general type than originally specified. Example: If Cat is a subclass of Animal, you can assign an instance of Callable[[Animal], None] to a variable of type Callable[[Cat], None].
Invariance means that you can only use the type originally specified. An invariant generic type parameter is neither covariant nor contravariant. Example: If Cat is a subclass of Animal, you cannot assign an instance of list[Animal] to a variable of type list[Cat] or vice versa.

If we look at Python types, there are already many types and combinations of types that have different variance:

Function types i.e. callables are covariant on their return type, and contravariant on their arguments.
Mutable containers like list and dict are invariant.
Immutable containers like tuple and set are covariant.
Union types are covariant. This means that optional types are also covariant because they are equivalent to T | None.

Understanding variance helps you writing more flexible and type-safe code, especially when working with container types, generics and inheritance.

Covariance

Covariance (co- = together) means the subtype relationship goes in the same direction i.e. transform (vary) together with the wrapped type. For example, if Cat is a subtype of Animal, then set[Cat] is a subtype of set[Animal]. The type parameter varies together and in the same direction as the inheritance relationship.

As we mentioned in the introduction, covariance is a type of variance that allows you to use a more specific type than originally specified. For example, if Cat is a subclass of Animal, you can assign an instance of Iterable[Cat] to a variable of type Iterable[Animal], and if you have a method that takes an Iterable[Animal], you can safely pass in an Iterable[Cat].

The definition is that a generic type GenericType[T] is covariant in type parameter T if:

Derived is subtype of Base.
GenericType[Derived] is a subtype of GenericType[Base]

Examples of covariant types in Python are Iterable, set, tuple, and return types of callables.

Before we start we need to import a few types that we will use in the examples.

from abc import abstractmethod
from collections.abc import Callable, Iterable
from typing import Generic, TypeVar

Let's define a few classes. We will use Animal as a base class, and define Cat and Dog as subclasses of Animal.

class Animal:
    @abstractmethod
    def say(self) -> str: ...


class Cat(Animal):
    def say(self) -> str:
        return "Meow"


class Dog(Animal):
    def say(self) -> str:
        return "Woof"

Let's first see how this works with basic assignments.

cats = [Cat(), Cat()]
xs: Iterable[Animal] = cats  # Ok
ys: list[Animal] = cats  # Error: ...
# Type parameter "_T@list" is invariant, but "Cat" is not the same as "Animal"

So we see for the first assignment everything is ok, since the type of xs is Iterable[Animal], which is indeed a subtype of Iterable[Cat].

But for the second assignment, we get an error. This is because list[Animal] is invariant, and list[Cat] is not a subtype of list[Animal].

The problem is that lists are mutable. Think for a minute what would happen if we appended a Dog to the list ys. This is fine for ys since the type is list[Animal], but this means that cats would also be modified and would now contain a Dog, which is not allowed and should come as a surprise to any code still using cats.

cats: list[Cat] = [Cat(), Cat()]
ys: list[Animal] = cats  # type: ignore
ys.append(Dog())

print([cat.say() for cat in cats])
# Output: ['Meow', 'Meow', 'Woof']

Covariance And Function Return Types

Now let's see how this works with function return types for callables. We will define some "getter" functions that returns an instance of Animal or Cat, and also a "setter" function just to show that this does not work.

def get_animal() -> Animal:
    return Cat()  # Cat, but returned as Animal


def get_animals() -> Iterable[Animal]:
    return iter([Cat()])


def get_cat() -> Cat:
    return Cat()


def set_cat(cat: Cat) -> None:
    pass


def get_cats() -> Iterable[Cat]:
    return iter([Cat()])


# Cat -> Animal
var1: Animal = Cat()  # Ok, polymorphism
var2: Callable[[], Animal] = get_cat  # Ok, covariance,
var3: Callable[[], Iterable[Animal]] = get_cats  # Ok, covariance
var4: Callable[[Animal], None] = set_cat  # Error: ...
# Parameter 1: type "Animal" is incompatible with type "Cat"

The first assignment of var1 is just normal polymorphism. This is just to show the similarity between polymorphism and covariance. For the second and third assignments we see that covariance works for return types in callables since a function that returns a Cat is compatible with a function that returns an Animal.

For the last assignment, we get an error, since set_cat is a function that takes a Cat, and set_cat is not compatible with a function that takes an Animal. This is because callables are not covariant on parameter types.

In the next example, we will see how this works when assigning a general type e.g. Animal to a more specific type e.g Cat.

# Animal -> Cat
var5: Cat = Animal()  # Error: "Animal" is incompatible with "Cat"
var6: Callable[[], Cat] = get_animal  # Error: ...
var7: Callable[[], Iterable[Cat]] = get_animals  # Error: ...
# Type parameter "_T_co@Iterable" is covariant, but "Animal" is not a subtype of "Cat"

For the first assignment of var5, we get an error, since Animal is not a subtype of Cat. This is because a function that returns an Animal is not compatible with a function that returns a Cat. This is because the function might return a Dog.

For the second assignment of var6, and third assignments of var7, we also get errors, since Animal is not a subtype of Cat, hence a Dog might be returned from get_animal or get_animals which is incompatible with Cat.

Custom Covariant Generic Classes

We can also define our own covariant generic classes. Let's see how this works. To define a covariant generic class, we need to use the covariant keyword argument for the T_co type variable.` This is by the way similar to how we declared type variables before Python 3.12.

We will make a Rabbit class that is a subclass of Animal, and a Hat class that is covariant in its type parameter. This means that a Hat[Rabbit] is a subtype of Hat[Animal].

Let's see how this looks in code.

`python
T_co = TypeVar("T_co", covariant=True)

class Rabbit(Animal):
def say(self) -> str:
return "Squeak"

class Hat(Generic[T_co]):
def init(self, value: T_co) -> None:
self.value = value

def pull(self) -> T_co:
    return self.value

One way to think about covariance is that covariant types are "out" types and can only be used as return types. If a class were to allow inserting and setting values of the generic type, it would violate the principle of covariance and could lead to type safety issues.

Let's see what happens if we try to add a method that takes the generic type as input for a class with the covariant type variable.

`python
class InvalidHat(Hat[T_co]):
"""Just to show that in parameters are not allowed"""

def put(self, value: T_co) -> None:  # Error: Covariant type variable cannot be used in parameter type
    self.value = value

As we see in the example above, we get an error when we try to add a method that takes the generic type in the parameter. This is because covariant types can only be used as return types. If a class were to allow inserting and setting values of the generic type, it could lead to type safety issues.

But wait a minute. The constructor or the initializer __init__ method is taking the generic type as an argument. Why isn't that a problem? The reason why this is okay is that the object is being created at that point, and the type is being established. Once the object is created, its type is fixed and won't change.

But for abstract covariant classes or protocols that do not have constructors, we can only use the generic type as on out type, i.e. only in the return type of a method.

`python
hat_with_animal: Hat[Animal] = HatRabbit

def fetch_rabbit_hat() -> Hat[Rabbit]:
return Hat(Rabbit())

fetch_animal_hat: Callable[[], Hat[Animal]] = fetch_rabbit_hat
`

In the example above we defined Hat[Rabbit] and assign it to a variable that has the type Hat[Animal]. This would have given an error if the generic type T_co was not covariant.

Note: we specify Hat[Rabbit](Rabbit()) to avoid that the constructor uses polymorphism from Rabbit to Animal so we do create a Hat[Rabbit] and not a Hat[Animal].

Covariance summarized

Covariance is in may ways similar to polymorphism in the way we think about and use the type in our code. We use it for "out" types we have in our methods, i.e. methods that returns the generic type like Iterable, Set, Tuple, and also return types of Callable.

When we define a type to be covariant, we are able to assign a container i.e. generic class of e.g. Rabbit, to a variable that is annotated as a generic class of Animal. This would not have been possible if the type was not covariant.

Contravariance

Contravariance (contra- = against/opposite) means the subtype relationship goes in the opposite direction. If Cat is a subtype of Animal, then e.g Observer[Animal] is a subtype of Observer[Cat]. The type parameter varies in the opposite direction from the inheritance relationship of the wrapped type.

As mentioned introduction, contravariance is a type of variance that allows you to use a more general type in place of a more specific type. This might sound counterintuitive at first. It usually goes against what you would expect, and it's safe to say that this is something most developers don't know about.

In Python, contravariance is typically experienced for function arguments in callables, or push-based containers such as observables (RxPY). This means that it might help to think in terms of callbacks when you try to understand contravariance. This is because callbacks are usually functions that usually takes one or more arguments and returns nothing.

The definition is that a generic type GenericType[T] is contravariant in type parameter T if:

Derived is subtype of Base.
GenericType[Base] is a subtype of GenericType[Derived].

Examples of contravariant types in Python are callables, and function arguments. The Observer class in RxPY and similar classes using the "consumer"" pattern e.g (send, throw, close) style of methods that take generic type T as an argument and return nothing.

First, we need to import a few types that we will use in the examples.

python from abc import abstractmethod from collections.abc import Callable, Iterable from typing import Generic, TypeVar

Let's define a few classes, the same as we used with covariance so we can compare the two. We will use Animal as a base class, and define Cat and Dog as subclasses of Animal.

`python
class Animal:
@abstractmethod
def say(self) -> str: ...

class Cat(Animal):
def say(self) -> str:
return "Meow"

class Dog(Animal):
def say(self) -> str:
return "Woof"
`

Example: Function Arguments

Let's see how this works with function arguments for callables. Callables are generic types that are contravariant in their argument types, e.g. you can assign an instance of Callable[[Animal], None] to a variable of type Callable[[Cat], None]

We can define a few setter functions that takes an argument of type Animal or Cat and returns nothing. These are the opposites of the getter functions we defined for covariance.

`python
def set_animal(animal: Animal) -> None:
pass

def set_animals(animals: Iterable[Animal]) -> None:
pass

def set_cat(cat: Cat) -> None:
pass

def set_cats(cats: Iterable[Cat]) -> None:
pass

def get_animal() -> Animal:
return Cat() # Cat, but returned as Animal

Cat -> Animal

var1: Animal = Cat() # Ok, polymorphism

This works because a function that takes a Cat is compatible with a function that

takes an Animal.

var2: Callable[[Cat], None] = set_animal # Ok, since Callable is contravariant for arguments
var3: Callable[[Iterable[Cat]], None] = set_animals # Ok, contravariance
var4: Callable[[], Cat] = get_animal # Error: "Animal" is incompatible with "Cat"
`

We start in a similar way as we did with covariance. We see that for the first assignment, everything is ok, since the type of var1 is Animal, which is a base class of Cat. This is normal polymorphism.

For the second and third assignments, we start to see how contravariance works for function arguments. This works because a function that takes an Animal can be assigned to a variable that is annotated as a callable that takes a Cat. We can always call a callback that takes an Animal with a Cat.

For the last assignment, we get an error, since get_animal is a function that returns an Animal, and get_animal is not compatible with a function that returns a Cat. This is because callables are not contravariant on return types.

`python

Animal -> Cat

var5: Cat = Animal() # Error: "Animal" is incompatible with "Cat"

We get an error here because a function that takes an Animal is not compatible with

a function that takes a Cat. This is because the function might take a Dog.

var6: Callable[[Animal], None] = set_cat # Error: ...
var7: Callable[[Iterable[Animal]], None] = set_cats # Error: ...

(*) Type parameter "_T_co@Iterable" is covariant, but "Animal" is not a subtype of "Cat"

For the first assignment, we get an error, since Animal is not a subtype of Cat. For the second and third assignments, we get an error because Animal is not a subtype of Cat. If you think about the callable as a callback, then it's easier to see that you cannot give an Animal e.g. a Dog to a function that takes a Cat.

Custom Contravariant Generic Classes

We can also define our own contravariant generic classes, similar to how we made covariant classes. To define a contravariant generic class, we need to use the contravariant keyword argument for the T_contra type variable.` This is by the way similar to how we declared type variables before Python 3.12.

We will make a Rabbit class that is a subclass of Animal, and a Hat class that is contravariant in its type parameter. This means that a Hat[Animal] is a subtype of Hat[Rabbit].

Let's see how this looks in code.

T_contra = TypeVar("T_contra", contravariant=True)


class Rabbit(Animal):
    def say(self) -> str:
        return "Squeak"


class Hat(Generic[T_contra]):
    def __init__(self, value: T_contra) -> None:
        self.value = value

    def put(self, value: T_contra) -> None:
        self.value = value


class Callable_(Generic[T_contra]):
    def __call__(self, value: T_contra) -> None: ...

Let's see what happens if we try to add a method that returns the generic type for a class with a contravariant type variable.

class InvalidHat(Hat[T_contra]):
    def __init__(self, value: T_contra) -> None:
        self.value = value

    def get(self) -> T_contra:  # Error: Contravariant type variable cannot be used as a return type
        return self.value

As we see in the example above, we get an error when we try to add a method that returns the generic type. This is because contravariant types can only be used as function argument types. If a class were to allow returning values of the generic type, it could lead to type safety issues.

One way to think about contravariance is that contravariant types are "in" types and can only be used as function argument types. If a class were to allow returning values of the generic type, it would violate the principle of contravariance and could lead to type safety issues.

We see that we get the opposite of what we saw with covariance. The get_value method now has an error, since we cannot return a value of type T_contra. But the set_value method works, since we can set the value to a value of type T_contra.

animal: Animal = Rabbit()
hat_with_rabbit: Hat[Rabbit] = Hat[Animal](animal)


def fetch_animal_hat() -> Hat[Animal]:
    return Hat(Rabbit())


fetch_rabbit_hat: Callable[[], Hat[Rabbit]] = fetch_animal_hat

In the example above we defined Hat[Animal] and assign it to a variable that has the type Hat[Rabbit]. This would have given an error if the generic type T_contra was not contravariant.

Summary

Contravariance is the opposite of covariance, and this makes it quite a bit harder to understand since Hat[Rabbit] is not a subtype of Hat[Animal] perhaps as you might expect. It is actually the other way around. With contravariance Hat[Animal] becomes a subtype of Hat[Rabbit].

When we define a type to be contravariant, we are able to assign a container i.e. generic class of e.g. Animal, to a variable that is annotated as a generic class of Rabbit. This would not have been possible if the type was not contravariant.

Invariance in Generics

Invariance (in- = un/not) means that the type is not variant, and will not transform (vary) together with the wrapped type. This means that you can use only the type originally specified, and neither a more specific nor a more general type. This is the default behavior for generic types in Python.

An invariant generic type parameter is neither covariant nor contravariant. You cannot assign an instance of Hat[Animal] to a variable of type Hat[Rabbit] or vice versa.

from abc import abstractmethod


class Animal:
    @abstractmethod
    def render(self) -> str: ...


class Rabbit(Animal):
    def render(self) -> str:
        return "Rabbit!"


class Hat[T]:
    @abstractmethod
    def put(self, value: T) -> None: ...

    @abstractmethod
    def pull(self) -> T: ...


class RabbitHat(Hat[Rabbit]):
    def put(self, value: Rabbit) -> None:
        print(f"Putting {value.render()} in the hat")

    def pull(self) -> Rabbit:
        """Pull a Rabbit out of the hat"""
        return Rabbit()


# This will not work due to invariance
animal_hat: Hat[Animal] = RabbitHat()  # Error: ...
# Type parameter "T@Hat" is invariant, but "Rabbit" is not the same as "Animal"

# This also will not work due to invariance
rabbit_hat: Hat[Rabbit] = Hat[Animal]()  # Error: ...
# Type parameter "T@Hat" is invariant, but "Animal" is not the same as "Rabbit"

# This is the only valid assignment
rabbit_hat: Hat[Rabbit] = RabbitHat()

# We can only put Rabbits in a RabbitHat
rabbit_hat.put(Rabbit())

# This will not work, even though Rabbit is a subclass of Animal
rabbit_hat.put(Animal())  # Error: ...
# "Animal" is incompatible with "Rabbit"

# We can only take Rabbits from a RabbitHat
rabbit: Rabbit = rabbit_hat.pull()

Invariance restricts us to use exactly the type specified. This happens when we use the generic type as both "in" and "out" types, meaning that methods of the type use the generic type both in the parameters, and return types.

This hints that the generic type may be some kind of mutable container and we cannot allow assigning a Hat[Animal] to a Hat[Rabbit] or vice versa since that could easily lead to code adding a Cat into a Hat[Rabbit].

References

Python Type Annotations (part 2)

Cristina Ferrer — Sun, 10 Aug 2025 05:50:53 +0000

Python Type Annotations is a tutorial in 3 parts: Part 1 | Part 2 (this post) | Part 3

Generics
Variadic Generics
Parameter Specification
Overloads
Final notes
References

Generics

Generics provide a powerful way to create flexible and reusable code components that can work with multiple data types while maintaining type safety.

They are a way to defer the specification of types until you actually need to use them in your code. In other words, generics allow you to write a function or a class that can work with any data type.

If Python is a dynamically typed language, and already works with any type, why do we need generics?

Sometimes you want functions to handle different types in a consistent way. Consistent here means that we are locking the types of two or more type parameters. If we set the type of one parameter to be int, all other uses of that type parameter must also be int. It's like telling Python, "Hey, whatever type you choose, stick with it throughout this function!"

For Python 3.12 and later versions, generic type parameters can be defined by using square brackets after the name of the function, for example [T]. This type parameter can then be used both in the function signature, and in the body of the function.

def identity[T](value: T) -> T:
    return value

This generic identity function locks the return type T to be the same as the input value type T. If we pass an int, the return type will then also have to be an int. Similarly, if we pass a str, the return type will be a str.

We can now use the function with any type such as int, str, etc:

a: int = identity(10)
b: str = identity("test")

Note: Before Python 3.12, generic type variables were defined using TypeVar from the typing module.

Similar to private variables in a Python module, we usually prepend a _ to the name of the type variable to indicate that it is private and not to be used outside the module.

from typing import TypeVar  # noqa: E402

_T = TypeVar("_T")


def identity_(value: _T) -> _T:
    return value

In the next example, we create a filter function that filters a list of a given data type [T]. The function takes two arguments: a predicate function that filters the list, and the source list to be filtered:

from collections.abc import Callable  # noqa: E402
from typing import reveal_type  # noqa: E402


def filter[T](predicate: Callable[[T], bool], source: list[T]) -> list[T]:
    return [x for x in source if predicate(x)]

If we pass in a list[int], it will expect a predicate function that takes an int and returns a bool. The result of the the function will also be a list[int]:

xs: list[int] = [1, 2, 3]
ys = filter(lambda x: x > 2, xs)
reveal_type(ys)  # Type of "ys" is "list[int]"

Similarly, if we pass in a list[str], the predicate function will take a str and return a bool. The result of the function will also be a list[str]:

xs_: list[str] = ["a", "b", "c"]
ys_ = filter(lambda x: len(x) > 1, xs_)
reveal_type(ys_)  # Type of "ys_" is "list[str]"

Note that generic types are only really useful when the declared type parameters are used more than once. In the function below, the type parameter T is only used once, so the type is not locked to any other argument, or to the return type in the function.

def length[T](xs: list[T]) -> int:
    return sum(1 for _ in xs)

When a type variable is used only once, it is equivalent to using Any, as the function will accept any type. In such cases, the type checker cannot provide any meaningful validation.

from typing import Any  # noqa: E402


def length_(xs: list[Any]) -> int:
    return sum(1 for _ in xs)

Generic classes

We can also create generic classes by using class type parameters. This will make the class reusable with different types. In the following example, we create a Stack class that can be used with different types of data.

class Stack[T]:
    def __init__(self, initial_values: list[T] | None = None) -> None:
        self.items: list[T] = initial_values or []

    def push(self, item: T) -> None:
        self.items.append(item)

    def pop(self) -> T:
        return self.items.pop()


int_stack = Stack([1, 2, 3])
int_stack.push(1)
int_stack.push(2)

str_stack = Stack[str]()
str_stack.push("hello")
str_stack.push("world")

Note: Before Python 3.12, generic types required to define a TypeVar and use Generic[_T] to declare a generic type of _T. This approach is still valid but for most cases not needed anymore. The exception is if we want to specify variance, which is not possible with the new syntax. We will explore variance in Part 3.

from typing import Generic  # noqa: E402

_D = TypeVar("_D")


class Stack_(Generic[_D]):
    def __init__(self, initial_values: list[_D] | None = None) -> None:
        self.items: list[_D] = initial_values or []

    def push(self, item: _D) -> None:
        self.items.append(item)

    def pop(self) -> _D:
        return self.items.pop()

Generic Type Aliases

Type aliases in Python provide a way to create alternate names for complex types, making your code more readable and maintainable. It reduces redundancy and also adds semantic meaning to your type annotations.

In Python 3.12, you can use the new type keyword to define aliases:

type UserScores = dict[str, list[int]]

We can make type aliases generic by using square brackets after the name of the type alias similar to how we make generic functions and classes.

type PropertyBag[T] = dict[str, T]

# We can now use the generic type alias to create a more specific non-generic type
type StringBag = PropertyBag[str]

Note: Before python 3.12, type aliases were defined using the TypeAlias feature from the typing module.

from typing import TypeAlias, TypeVar, override  # noqa: E402

_B = TypeVar("_B")

PropertyBag_: TypeAlias = dict[str, _B]  # noqa: UP040

StringBag_: TypeAlias = PropertyBag_[str]  # noqa: UP040

How to restrict Generic Type Parameters

Generic types can be restricted to work with specific types or their subclasses:

Using a bound type parameter: It sets an upper bound for the type. This means the type can only be the specified type or a subclass of the type. For example, to create a generic type that accepts float or any subclass of float (like int), you can use a bounded type parameter [T: float].
Using a constrained type parameter: It limits the type to a specific set of two or more types, without including their subclasses. For example, to create a generic type that accepts only int or str, you can use a constrained type parameter: [T: (int, str)].

Note: Before Python 3.12, bound and constrained generic types were defined in the TypeVar definition.

from typing import TypeVar  # noqa: E402

# Bound type parameter
T = TypeVar("T", bound=float)

# Constrained type parameter
S = TypeVar("S", int, str)

Why to restrict Generic Type Parameters

At first, we might think that we could use unions, overloads, or base classes to achieve the same functionality as restricted generic type parameters. However, they will not work the same as restricted generic type parameters.

To explore this, let's define a data model for some animals and their subclasses:

class Animal:
    """A base class for animals"""

    def __init__(self, name: str) -> None:
        self.name = name

    def feed(self) -> str:
        return "Animal is eating"


class Rabbit(Animal):
    """A subclass of Animal"""

    def run(self) -> str:
        return "Rabbit is running"

    @override
    def feed(self) -> str:
        return "Rabbit is eating"


class Fox(Animal):
    """A subclass of Animal"""

    def say(self) -> str:
        return "Ring-ding-ding-ding!"

    @override
    def feed(self) -> str:
        return "Fox is eating"


class RedFox(Fox):
    """A subclass of Fox"""

    def go_nuts(self) -> str:
        return "Going nuts"


fox = Fox("Tod")
rabbit = Rabbit("Harvey")
red_fox = RedFox("Foxy")

In the following examples, we'll use these classes to illustrate the differences between using unions, overloads, base classes, constrained generic types and bound generic types. The RedFox subclass will highlight potential problems when working with subclasses and generics.

Note: The @override decorator is used to indicate that a method overrides a base class method. This is useful for static type checkers to verify the method actually overrides a parent method.

Using unions

For the first example, let's create a function that takes either a Fox or a Rabbit as an argument, and returns Fox or Rabbit as the output type. We will then try to call some of the methods on the returned object to see what happens.

def care_for_animal(animal: Fox | Rabbit) -> Fox | Rabbit:
    animal.feed()
    ...
    return animal


care_for_animal(rabbit).run()  # Error: Cannot access attribute "run" for class "Fox"
care_for_animal(fox).say()  # Error: Cannot access attribute "say" for class "Rabbit"
care_for_animal(red_fox).go_nuts()  # Error: Cannot access attribute "go_nuts" for class "Fox"

In the example above, we can never be sure if the output of care_for_animal will be a Fox or a Rabbit. Therefore, we need to use type narrowing, such as a match statement, to check the type of the result. This creates a lot of noise to our code by requiring type checks before using the result.

result = care_for_animal(rabbit)
reveal_type(result)  # Type of "result" is "Rabbit | Fox"

match result:
    case Rabbit():
        result.run()
    case Fox():
        result.say()

As an alternative, we can try using overloads or a constrained generic type parameter.

Using overloads

Function overloads allow you to specify multiple type signatures for a single function. They're especially useful when a function can accept different parameter types or combinations of parameters. Overloads are explained in more detail in the next section.

Let's define different signatures for the care_for_animal function:

from typing import overload  # noqa: E402


@overload
def care_for_animal_overloads(animal: Rabbit) -> Rabbit: ...


@overload
def care_for_animal_overloads(animal: Fox) -> Fox: ...


def care_for_animal_overloads(animal: Fox | Rabbit) -> Fox | Rabbit:
    animal.feed()
    ...
    return animal


care_for_animal_overloads(rabbit).run()
care_for_animal_overloads(fox).say()
care_for_animal_overloads(red_fox).go_nuts()  # Error: Cannot access attribute "go_nuts" for class "Fox"

Using overloads is more verbose, but when we call the function with a Rabbit or a Fox, it returns a Rabbit or Fox respectively, allowing us to call their specific methods. However, subclasses like RedFox are treated as their parent class Fox, so we cannot call the go_nuts method as it's only available on the RedFox class.

To address these limitations, we can explore using a constrained generic type.

Using a constrained generic type

Let's make T a constrained type parameter that can only be Rabbit or Fox.

def care_for_animal_constrained[T: (Rabbit, Fox)](animal: T) -> T:
    animal.feed()
    ...
    return animal


care_for_animal_constrained(rabbit).run()
care_for_animal_constrained(fox).say()
care_for_animal_constrained(red_fox).go_nuts()  # Error: Cannot access attribute "go_nuts" for class "Fox"

This approach is less verbose, but it has the same limitation as using overloads. It requires knowing all restricted types upfront and won't work with other animals or even subclasses of the specified animal types. We still cannot call the go_nuts method on the red_fox object because the returned type is Fox and not RedFox.

To address this problem we need to use subclassing of some sort.

Using a base class

Let's try to use the Animal base class as the input type parameter instead of Rabbit and Fox.

def care_for_animal_subclassing(animal: Animal) -> Animal:
    animal.feed()
    ...
    return animal


care_for_animal_subclassing(rabbit).feed()

care_for_animal_subclassing(rabbit).run()  # Error: Cannot access attribute "run" for class "Animal"
care_for_animal_subclassing(fox).say()  # Error: Cannot access attribute "say" for class "Animal"
care_for_animal_subclassing(red_fox).go_nuts()  # Error: Cannot access attribute "go_nuts" for class "Animal"

With subclassing in itself we will only be able to feed the animals, calling methods that are only available on the subclasses themselves will not work.

Let's try to use a bound generic type parameter instead.

Using a bound generic type parameter

Bound generic type parameters work with subclasses, so let's try to use a bound generic type parameter with the base class Animal.

def care_for_animal_bound[T: Animal](animal: T) -> T:
    animal.feed()
    ...
    return animal


care_for_animal_bound(rabbit).run()
care_for_animal_bound(fox).say()
care_for_animal_bound(red_fox).go_nuts()

Now the output type matches the input type!

Subclassing with a bound generic parameter solves most of the problems we had earlier. However, it still limits us to using the function only with subclasses of Animal, making it less flexible for other types of animals.

Let's try using a protocol as the bound generic type.

Using a bound generic protocol

In Part 1, we explored protocols, which allow us to define a set of methods that a class must implement without requiring inheritance from a base class.

We can create a protocol that requires the feed method to be implemented, and use this protocol as a bound generic type parameter.

from typing import Protocol  # noqa: E402


class CareFor(Protocol):
    def feed(self) -> str: ...


def care_for_animal_protocol[T: CareFor](animal: T) -> T:
    animal.feed()
    return animal


care_for_animal_protocol(rabbit).run()
care_for_animal_protocol(fox)

The care_for_animal_protocol function supports now static duck typing. It will work with any type that implements the feed method, allowing us to use it with any animal, not just subclasses of Animal:

class Dog:
    def feed(self) -> str:
        return "Dog is eating"


care_for_animal_protocol(Dog()).feed()

care_for_animal_protocol(rabbit).run()
care_for_animal_protocol(fox).say()
care_for_animal_protocol(red_fox).go_nuts()

Using a class that does not implement the feed method will result in a type error:

class Robot: ...


care_for_animal_protocol(Robot())  # Error: "Robot" is incompatible with protocol "CareFor"

More about bound generic protocols

Bound generic parameters combined with protocols are particularly useful when we need to ensure that a generic function or method works with a range of compatible types that share certain characteristics or behaviors, without requiring those types to inherit from a common base class.

Here is another example. We can define a generic function that takes a list of values and returns the largest value. This function can work with any type that implements the __gt__ method, such as int, float, or custom classes that define the __gt__ method.

To achieve this, we will need to create a protocol that requires a type to be comparable using the greater-than operator >. This protocol will then be used to bound the generic type T used in the function:

from collections.abc import Iterable  # noqa: E402
from typing import Any, reveal_type  # noqa: E402


class IsGreaterThan(Protocol):
    def __gt__(self, value: Any, /) -> bool: ...


def largest[T: IsGreaterThan](xs: Iterable[T]) -> T:
    return max(xs)


xs: list[int] = [1, 2, 3]
result = largest(xs)
reveal_type(result)  # Type of "result" is "int"

ss: list[str] = ["a", "b", "c"]
result = largest(ss)
reveal_type(result)  # Type of "result" is "str"

We can also use the IsGreaterThan Protocol for a function that takes a list of comparable values. We can pass in either a list of int or a list of str. The return type will correspond to the input type, returning a list of int or str, respectively.

def sort_list[T: IsGreaterThan](items: list[T]) -> list[T]:
    return sorted(items)


numbers = [3, 1, 4, 1, 5, 9]
sorted_numbers = sort_list(numbers)
reveal_type(sorted_numbers)  # Type of "sorted_numbers" is "list[int]"

names = ["Alice", "Bob", "Charlie"]
sorted_names = sort_list(names)
reveal_type(sorted_names)  # Type of "sorted_names" is "list[str]"

Variadic Generics

In the previous section about Generics, we looked at how we can define generic classes using one or more type variables, such as T and U. However, in some cases, we might not know the number of type variables before the class instance or function is created.

Variadic generics allow us to define classes and functions that can take any number of type arguments, similar to tuple arguments such as *args, where both the number of elements and their types depend on the function caller.

Let's explore how we can use variadic generics in classes, functions and callables.

Classes with Variadic Generics

Variadic generics uses the star * notation for type variables, such as *Ts, to indicate that the type variable can represent any number of type arguments. The lowercase s is a convention used to indicate that the type variable is plural, showing that it represents multiple type arguments, compared to the commonly used T that represents a single type argument.

In the following example, we create two instances of DataPoint, each with a different number of arguments and types.

from typing import reveal_type


class DataPoint[*Ts]:
    def __init__(self, *values: *Ts) -> None:
        self.values = values


first = DataPoint(True)
reveal_type(first)  # Type of "first" is "DataPoint[bool]"

second = DataPoint(1, "test", 2.3)
reveal_type(second)  # Type of "second" is "DataPoint[int, str, float]"

--- Note: Before Python 3.12, variadic generics were defined using TypeVarTuple instead of using the *Ts syntax. It needs to be imported from the typing module for Python 3.11, and from typing_extensions for versions earlier than 3.11:

from typing import TypeVarTuple  # noqa: E402

_Ts = TypeVarTuple("_Ts")  # Only needed for Python 3.11 and earlier

Functions with Variadic Generics

Variadic generics can also be used to define functions that can take any number of arguments and types. This enables us to statically type the so-called *args argument.

Similarly to the previous example, here we define the generic make_datapoint function, which can take any number of arguments and types. The types are inferred from the provided arguments:

def make_datapoint[*Ts](*values: *Ts) -> DataPoint[*Ts]:
    return DataPoint(*values)


point1 = make_datapoint("temperature", 25.5)
point2 = make_datapoint(1, "test", 2.3)

reveal_type(point1)  # Type of "point1" is "DataPoint[int, str, float]"
reveal_type(point2)  # Type of "point2" is "DataPoint[str, float]"

Let's take a look at another example. We can define a head function that can take any number of arguments and types and returns the first element of the tuple. This is achieved by defining the type of the tuple argument as tuple[T, *Ts] where T is the first element and Ts the rest of the elements.

def head[T, *Ts](tup: tuple[T, *Ts]) -> T:
    return tup[0]


x = head((1, "test", 2.3))
reveal_type(x)  # Type of "x" is "int"

Similarly, we can define a tail function that can take any number of arguments and types and return all of them except for the first one.

def tail[T, *Ts](tup: tuple[T, *Ts]) -> tuple[*Ts]:
    return tup[1:]


y = tail((1, "test", 2.3))
reveal_type(y)  # Type of "y" is "tuple[str, float]"

Callables with Variadic Generics

Variadic generics can also be used to annotate callables.

In this example, we define a function apply that uses variadic generics to accept a callable fn and a variable number of arguments of type Ts. The apply function then calls the provided callable with the given arguments and returns the result.

from collections.abc import Callable  # noqa: E402


def apply[*Ts](fn: Callable[[*Ts], int], *args: *Ts) -> int:
    return fn(*args)


a = apply(lambda x, y: x + y, 10, 10)

In the next section, we will also see how to use Parameter Specification (ParamSpec) to define both *args and **kwargs.

Parameter Specification

While variadic generics are useful for handling a variable number of type arguments, they are limited to only handling positional arguments. Parameter Specification is a special way of annotating callables that captures both positional and keyword arguments. It is specifically designed to be used with decorators, allowing us to forward argument types between functions and decorators. We will explore this and other uses in this section.

Type Annotating Decorators

Before parameter specification became available, it was impossible to type-annotate decorators accurately. This is because the decorator function needs to forward the same type of parameters as the function it decorates, which can be positional, named, or both.

In the following example, we define a simple decorator logging_before_paramspec that logs the function call details before executing the function. However, this decorator does not maintain the types of the original function it decorates. Instead, it uses Callable[..., Any] for both the input and output types, which means it accepts and returns any callable. As a result, the type information of the original function is lost.

from collections.abc import Callable
from typing import Any, reveal_type


def logging_before_paramspec(func: Callable[..., Any]) -> Callable[..., Any]:
    def wrapper(*args: Any, **kwargs: Any) -> Any:
        print(f"Calling {func.__name__} with {args} and {kwargs}")
        return func(*args, **kwargs)

    return wrapper


@logging_before_paramspec
def my_func_(a: int, b: str) -> float:
    return a + float(b)


reveal_type(my_func_)  # Type of "my_func_" is "(...) -> Any"

Now let's make use of ParamSpec to annotate the decorator, ensuring that the type information of the original function is preserved:

def logging[**P, R](func: Callable[P, R]) -> Callable[P, R]:
    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
        print(f"Calling {func.__name__} with {args} and {kwargs}")
        return func(*args, **kwargs)

    return wrapper


@logging
def my_func(a: int, b: str) -> float:
    return a + float(b)


reveal_type(my_func)  # Type of "my_func" is "(a: int, b: str) -> float

ParamSpec is unique because it's not used like a regular type parameter. Instead, we declare a generic type parameter with double star e.g. **P. The use of P within a function signature Callable[P, R] will capture all of the arguments, both positional and keyword, of a callable function. You can then use P in another function, or use P.args and P.kwargs to refer to positional arguments or keyword arguments.

Note: ParamSpec became available in Python 3.10. It's still possible to use ParamSpec in earlier versions, such as 3.9, by importing it from typing_extensions.

from typing_extensions import ParamSpec  # noqa: E402

_P = ParamSpec("_P")

Concatenating Type Parameters

Parameter specification can also be used to concatenate type parameters. This is useful when you want to define a function that takes a variable number of arguments and need to add or remove some of the positional arguments between the functions.

In the following example, we use the Concatenate type to concatenate the type parameters of the decorated function with the type parameter of the decorator. This allows us to add one positional argument between the two, enabling us to inject a default value for the format argument of the date2str function.

from datetime import datetime  # noqa: E402
from typing import Any, Concatenate  # noqa: E402


def inject[T, **P, R](__arg: T) -> Callable[[Callable[Concatenate[T, P], R]], Callable[P, R]]:
    def decorator(func: Callable[Concatenate[T, P], R]) -> Callable[P, R]:
        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
            return func(__arg, *args, **kwargs)

        return wrapper

    return decorator


@inject("%Y-%m-%d")
def date2str(format: str, dt: datetime) -> str:
    return dt.strftime(format)


dt = date2str(datetime.now())  # (function) def date2str(dt: datetime) -> str
print(dt)  # 2024-07-24

The inject decorator is defined with the type variable T, which represents the type of the argument to be injected (like a str format), the parameter specification **P which captures the original function's variable arguments, and the type variable R which defines the decorated function's return type.

The decorator function takes a callable with concatenated type parameters Concatenate[T, P] and returns a new function that only requires the original P arguments while preserving the original return type R.

The wrapper function inside the decorator adds the injected argument __arg as the first positional argument when calling the original function.

It's not often used in practice, but it's still a useful feature. Check out overloads for the curry_flip in the Expression library for a more practical example.

Overloads

Overloads are useful when you need to define functions that can take different combinations of arguments and perhaps different return types depending on the combinations of arguments.

We can define multiple type signatures by using the @overload decorator from the typing module.

Only the main function should contain the implementation and should be type annotated accepting all cases (often using Any). The overloads should be specific and should not overlap.

In the following example, we define a pipe function that takes a value and up to three positional arguments, each of which is a callable. Each callable takes the output of the previous one as its input. The return type of the pipe function is the result of applying all the callables to the initial value.

from collections.abc import Callable
from functools import reduce
from typing import Any, overload


@overload
def pipe[_A](value: _A) -> _A: ...


@overload
def pipe[_A, _B](value: _A, fn: Callable[[_A], _B], /) -> _B: ...


@overload
def pipe[_A, _B, _C](
    value: _A,
    fn1: Callable[[_A], _B],
    fn2: Callable[[_B], _C],
    /,
) -> _C: ...


@overload
def pipe[_A, _B, _C, _D](
    value: _A,
    fn1: Callable[[_A], _B],
    fn2: Callable[[_B], _C],
    fn3: Callable[[_C], _D],
    /,
) -> _D: ...


def pipe(value: Any, *fns: Callable[[Any], Any]) -> Any:
    return reduce(lambda acc, fn: fn(acc), fns, value)

Note: The overload decorated definitions are only for the benefit of the type checker. At runtime, only the main function is used. The type checker will use the overload decorated definitions to check if the function is called with the correct arguments and return types.

Let's take a look at another example. We can define different overloads for different keyword arguments. In this case, we can use * to explicitly define the end of positional arguments.

@overload
def keyword_arguments(value: int, *, name: str, age: int) -> str: ...


@overload
def keyword_arguments(value: int, *, city: str, location: int) -> str: ...


def keyword_arguments(value: int, **kwargs: Any) -> Any:
    """This function is used to demonstrate the use of keyword arguments."""

Why not use union types instead of overloads?

While it might be tempting to use Union types instead of overloads, it can be challenging to get it right. For example, if we have a function with two arguments and each argument can be of different types, Union types cannot specify which combinations of types are valid. This adds the need to validate the arguments before using them.

When using overloads, the type checker will catch invalid combinations of arguments, eliminating the need for manual validation.

Let's demonstrate this with an example. We'll define a function that takes two arguments and returns their sum. First, we'll annotate the function using Union types.

from typing import reveal_type  # noqa: E402


def process_with_union(arg1: int | str, arg2: int | str) -> int | str:
    match arg1, arg2:
        case int(), int():
            return arg1 + arg2
        case str(), str():
            return arg1 + arg2
        case _:
            raise TypeError("Invalid arguments")

There are several issues with the example above. When calling the function we can never be sure if the return type will be int or str:

ret1 = process_with_union(10, 10)
reveal_type(ret1)  # Type of "ret1" is "int | str"

ret2 = process_with_union("hello", " world")
reveal_type(ret2)  # Type of "ret2" is "int | str"

This means that if you try to use the return type directly, the type checker will give an error. To resolve this, you will need to use type narrowing before using the return values:

ret3 = ret1 + 10  # Error: Operator "+" not supported for types "int | str" and "Literal[10]"
ret4 = ret2 + "!"  # Error: Operator "+" not supported for types "int | str" and "Literal['!']"

if isinstance(ret1, int):
    ret5 = ret1 + 10
    reveal_type(ret5)  # Type of "ret5" is "int"

if isinstance(ret2, str):
    ret6 = ret2 + "!"
    reveal_type(ret6)  # Type of "ret6" is "str"

The type checker will also not warn us if we call the function with an invalid combination of arguments. We will only get a TypeError at runtime.

process_with_union("hello", 10)  # type checker does not warn of an error

Let's instead try to use overloads:

@overload
def process_with_overloads(arg1: int, arg2: int) -> int:
    """Process two integers"""


@overload
def process_with_overloads(arg1: str, arg2: str) -> str:
    """Process two strings"""


def process_with_overloads(arg1: Any, arg2: Any) -> Any:
    """Main function"""
    return arg1 + arg2

Now, we get a return type from the function that we can use directly without needing to narrow the type beforehand.

ret7: int = process_with_overloads(10, 10)
reveal_type(ret7)  # Type of "ret3" is "int

ret8 = process_with_overloads("hello", " world")
reveal_type(ret8)  # Type of "ret4" is "str"

ret7 = ret7 + 10
ret8 = ret8 + "!"

And we also get a type error when calling the function with an invalid combination of arguments.

process_with_overloads("hello", 10)  # Error: No overloads for "process_with_overloads" match the provided arguments

--- Note: As we can see in the above example, docstrings can also be added to the overloads instead of the main function to document each overload. If you don't document each overload then the VSCode Python Extension will fallback to show the main function documentation instead when hovering over the function name.

Final Notes

Using type annotations will help you write better code that is easier to understand, more maintainable, easier to refactor, and easier to test. It can ensure robustness by catching potential type errors during static type checking and improving the overall coding experience. Additionally, it will make it easier for AI tools to understand your code and assist with code completion, refactoring, adding new features and finding bugs.

However, typing in Python can be a double-edged sword:

Updates to MyPY and Pyright will break your code with new releases and you need to take this into your budget. You will spend time fixing type errors with every new release of the type checker.
Many common libraries still do not support typing, e.g. pandas, so you might have to write stubs for these libraries yourself, or reduce the type checking when using these libraries by either using # type: ignore or setting type checking mode from strict to basic.
There will be both false positives, and false negatives. You never have this problem with languages such as Java, Scala, C#, or F#. Prefer writing simple code to reduce the number of false positives and false negatives and reduce the time you spend fixing type errors.
Static type checkers are not able to analyze dynamic code that changes at runtime. While mocking is useful for testing, it can potentially bypass or confuse static type checkers.

However, the benefits of using type annotations in Python far outweigh the disadvantages. It will make you a better programmer and make your code more robust and maintainable. If you want to write high quality production grade code, then you should definitely use type annotations in Python!

References

Python Type Annotations (part 1)

Cristina Ferrer — Sun, 10 Aug 2025 05:43:21 +0000

Python Type Annotations is a tutorial in 3 parts: Part 1 (this post) | Part 2 | Part 3

Python's dynamic typing is one of its core strengths. The low friction allows for rapid development that makes it a popular choice for new developers. However, as projects grow and evolve, the lack of type annotations makes code difficult to understand and maintain. This can lead to unexpected bugs that are hard to track down.

That Python is a dynamically typed language doesn't mean that Python does not have types, it means that types are not known until the code runs. But over the last years static type checking has become more popular. Type annotations provide a Matrix-like view into the code. Once you learn to read type signatures, you'll feel like you have superpowers!

This blog post will explore type annotations in Python, a feature that can improve code readability and catch potential bugs early. We'll show how to use static type checkers and annotate your code with type hints for basic type annotations, type narrowing, structural sub-typing and callables. In Part 2, we will cover more advanced topics such as generics, variadic generics paramspec and overloads.

What are Type Annotations?
Why do we need Type Annotations?
Static Type Checkers
Installing and Setup
Basic Type Annotations
Type Inference
Type Narrowing
Static Duck Typing and Protocols
Functions and Callables
References

What are Type Annotations?

Type annotations, also known as type hints, are a way to specify the type of a variable, function, or argument in Python.

For example, in the following function, we are specifying that the function add takes two arguments x and y of type float as input and returns a value of type float as output.

def add(x: float, y: float) -> float:
    return x + y

Why do we need type annotations?

Python type annotations offer significant advantages in modern software development:

Early Bug Detection. Type annotations help catch potential type-related issues early in the development process. By identifying errors in the IDE or CI pipeline, they prevent bugs from reaching production, saving time and reducing risks. This is especially crucial for industrial-scale applications where downtime is expensive.
Safer refactoring. Immediate feedback on type mismatches makes code changes smoother and more reliable. Developers can confidently modify code with real-time type checking support.
Reduce the need for unit testing. Type annotations minimize the need for extensive type-checking tests, allowing developers to focus on writing tests that validate core business logic rather than basic type compatibility.
Better code clarity. Unlike traditional docstrings, type annotations are compiler-checked and always in sync with the code. They provide clear, immediate insights into function inputs and outputs, making code more readable and self-documenting.

Example: Type safety in coordinate handling

Let's see how type annotations can prevent common errors using a simple geographic coordinate formatting function.

1. Starting Point: Untyped Code

Consider the following function that formats latitude and longitude:

def get_location_untyped(lat, lon):  # Error: Type of parameter "lat" is unknown
    return f"Latitude: {lat:.6f}, Longitude: {lon:.6f}"

This code can lead to multiple issues:

We can call it with incorrect types (e.g., str instead of float)

get_location_untyped("59.32", "18.06")

We can accidentally swap latitude and longitude values

get_location_untyped(59.32, 18.06)
get_location_untyped(18.06, 59.32)

Neither issue will be caught until runtime

2. Adding Basic Type Annotations

We can add basic type annotations to the function signature to specify the expected input types and return type.

def get_location_typed(lat: float, lon: float) -> str:
    return f"Latitude: {lat:.6f}, Longitude: {lon:.6f}"

The IDE and type checkers can now detect type-related errors before runtime. (e.g., passing str instead of float) at development time

get_location_typed("59.32", "18.06")  # Error: "Literal['18.06']" is not assignable to "float"

However, this still doesn't prevent accidentally swapping parameters:

get_location_typed(59.32, 18.06)
get_location_typed(18.06, 59.32)

3. Domain-Driven Type Safety

One feature of domain-driven design is to create distinct types for values that are semantically different. For example, instead of using a generic float type for both a lat and lon you would create specific types like Lat and Lon to represent these values. This helps in making the code more expressive and reducing the possibility of errors.

A less known feature in Python is NewType from the typing module. NewType is a great option for creating distinct types for values that are semantically different but share the same underlying type.

While subclassing is an alternative, NewType offers a more lightweight approach to type safety with zero runtime overhead.

from typing import NewType  # noqa: E402

Lat = NewType("Lat", float)
Lon = NewType("Lon", float)


def get_location(lat: Lat, lon: Lon) -> str:
    return f"Latitude: {lat:.6f}, Longitude: {lon:.6f}"

Swapping the parameters will now raise a type error at compile time.

get_location(Lat(59.32), Lon(18.06))
get_location(Lon(18.06), Lat(59.32))  # Error: "Lon" is not assignable to "Lat",  "Lat" is not assignable to "Lon"

Static Type Checking

Static type checking occurs without running the program. This is a standard feature in languages like Java and C#, where it is integrated into the compilation phase, and is required for identifying type mismatches and potential errors before an executable can be produced.

In Python, static type checking is optional. You can add type hints to your code, and use a static type checker to catch type errors before running the code. You can think of it as debugging your code up-front.

Static Type Checkers

There are several static type checkers available for Python:

Pyright by Microsoft is a full-featured, standards-based static type checker for Python.
MyPY by Dropbox et al. is an optional static type checker for Python that aims to combine the benefits of dynamic (or "duck") typing and static typing.
Pyre by Facebook is a performant type checker for Python compliant with PEP 484. Pyre can analyze codebases with millions of lines of code incrementally.
Pytype by Google checks and infers types for your Python code without requiring type annotations.

In this blog post, we will use Pyright, a fast type checker for Python that is written in TypeScript and integrated with Visual Studio Code through the Pylance extension.

Installing and Setup

Enable Pylance in Visual Studio Code.

If you are using the Python extension for Visual Studio Code, it will automatically install Pylance.

Configure the type checking level in your pyproject.toml file:

[tool.pyright] typeCheckingMode = "strict"  # Options: "off", "basic", "standard", "strict"

Basic Type Annotations

For basic type annotations, we will cover annotating primitive types, container types and simple functions.

Primitive types

These types represent single values rather than collections. Below are examples of the most common primitive type annotations:

from typing import Literal

speakers: int = 2
talk: str = "Python type annotations"
active: bool = True
pi: float = 3.14159
number: int | None = 42
status: Literal["active", "inactive"] = "active"
# .. is the same as
status: Literal["active"] | Literal["inactive"] = "active"

Container types

A container is a type that can hold multiple values, such as list, tuple, set, and dict. The inner type of the container must also be annotated. For example, a list of integers can be annotated as list[int].

Below we can see that attempting to add incompatible values to our containers results in errors:

xs: list[int] = [1, 2, 3]
xs.append("2")  # Error: "Literal['2']" is not assignable to "int"

ts: tuple[int, str] = (1, "test")

us: set[int | str] = {1, 2, 3, "test"}

vs: dict[str, int] = {"one": 1, "two": 2}
vs["one"] = 2
vs["three"] = "three"  # Error: "Literal['three']" is not assignable to "int"

Annotating Functions

Function annotations in Python allow us to specify both parameter types and return types. The syntax uses colons : for parameter annotation and an arrow -> for the return type annotation.

Here's an example with a divide function that accepts two float parameters, and returns a union type of float or None, this is also called an optional type:

def divide(a: float, b: float) -> float | None:
    if b == 0:
        return None
    return a / b

When working with functions that return union types, the type checker will prevent us from directly using the result since it might be None. For example, the following code will flag an error:

from typing import reveal_type  # noqa: E402

result = divide(10, 20)
reveal_type(result)  # Type of "result" is "float | None"

d = result + 1  # Error: Operator "+" not supported for "None"

To safely use the result, we need to perform type narrowing through conditional checks. There is a specific section that will cover type narrowing in more detail, showing various ways to safely work with union types. For now, we will ensure that the result is a float before we can use it in an arithmetic operation.

if result is not None:
    d = result + 1  # OK

Note: In this post we will be using the function reveal_type to ask the static type checker to reveal the inferred type of its argument.

Most type checkers support reveal_type() even if the name is not imported from typing. However, to avoid runtime errors it should be imported from the typing module. At runtime, this function prints the runtime type of its argument and returns the argument unchanged.

Type Inference

Type inference is a powerful feature that allows programming languages to automatically determine variable types without explicit type annotations.

MyPy and Pyright will try to infer the type of unannotated variables and parameters based on context. Pyright will also try to infer the type of unannotated return types, while MyPy will interpret unannotated return types as Any.

For example, when a variable is assigned a specific value, type checkers can infer a precise type:

from typing import reveal_type  # noqa: E402

a = 10
reveal_type(a)  # Type of "a" is "Literal[10]"

Complementing Type Inference

Despite its convenience, type inference has limitations. In some cases, type inference is not enough to understand the type of a variable and developers often need to provide additional type information in several scenarios:

Giving a broader type to an object

The type checker will assume that if we initialize a list with a homogenous set of objects, probably that's what we intended.

xs = [1, 2, 3]
reveal_type(xs)  # Type of "xs" is "list[int]"
xs.append("2")  # Error: "Literal['2']" is not assignable to "int"

# allow a broader type than the one inferred
xz: list[int | str] = [1, 2, 3]
xz.append("2")

Restrict new types assigned to a variable

To enforce type consistency throughout an application type annotations can ensure that subsequent value assignments are compatible with the initially declared type.

# Variable type changes dynamically without type annotation
x = 10
reveal_type(x)  # Type of "x" is "Literal[10]"

# Redeclare the variable with a different type
x = "10"
reveal_type(x)  # Type of "x" is "Literal['10']"

# Annotate a variable to restrict the type
xx: int = 10
reveal_type(xx)  # Type of "xx" is "Literal[10]"
xx = "10"  # Error: Type "Literal['10']" is not assignable to declared type "int"

Initialize empty containers

Empty containers are initially typed as Any, requiring explicit type specification:

lst_ = []
reveal_type(lst_)  # Type of "lst" is "Any"
lst_.append(1)  # Error: Type of "append" is partially unknown

# Specify the expected type
lst: list[int] = []
lst.append(1)

Validating function output types

Type annotations serve as a powerful mechanism for ensuring type correctness, particularly when dealing with external or untyped code. By explicitly defining expected return types, developers can intercept type mismatches during code refactoring, prevent silent type-related errors from spreading through the application and create a robust type verification layer for third-party or legacy functions.

# Third-party function without type annotations
def get_status():
    return "active"


# Enforcing type constraints within the application
type Status = Literal["active", "inactive"]
status: Status = get_status()

Any vs. object

In Python, Any and object are two special types that can be used to represent unknown, any or arbitrary types. However, they have different semantics and use cases.

object is the base class for all Python objects. It can be used to represent any object in Python, and it is often used when the specific type of an object is not important.
Any is a special type that can also represent any value. However, the Any type is far more flexible than object because it effectively opts out of type checking all-together. It will allow any operation to be performed on the value. Any other value can be assigned to the value, and a value with type Any can be assigned to a variable of any other type.

Using Any can be tempting since it solves most type related issues you might have. But you should be very cautious when using Any, since it opts out of type checking and can lead to runtime errors. Using object is a much safer choice when the specific type of an object is not important.

The following example demonstrates the difference between Any and object:

from typing import Any  # noqa: E402


# This function passes type checking
def process_any(x: Any) -> None:
    x.arbitrary_method()  # No complaints
    _ = x + 5  # No complaints
    x["key"]  # No complaints


# This function raises type checker warnings
def process_object(x: object) -> None:
    x.arbitrary_method()  # Error: Cannot access attribute "arbitrary_method" for class "object"
    _ = x + 5  # Error: Operator "+" not supported for "object" and "Literal[5]"
    x["key"]  # Error: __getitem__ not supported for class "object"

Type Narrowing

Type narrowing is the act of making the type of a variable more narrow or specific e.g. that Animal is actually a Cat, or that Optional[int] i.e int | None in some cases must be int (or just None). This can be done by using special type narrowing expressions, statements and type guards.

While these checks are performed at runtime, static type checkers also use these constructs for type narrowing during static analysis. By narrowing the type of a variable, we can write more type-safe code and catch errors at compile time rather than at runtime.

In this section, we will also discuss type casting and why it should be avoided.

The following examples will use the divide function from the previous section:

def divide(a: float, b: float) -> float | None:
    if b == 0:
        return None
    return a / b


result = divide(10, 20)

Type Narrowing Expressions

There are several built-in expressions in Python that can be used to narrow the type of a variable. These include:

isinstance - Check if an object is an instance of a class.

from typing import reveal_type  # noqa: E402

if isinstance(result, float):
    reveal_type(result)  # Type of "result" is "float"
else:
    reveal_type(result)  # Type of "result" is "None"

issubclass - Check if a class is a subclass of another class.

# pyright does not support giving expressions to isinstance, https://github.com/microsoft/pyright/issues/3565
# so issubclass(type(result), str)  will not narrow the type of result

result_type = type(result)
reveal_type(result_type)  # Type of "result_type" is "type[float] | type[None]"

if issubclass(result_type, float):
    reveal_type(result_type)  # Type of "result_type" is "type[float]"
else:
    reveal_type(result_type)  # Type of "result_type" is "type[None]"

callable - Check if an object is callable.

from collections.abc import Callable  # noqa: E402


def factory() -> Callable[[float, float], float | None] | None:
    return divide


divide_ = factory()
reveal_type(divide_)  # Type of "divide_" is "((float, float) -> (float | None)) | None"

if callable(divide_):
    reveal_type(divide_)  # Type of "divide_" is "(float, float) -> (float | None)"
else:
    reveal_type(divide_)  # Type of "divide_" is "None"

is - Check if two objects are the same.

if result is not None:
    reveal_type(result)  # Type of "result" is "float"
else:
    reveal_type(result)  # Type of "result" is "None"

Type Narrowing Statements

There are several built-in statements in Python that can be used to narrow the type of a variable. These include:

if - Check if a value is truthy.

In the previous example, we use an if statement to check if result is not None. This narrows the type of result within the if block to float, allowing us to safely perform operations that require a float type. If result is None, the else block handles that case separately.

assert - Assert if a value is truthy.

An assert statement will be executed at runtime, and if the condition fails, an AssertionError is raised.

assert result
reveal_type(result)  # Type of "result" is "float | int"

match - Check a value against a series of patterns.

The match statement is a new feature in Python 3.10 that allows us to match a value against a series of patterns and execute the corresponding block of code. The match statement can be used to narrow the type of a variable based on the pattern that matches the value. Using the match statement is essentially a more concise way of writing isinstance checks, but it can be more readable and ensures that the check is exhaustive so that no case if left unchecked.

result = divide(10, 20)
match result:
    case float(f) | int(f):
        reveal_type(f)  # Type of "f" is "float | int"
    case None:
        reveal_type(result)  # Type of "result" is "None"

User Defined Type Guards

We can add our own type guards for custom types as well. Type guards are special functions that help the type checker narrow down the type of a variable based on runtime checks. They return a boolean value and have a special return type TypeGuard, which indicates to the type checker that the function is a type guard and can be used to narrow the type of a variable to the specified type.

Type guards are functional at runtime, affecting the program's flow based on their checks, but they are also used by static type checkers to narrow the types during static analysis.

In the following example, we define a type guard all_int that checks if all elements in a list are of type int. This allows the type checker to narrow the type of the list based on the result of the check.

from typing import Any, TypeGuard  # noqa: E402


def all_int(xs: list[Any]) -> TypeGuard[list[int]]:
    return all(isinstance(x, int) for x in xs)


xs = [1, 2, 3, "test"]  # list[int | str]

if all_int(xs):
    reveal_type(xs)  # Type of "xs" is "list[int]"
else:
    reveal_type(xs)  # Type of "xs" is "list[int | str]"

Type Casting

Type casting is used to explicitly specify a different type for a variable. Using cast doesn't actually change the type of a variable at runtime; it only informs the type checker to treat the variable as a different type without performing any runtime type conversion.

from typing import cast  # noqa: E402


def process_data(data: object) -> str:
    # We might know this is actually a string, but the type checker doesn't
    return cast(str, data).upper()


# Usage
result = process_data("hello")
reveal_type(result)  # Type of "result" is "str"

It should be avoided if possible, since it can hide mistakes and lead to runtime errors.

a = 1
b = cast(str, a)
reveal_type(b)  # Type of "b" is "str"

# cast is omitted in runtime, so this will raise a TypeError
print(b + "c")  # TypeError: unsupported operand type(s) for +: 'int' and 'str'

Static Duck Typing and Protocols

Python is well-known for its duck typing, a programming approach that focuses on what an object can do rather than what it is. If an object implements the methods and attributes we need, we can work with it regardless of its class hierarchy. This flexibility is great, but it raises an interesting challenge:

How do we combine duck typing's dynamic nature with static type annotations?

Let's explore this concept with an example:

We will define two classes Rabbit and Fox which share a common method called feed:

class Rabbit:
    def run(self) -> str:
        return "Rabbit is running"

    def feed(self) -> str:
        return "Rabbit is eating"


class Fox:
    def say(self) -> str:
        return "Ring-ding-ding-ding!"

    def feed(self) -> str:
        return "Fox is eating"

And a function that takes an animal parameter and calls its feed method:

def care_for_animal_untyped(animal):  # Error: Type of parameter "animal" is unknown
    animal.feed()  # Error: Type of "feed" is unknown
    ...


care_for_animal_untyped(Rabbit())
care_for_animal_untyped(Fox())

How can we type the animal parameter?

We have several options, but each has drawbacks:

Creating an Animal base class would limit the flexibility of duck typing.
Using Union[Rabbit, Fox] would restrict us to specific types.
Using Any would disable type checking entirely, allowing objects without a feed method.

A better approach is to use Protocols, which enable static duck typing (also known as structural subtyping). Protocols let us define a set of methods that a class must implement without requiring inheritance from a base class.

To create a protocol, we use the Protocol base class from the typing module. In the following example, we define a CareFor protocol that requires the implementation of a feed method:

from typing import Protocol, runtime_checkable  # noqa: E402


@runtime_checkable
class CareFor(Protocol):
    def feed(self) -> str: ...


def care_for_animal(animal: CareFor):
    animal.feed()
    ...


care_for_animal(Rabbit())
care_for_animal(Fox())

The type checker ensures that the animal parameter in the care_for_animal function will accept any class that has a method feed. Trying to use a class without the required methods will raise a type error:

# This would fail type checking
class Dog:
    """A class that doesn't implement the CareFor protocol."""

    def bark(self) -> str:
        return "Woof!"


care_for_animal(Dog())  # Error: Dog doesn't implement CareFor protocol

Note: The use of the @runtime_checkable decorator is required to enable runtime type checking using isinstance. Without it, the CareFor protocol would not be recognized as a valid type at runtime:

assert isinstance(Rabbit(), CareFor)

You can use Protocol types just like any other type annotation:

animal: CareFor = Rabbit()
animals: list[CareFor] = [Rabbit(), Fox()]

Protocols are meant to define a set of methods and attributes that a class must implement, but they are not meant to be instantiated themselves:

animal = CareFor()  # Error: Cannot instantiate protocol class "CareFor"

Built-in Protocols

The typing module includes several protocol classes that represent common Python interfaces. Let's take a look at a few of them:

Iterable[T]: implements__iter__ method.

In the example below, the class BookCollection contains an __iter__ method, which means it adheres to the iterable protocol and can be used wherever Iterable[T] is expected, such as in a for loop.

Iterable[T] is a generic type. Generics are covered in more detail in Part 2 of this series.

class BookCollection:
    def __init__(self):
        self.books: list[tuple[str, str]] = []

    def add_book(self, title: str, author: str):
        self.books.append((title, author))

    def __iter__(self):
        return iter(self.books)


library = BookCollection()
library.add_book("1984", "George Orwell")

for title, author in library:
    print(f"{title} by {author}")

Container[T]: implements __contains__ method.

In the example below, the class TagCollection contains a __contains__ method, which means it adheres to the container protocol and can be used wherever Container[T] is expected, such as in the in operator.

Container[T] is a generic type. Generics are covered in more detail in Part 2 of this series.

class TagCollection:
    def __init__(self):
        self.tags: set[str] = set()

    def add_tag(self, tag: str):
        self.tags.add(tag.lower())

    def __contains__(self, item: str):
        return item.lower() in self.tags


tags = TagCollection()
tags.add_tag("Python")
tags.add_tag("Programming")

print("python" in tags)  # True
print("Java" in tags)  # False

SupportsFloat: implements __float__ method.

In the example below, the class Temperature contains a __float__ method, which means it adheres to the SupportsFloat protocol and can be used wherever SupportsFloat is expected, such as in the float() function.

from typing import SupportsFloat  # noqa: E402


class Temperature:
    def __init__(self, celsius: float):
        self._celsius = celsius

    def __float__(self) -> float:
        return self._celsius


def celsius_to_kelvin(celcius: SupportsFloat) -> float:
    return float(celcius) + 273.15


temp = Temperature(25.0)
kelvin = celsius_to_kelvin(temp)

Protocol Inheritance

Protocols can be extended like regular classes, but with an important distinction:

Just inheriting from an existing Protocol creates a regular class that implements the Protocol.
To create a new Protocol, you must explicitly include Protocol in the inheritance.

class AdvancedCare(CareFor, Protocol):
    """Protocol for animals requiring advanced care."""

    def groom(self) -> str: ...
    def exercise(self) -> str: ...

Functions and Callables

We have already seen that we can annotate functions with type hints. These annotations ensure both proper function usage and correct handling of the return value.

Python functions can take many forms and perform a variety of tasks. You can create functions that accept other functions as inputs, functions that produce new functions as outputs, and functions that handle a flexible number of arguments including default parameters, variadic arguments (*args) and keyword arguments (**kwargs). Functions can also act as generators using yield or run asynchronously using async and await.

In addition, Python also includes a broader concept called "callables" - essentially anything you can execute using parentheses. This category encompasses regular functions, class methods, and classes that implement the __call__ method. For more complex scenarios, you can define callable protocols, that can be used to specify precise signatures for these callable objects.

Basic Functions

Let's review how to annotate basic functions.

Below is a simple function that adds two integers. The type hints a: int and b: int specify that both parameters must be integers, while -> int indicates that the function returns an integer.

from typing import reveal_type


def sum_two(a: int, b: int) -> int:
    return a + b


result = sum_two(10, 20)
reveal_type(result)  # Type of "result" is "int"

Variadic Arguments

Variadic arguments are variable-length arguments often referred to as *args in Python, which allow us to pass a variable number of positional arguments to the function.

Annotate *args with the same type

Let's take a look at how we can annotate variadic arguments of the same type. In the example below, we have a function sum_all that takes a variable number of integers and returns their sum:

def sum_all(*args: int) -> int:
    reveal_type(args)  # Type of "args" is "tuple[int, ...]"
    return sum(args)


sum_all(1, 2, 3)
sum_all(1, 2, 3, 4, 5)

The type of the args variable is a tuple with an ellipsis ... at the end. A tuple annotated as tuple[T, ...] means that all the elements are of the same type, in this case the args variable is a tuple of ints.

Annotate *args with different types

To annotate variadic arguments of different types, we can define a predefined tuple that contains the different types, and we can use it with the star * operator to unpack it. In this example, calling foo with only one argument will raise an error:

type Args = tuple[int, str, float]


def foo(*args: *Args) -> None:
    reveal_type(args)  # Type of "args" is "tuple[int, str, float]"
    ...


foo(42, "test", 10.3)
foo(42)  # Error: Arguments missing for parameters "args[1]", "args[2]"

--- Note: Defining a predefined tuple will restrict the number of arguments that can be passed to the function. To allow for a variable number of arguments of different types, we can use Variadic Generics. We will cover this in more detail in Part 2.

Keyword Arguments

Keyword arguments are also variable-length arguments, often referred to as **kwargs in Python, which allow us to pass a variable number of arguments by name in any order, and to specify default values for the arguments.

Annotate **kwargs with the same type

When annotating kwargs with a single type, for example int, the real type of the kwargs parameter is dict[str, int], where the keys are always str representing the parameter names:

def sum_integer_kwargs(**kwargs: int) -> int:
    reveal_type(kwargs)  # Type of "kwargs" is "dict[str, int]"
    return sum(kwargs.values())


sum_integer_kwargs(a=1, b=2, c=3)

Annotate **kwargs with different types

To annotate kwargs with different types, we can use TypeDict from the typing module to specify the name and the type of each of the keyword arguments:

from typing import NotRequired, TypedDict, Unpack  # noqa: E402


class Person(TypedDict):
    name: str
    age: int
    is_student: bool
    address: NotRequired[str]  # optional parameter


def greet(**kwargs: Unpack[Person]) -> None:
    reveal_type(kwargs)  # Type of "kwargs" is "Person"
    ...


greet(name="John", age=20, is_student=True)
greet(name="John", age=20)  # Error: Argument missing for parameter "is_student"

Note:

We cannot use the ** to unpack a TypeDict, instead we need to use Unpack from the typing module.
TypeDict does not support assigning default values. To annotate kwargs with default values we can use Callback Protocols which we will cover in the next section.
Similarly as with *args, defining a TypedDict will restrict the number of arguments that can be passed to the function. To annotate kwargs with a variable number of arguments of different types, we can use Parameter Specification. We will cover this in more detail in Part 2.

What is the benefit of unpacking typed tuples and dictionaries instead of just annotating each of the arguments as normal positional and keyword arguments?

The main benefit might not be obvious at first, but it allows us to define a data model outside the function. This way, the function can depend on the data model instead of needing to know about the specific arguments.

In Part 2, we will see that we can combine tuple unpacking with variadic generics to avoid limiting the number of arguments. For example, the first argument can be pinned to a specific type, while the rest of the arguments can be of any type.

Callables

We can also annotate callables. This is useful, for example, for functions that take other functions as arguments, or functions that return functions. A callable can be annotated using the Callable form, which takes a list of argument types and a return type. For instance, Callable[[int],str] represents a function that takes an int and returns a str.

In the example below, we have a mapper function that converts an int to a str. We also have a map function that takes a mapper function with a list of ints, and returns a list of strs. The map function applies the mapper to each element in the list, converting each int to a str:

from collections.abc import Callable  # noqa: E402


def mapper(number: int) -> str:
    return str(number)


def map(
    mapper: Callable[[int], str],
    source: list[int],
) -> list[str]:
    return [mapper(x) for x in source]


xs = [1, 2, 3]
ys = map(mapper, xs)
reveal_type(ys)  # Type of "ys" is "list[str]

Lambda Functions

We can also use lambdas to define the mapper function. Using lambdas
can make the code more compact since you don't need to define a separate
function, and naming such a function can sometimes be challenging.

However, it is not possible to annotate lambda parameters with type
hints. The type checker will have to infer the type of the lambda from
the context.

zs = map(lambda x: str(x), xs)
reveal_type(lambda x: str(x))  # Type of "lambda x: str(x)" is "(x: Unknown) -> str" # Error: Argument type is unknown
reveal_type(zs)  # Type of "zs" is "list[str]"

You can always try to help the type checker by providing a type
annotation for the variable. However, note that some linters will warn
against assigning lambda functions to a variable.

# Warning: Do not assign a `lambda`expression, use a `def`
mapper_: Callable[[int], str] = lambda x: str(x)  # noqa: E731

Callback Protocols

One limitation with the Callable form is that it doesn't allow us to specify variadic arguments like *args or **kwargs. Therefore, we cannot specify optional parameters with default values.

In the example below, we have a function callback that takes two arguments, but we have no way of specifying that the second argument is optional. As a result, we get an error when we try to call the cb function with only one argument:

def callback(a: int, b: int | None = None) -> int:
    return a + (b or 20)


def use_callback(cb: Callable[[int, int | None], int]) -> int:
    return cb(10)  # Error: Expected 1 more positional argument


use_callback(callback)

To address these issues, we can use callback protocols. A callback protocol is a Protocol class that defines a __call__ method. This method can have any number of positional or keyword parameters with or without default values. The type checker will check that the __call__ method matches with the signature of the function that uses such a callback protocol.

In the example below, we define a KeyboardEvent protocol with a __call__ method that takes a keycode parameter and an optional completed keyword parameter. The on_event function matches this signature. The KeyboardEvent protocol ensures that any function passed to the register function adheres to this signature:

from typing import Protocol  # noqa: E402


class KeyboardEvent(Protocol):
    def __call__(self, keycode: int, *, completed: bool = False) -> None: ...


def on_event(keycode: int, *, completed: bool = False) -> None:
    # Handle the event
    ...


def register(event_callback: KeyboardEvent) -> None:
    ...
    event_callback(keycode=10)
    ...
    event_callback(keycode=10, completed=True)


register(on_event)

This concludes part 1 of our exploration into type annotations in Python. We've covered the basics of type annotations, type narrowing, structural sub-typing, and callables. By using these techniques, you can improve code readability, catch potential bugs early and ensure type safety in your Python projects.

In Part 2 of this series, we will build on these fundamentals and explore more advanced features such as generics, variadic generics, paramspec, and overloads.

DEV Community: Cardamom Code

Python Type Annotations (part 3)

Table of contents

Variance in Generics

Covariance

Covariance And Function Return Types

Custom Covariant Generic Classes

Covariance summarized

Contravariance

Example: Function Arguments

Cat -> Animal

This works because a function that takes a Cat is compatible with a function that

takes an Animal.

Animal -> Cat

We get an error here because a function that takes an Animal is not compatible with

a function that takes a Cat. This is because the function might take a Dog.

(*) Type parameter "_T_co@Iterable" is covariant, but "Animal" is not a subtype of "Cat"

Custom Contravariant Generic Classes

Summary

Invariance in Generics

References

Python Type Annotations (part 2)

Table of contents

Generics

Generic classes

Generic Type Aliases

How to restrict Generic Type Parameters

Why to restrict Generic Type Parameters

Using unions

Using overloads

Using a constrained generic type

Using a base class

Using a bound generic type parameter

Using a bound generic protocol

More about bound generic protocols

Variadic Generics

Classes with Variadic Generics

Functions with Variadic Generics

Callables with Variadic Generics

Parameter Specification

Type Annotating Decorators

Concatenating Type Parameters

Overloads

Final Notes

References

Python Type Annotations (part 1)

Table of contents

What are Type Annotations?

Why do we need type annotations?

Example: Type safety in coordinate handling

Static Type Checking

Static Type Checkers

Installing and Setup

Basic Type Annotations

Primitive types

Container types

Annotating Functions

Type Inference

Complementing Type Inference

Any vs. object

Type Narrowing

Type Narrowing Expressions

Type Narrowing Statements

User Defined Type Guards

Type Casting

Static Duck Typing and Protocols

Built-in Protocols

Protocol Inheritance

Functions and Callables

Basic Functions

Variadic Arguments

Annotate *args with the same type

Annotate *args with different types

Keyword Arguments

Annotate **kwargs with the same type

Annotate **kwargs with different types

Callables

Lambda Functions

Callback Protocols

References