Build a Command-Line To-Do App With Python and Typer (original) (raw)

Watch Now This tutorial has a related video course created by the Real Python team. Watch it together with the written tutorial to deepen your understanding: Building a Python Command-Line To-Do App With Typer

Building an application to manage your to-do list can be an interesting project when you’re learning a new programming language or trying to take your skills to the next level. In this tutorial, you’ll build a functional to-do application for the command line using Python and Typer, which is a relatively young library for creating powerful command-line interface (CLI) applications in almost no time.

With a project like this, you’ll apply a wide set of core programming skills while building a real-world application with real features and requirements.

In this tutorial, you’ll learn how to:

• Build a functional to-do application with a Typer CLI in Python
• Use Typer to add commands, arguments, and options to your to-do app
• Test your Python to-do application with Typer’s CliRunner and pytest

Additionally, you’ll practice your skills related to processing JSON files by using Python’s json module and managing configuration files with Python’s configparser module. With this knowledge, you’ll be ready to start creating CLI applications right away.

You can download the entire code and all the additional resources for this to-do CLI application by clicking the link below and going to the source_code_final/ directory:

Demo

In this step-by-step project, you’ll build a command-line interface (CLI) application to manage a to-do list. Your application will provide a CLI based on Typer, a modern and versatile library for creating CLI applications.

Before you get started, check out this demo of how your to-do application will look and work once you get to the end of this tutorial. The first part of the demo shows how to get help on working with the app. It also shows how to initialize and configure the app. The rest of the video demonstrates how to interact with the essential features, such as adding, removing, and listing to-dos:

Nice! The application has a user-friendly CLI that allows you to set up the to-do database. Once there, you can add, remove, and complete to-dos using appropriate commands, arguments, and options. If you ever get stuck, then you can ask for help using the --help option with proper arguments.

Do you feel like kicking off this to-do app project? Cool! In the next section, you’ll plan out how to structure the layout of the project and what tools you’ll use to build it.

Project Overview

When you want to start a new application, you typically start by thinking about how you want the app to work. In this tutorial, you’ll build a to-do app for the command line. You’ll call that application rptodo.

You want your application to have a user-friendly command-line interface that allows your users to interact with the app and manage their to-do lists.

To start off, you want your CLI to provide the following global options:

• -v or --version shows the current version and exits the application.
• --help shows the global help message for the entire application.

You’ll see these same options in many other CLI applications out there. It’s a nice idea to provide them because most users who work with the command line expect to find them in every app.

Regarding managing a to-do list, your application will provide commands to initialize the app, add and remove to-dos, and manage the to-do completion status:

These commands provide all the functionality you need to turn your to-do application into a minimum viable product (MVP) so that you can publish it to PyPI or the platform of your choice and start getting feedback from your users.

To provide all these features in your to-do application, you’ll need to complete a few tasks:

1. Build a command-line interface capable of taking and processing commands, options, and arguments
2. Select an appropriate data type to represent your to-dos
3. Implement a way to persistently store your to-do list
4. Define a way to connect that user interface with the to-do data

These tasks relate well to what is known as the Model-View-Controller design, which is an architectural pattern. In this pattern, the model takes care of the data, the view deals with the user interface, and the controller connects both ends to make the application work.

The main reason for using this pattern in your applications and projects is to provide separation of concerns (SoC), making different parts of your code deal with specific concepts independently.

The next decision you need to make is about the tools and libraries you’ll use to tackle each of the tasks you defined further up. In other words, you need to decide your software stack. In this tutorial, you’ll use the following stack:

• Typer to build the to-do application’s CLI
• Named tuples and dictionaries to handle the to-do data
• Python’s json module to manage persistent data storage

You’ll also use the configparser module from the Python standard library to handle the application’s initial settings in a configuration file. Within the configuration file, you’ll store the path to the to-do database in your file system. Finally, you’ll use pytest as a tool for testing your CLI application.

Prerequisites

To complete this tutorial and get the most out of it, you should be comfortable with the following topics:

• The Model-View-Controller pattern
• Command-line interfaces (CLI)
• Python type hints, also known as type annotations
• Unit tests with pytest
• Object-oriented programming in Python
• Configuration files with configparser
• JSON files with Python’s json
• File system path manipulation with pathlib

That’s it! If you’re ready to get your hands dirty and start creating your to-do app, then you can begin with setting up your working environment and project layout.

Step 1: Set Up the To-Do Project

To start coding your to-do application, you need to set up a working Python environment with all the tools, libraries, and dependencies you’ll use in the process. Then you need to give the project a coherent Python application layout. That’s what you’ll do in the following subsections.

To download all the files and the project structure you’ll be creating in this section, click the link below and go to the source_code_step_1/ directory:

Set Up the Working Environment

In this section, you’ll create a Python virtual environment to work on your to-do project. Using a virtual environment for each independent project is a best practice in Python programming. It allows you to isolate your project’s dependencies without cluttering your system Python installation or breaking other projects that use different versions of the same tools and libraries.

To create a Python virtual environment, move to your favorite working directory and create a folder called rptodo_project/. Then fire up a terminal or command line and run the following commands:

Here, you first enter the rptodo_project/ directory using cd. This directory will be your project’s root directory. Then you create a Python virtual environment using venv from the standard library. The argument to venv is the path to the directory hosting your virtual environment. A common practice is to call that directory venv, .venv, or env, depending on your preferences.

