Decorators and typing all 3 written

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21# A function that takes a function and returns a replacement for it.
def announced(func):
    def wrapper(*args, **kwargs):
        print(f"   calling {func.__name__}")
        result = func(*args, **kwargs)
        print(f"   {func.__name__} returned {result!r}")
        return result
    return wrapper

def add(a, b):
    return a + b

# The decorator applied manually: rebind the name to the wrapper.
add = announced(add)

print("add(2, 3):")
total = add(2, 3)
print("->", total)

test("the wrapped function still works", total, 5)
test("the name now refers to the wrapper", add.__name__, "wrapper")

add(2, 3):
   calling add
   add returned 5
-> 5
ok   the wrapped function still works
ok   the name now refers to the wrapper

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18def announced(func):
    def wrapper(*args, **kwargs):
        print(f"   calling {func.__name__}")
        return func(*args, **kwargs)
    return wrapper

@announced                      # identical to: multiply = announced(multiply)
def multiply(a, b):
    return a * b

print("multiply(3, 4):")
print("->", multiply(3, 4))

print()
print("The two forms are the same operation. @ just puts it before the def,")
print("so a reader sees the decoration before reading the body.")

test("the decorated function works", multiply(3, 4), 12)

multiply(3, 4):
   calling multiply
-> 12

The two forms are the same operation. @ just puts it before the def,
so a reader sees the decoration before reading the body.
   calling multiply
ok   the decorated function works

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40import functools

def naive(func):
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    return wrapper

def careful(func):
    @functools.wraps(func)          # copy the metadata across
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    return wrapper

@naive
def documented_a(x):
    """Does something useful."""
    return x

@careful
def documented_b(x):
    """Does something useful."""
    return x

print("without wraps:")
print("   __name__:", documented_a.__name__)
print("   __doc__: ", documented_a.__doc__)

print("with wraps:")
print("   __name__:", documented_b.__name__)
print("   __doc__: ", documented_b.__doc__)

# wraps also keeps a reference to the original, which is occasionally vital.
print()
print("the original is reachable:", documented_b.__wrapped__.__name__)

test("without wraps the identity is lost", documented_a.__name__, "wrapper")
test("and so is the docstring", documented_a.__doc__, None)
test("wraps restores both", (documented_b.__name__, documented_b.__doc__),
     ("documented_b", "Does something useful."))
test("and keeps the original reachable", documented_b.__wrapped__.__name__, "documented_b")

without wraps:
   __name__: wrapper
   __doc__:  None
with wraps:
   __name__: documented_b
   __doc__:  Does something useful.

the original is reachable: documented_b
ok   without wraps the identity is lost
ok   and so is the docstring
ok   wraps restores both
ok   and keeps the original reachable

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35import functools, time

