Fundamentals

def greet(name: str, loud: bool = False) -> str:
    """Return a greeting for `name`."""
    msg = f"hello {name}"
    if loud:
        msg = msg.upper()
    return msg
 
 
total = (
    1 + 2
    + 3
)  # brackets continue the expression
print(greet("ada", loud=True), total)

import re
 
a, b = [1, 2], [1, 2]
print(a == b, a is b)  # True False
 
x: int | None = None
print(x is None)  # always compare None with `is`
 
if (m := re.search(r"(\d+)px", "width: 40px")) is not None:
    print(int(m.group(1)))  # 40
 
nums = [3, 8, 1]
if (big := [n for n in nums if n > 2]) and len(big) > 1:
    print(big)  # [3, 8]

for i, name in enumerate(["ann", "bo"], start=1):
    print(i, name)
 
for key, value in {"x": 1, "y": 2}.items():
    print(key, value)
 
for n, ch in zip([1, 2], "ab", strict=True):  # raise
    print(n, ch)                              # on length
                                              # mismatch
for n in range(2, 10):
    if n % 7 == 0:
        print("found", n)
        break
else:  # runs only when the loop did not `break`
    print("none")
 
count = 0
while count < 3:
    count += 1

from dataclasses import dataclass
 
 
@dataclass
class Point:
    x: float
    y: float
 
 
def describe(obj: object) -> str:
    match obj:
        case None:
            return "nothing"
        case 0 | 1:
            return "bit"
        case int(n) if n < 0:
            return "negative int"
        case str() as s:
            return f"string of {len(s)}"
        case [x, y]:
            return f"pair {x}, {y}"
        case [first, *rest]:
            return f"{first} and {len(rest)} more"
        case {"type": "click", "pos": (x, y)}:
            return f"click at {x}, {y}"
        case Point(x=0, y=0):
            return "origin"
        case Point(x=px):
            return f"point at x={px}"
        case _:
            return "something else"
 
 
print(describe({"type": "click", "pos": (1, 2)}))

nums = range(10)
evens_sq = [n * n for n in nums if n % 2 == 0]
lengths = {w: len(w) for w in ["hi", "hey"]}
initials = {w[0] for w in ["ann", "amy", "bo"]}
total = sum(n * n for n in nums)  # generator: lazy
pairs = [(r, c) for r in range(2) for c in range(3)]
flat = [x for row in [[1], [2, 3]] for x in row]
labels = ["even" if n % 2 == 0 else "odd" for n in nums]
first_big = next((n for n in nums if n > 7), None)

a, b = 1, 2
a, b = b, a  # swap
first, *middle, last = [1, 2, 3, 4]  # middle == [2, 3]
(x, y), z = (1, 2), 3
_, value = ("key", 42)  # _ = ignored by convention
 
base = {"a": 1, "b": 2}
merged = {**base, "b": 3}  # like {...base, b: 3}
union = base | {"c": 4}  # dict union (3.9+)
combined = [*range(3), *"ab"]  # [0, 1, 2, 'a', 'b']
 
 
def add3(a: int, b: int, c: int) -> int:
    return a + b + c
 
 
args = [1, 2, 3]
kwargs = {"a": 1, "b": 2, "c": 3}
assert add3(*args) == add3(**kwargs) == 6

def request(
    url: str,
    /,  # url is positional-only
    method: str = "GET",
    *,  # the rest are keyword-only
    timeout: float = 10.0,
    **headers: str,
) -> str:
    return f"{method} {url} {timeout}s {headers}"
 
 
request("/a", "POST", timeout=5, accept="json")
# request(url="/a")   TypeError: positional-only
# request("/a", "GET", 5)   TypeError: keyword-only
 
 
def total(*nums: float) -> float:  # nums: tuple
    return sum(nums)
 
 
by_age = sorted(
    [("ann", 30), ("bo", 20)],
    key=lambda u: u[1],  # one expression only
)

def add_bad(item: int, bucket: list[int] = []) -> list[int]:
    bucket.append(item)  # ❌ same list on every call
    return bucket
 
 
