DEV Community: Samuel Ochaba

Garbage Collection Isn't Magic: Why Your App Still Leaks Memory

Samuel Ochaba — Sun, 21 Jun 2026 09:34:08 +0000

You picked JavaScript (or Python, or Go, or Java) partly so you'd never have to think about memory. No malloc, no free, no dangling pointers. The runtime cleans up after you.

So why does your app get slower the longer it runs? Why does the process climb from 80 MB to 1.5 GB overnight, then feel instant again the moment you restart, only to climb right back up?

Here is the uncomfortable truth: the garbage collector is working perfectly. It is reclaiming exactly what it was designed to reclaim. The leak is not a failure of the language. It is a data structure you wrote that holds a reference forever.

In this post I'll show how reachability actually works, why two styles of collector differ, and the one-line mental model that stops the most common memory leak in modern code. There's a working example at the end. ([I wrote more on profiling this here][add link].)

Garbage collection decides one question: is it reachable?

Modern collectors do not count how many times you use a value. They ask a single, sharp question: can I still get to this object from somewhere that matters?

The "somewhere that matters" set is called the roots. Roots are the live, in-scope things: local variables on the call stack, globals, event handlers the runtime still tracks. From those roots, the collector walks every reference, then every reference those references hold, and so on, marking everything it touches as alive. Everything it never reaches is garbage, and it gets freed in bulk.

That is the whole model. If you can draw a line of pointers from a root to your object, the object survives. If you can't, it dies.

This is beautiful and generous, and it has one sharp edge it never warns you about: the collector has no opinions about your data structures. If your cache holds a pointer to a task you looked at an hour ago, the collector traces that pointer, reaches the task, and concludes "alive." It is not leaking. It is obeying you.

Reachability is not reference counting

People often picture garbage collection as a tally: every object counts how many things point at it, and when the count hits zero, free it on the spot. That strategy is real, it's called reference counting, and some languages use it (Python's CPython is the famous example, with a tracing collector as backup).

It has one fatal flaw: cycles.

a = {}
b = {}
a["partner"] = b
b["partner"] = a
# a and b now reference each other.
# Each has a reference count of at least 1, forever,
# even if nothing else in the program can reach them.

Two objects pointing at each other never hit zero. A pure reference counter would hold them until the process exits.

The collectors in JavaScript, Go, and Java don't have this problem, because they don't count references at all. They trace from roots, periodically, and anything unreachable dies regardless of how many internal pointers it has. Cycles are free.

Which means: if you are debugging a memory leak in a tracing-collected language, the cycle explanation is a dead end. The real cause is almost always simpler.

The modern leak, with a real example

A reader was sketching a "recently viewed" menu for a task app. Clean, tiny feature. This was the heart of it:

const recent = [];

function trackView(task) {
  recent.push(task); // every task we ever look at lands here
  renderRecent(recent);
}

It felt great for the first fifty views. Then the UI slowed. Then it crawled. Restart, instant again, fifty more views, slow again.

Nothing is wrong with that push. Nothing is wrong with the language. The problem is that recent is a root-reachable array, and it holds a pointer to every task the user has ever opened. The collector traces the chain recent -> task, marks each task alive, and correctly refuses to free it. The array grows without bound. So does memory.

The fix is not smarter collection. It is to stop holding the reference:

const RECENT_LIMIT = 20;
const recent = [];

function trackView(task) {
  recent.push(task);
  if (recent.length > RECENT_LIMIT) {
    recent.shift(); // drop the oldest entry
    // nothing else points to it now -> unreachable -> collected
  }
  renderRecent(recent);
}

The moment shift() removes the last reference to an old task, the collector can no longer reach it from any root. Next collection cycle, that memory comes back. No free(), no delete. Just a data structure that finally agrees to let go.

A mental model that catches these before they ship

After the tenth leak of this shape, I wrote myself a one-line rule and taped it to the mental wall:

If a collection can grow without bound, treat it as a leak until proven otherwise.

When you review a PR, scan for these patterns:

Caches and "recent" lists with no eviction policy or size cap.
Event listeners or observers added but never removed, holding their context alive.
Closures that capture large objects they never actually need.
Global accumulators (logs, metrics, registries) that append forever.
Maps keyed by long-lived objects where stale keys are never deleted.