def timed(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        start = time.perf_counter()
        try:
            return func(*args, **kwargs)
        finally:
            wrapper.last_duration = time.perf_counter() - start
    return wrapper

@timed
def slow_sum(n):
    return sum(range(n))

result = slow_sum(200_000)
print("result:", result)
print(f"took:   {slow_sum.last_duration:.6f}s")

# The finally means the timing is recorded even when the function raises.
@timed
def fails():
    raise ValueError("boom")

try:
    fails()
except ValueError:
    pass
print()
print("timing was still recorded on failure:", fails.last_duration >= 0)

test("the decorated function returns the right answer", result, sum(range(200_000)))
test("the duration was recorded", slow_sum.last_duration > 0, True)
test("and recorded even when the call raised", fails.last_duration >= 0, True)

result: 19999900000
took:   0.002802s

timing was still recorded on failure: True
ok   the decorated function returns the right answer
ok   the duration was recorded
ok   and recorded even when the call raised

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27import functools

def repeat(times):                      # 1. takes the ARGUMENT
    def decorator(func):                # 2. takes the FUNCTION
        @functools.wraps(func)
        def wrapper(*args, **kwargs):   # 3. takes the CALL's arguments
            results = [func(*args, **kwargs) for _ in range(times)]
            return results
        return wrapper
    return decorator

@repeat(times=3)
def greet(name):
    return f"hi {name}"

print("greet('ada'):", greet("ada"))

# Written out without @, the three layers are visible:
def shout(text):
    return text.upper()

shout = repeat(2)(shout)
print("shout('hey'): ", shout("hey"))

test("the argument controlled the repetition", greet("ada"), ["hi ada", "hi ada", "hi ada"])
test("and the manual form is identical", shout("hey"), ["HEY", "HEY"])
test("wraps still preserved the name", greet.__name__, "greet")

greet('ada'): ['hi ada', 'hi ada', 'hi ada']
shout('hey'):  ['HEY', 'HEY']
ok   the argument controlled the repetition
ok   and the manual form is identical
ok   wraps still preserved the name

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46import functools

# A decorator that works both with and without arguments, which is what
# library code does to be forgiving. The trick: detect whether it was handed
# a function or an argument.
def retry(func=None, *, attempts=3):
    def decorator(f):
        @functools.wraps(f)
        def wrapper(*args, **kwargs):
            last = None
            for attempt in range(1, attempts + 1):
                try:
                    return f(*args, **kwargs)
                except ValueError as exc:
                    last = exc
            raise last
        return wrapper
    # Called as @retry -> func is the function. As @retry(...) -> func is None.
    return decorator if func is None else decorator(func)

calls = []

@retry                          # no brackets
def flaky_a():
    calls.append("a")
    if len(calls) < 2:
        raise ValueError("not yet")
    return "a succeeded"

@retry(attempts=5)              # with brackets
def flaky_b():
    calls.append("b")
    raise ValueError("always fails")

print("flaky_a():", flaky_a())
try:
    flaky_b()
except ValueError as exc:
    print("flaky_b() gave up after 5:", exc)

print()
print("call log:", calls)

test("the bare form works", flaky_a.__name__, "flaky_a")
test("the argument form respected attempts=5", calls.count("b"), 5)
test("and the last exception was re-raised", len(calls) > 5, True)

flaky_a(): a succeeded
flaky_b() gave up after 5: always fails

call log: ['a', 'a', 'b', 'b', 'b', 'b', 'b']
ok   the bare form works
ok   the argument form respected attempts=5
ok   and the last exception was re-raised

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35import functools

def outer(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        return f"outer({func(*args, **kwargs)})"
    return wrapper

def inner(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        return f"inner({func(*args, **kwargs)})"
    return wrapper

@outer
@inner
def value():
    return "x"

print("result:", value())
print()
print("@inner is applied FIRST (it is closest to the def), then @outer wraps")
print("that. So the equivalent assignment is: value = outer(inner(value))")

# Reversing the order reverses the nesting.
@inner
@outer
def other():
    return "x"

print()
print("reversed:", other())

test("the decorator nearest the def is applied first", value(), "outer(inner(x))")
test("and swapping them swaps the nesting", other(), "inner(outer(x))")

result: outer(inner(x))

@inner is applied FIRST (it is closest to the def), then @outer wraps
that. So the equivalent assignment is: value = outer(inner(value))

reversed: inner(outer(x))
ok   the decorator nearest the def is applied first
ok   and swapping them swaps the nesting

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25import functools

def logged(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        # self arrives as args[0] -- *args is what makes this work unchanged.
        print(f"   {func.__name__} called on {type(args[0]).__name__}")
        return func(*args, **kwargs)
    return wrapper

class Account:
    def __init__(self, balance):
        self.balance = balance

    @logged
    def deposit(self, amount):
        self.balance += amount
        return self.balance

a = Account(100)
print("deposit(50):")
print("->", a.deposit(50))

test("the method still mutates the instance", a.balance, 150)
test("and the decorator saw the instance", a.deposit(0), 150)

deposit(50):
   deposit called on Account
-> 150
ok   the method still mutates the instance
   deposit called on Account
ok   and the decorator saw the instance

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28import functools

def logged(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    return wrapper

class Broken:
    @logged            # wrong: this wraps the property OBJECT, not the getter
    @property
    def value(self):
        return 42

got = Broken().value
print("reading .value gave a:", type(got).__name__)
print("which is not 42, and did not raise")

# The error only appears when something tries to use it.
try:
    got()
except TypeError as exc:
    print()
    print("calling it:", exc)

test("reading the attribute silently returns a method, not the value",
     type(got).__name__, "method")
test("so nothing raised at the point of the mistake", got is not None, True)

reading .value gave a: method
which is not 42, and did not raise

calling it: 'property' object is not callable
ok   reading the attribute silently returns a method, not the value
ok   so nothing raised at the point of the mistake

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19import functools

def logged(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    return wrapper

class Correct:
    @property          # outermost
    @logged            # wraps the getter itself
    def value(self):
        return 42

print("value:", Correct().value, "<- the value, not a method")
print("the class attribute is a property:", isinstance(Correct.value, property))

test("property outermost gives the value", Correct().value, 42)
test("and the attribute really is a property", isinstance(Correct.value, property), True)

value: 42 <- the value, not a method
the class attribute is a property: True
ok   property outermost gives the value
ok   and the attribute really is a property

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26import functools

class CountCalls:
    """A decorator with state, written as a class."""

    def __init__(self, func):
        functools.update_wrapper(self, func)     # the wraps equivalent
        self.func = func
        self.count = 0

    def __call__(self, *args, **kwargs):
        self.count += 1
        return self.func(*args, **kwargs)

@CountCalls
def ping():
    return "pong"

ping(); ping(); ping()
print("result:", ping())
print("calls: ", ping.count)
print("name preserved:", ping.__name__)

test("the function works", ping(), "pong")
test("the decorator counted every call", ping.count, 5)
test("update_wrapper preserved the name", ping.__name__, "ping")

result: pong
calls:  4
name preserved: ping
ok   the function works
ok   the decorator counted every call
ok   update_wrapper preserved the name

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23from functools import cache
import time

calls = []

@cache                       # unbounded; lru_cache(maxsize=None) is the same thing
def fibonacci(n):
    calls.append(n)
    if n < 2:
        return n
    return fibonacci(n - 1) + fibonacci(n - 2)

print("fibonacci(30) =", fibonacci(30))
print("distinct arguments computed:", len(set(calls)))
print("total calls to the body:    ", len(calls))
print()
print("Without the cache this recursion makes over a million calls.")
print("cache info:", fibonacci.cache_info())

test("the answer is right", fibonacci(30), 832040)
test("each argument was computed once", len(calls), len(set(calls)))
test("which is 31 distinct values for n=0..30", len(set(calls)), 31)
test("and later calls are pure cache hits", fibonacci.cache_info().hits > 0, True)

fibonacci(30) = 832040
distinct arguments computed: 31
total calls to the body:     31

Without the cache this recursion makes over a million calls.
cache info: CacheInfo(hits=28, misses=31, maxsize=None, currsize=31)
ok   the answer is right
ok   each argument was computed once
ok   which is 31 distinct values for n=0..30
ok   and later calls are pure cache hits

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24from functools import lru_cache

computed = []

@lru_cache(maxsize=2)        # room for two results only
def square(n):
    computed.append(n)
    return n * n

square(1); square(2)         # both cached
square(1)                    # a hit -- 1 is now the most recently used
square(3)                    # evicts the least recent, which is 2
square(2)                    # recomputed, because it was evicted

print("arguments actually computed:", computed)
print("cache info:", square.cache_info())

# The cache can be inspected and cleared.
square.cache_clear()
print("after cache_clear:", square.cache_info())

test("2 had to be recomputed after eviction", computed, [1, 2, 3, 2])
test("the cache never held more than maxsize", square.cache_info().maxsize, 2)
test("cache_clear empties it", square.cache_info().currsize, 0)

arguments actually computed: [1, 2, 3, 2]
cache info: CacheInfo(hits=1, misses=4, maxsize=2, currsize=2)
after cache_clear: CacheInfo(hits=0, misses=0, maxsize=2, currsize=0)
ok   2 had to be recomputed after eviction
ok   the cache never held more than maxsize
ok   cache_clear empties it

1
2
3
4
5
6
7from functools import cache

@cache
def total(values):
    return sum(values)

total([1, 2, 3])

Traceback (most recent call last):
  File "example.py", line 7, in <module>
    total([1, 2, 3])
    ~~~~~^^^^^^^^^^^
TypeError: unhashable type: 'list'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18from functools import cache

@cache
def total(values):
    return sum(values)

# The fix: accept something hashable at the boundary.
print("with a tuple:", total((1, 2, 3)))

# Or wrap, so callers can still pass a list.
def total_from_list(values):
    return total(tuple(values))

print("via a wrapper:", total_from_list([1, 2, 3]))

test("a tuple works as a cached argument", total((1, 2, 3)), 6)
test("and converting at the boundary keeps the caller's convenience",
     total_from_list([1, 2, 3]), 6)

with a tuple: 6
via a wrapper: 6
ok   a tuple works as a cached argument
ok   and converting at the boundary keeps the caller's convenience

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39from functools import lru_cache

class Heavy:
    def __init__(self, label):
        self.label = label

    @lru_cache(maxsize=None)        # the cache lives on the CLASS, not the instance
    def compute(self):
        return f"computed for {self.label}"

# Each instance that calls compute() is stored in the class-level cache forever.
for i in range(3):
    Heavy(f"item{i}").compute()

print("cache entries:", Heavy.compute.cache_info().currsize)
print("Those three instances cannot be garbage collected, because the cache")
print("on the CLASS is still holding each 'self' as part of its key.")

# The safe patterns: cached_property for per-instance, or cache a plain function.
class Better:
    def __init__(self, label):
        self.label = label

    def compute(self):
        return _compute(self.label)     # cache keyed on the VALUE, not on self

@lru_cache(maxsize=None)
def _compute(label):
    return f"computed for {label}"

print()
print("Better:", Better("x").compute())
print("keyed on the label only, so no instance is retained")

test("the method cache retained one entry per instance",
     Heavy.compute.cache_info().currsize, 3)
test("the value-keyed version still caches", _compute("x"), _compute("x"))
test("and its cache holds one entry for one label",
     _compute.cache_info().currsize, 1)

cache entries: 3
Those three instances cannot be garbage collected, because the cache
on the CLASS is still holding each 'self' as part of its key.

Better: computed for x
keyed on the label only, so no instance is retained
ok   the method cache retained one entry per instance
ok   the value-keyed version still caches
ok   and its cache holds one entry for one label

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40from functools import cached_property

class Report:
    def __init__(self, rows):
        self.rows = rows
        self.computations = 0

    @property
    def total_uncached(self):
        self.computations += 1
        return sum(self.rows)

    @cached_property
    def total_cached(self):
        self.computations += 1
        return sum(self.rows)

r = Report([1, 2, 3])

r.total_uncached, r.total_uncached, r.total_uncached
uncached_count = r.computations
print("plain property, read 3 times -> computed", uncached_count, "times")

r.computations = 0
r.total_cached, r.total_cached, r.total_cached
cached_count = r.computations
print("cached_property, read 3 times -> computed", cached_count, "time")

# It is stored in the instance dict, so it can be invalidated by deleting it.
print()
print("stored on the instance:", "total_cached" in r.__dict__)
del r.total_cached
r.computations = 0
r.total_cached
print("after deleting it, recomputed:", r.computations, "time")

test("a plain property recomputed on all three reads", uncached_count, 3)
test("cached_property computed only once", cached_count, 1)
test("the result is stored on the instance", "total_cached" in r.__dict__, True)
test("deleting the attribute forces a recompute", r.computations, 1)

plain property, read 3 times -> computed 3 times
cached_property, read 3 times -> computed 1 time

stored on the instance: True
after deleting it, recomputed: 1 time
ok   a plain property recomputed on all three reads
ok   cached_property computed only once
ok   the result is stored on the instance
ok   deleting the attribute forces a recompute

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30from functools import partial

def power(base, exponent):
    return base ** exponent

# Fix the first argument positionally.
powers_of_two = partial(power, 2)
print("powers_of_two(10):", powers_of_two(10))

# Or fix a later one by keyword.
square = partial(power, exponent=2)
cube = partial(power, exponent=3)
print("square(7):", square(7))
print("cube(3):  ", cube(3))

# A real use: supplying a configured function where a plain one is expected.
lines = ["10", "1010", "ff"]
as_binary = partial(int, base=2)
print()
print("parsed as binary:", [as_binary(x) for x in lines[:2]])
print("parsed as hex:   ", int("ff", base=16))

# partial keeps what it was built from, which is useful when debugging.
print()
print("func:", powers_of_two.func.__name__, " args:", powers_of_two.args)

test("a positional argument can be fixed", powers_of_two(10), 1024)
test("and a keyword one", (square(7), cube(3)), (49, 27))
test("partial composes with built-ins", as_binary("1010"), 10)
test("and records what it was built from", powers_of_two.args, (2,))

powers_of_two(10): 1024
square(7): 49
cube(3):   27

parsed as binary: [2, 10]
parsed as hex:    255

func: power  args: (2,)
ok   a positional argument can be fixed
ok   and a keyword one
ok   partial composes with built-ins
ok   and records what it was built from

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29from functools import reduce
import math
import operator

numbers = [1, 2, 3, 4]

# reduce folds a sequence into one value.
print("reduce(add):", reduce(operator.add, numbers))
print("but sum() exists:", sum(numbers))

print()
print("reduce(mul):", reduce(operator.mul, numbers))
print("and math.prod exists:", math.prod(numbers))

# Where reduce is genuinely useful: a fold with no built-in equivalent.
words = ["apple", "fig", "cherry"]
longest = reduce(lambda a, b: a if len(a) >= len(b) else b, words)
print()
print("longest via reduce:", longest)
print("but max(key=len) is clearer:", max(words, key=len))

# An initial value matters for an empty sequence.
print()
print("reduce with initial on empty:", reduce(operator.add, [], 0))

test("reduce can add", reduce(operator.add, numbers), 10)
test("and sum agrees", sum(numbers), reduce(operator.add, numbers))
test("max with a key is equivalent to that fold", max(words, key=len), longest)
test("an initial value makes the empty case safe", reduce(operator.add, [], 0), 0)

reduce(add): 10
but sum() exists: 10

reduce(mul): 24
and math.prod exists: 24

longest via reduce: cherry
but max(key=len) is clearer: cherry

reduce with initial on empty: 0
ok   reduce can add
ok   and sum agrees
ok   max with a key is equivalent to that fold
ok   an initial value makes the empty case safe

1
2
3
4from functools import reduce
import operator

reduce(operator.add, [])

Traceback (most recent call last):
  File "example.py", line 4, in <module>
    reduce(operator.add, [])
    ~~~~~~^^^^^^^^^^^^^^^^^^
TypeError: reduce() of empty iterable with no initial value

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49from functools import singledispatch
from datetime import date
from decimal import Decimal

# The pattern this replaces: a growing isinstance chain in one function.
def describe_by_chain(value):
    if isinstance(value, int):
        return f"int: {value}"
    if isinstance(value, (list, tuple)):
        return f"sequence of {len(value)}"
    if isinstance(value, date):
        return f"date: {value.isoformat()}"
    return f"something: {value!r}"

# The same behaviour, dispatched on the argument's type.
@singledispatch
def describe(value):
    return f"something: {value!r}"       # the fallback

@describe.register
def _(value: int):
    return f"int: {value}"

@describe.register
def _(value: list):
    return f"sequence of {len(value)}"

@describe.register
def _(value: date):
    return f"date: {value.isoformat()}"

values = [1, [1, 2], date(2026, 1, 1), "x"]
for v in values:
    print(f"  {repr(v):>22}  {describe(v)}")

print()
print("Registering a new type does not touch the existing function -- which")
print("is the whole difference from editing an isinstance chain.")

# It dispatches on the MRO, so a bool (a subclass of int) finds the int handler.
print()
print("describe(True):", describe(True), "<- bool is a subclass of int")

test("each registered type gets its own implementation",
     [describe(v) for v in values],
     [describe_by_chain(v) for v in values])
test("the fallback catches unregistered types", describe("x"), "something: 'x'")
test("dispatch follows the MRO, so bool uses the int handler", describe(True), "int: True")
test("and the registry is introspectable", date in describe.registry, True)

                       1  int: 1
                  [1, 2]  sequence of 2
  datetime.date(2026, 1, 1)  date: 2026-01-01
                     'x'  something: 'x'

Registering a new type does not touch the existing function -- which
is the whole difference from editing an isinstance chain.

describe(True): int: True <- bool is a subclass of int
ok   each registered type gets its own implementation
ok   the fallback catches unregistered types
ok   dispatch follows the MRO, so bool uses the int handler
ok   and the registry is introspectable

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41from functools import total_ordering, wraps

# total_ordering, from lesson 29: define __eq__ and one comparison, get the rest.
@total_ordering
class Weight:
    def __init__(self, grams):
        self.grams = grams

    def __eq__(self, other):
        return self.grams == other.grams

    def __lt__(self, other):
        return self.grams < other.grams

a, b = Weight(100), Weight(200)
print("a < b :", a < b)
print("a <= b:", a <= b)
print("a > b :", a > b)
print("a >= b:", a >= b)
print("derived methods:", sorted(
    m for m in ("__le__", "__gt__", "__ge__") if m in Weight.__dict__
))

# wraps, from lesson 36: the one line every decorator needs.
def noop(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    return wrapper

@noop
def documented():
    """Kept."""
    return 1

print()
print("wraps kept:", documented.__name__, "/", documented.__doc__)

test("total_ordering derived the other comparisons", (a <= b, a > b, a >= b), (True, False, False))
test("and they were added to the class", "__le__" in Weight.__dict__, True)
test("wraps preserved the identity", documented.__name__, "documented")

a < b : True
a <= b: True
a > b : False
a >= b: False
derived methods: ['__ge__', '__gt__', '__le__']

wraps kept: documented / Kept.
ok   total_ordering derived the other comparisons
ok   and they were added to the class
ok   wraps preserved the identity

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17def repeat(text: str, times: int) -> str:
    return text * times

# Correct use.
print("repeat('ab', 2):", repeat("ab", 2))

# Entirely wrong types. The annotation does not object.
print("repeat([1], 3): ", repeat([1], 3), "<- a list, and it worked")
print("repeat('x', True):", repeat("x", True), "<- a bool where int was promised")

# The annotations are just data hanging off the function.
print()
print("annotations:", repeat.__annotations__)

test("the annotated use works", repeat("ab", 2), "abab")
test("a wrong type is not rejected", repeat([1], 3), [1, 1, 1])
test("annotations are only recorded", set(repeat.__annotations__), {"text", "times", "return"})

repeat('ab', 2): abab
repeat([1], 3):  [1, 1, 1] <- a list, and it worked
repeat('x', True): x <- a bool where int was promised

annotations: {'text': <class 'str'>, 'times': <class 'int'>, 'return': <class 'str'>}
ok   the annotated use works
ok   a wrong type is not rejected
ok   annotations are only recorded

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46from typing import Any

# Builtin generics, since 3.9 -- no typing.List needed.
def totals(rows: list[dict[str, int]]) -> dict[str, int]:
    out: dict[str, int] = {}
    for row in rows:
        for key, value in row.items():
            out[key] = out.get(key, 0) + value
    return out

print(totals([{"a": 1}, {"a": 2, "b": 3}]))

# Unions with |, since 3.10. Optional[X] is just X | None.
def parse(text: str) -> int | None:
    try:
        return int(text)
    except ValueError:
        return None

print()
print("parse('12'):", parse("12"))
print("parse('x'): ", parse("x"))

# Tuples: fixed length, or homogeneous with ...
def pair() -> tuple[str, int]:
    return ("a", 1)

def many() -> tuple[int, ...]:
    return (1, 2, 3)

print()
print("fixed-length tuple:", pair())
print("variable-length:   ", many())

# Callable, and Any as the deliberate escape hatch.
from collections.abc import Callable

def apply_twice(fn: Callable[[int], int], value: int) -> int:
    return fn(fn(value))

print()
print("apply_twice:", apply_twice(lambda n: n + 3, 1))

test("builtin generics work", totals([{"a": 1}, {"a": 2}]), {"a": 3})
test("a union return is just a normal return", (parse("12"), parse("x")), (12, None))
test("Callable describes a function parameter", apply_twice(lambda n: n * 2, 3), 12)

{'a': 3, 'b': 3}

parse('12'): 12
parse('x'):  None

fixed-length tuple: ('a', 1)
variable-length:    (1, 2, 3)

apply_twice: 7
ok   builtin generics work
ok   a union return is just a normal return
ok   Callable describes a function parameter

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32from typing import get_type_hints

def transfer(amount: int, note: str = "") -> bool:
    return amount > 0

# __annotations__ is the raw form; get_type_hints resolves strings and defaults.
print("raw:     ", transfer.__annotations__)
print("resolved:", get_type_hints(transfer))

# It works on classes too, which is how dataclasses and validation libraries
# read your field types.
class Account:
    owner: str
    balance: int = 0

print()
print("class hints:", get_type_hints(Account))

# Forward references -- a name not defined yet -- are written as strings and
# resolved later. This is the one case where the string form is required.
class Node:
    def __init__(self, value: int, parent: "Node | None" = None):
        self.value = value
        self.parent = parent

print()
print("forward reference resolved:", get_type_hints(Node.__init__)["parent"])

test("get_type_hints resolves the annotations", get_type_hints(transfer)["amount"], int)
test("it reads class-level annotations", get_type_hints(Account)["balance"], int)
test("and resolves a string forward reference",
     get_type_hints(Node.__init__)["parent"] is not None, True)

raw:      {'amount': <class 'int'>, 'note': <class 'str'>, 'return': <class 'bool'>}
resolved: {'amount': <class 'int'>, 'note': <class 'str'>, 'return': <class 'bool'>}

class hints: {'owner': <class 'str'>, 'balance': <class 'int'>}

forward reference resolved: __main__.Node | None
ok   get_type_hints resolves the annotations
ok   it reads class-level annotations
ok   and resolves a string forward reference

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24from typing import TypedDict

class Movie(TypedDict):
    title: str
    year: int

correct: Movie = {"title": "Arrival", "year": 2016}
print("correct:", correct)
print("its actual type:", type(correct).__name__)

# Constructed with completely wrong types. Nothing objects at runtime.
wrong = Movie(title=1, year="not a year")
print()
print("wrong types accepted:", wrong)
print("still just a dict:   ", type(wrong).__name__)

# And it is a dict, so every dict operation works.
print()
print("keys:", list(correct))
print("get with a default:", correct.get("director", "unknown"))

test("a TypedDict is a plain dict at runtime", type(correct).__name__, "dict")
test("wrong value types are not rejected", wrong["title"], 1)
test("and dict methods all work", correct.get("director", "unknown"), "unknown")

correct: {'title': 'Arrival', 'year': 2016}
its actual type: dict

wrong types accepted: {'title': 1, 'year': 'not a year'}
still just a dict:    dict

keys: ['title', 'year']
get with a default: unknown
ok   a TypedDict is a plain dict at runtime
ok   wrong value types are not rejected
ok   and dict methods all work

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25from typing import Protocol, runtime_checkable

class Renderable(Protocol):
    def render(self) -> str: ...

# Neither of these inherits from Renderable.
class Button:
    def render(self) -> str:
        return "[Button]"

class Heading:
    def render(self) -> str:
        return "# Heading"

class NotRenderable:
    pass

def draw(items: list[Renderable]) -> str:
    return " ".join(item.render() for item in items)

print("draw:", draw([Button(), Heading()]))
print("neither inherits from the protocol:", Button.__bases__)

test("structural typing needs no inheritance", draw([Button()]), "[Button]")
test("and the classes are unrelated to the protocol", Renderable in Button.__mro__, False)

draw: [Button] # Heading
neither inherits from the protocol: (<class 'object'>,)
ok   structural typing needs no inheritance
ok   and the classes are unrelated to the protocol

1
2
3
4
5
6
7
8
9
10from typing import Protocol

class Renderable(Protocol):
    def render(self) -> str: ...

class Button:
    def render(self) -> str:
        return "[Button]"

isinstance(Button(), Renderable)

Traceback (most recent call last):
  File "example.py", line 10, in <module>
    isinstance(Button(), Renderable)
    ~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^
  File "<python>/lib/python3.14/typing.py", line 2048, in __instancecheck__
    raise TypeError("Instance and class checks can only be used with"
                    " @runtime_checkable protocols")
TypeError: Instance and class checks can only be used with @runtime_checkable protocols

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25from typing import Protocol, runtime_checkable

@runtime_checkable
class Renderable(Protocol):
    def render(self) -> str: ...

class Button:
    def render(self) -> str:
        return "[Button]"

class Misleading:
    def render(self, extra, arguments, entirely_wrong):
        return "?"

class Nothing:
    pass

print("Button:     ", isinstance(Button(), Renderable))
print("Nothing:    ", isinstance(Nothing(), Renderable))
print("Misleading: ", isinstance(Misleading(), Renderable), "<- signature NOT checked")

test("a conforming class passes", isinstance(Button(), Renderable), True)
test("a class without the method fails", isinstance(Nothing(), Renderable), False)
test("but only the method's existence is checked, not its signature",
     isinstance(Misleading(), Renderable), True)

Button:      True
Nothing:     False
Misleading:  True <- signature NOT checked
ok   a conforming class passes
ok   a class without the method fails
ok   but only the method's existence is checked, not its signature

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35from typing import get_type_hints

# PEP 695 syntax: the type parameter is declared in brackets.
def first[T](items: list[T]) -> T:
    return items[0]

print("first([1, 2]):      ", first([1, 2]))
print("first(['a', 'b']):  ", first(["a", "b"]))
print("hints:", get_type_hints(first))

# A generic class.
class Box[T]:
    def __init__(self, item: T) -> None:
        self.item = item

    def get(self) -> T:
        return self.item

box_of_int = Box(5)
print()
print("Box(5).get():", box_of_int.get())
print("Box[int] is a real object:", Box[int])

# Constraining the parameter: T must support <
def largest[T: (int, float, str)](items: list[T]) -> T:
    return max(items)

print()
print("largest([3, 1]):    ", largest([3, 1]))
print("largest(['a', 'z']):", largest(["a", "z"]))

test("a generic function works for any type", (first([1, 2]), first(["a"])), (1, "a"))
test("a generic class works too", Box(5).get(), 5)
test("and can be subscripted", Box[int] is not None, True)
test("a constrained parameter still just runs", largest([3, 1]), 3)

first([1, 2]):       1
first(['a', 'b']):   a
hints: {'items': list[T], 'return': T}

Box(5).get(): 5
Box[int] is a real object: __main__.Box[int]

largest([3, 1]):     3
largest(['a', 'z']): z
ok   a generic function works for any type
ok   a generic class works too
ok   and can be subscripted
ok   a constrained parameter still just runs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25# Over-annotated: every line states what is already obvious.
def over(values: list[int]) -> int:
    total: int = 0
    index: int = 0
    for value in values:
        doubled: int = value * 2
        total = total + doubled
        index = index + 1
    return total

# The same function, annotated only where it helps: the signature.
def measured(values: list[int]) -> int:
    total = 0
    for value in values:
        total += value * 2
    return total

print("over:    ", over([1, 2, 3]))
print("measured:", measured([1, 2, 3]))
print()
print("Both are equally checkable: a checker infers the locals from the signature.")

test("both produce the same answer", over([1, 2, 3]), measured([1, 2, 3]))
test("the useful annotations are on the signature",
     set(measured.__annotations__), {"values", "return"})

over:     12
measured: 12

Both are equally checkable: a checker infers the locals from the signature.
ok   both produce the same answer
ok   the useful annotations are on the signature