The third command activates the virtual environment you just created. You know that the environment is active because your prompt changes to something like (venv) $.

Now that you have a working virtual environment, you need to install Typer to create the CLI application and pytest to test your application’s code. To install Typer with all its current optional dependencies, run the following command:

This command installs Typer and all its recommended dependencies, such as Colorama, which ensures that colors work correctly on your command line window.

To install pytest, which you’ll use later to test your to-do application, run the following command:

With this last command, you successfully installed all the tools you need to start developing your to-do application. The rest of the libraries and tools you’ll use are part of the Python standard library, so you don’t have to install anything to use them.

Define the Project Layout

The last step you’ll run to finish setting up your to-do app project is to create the packages, modules, and files that will frame the application layout. The app’s core package will live in the rptodo/ directory inside rptodo_project/.

Here’s a description of the package’s contents:

You’ll also need a tests/ directory containing a __init__.py file to turn the directory into a package and a test_rptodo.py file to hold unit tests for the application.

Go ahead and create the project’s layout with the following structure:

rptodo_project/ │ ├── rptodo/ │ ├── __init__.py │ ├── __main__.py │ ├── cli.py │ ├── config.py │ ├── database.py │ └── rptodo.py │ ├── tests/ │ ├── __init__.py │ └── test_rptodo.py │ ├── README.md └── requirements.txt

The README.md file will provide the project’s description and instructions for installing and running the application. Adding a descriptive and detailed README.md file to your project is a best practice in programming, especially if you plan to release the project as open source.

The requirements.txt file will provide the list of dependencies for your to-do application. Go ahead and fill it with the following contents:

Now your users can automatically install the listed dependencies by running the following command:

Providing a requirements.txt like this ensures that your user will install the exact versions of dependencies you used to build the project, avoiding unexpected issues and behaviors.

Except for requirements.txt, all your project’s files should be empty at this point. You’ll fill each file with the necessary content moving forward through this tutorial. In the following section, you’ll code the application’s CLI with Python and Typer.

Step 2: Set Up the To-Do CLI App With Python and Typer

At this point, you should have a complete project layout for your to-do application. You should also have a working Python virtual environment with all the required tools and libraries. At the end of this step, you’ll have a functional Typer CLI application. Then you’ll be able to build on top of its minimal functionality.

You can download the code, unit tests, and resources you’ll add in this section by clicking the link below and going to the source_code_step_2/ directory:

Fire up your code editor and open the __init__.py file from the rptodo/ directory. Then add the following code to it:

Here, you start by defining two module-level names to hold the application’s name and version. Then you define a series of return and error codes and assign integer numbers to them using range(). ERROR is a dictionary that maps error codes to human-readable error messages. You’ll use these messages to tell the user what’s happening with the application.

With this code in place, you’re ready to create the skeleton of your Typer CLI application. That’s what you’ll do in the following section.

Create the Typer CLI Application

In this section, you’ll create a minimal Typer CLI application with support for --help, -v, and --version options. To do so, you’ll use an explicit Typer application. This type of application is suitable for large projects that include multiple commands with several options and arguments.

Go ahead and open rptodo/cli.py in your text editor and type in the following code:

Typer uses Python type hints extensively, so in this tutorial, you’ll use them as well. That’s why you start by importing Optional from typing. Next, you import typer. Finally, you import __app_name__ and __version__ from your rptodo package.

Here’s how the rest of the code works:

• Line 10 creates an explicit Typer application, app.
• Lines 12 to 15 define _version_callback(). This function takes a Boolean argument called value. If value is True, then the function prints the application’s name and version using echo(). After that, it raises a typer.Exit exception to exit the application cleanly.
• Lines 17 and 18 define main() as a Typer callback using the @app.callback() decorator.
• Line 19 defines version, which is of type Optional[bool]. This means it can be either of bool or None type. The version argument defaults to a typer.Option object, which allows you to create command-line options in Typer.
• Line 20 passes None as the first argument to the initializer of Option. This argument is required and supplies the option’s default value.
• Lines 21 and 22 set the command-line names for the version option: -v and --version.
• Line 23 provides a help message for the version option.
• Line 24 attaches a callback function, _version_callback(), to the version option, which means that running the option automatically calls the function.
• Line 25 sets the is_eager argument to True. This argument tells Typer that the version command-line option has precedence over other commands in the current application.

With this code in place, you’re ready to create the application’s entry-point script. That’s what you’ll do in the following section.

Create an Entry-Point Script

You’re almost ready to run your to-do application for the first time. Before doing that, you should create an entry-point script for the app. You can create this script in a few different ways. In this tutorial, you’ll do it using a __main__.py module inside the rptodo package. Including a __main__.py module in a Python package enables you to run the package as an executable program using the command python -m rptodo.

Go back to your code editor and open __main__.py from the rptodo/ directory. Then add the following code:

In __main__.py, you first import cli and __app_name__ from rptodo. Then you define main(). In this function, you call the Typer app with cli.app(), passing the application’s name to the prog_name argument. Providing a value to prog_name ensures that your users get the correct app name when running the --help option on their command line.

With this final addition, you’re ready to run your to-do application for the first time. Move to your terminal window and execute the following commands:

The first command runs the -v option, which displays the app’s version. The second command runs the --help option to show a user-friendly help message for the entire application. Typer automatically generates and displays this help message for you.

Set Up Initial CLI Tests With pytest

