Overview

A pure function's output depends ONLY on its arguments, and it produces no observable side effect -- no mutating an argument, no writing to a global, no printing, no touching a file or the network. Call it twice with the same arguments and it always gives the same result, which makes it trivially safe to call twice, safe to call from multiple threads, and easy to test with nothing but its arguments and its return value (Example 1 contrasts add_pure against add_impure; Example 58 property-tests purity itself across 200 generated inputs).

A side effect is anything a function does besides computing and returning a value -- printing, mutating an argument the caller can see, writing a file, incrementing state outside the function's own scope. Naming exactly where that boundary sits is a design decision, not an accident: a codebase that never draws it lets side effects creep in anywhere, which is precisely what makes large imperative code hard to test (Example 1's impure twin mutates a global as its side effect; Example 3 classifies three functions and confirms only the pure one is flagged pure).

A call is referentially transparent if it can be replaced by its own return value anywhere in the program without changing what the program does -- add(2, 3) can always be replaced by 5. This is what makes equational reasoning possible: a reader can simplify an expression by substituting a call for its value the same way they simplify algebra, without tracing side effects to check the substitution is safe (Example 2 replaces a call with its literal value inside a larger expression and confirms the output is unchanged).

tuple and frozenset are built-in immutable containers; @dataclass(frozen=True) makes a custom record immutable, raising FrozenInstanceError on an attempted attribute set; types.MappingProxyType wraps a dict in a read-only view. An object nobody can mutate is always safe to hand to another function, another thread, or another part of the codebase -- there is no way for that code to corrupt what the caller still holds a reference to (Example 4 catches a TypeError on tuple mutation; Example 5 shows a frozen dataclass rejecting an attribute set).

A persistent data structure keeps every old version reachable after an "update," because the update never mutates anything -- it builds a new version that shares whatever structure didn't change with the old one. Structural sharing is what makes immutability affordable: without it, every update would have to deep-copy the entire structure, which is both slow and memory-hungry; sharing the unchanged parts can keep an update as cheap as O(1) (Example 7's cons-list prepend; Example 59's persistent binary tree update confirms the old root stays intact).

Functions in Python can be assigned to a variable, stored in a list or dict, passed as an argument, and returned from another function, all without special syntax. Once functions are values, behavior itself becomes something you can pass around, store, and compose -- the seed that higher-order functions, closures, currying, composition, and decorators all grow from (Example 8 assigns a function to a variable and calls through it; Example 9 stores several functions in a list and calls each in turn).

