Skip to content

Compound statements

What TyPy accepts

Item Rule
if, elif and else CST-01
while and for, each with an optional else CST-02
for over range, str, bytes, list, tuple, dict, set, the views of a dict, and enumerate, zip and reversed of them CST-03
try with except clauses, else and finally, described in Exceptions CST-04
for over an instance of a class with __iter__, whose result has __next__ CST-08
iter and next, with or without a default, and for over an iterator CST-09
with, with one or more context managers and as targets CST-05, CST-10
match with literal, value, capture, wildcard, as, \|, sequence, mapping and class patterns and guards CST-06

Example

prices = {"tea": 3, "cake": 5}
for name, price in prices.items():
    if price > 4:
        print(name, "is dear")
    elif price > 2:
        print(name, "is fair")
    else:
        print(name, "is cheap")
for index, letter in enumerate(reversed("abc"), start=1):
    print(index, letter)
count = 0
while count < 3:
    count += 1
else:
    print("counted to", count)

A loop's variable has one type, so a loop over a tuple of mixed items is refused:

for item in (1, "a"):
    print(item)

Matching values

match tries its cases in order and runs the first whose pattern matches the subject and whose guard, the if after the pattern, is true. A literal or a dotted name such as Color.RED matches a subject equal to it, and None, True and False match the subject that is them. A name captures the subject, _ matches anything and binds nothing, p as name binds what p matched, and p | q tries each alternative. When no case matches, the statement does nothing.

def describe(code: int | None) -> str:
    match code:
        case None:
            return "no code"
        case 200 | 201:
            return "ok"
        case 404 as missing:
            return f"missing {missing}"
        case other if other >= 500:
            return f"server {other}"
        case other:
            return f"code {other}"


for code in [200, None, 404, 503, 302]:
    print(describe(code))

A case narrows the subject as the test it stands for does: after case None:, a later case sees an int | None subject as int. A pattern that matches anything, a capture or _, must come last, as CPython requires:

code = 1
match code:
    case other:
        print(other)
    case 1:
        print("one")

Sequence and mapping patterns

[p, q] or (p, q) matches a list, tuple or range of two items whose items match p and q; the brackets do not decide the type. *rest takes the items between the others as a new list, and *_ skips them. A str or bytes subject is not a sequence to a pattern, as in CPython. {"key": p} matches a dict that holds the key with a value matching p, and **rest takes the other items as a new dict.

def describe(command: list[str]) -> str:
    match command:
        case []:
            return "nothing"
        case ["go", direction]:
            return f"going {direction}"
        case ["say", *words]:
            return " ".join(words)
        case [verb, *_]:
            return f"unknown {verb}"
        case _:
            return "not a command"


def size(settings: dict[str, int]) -> str:
    match settings:
        case {"width": width, "height": height, **others}:
            return f"{width}x{height} and {len(others)} more"
        case _:
            return "no size"


print(describe(["go", "north"]), describe(["say", "hi", "there"]))
print(size({"width": 3, "height": 4, "depth": 1}), size({}))

A pattern that no value of the subject's type can match is refused with E0407, as a sequence pattern on a str or a tuple pattern of the wrong length is. A sequence pattern on a union of several sequence types, such as list[int] | tuple[int, int], is planned for 1.0.

Class patterns

Point(x, y=0) matches an instance of Point, or of a class derived from it, whose attributes match: a keyword names the attribute, and a positional sub-pattern takes the name at its position in the class's __match_args__. A dataclass has its fields as __match_args__, unless it is declared with match_args=False; any other class writes the tuple in its body, or takes its base's. For bool, bytes, dict, float, int, list, set, str and tuple, one positional sub-pattern matches the subject itself, so case int(n): binds the number.

from dataclasses import dataclass


@dataclass
class Point:
    x: int
    y: int


def where(point: Point | int) -> str:
    match point:
        case Point(0, 0):
            return "origin"
        case Point(x, 0) | Point(0, x):
            return f"on an axis at {x}"
        case Point(x=x, y=y):
            return f"at {x},{y}"
        case int(n):
            return f"number {n}"


print(where(Point(0, 0)), where(Point(3, 0)), where(Point(1, 2)))
print(where(7))

Where CPython raises TypeError for a class pattern whenever the subject is an instance, TyPy refuses the pattern with E0401: more positional sub-patterns than __match_args__ names, and two sub-patterns for one attribute. A keyword naming an attribute the class does not have is refused as reading that attribute is. A __match_args__ other than a tuple of str literals is planned for 1.0.

Missing cases

When the subject's type is a union, an optional or a bool, TyPy checks that the cases without a guard match every member of it: each class of the union, None, and True and False. A match that does is complete, so where above returns from every case and needs no return after the match. A match that leaves members unmatched gets the warning W0401, which names them (CST-07, ADR-0033):

def switch(state: bool | None) -> str:
    match state:
        case True:
            return "on"
        case None:
            return "unknown"
    return "off"


print(switch(False))

Here W0401 names False. A case covers a member when its pattern matches every value of it: a capture or _, None, True or False, a class pattern whose sub-patterns are captures or _, [*rest] for a list or a tuple, and {} or {**rest} for a dict.

Context managers

with manager as target: calls the manager's __enter__, binds what it returns to the target, and calls __exit__ on every way out of the body: at its end, on return, break and continue, and when an exception leaves it. __exit__ takes the class of the exception, the exception and its traceback, or three None values; its parameters may be left without annotations (CST-10). When it returns a true value, the exception is suppressed and the code after the with runs. Several managers in one with nest, the first outermost.

class Section:
    def __init__(self, title: str) -> None:
        self.title = title

    def __enter__(self) -> str:
        print("begin", self.title)
        return self.title.upper()

    def __exit__(self, kind, error, trace) -> bool:
        print("end", self.title, error)
        return kind is ValueError


with Section("intro") as heading:
    print(heading)
    raise ValueError("handled by __exit__")
print("after")

TyPy keeps no frames in a traceback object, so trace is one object written as <traceback object at 0x...>, or None.

Iterators

A class is iterable when it defines __iter__, which takes only self and returns an instance of a class that defines __next__, often the instance itself. for calls __iter__ once, then __next__ until it raises StopIteration, which ends the loop; any other exception goes on.

class Countdown:
    def __init__(self, start: int) -> None:
        self.current = start

    def __iter__(self) -> "Countdown":
        return self

    def __next__(self) -> int:
        if self.current <= 0:
            raise StopIteration
        self.current -= 1
        return self.current + 1


for number in Countdown(3):
    print(number)

iter(value) gives an iterator over a list, tuple, str, bytes, set, dict or view of a dict, as CPython's: a list iterator sees items appended while it runs, and a set or dict that changes size raises RuntimeError. iter of an iterator gives the iterator itself, and of an instance calls its __iter__. next(iterator) gives the next item, or raises StopIteration at the end; next(iterator, default) gives the default there, which has the item type or is None, making the result optional.

words = iter(["alpha", "beta"])
print(next(words), next(words), next(words, None))

A function takes and returns iterators with the annotations Iterator[T] and Iterable[T], described in Types (TYP-15).