Python

This is the beginning: how to store a value under a name, and the four kinds of value everything else is built out of — text, whole numbers, decimals, and true or false. Most of what you do in Python is done to text, so a good part of this section is what you can do to a string and how to build one out of other values. It assumes you have never written a line of code.

Variables#

A variable is a name for a value. You do not declare a type. Python works it out from what you assign.

name = "Jack"
age = 29
price = 19.99
is_active = True

Those are the four basic types: str for text, int for whole numbers, float for decimals, bool for true or false. You can check any value's type with type().

type(name)        # <class 'str'>
type(age)         # <class 'int'>

Strings#

A string is text. Single or double quotes both work. Use triple quotes when you need several lines.

a = 'hello'
b = "hello"
c = """line one
line two"""

Here are the string operations you will use most often.

s = "Hello World"

len(s)              # 11
s.upper()           # 'HELLO WORLD'
s.lower()           # 'hello world'
s.replace("World", "Python")   # 'Hello Python'
s.split(" ")        # ['Hello', 'World']
s.strip()           # removes spaces at both ends
s.startswith("He")  # True
"World" in s        # True

You can pick out parts of a string by position. Counting starts at 0. This is called slicing.

s = "Python"

s[0]       # 'P'    first character
s[-1]      # 'n'    last character
s[0:3]     # 'Pyt'  characters 0, 1, 2
s[2:]      # 'thon' from position 2 to the end
s[:2]      # 'Py'   up to but not including position 2
s[::-1]    # 'nohtyP'  reversed

Joining strings together#

You can add strings with +, but join is better when you have many pieces.

first = "Hello"
second = "World"

first + " " + second          # 'Hello World'

words = ["Hello", "World", "again"]
" ".join(words)               # 'Hello World again'
", ".join(words)              # 'Hello, World, again'

Why join is better: each + creates a brand new string and copies everything so far. With 10 pieces you will not notice. With 10,000 pieces in a loop, the program crawls. join builds the result in one pass.

# Slow with many lines
out = ""
for line in lines:
    out = out + line

# Fast
out = "".join(lines)

f-strings#

An f-string lets you put variables directly inside text. Put an f before the quote and wrap the variable in curly braces. This is the normal way to build text in modern Python.

name = "Jack"
tokens = 1250

f"Hello {name}"                 # 'Hello Jack'
f"Used {tokens} tokens"         # 'Used 1250 tokens'
f"Double: {tokens * 2}"         # 'Double: 2500'

You can control how numbers look by adding a colon and a format code.

cost = 0.0374125

f"{cost:.2f}"       # '0.04'     two decimal places
f"{cost:.4f}"       # '0.0374'   four decimal places
f"{1250:,}"         # '1,250'    thousands separator
f"{0.37:.0%}"       # '37%'      as a percentage

Numbers#

Two kinds of division catch people out, so learn them together.

7 / 2       # 3.5    always gives a float
7 // 2      # 3      floor division, drops the remainder
7 % 2       # 1      the remainder
2 ** 10     # 1024   power

round(3.7)        # 4
int("42")         # 42     text to number
str(42)           # '42'   number to text

None, True and False#

None means no value. It is what a function returns when it does not return anything. It is not zero and not an empty string.

Python also treats some values as false when you use them in an if statement. These are all falsy: False, None, 0, empty string, empty list, empty dict.

items = []

if items:
    print("has items")
else:
    print("empty")        # this runs

One value under one name gets you a short way. Real programs hold groups of things: a list of results, a record with named fields, a set of items already seen. This section covers Python's three main containers, how to loop over each, and how to choose between them, which usually comes down to whether order matters and whether you look things up by name or by position.

Lists#

A list holds items in order. It can hold duplicates. Square brackets.

topics = ["python", "sql", "git"]

topics[0]              # 'python'
topics[-1]             # 'git'
len(topics)            # 3

topics.append("rag")            # add to the end
topics.insert(0, "linux")       # add at a position
topics.remove("sql")            # remove by value
topics.pop()                    # remove and return the last item
"git" in topics                 # True

Sorting is worth knowing properly, because it comes up constantly.

nums = [5, 2, 9, 1]

sorted(nums)                  # [1, 2, 5, 9]  returns a NEW list
nums.sort()                   # sorts nums in place, returns None
sorted(nums, reverse=True)    # [9, 5, 2, 1]

