Overview

A saved script (python3 file.py), an inline one-liner (python3 -c "..."), and the interactive REPL (python3 with no arguments). The -c flag and the REPL both need no saved file -- the REPL additionally needs no argument at all.

An isolated, per-project Python interpreter and pip under .venv/. It solves dependency collision: without one, every project's packages install into one shared system Python, so two projects needing different versions of the same package cannot coexist.

black/ruff format rewrites code into a canonical, deterministic style -- spacing, line breaks, quote style -- with no judgment about correctness. ruff check lints: it flags likely bugs and smells (an unused import, an undefined name) without reformatting anything. Formatting and linting are two distinct, complementary passes.

A name is just a label pointing at an object in memory, created by =, not a typed storage slot. Because Python is dynamically typed, the same name can be rebound to point at a value of a completely different type later in the same scope -- the type lives on the object, never on the name.

int, float, str, bool, and None -- each with its own literal syntax (3, 1.5, "x", True/False, None) and its own set of operators.

No -- type hints are pure documentation as far as python3 is concerned; nothing about x: int stops you from later assigning a str to x at runtime (Example 84 proves this directly). A separate static type checker, pyright, reads the hints and reports mismatches without ever running the code.

// is floor division -- it discards the remainder and always rounds toward negative infinity, returning an int when both operands are int. / is true division and always returns a float, even when the operands divide evenly.

It prints both the literal source text of the expression and its value, joined by = -- e.g. f"{value=}" for value = 42 prints value=42, with no manual f"value: {value}" needed.

None -- .append() mutates the list in place and returns nothing. The classic bug is writing nums = nums.append(4), which discards the entire list, replacing it with None.

Hashability requires a value's hash to never change for as long as it's used as a dict key or set element. Tuples are immutable, so their hash is stable for their entire lifetime. Lists are mutable -- a list's contents (and therefore its hash) could change after insertion, which would break lookups, so Python disallows hashing them entirely.

Since Python 3.7, dicts preserve insertion order as a language guarantee, not merely an implementation detail -- .items()/.keys()/.values() always iterate in the order keys were first inserted.

O(1) average case for a set, versus O(n) for a list -- a set is the right tool whenever the recurring question is "have I seen this value before?" rather than "in what order did I see these?"

No -- stop is always exclusive in a slice, so nums[1:4] returns indices 1, 2, 3 only. nums[::-1] (empty start, empty stop, step -1) reverses any sequence -- list, tuple, or string.

A colon. {expr for x in iterable} (no colon) builds a set; {key_expr: value_expr for x in iterable} (with a colon) builds a dict -- the braces alone don't distinguish them.

Any four of: 0, 0.0, "" (empty string), [] (empty list), {} (empty dict), set() (empty set), None -- Python treats "empty" broadly as falsy, unlike languages with a narrower falsy set.

It silently stops at the shortest input, with no error and no warning -- pairing continues only as far as the shortest iterable allows.

More than one -- a bare comma-separated expression after return (e.g. return a, b) implicitly builds a tuple, which the caller can then unpack into separate names in one assignment.

*args collects extra positional arguments into a tuple; **kwargs collects extra keyword arguments into a dict keyed by the argument names.

nonlocal. Without it, an assignment like count += 1 inside a nested function creates a brand-new local variable instead of mutating the enclosing one, and raises UnboundLocalError the moment a read happens before that new local is ever assigned.

