Building a Countdown Timer CLI in Python — time, finally, mock, and Testing Exceptions

Introduction

This is my tenth article as a Java engineer learning TypeScript and Python from scratch.

This is the third project in my Python series. The first was a weight tracker CLI (type hints, pure functions, separating I/O from logic), and the second was a password generator CLI (string, random, any, and a testing strategy for randomness).

This time I built a countdown timer CLI. You pick a number of seconds from a menu, and it counts down one second at a time. Where the previous projects were about "calculating or generating a value," this one centers on time control and exception handling.

What I focused on this time:

• Stepping through a process one second at a time with time.sleep()
• A reverse loop with range(n, 0, -1) (the countdown)
• Overwriting the same line in place with \r (carriage return) plus end="" plus flush=True
• Exception design with try / except / finally (catching KeyboardInterrupt and a generic Exception)
• Using finally to gather "the message that must appear on success, interruption, or error alike"
• Mocking (swapping out) time.sleep in tests to raise exceptions on purpose
• Capturing stdout as a string with capsys for verification

As always, I write honestly about where I got stuck, what I thought through, and what I asked AI for.

📝 Where this sits in the series

This is the third article in my Python series. So far the processes always ran to the end, but this time I step into a new theme: how to design and test a process that might stop partway, like a user pressing Ctrl+C mid-run.

My Learning Style (AI Transparency)

💡 Learning companions & how this article is written

I use Claude Pro (design discussions, Q&A, and article drafting) and Cursor Pro (coding support).

Division of roles:

• Tech selection, design, implementation, and code verification → me
• Article structure, outline, draft prose, and translation → in collaboration with Claude
• All content is checked and revised by me before publishing → me

For the code, I set myself these rules: I write the code myself (I never ask AI to write code for me), I use AI for hints, spec clarification, and bug spotting, and I make sure I understand why before moving on. In this article I clearly separate "what I implemented myself" from "what I asked AI for." My line is "the thinking and decisions are mine, the wording is AI-assisted, and I verify the final content myself." This isn't an apology — just stating the facts.

What I Built

A CLI tool where you pick a menu number and count down 60 seconds, 30 seconds, or a custom number of seconds. While counting, the number decreases overwriting the same line.

----------------------------------
Welcome to the countdown timer!
1. Count down 60 seconds
2. Count down 30 seconds
3. Count down custom seconds
4. Exit
----------------------------------
Enter your choice: 3
Enter the number of seconds: 5
1 seconds remaining...Time's up!
Countdown finished.
----------------------------------
Welcome to the countdown timer!
1. Count down 60 seconds
2. Count down 30 seconds
3. Count down custom seconds
4. Exit
----------------------------------
Enter your choice: 4
Exiting the program...

The example only shows 1 seconds remaining..., but that's because 5, 4, 3, 2, 1 are all overwriting the same line (the mechanism is explained later). Press Ctrl+C during the count, and it shows an interruption message and returns to the menu.

📦 Repository: https://github.com/uya0526-design/countdown_timer_py

File Structure and Tech Stack

In the previous project (password generator) I split the logic from the entry point into separate files, so I kept the same approach here. The countdown body goes in timer.py, and the menu and entry point go in main.py.

countdown_timer_py/
├── src/
│   ├── __init__.py
│   ├── main.py          # entry point
│   └── timer.py         # countdown logic
├── tests/
│   ├── __init__.py
│   └── test_timer.py    # unit tests
├── requirements.txt     # dependencies
├── LEARNING_LOG.md      # learning log
└── README.md

Tech stack:

• Python 3.12
• pytest 9.0.3

I split the countdown logic (timer.py) from the menu I/O (main.py) because I wanted to keep the "separation of concerns" I'd learned in earlier projects. In Java terms, it feels close to separating the class that holds the logic from the startup class that holds main.

What I Implemented Myself

timer.py — A reverse loop and time.sleep to step one second at a time

This is the heart of the countdown. I run range backward and wait one second on each pass with time.sleep(1).

import time

def count_down(seconds: int) -> None:
    '''Count down the specified seconds'''
    try:
        for i in range(seconds, 0, -1):
            print(f"\r{i} seconds remaining...", end="", flush=True)
            time.sleep(1)
        print("Time's up!")
    except KeyboardInterrupt:
        print("Countdown interrupted by user.")
    except Exception as e:
        print(f"An error occurred: {e}")
    finally:
        print("Countdown finished.")

Three points here.

1. Looping backward with range(seconds, 0, -1)

Passing -1 as the step in range(start, stop, step) makes the loop count down: seconds, seconds-1, ..., 1 (since stop=0 is excluded, it stops at 1). It's a direct replacement for Java's for (int i = seconds; i > 0; i--), so for someone with a Java background it was actually a familiar way to write it.

2. Waiting one second with time.sleep(1)

time.sleep(seconds) pauses the process for that many seconds. That's what creates the feel of "the number drops once per second." It's the counterpart of Java's Thread.sleep(1000) (in milliseconds), but Python takes seconds, which was a small but notable difference.

3. The loop variable i is used for display

