Giter VIP home page Giter VIP logo

wasabi's Introduction

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+.

tests PyPi conda GitHub Code style: black

πŸ’¬ 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 Default
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

wasabi's People

Contributors

adrianeboyd avatar honnibal avatar ines avatar justindujardin avatar kabirkhan avatar kennethenevoldsen avatar ljvmiranda921 avatar njsmith avatar patjouk avatar polm avatar richardpaulhudson avatar svlandeg avatar thetwitchy avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

wasabi's Issues

Support for `debug()` under `Printer`?

Currently if I wish to print debug messages, the usage is something like this:

from wasabi import msg
msg.info('Hello', show=is_verbose)

But now is_verbose is scattered everywhere in code. I'd like to propose a class-level variable for Printer that sets the is_verbose flag once with the Printer and a msg.debug() function that will print based on this flag. Essentially a flag for log level is what I am looking for.

Proposed Usage:

from wasabi import Printer
msg = Printer(is_verbose=True)
msg.debug('Hello') # This prints to console
msg = Printer(is_verbose=False)
msg.debug('Hello') # This does not print to console

Let me know if this usage makes sense and I can contribute a PR or maybe there is an existing way to achieve this functionality that I am probably now aware of? :)

Removing "Loading" text after loading?

Hello,

I couldn't find anything in the docs about how to get rid of the "Loading..." text fully after the loading is "finished"? I tried it in a Jupyter Notebook and this is the result:

image

Any suggestions?

Print to stderr instead of stdout

As of now, wasabi just calls print(), which by default prints to the stdout. In my opinion, this is wrong, as stdout (in the Unix ideology) should be used to output the result of the program (for eventual piping), while stderr should be used for warnings and errors.

I propose adding a "stream" parameter to Printer.__init__(), which by default should be set to sys.stderr. You can then use it inside the print() call.

If you're low on free time, I can implement this, too :)

Adding custom COLORS values to traceback

Hi @ines

Lovely tool!

In Printer I can provide my own colors dictionary but that is not an option in TracebackPrinter. The colors being used there are defined by wasabi.COLORS. I need to change it since Pycharm only supports certain ANSI colors. Is that possible?

Btw. do you combine wasabi with logging module? I was considering adding a WasabiStreamHandler but maybe it already exists?

Windows support

It seems that colors do not work in Windows.
In an ipython session:
image
In a python script:
image

Also, the following example, that is stated in the readme, does not work, at least in my Windows box.

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

It should be wrapped under the __name__ == "__main__" like this:

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

Otherwise you will get a RuntimeError:

An attempt has been made to start a new process before the
        current process has finished its bootstrapping phase.

        This probably means that you are not using fork to start your
        child processes and you have forgotten to use the proper idiom
        in the main module:

            if __name__ == '__main__':
                freeze_support()
                ...

        The "freeze_support()" line can be omitted if the program
        is not going to be frozen to produce an executable.

Runtime error when calling msg.loading("..")

I run into the following error when trying to run a simple sample snippet using msg.loading with wasabi

RuntimeError: 
        An attempt has been made to start a new process before the
        current process has finished its bootstrapping phase.

        This probably means that you are not using fork to start your
        child processes and you have forgotten to use the proper idiom
        in the main module:

            if __name__ == '__main__':
                freeze_support()
                ...

        The "freeze_support()" line can be omitted if the program
        is not going to be frozen to produce an executable.

Here's the code snippet being executed:

from time import sleep
from wasabi import msg, Printer

msg = Printer()
msg.good("Starting")
msg.warn("Warning")
with msg.loading("Loading.."):
    sleep(3)
msg.good("done")

Python Version Information:

Python 3.8.5 (default, Sep 27 2020, 15:45:15) 
[Clang 9.0.0 (clang-900.0.39.2)] on darwin

wasabi version: 0.8.2

Would be happy to provide any additional info on this. Thanks! :)

Option to adjust default text wrap length

The wrap function takes a wrap_max argument that controls the maximum line width. When I'm using the typical functions for printing formatted messages like good, fail, warn, and info, they are calling wrap internally, and there's no easy way to adjust the line width. The Printer class does have a line_max argument, but it's only used for dividers.

Can there be a way to adjust the default wrap_max value, either by configuring a Printer instance or via an environment variable? I'm using wasabi in my spaCy related projects, and the short 80 character output has been really limiting some of my logging output.

RuntimeError with context manager and no_print=True

First of all, thanks for wasabi! It's really easy to use and most importantly, looks cool.

I just ran into an error using the context manager and no_print=True. I have a verbose option in my code that I'd like to use to control whether wasabi prints loading messages, but I've encountered an error. If I change the context manager example in the docs from msg = Printer() to msg = Printer(no_print=True), I get a RuntimeError. Full code, output, and error below:

from wasabi import Printer
import time

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

Nothing for 5 seconds, then the following:

β ™ Loading...
---------------------------------------------------------------------------
RuntimeError                              Traceback (most recent call last)
<ipython-input-20-455695c9f881> in <module>()
      1 with msg.loading("Loading..."):
      2     # Do something here that takes longer
----> 3     time.sleep(5)
      4 msg.good("Successfully loaded something!")

~/anaconda3/lib/python3.6/contextlib.py in __exit__(self, type, value, traceback)
     90                 return False
     91             else:
---> 92                 raise RuntimeError("generator didn't stop")
     93         else:
     94             if value is None:

RuntimeError: generator didn't stop

β § Loading...

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    πŸ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. πŸ“ŠπŸ“ˆπŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❀️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.