Language

Control flow

if / elif / else

def classify(n):
  if n < 0:
    return "negative"
  elif n == 0:
    return "zero"
  else:
    return "positive"

for x in [-3, 0, 7]:
  print(classify(x))

{}

negative
zero
positive

Output

while

n, total = 5, 0
while n > 0:
  total += n
  n -= 1
print(total)

{}

Output

while … else

The else runs when the loop ends without break.

x = 0
while x < 3:
  x += 1
else:
  print("loop finished cleanly")

{}

loop finished cleanly

Output

for

for iterates any iterable. Lists, tuples, dicts, sets, ranges, strings and generators all work.

for ch in "abc":
  print(ch)

{}

a
b
c

Output

The loop variable takes the same targets as assignment, nested and starred ones included. Tuple unpacking lists them.

pairs = [("a", 1), ("b", 2), ("c", 3)]
for key, value in pairs:
  print(key, value)

{}

a 1
b 2
c 3

Output

break and continue

break exits the loop. continue skips to the next item. Both work in for and while.

for i in range(10):
  if i == 5:
    break
  if i % 2 == 0:
    continue
  print(i)

{}

1
3

Output

for … else

The else runs when the loop exhausts its iterator without break. It fits a search that reports a miss.

def search(items, target):
  for i, item in enumerate(items):
    if item == target:
      print("found at", i)
      break
  else:
    print("not found")

search([4, 5, 6], 5)
search([4, 5, 6], 9)

{}

found at 1
not found

Output

match / case

match tries each case in order and runs the first one whose pattern fits the subject.

Pattern	Example	Matches
Literal	`0`, `-1.5`, `"a"`, `b"x"`	An equal value
Singleton	`True`, `False`, `None`	The same object. `case True` rejects `1`
Capture	`x`	Anything, bound to the name
Wildcard	`_`	Anything, bound to nothing
OR	`1 \| 2 \| 3`	Any of the alternatives
`as` capture	`[x, y] as pair`	The inner pattern, bound to the name
Sequence	`[a, *rest]`, `(a, b)`, `a, b`	A list or tuple of that shape
Mapping	`{"k": p, **rest}`	A dict holding those literal keys
Class	`Point(x, y=0)`, `int(n)`	An instance whose attributes match
Dotted name	`Color.RED`	A value equal to that attribute

A few rules shape how the patterns combine.

A guard such as case x if x < 0 adds a condition after the pattern.
Adjacent string or bytes literals join into one literal.
Parentheses without a comma only group. (x) is the capture x.
Items of a sequence pattern can be any pattern, nested sequences, OR groups and as captures included.
A sequence pattern matches only list and tuple subjects. A str, bytes or any other value fails it and falls through to the next case.
A mapping pattern matches only dicts. **rest collects the other keys.
A class pattern checks isinstance and reads positional items through __match_args__. On a builtin type such as int(n) the positional item is the subject itself.

Literals, OR patterns, guards and the wildcard.

def sign(n):
  match n:
    case 0:
      return 'zero'
    case 1 | 2 | 3:
      return 'small'
    case x if x < 0:
      return 'negative'
    case _:
      return 'other'

print(sign(0), sign(2), sign(-7), sign(99))

{}

zero small negative other

Output

Sequence patterns.

def shape(seq):
  match seq:
    case []:
      return 'empty'
    case [x]:
      return f'single {x}'
    case [x, y] if x == y:
      return 'pair-equal'
    case [first, *rest]:
      return f'{first} then {len(rest)} more'

print(shape([]))
print(shape([5]))
print(shape([3, 3]))
print(shape([1, 2, 3, 4]))

{}

empty
single 5
pair-equal
1 then 3 more

Output

Mapping patterns.

def describe(cfg):
  match cfg:
    case {"host": h, "port": p, **rest}:
      return f"{h}:{p} {rest}"
    case {"host": h}:
      return f"{h}:80"
    case _:
      return "no host"

print(describe({"host": "api", "port": 443, "tls": True}))
print(describe({"host": "api"}))
print(describe(["host"]))

{}

api:443 {'tls': True}
api:80
no host

Output

Class patterns.

class Point:
  __match_args__ = ("x", "y")
  def __init__(self, x, y):
    self.x, self.y = x, y

def where(p):
  match p:
    case Point(0, 0):
      return "origin"
    case Point(x, y=0):
      return f"on the x axis at {x}"
    case Point(x, y):
      return f"at {x}, {y}"
    case int(n):
      return f"int {n}"

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

{}

origin
on the x axis at 3
at 1, 2
int 7

Output

Dotted names compare by value.

class Color:
  RED = 1
  GREEN = 2

def name(c):
  match c:
    case Color.RED:
      return "red"
    case Color.GREEN:
      return "green"
    case _:
      return "other"