In the previous password generator I just needed "the number of repetitions," so I used for _ in range(...) with _. This time I use i (the remaining seconds) for display, so I give it a real name. Being able to consciously choose between i and _ based on "do I use the loop variable or not?" is continuous growth from last time.

timer.py — Overwriting the same line with \r

When I first wrote this naively, the countdown stacked up vertically.

5 seconds remaining...
4 seconds remaining...
3 seconds remaining...
...

That doesn't feel like a timer. What I used here is \r (carriage return).

print(f"\r{i} seconds remaining...", end="", flush=True)

The role of each argument:

• \r ... returns the cursor to the start of the line, so the next output overwrites the same line
• end="" ... stops the newline print adds by default (a newline would break the overwrite)
• flush=True ... flushes the output buffer immediately so it reaches the screen without waiting

With these three together, 5, 4, 3, 2, 1 rewrite in place on the same line. I also learned by testing that without flush=True, the display sometimes doesn't update while sleep is paused, and it "stutters."

💡 A common terminal-UI technique

This is a standard terminal-UI trick, and apparently it also applies to progress bars and "processing..." spinners. The look of the display is a real part of UX too — that's the mindset I brought to this spot.

timer.py — Designing a "process that may stop partway" with try / except / finally

The part I thought about most this time was exception design. A countdown is a process where "the user may stop it partway with Ctrl+C," so I want to catch that interruption gracefully instead of crashing with an error. So I used a three-layer structure.

    try:
        for i in range(seconds, 0, -1):
            print(f"\r{i} seconds remaining...", end="", flush=True)
            time.sleep(1)
        print("Time's up!")
    except KeyboardInterrupt:
        print("Countdown interrupted by user.")
    except Exception as e:
        print(f"An error occurred: {e}")
    finally:
        print("Countdown finished.")

The roles, organized:

Here my Java experience paid off directly for the first time in a while. The try / catch / finally structure is almost the same as Java, and the point that finally "always runs regardless of whether an exception occurred" matches too. The differences are that Java's catch (Exception e) becomes except Exception as e in Python, and that you can catch Ctrl+C as a KeyboardInterrupt exception. Signal handling felt like extra work in Java, so being able to treat this as an ordinary exception was fresh.

What I focused on in the design was "what to put in finally." Countdown finished. is a message I want shown on every kind of ending, so I put it in finally. Conversely, the "only on success" Time's up! goes at the end of try, and the "only on interruption" message goes in except. The idea of deciding where to place things by working backward from the requirement "when do I want this shown?" clicked for me this time.

main.py — The menu loop and catching ValueError

The entry point main.py runs the menu with while True and guards the custom-seconds input with try / except.

from timer import count_down

def main() -> None:
    '''Main function'''
    while True:
        print("----------------------------------")
        print("Welcome to the countdown timer!")
        print("1. Count down 60 seconds")
        print("2. Count down 30 seconds")
        print("3. Count down custom seconds")
        print("4. Exit")
        print("----------------------------------")
        choice = input("Enter your choice: ")
        if choice == "1":
            count_down(60)
        elif choice == "2":
            count_down(30)
        elif choice == "3":
            try:
                seconds = int(input("Enter the number of seconds: "))
                count_down(seconds)
            except ValueError:
                print("Invalid input. Please enter a valid number of seconds.")
                continue
        elif choice == "4":
            print("Exiting the program...")
            break
        else:
            print("Invalid choice. Please enter a valid choice.")
            continue

Input that int() can't convert raises ValueError (close to Java's NumberFormatException), so I catch it and continue back to the top of the menu. This try / except ValueError then continue pattern shows up again and again across the Python series, and it has become second nature.

tests/test_timer.py — How to test a "waiting" process and exceptions

The hard parts of testing this time were two: (1) if time.sleep really waits, the test is slow, and (2) how do I raise exceptions (Ctrl+C or an error) on purpose? I solved these with unittest.mock.patch and capsys.

import pytest
from unittest.mock import patch

from src.timer import count_down

def test_count_down(capsys):
    '''The countdown will start for the number of seconds entered'''
    assert count_down(1) is None
    assert "1 seconds remaining...Time's up!\nCountdown finished." in capsys.readouterr().out

def test_keyboard_interrupt(capsys):
    '''KeyboardInterrupt: A message will be returned when an exception occurs'''
    with patch('time.sleep', side_effect=KeyboardInterrupt):
        assert count_down(1) is None
        assert "Countdown interrupted by user." in capsys.readouterr().out

def test_exception(capsys):
    '''Exception: A message will be returned when an exception occurs'''
    with patch('time.sleep', side_effect=Exception):
        assert count_down(1) is None
        assert "An error occurred" in capsys.readouterr().out

Three things I worked out.

1. Capturing stdout with capsys

capsys is a fixture pytest provides, and capsys.readouterr().out lets me grab "the string that print produced." A function that returns None (count_down) can't be verified by its return value alone, so I switched to the mindset of checking correctness by looking at the output.

2. Injecting an exception with patch('time.sleep', side_effect=KeyboardInterrupt)

