close

Articles Home » Programming Languages » Building Python CLIs with rich user interfaces using Prompt Toolkit

Building Python CLIs with rich user interfaces using Prompt Toolkit

Introduction

Introduction to Python CLIs

Command-line interfaces (CLIs) have been an essential tool for developers since the early days of computing. In Python, CLIs offer a powerful way to interact with programs, automate tasks, and manage systems. A CLI provides a means for the user to interact with the application through a command-line or terminal, making it an integral part of various development, testing, and deployment processes.

Importance of Rich User Interfaces in CLIs

Modern CLIs are no longer confined to plain text and monochrome displays. Rich user interfaces bring the efficiency and visual aesthetics of GUIs to the command line. By using elements such as color, auto-completion, syntax highlighting, and more, developers can create more interactive and user-friendly CLIs. These enhancements not only improve usability but also reduce the learning curve for new users and increase productivity for experienced users.

Overview of Prompt Toolkit

Prompt Toolkit is a Python library that aims to provide an easy and flexible way to build rich user interfaces in command-line applications. Developed to be cross-platform and support various customizations, Prompt Toolkit offers features like syntax highlighting, auto-suggestions, key bindings, and more. It abstracts many complexities of working directly with terminal controls, enabling developers to focus more on the application’s functionality.

Purpose of the Article

The goal of this article is to present a comprehensive guide to building Python CLIs with rich user interfaces using Prompt Toolkit. It will explore both the foundational concepts and the advanced techniques, complete with practical code examples. The article will not only showcase the features of Prompt Toolkit but also demonstrate how to apply them in real-world applications.

Who Should Read This Article

This article is primarily targeted at experienced developers who have a basic understanding of Python and are interested in enhancing their CLI applications with rich, interactive user interfaces. Whether you are looking to build a new CLI tool or improve an existing one, the insights and examples in this article will provide you with the knowledge and tools to create engaging and efficient command-line interfaces using Prompt Toolkit.

By the end of this introduction, readers should have a clear understanding of what to expect from the article and how it aligns with their interests and needs in the domain of Python CLI development.

Setting Up the Development Environment

Required Python Version

Building Python CLI applications with Prompt Toolkit requires a specific version of Python to ensure compatibility. Prompt Toolkit 3.x, for example, requires Python 3.6 or above. It’s essential to have the correct version installed, and you can check your current Python version by running the following command:

python --versionCode language: Bash (bash)

If you need to upgrade, you can download the latest version from the official Python website.

Installing Prompt Toolkit

Installing Prompt Toolkit is a straightforward process and can be done using the pip package manager. Open your terminal and run the following command:

pip install prompt-toolkitCode language: Bash (bash)

This will download and install the latest stable version of Prompt Toolkit along with its core dependencies.

Additional Libraries and Dependencies

Depending on the complexity of your CLI application, you may need to install additional libraries. For instance, if you plan to work with databases or APIs, you may require packages like SQLAlchemy or Requests. It’s wise to identify the necessary libraries beforehand and include them in your project’s requirements file:

pip install -r requirements.txtCode language: Bash (bash)

Your requirements.txt file should list all the required packages, including Prompt Toolkit.

Basic Setup

Once you have everything installed, you can create a simple CLI application with Prompt Toolkit. Here’s a basic code snippet to get you started:

from prompt_toolkit import prompt

def main():
    user_input = prompt('Please enter your command: ')
    print(f'You entered: {user_input}')

if __name__ == "__main__":
    main()Code language: Python (python)

Save this script and run it. You’ll notice the rich features of Prompt Toolkit even in this simple example, such as line editing and history navigation.

Introduction to Prompt Toolkit

What is Prompt Toolkit?

Prompt Toolkit is a sophisticated library designed to facilitate the creation of interactive and attractive command-line interfaces (CLIs) in Python. It provides a robust set of tools to build applications that offer a rich user experience, bridging the gap between traditional CLIs and graphical user interfaces (GUIs). The library’s flexibility and extensibility have made it a popular choice among Python developers for CLI applications.

Key Features and Benefits