print(name(1), name(2), name(3))

{}

red green other

Output

try / except / else / finally

def safe_div(a, b):
  try:
    return a / b
  except ZeroDivisionError:
    return None

print(safe_div(10, 2))
print(safe_div(10, 0))

{}

5.0
None

Output

A try statement has up to four kinds of clauses.

An except handler names one exception, a tuple of exceptions, or nothing.
A bare except catches everything.
else runs when the try body raised nothing.
finally always runs.

try:
  x = int("42")
except (ValueError, TypeError):
  x = -1
else:
  print("parsed", x)
finally:
  print("cleanup")

{}

parsed 42
cleanup

Output

# Bare except catches everything
try:
  {}["missing"]
except:
  print("caught")

{}

caught

Output

Handlers match subclasses. except Exception catches ValueError, RuntimeError, KeyError and the rest of the exception hierarchy.

try:
  raise RuntimeError("boom")
except Exception:
  print("subclass caught")

{}

subclass caught

Output

raise

raise takes an exception class or an instance. Any other value, such as raise "boom", raises TypeError with the message “exceptions must derive from BaseException”.

def positive(n):
  if n < 0:
    raise ValueError
  return n

try:
  positive(-1)
except ValueError:
  print("rejected")

{}

rejected

Output

A bare raise inside an except block re-raises the exception being handled.

def attempt():
  try:
    raise ValueError("bad")
  except ValueError:
    print("logging")
    raise

try:
  attempt()
except ValueError as e:
  print("outer", e.args[0])

{}

logging
outer bad

Output

raise X from Y raises X with Y as its __cause__. An exception raised while another is handled keeps that one as its __context__, and from None hides it. An uncaught chain prints each exception in turn.

try:
  try:
    {}["port"]
  except KeyError as e:
    raise ValueError("bad config") from e
except ValueError as e:
  print(type(e.__cause__).__name__, e.__suppress_context__)

{}

KeyError True

Output

with

with runs the context manager protocol in three steps.

Evaluate the expression.
Call __enter__ and bind its result to the as target.
On exit, call __exit__(exc_type, exc_value, traceback).

The arguments of __exit__ are (None, None, None) on a clean exit. On an exception they are the exception type and value, and traceback is always None.

Several managers in one with nest. The last one enters last and exits first.

class Tag:
  def __init__(self, name):
    self.name = name
  def __enter__(self):
    print("enter", self.name)
    return self.name
  def __exit__(self, exc_type, exc_value, traceback):
    print("exit", self.name, exc_type, exc_value, traceback)
    return False

with Tag("a") as x, Tag("b") as y:
  print(x, y)

try:
  with Tag("c"):
    raise ValueError("bad")
except ValueError:
  print("propagated")

{}

enter a
enter b
a b
exit b None None None
exit a None None None
enter c
exit c <class 'ValueError'> bad None
propagated

Output

What __exit__ returns or raises decides how the block ends.

A truthy return suppresses the exception. A falsy one lets it propagate.
Each manager has its own handler. When an inner one suppresses, the outer ones exit with (None, None, None).
If __exit__ raises, the new exception replaces the original.

class Suppress:
  def __enter__(self):
    return self
  def __exit__(self, *exc):
    return True

with Suppress():
  raise ValueError("gone")
print("suppressed")

{}

suppressed

Output

Cleanup on early exit

finally and __exit__ run on every way out of a block. That includes normal completion, exceptions, return, break and continue. A return or break inside finally replaces the original exit.

class Lock:
  def __enter__(self):
    return self
  def __exit__(self, *exc):
    print("released")

def take(n):
  with Lock():
    if n < 0:
      return "negative"
    return n * 2

print(take(5))
print(take(-1))

for i in range(3):
  try:
    if i == 1:
      break
  finally:
    print("tick", i)

{}

released
10
released
negative
tick 0
tick 1

Output

assert

def reciprocal(n):
  assert n != 0, "n must be non-zero"
  return 1 / n

print(reciprocal(4))

{}

0.25

Output

A failed assertion raises AssertionError. The message after the comma evaluates only on failure. It becomes the exception argument in e.args.

try:
  assert 1 == 2, "math broke"
except AssertionError as e:
  print(e.args[0])

{}

math broke

Output

del

del removes a binding. It works on plain names, attributes (del obj.attr), indexed positions (del seq[i]) and parenthesized groups (del (a, b)).

x = 42
del x
try:
  print(x)
except NameError:
  print("gone")

xs = [1, 2, 3]
del xs[1]
print(xs)

{}

gone
[1, 3]

Output

pass

pass does nothing. Use it where the grammar requires a block.

for i in range(3):
  pass
print("done")

{}

done

Output

FunctionsParameters, closures, generators and decorators.Limits and errorsThe exception hierarchy and what raises each error.