If I swap out time.sleep with patch and set side_effect to an exception, that exception is raised the moment sleep is called. That let me reproduce "the user pressed Ctrl+C" from the test. It feels close to writing when(...).thenThrow(...) with Mockito in Java.

3. The normal-path count_down(1) actually waits one second

Only the normal-path test leaves sleep un-mocked and really waits one second. One second is within tolerance, so I deliberately ran it as-is here.

📝 A spot I got stuck on

I tripped up once on "where to apply the mock" (detailed below in "Where I Got Stuck"). At first I tried to mock the input, but input isn't called inside count_down, so I was applying it to the wrong place.

What I Asked AI For

Note: the idea of overwriting a line with \r, and identifying where to apply patch (next section) were things I thought through and debugged myself.

Where I Got Stuck

1. Mocked it, but no exception fires — the patch target was wrong

Situation: When writing the KeyboardInterrupt test, I first thought "if I swap out the input I can raise the exception," and applied patch('builtins.input', ...). But no exception fired at all, and the test didn't behave as intended.

Root cause: Looking closely, input is never called inside the count_down function. The one using input is main.py, and what actually gets called and waits inside count_down is time.sleep. In other words, "where I wanted to inject the exception" and "where I applied the mock" were out of sync.

Fix: I changed the mock target to time.sleep.

# NG: input is not called inside count_down, so nothing happens when applied here
with patch('builtins.input', side_effect=KeyboardInterrupt):
    ...

# OK: apply it to time.sleep, which is actually called inside count_down
with patch('time.sleep', side_effect=KeyboardInterrupt):
    ...

Takeaway: A mock has no effect unless you apply it where the call actually happens. You decide the target by looking not at "what I want to swap out" but at "what the function under test actually calls." I got stuck on "is the path correct?" with __init__.py import resolution last time, and a mock is the same in that "is it pointing at the right target?" is the crux.

2. "An error occurred: Exception" makes the assertion fail — the empty-message trap

Situation: In the generic Exception test, I first wrote the assertion expecting the output "An error occurred: Exception", and it failed.

Root cause: The production code embeds the exception with print(f"An error occurred: {e}"). Here side_effect=Exception throws an Exception() with no arguments, so the str(e) going into {e} becomes an empty string. The actual output is therefore "An error occurred: " (nothing after the colon), which doesn't match "An error occurred: Exception".

Fix: I relaxed the assertion to only "does it contain the first part?"

# NG: expected the exception message (after the colon) to match too
assert "An error occurred: Exception" in capsys.readouterr().out

# OK: verify only the first part that always appears
assert "An error occurred" in capsys.readouterr().out

Takeaway: I only noticed that str(Exception()) becomes an empty string by reading the error log. The lesson is that narrowing a test assertion to "the minimal fact that always holds" makes it harder to break and clearer in intent. Following last time's "crush probabilistic failures with a large enough number of trials," my sense for "how to keep tests stable" is slowly growing.

What I Learned

Python syntax and standard library

Testing knowledge

Design and debugging thinking

• What to put in finally is decided by working backward from "what message do I want on every ending?"
• The look of the display (overwriting with \r) is something to treat as part of UX design.
• When an error appears, read the difference between "the actual output" and "the expected output." The pattern "if the patch target is wrong, no exception fires" has become a familiar way to isolate causes.

Reflection

As before, I built this by writing the code myself and having AI review it, and I completed implementation, debugging, and testing on my own. As my third Python project, three things stood out.

I stepped into designing a "process that stops partway" for the first time: So far the processes always ran to completion, but this time I designed a way to gracefully catch an interruption via Ctrl+C — an ending that is neither the normal path nor an error — with try / except / finally. It was a nice bonus that my knowledge of Java's finally carried straight over.

A lesson from the mock target: I learned the mock principle "decide the target by what the target actually calls, not by what you want to swap out" by actually getting stuck. As with last time's import resolution, I re-confirmed from a different angle how important it is to "point at the right path / target."

A small win in display control: The moment the number rewrote in place with \r was a quiet but real sense of "now it feels like a timer." Going one step beyond "it just works" to caring about how it looks feels continuous with my front-end learning too.

Wrapping Up

This was my record of building a countdown timer CLI in Python, centered on time, finally, and mock — my third article in the Python series.

Continuous progress from last time:

1. Learned to write a "process that advances over time" with time.sleep and range(n, 0, -1)
2. Picked up display control that overwrites the same line with \r plus end="" plus flush=True
3. Cleanly designed a "process that stops partway" with try / except / finally (Java knowledge paid off)
4. Wrote tests that swap out time.sleep with patch to raise exceptions on purpose
5. Learned the principle "apply a mock where the call happens" from actually getting stuck

Next, I'll finally move into persistence to a file (a diary app). I'll graduate from the "data disappears when you exit" simplification I've kept up to now in the next stage.

The full learning log is in the repository:

• countdown_timer_py / LEARNING_LOG.md

This article is part of my public learning journey using AI tools (Claude Pro / Cursor Pro). The thinking and all code are mine; I collaborate with AI on the writing (structure, drafting, translation) and verify every line before publishing.