def add(
    item: int, bucket: list[int] | None = None
) -> list[int]:
    bucket = [] if bucket is None else bucket
    bucket.append(item)
    return bucket
 
 
add_bad(1)
print(add_bad(2), add(2))  # [1, 2] [2]

from collections.abc import Callable
 
hits = 0
 
 
def bump() -> None:
    global hits
    hits += 1  # without `global`: UnboundLocalError
 
 
def counter() -> Callable[[], int]:
    n = 0
 
    def inc() -> int:
        nonlocal n
        n += 1
        return n
 
    return inc
 
 
c = counter()
c(), c()  # (1, 2)
 
late = [lambda: i for i in range(3)]
[f() for f in late]  # [2, 2, 2]: closures see the last i
bound = [lambda i=i: i for i in range(3)]
[f() for f in bound]  # [0, 1, 2]

import functools
import time
from collections.abc import Callable
 
 
def timed[**P, R](fn: Callable[P, R]) -> Callable[P, R]:
    @functools.wraps(fn)  # keep __name__, __doc__
    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
        start = time.perf_counter()
        try:
            return fn(*args, **kwargs)
        finally:
            ms = (time.perf_counter() - start) * 1000
            print(f"{fn.__name__}: {ms:.2f} ms")
 
    return wrapper
 
 
@timed
def work(n: int) -> int:
    return sum(range(n))
 
 
work(100_000)

import json
from pathlib import Path
 
 
def load(path: Path) -> dict[str, object]:
    try:
        raw = path.read_text(encoding="utf-8")
        data = json.loads(raw)
    except FileNotFoundError:
        return {}
    except PermissionError, IsADirectoryError:  # 3.14
        raise
    except json.JSONDecodeError as e:
        e.add_note(f"while loading {path}")
        raise ValueError("bad config") from e
    else:  # ran only if nothing was raised
        if not isinstance(data, dict):
            raise TypeError("expected an object")
        return data
    finally:  # always runs; don't `return` here
        print("done", path)

class AppError(Exception):
    """Base class for this app's errors."""
 
 
class NotFoundError(AppError):
    def __init__(self, what: str) -> None:
        super().__init__(f"{what} not found")
        self.what = what

def run_batch() -> None:
    raise ExceptionGroup(
        "batch failed",
        [
            ValueError("row 3"),
            KeyError("id"),
            ValueError("row 9"),
        ],
    )
 
 
try:
    run_batch()
except* ValueError as eg:
    print("bad rows:", [str(e) for e in eg.exceptions])
except* KeyError as eg:
    print("missing:", eg.exceptions)

from collections.abc import Generator, Iterator
from pathlib import Path
 
 
def countdown(n: int) -> Iterator[int]:
    while n > 0:
        yield n
        n -= 1
 
 
print(list(countdown(3)))  # [3, 2, 1]
it = iter([1, 2])
print(next(it), next(it), next(it, None))  # 1 2 None
 
 
def lines(path: Path) -> Iterator[str]:
    with path.open(encoding="utf-8") as f:
        yield from (ln.rstrip("\n") for ln in f)
 
 
def running_avg() -> Generator[float, float]:
    total, count = 0.0, 0
    value = yield 0.0
    while True:
        total, count = total + value, count + 1
        value = yield total / count
 
 
avg = running_avg()
next(avg)  # prime it
print(avg.send(10), avg.send(20))  # 10.0 15.0

from collections.abc import Callable, Iterable, Sequence
from typing import Literal, NotRequired, Protocol, TypedDict
 
type UserId = int  # alias (3.12+)
type Json = (
    dict[str, Json] | list[Json] | str | int | float
    | bool | None
)
Mode = Literal["r", "w"]
 
 
class User(TypedDict):  # like a TS object type
    id: UserId
    name: str
    email: NotRequired[str]
 
 
class HasLen(Protocol):  # structural, like an interface
    def __len__(self) -> int: ...
 
 
