# 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](https://spacy.io), [Thinc](https://github.com/explosion/thinc) and
[Prodigy](https://prodi.gy). 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+.
[](https://github.com/explosion/wasabi/actions/workflows/tests.yml)
[](https://pypi.python.org/pypi/wasabi)
[](https://anaconda.org/conda-forge/wasabi)
[](https://github.com/ines/wasabi)
[](https://github.com/ambv/black)
<img width="609" src="https://user-images.githubusercontent.com/13643239/48663861-8c9ea000-ea96-11e8-8b04-d120c52276a8.png">
## π¬ 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`](https://pypi.org/project/colored/),
[`crayons`](https://github.com/kennethreitz/crayons),
[`colorful`](https://github.com/timofurrer/colorful),
[`tabulate`](https://bitbucket.org/astanin/python-tabulate),
[`console`](https://github.com/mixmastamyk/console) or
[`py-term`](https://github.com/gravmatt/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
```bash
pip install wasabi
```
## π API
### <kbd>function</kbd> `msg`
An instance of `Printer`, initialized with the default config. Useful as a quick
shortcut if you don't need to customize initialization.
```python
from wasabi import msg
msg.good("Success!")
```
### <kbd>class</kbd> `Printer`
#### <kbd>method</kbd> `Printer.__init__`
```python
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. | - |
#### <kbd>method</kbd> `Printer.text`
```python
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` |
#### <kbd>method</kbd> `Printer.good`, `Printer.fail`, `Printer.warn`, `Printer.info`
Print special formatted messages.
```python
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` |
#### <kbd>method</kbd> `Printer.divider`
Print a formatted divider.
```python
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` |
#### <kbd>contextmanager</kbd> `Printer.loading`
```python
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..."` |
#### <kbd>method</kbd> `Printer.table`, `Printer.row`
See [Tables](#tables).
#### <kbd>property</kbd> `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"
```python
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
#### <kbd>function</kbd> `table`
Lightweight helper to format tabular data.
```python
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. | |
#### <kbd>function</kbd> `row`
```python
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. | |
### <kbd>class</kbd> `TracebackPrinter`
Helper to output custom formatted tracebacks and error messages. Currently used
in [Thinc](https://github.com/explosion/thinc).
#### <kbd>method</kbd> `TracebackPrinter.__init__`
Initialize a traceback printer.
```python
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. | |
#### <kbd>method</kbd> `TracebackPrinter.__call__`
Output custom formatted tracebacks and errors.
```python
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. | |
### <kbd>class</kbd> `MarkdownRenderer`
Helper to create Markdown-formatted content. Will store the blocks added to the
Markdown document in order.
```python
from wasabi import MarkdownRenderer
md = MarkdownRenderer()
md.add(md.title(1, "Hello world"))
md.add("This is a paragraph")
print(md.text)
```
### <kbd>method</kbd> `MarkdownRenderer.__init__`
Initialize a Markdown renderer.
```python
from wasabi import MarkdownRenderer
md = MarkdownRenderer()
```
| Argument | Type | Description | Default |
| ----------- | ------------------ | ------------------------------ | ------- |
| `no_emoji` | bool | Don't include emoji in titles. | `False` |
| **RETURNS** | `MarkdownRenderer` | The renderer. |
### <kbd>method</kbd> `MarkdownRenderer.add`
Add a block to the Markdown document.
```python
from wasabi import MarkdownRenderer
md = MarkdownRenderer()
md.add("This is a paragraph")
```
| Argument | Type | Description | Default |
| -------- | ---- | ------------------- | ------- |
| `text` | str | The content to add. | |
### <kbd>property</kbd> `MarkdownRenderer.text`
The rendered Markdown document.
```python
md = MarkdownRenderer()
md.add("This is a paragraph")
print(md.text)
```
| Argument | Type | Description | Default |
| ----------- | ---- | -------------------------------- | ------- |
| **RETURNS** | str | The document as a single string. | |
### <kbd>method</kbd> `MarkdownRenderer.table`
Create a Markdown-formatted table.
```python
md = MarkdownRenderer()
table = md.table([("a", "b"), ("c", "d")], ["Column 1", "Column 2"])
md.add(table)
```
<!-- prettier-ignore -->
```markdown
| 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. | |
### <kbd>method</kbd> `MarkdownRenderer.title`
Create a Markdown-formatted heading.
```python
md = MarkdownRenderer()
md.add(md.title(1, "Hello world"))
md.add(md.title(2, "Subheading", "π"))
```
```markdown
# 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. | |
### <kbd>method</kbd> `MarkdownRenderer.list`
Create a Markdown-formatted non-nested list.
```python
md = MarkdownRenderer()
md.add(md.list(["item", "other item"]))
md.add(md.list(["first item", "second item"], numbered=True))
```
```markdown
- 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. | |
### <kbd>method</kbd> `MarkdownRenderer.link`
Create a Markdown-formatted link.
```python
md = MarkdownRenderer()
md.add(md.link("Google", "https://google.com"))
```
```markdown
[Google](https://google.com)
```
| Argument | Type | Description | Default |
| ----------- | ---- | ------------------ | ------- |
| `text` | str | The link text. | |
| `url` | str | The link URL. | |
| **RETURNS** | str | The rendered link. | |
### <kbd>method</kbd> `MarkdownRenderer.code_block`
Create a Markdown-formatted code block.
```python
md = MarkdownRenderer()
md.add(md.code_block("import spacy", "python"))
```
````markdown
```python
import spacy
```
````
| Argument | Type | Description | Default |
| ----------- | ---- | ------------------------ | ------- |
| `text` | str | The code text. | |
| `lang` | str | Optional code language. | `""` |
| **RETURNS** | str | The rendered code block. | |
### <kbd>method</kbd> `MarkdownRenderer.code`, `MarkdownRenderer.bold`, `MarkdownRenderer.italic`
Create a Markdown-formatted text.
```python
md = MarkdownRenderer()
md.add(md.code("import spacy"))
md.add(md.bold("Hello!"))
md.add(md.italic("Emphasis"))
```
```markdown
`import spacy`
**Hello!**
_Emphasis_
```
### Utilities
#### <kbd>function</kbd> `color`
```python
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. | |
#### <kbd>function</kbd> `wrap`
```python
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. | |
#### <kbd>function</kbd> `diff_strings`
```python
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`](/wasabi/tests).
```bash
pip install pytest
cd wasabi
python -m pytest wasabi
```
Raw data
{
"_id": null,
"home_page": "https://github.com/explosion/wasabi",
"name": "wasabi",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "",
"author": "Explosion",
"author_email": "contact@explosion.ai",
"download_url": "https://files.pythonhosted.org/packages/3e/09/bbd7e880b56e825d5859a58adb1bd1feb45b604218706057ca1e3278fa62/wasabi-1.1.2.tar.gz",
"platform": null,
"description": "# wasabi: A lightweight console printing and formatting toolkit\n\nOver the years, I've written countless implementations of coloring and\nformatting utilities to output messages in our libraries like\n[spaCy](https://spacy.io), [Thinc](https://github.com/explosion/thinc) and\n[Prodigy](https://prodi.gy). While there are many other great open-source\noptions, I've always ended up wanting something slightly different or slightly\ncustom.\n\nThis package is still a work in progress and aims to bundle those utilities in a\nstandardised way so they can be shared across our other projects. It's super\nlightweight, has zero dependencies and works with Python 3.6+.\n\n[](https://github.com/explosion/wasabi/actions/workflows/tests.yml)\n[](https://pypi.python.org/pypi/wasabi)\n[](https://anaconda.org/conda-forge/wasabi)\n[](https://github.com/ines/wasabi)\n[](https://github.com/ambv/black)\n\n<img width=\"609\" src=\"https://user-images.githubusercontent.com/13643239/48663861-8c9ea000-ea96-11e8-8b04-d120c52276a8.png\">\n\n## \ud83d\udcac FAQ\n\n### Are you going to add more features?\n\nYes, there's still a few of helpers and features to port over. However, the new\nfeatures will be heavily biased by what we (think we) need. I always appreciate\npull requests to improve the existing functionality \u2013 but I want to keep this\nlibrary as simple, lightweight and specific as possible.\n\n### Can I use this for my projects?\n\nSure, if you like it, feel free to adopt it! Just keep in mind that the package\nis very specific and not intended to be a full-featured and fully customisable\nformatting library. If that's what you're looking for, you might want to try\nother packages \u2013 for example, [`colored`](https://pypi.org/project/colored/),\n[`crayons`](https://github.com/kennethreitz/crayons),\n[`colorful`](https://github.com/timofurrer/colorful),\n[`tabulate`](https://bitbucket.org/astanin/python-tabulate),\n[`console`](https://github.com/mixmastamyk/console) or\n[`py-term`](https://github.com/gravmatt/py-term), to name a few.\n\n### Why `wasabi`?\n\nI was looking for a short and descriptive name, but everything was already\ntaken. So I ended up naming this package after one of my rats, Wasabi. \ud83d\udc00\n\n## \u231b\ufe0f Installation\n\n```bash\npip install wasabi\n```\n\n## \ud83c\udf9b API\n\n### <kbd>function</kbd> `msg`\n\nAn instance of `Printer`, initialized with the default config. Useful as a quick\nshortcut if you don't need to customize initialization.\n\n```python\nfrom wasabi import msg\n\nmsg.good(\"Success!\")\n```\n\n### <kbd>class</kbd> `Printer`\n\n#### <kbd>method</kbd> `Printer.__init__`\n\n```python\nfrom wasabi import Printer\n\nmsg = Printer()\n```\n\n| Argument | Type | Description | Default |\n| ----------------- | --------- | ------------------------------------------------------------- | ------------- |\n| `pretty` | bool | Pretty-print output with colors and icons. | `True` |\n| `no_print` | bool | Don't actually print, just return. | `False` |\n| `colors` | dict | Add or overwrite color values, names mapped to `0`-`256`. | `None` |\n| `icons` | dict | Add or overwrite icon. Name mapped to unicode. | `None` |\n| `line_max` | int | Maximum line length (for divider). | `80` |\n| `animation` | str | Steps of loading animation for `Printer.loading`. | `\"\u2819\u2839\u2838\u283c\u2834\u2826\u2827\u2807\u280f\"` |\n| `animation_ascii` | str | Alternative animation for ASCII terminals. | `\"\\|/-\\\\\"` |\n| `hide_animation` | bool | Don't display animation, e.g. for logs. | `False` |\n| `ignore_warnings` | bool | Don't output messages of type `MESSAGE.WARN`. | `False` |\n| `env_prefix` | str | Prefix for environment variables, e.g. `WASABI_LOG_FRIENDLY`. | `\"WASABI\"` |\n| `timestamp` | bool | Add timestamp before output. | `False` |\n| **RETURNS** | `Printer` | The initialized printer. | - |\n\n#### <kbd>method</kbd> `Printer.text`\n\n```python\nmsg = Printer()\nmsg.text(\"Hello world!\")\n```\n\n| Argument | Type | Description | Default |\n| ---------- | -------------- | ---------------------------------------------------------------------------------------------------------------------- | ------- |\n| `title` | str | The main text to print. | `\"\"` |\n| `text` | str | Optional additional text to print. | `\"\"` |\n| `color` | \u00a0unicode / int | Color name or value. | `None` |\n| `icon` | str | Name of icon to add. | `None` |\n| `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` |\n| `spaced` | bool | Whether to add newlines around the output. | `False` |\n| `no_print` | bool | Don't actually print, just return. Overwrites global setting. | `False` |\n| `exits` | int | If set, perform a system exit with the given code after printing. | `None` |\n\n#### <kbd>method</kbd> `Printer.good`, `Printer.fail`, `Printer.warn`, `Printer.info`\n\nPrint special formatted messages.\n\n```python\nmsg = Printer()\nmsg.good(\"Success\")\nmsg.fail(\"Error\")\nmsg.warn(\"Warning\")\nmsg.info(\"Info\")\n```\n\n| Argument | Type | Description | Default |\n| -------- | ---- | ---------------------------------------------------------------------------------------------------------------------- | ------- |\n| `title` | str | The main text to print. | `\"\"` |\n| `text` | str | Optional additional text to print. | `\"\"` |\n| `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` |\n| `exits` | int | If set, perform a system exit with the given code after printing. | `None` |\n\n#### <kbd>method</kbd> `Printer.divider`\n\nPrint a formatted divider.\n\n```python\nmsg = Printer()\nmsg.divider(\"Heading\")\n```\n\n| Argument | Type | Description | Default |\n| -------- | ---- | ---------------------------------------------------------------------------------------------------------------------- | ------- |\n| `text` | str | Headline text. If empty, only the line is printed. | `\"\"` |\n| `char` | str | Single line character to repeat. | `\"=\"` |\n| `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` |\n| `icon` | str | Optional icon to use with title. | `None` |\n\n#### <kbd>contextmanager</kbd> `Printer.loading`\n\n```python\nmsg = Printer()\nwith msg.loading(\"Loading...\"):\n # Do something here that takes longer\n time.sleep(10)\nmsg.good(\"Successfully loaded something!\")\n```\n\n| Argument | Type | Description | Default |\n| -------- | ---- | ---------------------------------- | -------------- |\n| `text` | str | The text to display while loading. | `\"Loading...\"` |\n\n#### <kbd>method</kbd> `Printer.table`, `Printer.row`\n\nSee [Tables](#tables).\n\n#### <kbd>property</kbd> `Printer.counts`\n\nGet the counts of how often the special printers were fired, e.g.\n`MESSAGES.GOOD`. Can be used to print an overview like \"X warnings\"\n\n```python\nmsg = Printer()\nmsg.good(\"Success\")\nmsg.fail(\"Error\")\nmsg.warn(\"Error\")\n\nprint(msg.counts)\n# Counter({'good': 1, 'fail': 2, 'warn': 0, 'info': 0})\n```\n\n| Argument | Type | Description |\n| ----------- | --------- | ---------------------------------------------------- |\n| **RETURNS** | `Counter` | The counts for the individual special message types. |\n\n### Tables\n\n#### <kbd>function</kbd> `table`\n\nLightweight helper to format tabular data.\n\n```python\nfrom wasabi import table\n\ndata = [(\"a1\", \"a2\", \"a3\"), (\"b1\", \"b2\", \"b3\")]\nheader = (\"Column 1\", \"Column 2\", \"Column 3\")\nwidths = (8, 9, 10)\naligns = (\"r\", \"c\", \"l\")\nformatted = table(data, header=header, divider=True, widths=widths, aligns=aligns)\n```\n\n```\nColumn 1 Column 2 Column 3\n-------- --------- ----------\n a1 a2 a3\n b1 b2 b3\n```\n\n| Argument | Type | Description | Default |\n| -------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ---------- |\n| `data` | iterable / dict | The data to render. Either a list of lists (one per row) or a dict for two-column tables. | |\n| `header` | iterable | Optional header columns. | `None` |\n| `footer` | iterable | Optional footer columns. | `None` |\n| `divider` | bool | Show a divider line between header/footer and body. | `False` |\n| `widths` | iterable / `\"auto\"` | Column widths in order. If `\"auto\"`, widths will be calculated automatically based on the largest value. | `\"auto\"` |\n| `max_col` | int | Maximum column width. | `30` |\n| `spacing` | int | Number of spaces between columns. | `3` |\n| `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` |\n| `multiline` | bool | If a cell value is a list of a tuple, render it on multiple lines, with one value per line. | `False` |\n| `env_prefix` | unicode | Prefix for environment variables, e.g. WASABI_LOG_FRIENDLY. | `\"WASABI\"` |\n| `color_values` | dict | Add or overwrite color values, name mapped to value. | `None` |\n| `fg_colors` | iterable | Foreground colors, one per column. None can be specified for individual columns to retain the default background color. | `None` |\n| `bg_colors` | iterable | Background colors, one per column. None can be specified for individual columns to retain the default background color. | `None` |\n| **RETURNS** | str | The formatted table. | |\n\n#### <kbd>function</kbd> `row`\n\n```python\nfrom wasabi import row\n\ndata = (\"a1\", \"a2\", \"a3\")\nformatted = row(data)\n```\n\n```\na1 a2 a3\n```\n\n| Argument | Type | Description | Default |\n| ------------ | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |\n| `data` | iterable | The individual columns to format. | |\n| `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\"` |\n| `spacing` | int | Number of spaces between columns. | `3` |\n| `aligns` | list | Columns alignments in order. `\"l\"` (left), `\"r\"` (right) or `\"c\"` (center). | `None` |\n| `env_prefix` | unicode | Prefix for environment variables, e.g. WASABI_LOG_FRIENDLY. | `\"WASABI\"` |\n| `fg_colors` | list | Foreground colors for the columns, in order. None can be specified for individual columns to retain the default foreground color. | `None` |\n| `bg_colors` | list | Background colors for the columns, in order. None can be specified for individual columns to retain the default background color. | `None` |\n| **RETURNS** | str | The formatted row. | |\n\n### <kbd>class</kbd> `TracebackPrinter`\n\nHelper to output custom formatted tracebacks and error messages. Currently used\nin [Thinc](https://github.com/explosion/thinc).\n\n#### <kbd>method</kbd> `TracebackPrinter.__init__`\n\nInitialize a traceback printer.\n\n```python\nfrom wasabi import TracebackPrinter\n\ntb = TracebackPrinter(tb_base=\"thinc\", tb_exclude=(\"check.py\",))\n```\n\n| Argument | Type | Description | Default |\n| ----------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |\n| `color_error` | str / int | Color name or code for errors (passed to `color` helper). | `\"red\"` |\n| `color_tb` | str / int | Color name or code for traceback headline (passed to `color` helper). | `\"blue\"` |\n| `color_highlight` | str / int | Color name or code for highlighted text (passed to `color` helper). | `\"yellow\"` |\n| `indent` | int | Number of spaces to use for indentation. | `2` |\n| `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` |\n| `tb_exclude` | tuple | List of filenames to exclude from traceback. | `tuple()` |\n| **RETURNS** | `TracebackPrinter` | The traceback printer. | |\n\n#### <kbd>method</kbd> `TracebackPrinter.__call__`\n\nOutput custom formatted tracebacks and errors.\n\n```python\nfrom wasabi import TracebackPrinter\nimport traceback\n\ntb = TracebackPrinter(tb_base=\"thinc\", tb_exclude=(\"check.py\",))\n\nerror = tb(\"Some error\", \"Error description\", highlight=\"kwargs\", tb=traceback.extract_stack())\nraise ValueError(error)\n```\n\n```\n Some error\n Some error description\n\n Traceback:\n \u251c\u2500 <lambda> [61] in .env/lib/python3.6/site-packages/pluggy/manager.py\n \u251c\u2500\u2500\u2500 _multicall [187] in .env/lib/python3.6/site-packages/pluggy/callers.py\n \u2514\u2500\u2500\u2500\u2500\u2500 pytest_fixture_setup [969] in .env/lib/python3.6/site-packages/_pytest/fixtures.py\n >>> result = call_fixture_func(fixturefunc, request, kwargs)\n```\n\n| Argument | Type | Description | Default |\n| ----------- | -------- | ------------------------------------------------------------------------------------------ | ------- |\n| `title` | str | The message title. | |\n| `*texts` | str | Optional texts to print (one per line). | |\n| `highlight` | str | Optional sequence to highlight in the traceback, e.g. the bad value that caused the error. | `False` |\n| `tb` | iterable | The traceback, e.g. generated by `traceback.extract_stack()`. | `None` |\n| **RETURNS** | str | The formatted traceback. Can be printed or raised by custom exception. | |\n\n### <kbd>class</kbd> `MarkdownRenderer`\n\nHelper to create Markdown-formatted content. Will store the blocks added to the\nMarkdown document in order.\n\n```python\nfrom wasabi import MarkdownRenderer\n\nmd = MarkdownRenderer()\nmd.add(md.title(1, \"Hello world\"))\nmd.add(\"This is a paragraph\")\nprint(md.text)\n```\n\n### <kbd>method</kbd> `MarkdownRenderer.__init__`\n\nInitialize a Markdown renderer.\n\n```python\nfrom wasabi import MarkdownRenderer\n\nmd = MarkdownRenderer()\n```\n\n| Argument | Type | Description | Default |\n| ----------- | ------------------ | ------------------------------ | ------- |\n| `no_emoji` | bool | Don't include emoji in titles. | `False` |\n| **RETURNS** | `MarkdownRenderer` | The renderer. |\n\n### <kbd>method</kbd> `MarkdownRenderer.add`\n\nAdd a block to the Markdown document.\n\n```python\nfrom wasabi import MarkdownRenderer\n\nmd = MarkdownRenderer()\nmd.add(\"This is a paragraph\")\n```\n\n| Argument | Type | Description | Default |\n| -------- | ---- | ------------------- | ------- |\n| `text` | str | The content to add. | |\n\n### <kbd>property</kbd> `MarkdownRenderer.text`\n\nThe rendered Markdown document.\n\n```python\nmd = MarkdownRenderer()\nmd.add(\"This is a paragraph\")\nprint(md.text)\n```\n\n| Argument | Type | Description | Default |\n| ----------- | ---- | -------------------------------- | ------- |\n| **RETURNS** | str | The document as a single string. | |\n\n### <kbd>method</kbd> `MarkdownRenderer.table`\n\nCreate a Markdown-formatted table.\n\n```python\nmd = MarkdownRenderer()\ntable = md.table([(\"a\", \"b\"), (\"c\", \"d\")], [\"Column 1\", \"Column 2\"])\nmd.add(table)\n```\n\n<!-- prettier-ignore -->\n```markdown\n| Column 1 | Column 2 |\n| --- | --- |\n| a | b |\n| c | d |\n```\n\n| Argument | Type | Description | Default |\n| ----------- | ----------------------- | ------------------------------------------------------------------------------------ | ------- |\n| `data` | Iterable[Iterable[str]] | The body, one iterable per row, containig an interable of column contents. | |\n| `header` | Iterable[str] | The column names. | |\n| `aligns` | Iterable[str] | Columns alignments in order. `\"l\"` (left, default), `\"r\"` (right) or `\"c\"` (center). | `None` |\n| **RETURNS** | str | The table. | |\n\n### <kbd>method</kbd> `MarkdownRenderer.title`\n\nCreate a Markdown-formatted heading.\n\n```python\nmd = MarkdownRenderer()\nmd.add(md.title(1, \"Hello world\"))\nmd.add(md.title(2, \"Subheading\", \"\ud83d\udc96\"))\n```\n\n```markdown\n# Hello world\n\n## \ud83d\udc96 Subheading\n```\n\n| Argument | Type | Description | Default |\n| ----------- | ---- | -------------------------------------- | ------- |\n| `level` | int | The heading level, e.g. `3` for `###`. | |\n| `text` | str | The heading text. | |\n| `emoji` | str | Optional emoji to show before heading. | `None` |\n| **RETURNS** | str | The rendered title. | |\n\n### <kbd>method</kbd> `MarkdownRenderer.list`\n\nCreate a Markdown-formatted non-nested list.\n\n```python\nmd = MarkdownRenderer()\nmd.add(md.list([\"item\", \"other item\"]))\nmd.add(md.list([\"first item\", \"second item\"], numbered=True))\n```\n\n```markdown\n- item\n- other item\n\n1. first item\n2. second item\n```\n\n| Argument | Type | Description | Default |\n| ----------- | ------------- | ------------------------------- | ------- |\n| `items` | Iterable[str] | The list items. | |\n| `numbered` | bool | Whether to use a numbered list. | `False` |\n| **RETURNS** | str | The rendered list. | |\n\n### <kbd>method</kbd> `MarkdownRenderer.link`\n\nCreate a Markdown-formatted link.\n\n```python\nmd = MarkdownRenderer()\nmd.add(md.link(\"Google\", \"https://google.com\"))\n```\n\n```markdown\n[Google](https://google.com)\n```\n\n| Argument | Type | Description | Default |\n| ----------- | ---- | ------------------ | ------- |\n| `text` | str | The link text. | |\n| `url` | str | The link URL. | |\n| **RETURNS** | str | The rendered link. | |\n\n### <kbd>method</kbd> `MarkdownRenderer.code_block`\n\nCreate a Markdown-formatted code block.\n\n```python\nmd = MarkdownRenderer()\nmd.add(md.code_block(\"import spacy\", \"python\"))\n```\n\n````markdown\n```python\nimport spacy\n```\n````\n\n| Argument | Type | Description | Default |\n| ----------- | ---- | ------------------------ | ------- |\n| `text` | str | The code text. | |\n| `lang` | str | Optional code language. | `\"\"` |\n| **RETURNS** | str | The rendered code block. | |\n\n### <kbd>method</kbd> `MarkdownRenderer.code`, `MarkdownRenderer.bold`, `MarkdownRenderer.italic`\n\nCreate a Markdown-formatted text.\n\n```python\nmd = MarkdownRenderer()\nmd.add(md.code(\"import spacy\"))\nmd.add(md.bold(\"Hello!\"))\nmd.add(md.italic(\"Emphasis\"))\n```\n\n```markdown\n`import spacy`\n\n**Hello!**\n\n_Emphasis_\n```\n\n### Utilities\n\n#### <kbd>function</kbd> `color`\n\n```python\nfrom wasabi import color\n\nformatted = color(\"This is a text\", fg=\"white\", bg=\"green\", bold=True)\n```\n\n| Argument | Type | Description | Default |\n| ----------- | --------- | --------------------------------------------- | ------- |\n| `text` | str | The text to be formatted. | - |\n| `fg` | str / int | Foreground color. String name or `0` - `256`. | `None` |\n| `bg` | str / int | Background color. String name or `0` - `256`. | `None` |\n| `bold` | bool | Format the text in bold. | `False` |\n| `underline` | bool | Format the text by underlining. | `False` |\n| **RETURNS** | str | The formatted string. | |\n\n#### <kbd>function</kbd> `wrap`\n\n```python\nfrom wasabi import wrap\n\nwrapped = wrap(\"Hello world, this is a text.\", indent=2)\n```\n\n| Argument | Type | Description | Default |\n| ----------- | ---- | ------------------------------------------ | ------- |\n| `text` | str | The text to wrap. | - |\n| `wrap_max` | int | Maximum line width, including indentation. | `80` |\n| `indent` | int | Number of spaces used for indentation. | `4` |\n| **RETURNS** | str | The wrapped text with line breaks. | |\n\n#### <kbd>function</kbd> `diff_strings`\n\n```python\nfrom wasabi import diff_strings\n\ndiff = diff_strings(\"hello world!\", \"helloo world\")\n```\n\n| Argument | Type | Description | Default |\n| ----------- | --------- | ---------------------------------------------------------------------------- | ------------------ |\n| `a` | str | The first string to diff. |\n| `b` | str | The second string to diff. |\n| `fg` | str / int | Foreground color. String name or `0` - `256`. | `\"black\"` |\n| `bg` | tuple | Background colors as `(insert, delete)` tuple of string name or `0` - `256`. | `(\"green\", \"red\")` |\n| **RETURNS** | str | The formatted diff. | |\n\n### Environment variables\n\nWasabi also respects the following environment variables. The prefix can be\ncustomised on the `Printer` via the `env_prefix` argument. For example, setting\n`env_prefix=\"SPACY\"` will expect the environment variable `SPACY_LOG_FRIENDLY`.\n\n| Name | Description |\n| ---------------------- | ------------------------------------------------------ |\n| `ANSI_COLORS_DISABLED` | Disable colors. |\n| `WASABI_LOG_FRIENDLY` | Make output nicer for logs (no colors, no animations). |\n| `WASABI_NO_PRETTY` | Disable pretty printing, e.g. colors and icons. |\n\n## \ud83d\udd14 Run tests\n\nFork or clone the repo, make sure you have `pytest` installed and then run it on\nthe package directory. The tests are located in\n[`/wasabi/tests`](/wasabi/tests).\n\n```bash\npip install pytest\ncd wasabi\npython -m pytest wasabi\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A lightweight console printing and formatting toolkit",
"version": "1.1.2",
"project_urls": {
"Homepage": "https://github.com/explosion/wasabi"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8f6926cbf0bad11703241cb84d5324d868097f7a8faf2f1888354dac8883f3fc",
"md5": "43f90535a5ea69a58276356aa6a65d3f",
"sha256": "0a3f933c4bf0ed3f93071132c1b87549733256d6c8de6473c5f7ed2e171b5cf9"
},
"downloads": -1,
"filename": "wasabi-1.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "43f90535a5ea69a58276356aa6a65d3f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 27762,
"upload_time": "2023-06-07T07:35:06",
"upload_time_iso_8601": "2023-06-07T07:35:06.142123Z",
"url": "https://files.pythonhosted.org/packages/8f/69/26cbf0bad11703241cb84d5324d868097f7a8faf2f1888354dac8883f3fc/wasabi-1.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3e09bbd7e880b56e825d5859a58adb1bd1feb45b604218706057ca1e3278fa62",
"md5": "dd9c1e5d01a49611ff39d4bd299d535a",
"sha256": "1aaef3aceaa32edb9c91330d29d3936c0c39fdb965743549c173cb54b16c30b5"
},
"downloads": -1,
"filename": "wasabi-1.1.2.tar.gz",
"has_sig": false,
"md5_digest": "dd9c1e5d01a49611ff39d4bd299d535a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 30158,
"upload_time": "2023-06-07T07:35:08",
"upload_time_iso_8601": "2023-06-07T07:35:08.068212Z",
"url": "https://files.pythonhosted.org/packages/3e/09/bbd7e880b56e825d5859a58adb1bd1feb45b604218706057ca1e3278fa62/wasabi-1.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-07 07:35:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "explosion",
"github_project": "wasabi",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "typing_extensions",
"specs": [
[
">=",
"3.7.4.1"
],
[
"<",
"4.5.0"
]
]
},
{
"name": "pytest",
"specs": []
},
{
"name": "mypy",
"specs": []
},
{
"name": "types-colorama",
"specs": []
},
{
"name": "nbconvert",
"specs": []
},
{
"name": "ipykernel",
"specs": []
}
],
"lcname": "wasabi"
}
JSON