It checks whether __name__ equals the string "__main__", which is true only when the file is run directly (python3 file.py), never when the file is imported by another module (where __name__ instead equals the module's own name). That lets one file serve as both an importable library and a runnable script with no unwanted side effects on import.

else runs only if the try block raised no exception at all. finally runs unconditionally -- whether the try block succeeded, raised a caught exception, or even let an uncaught exception propagate past the whole block -- making it the right place for guaranteed cleanup.

That the file closes automatically on the way out of the block, exception or not -- the same guarantee finally provides, built directly into open()'s context-manager protocol (__enter__/__exit__).

The s-suffixed pair works on strings in memory (dumps serializes to a str, loads parses a str). The non-s pair works directly on an open file object (dump writes to it, load reads from it) -- otherwise, they perform the identical serialize/parse operation.

__init__ (a constructor accepting each field as a parameter) and __repr__ (a readable string representation) -- both derived purely from the class body's type-annotated field declarations, with no method bodies written by hand.

Yes. Example 84 passes a str where a parameter is annotated int: python3 runs the file to completion and exits 0, because it never checks type hints at runtime, while pyright reports exactly one reportArgumentType error on that exact call, because it checks the annotation statically without running anything. Both tools are "right" -- they check different things.

Default the parameter to None, not [], then build the real empty list inside the function body: def f(items: list[str] | None = None) -> list[str]: items = items if items is not None else []. A mutable default argument (= []) is evaluated exactly once, at function-definition time, and reused by every call that omits the argument -- Kata 1 demonstrates this bug directly.

config.get("field", default_value) instead of config["field"]. [] raises KeyError on a missing key; .get(key, default) returns default instead, with no try/except needed.

Call .copy() (or the slice [:]) before mutating: backup = original.copy(). Plain assignment (backup = original) creates a second name pointing at the exact same list object -- mutating through either name is visible through both, exactly the aliasing bug Kata 3 demonstrates.

Catch the narrowest exception type the risky operation can actually raise (e.g. except ValueError: around int(raw)), never a bare except: or except Exception:. A bare except also swallows unrelated bugs that happen to raise inside the same block -- Kata 4 shows the difference between silently swallowing every error and reporting exactly what was skipped.

Capture the loop variable as a default argument: lambda i=i: i instead of lambda: i. A lambda (or any nested function) closes over the loop variable by reference, not by the value it held at creation time -- by the time the loop finishes and any closure runs, the shared variable holds its final value for every one of them, unless a default argument captures each iteration's value explicitly (Kata 5).

JSON object keys are always strings -- json.dumps silently converts every int dict key to its string form, and there is no JSON-native way to preserve the original type. Convert the keys back explicitly after loading: {int(k): v for k, v in restored.items()} (Kata 6's fix).

A generator is a single-pass iterator -- once fully consumed (by sum(), a for loop, or anything else that drains it), it stays exhausted forever; a second iteration attempt simply yields nothing. Materialize it into a list first ([n for n in ... ] instead of (n for n in ...)) if you need to iterate the same values more than once (Kata 7).

Run it as a module with -m from the package's parent directory (python3 -m pkg.main), not as a direct script path. Running python3 pkg/main.py puts pkg/ itself (not its parent) on sys.path, so Python has no way to resolve pkg as a top-level package from inside its own directory (Kata 8).

parser.add_argument("--flag", action="store_true"). store_true flags need no following value: present sets args.flag to True, absent leaves it False -- this is argparse's idiomatic boolean-switch shape (Example 62).

raise NewError("higher-level message") from original_err, inside the except block that caught the original. The from clause chains the original exception into the new one's traceback with a clear "the above exception was the direct cause of" separator, so both diagnostics stay visible (Example 66).

Write a pytest test: a function named test_* with a plain assert inside, in a file pytest can discover automatically (Example 74). Pure functions -- same input always produces the same output, no side effects -- are the easiest kind to test in isolation, which is exactly why this repository's own functional-core convention prefers them.

def add_item(item: str, cart: list[str] | None = None) -> list[str]:
    # THE FIX: default to None (an immutable sentinel), never a mutable literal.
    if cart is None:
        cart = []  # => a BRAND-NEW list, built fresh on every call that omits cart
    cart.append(item)
    return cart
 
 
print(add_item("apple"))  # => a fresh cart -- Output: ['apple']
print(add_item("banana"))  # => ANOTHER fresh cart, unrelated to the first -- Output: ['banana']

Root cause: cart: list[str] = [] evaluates the [] literal exactly once, at function-definition time, not on every call -- every call that omits cart shares that same one list object, so mutations from one call are visible on the next. Defaulting to None and building the real list inside the function body guarantees a fresh object every time.

Run: python3 kata.py

Output:

['apple']
['banana']

settings: dict[str, str] = {"theme": "dark"}
# THE FIX: .get(key, default) never raises -- it returns default on a miss instead.
print(settings.get("timeout", "30"))  # => "timeout" was never set -- falls back to "30"

Root cause: settings["timeout"] uses [] lookup, which raises KeyError the instant the key is absent -- there is no way to supply a fallback with [] syntax alone. .get(key, default) is the built-in, no-try/except-needed alternative whenever a missing key has a sensible default.

Run: python3 kata.py

Output:

30

original: list[int] = [1, 2, 3]
backup = original.copy()  # => THE FIX: .copy() builds a genuinely NEW list, not a second reference
backup.append(4)  # => mutates ONLY backup's own, independent list
print(original)  # => untouched -- Output: [1, 2, 3]
print(backup)  # => Output: [1, 2, 3, 4]

Root cause: backup = original binds a second name to the exact same list object -- it is not a copy, it is an alias. Mutating through backup (via .append()) is visible through original too, because there was only ever one list all along. .copy() (or the equivalent original[:] slice) is what actually allocates a new, independent list.

Run: python3 kata.py

Output:

[1, 2, 3]
[1, 2, 3, 4]

def parse_all(raw_values: list[str]) -> list[int]:
    parsed: list[int] = []
    skipped: list[str] = []
    for raw in raw_values:
        try:
            parsed.append(int(raw))
        except ValueError:  # => THE FIX: narrow to ValueError, not every Exception
            skipped.append(raw)  # => records what was skipped instead of discarding it
    if skipped:
        print(f"skipped invalid values: {skipped}")  # => Output line 1: skipped invalid values: ['two']
    return parsed
 
 
print(parse_all(["1", "two", "3"]))  # => Output line 2: [1, 3]

Root cause: except Exception: with a bare pass catches and discards every failure mode equally -- a genuine bug elsewhere in the loop body would be silenced exactly as quietly as an expected bad-input value. Narrowing to except ValueError: (the only exception int(raw) can actually raise here) and recording what was skipped keeps the failure visible without crashing the whole loop.

Run: python3 kata.py

Output:

skipped invalid values: ['two']
[1, 3]

# THE FIX: `i=i` as a default argument captures i's CURRENT value at each lambda's
# own creation time, instead of a live reference to the one shared loop variable.
makers = [lambda i=i: i for i in range(3)]
print([m() for m in makers])  # => each closure now has its OWN i -- Output: [0, 1, 2]

Root cause: a closure captures an enclosing variable by reference, not by the value it held at the moment the closure was created -- all three lambdas share the exact same i, which keeps changing as the comprehension's loop continues, and settles at 2 once the loop finishes. Binding i as a default argument (lambda i=i: i) evaluates and freezes that specific iteration's value at definition time, since default argument values ARE evaluated once, immediately, unlike the lambda body itself.

Run: python3 kata.py

Output:

[0, 1, 2]

scores: dict[int, str] = {1: "gold", 2: "silver", 3: "bronze"}
raw_restored: dict[str, str] = json.loads(json.dumps(scores))
# THE FIX: rebuild the dict with int() keys immediately after loading -- a
# comprehension (co-14), converting every key back from str to int explicitly.
restored: dict[int, str] = {int(key): value for key, value in raw_restored.items()}
print(restored[1])  # => Output: gold

Root cause: JSON object keys are always strings by specification -- json.dumps silently stringifies every int key (1 becomes "1"), and json.loads has no way to know it should convert "1" back to 1 on the way in, since JSON alone carries no type information about what a key "should" be. Any code relying on int dict keys surviving a JSON roundtrip must convert them back explicitly.

Run: python3 kata.py

Output:

gold

# THE FIX: [n for n in ...] (a list comprehension) materializes every value up
# front, instead of (n for n in ...) (a generator expression), which is lazy and
# single-pass -- once fully consumed by the first sum(), it stays exhausted.
evens = [n for n in range(4) if n % 2 == 0]
total = sum(evens)  # => first full pass -- Output component: 2 (0 + 2)
count = sum(1 for _ in evens)  # => a SECOND full pass -- still works on a list
print(total, count)  # => Output: 2 2

Root cause: a generator expression is a single-pass iterator -- once sum(evens) fully drains it, every later iteration attempt (even a completely different for loop over the same name) yields nothing at all, silently, with no error. A list comprehension materializes every value into memory up front, so it can be iterated as many times as needed.

Run: python3 kata.py

Output:

2 2

# pkg/main.py -- UNCHANGED from the buggy version -- the fix is entirely in HOW this file is run.
from pkg.util import shout
 
print(shout("hello"))  # => Output: HELLO!

Root cause: running python3 pkg/main.py directly puts pkg/'s own directory on sys.path, not its parent -- so Python has no way to resolve pkg as a top-level package from inside pkg/'s own directory, and from pkg.util import shout fails with ModuleNotFoundError. Running python3 -m pkg.main from pkg/'s parent directory instead puts that parent on sys.path, where pkg correctly resolves as a package (Example 64's exact python3 -m app shape, applied here to diagnose a real failure mode instead of the happy path).

Run: python3 -m pkg.main (from the directory containing pkg/)

Output:

HELLO!

A def statement is itself an expression that runs once, at the moment Python first reads it -- every part of the signature, including default-argument expressions, is evaluated right then and bound into the function object as a fixed attribute, not re-evaluated on every subsequent call. That's a direct instance of abstraction-and-its-cost: Python's default-argument syntax buys a concise way to express "this parameter is optional, and here's its fallback value" in one line, but the cost is that the fallback is computed once and reused, which is invisible and surprising exactly when that fallback happens to be mutable. The idiomatic None-sentinel workaround (Kata 1) is not a language wart to route around quietly -- it's the deliberate, well-known pattern every experienced Python developer reaches for once they understand the trade being made.

Making every type-hint mismatch a runtime error would turn Python into a fundamentally different, statically-typed language -- one where you cannot run a single line of code until every annotation in the file (and everything it imports) is provably consistent. Python instead lets you ship and run code immediately, then layer static verification (pyright) on top as a separate, optional step you invoke deliberately, exactly when you want that stronger guarantee. Example 84 makes the trade concrete: repeat_label("3", 2) runs to completion and produces sensible-looking output despite the type mismatch, while pyright still catches the underlying bug -- the language prioritizes "pragmatic, runnable now" over "provably correct before anything runs," and hands you a separate tool for correctness on your own schedule.

If closures captured a frozen copy of a variable's value at creation time, a counter-style closure (Example 41) could never see its own later mutations reflected -- every count += 1 inside the inner function would be updating a private copy invisible to anything outside it, defeating the entire point of a closure holding onto live, ongoing state. Capturing by reference is what lets a closure's returned function keep mutating the same variable across repeated calls. The cost only becomes visible in a loop (Kata 5): every closure built inside that loop shares the one loop variable, which is why binding it explicitly as a default argument is the correct, well-known workaround, not a language flaw to avoid Python over.

JSON's own specification defines an "object" as a set of string-keyed name/value pairs -- there is no alternate object syntax for a non-string key anywhere in the format, because JSON was designed as a small, language-agnostic interchange format, and not every target language even has Python's notion of an arbitrarily-typed hashable key. json.dumps has to pick some behavior for a non-string Python key, and silently coercing it to its string form (rather than raising an error) is the pragmatic choice that keeps most real-world serialization working without extra ceremony -- the cost, Kata 6's whole point, is that a round-trip through JSON is lossy for key type, even when it's lossless for every value.

A generator produces its values lazily, one at a time, computing each one only when actually requested and immediately discarding the machinery needed to produce the previous one -- it never holds the full sequence in memory at once, which is precisely the memory-efficiency benefit abstraction-and-its-cost highlights for generator expressions over list comprehensions (Example 33). That efficiency is only possible because a generator does not remember where it started: once its internal position reaches the end, there's no stored sequence left to "rewind" to the beginning of. Trading the ability to re-iterate for near-zero memory overhead is the entire reason a generator exists as a distinct concept from a list in the first place -- Kata 7's fix (materializing into a list) is choosing the opposite trade-off deliberately, not fixing a bug in generators.

python3 <path> adds the directory containing that file to sys.path[0], treating the file as a standalone script with no package context at all -- from inside pkg/'s own directory, there is no way to resolve pkg as an importable name, since pkg isn't a subdirectory of anywhere on sys.path. python3 -m <module> works differently by design: it resolves pkg.main as a dotted module path relative to the current working directory, adding that directory (the parent of pkg/) to sys.path instead, where pkg correctly exists as a subdirectory. The two invocation styles are not interchangeable for any file inside a real package -- -m is the one that actually understands package structure, which is why Example 64 introduces python3 -m app for exactly this reason before Kata 8 shows what breaks without it.