def first[T](xs: Sequence[T]) -> T | None:
    return xs[0] if xs else None
 
 
def longest[S: HasLen](xs: Iterable[S]) -> S:  # bound
    return max(xs, key=len)
 
 
class Box[T = int]:  # type parameter default (3.13+)
    def __init__(self, value: T) -> None:
        self.value = value
 
    def map[U](self, f: Callable[[T], U]) -> Box[U]:
        return Box(f(self.value))
 
 
u: User = {"id": 1, "name": "ann"}
print(first([1, 2]), longest(["a", "abc"]))

from collections import Counter, defaultdict
 
users = [
    {"name": "ann", "team": "a"},
    {"name": "bo", "team": "b"},
    {"name": "cy", "team": "a"},
]
role = users[0].get("role", "member")  # no KeyError
 
by_team: defaultdict[str, list[str]] = defaultdict(list)
for u in users:
    by_team[u["team"]].append(u["name"])
print(dict(by_team))  # {'a': ['ann', 'cy'], 'b': ['bo']}
 
counts = Counter(u["team"] for u in users)
print(counts.most_common(1))  # [('a', 2)]
 
seen: dict[str, int] = {}
seen.setdefault("x", 0)  # insert only if missing
 
 
def dig(d: object, *keys: str) -> object:
    for k in keys:
        if not isinstance(d, dict):
            return None
        d = d.get(k)
    return d
 
 
print(dig({"a": {"b": {"c": 1}}}, "a", "b", "c"))  # 1

from collections.abc import Iterable, Iterator
from itertools import chain
 
rows = [[1, 2], [3], []]
print(list(chain.from_iterable(rows)))  # one level
 
type Nested = int | Iterable[Nested]
 
 
def deep_flatten(x: Nested) -> Iterator[int]:
    if isinstance(x, int):  # check str too if it
        yield x             # can appear: str iterates
    else:
        for item in x:
            yield from deep_flatten(item)
 
 
print(list(deep_flatten([1, [2, [3, [4]]]])))

from itertools import batched
 
for batch in batched(range(7), 3):
    print(batch)  # (0, 1, 2) (3, 4, 5) (6,)
 
# strict=True raises ValueError on a short last batch
list(batched("abcdef", 2, strict=True))
 
xs = list(range(7))
chunks = [xs[i : i + 3] for i in range(0, len(xs), 3)]

xs = [3, 1, 3, 2, 1]
print(list(dict.fromkeys(xs)))  # [3, 1, 2]
 
users = [{"id": 1}, {"id": 2}, {"id": 1}]
unique = list({u["id"]: u for u in users}.values())

import argparse
import sys
 
 
def main(argv: list[str] | None = None) -> int:
    p = argparse.ArgumentParser(prog="mytool")
    p.add_argument("path")
    p.add_argument("-n", "--count", type=int, default=1)
    p.add_argument("-v", "--verbose", action="store_true")
    args = p.parse_args(argv)
    for _ in range(args.count):
        print(args.path)
    return 0
 
 
if __name__ == "__main__":  # not run on import
    sys.exit(main())

[project.scripts]
mytool = "mytool.cli:main"  # then: uv run mytool a.txt

import functools
import random
import time
from collections.abc import Callable
 
 
def retry[**P, R](
    times: int = 3,
    base: float = 0.2,
    on: tuple[type[Exception], ...] = (Exception,),
) -> Callable[[Callable[P, R]], Callable[P, R]]:
    def deco(fn: Callable[P, R]) -> Callable[P, R]:
        @functools.wraps(fn)
        def wrapper(*a: P.args, **kw: P.kwargs) -> R:
            for attempt in range(1, times + 1):
                try:
                    return fn(*a, **kw)
                except on:
                    if attempt == times:
                        raise
                    cap = base * 2 ** (attempt - 1)
                    time.sleep(random.uniform(0, cap))
            raise AssertionError("unreachable")
 
        return wrapper
 
    return deco
 
 
@retry(times=5, on=(ConnectionError, TimeoutError))
def fetch_status() -> int:
    return 200