Using List/Tuple/etc. from typing vs directly referring type as list/tuple/etc

Question

What's the difference of using List, Tuple, etc. from typing module:

from typing import Tuple

def f(points: Tuple):
    return map(do_stuff, points)

As opposed to referring to Python's types directly:

def f(points: tuple):
    return map(do_stuff, points)

And when should I use one over the other?

Answer 1

typing.Tuple and typing.List are Generic types; this means you can specify what type their contents must be:

def f(points: Tuple[float, float]):
    return map(do_stuff, points)

This specifies that the tuple passed in must contain two float values. You can't do this with the built-in tuple type.

typing.Tuple is special here in that it lets you specify a specific number of elements expected and the type of each position. Use ellipsis if the length is not set and the type should be repeated: Tuple[float, ...] describes a variable-length tuple with floats.

For typing.List and other sequence types you generally only specify the type for all elements; List[str] is a list of strings, of any size. Note that functions should preferentially take typing.Sequence as arguments and typing.List is typically only used for return types; generally speaking most functions would take any sequence and only iterate, but when you return a list, you really are returning a specific, mutable sequence type.

You should always pick the typing generics even when you are not currently restricting the contents. It is easier to add that constraint later with a generic type as the resulting change will be smaller.