Prompt Toolkit provides a wide range of features that allow developers to enhance the user interaction within a command-line environment:

  1. Syntax Highlighting: Colorize input according to syntax rules, which is especially useful for programming shells.
  2. Auto-Completion: Suggest completions based on the current input, enhancing the user’s efficiency and accuracy.
  3. Key Bindings: Customize key combinations to trigger specific actions, allowing for personalized interaction.
  4. Mouse Support: Extend interactivity beyond the keyboard, enabling mouse clicks and scrolling.
  5. Multi-line Editing: Facilitate the editing of multi-line input, useful for complex commands or code snippets.
  6. Asynchronous Programming Support: Implement responsive interfaces that don’t block the main thread.

These features contribute to a more interactive, user-friendly CLI, often resulting in increased productivity and more enjoyable user experiences.

Brief History and Community Support

Prompt Toolkit was created by Jonathan Slenders and first released in 2014. Since then, it has become one of the go-to libraries for building advanced command-line applications in Python. The library has evolved through community contributions and feedback, resulting in a powerful toolkit that continues to grow in popularity.

The thriving community around Prompt Toolkit ensures constant updates, extensive documentation, and a wealth of online resources, tutorials, and support forums. This backing provides a solid foundation for both new and experienced developers to leverage the capabilities of Prompt Toolkit effectively.

Simple Prompt with Prompt Toolkit

To demonstrate the basic functionality of Prompt Toolkit, here’s a simple example that uses the prompt function to ask the user for input:

from prompt_toolkit import prompt

def get_user_name():
    name = prompt('What is your name? ')
    print(f'Hello, {name}!')

if __name__ == "__main__":
    get_user_name()Code language: Python (python)

Running this script will present a styled prompt, and the user can type their name. The entered name is then printed with a greeting.

This example barely scratches the surface of what’s possible with Prompt Toolkit, but it offers a glimpse into its ease of use and potential.

Building a Basic CLI with Prompt Toolkit

Understanding CLI Structure

Before diving into code, it’s essential to understand the structure of a CLI application built with Prompt Toolkit. A basic CLI typically consists of the following components:

  1. Command Prompt: Where users enter commands, parameters, or options.
  2. Command Parser: Interprets the user’s input and maps it to corresponding actions or functions.
  3. Action Handlers: Functions or methods that execute the specific tasks related to each command.
  4. Feedback Mechanism: Provides responses to the user, such as success messages, errors, or data display.

The synergy between these components creates an intuitive and responsive CLI experience.

Creating a Basic Command Prompt

Prompt Toolkit offers various features for crafting an engaging command prompt. The essential step is to define the prompt and how it will handle user input. You can design the appearance of the prompt, adding colors, and even implementing real-time validation.

Here’s a basic snippet to create a prompt:

from prompt_toolkit import prompt

user_input = prompt('Enter a command: ')Code language: Python (python)

This code will display a simple command line, waiting for the user’s input.

Building a Simple CLI

Let’s build upon the prompt to create a very basic CLI that can handle a few simple commands:

from prompt_toolkit import prompt

def handle_command(command):
    if command == 'hello':
        return 'Hello, World!'
    elif command == 'exit':
        return None
    else:
        return 'Unknown command!'

def main():
    while True:
        user_input = prompt('CLI> ')
        response = handle_command(user_input.strip())

        if response is None:
            print('Exiting CLI.')
            break

        print(response)

if __name__ == "__main__":
    main()Code language: Python (python)

This code snippet sets up a very basic command-line interface that recognizes two commands: ‘hello’ and ‘exit’. If the user types ‘hello’, it will respond with a greeting. If the user types ‘exit’, it will terminate the CLI. Any other input will result in an ‘Unknown command!’ message.

This example illustrates the fundamental structure of a CLI application using Prompt Toolkit. Although simple, it provides a foundation that you can expand and adapt to more complex use cases, incorporating many of the rich features that Prompt Toolkit has to offer.

Adding Rich User Interfaces to CLI

Using Colors and Styles

Prompt Toolkit provides an extensive set of styling options that enable developers to enhance the visual appeal of their CLI applications. Colors, bold text, italics, and other styles can be applied to various parts of the user interface.

You can use the HTML class for styling:

from prompt_toolkit import prompt
from prompt_toolkit.formatted_text import HTML

user_input = prompt(HTML('<ansigreen>Enter a command:</ansigreen> '))Code language: Python (python)

This code snippet displays the prompt text in green, giving it a more visually engaging appearance.

Creating Interactive Prompts

Interactive prompts go beyond simple text input to offer options, selections, confirmations, and other interactive elements. Here’s how you can create an interactive yes/no prompt:

from prompt_toolkit.shortcuts import confirm

response = confirm('Do you want to continue? ')
print('Yes, let\'s continue!' if response else 'No, let\'s stop here.')Code language: Python (python)

This will present the user with a ‘[y/N]’ prompt, and the response will be a boolean value.

Implementing Auto-Complete Features

Auto-completion significantly enhances user experience by suggesting possible completions for the current input. With Prompt Toolkit, you can easily add this feature:

from prompt_toolkit import prompt
from prompt_toolkit.completion import WordCompleter

completer = WordCompleter(['command1', 'command2', 'exit'])
user_input = prompt('CLI> ', completer=completer)Code language: Python (python)

This will suggest ‘command1’, ‘command2’, or ‘exit’ as the user types.

Adding Various UI Elements

Combining these features, you can create a rich and interactive CLI interface:

from prompt_toolkit import prompt
from prompt_toolkit.completion import WordCompleter
from prompt_toolkit.formatted_text import HTML

def main():
    completer = WordCompleter(['hello', 'exit'], ignore_case=True)
    while True:
        user_input = prompt(HTML('<ansired>CLI></ansired> '), completer=completer)
        if user_input.strip() == 'exit':
            print('Exiting CLI.')
            break
        elif user_input.strip() == 'hello':
            print('Hello, World!')
        else:
            print('Unknown command!')

if __name__ == "__main__":
    main()Code language: Python (python)

This example combines colors, interactive prompts, and auto-completion to create a more engaging command-line experience.

Advanced Prompt Toolkit Features

Working with Asynchronous Programming

Asynchronous programming can make your CLI more responsive and capable of handling multiple tasks simultaneously. Prompt Toolkit supports Python’s asyncio, allowing you to integrate asynchronous code into your CLI applications.

Here’s a simple example using asynchronous programming to perform a background task while accepting user input:

import asyncio
from prompt_toolkit import prompt

async def background_task():
    while True:
        print('Background task running...')
        await asyncio.sleep(5)

async def main():
    task = asyncio.create_task(background_task())

    user_input = await prompt('Enter a command (type "exit" to quit): ', async_=True)

    if user_input == 'exit':
        task.cancel()

asyncio.run(main())Code language: Python (python)

Custom Key Bindings

Key bindings allow users to execute specific actions or commands using custom key combinations. This increases efficiency and provides a more personalized user experience.

You can define custom key bindings in Prompt Toolkit like this:

from prompt_toolkit import prompt
from prompt_toolkit.keys import Keys
from prompt_toolkit.key_binding import KeyBindings

bindings = KeyBindings()

@bindings.add(Keys.ControlC)
def _(event):
    event.app.exit(result='Exiting via Ctrl-C!')

user_input = prompt('Enter a command: ', key_bindings=bindings)Code language: Python (python)

Using Layouts and Containers

Layouts enable you to organize your CLI into distinct sections, just like in a GUI. With Prompt Toolkit’s layout system, you can create complex interfaces with menus, toolbars, and status lines.

Here’s an example of a basic layout with a header and content area:

from prompt_toolkit import Application
from prompt_toolkit.layout.containers import VSplit, HSplit
from prompt_toolkit.layout.layout import Layout
from prompt_toolkit.widgets import Box, Label, TextArea

header = Label(text="My Custom CLI", style="class:title")
content = TextArea(text="Command Line Content Here")

root_container = HSplit([
    header,
    Box(content, height=10),
])

layout = Layout(root_container)

app = Application(layout=layout)
app.run()Code language: Python (python)

Implementing Advanced Features

Combining these advanced features, you can create a powerful and versatile CLI application:

from prompt_toolkit import Application
from prompt_toolkit.key_binding import KeyBindings
from prompt_toolkit.layout.containers import HSplit
from prompt_toolkit.layout.layout import Layout
from prompt_toolkit.widgets import Label, TextArea

bindings = KeyBindings()

@bindings.add('c-q')
def _(event):
    event.app.exit()

header = Label(text="Press 'Ctrl-Q' to quit", style="class:title")
content = TextArea()

root_container = HSplit([
    header,
    content,
])

layout = Layout(root_container)

app = Application(layout=layout, key_bindings=bindings)
app.run()Code language: Python (python)

This application integrates custom key bindings with layouts to provide a more dynamic and user-friendly interface.

Example Exercise: Building a Real-World CLI Application

Defining the Project

For our real-world example, let’s design a CLI application that serves as a basic task manager. Users can add, list, update, and delete tasks.

The main features include:

  • Adding a new task with a description and priority.
  • Listing all tasks.
  • Updating a task’s description or priority.
  • Deleting a task.

Designing the User Interface

The UI will comprise of:

  • Main Menu: Options to add, list, update, delete, or exit.
  • Add Task Interface: Prompts for task description and priority.
  • List Tasks Interface: Displays all tasks.
  • Update and Delete Interfaces: Select a task and perform the required operation.

Writing the Core Logic

The core logic will include functions to handle each of the main operations:

  • add_task(): Adds a new task to the list.
  • list_tasks(): Prints the current list of tasks.
  • update_task(): Modifies an existing task.
  • delete_task(): Removes a task from the list.

Complete Project Code

Here’s an example code that ties everything together:

from prompt_toolkit import prompt
from prompt_toolkit.completion import WordCompleter

tasks = []

def main_menu():
    completer = WordCompleter(['add', 'list', 'update', 'delete', 'exit'])
    option = prompt('Task Manager> ', completer=completer)
    return option.strip()

def add_task():
    description = prompt('Enter task description: ')
    priority = prompt('Enter task priority (low/medium/high): ')
    tasks.append((description, priority))
    print(f"Task '{description}' added.")

def list_tasks():
    print("\nTasks:")
    for idx, task in enumerate(tasks):
        print(f"{idx}. {task[0]} (Priority: {task[1]})")

def update_task():
    list_tasks()
    task_idx = int(prompt('Select task number to update: '))
    description = prompt('Enter new description: ')
    priority = prompt('Enter new priority (low/medium/high): ')
    tasks[task_idx] = (description, priority)
    print("Task updated.")

def delete_task():
    list_tasks()
    task_idx = int(prompt('Select task number to delete: '))
    del tasks[task_idx]
    print("Task deleted.")

def main():
    while True:
        option = main_menu()
        if option == 'add':
            add_task()
        elif option == 'list':
            list_tasks()
        elif option == 'update':
            update_task()
        elif option == 'delete':
            delete_task()
        elif option == 'exit':
            print('Exiting Task Manager.')
            break

if __name__ == "__main__":
    main()Code language: Python (python)

Testing and Debugging Tips

To ensure the CLI application functions as intended, follow these testing and debugging tips:

  • Unit Testing: Break down the application into smaller parts and test individual functions.
  • Manual Testing: Run the application and manually test various scenarios, edge cases, and potential user mistakes.
  • Logging: Implement logging to track what’s happening inside the application during execution.
  • Error Handling: Add proper error handling to ensure that the application handles unexpected situations gracefully.

Integrating with Other Python Libraries

Prompt Toolkit can work seamlessly with other Python libraries to create more sophisticated CLI applications. This section explores how to integrate databases, web APIs, and other UI libraries within your CLI.

Working with Databases

A common requirement for many CLI applications is storing and retrieving data. You can integrate Prompt Toolkit with a database like SQLite to manage data within your CLI.

Example code for adding a task to an SQLite database:

import sqlite3

def add_task_to_db(description, priority):
    conn = sqlite3.connect('tasks.db')
    cursor = conn.cursor()
    
    cursor.execute("INSERT INTO tasks (description, priority) VALUES (?, ?)", (description, priority))
    
    conn.commit()
    conn.close()
    print(f"Task '{description}' added to the database.")Code language: Python (python)