Each of these is a root-reachable structure quietly pinning memory in place. The collector is doing its job. The structure is doing yours, badly.

The takeaway

Automatic memory management is not automatic memory forgetting. The collector will reclaim everything you stop reaching for, and it will dutifully keep everything you keep reaching for, even if you forgot you still were.

So the next time your app slows and stays slow, before you blame the runtime, ask the only question that matters: what am I still pointing at?

I write about performance and clean architecture every week. Follow along if that's your kind of thing.

Over to you: what's the dumbest memory leak you've ever shipped, and how long did it take you to find it? Drop it below, I'm collecting war stories. 👇

Stop Hitting Yourself: The Quiet Lie in Function Signatures

Samuel Ochaba — Sun, 21 Jun 2026 09:25:41 +0000

Every codebase has a function like this:

function getUser(id: string): User {
  // ... fetch from DB ...
  return user;
}

It looks innocent. It is not. That signature makes a promise: give me an ID, I will hand you back a User. Except it will not. Sometimes there is no user. Sometimes the database is on fire. Sometimes the caller passed an ID that was never valid. The signature does not tell you which, and that silence is one of the most expensive bugs in software.

This post is about the difference between code that runs and code that is honest, and the three failure modes that separate them. It is short, it has working TypeScript, and by the end you will know exactly what to put in your type signatures the next time you are tempted to write return null or throw new Error(...) and move on.

The Lie Hiding in Plain Sight

A type signature is a contract. When you write getUser(id: string): User, you are telling every caller, every reviewer, and the compiler itself: this returns a User.

Then you do this:

function getUser(id: string): User {
  const user = db.findUser(id);
  if (!user) return null; // 🤥
  return user;
}

The signature still says User. The body returns null. The caller has no way to know without reading the implementation, and once you are reading the implementation, the type system has stopped doing its job. This is the family of bug Tony Hoare famously called his billion-dollar mistake: letting types promise a value they might not deliver.

So how do you fix it? First you have to realize there is not one kind of "something went wrong." There are three.

Exceptions, Errors, and Panics: Know the Difference

Most codebases treat every failure as an exception, and that is the root of the confusion. Let me untangle them.

Exceptions: for things you cannot handle

An exception is for exceptional conditions, things outside this function's control or knowledge:

the database is unreachable
a required config file is missing
a network call timed out mid-request
a programming bug, like calling a method on the wrong shape of object

The defining property: the current function does not know what to do, so it unwinds the stack and asks someone above it to figure it out. If nobody can, the request dies. That is the correct outcome. You genuinely did not know.

Errors: for things the caller must handle

An error is an expected, recoverable failure that belongs to the normal operation of the program:

the record was not found
the input failed validation
the user lacks permission
a file already exists

These are not exceptional. They are Tuesday. The function knows they are possible, and the right move is to return the failure so the caller is forced to deal with it, not throw it and hope.

Panics: for the impossible

A panic is for an unrecoverable invariant violation, a state the author believed could not happen:

a switch statement hits a case that should be unreachable
an array that was just checked is somehow empty
an internal counter is negative

You do not catch a panic. It means the program is in a state nobody designed for, and continuing would be worse than stopping. Crash loudly, with a stack trace, so somebody fixes it.

Make the Possibility Visible in the Type

Now the fix writes itself. "Record not found" is an error, not an exception. So do not throw, and do not sneakily return null. Make the absence part of the type:

function getUser(id: string): User | null {
  const user = db.findUser(id);
  return user ?? null;
}

Now the signature tells the truth: a User, or nothing. And TypeScript will not let the caller pretend otherwise:

const user = getUser(id);
console.log(user.email); // ❌ Error: 'user' is possibly 'null'

if (user !== null) {
  console.log(user.email); // ✅ narrowed to User
}

The compiler became your ally instead of your adversary. The bug that would have shipped at runtime now fails at tsc.

Want to carry a reason along with the absence? Reach for the richer version of the same idea:

type FindResult<T> =
  | { ok: true; value: T }
  | { ok: false; reason: "not_found" | "forbidden" };

function getUser(id: string): FindResult<User> { /* ... */ }

