Introducing outputformat, a small python library to help you decorate and beautify your standard output.

The idea behind this library is to make the output of our algorithms more readable and easier to interpret for humans. Having scripts that can easily generate automated small reports can be quite useful, not only for you to quickly grasp your own results, but also when you need to quickly communicate them to your peers (think about copy/pasting something from your terminal into a Slack channel, in a way that others can actually understand the results)

The project is available at GitHub. The latest release can simply be installed using pip:

pip install outputformat

There are no dependencies, the idea is to make the library as light as possible.

I recommend using ouf as an alias when importing:

import outputformat as ouf

It’s a wordplay between “OutputFormat” and the French expression “Ouf“, which basically means “Cool“. More details about the expression are here in this link, in case you’re interested.

Basic usage

The library is still in early development (v0.1.2 as of writing), but we have already some basic functionality that can actually be helpful in the daily work.

The main functions are:

  • ouf.boxtitle
  • ouf.linetitle
  • ouf.bigtitle
  • ouf.showlist
  • ouf.bar
  • ouf.barlist

By default, functions print the result. You have the alternative to return a string instead, using the argument return_str=True (nothing will be printed in this case). This can be useful in case there’s a specific logger that you need to use.

Creating titles

To decorate titles with a box around them, use ouf.boxtitle:

ouf.boxtitle("Long title in a box")

Boxes can have different styles:

ouf.boxtitle("Box with 'line' style", style="line")
ouf.boxtitle("Box with 'double' style", style="double")
ouf.boxtitle("Box with 'dashes' style", style="dashes")

Or you can pass any character and it will be used for the decoration:

ouf.boxtitle("Box with custom character as style", style="ø")

With the same options as for boxtitle, you can use linetitle for a simple line underneath your text:

ouf.linetitle("Long title with 'double' underline", style="double")

For the really important stuff, you can use ouf.bigtitle:

ouf.bigtitle("Here's a big title!")

It uses ASCII art to create characters. Different font options will be added in future releases.

Showing lists

To show lists, call ouf.showlist

ouf.showlist(["Item A", "Item B", "Item C", "Item D"])

Mixed types can be used, as each item will be converted to a string before showing. For floats, you can use the parameter precision to set how many decimals are shown (this avoid long floats that make the list harder to read). Also, you can pass a title to your list:

data = ["String", 42, None, 99.99000000001, False, np.nan]
ouf.showlist(data, title="List of items with mixed type", precision=2)

Different styles can be used to present the list:

ouf.showlist(["Item A", "Item B", "Item C", "Item D"], style="line", title="Style line")

ouf.showlist(["String", 42, None, 99.99, False], style="box", title="Style box")

ouf.showlist([42, -10, -42, 99], style="ordinal", title="Style ordinal")

You also have the possibility of using a custom marker for the list:

data = ["Item A", "Item B", "Item C", "Item D"]
ouf.showlist(data, style="~>", title="Custom style list")

Creating bars

Sometimes the best way to visualize a value is a quick graphical representation, so ouf.bar can be used. The first parameter value is the filled amount, the second maxvalue is the maximum amount:

ouf.bar(35, 50)

Important to note here that the idea of this function isn’t to create progress bars to track your code, we have already great libraries that do this very well ( as tqdm and rich for example). The purpose is to easily visualize the results of your code.

Note that some integer rounding is needed to create the bar, so the size is not precise, more like a ballpark visualisation. The size of the bar (in characters) is defined by length, and longer bars will be more precise.

ouf.bar(35, 50, length=10)
ouf.bar(35, 50, length=50)

Different styles are available, as well as the possibility of having a title for your bar. Values and percentages after the bar are also optional:

ouf.bar(35, 50, style="block", title="Block style")

ouf.bar(35, 50, style="battery", title="Battery style", values_precision=0, show_percentage=False)

ouf.bar(35, 50, style="bar",  title="Bar style", show_values=False)

ouf.bar(35, 50, style="circle", length=10, title="Circle style", show_percentage=False)

ouf.bar(35, 50, style="star", length=5, title="Star style", show_percentage=False, show_values=False)

List of values

A more useful case is to show a list of values. For this use ouf.barlist, that accepts the same customization as ouf.bar

values = [6, 3, 13, 8]
titles = ["var", "long var name", "medium var", "another"]
ouf.barlist(values, titles, maxvalue=15, values_precision=0)

In case maxvalue is not provided, the largest value of the list will be used as 100%

Final thoughts

The creation of outputformat came from the necessity of quickly understanding and sharing results. Having values aligned, organized and without clutter can make communication easier, especially when sharing quick snippets in a chat, for example. It can be easily installed with pip install outputformat and usage is meant to be short and intuitive.

Future releases will add some needed features, as showing dictionaries, for example. If you want to get involved, here’s the GitHub repo!