# Sorting by something other than the value itself
people = [{"name": "A", "age": 30}, {"name": "B", "age": 25}]
sorted(people, key=lambda p: p["age"])

Dictionaries#

A dictionary maps a key to a value. Think of a real dictionary: you look up a word and get its meaning. Curly braces.

user = {"name": "Jack", "role": "engineer", "years": 5}

user["name"]                # 'Jack'
user["city"] = "Berlin"     # add a new key
del user["years"]           # remove a key
"role" in user              # True
len(user)                   # number of keys

Looking up a key that does not exist raises an error. get() returns None instead, or a default you choose. Use get whenever the key might be missing.

user["city"]              # KeyError if missing
user.get("city")          # None if missing
user.get("city", "n/a")   # 'n/a' if missing

Looping over a dictionary gives you the keys unless you ask for more.

for key in user:
    print(key)

for key, value in user.items():
    print(key, value)

user.keys()      # all keys
user.values()    # all values

Sets#

A set holds unique items with no order. Adding something twice changes nothing. Its main use is removing duplicates and checking membership quickly.

tags = {"python", "ai", "python"}   # {'python', 'ai'}

tags.add("sql")
tags.discard("ai")

a = {1, 2, 3}
b = {2, 3, 4}
a & b       # {2, 3}       in both
a | b       # {1, 2, 3, 4} in either
a - b       # {1}          in a only

# Removing duplicates from a list
unique = list(set([1, 2, 2, 3, 3, 3]))

Sets matter for speed. Checking whether something is in a list means looking at every item one by one. Checking a set is instant, no matter how big it is. If you are checking membership inside a loop, use a set.

seen = ["a1", "b2", "c3"]      # slow to search when large
seen = {"a1", "b2", "c3"}      # fast, always

if "b2" in seen:
    ...

Which one should you use?#

• Order matters and duplicates are fine, use a list.
• You look things up by a name or id, use a dictionary.
• You need uniqueness, or you check membership a lot, use a set.
• The values are fixed and must never change, use a tuple.

Comprehensions#

A comprehension builds a list in one line. It does the same job as a loop with append, and Python programmers expect to see it.

# The long way
squares = []
for n in range(5):
    squares.append(n * n)

# The same thing
squares = [n * n for n in range(5)]      # [0, 1, 4, 9, 16]

You can filter at the same time by adding an if at the end.

nums = [1, 2, 3, 4, 5, 6]

evens = [n for n in nums if n % 2 == 0]        # [2, 4, 6]

names = [u["name"] for u in users]
adults = [u for u in users if u["age"] >= 18]

# Dictionary and set comprehensions work the same way
by_id = {u["id"]: u for u in users}
roles = {u["role"] for u in users}

So far a program runs from top to bottom and does the same thing every time. This section is about the three ways that changes: doing something only when a condition holds, doing something repeatedly, and packaging a piece of work under a name so it can be called from anywhere with different inputs. Functions are the larger half — nearly all the code you will read is organised into them.

Conditions#

Python uses indentation instead of braces. Everything indented under the if belongs to it. Four spaces is the convention.

score = 72

if score >= 90:
    grade = "A"
elif score >= 70:
    grade = "B"
else:
    grade = "C"

# Comparisons
==  !=  <  >  <=  >=

# Combining them
if age > 18 and has_id:
    ...
if role == "admin" or role == "owner":
    ...
if not is_blocked:
    ...

# Python lets you chain comparisons
if 0 < score < 100:
    ...

Loops#

A for loop walks through anything you can iterate: a list, a string, a dictionary, a range.

for topic in topics:
    print(topic)

for i in range(5):          # 0, 1, 2, 3, 4
    print(i)

for i in range(1, 6):       # 1 to 5
    print(i)

# When you need the position as well as the item
for index, topic in enumerate(topics):
    print(index, topic)

# When you need to walk two lists together
for name, score in zip(names, scores):
    print(name, score)

break leaves the loop entirely. continue skips to the next iteration.

for n in numbers:
    if n < 0:
        continue        # skip negatives
    if n > 100:
        break           # stop completely
    process(n)

A while loop runs until its condition becomes false. Use it when you do not know how many times you will loop, such as retrying until something succeeds.

attempts = 0
while attempts < 3:
    if try_once():
        break
    attempts += 1

Functions#

A function is a named block of code that takes inputs and gives back a result. def defines it, return sends a value back.

def greet(name):
    return f"Hello {name}"

message = greet("Jack")     # 'Hello Jack'

