.. image:: http://www.repostatus.org/badges/latest/active.svg
:target: http://www.repostatus.org/#active
:alt: Project Status: Active — The project has reached a stable, usable
state and is being actively developed.
.. image:: https://github.com/jwodder/txtble/workflows/Test/badge.svg?branch=master
:target: https://github.com/jwodder/txtble/actions?workflow=Test
:alt: CI Status
.. image:: https://codecov.io/gh/jwodder/txtble/branch/master/graph/badge.svg
:target: https://codecov.io/gh/jwodder/txtble
.. image:: https://img.shields.io/pypi/pyversions/txtble.svg
:target: https://pypi.org/project/txtble/
.. image:: https://img.shields.io/github/license/jwodder/txtble.svg
:target: https://opensource.org/licenses/MIT
:alt: MIT License
`GitHub <https://github.com/jwodder/txtble>`_
| `PyPI <https://pypi.org/project/txtble/>`_
| `Issues <https://github.com/jwodder/txtble/issues>`_
| `Changelog <https://github.com/jwodder/txtble/blob/master/CHANGELOG.md>`_
.. contents::
:backlinks: top
``txtble`` is yet another Python library for creating plain-text tables. (All
the good names were taken, OK?) Pass in a list of lists of strings (or other
stringable things) and get out something nice like::
+---------+----------+------------------+
|Month |Birthstone|Birth Flower |
+---------+----------+------------------+
|January |Garnet |Carnation |
|February |Amethyst |Violet |
|March |Aquamarine|Jonquil |
|April |Diamond |Sweetpea |
|May |Emerald |Lily Of The Valley|
|June |Pearl |Rose |
|July |Ruby |Larkspur |
|August |Peridot |Gladiolus |
|September|Sapphire |Aster |
|October |Opal |Calendula |
|November |Topaz |Chrysanthemum |
|December |Turquoise |Narcissus |
+---------+----------+------------------+
Features:
- Rows can be passed as lists or `dict`\ s
- ANSI color aware
- Unicode fullwidth & combining character aware
- Control the horizontal (left, center, & right) and vertical (top, middle, &
bottom) alignment of text
- Align numbers along their decimal points
- Customize characters used for drawing borders
- Toggle inter-row, inter-column, and outer borders
- Set the value used to fill out ragged rows
- Pad cells on the left & right
- Set column widths, with long lines wrapped to fit
- Configure how `None` values are displayed
- Type annotations
Installation
============
``txtble`` requires Python 3.7 or higher. Just use `pip
<https://pip.pypa.io>`_ for Python 3 (You have pip, right?) to install
``txtble`` and its dependencies::
python3 -m pip install txtble
Examples
========
Construct & show a basic table:
>>> from txtble import Txtble
>>> # Taken from /usr/share/misc/birthtoken.gz in Ubuntu Xenial's miscfiles package:
>>> HEADERS = ['Month', 'Birthstone', 'Birth Flower']
>>> DATA = [
... ['January', 'Garnet', 'Carnation'],
... ['February', 'Amethyst', 'Violet'],
... ['March', 'Aquamarine', 'Jonquil'],
... ['April', 'Diamond', 'Sweetpea'],
... ['May', 'Emerald', 'Lily Of The Valley'],
... ['June', 'Pearl', 'Rose'],
... ['July', 'Ruby', 'Larkspur'],
... ['August', 'Peridot', 'Gladiolus'],
... ['September', 'Sapphire', 'Aster'],
... ['October', 'Opal', 'Calendula'],
... ['November', 'Topaz', 'Chrysanthemum'],
... ['December', 'Turquoise', 'Narcissus'],
... ]
>>> tbl = Txtble(DATA, headers=HEADERS)
>>> print(tbl)
+---------+----------+------------------+
|Month |Birthstone|Birth Flower |
+---------+----------+------------------+
|January |Garnet |Carnation |
|February |Amethyst |Violet |
|March |Aquamarine|Jonquil |
|April |Diamond |Sweetpea |
|May |Emerald |Lily Of The Valley|
|June |Pearl |Rose |
|July |Ruby |Larkspur |
|August |Peridot |Gladiolus |
|September|Sapphire |Aster |
|October |Opal |Calendula |
|November |Topaz |Chrysanthemum |
|December |Turquoise |Narcissus |
+---------+----------+------------------+
The table can also be constructed like this:
>>> tbl = Txtble(headers=HEADERS)
>>> tbl.extend(DATA)
Or like this:
>>> tbl = Txtble(headers=HEADERS)
>>> for row in DATA:
... tbl.append(row)
Or even like this:
>>> tbl = Txtble(DATA)
>>> tbl.headers = HEADERS
The rows of the table can be lists of values (as seen above) or `dict`\ s that
map header names to values:
>>> tbl = Txtble(
... headers = ["Red", "Green", "Blue"],
... data = [
... {"Red": "Ruby", "Green": "Emerald", "Blue": "Sapphire"},
... {"Red": "Fire", "Green": "Earth", "Blue": "Water"},
... ],
... )
>>> print(tbl)
+----+-------+--------+
|Red |Green |Blue |
+----+-------+--------+
|Ruby|Emerald|Sapphire|
|Fire|Earth |Water |
+----+-------+--------+
Missing `dict` keys can be filled in with the ``dict_fill`` option (Without it,
you'd get a `KeyError` here):
>>> tbl = Txtble(
... headers = ["Red", "Green", "Blue"],
... data = [
... {"Red": "Ruby", "Green": "Emerald", "Blue": "Sapphire"},
... {"Red": "Fire", "Green": "Earth", "Blue": "Water"},
... {"Red": "Hot", "Blue": "Cold"},
... ],
... dict_fill = 'UNKNOWN',
... )
>>> print(tbl)
+----+-------+--------+
|Red |Green |Blue |
+----+-------+--------+
|Ruby|Emerald|Sapphire|
|Fire|Earth |Water |
|Hot |UNKNOWN|Cold |
+----+-------+--------+
The number of columns is automatically set to the length of the longest row:
>>> tbl = Txtble([
... ['1', '1'],
... ['Z_6', '1', 'x', 'x^2', 'x^3', 'x^4', 'x^5'],
... ['S_3', '1', 'a', 'b', 'aba', 'ba', 'ab'],
... ['Z_4', '1', 'x', 'x^2', 'x^3'],
... ['V_4', '1', 'a', 'b', 'ab'],
... ])
>>> print(tbl)
+---+-+-+---+---+---+---+
|1 |1| | | | | |
|Z_6|1|x|x^2|x^3|x^4|x^5|
|S_3|1|a|b |aba|ba |ab |
|Z_4|1|x|x^2|x^3| | |
|V_4|1|a|b |ab | | |
+---+-+-+---+---+---+---+
... unless you've specified a header row, which puts a limit on the number of
columns:
>>> tbl.headers = ['Group', 'Elements']
>>> print(tbl)
+-----+--------+
|Group|Elements|
+-----+--------+
|1 |1 |
|Z_6 |1 |
|S_3 |1 |
|Z_4 |1 |
|V_4 |1 |
+-----+--------+
... unless you've *also* specified a ``header_fill`` to use as the header for
extra columns:
>>> tbl.header_fill = 'Extra!'
>>> print(tbl)
+-----+--------+------+------+------+------+------+
|Group|Elements|Extra!|Extra!|Extra!|Extra!|Extra!|
+-----+--------+------+------+------+------+------+
|1 |1 | | | | | |
|Z_6 |1 |x |x^2 |x^3 |x^4 |x^5 |
|S_3 |1 |a |b |aba |ba |ab |
|Z_4 |1 |x |x^2 |x^3 | | |
|V_4 |1 |a |b |ab | | |
+-----+--------+------+------+------+------+------+
You can set the widths of columns; long lines will be wrapped to fit:
>>> tbl = Txtble(
... headers=['Short Text', 'Long Text'],
... data=[
... [
... 'Hi there!',
... 'Lorem ipsum dolor sit amet, consectetur adipisicing elit',
... ]
... ],
... widths=[20, 20],
... )
>>> print(tbl)
+--------------------+--------------------+
|Short Text |Long Text |
+--------------------+--------------------+
|Hi there! |Lorem ipsum dolor |
| |sit amet, |
| |consectetur |
| |adipisicing elit |
+--------------------+--------------------+
You can align column text to the left, right, or center:
>>> tbl = Txtble(DATA, headers=HEADERS, align=['r', 'c', 'l'])
>>> print(tbl)
+---------+----------+------------------+
| Month|Birthstone|Birth Flower |
+---------+----------+------------------+
| January| Garnet |Carnation |
| February| Amethyst |Violet |
| March|Aquamarine|Jonquil |
| April| Diamond |Sweetpea |
| May| Emerald |Lily Of The Valley|
| June| Pearl |Rose |
| July| Ruby |Larkspur |
| August| Peridot |Gladiolus |
|September| Sapphire |Aster |
| October| Opal |Calendula |
| November| Topaz |Chrysanthemum |
| December|Turquoise |Narcissus |
+---------+----------+------------------+
Numbers in the same column can be aligned on their decimal point with the
``'n'`` alignment:
>>> tbl = Txtble(
... headers=['Thing', 'Value'],
... data=[
... ['Foo', 12345],
... ['Bar', 1234.5],
... ['Baz', 123.45],
... ['Quux', 12.345],
... ['Glarch', 1.2345],
... ['Gnusto', .12345],
... ],
... align=['l', 'n'],
... )
>>> print(tbl)
+------+-----------+
|Thing |Value |
+------+-----------+
|Foo |12345 |
|Bar | 1234.5 |
|Baz | 123.45 |
|Quux | 12.345 |
|Glarch| 1.2345 |
|Gnusto| 0.12345|
+------+-----------+
Unicode works too, even fullwidth characters and combining characters:
>>> tbl = Txtble(
... headers=['Wide', 'Accented'],
... data=[
... [
... u'\uFF37\uFF49\uFF44\uFF45',
... u'A\u0301c\u0301c\u0301e\u0301n\u0301t\u0301e\u0301d\u0301',
... ]
... ]
... )
>>> print(tbl)
+--------+--------+
|Wide |Accented|
+--------+--------+
|Ｗｉｄｅ|Áććéńt́éd́|
+--------+--------+
You can configure the borders and make them fancy:
>>> from txtble import ASCII_EQ_BORDERS
>>> tbl = Txtble(
... DATA,
... headers = HEADERS,
... header_border = ASCII_EQ_BORDERS,
... row_border = True,
... )
>>> print(tbl)
+---------+----------+------------------+
|Month |Birthstone|Birth Flower |
+=========+==========+==================+
|January |Garnet |Carnation |
+---------+----------+------------------+
|February |Amethyst |Violet |
+---------+----------+------------------+
|March |Aquamarine|Jonquil |
+---------+----------+------------------+
|April |Diamond |Sweetpea |
+---------+----------+------------------+
|May |Emerald |Lily Of The Valley|
+---------+----------+------------------+
|June |Pearl |Rose |
+---------+----------+------------------+
|July |Ruby |Larkspur |
+---------+----------+------------------+
|August |Peridot |Gladiolus |
+---------+----------+------------------+
|September|Sapphire |Aster |
+---------+----------+------------------+
|October |Opal |Calendula |
+---------+----------+------------------+
|November |Topaz |Chrysanthemum |
+---------+----------+------------------+
|December |Turquoise |Narcissus |
+---------+----------+------------------+
... or *very* fancy:
>>> from txtble import DOUBLE_BORDERS
>>> tbl = Txtble(DATA, headers=HEADERS, border_style=DOUBLE_BORDERS)
>>> print(tbl)
╔═════════╦══════════╦══════════════════╗
║Month ║Birthstone║Birth Flower ║
╠═════════╬══════════╬══════════════════╣
║January ║Garnet ║Carnation ║
║February ║Amethyst ║Violet ║
║March ║Aquamarine║Jonquil ║
║April ║Diamond ║Sweetpea ║
║May ║Emerald ║Lily Of The Valley║
║June ║Pearl ║Rose ║
║July ║Ruby ║Larkspur ║
║August ║Peridot ║Gladiolus ║
║September║Sapphire ║Aster ║
║October ║Opal ║Calendula ║
║November ║Topaz ║Chrysanthemum ║
║December ║Turquoise ║Narcissus ║
╚═════════╩══════════╩══════════════════╝
See the following documentation for more information:
API
===
``Txtble``
----------
``Txtble(data=(), **kwargs)``
Create a new ``Txtble`` object. The table's data may be passed to the
constructor as an iterable of rows of values, where each row is either an
iterable of cell values or a mapping from header names to cell values;
otherwise, the data starts out empty. In either case, further data rows can
be added via the ``append()`` and ``extend()`` methods.
``**kwargs`` are used to configure the ``Txtble`` instance; see
"`Configuration Options`_" below.
``tbl.append(row)``
Add a new data row at the bottom of the table. ``row`` can be either an
iterable of cell values or a mapping from header names to cell values.
``tbl.extend(rows)``
Add zero or more new data rows at the bottom of the table
``tbl.show()`` or ``str(tbl)``
Convert the ``Txtble`` instance to a string showing a plain text table.
Table cells and filler values that are not already strings are converted by
calling `str()` on them; the exceptions are `None` values, which are
displayed according to the ``none_str`` option (see below). All tab
characters are expanded to spaces before building the table. If any of the
resulting strings have indeterminate width (i.e., if ``wcwidth.wcswidth()``
returns a negative number for any of them), an ``IndeterminateWidthError``
(a subclass of `ValueError`) is raised.
Note that the resulting string will likely contain one or more embedded
newlines, but (outside of some very odd cases) it will not end with a
newline. This means that you can do ``print(tbl)`` and there won't be a
blank line added at the end.
Configuration Options
---------------------
These options can be set either as keywords passed to the ``Txtble``
constructor or as attributes on a ``Txtble`` instance::
tbl = Txtble(data, border=False)
# Same as:
tbl = Txtble(data)
tbl.border = False
``align: Union[str, Sequence[str]] = ()``
A sequence of alignment specifiers indicating how the contents of each
column, in order, should be horizontally aligned. The alignment specifiers
are ``'l'`` (left alignment), ``'c'`` (centered alignment), and ``'r'``
(right alignment). ``align`` may optionally be set to a single alignment
specifier to cause all columns to be aligned in that way.
An alignment specifier may optionally include ``'n'`` to cause all numbers
in the relevant column to be aligned on their decimal point; the ``'l'``,
``'c'``, or ``'r'`` then determines how the "block" of numbers is aligned as
a whole (This is generally only relevant if the column also contains a
string value longer than any of the numbers). An alignment specifier of
just ``'n'`` is equivalent to ``'ln'`` or ``'nl'``.
``align_fill: str = 'l'``
If there are more columns than there are entries in ``align``, the extra
columns will have their alignment set to ``align_fill``.
``border: Union[bool, BorderStyle] = True``
Whether to draw a border around the edge of the table. ``border`` may
optionally be set to a ``BorderStyle`` instance to set the characters used
for drawing the border around the edge of the table. Individual edges can
be toggled or stylized by setting the ``bottom_border``, ``left_border``,
``right_border``, and ``top_border`` options.
``border_style: BorderStyle = ASCII_BORDERS``
A ``BorderStyle`` instance specifying the characters to use for drawing all
of the table's borders & rules. The border style can be overridden for
individual borders by setting their respective options (``border``,
``column_border``, etc.) to ``BorderStyle`` instances. See "BorderStyle_"
below for more information.
``bottom_border: Union[bool, BorderStyle, None] = None``
Whether to draw a border along the bottom edge of the table. The default
value of `None` means to inherit the value set for ``border``.
``bottom_border`` may optionally be set to a ``BorderStyle`` instance to set
the characters used for drawing the border along the bottom edge.
``break_long_words: bool = True``
Whether to force a line break in the middle of a word if said word is too
long for the column's width
``break_on_hyphens: bool = True``
Whether to break on hyphens in addition to whitespace when wrapping text
``column_border: Union[bool, BorderStyle] = True``
Whether to draw a vertical rule between individual columns.
``column_border`` may optionally be set to a ``BorderStyle`` instance to set
the characters used for drawing the vertical rules between columns.
``columns: Optional[int] = None``
An optional positive integer. When set, show exactly the given number of
columns per row, adding cells with ``row_fill`` and discarding extra cells
as needed. If ``headers`` is also set, its length must equal ``columns`` or
else a `ValueError` is raised. Setting both ``columns`` and ``headers``
causes ``header_fill`` to be ignored.
``dict_fill: Any``
If a header name does not appear as a key in a `dict`/mapping row, the value
of ``dict_fill`` will be used for the corresponding cell value. If
``dict_fill`` is not set, a missing key will cause a ``KeyError`` to be
raised.
``header_border: Union[bool, BorderStyle, None] = None``
Whether to draw a horizontal rule above the data rows, below the header row
(if any). The default value of `None` means that the border will be drawn
if & only if ``headers`` is non-`None`. ``header_border`` may optionally be
set to a ``BorderStyle`` instance to set the characters used for drawing the
horizontal rule above the data rows.
If ``headers`` is `None` and ``top_border`` is set to a true value (or
inherits a true value from ``border``), the header border will not be drawn.
``header_fill: Any = None``
When ``headers`` is non-`None` and ``columns`` is `None`, this option
determines how rows with more columns than there are headers are handled.
When ``header_fill=None``, any extra columns are discarded from long rows.
For all other values, the header row will be extended to the length of the
longest data row, and the new header cells will contain the ``header_fill``
value.
``headers: Optional[list] = None``
An optional list of cell values to display in a row at the top of the table.
Setting this option also implicitly sets a minimum number of columns per
row; see ``header_fill`` for allowing extra columns.
If ``headers`` is set to an empty list, ``header_fill`` must be set to a
non-`None` value or else a `ValueError` will be raised upon trying to render
the ``Txtble``.
``left_border: Union[bool, BorderStyle, None] = None``
Whether to draw a border along the left edge of the table. The default
value of `None` means to inherit the value set for ``border``.
``left_border`` may optionally be set to a ``BorderStyle`` instance to set
the characters used for drawing the border along the left edge.
``left_padding: Union[int, str, None] = None``
Padding to insert on the left of every table cell. This can be either an
integer (to insert that many space characters) or a string. If a string, it
may not contain any newlines. The default value of `None` means to inherit
the value set for ``padding``.
``len_func: Optional[Callable[[str], int]]``
The function to use for calculating how many terminal cells wide a string
is; it should take one string argument and return a width. Returning a
negative width causes ``Txtble`` to raise an ``IndeterminateWidthError``.
The default value (also used when set to `None`) is
``with_color_stripped(wcwidth.wcswidth)`` (See "Other_" below).
``none_str: Any = ''``
The string to display in place of `None` values (Setting ``none_str=None``
is the same as setting it to ``'None'``)
``padding: Union[int, str] = 0``
Padding to insert on the left & right of every table cell. This can be
either an integer (to insert that many space characters) or a string. If a
string, it may not contain any newlines. Padding for the left and right of
table cells can be specified separately via the ``left_padding`` and
``right_padding`` options.
``right_border: Union[bool, BorderStyle, None] = None``
Whether to draw a border along the right edge of the table. The default
value of `None` means to inherit the value set for ``border``.
``right_border`` may optionally be set to a ``BorderStyle`` instance to set
the characters used for drawing the border along the right edge.
``right_padding: Union[int, str, None] = None``
Padding to insert on the right of every table cell. This can be either an
integer (to insert that many space characters) or a string. If a string, it
may not contain any newlines. The default value of `None` means to inherit
the value set for ``padding``.
``row_border: Union[bool, BorderStyle] = False``
Whether to draw horizontal rules between data rows. ``row_border`` may
optionally be set to a ``BorderStyle`` instance to set the characters used
for drawing the horizontal rules between data rows.
``row_fill: Any = ''``
If the rows of a table differ in number of columns, cells are added to the
shorter rows until they all line up, and the added cells contain
``row_fill`` as their value.
``rstrip: bool = True``
When ``border=False``, setting ``rstrip=False`` will cause the last cell of
each row to still be padded with trailing whitespace and ``padding`` in
order to reach the full column width. (Normally, this whitespace and
``padding`` is omitted when ``border=False`` as there is no end-of-line
border to align.) This option is useful if you wish to append text to one
or more lines of the output and have it appear strictly outside the table.
``top_border: Union[bool, BorderStyle, None] = None``
Whether to draw a border along the top edge of the table. The default value
of `None` means to inherit the value set for ``border``. ``top_border`` may
optionally be set to a ``BorderStyle`` instance to set the characters used
for drawing the border along the top edge.
``valign: Union[str, Sequence[str]] = ()``
A sequence of vertical alignment specifiers indicating how the contents of
each column, in order, should be vertically aligned. The vertical alignment
specifiers are ``'t'`` (top alignment), ``'m'`` (middle alignment), and
``'b'`` (bottom alignment). ``valign`` may optionally be set to a single
vertical alignment specifier to cause all columns to be vertically aligned
in that way.
``valign_fill: str = 't'``
If there are more columns than there are entries in ``valign``, the extra
columns will have their vertical alignment set to ``valign_fill``.
``width_fill: Optional[int] = None``
If there are more columns than there are entries in ``widths``, the extra
columns will have their widths set to ``width_fill``.
``widths: Union[int, Sequence[Optional[int]], None] = ()``
A sequence of integers specifying the width of each column, in order. Lines
wider than the given width will be wrapped; the wrapping can be configured
via the ``break_long_words`` and ``break_on_hyphens`` options. A width of
`None` disables wrapping for that column and causes the column's width to be
set to the width of the longest line. ``widths`` may optionally be set to a
single width to cause all columns to be that wide.
``wrap_func: Optional[Callable[[str, int], Iterable[str]]] = None``
The function to use for wrapping long lines; it should take a string and a
width and return an iterable of strings. The default value of `None` causes
a custom function to be used that properly handles fullwidth characters,
ANSI color escape sequences, etc.; if your table contains such strings, any
user-supplied ``wrap_func`` must be able to handle them as well. When
``wrap_func`` is set to a user-supplied value, the ``break_long_words`` and
``break_on_hyphens`` options are ignored.
``BorderStyle``
---------------
The ``BorderStyle`` class is a `namedtuple` listing the strings to use for
drawing a table's borders & rules. Its attributes are:
.. csv-table::
:header: Attribute,Description,Example
``hline``,horizontal line,─
``vline``,vertical line,│
``ulcorner``,upper-left box corner,┌
``urcorner``,upper-right box corner,┐
``llcorner``,lower-left box corner,└
``lrcorner``,lower-right box corner,┘
``vrtee``,tee pointing right,├
``vltee``,tee pointing left,┤
``dhtee``,tee pointing down,┬
``uhtee``,tee pointing up,┴
``plus``,cross/four-way joint,┼
``txtble`` provides the following predefined ``BorderStyle`` instances:
``ASCII_BORDERS``
The default border style. Draws borders using only the ASCII characters
``-``, ``|``, and ``+``::
+-+-+
|A|B|
+-+-+
|C|D|
+-+-+
``ASCII_EQ_BORDERS``
Like ``ASCII_BORDERS``, but uses ``=`` in place of ``-``::
+=+=+
|A|B|
+=+=+
|C|D|
+=+=+
``LIGHT_BORDERS``
Uses the light box drawing characters::
┌─┬─┐
|A|B|
├─┼─┤
|C|D|
└─┴─┘
``HEAVY_BORDERS``
Uses the heavy box drawing characters::
┏━┳━┓
┃A┃B┃
┣━╋━┫
┃C┃D┃
┗━┻━┛
``DOUBLE_BORDERS``
Uses the double box drawing characters::
╔═╦═╗
║A║B║
╠═╬═╣
║C║D║
╚═╩═╝
``DOT_BORDERS``
Uses ``⋯``, ``⋮``, and ``·``::
·⋯·⋯·
⋮A⋮B⋮
·⋯·⋯·
⋮C⋮D⋮
·⋯·⋯·
If you define your own custom instances of ``BorderStyle``, they must adhere to
the following rules:
- The ``hline`` string must be exactly one terminal column wide (the same width
as a space character).
- All strings other than ``hline`` must be the same width.
- No string may contain a newline.
Other
-----
``IndeterminateWidthError``
Subclass of ``ValueError``. Raised when a string is reported as having
negative/indeterminate width. (For the default ``len_func``, this happens
when the string contains a DEL or a C0 or C1 control character other than a
tab, newline, or ANSI color escape sequence.) The string in question is
available as the exception's ``string`` attribute.
``NumericWidthOverflowError``
Subclass of ``ValueError``. Raised when a column has a non-`None` width,
the column's ``align`` value contains ``'n'``, and aligning the numbers in
the column along their decimal points would cause one or more cells to
exceed the column's width.
``UnterminatedColorError``
Subclass of ``ValueError``. Raised by ``with_color_stripped`` upon
encountering an ANSI color escape sequence that is not eventually terminated
by a reset/sgr0 sequence. The string in question is available as the
exception's ``string`` attribute.
``with_color_stripped``
A function decorator for applying to ``len`` or imitators thereof that
strips ANSI color sequences from a single string argument before passing it
on. If any color sequences are not followed by a reset sequence, an
``UnterminatedColorError`` is raised.
Raw data
{
"_id": null,
"home_page": "https://github.com/jwodder/txtble",
"name": "txtble",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "box-drawing,grid,table",
"author": "John Thorvald Wodder II",
"author_email": "txtble@varonathe.org",
"download_url": "https://files.pythonhosted.org/packages/cc/97/89e95da96d127052ce2ba6f3084c2733a93b43b7d8977f9f83067d2b56e1/txtble-0.12.1.tar.gz",
"platform": null,
"description": ".. image:: http://www.repostatus.org/badges/latest/active.svg\n :target: http://www.repostatus.org/#active\n :alt: Project Status: Active \u2014 The project has reached a stable, usable\n state and is being actively developed.\n\n.. image:: https://github.com/jwodder/txtble/workflows/Test/badge.svg?branch=master\n :target: https://github.com/jwodder/txtble/actions?workflow=Test\n :alt: CI Status\n\n.. image:: https://codecov.io/gh/jwodder/txtble/branch/master/graph/badge.svg\n :target: https://codecov.io/gh/jwodder/txtble\n\n.. image:: https://img.shields.io/pypi/pyversions/txtble.svg\n :target: https://pypi.org/project/txtble/\n\n.. image:: https://img.shields.io/github/license/jwodder/txtble.svg\n :target: https://opensource.org/licenses/MIT\n :alt: MIT License\n\n`GitHub <https://github.com/jwodder/txtble>`_\n| `PyPI <https://pypi.org/project/txtble/>`_\n| `Issues <https://github.com/jwodder/txtble/issues>`_\n| `Changelog <https://github.com/jwodder/txtble/blob/master/CHANGELOG.md>`_\n\n.. contents::\n :backlinks: top\n\n``txtble`` is yet another Python library for creating plain-text tables. (All\nthe good names were taken, OK?) Pass in a list of lists of strings (or other\nstringable things) and get out something nice like::\n\n +---------+----------+------------------+\n |Month |Birthstone|Birth Flower |\n +---------+----------+------------------+\n |January |Garnet |Carnation |\n |February |Amethyst |Violet |\n |March |Aquamarine|Jonquil |\n |April |Diamond |Sweetpea |\n |May |Emerald |Lily Of The Valley|\n |June |Pearl |Rose |\n |July |Ruby |Larkspur |\n |August |Peridot |Gladiolus |\n |September|Sapphire |Aster |\n |October |Opal |Calendula |\n |November |Topaz |Chrysanthemum |\n |December |Turquoise |Narcissus |\n +---------+----------+------------------+\n\nFeatures:\n\n- Rows can be passed as lists or `dict`\\ s\n- ANSI color aware\n- Unicode fullwidth & combining character aware\n- Control the horizontal (left, center, & right) and vertical (top, middle, &\n bottom) alignment of text\n- Align numbers along their decimal points\n- Customize characters used for drawing borders\n- Toggle inter-row, inter-column, and outer borders\n- Set the value used to fill out ragged rows\n- Pad cells on the left & right\n- Set column widths, with long lines wrapped to fit\n- Configure how `None` values are displayed\n- Type annotations\n\n\nInstallation\n============\n``txtble`` requires Python 3.7 or higher. Just use `pip\n<https://pip.pypa.io>`_ for Python 3 (You have pip, right?) to install\n``txtble`` and its dependencies::\n\n python3 -m pip install txtble\n\n\nExamples\n========\n\nConstruct & show a basic table:\n\n>>> from txtble import Txtble\n>>> # Taken from /usr/share/misc/birthtoken.gz in Ubuntu Xenial's miscfiles package:\n>>> HEADERS = ['Month', 'Birthstone', 'Birth Flower']\n>>> DATA = [\n... ['January', 'Garnet', 'Carnation'],\n... ['February', 'Amethyst', 'Violet'],\n... ['March', 'Aquamarine', 'Jonquil'],\n... ['April', 'Diamond', 'Sweetpea'],\n... ['May', 'Emerald', 'Lily Of The Valley'],\n... ['June', 'Pearl', 'Rose'],\n... ['July', 'Ruby', 'Larkspur'],\n... ['August', 'Peridot', 'Gladiolus'],\n... ['September', 'Sapphire', 'Aster'],\n... ['October', 'Opal', 'Calendula'],\n... ['November', 'Topaz', 'Chrysanthemum'],\n... ['December', 'Turquoise', 'Narcissus'],\n... ]\n>>> tbl = Txtble(DATA, headers=HEADERS)\n>>> print(tbl)\n+---------+----------+------------------+\n|Month |Birthstone|Birth Flower |\n+---------+----------+------------------+\n|January |Garnet |Carnation |\n|February |Amethyst |Violet |\n|March |Aquamarine|Jonquil |\n|April |Diamond |Sweetpea |\n|May |Emerald |Lily Of The Valley|\n|June |Pearl |Rose |\n|July |Ruby |Larkspur |\n|August |Peridot |Gladiolus |\n|September|Sapphire |Aster |\n|October |Opal |Calendula |\n|November |Topaz |Chrysanthemum |\n|December |Turquoise |Narcissus |\n+---------+----------+------------------+\n\nThe table can also be constructed like this:\n\n>>> tbl = Txtble(headers=HEADERS)\n>>> tbl.extend(DATA)\n\nOr like this:\n\n>>> tbl = Txtble(headers=HEADERS)\n>>> for row in DATA:\n... tbl.append(row)\n\nOr even like this:\n\n>>> tbl = Txtble(DATA)\n>>> tbl.headers = HEADERS\n\nThe rows of the table can be lists of values (as seen above) or `dict`\\ s that\nmap header names to values:\n\n>>> tbl = Txtble(\n... headers = [\"Red\", \"Green\", \"Blue\"],\n... data = [\n... {\"Red\": \"Ruby\", \"Green\": \"Emerald\", \"Blue\": \"Sapphire\"},\n... {\"Red\": \"Fire\", \"Green\": \"Earth\", \"Blue\": \"Water\"},\n... ],\n... )\n>>> print(tbl)\n+----+-------+--------+\n|Red |Green |Blue |\n+----+-------+--------+\n|Ruby|Emerald|Sapphire|\n|Fire|Earth |Water |\n+----+-------+--------+\n\nMissing `dict` keys can be filled in with the ``dict_fill`` option (Without it,\nyou'd get a `KeyError` here):\n\n>>> tbl = Txtble(\n... headers = [\"Red\", \"Green\", \"Blue\"],\n... data = [\n... {\"Red\": \"Ruby\", \"Green\": \"Emerald\", \"Blue\": \"Sapphire\"},\n... {\"Red\": \"Fire\", \"Green\": \"Earth\", \"Blue\": \"Water\"},\n... {\"Red\": \"Hot\", \"Blue\": \"Cold\"},\n... ],\n... dict_fill = 'UNKNOWN',\n... )\n>>> print(tbl)\n+----+-------+--------+\n|Red |Green |Blue |\n+----+-------+--------+\n|Ruby|Emerald|Sapphire|\n|Fire|Earth |Water |\n|Hot |UNKNOWN|Cold |\n+----+-------+--------+\n\nThe number of columns is automatically set to the length of the longest row:\n\n>>> tbl = Txtble([\n... ['1', '1'],\n... ['Z_6', '1', 'x', 'x^2', 'x^3', 'x^4', 'x^5'],\n... ['S_3', '1', 'a', 'b', 'aba', 'ba', 'ab'],\n... ['Z_4', '1', 'x', 'x^2', 'x^3'],\n... ['V_4', '1', 'a', 'b', 'ab'],\n... ])\n>>> print(tbl)\n+---+-+-+---+---+---+---+\n|1 |1| | | | | |\n|Z_6|1|x|x^2|x^3|x^4|x^5|\n|S_3|1|a|b |aba|ba |ab |\n|Z_4|1|x|x^2|x^3| | |\n|V_4|1|a|b |ab | | |\n+---+-+-+---+---+---+---+\n\n... unless you've specified a header row, which puts a limit on the number of\ncolumns:\n\n>>> tbl.headers = ['Group', 'Elements']\n>>> print(tbl)\n+-----+--------+\n|Group|Elements|\n+-----+--------+\n|1 |1 |\n|Z_6 |1 |\n|S_3 |1 |\n|Z_4 |1 |\n|V_4 |1 |\n+-----+--------+\n\n... unless you've *also* specified a ``header_fill`` to use as the header for\nextra columns:\n\n>>> tbl.header_fill = 'Extra!'\n>>> print(tbl)\n+-----+--------+------+------+------+------+------+\n|Group|Elements|Extra!|Extra!|Extra!|Extra!|Extra!|\n+-----+--------+------+------+------+------+------+\n|1 |1 | | | | | |\n|Z_6 |1 |x |x^2 |x^3 |x^4 |x^5 |\n|S_3 |1 |a |b |aba |ba |ab |\n|Z_4 |1 |x |x^2 |x^3 | | |\n|V_4 |1 |a |b |ab | | |\n+-----+--------+------+------+------+------+------+\n\nYou can set the widths of columns; long lines will be wrapped to fit:\n\n>>> tbl = Txtble(\n... headers=['Short Text', 'Long Text'],\n... data=[\n... [\n... 'Hi there!',\n... 'Lorem ipsum dolor sit amet, consectetur adipisicing elit',\n... ]\n... ],\n... widths=[20, 20],\n... )\n>>> print(tbl)\n+--------------------+--------------------+\n|Short Text |Long Text |\n+--------------------+--------------------+\n|Hi there! |Lorem ipsum dolor |\n| |sit amet, |\n| |consectetur |\n| |adipisicing elit |\n+--------------------+--------------------+\n\nYou can align column text to the left, right, or center:\n\n>>> tbl = Txtble(DATA, headers=HEADERS, align=['r', 'c', 'l'])\n>>> print(tbl)\n+---------+----------+------------------+\n| Month|Birthstone|Birth Flower |\n+---------+----------+------------------+\n| January| Garnet |Carnation |\n| February| Amethyst |Violet |\n| March|Aquamarine|Jonquil |\n| April| Diamond |Sweetpea |\n| May| Emerald |Lily Of The Valley|\n| June| Pearl |Rose |\n| July| Ruby |Larkspur |\n| August| Peridot |Gladiolus |\n|September| Sapphire |Aster |\n| October| Opal |Calendula |\n| November| Topaz |Chrysanthemum |\n| December|Turquoise |Narcissus |\n+---------+----------+------------------+\n\nNumbers in the same column can be aligned on their decimal point with the\n``'n'`` alignment:\n\n>>> tbl = Txtble(\n... headers=['Thing', 'Value'],\n... data=[\n... ['Foo', 12345],\n... ['Bar', 1234.5],\n... ['Baz', 123.45],\n... ['Quux', 12.345],\n... ['Glarch', 1.2345],\n... ['Gnusto', .12345],\n... ],\n... align=['l', 'n'],\n... )\n>>> print(tbl)\n+------+-----------+\n|Thing |Value |\n+------+-----------+\n|Foo |12345 |\n|Bar | 1234.5 |\n|Baz | 123.45 |\n|Quux | 12.345 |\n|Glarch| 1.2345 |\n|Gnusto| 0.12345|\n+------+-----------+\n\nUnicode works too, even fullwidth characters and combining characters:\n\n>>> tbl = Txtble(\n... headers=['Wide', 'Accented'],\n... data=[\n... [\n... u'\\uFF37\\uFF49\\uFF44\\uFF45',\n... u'A\\u0301c\\u0301c\\u0301e\\u0301n\\u0301t\\u0301e\\u0301d\\u0301',\n... ]\n... ]\n... )\n>>> print(tbl)\n+--------+--------+\n|Wide |Accented|\n+--------+--------+\n|\uff37\uff49\uff44\uff45|A\u0301c\u0301c\u0301e\u0301n\u0301t\u0301e\u0301d\u0301|\n+--------+--------+\n\nYou can configure the borders and make them fancy:\n\n>>> from txtble import ASCII_EQ_BORDERS\n>>> tbl = Txtble(\n... DATA,\n... headers = HEADERS,\n... header_border = ASCII_EQ_BORDERS,\n... row_border = True,\n... )\n>>> print(tbl)\n+---------+----------+------------------+\n|Month |Birthstone|Birth Flower |\n+=========+==========+==================+\n|January |Garnet |Carnation |\n+---------+----------+------------------+\n|February |Amethyst |Violet |\n+---------+----------+------------------+\n|March |Aquamarine|Jonquil |\n+---------+----------+------------------+\n|April |Diamond |Sweetpea |\n+---------+----------+------------------+\n|May |Emerald |Lily Of The Valley|\n+---------+----------+------------------+\n|June |Pearl |Rose |\n+---------+----------+------------------+\n|July |Ruby |Larkspur |\n+---------+----------+------------------+\n|August |Peridot |Gladiolus |\n+---------+----------+------------------+\n|September|Sapphire |Aster |\n+---------+----------+------------------+\n|October |Opal |Calendula |\n+---------+----------+------------------+\n|November |Topaz |Chrysanthemum |\n+---------+----------+------------------+\n|December |Turquoise |Narcissus |\n+---------+----------+------------------+\n\n... or *very* fancy:\n\n>>> from txtble import DOUBLE_BORDERS\n>>> tbl = Txtble(DATA, headers=HEADERS, border_style=DOUBLE_BORDERS)\n>>> print(tbl)\n\u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2566\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2566\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557\n\u2551Month \u2551Birthstone\u2551Birth Flower \u2551\n\u2560\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u256c\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u256c\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2563\n\u2551January \u2551Garnet \u2551Carnation \u2551\n\u2551February \u2551Amethyst \u2551Violet \u2551\n\u2551March \u2551Aquamarine\u2551Jonquil \u2551\n\u2551April \u2551Diamond \u2551Sweetpea \u2551\n\u2551May \u2551Emerald \u2551Lily Of The Valley\u2551\n\u2551June \u2551Pearl \u2551Rose \u2551\n\u2551July \u2551Ruby \u2551Larkspur \u2551\n\u2551August \u2551Peridot \u2551Gladiolus \u2551\n\u2551September\u2551Sapphire \u2551Aster \u2551\n\u2551October \u2551Opal \u2551Calendula \u2551\n\u2551November \u2551Topaz \u2551Chrysanthemum \u2551\n\u2551December \u2551Turquoise \u2551Narcissus \u2551\n\u255a\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2569\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2569\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255d\n\nSee the following documentation for more information:\n\n\nAPI\n===\n\n``Txtble``\n----------\n\n``Txtble(data=(), **kwargs)``\n Create a new ``Txtble`` object. The table's data may be passed to the\n constructor as an iterable of rows of values, where each row is either an\n iterable of cell values or a mapping from header names to cell values;\n otherwise, the data starts out empty. In either case, further data rows can\n be added via the ``append()`` and ``extend()`` methods.\n\n ``**kwargs`` are used to configure the ``Txtble`` instance; see\n \"`Configuration Options`_\" below.\n\n``tbl.append(row)``\n Add a new data row at the bottom of the table. ``row`` can be either an\n iterable of cell values or a mapping from header names to cell values.\n\n``tbl.extend(rows)``\n Add zero or more new data rows at the bottom of the table\n\n``tbl.show()`` or ``str(tbl)``\n Convert the ``Txtble`` instance to a string showing a plain text table.\n Table cells and filler values that are not already strings are converted by\n calling `str()` on them; the exceptions are `None` values, which are\n displayed according to the ``none_str`` option (see below). All tab\n characters are expanded to spaces before building the table. If any of the\n resulting strings have indeterminate width (i.e., if ``wcwidth.wcswidth()``\n returns a negative number for any of them), an ``IndeterminateWidthError``\n (a subclass of `ValueError`) is raised.\n\n Note that the resulting string will likely contain one or more embedded\n newlines, but (outside of some very odd cases) it will not end with a\n newline. This means that you can do ``print(tbl)`` and there won't be a\n blank line added at the end.\n\n\nConfiguration Options\n---------------------\nThese options can be set either as keywords passed to the ``Txtble``\nconstructor or as attributes on a ``Txtble`` instance::\n\n tbl = Txtble(data, border=False)\n # Same as:\n tbl = Txtble(data)\n tbl.border = False\n\n``align: Union[str, Sequence[str]] = ()``\n A sequence of alignment specifiers indicating how the contents of each\n column, in order, should be horizontally aligned. The alignment specifiers\n are ``'l'`` (left alignment), ``'c'`` (centered alignment), and ``'r'``\n (right alignment). ``align`` may optionally be set to a single alignment\n specifier to cause all columns to be aligned in that way.\n\n An alignment specifier may optionally include ``'n'`` to cause all numbers\n in the relevant column to be aligned on their decimal point; the ``'l'``,\n ``'c'``, or ``'r'`` then determines how the \"block\" of numbers is aligned as\n a whole (This is generally only relevant if the column also contains a\n string value longer than any of the numbers). An alignment specifier of\n just ``'n'`` is equivalent to ``'ln'`` or ``'nl'``.\n\n``align_fill: str = 'l'``\n If there are more columns than there are entries in ``align``, the extra\n columns will have their alignment set to ``align_fill``.\n\n``border: Union[bool, BorderStyle] = True``\n Whether to draw a border around the edge of the table. ``border`` may\n optionally be set to a ``BorderStyle`` instance to set the characters used\n for drawing the border around the edge of the table. Individual edges can\n be toggled or stylized by setting the ``bottom_border``, ``left_border``,\n ``right_border``, and ``top_border`` options.\n\n``border_style: BorderStyle = ASCII_BORDERS``\n A ``BorderStyle`` instance specifying the characters to use for drawing all\n of the table's borders & rules. The border style can be overridden for\n individual borders by setting their respective options (``border``,\n ``column_border``, etc.) to ``BorderStyle`` instances. See \"BorderStyle_\"\n below for more information.\n\n``bottom_border: Union[bool, BorderStyle, None] = None``\n Whether to draw a border along the bottom edge of the table. The default\n value of `None` means to inherit the value set for ``border``.\n ``bottom_border`` may optionally be set to a ``BorderStyle`` instance to set\n the characters used for drawing the border along the bottom edge.\n\n``break_long_words: bool = True``\n Whether to force a line break in the middle of a word if said word is too\n long for the column's width\n\n``break_on_hyphens: bool = True``\n Whether to break on hyphens in addition to whitespace when wrapping text\n\n``column_border: Union[bool, BorderStyle] = True``\n Whether to draw a vertical rule between individual columns.\n ``column_border`` may optionally be set to a ``BorderStyle`` instance to set\n the characters used for drawing the vertical rules between columns.\n\n``columns: Optional[int] = None``\n An optional positive integer. When set, show exactly the given number of\n columns per row, adding cells with ``row_fill`` and discarding extra cells\n as needed. If ``headers`` is also set, its length must equal ``columns`` or\n else a `ValueError` is raised. Setting both ``columns`` and ``headers``\n causes ``header_fill`` to be ignored.\n\n``dict_fill: Any``\n If a header name does not appear as a key in a `dict`/mapping row, the value\n of ``dict_fill`` will be used for the corresponding cell value. If\n ``dict_fill`` is not set, a missing key will cause a ``KeyError`` to be\n raised.\n\n``header_border: Union[bool, BorderStyle, None] = None``\n Whether to draw a horizontal rule above the data rows, below the header row\n (if any). The default value of `None` means that the border will be drawn\n if & only if ``headers`` is non-`None`. ``header_border`` may optionally be\n set to a ``BorderStyle`` instance to set the characters used for drawing the\n horizontal rule above the data rows.\n\n If ``headers`` is `None` and ``top_border`` is set to a true value (or\n inherits a true value from ``border``), the header border will not be drawn.\n\n``header_fill: Any = None``\n When ``headers`` is non-`None` and ``columns`` is `None`, this option\n determines how rows with more columns than there are headers are handled.\n When ``header_fill=None``, any extra columns are discarded from long rows.\n For all other values, the header row will be extended to the length of the\n longest data row, and the new header cells will contain the ``header_fill``\n value.\n\n``headers: Optional[list] = None``\n An optional list of cell values to display in a row at the top of the table.\n Setting this option also implicitly sets a minimum number of columns per\n row; see ``header_fill`` for allowing extra columns.\n\n If ``headers`` is set to an empty list, ``header_fill`` must be set to a\n non-`None` value or else a `ValueError` will be raised upon trying to render\n the ``Txtble``.\n\n``left_border: Union[bool, BorderStyle, None] = None``\n Whether to draw a border along the left edge of the table. The default\n value of `None` means to inherit the value set for ``border``.\n ``left_border`` may optionally be set to a ``BorderStyle`` instance to set\n the characters used for drawing the border along the left edge.\n\n``left_padding: Union[int, str, None] = None``\n Padding to insert on the left of every table cell. This can be either an\n integer (to insert that many space characters) or a string. If a string, it\n may not contain any newlines. The default value of `None` means to inherit\n the value set for ``padding``.\n\n``len_func: Optional[Callable[[str], int]]``\n The function to use for calculating how many terminal cells wide a string\n is; it should take one string argument and return a width. Returning a\n negative width causes ``Txtble`` to raise an ``IndeterminateWidthError``.\n The default value (also used when set to `None`) is\n ``with_color_stripped(wcwidth.wcswidth)`` (See \"Other_\" below).\n\n``none_str: Any = ''``\n The string to display in place of `None` values (Setting ``none_str=None``\n is the same as setting it to ``'None'``)\n\n``padding: Union[int, str] = 0``\n Padding to insert on the left & right of every table cell. This can be\n either an integer (to insert that many space characters) or a string. If a\n string, it may not contain any newlines. Padding for the left and right of\n table cells can be specified separately via the ``left_padding`` and\n ``right_padding`` options.\n\n``right_border: Union[bool, BorderStyle, None] = None``\n Whether to draw a border along the right edge of the table. The default\n value of `None` means to inherit the value set for ``border``.\n ``right_border`` may optionally be set to a ``BorderStyle`` instance to set\n the characters used for drawing the border along the right edge.\n\n``right_padding: Union[int, str, None] = None``\n Padding to insert on the right of every table cell. This can be either an\n integer (to insert that many space characters) or a string. If a string, it\n may not contain any newlines. The default value of `None` means to inherit\n the value set for ``padding``.\n\n``row_border: Union[bool, BorderStyle] = False``\n Whether to draw horizontal rules between data rows. ``row_border`` may\n optionally be set to a ``BorderStyle`` instance to set the characters used\n for drawing the horizontal rules between data rows.\n\n``row_fill: Any = ''``\n If the rows of a table differ in number of columns, cells are added to the\n shorter rows until they all line up, and the added cells contain\n ``row_fill`` as their value.\n\n``rstrip: bool = True``\n When ``border=False``, setting ``rstrip=False`` will cause the last cell of\n each row to still be padded with trailing whitespace and ``padding`` in\n order to reach the full column width. (Normally, this whitespace and\n ``padding`` is omitted when ``border=False`` as there is no end-of-line\n border to align.) This option is useful if you wish to append text to one\n or more lines of the output and have it appear strictly outside the table.\n\n``top_border: Union[bool, BorderStyle, None] = None``\n Whether to draw a border along the top edge of the table. The default value\n of `None` means to inherit the value set for ``border``. ``top_border`` may\n optionally be set to a ``BorderStyle`` instance to set the characters used\n for drawing the border along the top edge.\n\n``valign: Union[str, Sequence[str]] = ()``\n A sequence of vertical alignment specifiers indicating how the contents of\n each column, in order, should be vertically aligned. The vertical alignment\n specifiers are ``'t'`` (top alignment), ``'m'`` (middle alignment), and\n ``'b'`` (bottom alignment). ``valign`` may optionally be set to a single\n vertical alignment specifier to cause all columns to be vertically aligned\n in that way.\n\n``valign_fill: str = 't'``\n If there are more columns than there are entries in ``valign``, the extra\n columns will have their vertical alignment set to ``valign_fill``.\n\n``width_fill: Optional[int] = None``\n If there are more columns than there are entries in ``widths``, the extra\n columns will have their widths set to ``width_fill``.\n\n``widths: Union[int, Sequence[Optional[int]], None] = ()``\n A sequence of integers specifying the width of each column, in order. Lines\n wider than the given width will be wrapped; the wrapping can be configured\n via the ``break_long_words`` and ``break_on_hyphens`` options. A width of\n `None` disables wrapping for that column and causes the column's width to be\n set to the width of the longest line. ``widths`` may optionally be set to a\n single width to cause all columns to be that wide.\n\n``wrap_func: Optional[Callable[[str, int], Iterable[str]]] = None``\n The function to use for wrapping long lines; it should take a string and a\n width and return an iterable of strings. The default value of `None` causes\n a custom function to be used that properly handles fullwidth characters,\n ANSI color escape sequences, etc.; if your table contains such strings, any\n user-supplied ``wrap_func`` must be able to handle them as well. When\n ``wrap_func`` is set to a user-supplied value, the ``break_long_words`` and\n ``break_on_hyphens`` options are ignored.\n\n\n``BorderStyle``\n---------------\nThe ``BorderStyle`` class is a `namedtuple` listing the strings to use for\ndrawing a table's borders & rules. Its attributes are:\n\n.. csv-table::\n :header: Attribute,Description,Example\n\n ``hline``,horizontal line,\u2500\n ``vline``,vertical line,\u2502\n ``ulcorner``,upper-left box corner,\u250c\n ``urcorner``,upper-right box corner,\u2510\n ``llcorner``,lower-left box corner,\u2514\n ``lrcorner``,lower-right box corner,\u2518\n ``vrtee``,tee pointing right,\u251c\n ``vltee``,tee pointing left,\u2524\n ``dhtee``,tee pointing down,\u252c\n ``uhtee``,tee pointing up,\u2534\n ``plus``,cross/four-way joint,\u253c\n\n``txtble`` provides the following predefined ``BorderStyle`` instances:\n\n``ASCII_BORDERS``\n The default border style. Draws borders using only the ASCII characters\n ``-``, ``|``, and ``+``::\n\n +-+-+\n |A|B|\n +-+-+\n |C|D|\n +-+-+\n\n``ASCII_EQ_BORDERS``\n Like ``ASCII_BORDERS``, but uses ``=`` in place of ``-``::\n\n +=+=+\n |A|B|\n +=+=+\n |C|D|\n +=+=+\n\n``LIGHT_BORDERS``\n Uses the light box drawing characters::\n\n \u250c\u2500\u252c\u2500\u2510\n |A|B|\n \u251c\u2500\u253c\u2500\u2524\n |C|D|\n \u2514\u2500\u2534\u2500\u2518\n\n``HEAVY_BORDERS``\n Uses the heavy box drawing characters::\n\n \u250f\u2501\u2533\u2501\u2513\n \u2503A\u2503B\u2503\n \u2523\u2501\u254b\u2501\u252b\n \u2503C\u2503D\u2503\n \u2517\u2501\u253b\u2501\u251b\n\n``DOUBLE_BORDERS``\n Uses the double box drawing characters::\n\n \u2554\u2550\u2566\u2550\u2557\n \u2551A\u2551B\u2551\n \u2560\u2550\u256c\u2550\u2563\n \u2551C\u2551D\u2551\n \u255a\u2550\u2569\u2550\u255d\n\n``DOT_BORDERS``\n Uses ``\u22ef``, ``\u22ee``, and ``\u00b7``::\n\n \u00b7\u22ef\u00b7\u22ef\u00b7\n \u22eeA\u22eeB\u22ee\n \u00b7\u22ef\u00b7\u22ef\u00b7\n \u22eeC\u22eeD\u22ee\n \u00b7\u22ef\u00b7\u22ef\u00b7\n\nIf you define your own custom instances of ``BorderStyle``, they must adhere to\nthe following rules:\n\n- The ``hline`` string must be exactly one terminal column wide (the same width\n as a space character).\n- All strings other than ``hline`` must be the same width.\n- No string may contain a newline.\n\n\nOther\n-----\n\n``IndeterminateWidthError``\n Subclass of ``ValueError``. Raised when a string is reported as having\n negative/indeterminate width. (For the default ``len_func``, this happens\n when the string contains a DEL or a C0 or C1 control character other than a\n tab, newline, or ANSI color escape sequence.) The string in question is\n available as the exception's ``string`` attribute.\n\n``NumericWidthOverflowError``\n Subclass of ``ValueError``. Raised when a column has a non-`None` width,\n the column's ``align`` value contains ``'n'``, and aligning the numbers in\n the column along their decimal points would cause one or more cells to\n exceed the column's width.\n\n``UnterminatedColorError``\n Subclass of ``ValueError``. Raised by ``with_color_stripped`` upon\n encountering an ANSI color escape sequence that is not eventually terminated\n by a reset/sgr0 sequence. The string in question is available as the\n exception's ``string`` attribute.\n\n``with_color_stripped``\n A function decorator for applying to ``len`` or imitators thereof that\n strips ANSI color sequences from a single string argument before passing it\n on. If any color sequences are not followed by a reset sequence, an\n ``UnterminatedColorError`` is raised.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Yet another plain-text table typesetter",
"version": "0.12.1",
"project_urls": {
"Bug Tracker": "https://github.com/jwodder/txtble/issues",
"Homepage": "https://github.com/jwodder/txtble",
"Source Code": "https://github.com/jwodder/txtble"
},
"split_keywords": [
"box-drawing",
"grid",
"table"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d4727db433422de21741bf37c33936b691898882946c1efbbbf46be04ab7530a",
"md5": "de57e5a09b34ff8d13a72c6b4441285f",
"sha256": "e42fe75a8a8a71108bda88b02618d9427a9aa582258132c567d84db669288ffd"
},
"downloads": -1,
"filename": "txtble-0.12.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "de57e5a09b34ff8d13a72c6b4441285f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 18627,
"upload_time": "2023-10-10T19:23:33",
"upload_time_iso_8601": "2023-10-10T19:23:33.973886Z",
"url": "https://files.pythonhosted.org/packages/d4/72/7db433422de21741bf37c33936b691898882946c1efbbbf46be04ab7530a/txtble-0.12.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cc9789e95da96d127052ce2ba6f3084c2733a93b43b7d8977f9f83067d2b56e1",
"md5": "1317a185749197b136e906045fa0440d",
"sha256": "d13cd505df2cdc0fe9277e000de30ca5a7a993d4ab9f6e37eeace880fc284bba"
},
"downloads": -1,
"filename": "txtble-0.12.1.tar.gz",
"has_sig": false,
"md5_digest": "1317a185749197b136e906045fa0440d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 49329,
"upload_time": "2023-10-10T19:23:35",
"upload_time_iso_8601": "2023-10-10T19:23:35.895480Z",
"url": "https://files.pythonhosted.org/packages/cc/97/89e95da96d127052ce2ba6f3084c2733a93b43b7d8977f9f83067d2b56e1/txtble-0.12.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-10 19:23:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jwodder",
"github_project": "txtble",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "txtble"
}
JSON