The final action you’ll run in this section is to set up an initial test suite for your to-do application. To this end, you’ve created the tests package with a module called test_rptodo.py. As you learned earlier, you’ll use pytest for writing and running your unit tests.

Testing a Typer application is straightforward because the library integrates pretty well with pytest. You can use a Typer class called CliRunner to test the application’s CLI. CliRunner allows you to create a runner that you can use to test how your application’s CLI responds to real-world commands.

Go back to your code editor and open test_rptodo.py from the tests/ directory. Type in the following code:

Here’s what this code does:

• Line 3 imports CliRunner from typer.testing.
• Line 5 imports a few required objects from your rptodo package.
• Line 7 creates a CLI runner by instantiating CliRunner.
• Line 9 defines your first unit test for testing the application’s version.
• Line 10 calls .invoke() on runner to run the application with the --version option. You store the result of this call in result.
• Line 11 asserts that the application’s exit code (result.exit_code) is equal to 0 to check that the application ran successfully.
• Line 12 asserts that the application’s version is present in the standard output, which is available through result.stdout.

Typer’s CliRunner is a subclass of Click’s CliRunner. Therefore, its .invoke() method returns a Result object, which holds the result of running the CLI application with the target arguments and options. Result objects provide several useful attributes and properties, including the application’s exit code and standard output. Take a look at the class documentation for more details.

Now that you’ve set up the first unit test for your Typer CLI application, you can run the test with pytest. Go back to your command line and execute python -m pytest tests/ from your project’s root directory:

That’s it! You’ve successfully run your test suite for the first time! Yes, you only have one test so far. However, you’ll be adding more of them in upcoming sections. You can also add your own test if you want to challenge your testing skills.

With the skeleton to-do application in place, now you can think about setting up the to-do database to get it ready for use. That’s what you’ll do in the following section.

Step 3: Prepare the To-Do Database for Use

Up to this point, you’ve put together a CLI for your to-do application, created an entry-point script, and run the application for the first time. You’ve also set up and run a minimal test suite for the app. The next step is to define how your application will initialize and connect to the to-do database.

You’ll use a JSON file to store the data about your to-dos. JSON is a lightweight data-interchange format that’s human-readable and writable. Python’s standard library includes json, which is a module that provides support for the JSON file format out of the box. That’s what you’ll use to manage your to-do database.

You can download the entire code for this section by clicking the link below and going to the source_code_step_3/ directory:

At the end of this section, you’ll have written the code for creating, connecting, and initializing your to-do database so that it’s ready for use. The first step, however, is to define how your application will find the to-do database in your file system.

Set Up the Application’s Configurations

You can use different techniques to define how an application connects and opens a file on your file system. You can provide the file path dynamically, create an environment variable to hold the file path, create a configuration file in which you store the file path, and so on.

In this tutorial, you’ll provide your to-do app with a configuration file in your home directory to store the path to the database. To that end, you’ll use pathlib to work with file system paths and configparser to handle configuration files. Both packages are available for you in the Python standard library.

Now go back to your code editor and open config.py from rptodo/. Type in the following code:

Here’s a breakdown of what this code does:

• Line 4 imports configparser. This module provides the ConfigParser class, which allows you to handle config files with a structure similar to INI files.
• Line 5 imports Path from pathlib. This class provides a cross-platform way to handle system paths.
• Line 7 imports typer.
• Lines 9 to 11 import a bunch of required objects from rptodo.
• Line 13 creates CONFIG_DIR_PATH to hold the path to the app’s directory. To get this path, you call get_app_dir() with the application’s name as an argument. This function returns a string representing the path to a directory where you can store configurations.
• Line 14 defines CONFIG_FILE_PATH to hold the path to the configuration file itself.
• Line 16 defines init_app(). This function initializes the application’s configuration file and database.
• Line 18 calls the _init_config_file() helper function, which you define in lines 26 to 35. Calling this function creates the configuration directory using Path.mkdir(). It also creates the configuration file using Path.touch(). Finally, _init_config_file() returns the proper error codes if something wrong happens during the creation of the directory and file. It returns SUCCESS if everything goes okay.
• Line 19 checks if an error occurs during the creation of the directory and configuration file, and line 20 returns the error code accordingly.
• Line 21 calls the _create_database() helper function, which creates the to-do database. This function returns the appropriate error codes if something happens while creating the database. It returns SUCCESS if the process succeeds.
• Line 22 checks if an error occurs during the creation of the database. If so, then line 23 returns the corresponding error code.
• Line 24 returns SUCCESS if everything runs okay.

With this code, you’ve finished setting up the application’s configuration file to store the path to the to-do database. You’ve also added code to create the to-do database as a JSON file. Now you can write code for initializing the database and getting it ready for use. That’s what you’ll do in the following section.

Get the To-Do Database Ready for Use

To get the to-do database ready for use, you need to perform two actions. First, you need a way to retrieve the database file path from the application’s configuration file. Second, you need to initialize the database to hold JSON content.

Open database.py from rptodo/ in your code editor and write the following code:

In this file, lines 4 to 7 perform the required imports. Here’s what the rest of the code does:

