{"author":"Explosion","author_email":"contact@explosion.ai","bugtrack_url":null,"classifiers":[],"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[![tests](https://github.com/explosion/wasabi/actions/workflows/tests.yml/badge.svg)](https://github.com/explosion/wasabi/actions/workflows/tests.yml)\n[![PyPi](https://img.shields.io/pypi/v/wasabi.svg?style=flat-square&logo=pypi&logoColor=white)](https://pypi.python.org/pypi/wasabi)\n[![conda](https://img.shields.io/conda/vn/conda-forge/wasabi.svg?style=flat-square&logo=conda-forge/logoColor=white)](https://anaconda.org/conda-forge/wasabi)\n[![GitHub](https://img.shields.io/github/release/ines/wasabi/all.svg?style=flat-square&logo=github)](https://github.com/ines/wasabi)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg?style=flat-square)](https://github.com/ambv/black)\n\n

\n\n## 💬 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 – 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 – 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. 🐀\n\n## ⌛️ Installation\n\n```bash\npip install wasabi\n```\n\n## 🎛 API\n\n### function `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### class `Printer`\n\n#### method `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`. | `\"⠙⠹⠸⠼⠴⠦⠧⠇⠏\"` |\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#### method `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` | unicode / 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#### method `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#### method `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#### contextmanager `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#### method `Printer.table`, `Printer.row`\n\nSee [Tables](#tables).\n\n#### property `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#### function `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#### function `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### class `TracebackPrinter`\n\nHelper to output custom formatted tracebacks and error messages. Currently used\nin [Thinc](https://github.com/explosion/thinc).\n\n#### method `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#### method `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 ├─ [61] in .env/lib/python3.6/site-packages/pluggy/manager.py\n ├─── _multicall [187] in .env/lib/python3.6/site-packages/pluggy/callers.py\n └───── 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### class `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### method `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### method `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### property `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### method `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\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### method `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\", \"💖\"))\n```\n\n```markdown\n# Hello world\n\n## 💖 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### method `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### method `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### method `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### method `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#### function `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#### function `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#### function `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## 🔔 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","description_content_type":"text/markdown","docs_url":null,"download_url":null,"downloads":{"last_day":-1,"last_month":-1,"last_week":-1},"dynamic":null,"home_page":"https://github.com/explosion/wasabi","keywords":null,"license":"MIT","license_expression":null,"license_files":null,"maintainer":null,"maintainer_email":null,"name":"wasabi","package_url":"https://pypi.org/project/wasabi/","platform":null,"project_url":"https://pypi.org/project/wasabi/","project_urls":{"Homepage":"https://github.com/explosion/wasabi"},"provides_extra":null,"release_url":"https://pypi.org/project/wasabi/1.1.3/","requires_dist":["typing-extensions<5.0.0,>=3.7.4.1; python_version < \"3.8\"","colorama>=0.4.6; sys_platform == \"win32\" and python_version >= \"3.7\""],"requires_python":">=3.6","summary":"A lightweight console printing and formatting toolkit","version":"1.1.3","yanked":false,"yanked_reason":null}

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

Package search

wasabi

project_urls

Dependencies

All package metadata

Releases