Same principle, more information. Either way, the signature stops lying.

Three Rules to Take With You

Throw for the exceptional. Return for the expected. Crash for the impossible.
If the caller needs to handle it, it goes in the type. null, a discriminated union, a Result. Never a silent lie.
Every signature is a promise. Make ones you can keep, and let the compiler enforce them.

Over to You

The next time you reach for throw new Error("not found") or return null on a typed User, ask the question that matters: what is my signature actually promising, and is it true?

I am genuinely curious how other teams draw the exception/error/panic line. Do you throw on "not found" and catch it later, return an optional, or use a full Result type? Tell me in the comments, I read all of them.

If this was useful, I write about TypeScript, system design, and the small decisions that compound in a codebase. Follow for the next one, and check out my earlier post on the same idea applied to optional fields.

Refactoring is not a bag of tricks. It is a professional discipline.

Samuel Ochaba — Thu, 09 Apr 2026 12:17:44 +0000

We built TekBreed because we think many developers are not struggling from a lack of information.

They are struggling from a lack of the right kind of training.

There is a difference.

Information tells you what something is.

Training helps you operate when the situation is unclear, messy, or high-stakes.

That difference is especially visible in refactoring.

That is why one of the sprints we are most excited about on TekBreed is:

Refactoring Mastery: Thinking & Building Like a Senior Engineer

Right now, during early access, the first milestone of that sprint is open for free until April 13, 2026, along with the first milestone of every premium sprint on the platform.

Why refactoring was one of the first topics we wanted to teach this way

Refactoring looks simple when you only see the polished version.

A blog post shows ugly code.

Then it shows cleaner code.

Then it explains the technique.

That is useful, but it does not fully train the real skill.

Behind the scenes, the real challenge in refactoring is not just knowing a technique.

It is knowing how to evaluate structure under real constraints.

That includes questions like:

What is safe to change right now?
What behavior must be preserved?
What part of this code is actually causing pain?
Should this be refactored now, later, or not at all?
Is this change improving the system or just making it look nicer?

That is closer to real engineering work.

And that is the kind of thinking we want TekBreed to support.

What TekBreed is trying to do differently

TekBreed is a software engineering learning platform built around deeper understanding, practical thinking, and more realistic skill development.

We are not trying to be just another place to consume tutorials.

We want the platform to help learners:

Build stronger mental models
Move beyond surface-level code familiarity
Interact with ideas more actively
Get help when they are stuck
Think more like practicing engineers

That is also where TekChat comes in.

Why TekChat matters

A learner usually does not need help only before or after a lesson.

They need help in the middle of it.

Inside the moment where something almost makes sense, but not quite.

Inside the moment where a concept becomes slippery.

Inside the moment where they need one more explanation, one more example, or one more reframing.

That is where TekChat is meant to be useful.

Behind the scenes, the goal is not to remove effort.

The goal is to support effort.

We want TekChat to help learners keep moving when they hit friction, instead of quietly dropping off.

And because we are in early access, we want people to use TekChat however they want and tell us where it is genuinely helpful and where it still needs work.

Why the refactoring sprint is a strong place to start

The refactoring sprint represents a lot of what we care about.

It is not only about code cleanup.

It is about engineering judgment.

It is about learning to think carefully about:

Structure
Safety
Behavior preservation
Tradeoffs
Decision-making under constraints

That is why the sprint is called:

Refactoring Mastery: Thinking & Building Like a Senior Engineer

We wanted the framing to be honest.

This is not “10 refactoring tricks.”

It is a more serious attempt to teach what better engineering judgment looks like in practice.

And because the first milestone is open, people can experience the direction of that sprint right now.

What early access looks like

From now until April 13, 2026:

TekBreed is open for early access
The first milestone of every premium sprint is free
TekChat can be used freely
Feedback is strongly encouraged

Then, from April 13 through April 30, 2026, subscribers get 30% off.

This is not meant to be a soft, polite preview.

We want real usage.

We want people to test the product properly.

We want them to try the refactoring sprint.

We want them to use TekChat heavily.

We want them to tell us what feels sharp, what feels unclear, and what breaks.

Because that is how the platform gets better.

Try the first milestone

