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 with Python 3.6+.

💬 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`	str	Steps of loading animation for `Printer.loading`.	`"⠙⠹⠸⠼⠴⠦⠧⠇⠏"`
`animation_ascii`	str	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`	str	Prefix for environment variables, e.g. `WASABI_LOG_FRIENDLY`.	`"WASABI"`
`timestamp`	bool	Add timestamp before output.	`False`
RETURNS	`Printer`	The initialized printer.	-

`method` `Printer.text`

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

Argument	Type	Description	Default
`title`	str	The main text to print.	`""`
`text`	str	Optional additional text to print.	`""`
`color`	unicode / int	Color name or value.	`None`
`icon`	str	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`	str	The main text to print.	`""`
`text`	str	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`	str	Headline text. If empty, only the line is printed.	`""`
`char`	str	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`	str	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`	str	The text to display while loading.	`"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`
`env_prefix`	unicode	Prefix for environment variables, e.g. WASABI_LOG_FRIENDLY.	`"WASABI"`
`color_values`	dict	Add or overwrite color values, name mapped to value.	`None`
`fg_colors`	iterable	Foreground colors, one per column. None can be specified for individual columns to retain the default background color.	`None`
`bg_colors`	iterable	Background colors, one per column. None can be specified for individual columns to retain the default background color.	`None`
RETURNS	str	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`	list / 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`	list	Columns alignments in order. `"l"` (left), `"r"` (right) or `"c"` (center).	`None`
`env_prefix`	unicode	Prefix for environment variables, e.g. WASABI_LOG_FRIENDLY.	`"WASABI"`
`fg_colors`	list	Foreground colors for the columns, in order. None can be specified for individual columns to retain the default foreground color.	`None`
`bg_colors`	list	Background colors for the columns, in order. None can be specified for individual columns to retain the default background color.	`None`
RETURNS	str	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`	str / int	Color name or code for errors (passed to `color` helper).	`"red"`
`color_tb`	str / int	Color name or code for traceback headline (passed to `color` helper).	`"blue"`
`color_highlight`	str / 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`	str	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`	str	The message title.
`*texts`	str	Optional texts to print (one per line).
`highlight`	str	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	str	The formatted traceback. Can be printed or raised by custom exception.

`class` `MarkdownRenderer`

Helper to create Markdown-formatted content. Will store the blocks added to the
Markdown document in order.

from wasabi import MarkdownRenderer

md = MarkdownRenderer()
md.add(md.title(1, "Hello world"))
md.add("This is a paragraph")
print(md.text)

`method` `MarkdownRenderer.init`

Initialize a Markdown renderer.

from wasabi import MarkdownRenderer

md = MarkdownRenderer()

Argument	Type	Description	Default
`no_emoji`	bool	Don't include emoji in titles.	`False`
RETURNS	`MarkdownRenderer`	The renderer.

`method` `MarkdownRenderer.add`

Add a block to the Markdown document.

from wasabi import MarkdownRenderer

md = MarkdownRenderer()
md.add("This is a paragraph")

Argument	Type	Description	Default
`text`	str	The content to add.

`property` `MarkdownRenderer.text`

The rendered Markdown document.

md = MarkdownRenderer()
md.add("This is a paragraph")
print(md.text)

Argument	Type	Description	Default
RETURNS	str	The document as a single string.

`method` `MarkdownRenderer.table`

Create a Markdown-formatted table.

md = MarkdownRenderer()
table = md.table([("a", "b"), ("c", "d")], ["Column 1", "Column 2"])
md.add(table)

| Column 1 | Column 2 |
| --- | --- |
| a | b |
| c | d |

Argument	Type	Description	Default
`data`	Iterable[Iterable[str]]	The body, one iterable per row, containig an interable of column contents.
`header`	Iterable[str]	The column names.
`aligns`	Iterable[str]	Columns alignments in order. `"l"` (left, default), `"r"` (right) or `"c"` (center).	`None`
RETURNS	str	The table.

`method` `MarkdownRenderer.title`

Create a Markdown-formatted heading.

md = MarkdownRenderer()
md.add(md.title(1, "Hello world"))
md.add(md.title(2, "Subheading", "💖"))

# Hello world

## 💖 Subheading

Argument	Type	Description	Default
`level`	int	The heading level, e.g. `3` for `###`.
`text`	str	The heading text.
`emoji`	str	Optional emoji to show before heading.	`None`
RETURNS	str	The rendered title.

`method` `MarkdownRenderer.list`

Create a Markdown-formatted non-nested list.

md = MarkdownRenderer()
md.add(md.list(["item", "other item"]))
md.add(md.list(["first item", "second item"], numbered=True))

- item
- other item

1. first item
2. second item

Argument	Type	Description	Default
`items`	Iterable[str]	The list items.
`numbered`	bool	Whether to use a numbered list.	`False`
RETURNS	str	The rendered list.

`method` `MarkdownRenderer.link`

Create a Markdown-formatted link.

md = MarkdownRenderer()
md.add(md.link("Google", "https://google.com"))

[Google](https://google.com)

Argument	Type	Description
`text`	str	The link text.
`url`	str	The link URL.
RETURNS	str	The rendered link.

`method` `MarkdownRenderer.code_block`

Create a Markdown-formatted code block.

md = MarkdownRenderer()
md.add(md.code_block("import spacy", "python"))

```python
import spacy
```

Argument	Type	Description	Default
`text`	str	The code text.
`lang`	str	Optional code language.	`""`
RETURNS	str	The rendered code block.

`method` `MarkdownRenderer.code`, `MarkdownRenderer.bold`, `MarkdownRenderer.italic`

Create a Markdown-formatted text.

md = MarkdownRenderer()
md.add(md.code("import spacy"))
md.add(md.bold("Hello!"))
md.add(md.italic("Emphasis"))

`import spacy`

**Hello!**

_Emphasis_

Utilities

`function` `color`

from wasabi import color

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

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

`function` `wrap`

from wasabi import wrap

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

Argument	Type	Description	Default
`text`	str	The text to wrap.	-
`wrap_max`	int	Maximum line width, including indentation.	`80`
`indent`	int	Number of spaces used for indentation.	`4`
RETURNS	str	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`	str	The first string to diff.
`b`	str	The second string to diff.
`fg`	str / 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	str	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

Dependencies of wasabi (2).
Dependency	Optional
colorama	false
typing-extensions	false

Package profile

wasabi

Releases

Release table

PyPI Downloads

Dependencies

Details

Project URLs

Dependencies

Package description