• Lines 9 to 11 define DEFAULT_DB_FILE_PATH to hold the default database file path. The application will use this path if the user doesn’t provide a custom one.
• Lines 13 to 17 define get_database_path(). This function takes the path to the app’s config file as an argument, reads the input file using ConfigParser.read(), and returns a Path object representing the path to the to-do database on your file system. The ConfigParser instance stores the data in a dictionary. The "General" key represents the file section that stores the required information. The "database" key retrieves the database path.
• Lines 19 to 25 define init_database(). This function takes a database path and writes a string representing an empty list. You call .write_text() on the database path, and the list initializes the JSON database with an empty to-do list. If the process runs successfully, then init_database() returns SUCCESS. Otherwise, it returns the appropriate error code.

Cool! Now you have a way to retrieve the database file path from the application’s configuration file. You also have a way to initialize the database with an empty to-do list in JSON format. It’s time to implement the init command with Typer so that your users can initialize their to-do database from the CLI.

Implement the init CLI Command

The final step to put together all the code you’ve written in this section is to add the init command to your application’s CLI. This command will take an optional database file path. It’ll then create the application’s configuration file and to-do database.

Go ahead and add init() to your cli.py file:

Here’s how this new code works:

• Lines 4 and 9 update the required imports.
• Lines 13 and 14 define init() as a Typer command using the @app.command() decorator.
• Lines 15 to 20 define a Typer Option instance and assign it as a default value to db_path. To provide a value for this option, your users need to use --db-path or -db followed by a database path. The prompt argument displays a prompt asking for a database location. It also allows you to accept the default path by pressing Enter.
• Line 23 calls init_app() to create the application’s configuration file and to-do database.
• Lines 24 to 29 check if the call to init_app() returns an error. If so, lines 25 to 28 print an error message. Line 29 exits the app with a typer.Exit exception and an exit code of 1 to signal that the application terminated with an error.
• Line 30 calls init_database() to initialize the database with an empty to-do list.
• Lines 31 to 38 check if the call to init_database() returns an error. If so, then lines 32 to 35 display an error message, and line 36 exits the application. Otherwise, line 38 prints a success message in green text.

To print the messages in this code, you use typer.secho(). This function takes a foreground argument, fg, that allows you to use different colors when printing text to the screen. Typer provides several built-in colors in typer.colors. There you’ll find RED, BLUE, GREEN, and more. You can use those colors with secho() as you did here.

Nice! With all this code in place, you can now give the init command a try. Go back to your terminal and run the following:

This command presents you with a prompt for entering a database location. You can press Enter to accept the default path in square brackets, or you can type in a custom path and then press Enter. The application creates the to-do database and tells you where it’ll reside from this point on.

Alternatively, you can provide a custom database path directly by using init with the -db or --db-path options followed by the desired path. In all cases, your custom path should include the database file name.

Once you’ve run the above command, take a look at your home directory. You’ll have a JSON file named after the filename you used with init. You’ll also have a rptodo/ directory containing a config.ini file somewhere in your home folder. The specific path to this file will depend on your current operating system. On Ubuntu, for example, the file will be at /home/user/.config/rptodo/.

Step 4: Set Up the To-Do App Back End

Up to this point, you’ve made a way to create, initialize, and connect to the to-do database. Now you can start thinking of your data model. In other words, you need to think about how to represent and store data about your to-dos. You also need to define how your application will handle communication between the CLI and database.

You can download the code and all the additional resources you’ll use in this section by clicking the link below and going to the source_code_step_4/ directory:

Define a Single To-Do

First, think about the data you need for defining a single to-do. In this project, a to-do will consist of the following pieces of information:

• Description: How do you describe this to-do?
• Priority: What priority does this to-do have over the rest of your to-dos?
• Done: Is this to-do done?

To store this information, you can use a regular Python dictionary:

The "Description" key stores a string describing the current to-do. The "Priority" key can take three possible values: 1 for high, 2 for medium, and 3 for low priority. The "Done" key holds True when you’ve completed the to-do and False otherwise.

Communicate With the CLI

To communicate with the CLI, you’ll use two pieces of data holding the required information:

1. todo: The dictionary holding the information for the current to-do
2. error: The return or error code confirming if the current operation was successful or not

To store this data, you’ll use a named tuple with appropriately named fields. Open up the rptodo.py module from rptodo to create the required named tuple:

In rptodo.py, you first import some required objects from typing. On line 6, you create a subclass of typing.NamedTuple called CurrentTodo with two fields todo and error.

Subclassing NamedTuple allows you to create named tuples with type hints for their named fields. For example, the todo field above holds a dictionary with keys of type str and values of type Any. The error field holds an int value.

Communicate With the Database

Now you need another data container that allows you to send data to and retrieve data from the to-do database. In this case, you’ll use another named tuple with the following fields:

1. todo_list: The to-do list you’ll write to and read from the database
2. error: An integer number representing a return code related to the current database operation

Finally, you’ll create a class called DatabaseHandler to read and write data to the to-do database. Go ahead and open database.py. Once you’re there, type in the following code:

Here’s what this code does:

• Lines 4, 6, and 8 add some required imports.
• Lines 12 to 14 define DBResponse as a NamedTuple subclass. The todo_list field is a list of dictionaries representing individual to-dos, while the error field holds an integer return code.
• Line 16 defines DatabaseHandler, which allows you to read and write data to the to-do database using the json module from the standard library.
• Lines 17 and 18 define the class initializer, which takes a single argument representing the path to the database on your file system.
• Line 20 defines .read_todos(). This method reads the to-do list from the database and deserializes it.
• Line 21 starts a try … except statement to catch any errors that occur while you’re opening the database. If an error occurs, then line 28 returns a DBResponse instance with an empty to-do list and a DB_READ_ERROR.
• Line 22 opens the database for reading using a with statement.
• Line 23 starts another try … except statement to catch any errors that occur while you’re loading and deserializing the JSON content from the to-do database.
• Line 24 returns a DBResponse instance holding the result of calling json.load() with the to-do database object as an argument. This result consists of a list of dictionaries. Every dictionary represents a to-do. The error field of DBResponse holds SUCCESS to signal that the operation was successful.
• Line 25 catches any JSONDecodeError while loading the JSON content from the database, and line 26 returns with an empty list and a JSON_ERROR.
• Line 27 catches any file IO problems while loading the JSON file, and line 28 returns a DBResponse instance with an empty to-do list and a DB_READ_ERROR.
• Line 30 defines .write_todos(), which takes a list of to-do dictionaries and writes it to the database.
• Line 31 starts a try … except statement to catch any errors that occur while you’re opening the database. If an error occurs, then line 36 returns a DBResponse instance with the original to-do list and a DB_READ_ERROR.
• Line 32 uses a with statement to open the database for writing.
• Line 33 dumps the to-do list as a JSON payload into the database.
• Line 34 returns a DBResponse instance holding the to-do list and the SUCCESS code.

Wow! That was a lot! Now that you finished coding DatabaseHandler and setting up the data exchange mechanism, you can think about how to connect them to the application’s CLI.

Write the Controller Class, Todoer

To connect the DatabaseHandler logic with your application’s CLI, you’ll write a class called Todoer. This class will work similarly to a controller in the Model-View-Controller pattern.

Now go back to rptodo.py and add the following code:

This code includes some imports and the definition of Todoer. This class uses composition, so it has a DatabaseHandler component to facilitate direct communication with the to-do database. You’ll add more code to this class in upcoming sections.

In this section, you’ve put together a lot of setups that shape how your to-do application’s back end will work. You’ve decided what data structures to use for storing the to-do data. You’ve also defined what kind of database you’ll use to save the to-do information and how to operate on it.

With all those setups in place, you’re now ready to start providing value to your users by allowing them to populate their to-do lists. You’ll also implement a way to display the to-dos on the screen.

Step 5: Code the Adding and Listing To-Dos Functionalities

In this section, you’ll code one of the main features of your to-do application. You’ll provide your users with a command to add new to-dos to their current list. You’ll also allow the users to list their to-dos on the screen in a tabular format.

Before working on these features, you’ll set up a minimal test suite for your code. Writing a test suite before writing the code will help you understand what test-driven development (TDD) is about.

To download the code, unit tests, and all the additional resources you’ll add in this section, just click the link below and go to the source_code_step_5/ directory:

Define Unit Tests for Todoer.add()

In this section, you’ll use pytest to write and run a minimal test suite for Todoer.add(). This method will take care of adding new to-dos to the database. With the test suite in place, you’ll write the required code to pass the tests, which is a fundamental idea behind TDD.

Before writing tests for .add(), think of what this method needs to do:

1. Get a to-do description and priority
2. Create a dictionary to hold the to-do information
3. Read the to-do list from the database
4. Append the new to-do to the current to-do list
5. Write the updated to-do list back to the database
6. Return the newly added to-do along with a return code back to the caller

A common practice in code testing is to start with the main functionality of a given method or function. You’ll start by creating test cases to check if .add() properly adds new to-dos to the database.

To test .add(), you must create a Todoer instance with a proper JSON file as the target database. To provide that file, you’ll use a pytest fixture.

Go back to your code editor and open test_rptodo.py from the tests/ directory. Add the following code to it:

Here, you first update your imports to complete some requirements. The fixture, mock_json_file(), creates and returns a temporary JSON file, db_file, with a single-item to-do list in it. In this fixture, you use tmp_path, which is a pathlib.Path object that pytest uses to provide a temporary directory for testing purposes.

You already have a temporary to-do database to use. Now you need some data to create your test cases:

These two dictionaries provide data to test Todoer.add(). The first two keys represent the data you’ll use as arguments to .add(), while the third key holds the expected return value of the method.

Now it’s time to write your first test function for .add(). With pytest, you can use parametrization to provide multiple sets of arguments and expected results to a single test function. This is a pretty neat feature. It makes a single test function behave like several test functions that run different test cases.

Here’s how you can create your test function using parametrization in pytest:

The @pytest.mark.parametrize() decorator marks test_add() for parametrization. When pytest runs this test, it calls test_add() two times. Each call uses one of the parameter sets from lines 7 to 11 and lines 12 to 16.

The string on line 5 holds descriptive names for the two required parameters and also a descriptive return value name. Note that test_add() has those same parameters. Additionally, the first parameter of test_add() has the same name as the fixture you just defined.

Inside test_add(), the code does the following actions:

• Line 20 creates an instance of Todoer with mock_json_file as an argument.
• Line 21 asserts that a call to .add() using description and priority as arguments should return expected.
• Line 22 reads the to-do list from the temporary database and stores it in read.
• Line 23 asserts that the length of the to-do list is 2. Why 2? Because mock_json_file() returns a list with one to-do, and now you’re adding a second one.

Cool! You have a test that covers the main functionality of .add(). Now it’s time to run your test suite again. Go back to your command line and run python -m pytest tests/. You’ll get an output similar to the following:

The F letters in the highlighted line mean that two of your test cases have failed. Having failing tests is the first step for TDD. The second step is to write code for passing those tests. That’s what you’re going to do next.