If you are interested in refactoring, engineering judgment, or learning environments that go beyond passive tutorials, this is a good time to try TekBreed.

Start with the first milestone of the refactoring sprint.

Use TekChat while you go through it.

Then leave feedback.

The Python Bug That Bites Every Developer (Exactly Once)

Samuel Ochaba — Fri, 23 Jan 2026 13:59:05 +0000

I stared at my screen for 20 minutes, convinced Python was broken.

My function was supposed to return a fresh list every time. Instead, it was accumulating items like it had a memory. The third call somehow contained results from the first two.

def add_item(item, items=[]):
    items.append(item)
    return items

print(add_item("apple"))   # ['apple'] ✓
print(add_item("banana"))  # ['apple', 'banana'] ???
print(add_item("cherry"))  # ['apple', 'banana', 'cherry'] !!!

I expected ['banana']. I got ['apple', 'banana'].

This is Python's mutable default argument bug — and every Python developer gets bitten by it exactly once.

The Mental Model That's Lying to You

When you see items=[], your brain reads: "If no list is provided, create an empty one."

That's wrong.

What Python actually does: "Create one empty list **right now, when the function is defined, and reuse that same object for every call."

The default value isn't "an empty list" — it's a reference to one specific list object that was created when Python first read your function.

Let me prove it:

def add_item(item, items=[]):
    print(f"List id: {id(items)}")
    items.append(item)
    return items

add_item("a")  # List id: 4399504832
add_item("b")  # List id: 4399504832  ← Same object!
add_item("c")  # List id: 4399504832  ← Still same!

Every call uses the exact same list object. When you append to it, that change persists.

The Fix: Use None as a Sentinel

The solution is elegant once you understand the problem:

def add_item(item, items=None):
    if items is None:
        items = []  # Create a NEW list each call
    items.append(item)
    return items

print(add_item("apple"))   # ['apple']
print(add_item("banana"))  # ['banana'] ✓

Now each call that doesn't provide items gets a fresh list, created at call time, not definition time.

This pattern should become automatic for any mutable default:

# Lists
def process(items=None):
    if items is None:
        items = []
    ...

# Dictionaries
def merge(config=None):
    if config is None:
        config = {}
    ...

# Sets
def collect(seen=None):
    if seen is None:
        seen = set()
    ...

Why This Actually Matters

This isn't just a gotcha for interviews. It causes real bugs:

Caching gone wrong: Your memoization function "remembers" too much
API handlers accumulating state: Each request sees data from previous requests
Test pollution: Tests pass individually but fail when run together

I've seen this bug in production code from senior engineers. It's subtle because the function works perfectly the first time — the bug only appears on subsequent calls.

The Deeper Lesson

Python's object model is consistent: variables are names pointing to objects. When you write items=[], you're creating an object and storing a reference to it. That reference is evaluated once — when the def statement runs.

Understanding this doesn't just help you avoid one bug. It unlocks how Python actually works under the hood.

This article is adapted from my upcoming book, **Zero to AI Engineer: Python Foundations.

I share excerpts like this on Substack — follow along for more!

Why You Freeze When Starting a New Project (And 5 Questions to Fix It)

Samuel Ochaba — Sun, 18 Jan 2026 15:32:00 +0000

You know the feeling.

You have a great idea for a project. You open your code editor. You create main.py. The blinking cursor waits.

And you freeze.

What do you type first? Do you need a class? A function? A variable? Ten minutes later, you're checking Reddit because the paralyzed feeling is too uncomfortable.

This happens not because you can't code, but because you're trying to do two things at once: designing the software and building it.

Professional developers don't start by writing code. They start by asking questions.

Here is the Five Questions Framework I teach my students to turn any vague idea into a concrete blueprint before writing a single line of Python.

1. WHAT does it do? (The Menu)

Imagine you're opening a restaurant. Before you buy stoves or hire chefs, you need a menu.

Your "menu" is your feature list. Don't worry about how to build it yet. Just list what it does.

Example: A Simple Contact Book

Add new contacts
View all contacts
Search by name
Save to file

2. WHO does the work? (The Staff)

In a restaurant, the host greets you, the chef cooks, and the dishwasher cleans. They have distinct responsibilities.

