Metadata-Version: 2.4
Name: cs-printt
Version: 20261016
Summary: Print text tables, in the terminal or to a file, using `printt()` and its supporting functions.
Keywords: python3
Author-email: Cameron Simpson <cs@cskk.id.au>
Description-Content-Type: text/markdown
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Text Processing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Requires-Dist: cs.ascii_art>=20260403
Requires-Dist: cs.deco>=20261016
Requires-Dist: cs.lex>=20261016
Requires-Dist: cs.seq>=20260912
Requires-Dist: typeguard
Project-URL: MonoRepo Commits, https://bitbucket.org/cameron_simpson/css/commits/branch/main
Project-URL: Monorepo Git Mirror, https://github.com/cameron-simpson/css
Project-URL: Monorepo Hg/Mercurial Mirror, https://hg.sr.ht/~cameron-simpson/css
Project-URL: Source, https://github.com/cameron-simpson/css/blob/main/lib/python/cs/printt.py

Print text tables, in the terminal or to a file, using `printt()` and its supporting functions.



Short summary:


* `flatten_table_rows`: Flatten a list of table rows or tuples-of-table-rows into a `(flat_rows,attach)` 2 -tuple where `flat_rows` is a list lof list-of-str rows and `attach` is a list of indices into `flat_rows` which are attachment points. Nested subtables are connected with lines.


* `printt`: A wrapper for `tabulate()` to print the results. Each positional argument is a table row.


* `row_cells`: Turn a row of items into a grid.


* `tabulate`: A generator yielding lines of values from `rows` aligned in columns.


* `tabulate_as_str`: The default function to return the printable form of an object `obj` for use in a table in `tabulate()`.

# Functions

## flatten_table_rows(table_rows: list, as_str: Optional[Callable[[Any], str]] = None) -> tuple[list[list[str]], list[int]]

Flatten a list of table rows or tuples-of-table-rows into a
`(flat_rows,attach)` 2 -tuple where `flat_rows` is a list lof
list-of-str rows and `attach` is a list of indices into `flat_rows`
which are attachment points.
Nested subtables are connected with lines.

The default `as_str` comes from `tabulate.as_str`.

This is a helper function for `tabulate()`, itself a helper
function for `printt()`.

## printt(*table, file=None, flush=False, indent='', print_func=None, **tabulate_kw)

A wrapper for `tabulate()` to print the results.
Each positional argument is a table row.

Parameters:
* `file`: optional output file, passed to `print_func`
* `flush`: optional flush flag, passed to `print_func`
* `indent`: optional leading indent for the output lines;
  if this is an `int` instead of a `str`, use that many spaces
* `print_func`: optional `print()` function, default `builtins.print`
Other keyword arguments are passed to `tabulate()`.

## row_cells(row: Union[str, Sequence[Any]], as_str: Optional[Callable[[Any], str]] = None) -> list[list[str]]

Turn a row of items into a grid.

This is a helper function for `flatten_table_rows()`.

Process:
- convert each non-`str` item into a string using `as_str`
- break each string into lines
- make enough rows to cover the tallest column

The default `as_str` comes from `tabulate.as_str`.

Example:

    >>> for cells in row_cells(['col1', 'multi\nline\ntext', 'goes\nhere', 'and\nhere']):
    ...     print(cells)
    ...
    ['col1', 'multi', 'goes', 'and']
    ['', 'line', 'here', 'here']
    ['', 'text', '', '']

## tabulate(*rows, sep='  ', as_str: Optional[Callable[[Any], str]] = None) -> Iterable[str]

A generator yielding lines of values from `rows` aligned in columns.

Usually, each row in rows is a `list` of strings. Non-`str` objects are
promoted to `str` via the `as_str` function.
If the strings contain newlines they will be split into
subrows.

A row may also be a `tuple`, indicating a subtable, which
will be embedded with its column 0 indented and joined up
with lines to indicate structure.

A row may also be a mapping, in which case it is transformed
into multiple rows of `[key,value]` from the `row.items()`,
sorted by `key` if possible.

The default `as_str` function is `TabulatePrettyPrinter().pformat`;
the `TabulatePrettyPrinter` class is a subclass of `pprint.PrettyPrinter`
which also understands `datetime.date` and `datetime.datetime` objects.
This is exposed as `tabulate.default_as_str`.

Example:

    >>> for row in tabulate(
    ...    ['one col'],
    ...    ['three', 'column', 'row'],
    ...    ['row3', 'multi\nline\ntext', 'goes\nhere', 'and\nhere'],
    ...    ['two', 'cols'],
    ...    (
    ...        ['subrow', 'description'],
    ...        (["0nd", "subtable"],),
    ...        (
    ...            ['inner', 'table'],
    ...            ['', 'unattached'],
    ...            ['inner\nbottom', 'last inner row'],
    ...        ),
    ...        (["2nd\nbbb", "subtable"],),
    ...        ['subrow2'],
    ...     ),
    ...     ['one col'],
    ...     ['three', 'column', 'row'],
    ...     ['row3', 'multi\nline\ntext', 'goes\nhere', 'and\nhere'],
    ...     ['two', 'cols'],
    ...     (
    ...        ['subrow','description'],
    ...        (
    ...           ['inner','table'],
    ...           ['','unattached'],
    ...           ['inner\nbottom','last inner row'],
    ...        ),
    ...     ),
    ...     ['subrow2'],
    ... ):
    ...     print(row)
    ...
    one col
    three       column          row
    row3        multi           goes  and
                line            here  here
                text
    two         cols
    ├─subrow    description
    │ ╰─0nd     subtable
    │ ╭─inner   table
    │ │         unattached
    │ ╰─inner   last inner row
    │   bottom
    │ ◯─2nd     subtable
    │   bbb
    ╰─subrow2
    one col
    three       column          row
    row3        multi           goes  and
                line            here  here
                text
    two         cols
    ╰─subrow    description
      ├─inner   table
      │         unattached
      ╰─inner   last inner row
        bottom
    subrow2
    >>>

## tabulate_as_str(obj, *, compact=True, sort_dicts=True, **pformat_kw) -> str

The default function to return the printable form of an object `obj`
for use in a table in `tabulate()`.

This function calls `pprint.pformat()` except for certain specially handled types:
- `date` and `datetime`: their ISO8601 format
- `PIL.Image.Image`: is cs.imageutils is available, a SIXEL presentation