Integrating with Web APIs

Your CLI may need to communicate with web services. Integrating web APIs enables your application to fetch, send, and manipulate data over the internet.

Example code for fetching data from an API:

import requests

def fetch_data_from_api():
    response = requests.get('https://api.example.com/data')
    if response.status_code == 200:
        return response.json()
    else:
        print('Failed to fetch data from API.')
        return NoneCode language: Python (python)

Combining with Other UI Libraries

If your CLI needs to perform graphical rendering or other advanced UI features, you can combine Prompt Toolkit with libraries like Matplotlib to visualize data.

Example code for plotting data with Matplotlib:

import matplotlib.pyplot as plt

def plot_data(data):
    plt.plot(data)
    plt.show()Code language: Python (python)

Real-world Integrations

Combining these elements, you can create a multifaceted CLI application:

from prompt_toolkit import prompt

def main():
    while True:
        action = prompt('Choose action (add/fetch/plot/exit): ')
        
        if action == 'add':
            description = prompt('Enter task description: ')
            priority = prompt('Enter task priority (low/medium/high): ')
            add_task_to_db(description, priority)
        elif action == 'fetch':
            data = fetch_data_from_api()
            print(data)
        elif action == 'plot':
            data = [1, 2, 3, 4, 5]
            plot_data(data)
        elif action == 'exit':
            print('Exiting application.')
            break

if __name__ == "__main__":
    main()Code language: Python (python)

Integrating Prompt Toolkit with other Python libraries broadens the horizons of what you can achieve with your CLI applications. Whether it’s storing data, communicating with web services, or rendering graphical content, the synergies between these libraries create endless possibilities for rich and functional command-line interfaces.

Best Practices and Common Pitfalls

Creating powerful and effective CLI applications with Prompt Toolkit requires adherence to best practices and awareness of common pitfalls. This section provides insights and guidelines to help you optimize your development process.

Design Considerations

  • Consistency: Maintain consistent command structure, syntax, and feedback throughout the application to provide an intuitive user experience.
  • Responsiveness: Leverage asynchronous programming to ensure smooth user interaction, even during long-running tasks.
  • Error Handling: Implement comprehensive error handling to guide the user and prevent crashes.
  • Accessibility: Consider color contrasts, text sizes, and other factors to ensure your CLI is accessible to users with various needs.

Performance Tips

  • Minimize Blocking Calls: Use asynchronous programming to avoid blocking the main thread, which can lead to a sluggish user experience.
  • Efficient Data Handling: Optimize data queries and manipulation, especially when working with databases or APIs, to enhance responsiveness.
  • Resource Management: Properly close database connections, file handles, and other resources to prevent leaks and other performance issues.

Security Considerations

  • Input Validation: Always validate user input to prevent SQL injection, command injection, and other security risks.
  • Secure Connections: When integrating with web APIs, use HTTPS to encrypt data during transmission.
  • Sensitive Data Handling: If your application deals with sensitive data, ensure it is securely stored, transmitted, and handled throughout the lifecycle.

Common Mistakes and How to Avoid Them

  1. Ignoring User Experience: Don’t sacrifice usability for functionality. Test your CLI with real users to ensure that it meets their expectations and is user-friendly.
  2. Hardcoding Configuration: Avoid hardcoding API keys, database credentials, and other configurations within the code. Use environment variables or secure configuration files instead.
  3. Poor Error Handling: Always provide clear error messages and guide the user to the correct action instead of simply printing stack traces or generic errors.
  4. Lack of Documentation: Document the code, provide help menus, and ensure that the users know how to use the application efficiently.

Building robust and effective CLI applications with Prompt Toolkit involves more than just writing code. By focusing on design, performance, security, and avoiding common mistakes, you can create command-line interfaces that not only accomplish their technical goals but also delight and empower their users. Following these best practices will lead to a more successful and maintainable CLI project.

The beauty of Prompt Toolkit and Python lies in their flexibility and robustness. I encourage you to experiment with the examples and concepts shared in this article. Challenge yourself with new features, combine different libraries, or even start a community project. The possibilities are boundless, and experimentation is the key to mastering and innovating.

Related posts: