wasabi 0.5.0

A lightweight console printing and formatting toolkit

wasabi: A lightweight console printing and formatting toolkit

Over the years, I've written countless implementations of coloring and formatting utilities to output messages in our libraries like spaCy, Thinc and Prodigy. While there are many other great open-source options, I've always ended up wanting something slightly different or slightly custom.

This package is still a work in progress and aims to bundle those utilities in a standardised way so they can be shared across our other projects. It's super lightweight, has zero dependencies and works across Python 2 and 3.

💬 FAQ

Are you going to add more features?

Yes, there's still a few of helpers and features to port over. However, the new features will be heavily biased by what we (think we) need. I always appreciate pull requests to improve the existing functionality – but I want to keep this library as simple, lightweight and specific as possible.

Can I use this for my projects?

Sure, if you like it, feel free to adopt it! Just keep in mind that the package is very specific and not intended to be a full-featured and fully customisable formatting library. If that's what you're looking for, you might want to try other packages – for example, colored, crayons, colorful, tabulate, console or py-term, to name a few.

Why wasabi?

I was looking for a short and descriptive name, but everything was already taken. So I ended up naming this package after one of my rats, Wasabi. 🐀

⌛️ Installation

pip install wasabi

🎛 API

function msg

An instance of Printer, initialized with the default config. Useful as a quick shortcut if you don't need to customize initialization.

from wasabi import msg

msg.good("Success!")

class Printer

method Printer.__init__

from wasabi import Printer

msg = Printer()

Argument	Type	Description	Default
pretty	bool	Pretty-print output with colors and icons.	True
no_print	bool	Don't actually print, just return.	False
colors	dict	Add or overwrite color values, names mapped to 0-256.	None
icons	dict	Add or overwrite icon. Name mapped to unicode.	None
line_max	int	Maximum line length (for divider).	80
animation	unicode	Steps of loading animation for Printer.loading.	"⠙⠹⠸⠼⠴⠦⠧⠇⠏"
animation_ascii	unicode	Alternative animation for ASCII terminals.	"|/-\\"
hide_animation	bool	Don't display animation, e.g. for logs.	False
ignore_warnings	bool	Don't output messages of type MESSAGE.WARN.	False
env_prefix	unicode	Prefix for environment variables, e.g. WASABI_LOG_FRIENDLY.	"WASABI"
RETURNS	Printer	The initialized printer.	-

method Printer.text

msg = Printer()
msg.text("Hello world!")

Argument	Type	Description	Default
title	unicode	The main text to print.	""
text	unicode	Optional additional text to print.	""
color	unicode / int	Color name or value.	None
icon	unicode	Name of icon to add.	None
show	bool	Whether to print or not. Can be used to only output messages under certain condition, e.g. if --verbose flag is set.	True
spaced	bool	Whether to add newlines around the output.	False
no_print	bool	Don't actually print, just return. Overwrites global setting.	False
exits	int	If set, perform a system exit with the given code after printing.	None

method Printer.good, Printer.fail, Printer.warn, Printer.info

Print special formatted messages.

msg = Printer()
msg.good("Success")
msg.fail("Error")
msg.warn("Warning")
msg.info("Info")

Argument	Type	Description	Default
title	unicode	The main text to print.	""
text	unicode	Optional additional text to print.	""
show	bool	Whether to print or not. Can be used to only output messages under certain condition, e.g. if --verbose flag is set.	True
exits	int	If set, perform a system exit with the given code after printing.	None

method Printer.divider

Print a formatted divider.

msg = Printer()
msg.divider("Heading")

Argument	Type	Description	Default
text	unicode	Headline text. If empty, only the line is printed.	""
char	unicode	Single line character to repeat.	"="
show	bool	Whether to print or not. Can be used to only output messages under certain condition, e.g. if --verbose flag is set.	True
icon	unicode	Optional icon to use with title.	None

contextmanager Printer.loading

msg = Printer()
with msg.loading("Loading..."):
    # Do something here that takes longer
    time.sleep(10)
msg.good("Successfully loaded something!")

Argument	Type	Description	Default
text	unicode	The text to display while loading.	""

method Printer.table, Printer.row

See Tables.

property Printer.counts

Get the counts of how often the special printers were fired, e.g. MESSAGES.GOOD. Can be used to print an overview like "X warnings"

msg = Printer()
msg.good("Success")
msg.fail("Error")
msg.warn("Error")

print(msg.counts)
# Counter({'good': 1, 'fail': 2, 'warn': 0, 'info': 0})

Argument	Type	Description
RETURNS	Counter	The counts for the individual special message types.

Tables

function table

Lightweight helper to format tabular data.

from wasabi import table

data = [("a1", "a2", "a3"), ("b1", "b2", "b3")]
header = ("Column 1", "Column 2", "Column 3")
widths = (8, 9, 10)
aligns = ("r", "c", "l")
formatted = table(data, header=header, divider=True, widths=widths, aligns=aligns)

Column 1   Column 2    Column 3
--------   ---------   ----------
      a1      a2       a3
      b1      b2       b3

Argument	Type	Description	Default
data	iterable / dict	The data to render. Either a list of lists (one per row) or a dict for two-column tables.
header	iterable	Optional header columns.	None
footer	iterable	Optional footer columns.	None
divider	bool	Show a divider line between header/footer and body.	False
widths	iterable / "auto"	Column widths in order. If "auto", widths will be calculated automatically based on the largest value.	"auto"
max_col	int	Maximum column width.	30
spacing	int	Number of spaces between columns.	3
aligns	iterable / unicode	Columns alignments in order. "l" (left, default), "r" (right) or "c" (center). If If a string, value is used for all columns.	None
multiline	bool	If a cell value is a list of a tuple, render it on multiple lines, with one value per line.	False
RETURNS	unicode	The formatted table.

function row

from wasabi import row

data = ("a1", "a2", "a3")
formatted = row(data)

a1   a2   a3

Argument	Type	Description	Default
data	iterable	The individual columns to format.
widths	iterable / int / "auto"	Column widths, either one integer for all columns or an iterable of values. If "auto", widths will be calculated automatically based on the largest value.	"auto"
spacing	int	Number of spaces between columns.	3
aligns	iterable	Columns alignments in order. "l" (left), "r" (right) or "c" (center).	None
RETURNS	unicode	The formatted row.

class TracebackPrinter

Helper to output custom formatted tracebacks and error messages. Currently used in Thinc.

method TracebackPrinter.__init__

Initialize a traceback printer.

from wasabi import TracebackPrinter

tb = TracebackPrinter(tb_base="thinc", tb_exclude=("check.py",))

Argument	Type	Description	Default
color_error	unicode / int	Color name or code for errors (passed to color helper).	"red"
color_tb	unicode / int	Color name or code for traceback headline (passed to color helper).	"blue"
color_highlight	unicode / int	Color name or code for highlighted text (passed to color helper).	"yellow"
indent	int	Number of spaces to use for indentation.	2
tb_base	unicode	Name of directory to use to show relative paths. For example, "thinc" will look for the last occurence of "/thinc/" in a path and only show path to the right of it.	None
tb_exclude	tuple	List of filenames to exclude from traceback.	tuple()
RETURNS	TracebackPrinter	The traceback printer.

method TracebackPrinter.__call__

Output custom formatted tracebacks and errors.

from wasabi import TracebackPrinter
import traceback

tb = TracebackPrinter(tb_base="thinc", tb_exclude=("check.py",))

error = tb("Some error", "Error description", highlight="kwargs", tb=traceback.extract_stack())
raise ValueError(error)

  Some error
  Some error description

  Traceback:
  ├─ <lambda> [61] in .env/lib/python3.6/site-packages/pluggy/manager.py
  ├─── _multicall [187] in .env/lib/python3.6/site-packages/pluggy/callers.py
  └───── pytest_fixture_setup [969] in .env/lib/python3.6/site-packages/_pytest/fixtures.py
         >>> result = call_fixture_func(fixturefunc, request, kwargs)

Argument	Type	Description	Default
title	unicode	The message title.
*texts	unicode	Optional texts to print (one per line).
highlight	unicode	Optional sequence to highlight in the traceback, e.g. the bad value that caused the error.	False
tb	iterable	The traceback, e.g. generated by traceback.extract_stack().	None
RETURNS	unicode	The formatted traceback. Can be printed or raised by custom exception.

Utilities

function color

from wasabi import color

formatted = color("This is a text", fg="white", bg="green", bold=True)

Argument	Type	Description	Default
text	unicode	The text to be formatted.	-
fg	unicode / int	Foreground color. String name or 0 - 256.	None
bg	unicode / int	Background color. String name or 0 - 256.	None
bold	bool	Format the text in bold.	False
RETURNS	unicode	The formatted string.

function wrap

from wasabi import wrap

wrapped = wrap("Hello world, this is a text.", indent=2)

Argument	Type	Description	Default
text	unicode	The text to wrap.	-
wrap_max	int	Maximum line width, including indentation.	80
indent	int	Number of spaces used for indentation.	4
RETURNS	unicode	The wrapped text with line breaks.

function diff_strings

from wasabi import diff_strings

diff = diff_strings("hello world!", "helloo world")

Argument	Type	Description	Default
a	unicode	The first string to diff.
b	unicode	The second string to diff.
fg	unicode / int	Foreground color. String name or 0 - 256.	"black"
bg	tuple	Background colors as (insert, delete) tuple of string name or 0 - 256.	("green", "red")
RETURNS	unicode	The formatted diff.

Environment variables

Wasabi also respects the following environment variables. The prefix can be customised on the Printer via the env_prefix argument. For example, setting env_prefix="SPACY" will expect the environment variable SPACY_LOG_FRIENDLY.

Name	Description
ANSI_COLORS_DISABLED	Disable colors.
WASABI_LOG_FRIENDLY	Make output nicer for logs (no colors, no animations).
WASABI_NO_PRETTY	Disable pretty printing, e.g. colors and icons.

🔔 Run tests

Fork or clone the repo, make sure you have pytest installed and then run it on the package directory. The tests are located in /wasabi/tests.

pip install pytest
cd wasabi
python -m pytest wasabi