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:

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.