Python 3.12 Preview: Static Typing Improvements

Generic Classes and Functions

You’ve seen how you use TypeVar to define type variables. In Python 3.12, you don’t need to explicitly declare type variables when you’re defining generic classes. Instead, you can use the following syntax:

# generic_queue.py

from collections import deque

class Queue[T]:
    def __init__(self) -> None:
        self.elements: deque[T] = deque()

    def push(self, element: T) -> None:
        self.elements.append(element)

    def pop(self) -> T:
        return self.elements.popleft()

The syntax Queue[T] implies that you’re defining a generic class parametrized by T. Note that this implicitly defines T as a type variable that you can refer to within the class definition.

In addition to the cleaner syntax, the fact that you don’t need to import Generic or TypeVar or explicitly define T makes your code cleaner and more readable.

Pyright already supports the new syntax. However, when you’re using it, you need to explicitly tell Pyright that you’re using Python 3.12 syntax:

$ pyright --pythonversion 3.12 generic_queue.py
0 errors, 0 warnings, 0 informations

You can provoke the type checker similarly to earlier if you want to see the kind of errors that it can report.

So far, you’ve looked at generic classes. You can also define generic functions. These are functions that can handle several different types in their parameters.

As an example, you’ll implement push_and_pop() which can push an element to the end of a generic list and pop one off the front of it. First, you’ll implement it with the old syntax for type variables:

# list_helpers.py

from typing import TypeVar

T = TypeVar("T")

def push_and_pop(elements: list[T], element: T) -> T:
    elements.append(element)
    return elements.pop(0)

As earlier, you declare that T is a type variable. Then you use T as part of your annotations of push_and_pop(). In particular, you make sure that element matches the type of the elements already in the list.

You can experiment with the function to see that it allows you to use a list as a dynamic queue where an element pops off each time you insert a new one:

>>> from list_helpers import push_and_pop

>>> elements = [28, 1]
>>> push_and_pop(elements, 23)
28
>>> push_and_pop(elements, 10)
1

>>> elements
[23, 10]

You start with a list with two elements. When you insert 23 at the back of the list, then you’re also removing the first element, 28.

In Python 3.12, you can use the new syntax for such generic functions as well. Like you would for the generic class syntax, you declare the type variable inside square brackets:

# list_helpers.py

def push_and_pop[T](elements: list[T], element: T) -> T:
    elements.append(element)
    return elements.pop(0)

Again, note that you don’t need to declare the type variable any longer, apart from listing it within the square brackets.

This code is equivalent to the one above. There’s one significant difference, though. In the earlier example, T is defined in the global scope and is available outside the definition of push_and_pop(). In the latter code block, T is only available in annotations within the function.

In the examples that you’ve explored so far, the type variables could take on any type. This is often the case with collections that can contain any type of object. Type variables can also be useful in cases where the type is more constrained. You’ll look more closely at this in the next section.

Constrained and Bounded Type Variables

Sometimes you have a function that can take arguments of several—but not all—different types. Type variables support this through constraints and bounds:

• A constrained type variable takes on one of a fixed set of possible types.
• A bounded type variable takes on the type of the boundary type or one of its subtypes.

You’ll investigate both constrained and bounded type variables in this section and learn how the new syntax supports them.

As an example, say that you’re wrapping the concatenation operator (+) in a function to make combining strings more explicit:

# concatenation.py

def concatenate(first: str, second: str) -> str:
    return first + second

This function adds two strings together to form a new string. Your motivation for adding concatenate() is that it names the operation properly. You can use it to combine two strings as follows:

>>> from concatenation import concatenate

>>> concatenate("twenty", "twentythree")
'twentytwentythree'

In the type hints, you’ve noted that concatenate() is meant to work on strings. Technically, there are many objects in Python that you could add together. However, you wouldn’t necessarily call the operation concatenation. Therefore, your function doesn’t semantically support numbers.

However, there’s another type where + represents concatenation: bytes objects. You can also use concatenate() on them. For example, you can combine the following bytes literals:

>>> from concatenation import concatenate

>>> concatenate(b"twenty", b"twentythree")
b'twentytwentythree'

The only visible difference from strings is the b prefix indicating that each quoted element is a bytes object. You’d like the type hints to include bytes in addition to str.

You can do this by defining a constrained type variable. In the old syntax, this looked as follows:

# concatenation.py

from typing import TypeVar

T = TypeVar("T", str, bytes)

def concatenate(first: T, second: T) -> T:
    return first + second

In the declaration of T, you constrain T such that only str and bytes are valid types. If you try to concatenate two numbers, then the type checker will warn you, but the code will run. This T can only be str or bytes, and no other types are valid.

The new syntax also supports constraints. You can add type constraints in a literal tuple:

# concatenation.py

def concatenate[T: (str, bytes)](first: T, second: T) -> T:
    return first + second

As earlier, you declare T by adding it to the function definition inside square brackets. Additionally, you note that T must be either str or bytes by specifying those types in a tuple literal separated from T by a colon.

A related use case concerns bounded type variables. A bounded type variable is also limited by a specific type—its boundary type. In contrast to constrained type variables, bounded type variables can materialize as subtypes of their boundary type. For example, a type variable bounded by str can be represented by str or any subclass of str.

In the following example, you implement inspect(), which provides a simple description of a string. This function is meant to help with debugging, so it returns the original string, such that you can insert inspect() in the middle of the original processing.

You also define Words as a subclass of str. This is the start of a word-oriented string type where you only override how to calculate the length of a string:

# inspect_string.py

class Words(str):
    def __len__(self):
        return len(self.split())

def inspect[S: str](text: S) -> S:
    print(f"'{text.upper()}' has length {len(text)}")
    return text

The annotation [S: str] says that inspect() is a generic function parametrized by the type variable S. Furthermore, S is bound by str. In practice, this means that the text argument must be a string or a subclass of str. For example, both of the following uses are valid:

>>> from inspect_string import inspect, Words

>>> inspect("Hello, World!")
'HELLO, WORLD!' has length 13
'Hello, World!'

>>> inspect(Words("Hello, World!"))
'HELLO, WORLD!' has length 2
'Hello, World!'

Both the string and the Words subclass are valid arguments to inspect() since you’ve annotated text with a type variable bound to str.

You could’ve defined inspect() as a regular function and used a plain text: str type hint to say the same. You need to use the type variable in order to connect the type of the text argument to the return type of inspect().

You can use constrained and bounded type variables when you define generic classes as well. To do so, you use the same syntax, with the type variable separated by a colon from the constraint or bound. To sum up, compare the syntax of a free, constrained, and bounded type variable:

>>> def free[T](argument: T) -> T: ...

>>> def constrained[T: (str, bytes)](argument: T) -> T: ...

>>> def bounded[T: str](argument: T) -> T: ...

In these examples, T is a type variable:

• In free(), T can be any type.
• In constrained(), T can only be either str or bytes.
• In bounded(), T can be str or any subclass of str.

In addition to generic classes and functions, there’s a third way to use type variables. Namely, you can use them in generic type aliases. You’ll learn more about those in the next section.

Type Aliases

Sometimes, you want to use a different name or alias for a type. This could be because the type is cumbersome to describe. For example, you could be working with data represented as a list of tuples, with each tuple consisting of a string and an integer. In that case, you could define an alias:

ListOfTuples = list[tuple[str, int]]

Another reason for using an alias is to be more descriptive about your data structures. Maybe your list of tuples actually represents a deck of cards. In that case, you can use the type alias to say so:

CardDeck = list[tuple[str, int]]

Originally, type aliases were defined as simple assignments. PEP 613 introduced explicit type aliases to make them less ambigous.

Before Python 3.12, you needed to import TypeAlias from typing to use explicit type aliases:

from typing import TypeAlias

CardDeck: TypeAlias = list[tuple[str, int]]