Implement the add CLI Command

In this section, you’ll code .add() in the Todoer class. You’ll also code the add command in your Typer CLI. With these two pieces of code in place, your users will be able to add new items to their to-dos lists.

Every time the to-do application runs, it needs to access the Todoer class and connect the CLI with the database. To satisfy this requirement, you’ll implement a function called get_todoer().

Go back to your code editor and open cli.py. Type in the following code:

After updating the imports, you define get_todoer() on line 18. Line 19 defines a conditional that checks if the application’s configuration file exists. To do so, it uses Path.exists().

If the configuration file exists, then line 20 gets the path to the database from it. The else clause runs if the file doesn’t exist. This clause prints an error message to the screen and exits the application with an exit code of 1 to signal an error.

Line 27 checks if the path to the database exists. If so, then line 28 creates an instance of Todoer with the path as an argument. Otherwise, the else clause that starts on line 29 prints an error message and exits the application.

Now that you have an instance of Todoer with a valid database path, you can write .add(). Go back to the rptodo.py module and update Todoer:

Here’s how .add() works line by line:

• Line 14 defines .add(), which takes description and priority as arguments. The description is a list of strings. Typer builds this list from the words you enter at the command line to describe the current to-do. In the case of priority, it’s an integer value representing the to-do’s priority. The default is 2, indicating a medium priority.
• Line 16 concatenates the description components into a single string using .join().
• Lines 17 and 18 add a period (".") to the end of the description if the user doesn’t add it.
• Lines 19 to 23 build a new to-do from the user’s input.
• Line 24 reads the to-do list from the database by calling .read_todos() on the database handler.
• Line 25 checks if .read_todos() returned a DB_READ_ERROR. If so, then line 26 returns a named tuple, CurrentTodo, containing the current to-do and the error code.
• Line 27 appends the new to-do to the list.
• Line 28 writes the updated to-do list back to the database by calling .write_todos() on the database handler.
• Line 29 returns an instance of CurrentTodo with the current to-do and an appropriate return code.

Now you can run your test suite again to check if .add() works correctly. Go ahead and run python -m pytest tests/. You’ll get an output similar to the following:

The three green dots mean that you have three passing tests. If you downloaded the code from the project’s repo on GitHub, then you get an output with a few more successful tests.

Once you’ve finished writing .add(), you can head to cli.py and write the add command for your application’s CLI:

Here’s a breakdown of what the add command does:

• Lines 7 and 8 define add() as a Typer command using the @app.command() Python decorator.
• Line 9 defines description as an argument to add(). This argument holds a list of strings representing a to-do description. To build the argument, you use typer.Argument. When you pass an ellipsis (...) as the first argument to the constructor of Argument, you’re telling Typer that description is required. The fact that this argument is required means that the user must provide a to-do description at the command line.
• Line 10 defines priority as a Typer option with a default value of 2. The option names are --priority and -p. As you decided earlier, priority only accepts three possible values: 1, 2, or 3. To guarantee this condition, you set min to 1 and max to 3. This way, Typer automatically validates the user’s input and only accepts numbers within the specified interval.
• Line 13 gets a Todoer instance to use.
• Line 14 calls .add() on todoer and unpacks the result into todo and error.
• Lines 15 to 25 define a conditional statement that prints an error message and exits the application if an error occurs while adding the new to-do to the database. If no error happens, then the else clause on line 20 displays a success message on the screen.

Now you can go back to your terminal and give your add command a try:

In the first example, you execute the add command with the description "Get some milk" and a priority of 1. To set the priority, you use the -p option. Once you press Enter, the application adds the to-do and informs you about the successful addition. The second example works pretty similarly. This time you use --priority to set the to-do priority to 3.

In the third example, you provide a to-do description without supplying a priority. In this situation, the app uses the default priority value, which is 2.

In the fourth example, you try to add a new to-do with a priority of 5. Since this priority value is out of the allowed range, Typer displays a usage message along with an error message. Note that Typer automatically displays these messages for you. You don’t need to add extra code for this to happen.

Great! Your to-do application already has some cool functionality. Now you need a way to list all your to-dos to get an idea of how much work you have on your plate. In the following section, you’ll implement the list command to help you out with this task.

Implement the list Command

In this section, you’ll add the list command to your application’s CLI. This command will allow your users to list all their current to-dos. Before adding any code to your CLI, you need a way to retrieve the entire to-do list from the database. To accomplish this task, you’ll add .get_todo_list() to the Todoer class.

Open up rptodo.py in your code editor or IDE and add the following code:

Inside .get_todo_list(), you first get the entire to-do list from the database by calling .read_todos() on the database handler. The call to .read_todos() returns a named tuple, DBResponse, containing the to-do list and a return code. However, you just need the to-do list, so .get_todo_list() returns the .todo_list field only.

With .get_todo_list() in place, you can now implement the list command in the application’s CLI. Go ahead and add list_all() to cli.py:

Here’s how list_all() works:

• Lines 8 and 9 define list_all() as a Typer command using the @app.command() decorator. The name argument to this decorator sets a custom name for the command, which is list here. Note that list_all() doesn’t take any argument or option. It just lists the to-dos when the user runs list from the command line.
• Line 11 gets the Todoer instance that you’ll use.
• Line 12 gets the to-do list from the database by calling .get_todo_list() on todoer.
• Lines 13 to 17 define a conditional statement to check if there’s at least one to-do in the list. If not, then the if code block prints an error message to the screen and exits the application.
• Line 18 prints a top-level header to present the to-do list. In this case, secho() takes an additional Boolean argument called bold, which enables you to display text in a bolded font format.
• Lines 19 to 27 define and print the required columns to display the to-do list in a tabular format.
• Lines 28 to 36 run a for loop to print every single to-do on its own row with appropriate padding and separators.
• Line 37 prints a line of dashes with a final line feed character (\n) to visually separate the to-do list from the next command-line prompt.

If you run the application with the list command, then you get the following output:

This output shows all the current to-dos in a nicely formatted table. This way, your user can track the state of their list of tasks. Note that the output should display in blue font on your terminal window.

Step 6: Code the To-Do Completion Functionality

The next feature you’ll add to your to-do application is a Typer command that allows your users to set a given to-do as complete. This way, your users can track their progress and know how much work is left.

Again, you can download the code and all the resources for this section, including additional unit tests, by clicking the link below and going to the source_code_step_6/ directory:

As usual, you’ll start by coding the required functionality back in Todoer. In this case, you need a method that takes a to-do ID and marks the corresponding to-do as done. Go back to rptodo.py in your code editor and add the following code:

Your new .set_done() method does the required job. Here’s how:

• Line 10 defines .set_done(). The method takes an argument called todo_id, which holds an integer representing the ID of the to-do you want to mark as done. The to-do ID is the number associated with a given to-do when you list your to-dos using the list command. Since you’re using a Python list to store the to-dos, you can turn this ID into a zero-based index and use it to retrieve the required to-do from the list.
• Line 12 reads all the to-dos by calling .read_todos() on the database handler.
• Line 13 checks if any error occurs during the reading. If so, then line 14 returns a named tuple, CurrentTodo, with an empty to-do and the error.
• Line 15 starts a try … except statement to catch invalid to-do IDs that translate to invalid indices in the underlying to-do list. If an IndexError occurs, then line 18 returns a CurrentTodo instance with an empty to-do and the corresponding error code.
• Line 19 assigns True to the "Done" key in the target to-do dictionary. This way, you’re setting the to-do as done.
• Line 20 writes the update back to the database by calling .write_todos() on the database handler.
• Line 21 returns a CurrentTodo instance with the target to-do and a return code indicating how the operation went.

With .set_done() in place, you can move to cli.py and write the complete command. Here’s the required code:

Take a look at how this code works line by line:

• Lines 8 and 9 define set_done() as a Typer command with the usual @app.command() decorator. In this case, you use complete for the command name. The set_done() function takes an argument called todo_id, which defaults to an instance of typer.Argument. This instance will work as a required command-line argument.
• Line 11 gets the usual Todoer instance.
• Line 12 sets the to-do with the specific todo_id as done by calling .set_done() on todoer.
• Line 13 checks if any error occurs during the process. If so, then lines 14 to 18 print an appropriate error message and exit the application with an exit code of 1. If no error occurs, then lines 20 to 23 print a success message in green font.

That’s it! Now you can give your new complete command a try. Back in your terminal window, run the following commands:

First, you list all your to-dos to visualize the ID that corresponds to each of them. Then you use complete to set the to-do with an ID of 1 as done. When you list the to-dos again, you see that the first to-do is now marked as True in the Done column.

An important detail to note about the complete command and the underlying Todoer.set_done() method is that the to-do ID is not a fixed value. If you remove one or more to-dos from the list, then the IDs of some remaining to-dos will change. Speaking of removing to-dos, that’s what you’ll do in the following section.

Step 7: Code the Remove To-Dos Functionality

Removing to-dos from the list is another useful feature you can add to your to-do application. In this section, you’ll add two new Typer commands to the app’s CLI using Python. The first command will be remove. It’ll allow your users to remove a to-do by its ID. The second command will be clear and will enable the users to remove all the current to-dos from the database.

You can download the code, unit tests, and other additional resources for this section by clicking the link below and going to the source_code_step_7/ directory:

Implement the remove CLI Command

To implement the remove command in your application’s CLI, you first need to code the underlying .remove() method in Todoer. This method will provide all the functionality to remove a single to-do from the list using the to-do ID. Remember that you set up the to-do ID to be an integer number associated with a specific to-do. To display the to-do IDs, run the list command.

Here’s how you can code .remove() in Todoer:

Here, your code does the following:

• Line 6 defines .remove(). This method takes a to-do ID as an argument and removes the corresponding to-do from the database.
• Line 8 reads the to-do list from the database by calling .read_todos() on the database handler.
• Line 9 checks if any error occurs during the reading process. If so, then line 10 returns a named tuple, CurrentTodo, holding an empty to-do and the corresponding error code.
• Line 11 starts a try … except statement to catch any invalid ID coming from the user’s input.
• Line 12 removes the to-do at index todo_id - 1 from the to-do list. If an IndexError occurs during this operation, then line 14 returns a CurrentTodo instance with an empty to-do and the corresponding error code.
• Line 15 writes the updated to-do list back to the database.
• Line 16 returns a CurrentTodo tuple holding the removed to-do and a return code indicating a successful operation.

Now that you finished coding .remove() in Todoer, you can go to cli.py and add the remove command:

Wow! That’s a lot of code. Here’s how it works:

• Lines 8 and 9 define remove() as a Typer CLI command.
• Line 10 defines todo_id as an argument of type int. In this case, todo_id is a required instance of typer.Argument.
• Line 11 defines force as an option for the remove command. It’s a Boolean option that allows you to delete a to-do without confirmation. This option defaults to False (line 12) and its flags are --force and -f (lines 13 and 14).
• Line 15 defines a help message for the force option.
• Line 19 creates the required Todoer instance.
• Lines 21 to 33 define an inner function called _remove(). It’s a helper function that allows you to reuse the remove functionality. The function removes a to-do using its ID. To do that, it calls .remove() on todoer.
• Line 35 checks the value of force. A True value means that the user wants to remove the to-do without confirmation. In this situation, line 36 calls _remove() to run the remove operation.
• Line 37 starts an else clause that runs if force is False.
• Line 38 gets the entire to-do list from the database.
• Lines 39 to 43 define a try … except statement that retrieves the desired to-do from the list. If an IndexError occurs, then line 42 prints an error message, and line 43 exits the application.
• Lines 44 to 46 call Typer’s confirm() and store the result in delete. This function provides an alternative way to ask for confirmation. It allows you to use a dynamically created confirmation prompt like the one on line 45.
• Line 47 checks if delete is True, in which case line 48 calls _remove(). Otherwise, line 50 communicates that the operation was canceled.

You can try out the remove command by running the following on your command line:

In this group of commands, you first list all the current to-dos with the list command. Then you try to remove the to-do with the ID number 1. This presents you with a yes (y) or no (N) confirmation prompt. If you press Enter, then the application runs the default option, N, and cancels the remove action.

In the third command, you explicitly supply a y answer, so the application removes the to-do with ID number 1. If you list all the to-dos again, then you see that the to-do "Get some milk." is no longer in the list. As an experiment, go ahead and try to use the --force or -f option or try to remove a to-do that’s not in the list.

Implement the clear CLI Command

In this section, you’ll implement the clear command. This command will allow your users to remove all the to-dos from the database. Underneath the clear command is the .remove_all() method from Todoer, which provides the back-end functionality.

Go back to rptodo.py and add .remove_all() at the end of Todoer:

Inside .remove_all(), you remove all the to-dos from the database by replacing the current to-do list with an empty list. For consistency, the method returns a CurrentTodo tuple with an empty dictionary and an appropriate return or error code.

Now you can implement the clear command in the application’s CLI:

Here’s how this code works:

• Lines 8 and 9 define remove_all() as a Typer command using the @app.command() decorator with clear as the command name.
• Lines 10 to 14 define force as a Typer Option. It’s a required option of the Boolean type. The prompt argument asks the user to enter a proper value to force, which can be either y or n.
• Line 13 provides a help message for the force option.
• Line 17 gets the usual Todoer instance.
• Line 18 checks if force is True. If so, then the if code block removes all the to-dos from the database using .remove_all(). If something goes wrong during this process, the application prints an error message and exits (lines 21 to 25). Otherwise, it prints a success message on line 27.
• Line 29 runs if the user cancels the remove operation by supplying a false value, indicating no, to force.

To give this new clear command a try, go ahead and run the following on your terminal:

In the first example, you run clear. Once you press Enter, you get a prompt asking for yes (y) or no (N) confirmation. The uppercase N means that no is the default answer, so if you press Enter, you effectively cancel the clear operation.

In the second example, you run clear again. This time, you explicitly enter y as the answer to the prompt. This answer makes the application remove the entire to-do list from the database. When you run the list command, you get a message communicating that there are no tasks in the current to-do list.

That’s it! Now you have a functional CLI to-do application built with Python and Typer. Your application provides commands and options to create new to-dos, list all your to-dos, manage the to-do completion, and remove to-dos as needed. Isn’t that cool?

Conclusion

Building user-friendly command-line interface (CLI) applications is a fundamental skill to have as a Python developer. In the Python ecosystem, you’ll find several tools for creating this kind of application. Libraries such as argparse, Click, and Typer are good examples of those tools in Python. Here, you built a CLI application to manage a list of to-dos using Python and Typer.

In this tutorial, you learned how to:

• Build a to-do application with Python and Typer
• Add commands, arguments, and options to your to-do application using Typer
• Test your to-do application using Typer’s CliRunner and pytest in Python

You also practiced some additional skills, such as working with JSON files using Python’s json module and managing configuration files with Python’s configparser module. Now you’re ready to build command-line applications.

You can download the entire code and all the resources for this project by clicking the link below and going to the source_code_final/ directory:

Next Steps

In this tutorial, you’ve built a functional to-do application for your command line using Python and Typer. Even though the application provides only a minimal set of features, it’s a good starting point for you to continue adding features and keep learning in the process. This will help you take your Python skills to the next level.

Here are a few ideas you can implement to continue extending your to-do application:

• Add support for dates and deadlines: You can use the datetime module to get this done. This feature will allow the users to have better control over their tasks.
• Write more unit tests: You can use pytest to write more tests for your code. This will increase the code coverage and help you improve your testing skills. You may discover some bugs in the process. If so, go ahead and post them in the comments.
• Pack the application and publish it to PyPI: You can use Poetry or another similar tool to package your to-do application and publish it to PyPI.

These are just a few ideas. Take the challenge and build something cool on top of this project! You’ll learn a lot in the process.

Watch Now This tutorial has a related video course created by the Real Python team. Watch it together with the written tutorial to deepen your understanding: Building a Python Command-Line To-Do App With Typer