A function without a return statement gives back None. That is fine for functions that only print or save something.

Arguments can have defaults, which makes them optional when calling.

def call_model(prompt, model="fast", temperature=0.0):
    ...

call_model("hello")
call_model("hello", model="strong")
call_model("hello", temperature=0.7)

# Wrong
def add(item, items=[]):
    items.append(item)
    return items

# Right
def add(item, items=None):
    if items is None:
        items = []
    items.append(item)
    return items

Scope#

A variable created inside a function only exists inside it. The function can read variables from outside, but assigning to one creates a new local variable rather than changing the outer one.

count = 0

def increment():
    count = count + 1      # UnboundLocalError

def increment():
    global count           # works, but avoid this
    count = count + 1

def increment(count):      # better: pass it in, return it out
    return count + 1

Prefer the last version. Functions that take what they need and return a result are easier to test and easier to reason about than ones that reach out and change things elsewhere.

Lambda#

A lambda is a small function written in one line, with no name. You will mostly see it as the key argument to sorted.

sorted(people, key=lambda p: p["age"])

# The same thing written normally
def get_age(p):
    return p["age"]

sorted(people, key=get_age)

Three things a program needs the moment it leaves your own machine. What to do when something fails instead of stopping dead. How to read and write files, including JSON, which is the format almost every API speaks. And how to split code across several files and use one from another. Handling failure properly is what decides whether a bad response costs you one request or the whole run.

Handling errors#

When something goes wrong Python raises an exception and stops. try and except let you catch it and decide what to do.

try:
    age = int(user_input)
except ValueError:
    print("That is not a number")

The common built-in errors are worth recognising on sight.

• ValueError: right type, wrong value. int("abc") raises this.
• TypeError: wrong type entirely. "2" + 2 raises this.
• KeyError: that key is not in the dictionary.
• IndexError: that position is past the end of the list.
• FileNotFoundError: no file at that path.
• AttributeError: that object has no such method or attribute. Usually means the value is None.

Always name the exception you are catching. A bare except catches everything, including your own typos and the Ctrl-C that stops the program.

# Bad: hides real bugs
try:
    result = process(data)
except:
    result = None

# Good: catches one thing, on purpose
try:
    result = json.loads(raw)
except json.JSONDecodeError:
    result = None

else runs if nothing went wrong. finally always runs, whether or not it did.

try:
    data = fetch()
except TimeoutError:
    log("timed out")
else:
    save(data)          # only if fetch succeeded
finally:
    close_connection()  # always

Raising your own#

Raise an error when your function is given something it cannot work with. Failing loudly and early beats returning something wrong.

def set_temperature(value):
    if not 0 <= value <= 2:
        raise ValueError(f"temperature must be 0 to 2, got {value}")
    ...

# Your own error type, for when callers need to tell yours apart
class ModelOutputError(Exception):
    pass

raise ModelOutputError("model returned invalid JSON")

Files#

Always open files with a with block. It closes the file for you, including when something raises partway through.

# Reading
with open("notes.txt") as f:
    content = f.read()          # whole file as one string

with open("notes.txt") as f:
    for line in f:              # one line at a time, memory friendly
        print(line.strip())

# Writing
with open("out.txt", "w") as f:     # "w" overwrites
    f.write("hello\n")

with open("out.txt", "a") as f:     # "a" appends
    f.write("another line\n")

JSON#

JSON is how data moves between systems, including every API you will call. Python converts between JSON text and dictionaries with two pairs of functions.

import json

# Text to Python
data = json.loads('{"name": "Jack"}')     # from a string
with open("config.json") as f:
    data = json.load(f)                     # from a file

# Python to text
text = json.dumps(data)                     # to a string
text = json.dumps(data, indent=2)           # readable
with open("out.json", "w") as f:
    json.dump(data, f, indent=2)            # to a file

Modules#

Any Python file is a module. Importing one makes its functions available. This is how you split a program into files instead of one enormous script.

import json                       # whole module
from pathlib import Path          # one thing from a module
from collections import Counter, defaultdict
import numpy as np                # with a shorter name

# Your own file, helpers.py, in the same folder
from helpers import clean_text

Three standard library tools are worth knowing now, because they save you writing code by hand.

from collections import Counter, defaultdict
from pathlib import Path

Counter(["a", "b", "a"]).most_common(1)   # [('a', 2)]

groups = defaultdict(list)
groups["fruit"].append("apple")           # no need to create the list first