Group your features into "staff members" or layers.

User Interface (UI): The "Host". Displays menus, asks for input.
Business Logic: The "Chef". Adds, searches, and deletes contacts.
Storage: The "Archive Manager". Saves and loads JSON files.

3. HOW are they connected? (The Kitchen Flow)

The host doesn't cook the burger. The host hands an order to the chef.

Draw a simple dependency line:
UI -> Logic -> Storage

This tells you something critical: The Storage layer doesn't know the UI exists. This is "Separation of Concerns," and it prevents your code from becoming spaghetti.

4. WHAT flows between them? (The Dish)

When the host hands an order to the chef, what is written on the ticket?

Decide your data structure now.

Is a "Contact" a tuple? ("Alice", "555-1234")
Or a dictionary? {"name": "Alice", "phone": "555-1234"}

Choosing a list of dictionaries now prevents painful refactors later.

5. WHAT operations exist? (The Recipes)

Now, listing the functions becomes easy. You just map the work to the "staff":

Storage Layer:

load_contacts()
save_contacts()

Logic Layer:

add_contact()
search_contacts()

UI Layer:

display_menu()
get_user_input()

The "Aha" Moment

By answering these five questions, you didn't write code, but you just designed a full architecture.

When you finally return to main.py, the paralysis is gone. You aren't "building a contact book." You're just implementing load_contacts(). Then display_menu(). Small, manageable tasks.

Stop staring at the cursor. Start asking questions.

This framework is adapted from my upcoming book, Zero to AI Engineer: Python Foundations, where we use it to design everything from CLI tools to AI pipelines.

I share excerpts like this on Substack → https://substack.com/@samuelochaba

Why Your Python Code Takes Hours Instead of Seconds (A 3-Line Fix)

Samuel Ochaba — Mon, 12 Jan 2026 12:48:44 +0000

Your code works. It passes every test. Then you run it on real data and go make coffee. Then lunch. Then you start questioning your career choices.

Here's the pattern that's probably killing your performance:

def has_duplicates(items):
    for i in range(len(items)):
        for j in range(i + 1, len(items)):
            if items[i] == items[j]:
                return True
    return False

This checks for duplicates by comparing every pair. Perfectly logical. Perfectly correct. Perfectly devastating at scale.

The Math That Ruins Your Day

List Size	Comparisons	Time
100	4,950	Instant
1,000	499,500	Instant
10,000	49,995,000	Noticeable
100,000	~5 billion	Many seconds
1,000,000	~500 billion	Hours

That nested loop means comparisons grow with the square of your data. Double the input, quadruple the time.

The 3-Line Fix

def has_duplicates(items):
    return len(items) != len(set(items))

This version is essentially instant even for a million items.

Why? Converting to a set is O(n) — you touch each element once. Checking length is O(1). No nested loops, no quadratic explosion.

The Pattern to Recognize

Whenever you see nested loops over the same collection, alarm bells should ring:

# 🚨 O(n²) — danger zone
for item in collection:
    if item in other_list:  # This is a hidden loop!
        ...

# ✅ O(n) — convert first
other_set = set(other_list)
for item in collection:
    if item in other_set:  # O(1) lookup
        ...

That innocent if item in other_list is doing a linear scan each time. With a set, it's a hash lookup — constant time regardless of size.

The Real-World Impact

This isn't academic. In AI engineering, you're constantly:

Deduplicating embeddings
Checking if items exist in large collections
Processing batches where nested loops sneak in

The difference between O(n²) and O(n) is the difference between "works on my machine" and "works in production."

This is adapted from my upcoming book, Zero to AI Engineer: Python Foundations.

I share excerpts like this on Substack → https://substack.com/@samuelochaba

Python Sets: remove() vs discard() — When Silence Is Golden

Samuel Ochaba — Sun, 11 Jan 2026 13:16:22 +0000

Python sets have two methods for removing elements: remove() and discard().

They look identical:

colors = {"red", "green", "blue"}
colors.remove("green")    # Works
colors.discard("green")   # Also works

But watch what happens when the element doesn't exist:

colors = {"red", "blue"}

colors.remove("yellow")   # KeyError: 'yellow'
colors.discard("yellow")  # Nothing happens. No error.