A higher-order function takes another function as an argument, returns one, or both -- apply(fn, x) returning fn(x) works identically whether fn doubles, squares, or does something else entirely, because apply never needs to know what fn actually does. This factors "the shape of the computation" apart from "what specifically happens at each step," the mechanism underneath decorators and map/filter/reduce (Example 10's apply(fn, x) verified against two different functions).

A closure captures a variable from its enclosing scope and keeps using that captured value even after the enclosing function has returned -- multiplier(3) returns a function that remembers 3 forever, so multiplier(3)(4) multiplies by the captured 3, not by something threaded through fresh each call. This lets you "bake in" configuration once and get back a specialized function (Example 12's closure captures a threshold; Example 32 contrasts a stateful closure counter against a pure fold, naming exactly where each one's state lives).

Currying turns an n-argument function into a chain of one-argument functions -- add(a, b) becomes add(a)(b), where add(a) returns a new one-argument function waiting for b. Currying is ALWAYS one argument at a time by construction, while functools.partial can fix any number of arguments at once in a single call (Example 17 hand-curries a 2-argument function; Example 62's @curry decorator auto-curries by counting a function's arity).

Partial application fixes some of a function's arguments right now and returns a smaller function waiting for the rest -- functools.partial(pow, 2) fixes the base at 2 and returns a one-argument function computing 2**n, no lambda or manual closure required. It is more discoverable to a reviewer and composes cleanly with functools.reduce and decorator pipelines elsewhere in this topic (Example 18 verified to compute 2**n; Example 33 chains several partial calls into a composed transform).

compose(f, g) builds a new function so that calling it on x runs g(x) FIRST and feeds its result into f -- it computes exactly f(g(x)), right-to-left relative to how the call is written. This is how small, single-purpose functions become a pipeline without being fused into one large function body, each piece staying independently testable (Example 19 verified to compute f(g(x)); Example 34's compose(*fns) folds a whole list of functions with the application order verified).

pipe(x, f, g) reads left-to-right in the order it actually executes -- "start with x, apply f, then apply g" -- instead of the inside-out reading order nested calls (or compose) require. pipe and compose can compute the identical thing; the difference is purely a readability trade for a chain of more than two or three steps (Example 20's pipe(x, f, g) verified equal to the nested-call equivalent; Example 74 directly contrasts a deep pipe chain against nested calls on real data).

map applies a function to every element (replacing a "transform each item" loop), filter keeps only the elements a predicate accepts (replacing a "collect matching items" loop), and reduce folds a sequence to one accumulated value (replacing an "initialize then mutate a running total" loop). Together they cover the overwhelming majority of "loop over a collection and do something" code without a single mutable accumulator variable exposed to the caller (Example 13's map; Example 14's filter; Example 15's reduce; Example 37 chains all three for a data summary).

CPython, by explicit design choice, performs NO tail-call optimization -- a deeply recursive call still grows the call stack one frame per call and eventually raises RecursionError, unlike languages that optimize a self-tail-call into a loop automatically. The two standard workarounds are an explicit stack or a trampoline (Example 44 converts a deep recursion into an explicit stack; Example 66 builds a trampoline and verifies a deep recursion completes without ever raising RecursionError).

A generator computes a value only when it is actually needed -- a generator expression builds no list at all, and each value is produced on demand, one next() call at a time. That is what makes an infinite sequence (like itertools.count()) usable in the first place, and it lets a pipeline over a sequence of unknown or infinite size run without ever materializing that sequence in memory (Example 21 shows only pulled values are computed; Example 63 builds a lazy, infinite prime sieve).

islice takes a slice of any iterable (including an infinite one) without materializing it, chain concatenates iterables, accumulate produces running totals, groupby groups consecutive equal keys, tee splits one iterator into several independent ones, and pairwise yields consecutive element pairs. Every one of them is itself lazy -- none build an intermediate list (Example 23 uses islice over an infinite count(); Example 39 verifies prefix sums via accumulate).

Memoization caches a function's results keyed by its arguments, so a repeated call with the same arguments returns the cached result instead of recomputing it -- which is only safe because the function being cached is pure (co-01). Caching an impure function's result would silently return a stale value (and any stale side effect) forever after the first call, even after whatever the function actually depends on has changed (Example 25 puts @lru_cache on a recursive fib and confirms cache_info() shows hits; Kata 8 reproduces the stale-cache bug directly by memoizing an impure lookup).

@log_calls on def greet(): ... is exactly greet = log_calls(greet) -- a decorator is a higher-order function that takes a function and returns a wrapped replacement. Decorators let you attach cross-cutting behavior (logging, caching, retrying, timing) to a function without touching that function's own body, and functools.wraps preserves the wrapped function's __name__ and metadata so introspection still sees the original identity (Example 26 wraps a function with a logging decorator; Example 43 confirms functools.wraps preserves __name__).

Point-free style expresses a transformation by composing functions together without ever naming the argument the data flows through -- a pipeline built entirely from compose/pipe calls has no lambda x: ... anywhere, because the "point" (the argument) is never explicitly written. This topic treats it as one more tool, not a stylistic mandate -- taken too far it can obscure what's actually happening (Example 35 rewrites a lambda pipeline point-free and confirms identical output; Example 73 builds a small point-free combinator library).

Circle | Square (PEP 604 union syntax) says a Shape is EITHER a Circle or a Square, each carrying only the fields relevant to that variant -- there is no way to construct a Circle with a side_length field, because that field doesn't exist on Circle at all. This is a stronger guarantee than one class with nullable fields, where nothing stops a Circle instance from also carrying a stray field that means nothing (Example 45 models a shape as a union of frozen dataclasses and verifies each variant).

Python's match/case (PEP 634) has NO compile-time exhaustiveness checking at the language level -- an unmatched value simply falls through with no error unless the developer adds an explicit wildcard case _ and raises there themselves. (A static type checker like pyright CAN flag a non-exhaustive match over a fully-known closed union as a best-effort heuristic, but CPython itself enforces nothing at runtime.) (Example 46 matches over the Circle | Square ADT with an explicit note on this gap; Kata 7 reproduces the silent fall-through directly by omitting both the new variant's case and the wildcard.)

A function returning Optional[int] still lets a caller forget the None check and crash later with a "NoneType has no attribute" error, far from where the None actually originated. An Option-returning function (Some/Nothing, hand-rolled and stdlib-only) forces the caller to unwrap the result explicitly (or map through it), turning a possible runtime crash into a type-level obligation the caller cannot silently skip (Example 48 builds Some/Nothing with map; Example 49 chains Option-returning lookups and confirms short-circuit on the first miss).

def parse(s: str) -> int tells a caller nothing about whether it can raise; def parse(s: str) -> Result[int, str] states the failure mode directly in the type the caller sees at the call site, without reading the implementation. This makes failure an ordinary value you can map over, compose, and inspect, instead of a special control-flow mechanism that unwinds the stack (Example 50 carries an error as a value through a hand-rolled Ok/Err; Example 51 confirms a Result chain stops at the first Err).

Railway-oriented programming threads a Result through a pipeline of steps, replacing a pyramid of nested if err != nil checks (or scattered try/except blocks) with a single linear chain that reads top-to-bottom. The short-circuiting is handled once, by the Result type's own and_then/map machinery, instead of being re-implemented by hand at every step (Example 52's validation pipeline confirms one bad field short-circuits the rest; Kata 9 reproduces the crash that results when a hand-written and_then skips checking for Err before calling the next step).

The functor identity law states container.map(identity) == container -- mapping the identity function over a container changes nothing but confirms map genuinely just "applies this function to whatever's inside, however many things that is" (zero, one, or many), the exact same idea whether the container is a list, Some, or Nothing. Recognizing the functor pattern lets you transfer intuition about list map directly onto Option, Result, and any wrapped-value type you build (Example 53 shows the identity law by example; Example 70 property-tests the identity and composition laws together).

map/functor only handles a function of ONE wrapped argument; an applicative is the natural next step for combining SEVERAL independently-wrapped values with a multi-argument function -- map2(add, Some(2), Some(3)) unwraps both Options, calls add(2, 3), and wraps the result back up as Some(5), short-circuiting to Nothing if either input is absent (Example 55's map2 combines two Options; Example 71 builds an applicative that accumulates every validation error instead of stopping at the first one).

map applied to a function that itself returns a wrapped value produces a nested wrapper -- Ok(5).map(lambda x: Ok(x + 1)) would give Ok(Ok(6)), not Ok(6). bind (also called and_then or flat_map) is the extra piece that flattens the result instead: Ok(5).and_then(lambda x: Ok(x + 1)) correctly returns Ok(6) (Example 51's and_then on Result; Example 72 shows left-identity, right-identity, and associativity by example, the three monad laws made concrete).

A functional-core/imperative-shell design splits a program into a pure transformation core (parse, transform, aggregate -- no I/O anywhere) surrounded by a thin imperative shell that holds every effect (reading a file, writing output, talking to a network). The core is tested directly with no mocking, because it has nothing to mock -- it is the same purity-boundary idea from co-02, made into a concrete architectural pattern (Example 57 splits a CSV analyzer into a pure core and an I/O shell; Kata 10 reproduces a debug print() that leaks I/O into what was meant to be the pure core).

This is a purity violation (co-01, co-02) -- purity requires the OUTPUT to depend only on the arguments, and reading ANY external, non-deterministic, or mutable state (not just writing to it) breaks that guarantee just as thoroughly as printing or mutating an argument would (Example 1; Example 3; Kata 1's mutation-based variant of the same "hidden dependency" family).

This is an immutability question (co-04) -- a tuple cannot be mutated after construction, so handing it to three threads is safe by construction; a list handed the same way is an accident waiting to happen, because ANY of the three threads (or any other code holding the reference) can mutate it out from under the others (Example 4; Kata 2's dataclasses.replace shows the safe way to "update" an immutable record instead of mutating it in place).

This is closure late binding (co-08) -- a closure captures the VARIABLE, not a frozen snapshot of its value at closure-creation time. By the time any of the three lambdas is called, the loop variable has already reached its final value, and all three see that same final value; binding it as a default argument at each iteration is the fix (Example 11; Example 12; Kata 3).

This is a composition-ordering mistake (co-11, co-12) -- compose(f, g) applies g FIRST then f (right-to-left, mathematical convention), while pipe(x, f, g) applies f first then g (left-to-right, reading order). Reaching for the wrong helper silently reverses execution order even though every individual step is correct in isolation (Example 19; Example 20; Kata 4).

This is a mutable-default-argument leak (co-04, co-13) -- a mutable default argument (counts={}) is created ONCE, at function-definition time, and every call that omits the argument shares that SAME dict object. The reduce logic itself is correct; it is the accumulator it folds into that leaks across calls (Example 15; Example 36; Kata 5).

This is generator exhaustion (co-15) -- a generator is a single-use, statefully-exhausted iterator; once fully consumed by the sum, there is nothing left to yield on a second pass, and Python raises nothing to flag the mistake, it simply produces an empty iteration (Example 21; Example 22; Kata 6).

This is match/case's missing runtime exhaustiveness check (co-20, co-21) -- Python does not warn or error at the LANGUAGE level when a match block fails to cover every variant of a closed union; an unmatched value simply falls through, and with no explicit case _: raising an error, that fall-through looks like a legitimate result instead of a caught bug (Example 45; Example 46; Example 67; Kata 7).

This is memoization applied to an impure function (co-17, co-01) -- lru_cache is only safe on a function whose result depends ONLY on its arguments; this function secretly reads a mutable, externally-updated dict, so caching its result the first time freezes a value that was only ever correct at that one instant (Example 25; Example 41; Kata 8).

This is railway-oriented error handling done incorrectly (co-22, co-23, co-24) -- a correct and_then/bind chain checks whether the PREVIOUS step returned Ok/Some before ever calling the next step's function. Skip that check, and the next step receives the raw Err/Nothing wrapper as if it were a success value; calling success-shaped code on it crashes instead of cleanly short-circuiting (Example 51; Example 52; Kata 9).

This is a functional-core/imperative-shell boundary violation (co-28, co-02) -- a function that performs I/O (even just a diagnostic print) is, by definition, no longer part of the pure core. The moment a test needs to capture or redirect output to verify behavior, that is the signal the boundary has been drawn in the wrong place, and the print call belongs in the imperative shell instead (Example 57; Example 76; Kata 10).

Root cause: item.price *= rate mutates the SAME CartItem objects the caller's cart list holds references to. Two calls to apply_discount therefore compound: the second call discounts the ALREADY-discounted prices, not the originals. Building a brand-new CartItem per element (via dataclasses.replace) means the function only ever reads the input, never writes to it.

Run: python3 kata.py

Output:

[9.0, 18.0]
False

Root cause: a frozen dataclass overrides __setattr__ to reject any assignment after __init__, at RUNTIME -- # type: ignore[misc] only silences pyright's static warning, it does not change what the program does when actually run. dataclasses.replace(config, retries=5) is the correct "update": it builds a NEW instance with the named fields overridden, leaving config itself completely untouched.

Run: python3 kata.py

Output:

RetryConfig(retries=1, timeout_seconds=5.0)
RetryConfig(retries=5, timeout_seconds=5.0)

Root cause: a closure captures the ENCLOSING VARIABLE, not a snapshot of its value at the moment the lambda is defined. By the time validators is actually called (after the loop finishes), t holds its LAST value (30) for all three lambdas equally. lambda x, t=t: x > t works because Python evaluates a default-argument expression exactly ONCE, at the moment THAT lambda is created -- binding each closure's own t=t default to that iteration's value permanently.

Run: python3 kata.py

Output:

[True, False, False]

Root cause: compose(f, g) computes f(g(x)) -- g ALWAYS runs first, regardless of how natural the call compose(add_one, double) looks to read left to right. pipe(x, *fns) sidesteps the whole ambiguity by reading AND executing in the same order: the first function argument after x is the first one applied.

Run: python3 kata.py

Output:

12

Root cause: Python evaluates a default argument expression exactly ONCE, at function-definition time -- {} is created a single time, and the before version's loop MUTATES that single shared dict in place on every call that omits counts. Using None as a sentinel and building a fresh {} inside the body (or, as shown, folding with functools.reduce into a NEW dict each step) removes the shared mutable target entirely.

Run: python3 kata.py

Output:

{'a': 2, 'b': 1}
{'c': 1}

Root cause: a generator object tracks its own position and raises StopIteration once exhausted -- sum(values) fully drains it, so list(values) afterward has nothing left to pull and produces an empty list with NO error to flag the mistake. Wrapping the generator in list(...) once, up front, trades away the laziness (the whole sequence is now materialized in memory) in exchange for being safely re-iterable as many times as needed -- the right trade whenever a value is genuinely consumed more than once.

Run: python3 kata.py

Output:

14
[1, 4, 9]

Root cause: Python's match/case has no LANGUAGE-level exhaustiveness check -- a match block that doesn't cover every variant simply falls through with no error, and a function with no explicit return on that path implicitly returns None. (Note: this specific example IS statically catchable -- pyright's reportMatchNotExhaustive correctly flags the before version, which is why it needs a # type: ignore to demonstrate the runtime behavior at all; the underlying CPython runtime still enforces nothing.) Adding both the missing case Triangle(...) branch AND a case _: wildcard that raises makes any FUTURE unhandled variant a loud, immediate crash instead of a silent None.

Run: python3 kata.py

Output:

6.0

Root cause: get_price's result depends on the MODULE-LEVEL prices dict, not just on its own sku argument -- it is not actually pure, even though its signature looks like a simple lookup. @lru_cache assumes purity and caches by argument alone, so once get_price("widget") is called once, every LATER call with "widget" returns the frozen first result forever, regardless of what prices does afterward. The fix is not a smarter cache; it's recognizing this function was never safe to memoize in the first place.

Run: python3 kata.py

Output:

9.99
14.99

Root cause: the broken and_then reaches for result.value before confirming result is actually an Ok -- Err has an .error field, not .value, so the attribute access crashes the instant a legitimate failure reaches it. Pattern-matching on result's variant FIRST (case Ok(value=v) vs. case Err(error=e)) makes the check impossible to skip: step is only ever called inside the Ok branch, and an Err is returned untouched from the Err branch, exactly the short-circuit railway semantics are supposed to guarantee.

Run: python3 kata.py

Output:

Err(error='-5 is not positive')

Root cause: a print() call, even a "harmless" diagnostic one, is I/O -- the moment parse_and_total performs it, the function is no longer pure, and any test of its RETURN VALUE also has to manage its side effect (here, by redirecting stdout) to avoid polluting test output. Moving the print into a separate run_shell function draws the functional-core/imperative-shell boundary explicitly: the core is called directly with no redirection needed at all, and the shell is the ONLY place any output happens.

Run: python3 kata.py

Output:

60
''
parsing 3 rows
60

Eliminating I/O is not actually an option for a program that has to do anything observable in the real world -- the honest goal is taming-state: quarantining WHERE effects live instead of pretending they don't exist. The functional-core/imperative-shell split (co-28) is the concrete architectural answer: the core stays testable with zero mocking precisely because it holds none of the effects, and the shell is small and thin precisely because it holds ALL of them, in one place a reviewer can scrutinize directly.

Determinism shows up wherever purity does, under different names: memoization (co-17) is only safe because a pure function's result is deterministic by argument; a persistent data structure's old version (co-05) stays trustworthy because nothing about it can have silently changed; property-testing purity itself (Example 58) is really testing determinism directly. Recognizing "this is the same determinism-vs-emergence trade again" is what lets a developer transfer intuition from one FP feature to an unfamiliar one.

abstraction-and-its-cost is the honest counterweight this topic names explicitly: immutability allocates, and a persistent update that shares structure is still not free -- Example 75 measures this cost numerically rather than asserting it. A tight numeric loop or a huge in-place buffer is a place an imperative core is honestly faster, and pretending otherwise trades a real performance cost for a principle that buys nothing concrete in that specific spot.

Err genuinely has no .value field -- it has .error instead -- so step(result.value) is not merely logically wrong, it is a type-shape mismatch the moment result is actually an Err. Contrast Kata 7, where the bug (a missing match case) produces a plausible-looking None instead of a crash: some correctness bugs fail loudly by construction (a crash you cannot miss), and others fail silently by construction (a wrong value indistinguishable from a right one) -- recognizing which failure MODE a bug class produces is itself a useful skill.

Both statements are true at different levels: the Python LANGUAGE itself (CPython, at runtime) enforces nothing about match/case exhaustiveness -- an unmatched value simply falls through. A separate, optional STATIC TYPE CHECKER (pyright) can layer a best-effort exhaustiveness heuristic on top, but only when it can see the union's FULL set of variants statically; anything that defeats that visibility (a dynamically-constructed type, a variant defined in another module pyright isn't shown) removes the safety net entirely. The topic's own maxim -- always add a case _: that raises -- is what makes the guarantee hold regardless of which type checker (if any) a project runs.

Railway-oriented programming names the SHAPE of the resulting code, not a new mechanism: a chain of and_then calls reads top-to-bottom as one linear success path, with every failure mode handled ONCE by the Result type's own machinery instead of re-implemented as a nested if err != nil pyramid at every step. Naming the pattern is what lets a developer recognize "this messy nested-conditional code is secretly a railway that hasn't been written as one yet" the next time they see it.

Each pattern in isolation (Examples 1-56) proves the mechanism works; the capstone proves the mechanisms COMPOSE -- a real tool needs a pure core (co-28) that produces Result-typed rows (co-23), some of which fail independently and need combining via an applicative that accumulates every error instead of stopping at the first (co-26), all while the imperative shell stays the ONLY place touching a file. That composition is the actual skill a production codebase demands, not any one pattern recited alone.

Memoization's entire correctness argument is "the same arguments always produce the same result, so caching by argument is safe" -- which is EXACTLY the purity guarantee (co-01) and nothing else. Kata 8 demonstrates the failure directly: @lru_cache on a function reading mutable external state doesn't just fail to speed anything up correctly, it actively returns WRONG, stale answers forever after the first call, which is worse than not caching at all.

The topic's own scope note names this trade-off directly: a gentle, practical first exposure lets a developer recognize the SAME shape (map on a list, map on an Option, and_then chaining Result-returning steps) across libraries and languages immediately, which is the day-to-day payoff. The deeper, law-checking rigor (why the functor laws must hold, what associativity actually guarantees) is deliberately deferred to a later Type Systems topic -- teaching both at once here would spend this topic's whole budget on formalism before a reader has even seen the patterns pay off in working code.