Path("data/out.json").parent.mkdir(parents=True, exist_ok=True)

A type hint is a note in the code saying what kind of value belongs where. Python ignores hints while running, but your editor and a type checker read them, so a mistake surfaces as you type rather than in production. This section covers the annotations worth writing, then pydantic, which uses the same syntax to check data arriving from outside your program — an API response, a form, a model's output — and to reject it clearly when it is wrong.

What a type hint is#

A type hint says what kind of value something should be. Python ignores hints while running. Your editor and a type checker read them and warn you before you run anything.

def greet(name: str) -> str:
    return f"Hello {name}"

count: int = 0
prices: list[float] = []
user: dict[str, str] = {}

The practical benefit is autocomplete. Once your editor knows a variable is a str, it can offer you every string method. Without hints it can only guess.

Values that might be missing#

This is the most useful thing type hints do. If a function might return nothing, say so, and the checker will insist that callers handle it.

def find_user(user_id: str) -> dict | None:
    ...

user = find_user("abc")
print(user["name"])          # warning: user might be None

if user is not None:
    print(user["name"])      # fine now

The common shapes#

from typing import Literal

names: list[str]
scores: dict[str, int]
pair: tuple[int, int]
value: int | str                        # either one
role: Literal["user", "assistant"]      # only these exact strings

Where hints stop being enough#

Nothing checks a hint at runtime. If an API sends you a string where you declared an int, Python will not complain and your code will break later with a confusing error. For data arriving from outside your program, you need real validation.

pydantic#

pydantic takes a class definition and turns it into a validator. You describe the shape once, and it checks incoming data against it and converts types where it safely can.

from pydantic import BaseModel

class User(BaseModel):
    name: str
    age: int
    email: str | None = None      # optional, defaults to None

user = User(name="Jack", age=29)
user.name                          # 'Jack'

User(name="Jack", age="29")      # works: "29" converts to 29
User(name="Jack", age="abc")     # raises ValidationError

Field adds rules the type alone cannot express.

from pydantic import BaseModel, Field

class Invoice(BaseModel):
    number: str
    amount: float = Field(gt=0)                    # must be positive
    currency: str = Field(min_length=3, max_length=3)
    overdue: bool = False

When validation fails you get a list of every problem, not just the first, which makes it possible to tell a user everything that is wrong at once.

from pydantic import ValidationError

try:
    invoice = Invoice.model_validate_json(raw_text)
except ValidationError as e:
    for err in e.errors():
        field = ".".join(str(p) for p in err["loc"])
        print(f"{field}: {err['msg']}")

Why this matters for AI work#

A model returns text. That text is untrusted, exactly like input from a stranger. A pydantic model is where it stops being a guess and becomes something you can rely on. pydantic can also produce a JSON schema from your class, and that schema is exactly what tool definitions and structured output requests need.

Invoice.model_json_schema()
# Send this to the API as the required output shape,
# then validate the response with the same class.

Calling a model API is mostly waiting. Make a hundred calls one after another and your program spends nearly its whole life doing nothing, so the fix is to have many in flight at once. This section covers how Python expresses that, how to start many and collect the results, how to cap the number running so you do not trip a rate limit, and the one mistake that quietly turns concurrent code back into sequential code.

The problem async solves#

A call to a model API takes a few seconds, and your program spends nearly all of that time doing nothing but waiting for the reply. If you make fifty calls one after another, you wait fifty times.

# 50 calls, 2 seconds each, about 100 seconds total
for doc in docs:
    summarise(doc)

Async lets you start all fifty and wait for them together. The total becomes roughly the time of one call. This is the single biggest speed improvement available in most code that talks to an API.

The syntax#

Mark a function async def, and use await when calling something that takes time. A function marked async does not run on its own, it has to be started by asyncio.run or awaited from another async function.

import asyncio

async def summarise(doc: str) -> str:
    return await call_model(doc)

async def main():
    result = await summarise("some text")
    print(result)

asyncio.run(main())          # starts everything

Running many at once#

gather starts everything together and waits for all of it. Results come back in the order you passed them in.

async def main(docs):
    results = await asyncio.gather(*(summarise(d) for d in docs))
    return results

By default, if one of them raises, gather cancels the rest and raises. In a batch job that is usually wrong: one bad document should not lose the other forty-nine. Pass return_exceptions=True and the failures come back as values you can inspect.

results = await asyncio.gather(*tasks, return_exceptions=True)

for doc, result in zip(docs, results):
    if isinstance(result, Exception):
        log(f"failed: {doc}", result)
    else:
        save(result)

Not too many at once#

Firing five hundred requests simultaneously will get you rate limited. A semaphore is a counter that only lets a fixed number through at a time, and queues the rest.

async def run_all(docs, limit=8):
    sem = asyncio.Semaphore(limit)

    async def one(doc):
        async with sem:                       # waits for a free slot
            async with asyncio.timeout(60):   # give up after 60s
                return await summarise(doc)

    return await asyncio.gather(*(one(d) for d in docs), return_exceptions=True)

Put a timeout on anything that touches the network. Without one, a single stalled connection holds a slot forever and the job never finishes.

The mistake that undoes everything#

import requests, httpx, asyncio

# Blocks the whole event loop
async def bad(url):
    return requests.get(url).text

# Correct: an async client
async def good(url):
    async with httpx.AsyncClient() as client:
        r = await client.get(url)
        return r.text

# When you have no async option
async def fallback(path):
    return await asyncio.to_thread(heavy_sync_read, path)

When async does not help#

Async only helps when you are waiting. If the work is calculation rather than waiting, there is still only one thread doing all of it, so async adds complexity and speeds up nothing. For heavy computation you want multiprocessing instead.

A list holds everything at once, which is fine until the everything is a ten-gigabyte file. A generator hands you one item at a time and remembers where it got to, so you can work through data far larger than memory, and start handling a model's reply before it has finished arriving. This section covers what an iterator is, how to write a generator, how to batch, and the async version used for streaming responses.

The idea#

A normal function computes everything and returns it all at once. A generator produces one value at a time and pauses in between, remembering where it was. Nothing is computed until you ask for it.

# Returns a list of 1,000,000 numbers. All in memory at once.
def squares_list(n):
    return [i * i for i in range(n)]

# Produces them one at a time. Almost no memory.
def squares_gen(n):
    for i in range(n):
        yield i * i

for value in squares_gen(1_000_000):
    print(value)

Why this matters#

Reading a very large file with read() loads all of it into memory and may fail. Looping over the file object reads one line at a time, so the size of the file stops mattering.

# Loads the whole file
with open("huge.jsonl") as f:
    lines = f.readlines()

# Reads one line at a time
def records(path):
    with open(path) as f:
        for line in f:
            yield json.loads(line)

for record in records("huge.jsonl"):
    process(record)

Generator expressions#

A comprehension with round brackets instead of square ones is a generator. Use it when you are going to loop over the result once and do not need to keep it.

squares = [n * n for n in range(1000)]     # a list, held in memory
squares = (n * n for n in range(1000))     # a generator, produced on demand

total = sum(n * n for n in range(1000))    # no list is ever built

Batching#

Most embedding and inference APIs take batches, so you will regularly need to turn a long stream into fixed-size groups.

from itertools import batched

for chunk in batched(records("huge.jsonl"), 64):
    embed(chunk)        # a tuple of up to 64 items

# Before Python 3.12, written by hand
def batched_manual(items, size):
    batch = []
    for item in items:
        batch.append(item)
        if len(batch) == size:
            yield batch
            batch = []
    if batch:
        yield batch      # do not lose the last partial batch

Streaming responses#

When an API streams a reply, it arrives as an async generator. You loop with async for, and each pass waits for the next piece.

async def collect(stream):
    parts = []
    async for chunk in stream:
        parts.append(chunk.text)
        print(chunk.text, end="", flush=True)   # show it as it arrives
    return "".join(parts)

One consequence worth remembering: you cannot check the shape of a streamed response until it has finished. Any JSON parsing or schema validation has to happen after the loop, not inside it.

A test is a small piece of code that runs your code and checks the answer. The reason to write them is not diligence: it is that they let you change something six months later and find out in seconds whether you broke anything. This section covers pytest, running the same logic against many inputs, sharing setup between tests, and standing in fakes for slow or paid dependencies — which matters in AI work, where a real model call costs money and answers differently each time.

Your first test#

A test is a function whose name starts with test_ containing a plain assert. pytest finds them and runs them. There is no base class and no special assertion methods.

# add.py
def add(a, b):
    return a + b

# test_add.py
from add import add

def test_adds_two_numbers():
    assert add(2, 3) == 5

def test_handles_negatives():
    assert add(-1, 1) == 0

pytest                  # run everything
pytest test_add.py      # one file
pytest -k "negative"    # only tests matching a name
pytest -v               # show each test name

Many inputs, one test#

parametrize runs the same test once per set of inputs, and reports each one separately when it fails. This replaces copying a test five times with different values.

import pytest

@pytest.mark.parametrize(
    "raw, expected",
    [
        ("42", 42),
        (" 42 ", 42),
        ("0", 0),
    ],
)
def test_parses_int(raw, expected):
    assert parse_int(raw) == expected

Testing that something raises#

def test_rejects_bad_temperature():
    with pytest.raises(ValueError):
        set_temperature(5)

def test_error_message_is_useful():
    with pytest.raises(ValueError, match="must be 0 to 2"):
        set_temperature(5)

Fixtures#

A fixture is setup shared between tests. Declare it once, then take it as an argument in any test that needs it.

@pytest.fixture
def sample_records():
    return [
        {"id": "1", "score": 0.9},
        {"id": "2", "score": 0.4},
    ]

def test_filters_by_score(sample_records):
    result = above(sample_records, 0.5)
    assert len(result) == 1

Fakes, not mocks everywhere#

Replace the thing at the edge of your system, such as the model client, with a simple object that returns fixed answers. Do not replace your own functions with mocks. A test that only checks a mock was called proves nothing and keeps passing after you break the behaviour.

class FakeModel:
    def __init__(self, replies):
        self.replies = list(replies)
        self.calls = 0

    def call(self, prompt):
        self.calls += 1
        return self.replies.pop(0)

def test_agent_stops_at_turn_limit():
    model = FakeModel(["think", "think", "think"])
    agent = Agent(model=model, max_turns=2)

    agent.run("anything")

    assert model.calls == 2

What you can test in an AI system#

More than people expect. The model's output is not predictable, but everything around it is, and that is where most bugs live.

• Testable normally: parsing responses, retry logic, budget and turn limits, tool dispatch, building the message list, cost calculation.
• Not unit testable: whether the model's answer is good. That needs evals, which are a different tool for a different job.

Code that runs on your machine and nowhere else is not finished. This section covers what makes a project portable: a virtual environment so each project keeps its own packages and versions, pinned dependencies so a colleague installs exactly what you did, a layout people expect to find, and tools that format and check the code for you. It ends on reading a traceback, which is the single most useful debugging skill in the language.

Virtual environments#

A virtual environment is a folder holding its own copy of Python and its own packages. Each project gets one, so two projects can use different versions of the same library without fighting.

python3 -m venv .venv           # create it
source .venv/bin/activate       # turn it on (Mac and Linux)
.venv\Scripts\activate          # Windows

which python                    # .../project/.venv/bin/python
deactivate                      # turn it off

Activating simply puts that folder first in your PATH, which is the list of places your shell searches for commands. So typing python finds the project copy instead of the system one. That is the whole mechanism.

Dependencies#

pip install requests
pip install "pydantic>=2.0"
pip freeze > requirements.txt      # record exact versions
pip install -r requirements.txt    # install them elsewhere

Recording exact versions matters more than it seems. Without it, a project that builds today can break in three weeks because a library you never named published an update. The failure arrives in CI on an unrelated change and costs an afternoon.

Project layout#

myproject/
  .venv/              never committed
  .env                secrets, never committed
  .gitignore
  pyproject.toml      project and dependency declaration
  README.md
  src/
    myproject/
      __init__.py
      main.py
  tests/
    test_main.py

Secrets belong in a .env file that is listed in .gitignore, and are read at runtime. An API key committed to a public repository is scanned and abused within minutes.

import os
from dotenv import load_dotenv

load_dotenv()
api_key = os.environ["GEMINI_API_KEY"]

Tooling#

• ruff: linting and formatting in one tool, fast enough to run every time you save.
• uv: a much faster replacement for pip and venv, worth adopting on new projects.
• A type checker in your editor, so annotations help you while you type rather than in CI.

ruff check .          # find problems
ruff check --fix .    # fix what it can
ruff format .         # format everything

Reading a traceback#

Read a traceback from the bottom up. The last line is the actual error. The lines above it are the path of calls that led there, oldest at the top.

Traceback (most recent call last):
  File "main.py", line 12, in <module>
    result = process(data)
  File "process.py", line 8, in process
    return item["name"]
KeyError: 'name'

When the trace runs through library code, find the last line that belongs to you. That is almost always where the problem is, because the library is usually doing exactly what it was told.