remove() raises an exception. discard() fails silently.

When to Use Each

Use remove() when missing elements are bugs:

def deactivate_user(active_users, user_id):
    active_users.remove(user_id)  # Should exist!
    # If it doesn't, something's wrong upstream

If user_id isn't in active_users, that's a logic error in your code. You want the exception to surface it.

Use discard() when missing elements are expected:

def cleanup_session(sessions, session_id):
    sessions.discard(session_id)  # May already be gone
    # User might have logged out twice, that's fine

Here, the session might have already been cleaned up. No need to crash over it.

The AI Engineering Context

This pattern appears constantly in data pipelines:

# Processing documents for RAG
processed_ids = set()

for doc in document_stream():
    if doc.id in processed_ids:
        continue

    processed_ids.add(doc.id)
    process(doc)

    # Cleanup: remove from pending queue
    pending_queue.discard(doc.id)  # Might not be there

Using discard() here prevents crashes when the same document appears in multiple streams.

The Decision Framework

Scenario	Use	Because
Element should exist	`remove()`	Missing = bug, surface it
Element might exist	`discard()`	Missing = expected, ignore it
Idempotent operations	`discard()`	Safe to call multiple times
Strict state management	`remove()`	Catch invalid transitions

One More Option

If you want to know whether removal happened without raising an error, combine in with discard():

if element in my_set:
    my_set.discard(element)
    print("Removed")
else:
    print("Wasn't there")

Though this is rarely necessary—usually you either care (use remove()) or you don't (use discard() and move on).

Which do you default to? Do you prefer loud failures or silent forgiveness?

This is adapted from my upcoming book, Zero to AI Engineer: Python Foundations.
I share excerpts like this on Substack → https://substack.com/@samuelochaba

Python Dictionary Views Are Live (And It Might Break Your Code)

Samuel Ochaba — Sat, 10 Jan 2026 19:16:04 +0000

Quick quiz. What does this print?

d = {"a": 1, "b": 2}
keys = d.keys()
print(keys)

d["c"] = 3
print(keys)

If you said:

dict_keys(['a', 'b'])
dict_keys(['a', 'b'])

You're wrong.

It prints:

dict_keys(['a', 'b'])
dict_keys(['a', 'b', 'c'])  # ← Updated automatically!

Dictionary Views Are Live

.keys(), .values(), and .items() don't return copies.

They return view objects—live windows into the dictionary that update automatically when the dictionary changes.

>>> person = {"name": "Alice", "age": 30}
>>> k = person.keys()
>>> k
dict_keys(['name', 'age'])

>>> person["city"] = "NYC"  # Add a key
>>> k                       # View updated automatically
dict_keys(['name', 'age', 'city'])

This is by design. Views are memory-efficient—they don't copy data.

But it can cause bugs if you're not expecting it.

The Bug This Causes

Imagine you're iterating over dictionary keys while modifying the dictionary:

config = {"debug": True, "verbose": False, "temp_flag": True}

# Remove all flags that are True
for key in config.keys():
    if config[key] is True:
        del config[key]  # 💥 RuntimeError!

You get:

RuntimeError: dictionary changed size during iteration

The view is live. When you delete a key, the view changes mid-iteration. Python catches this and throws an error.

The Fix

If you need to modify while iterating, convert to a list first:

config = {"debug": True, "verbose": False, "temp_flag": True}

# Convert to list - creates a snapshot
for key in list(config.keys()):
    if config[key] is True:
        del config[key]

print(config)  # {'verbose': False}

list(config.keys()) creates a static copy at that moment. Now you can modify the original dictionary freely.

When Live Views Are Useful

Live views aren't just a gotcha—they're actually powerful:

# Monitor changes in real-time
cache = {}
cache_keys = cache.keys()

# ... elsewhere in your code ...
cache["user_123"] = data
cache["user_456"] = more_data

# cache_keys automatically reflects all additions
print(f"Cached: {len(cache_keys)} items")  # Always current

No need to re-fetch .keys() every time. The view stays synchronized.

Did you know dictionary views were live? Has this ever caught you off guard?

This is adapted from my upcoming book, Zero to AI Engineer: Python Foundations.

