Use the custom `print` function¶

Introduction¶

Since v0.1.0, Caliber comes with a custom implementation of the builtin print function. caliber.print() behaves as the builtin print and the rich.print() function in the rich package. In addition, it integrates well with the Caliber TUI. In this article we demonstrate how the function can be swapped with the builtin print, and the possibilities this opens for.

Basic usage¶

Open a repl, i.e. open a terminal and type py or python, and start experimenting. Type the following, and you will get no surprises:

from caliber import print

print('Hello, World!')

Notice how we used the from ... import ... syntax to swap caliber.print with the builtin print.

Since caliber.print emulates the print function from the Rich library, we can also use console markup or print Rich renderables like e.g. progress displays. More on progress displays in the next section. Type the following to see console markup in action:

print('[bold italic blue]Hello[/bold italic blue], [red]World[/red]!')

Printing Rich renderables¶

Say you have a function that performs three operations, 1) fetch data from an external source, 2) process the data, and 3) prepare results for further use. The function could have the following structure:

from time import sleep


def fetch_and_process_data():
    # Fetch data
    sleep(2)

    # Process data
    sleep(2)

    # Prepare output
    sleep(2)

In a real life situation, each of these steps might take some time, and if the elapsed time is long, the program execution might seem idle. This is a great use case for the Rich progress display.

A progress display can be added by slightly rewriting the function above.

from time import sleep

from rich.progress import Progress

from caliber import print


def fetch_and_process_data():
    with Progress() as progress:
        print(progress)
        progress_task = progress.add_task(
            'Fetching and processing data...', total=3
        )
        # Fetch data
        sleep(2)
        progress.update(progress_task, advance=1)

        # Process data
        sleep(2)
        progress.update(progress_task, advance=1)

        # Prepare output
        sleep(2)
        progress.update(progress_task, advance=1)

Notice that we are importing caliber.print and using it to print the progress display. Note that this is not necessary if you simply run the script as it is, since Rich automatically displays the progress display.

Printing in the text-based user interface (TUI)¶

The call to caliber.print in the above example becomes necessary if you wish to display the progress display while running the function as part of a workflow that is run using the Caliber CLI.

In fact, anything you wish to print to the terminal when running a workflow using the Caliber CLI should be printed using caliber.print, since the objects that are passed to the function will be displayed in a separate Task activity panel in the TUI.

Using caliber.print and running the function above as part of a workflow produces the following view.

print-to-task-activity

The contents of the Task activity panel is accumulated while a task is run, and cleared only when a new task is started. This way, you can use caliber.print to display messages that indicate the progress of the task.

Summary¶

Now you know

that Caliber comes with a custom print which can be swapped with the builtin print by using from caliber import print in the script or module you are using it,
that caliber.print can be used to display console markup and Rich renderables,
and that you should always use caliber.print when displaying objects in your workflows, this way the objects will be displayed in Task activity panel in the TUI.

Use the custom print function¶