I share excerpts like this on Substack → https://substack.com/@samuelochaba

Why Your Python Tuple Can't Be a Dictionary Key

Samuel Ochaba — Fri, 09 Jan 2026 09:02:43 +0000

"Tuples are immutable" is one of the first things you learn about Python tuples.

But check this out:

>>> t = ([1, 2], [3, 4])  # Tuple of lists
>>> t[0].append(99)        # Modify the list inside
>>> t
([1, 2, 99], [3, 4])      # It changed!

Wait—didn't we say tuples can't be modified?

The tuple itself didn't change. It still contains exactly two references to the same two list objects. What changed is the content of one of those list objects.

Think of it like a display case with two fish tanks inside. You can't add or remove tanks from the case (the tuple is immutable), but the fish inside each tank can still swim around (the lists are mutable).

This has real consequences:

>>> t = ([1, 2], [3, 4])
>>> hash(t)
Traceback (most recent call last):
  ...
TypeError: unhashable type: 'list'

Tuples containing mutable objects cannot be hashed—which means they can't be dictionary keys or set members.

Why this matters for AI engineering:

When you're working with embeddings, model outputs, or cached results, you might think "I'll use a tuple as a cache key." But if that tuple contains any mutable objects (lists, dicts, sets), you'll get a TypeError at runtime.

The fix: ensure all elements are also immutable:

# This works as a cache key
key = (model_name, tuple(input_ids), temperature)

# This fails
key = (model_name, input_ids, temperature)  # if input_ids is a list

This is adapted from my upcoming book, Zero to AI Engineer: Python Foundations.
I share excerpts like this on Substack → https://substack.com/@samuelochaba

You Know Python Basics—Now Let's Build Something Real

Samuel Ochaba — Thu, 08 Jan 2026 13:56:26 +0000

Who this is for: You've completed a Python basics course or tutorial. You understand variables, loops, conditionals, and strings. But you haven't built anything real yet. This project is specifically for that stage.

You've learned variables, loops, conditionals, and string methods. Each concept made sense in isolation. But when you stared at a blank file and tried to build something... nothing came together.

This is the gap between knowing syntax and actually programming.

I just open-sourced a project specifically designed to bridge that gap: a text adventure game that combines all those foundational concepts into one playable program.

Repo: github.com/samuel-ochaba-dev/zero-to-ai-engineer-projects

What You'll Practice

This isn't just another tutorial—it's a consolidation project. Every Python basic you've learned has a job:

Concept	How It's Used
Variables & Data Types	Game state, rooms, player info
Dictionaries	Nested data for the game world
Operators	Health checks, item membership
String Methods	`.strip()`, `.lower()`, `.split()`, `.join()`
User Input	Interactive `input()` game loop
Conditionals	`if-elif-else` and `match/case` for commands
While Loops	Main game loop
For Loops	Iterating inventory with `enumerate()`
Type Hints	Self-documenting function signatures

The point isn't to learn new syntax. The point is to combine concepts you already know.

How to Get the Most from This

Don't just run the code. That's the mistake most people make with learning projects.

Instead:

1. Read the code without running it first

Trace through the main loop. Predict what happens when you type go north or take torch. Then run it to check your mental model.

2. Break something intentionally

Remove a line. Change a condition. See what error you get. This teaches you what each piece is actually doing.

3. Extend it

The repo includes practice exercises:

Add a new room with items
Implement a locked door puzzle (requires a key)
Add a scoring system
Create new random events

Building on existing code is how real projects work.

The Pattern You'll Keep Using

The main game loop looks like this:

while game_running:
    # Check win/lose conditions
    # Display current state
    # Get player input
    # Process command
    # Trigger random events

This pattern—a loop that reads input, processes it, updates state, and displays results—appears everywhere:

CLI tools
Chat applications
AI chatbots (read user message → send to LLM → display response → repeat)
Game engines
REPLs

Once you understand this pattern deeply, you'll recognize it in every interactive program you encounter.

Requirements

Python 3.10+ (required for match/case syntax)
No external dependencies

git clone https://github.com/samuel-ochaba-dev/zero-to-ai-engineer-projects.git
cd zero-to-ai-engineer-projects/dungeon-escape-text-adventure-game
python3 adventure_game.py

Sample Gameplay

========================================
       DUNGEON ESCAPE
========================================

You wake up in a dark dungeon.
Find the exit to escape!
Type 'help' for available commands.

You are in the Entrance Hall.
A dusty entrance with cobwebs covering the walls.
A faint light flickers from the north.

Exits: north, east
Items here: torch

Health: 100 | Inventory: empty

What do you do? >

Navigate through rooms, collect items, survive random events, and find the exit.

The mental shift from "I know what a while loop is" to "I can use a while loop to build a game loop" is significant. This project is designed to make that shift concrete.

Clone it. Break it. Extend it.

This is adapted from my upcoming book, Zero to AI Engineer: Python Foundations.
I share excerpts like this on Substack → https://substack.com/@samuelochaba

Type Hints Make AI Code Generation Significantly Better

Samuel Ochaba — Wed, 07 Jan 2026 07:54:47 +0000

If you're using AI coding assistants without type hints, you're leaving performance on the table.

When you ask an AI to complete this:

def process(data):
    # TODO: split by comma and return uppercase words

The AI has to guess what data is. A string? A file? A list?

But with type hints:

def process(data: str) -> list[str]:
    # TODO: split by comma and return uppercase words

Now the AI knows:

data is definitely a string
It should return a list of strings
Methods like .split() and .upper() are appropriate

The result: More accurate completions, fewer hallucinations, less back-and-forth.

This extends to entire codebases. When your functions have type hints, AI tools can:

Generate code that matches your existing types
Suggest appropriate methods for the given types
Catch inconsistencies in their own output
Understand relationships between modules

Where this matters most:

API handlers (FastAPI uses type hints for automatic validation)
Data processing pipelines
Any code that interfaces with AI-generated components

Type hints are documentation for both humans and machines. In 2026, that dual purpose matters more than ever.

This is adapted from my upcoming book, Zero to AI Engineer: Python Foundations.

I share excerpts like this on Substack → https://substack.com/@samuelochaba

Python Comprehensions Are Declarative (And Why That Matters)

Samuel Ochaba — Tue, 06 Jan 2026 00:48:33 +0000

Two ways to square every number in a list:

# Version A
squares = []
for num in numbers:
    squares.append(num ** 2)

# Version B
squares = [num ** 2 for num in numbers]

Version A tells Python how to build the list:

Create empty list
Loop through numbers
Compute square
Append to list
Repeat

Version B tells Python what you want:
"A list of squared numbers."

This is the difference between imperative and declarative code.

Why Declarative Wins

Consider reading code you didn't write. With Version A, you have to trace the loop logic to understand the result. With Version B, the intent is immediate.

More importantly, declarative code is harder to mess up. In Version A, you could:

Forget to initialize squares = []
Misspell .append() as .appnd()
Accidentally append the wrong value
Break the loop prematurely

Version B eliminates these failure modes. The pattern is baked in.

The Newspaper Test

Ask yourself: "Can I understand this comprehension in one quick read?"

Passes:

[x ** 2 for x in numbers if x > 0]

Fails:

[(x, y) for x in range(10) for y in range(10)
 if x != y and (x + y) % 2 == 0 and x ** 2 + y ** 2 < 50]

If you have to stop and puzzle it out, the comprehension is too complex. Use a loop instead.

When Loops Are Better

Comprehensions aren't always right. Use loops when:

Multiple statements per item:

for item in items:
    item.validate()
    item.save()
    results.append(item.id)

Side effects:

# DON'T do this - creates useless list of Nones
[print(x) for x in items]

# DO this
for x in items:
    print(x)

Complex control flow:

for x in items:
    if not validate(x):
        continue
    if x.score <= threshold:
        break
    process(x)

The Mindset Shift

Think of comprehensions as expressions that produce collections, not loops that build them.

When you write [f(x) for x in items], you're saying: "This IS a list of f(x) values." Not "This becomes a list through these steps."

Once you internalize this, you'll reach for comprehensions naturally—and know when a loop serves you better.

This is adapted from my upcoming book, Zero to AI Engineer: Python Foundations.
I share excerpts like this on Substack → https://substack.com/@samuelochaba