Metadata-Version: 2.5
Name: printable
Version: 0.5.1
Summary: CLI and functions help for printing tabular data
Requires-Python: >=3.10
Requires-Dist: pyyaml>=6
Requires-Dist: wcwidth>=0.2.13
Description-Content-Type: text/markdown

# Printable

CLI and functions help for printing tabular data.

## Install

`pip3 install printable`

## Rendering Engines

Two engines render tables: `python` (pure Python) and `column` (a ctypes binding of the compiled util-linux column command). By default (`auto`), the column engine is used when no `--grid` is set, and falls back to the python engine if the shared library is missing; grid styles always use the python engine. Select explicitly with `-e python|column|auto`.

Width calculation uses the native library when available and falls back to pure Python otherwise. The native width path has an ASCII fast path and batches all cells into one C call. The current benchmark uses 5000×6 mixed zh-en rows on an Apple M4:

| engine           | input    | median (ms) | speedup |
| ---------------- | -------- | ----------: | -------: |
| Python           | rows     |       80.32 |    1.00x |
| Python + C width | rows     |       28.37 |    2.83x |
| Python column    | `str`    |       14.62 |    5.49x |
| Python column    | `bytes`  |       14.51 |    5.53x |
| Go column        | `[]byte` |       14.10 |    5.70x |

Python uses two warmups and ten repetitions; Go uses `go test -bench` with three runs. The standalone Python C-width call is 2.45 ms for the same 5000×6 cells; Go `BenchmarkWidthsOf` is 1.13 ms/op, 651–706 MB/s, with 17 allocations. The Go render benchmark reports about 811 KB and 5 allocations per render. The `str`/`bytes` difference is the Python UTF-8 input conversion cost; with pre-encoded input, both Go and Python spend most of the time in the shared C implementation.

## Usage Example

```python
from printable import readable

print(readable(list_of_dict, grid='full'))
```

```
$ printable -t csv -f samples/sample.csv
 symbol     desp      last    change   changeper  turnover  changesign  lastupdate
 HSI        恆指      26623   -468     1.73%      802億     -           2018/10/04 16:09
 HSCEI      國指      10547   -239     2.21%      257億     -           2018/10/04 16:08
 000001.SH  上證指數  2821    29       1.06%      1254億    +           2018/09/28 15:10
 000300.SH  滬深 300  3438    35       1.04%      949億     +           2018/09/28 15:10
 USDHKD     港匯      7.8337  -0.0037  -0.0472%             -

$ printable -t csv -f samples/sample.csv --grid inner
 symbol    │ desp     │ last   │ change  │ changeper │ turnover │ changesign │ lastupdate
───────────┼──────────┼────────┼─────────┼───────────┼──────────┼────────────┼──────────────────
 HSI       │ 恆指     │ 26623  │ -468    │ 1.73%     │ 802億    │ -          │ 2018/10/04 16:09
───────────┼──────────┼────────┼─────────┼───────────┼──────────┼────────────┼──────────────────
 HSCEI     │ 國指     │ 10547  │ -239    │ 2.21%     │ 257億    │ -          │ 2018/10/04 16:08
───────────┼──────────┼────────┼─────────┼───────────┼──────────┼────────────┼──────────────────
 000001.SH │ 上證指數 │ 2821   │ 29      │ 1.06%     │ 1254億   │ +          │ 2018/09/28 15:10
───────────┼──────────┼────────┼─────────┼───────────┼──────────┼────────────┼──────────────────
 000300.SH │ 滬深 300 │ 3438   │ 35      │ 1.04%     │ 949億    │ +          │ 2018/09/28 15:10
───────────┼──────────┼────────┼─────────┼───────────┼──────────┼────────────┼──────────────────
 USDHKD    │ 港匯     │ 7.8337 │ -0.0037 │ -0.0472%  │          │ -          │

$ printable -t csv -f samples/sample.csv --grid full
┌───────────┬──────────┬────────┬─────────┬───────────┬──────────┬────────────┬──────────────────┐
│ symbol    │ desp     │ last   │ change  │ changeper │ turnover │ changesign │ lastupdate       │
├───────────┼──────────┼────────┼─────────┼───────────┼──────────┼────────────┼──────────────────┤
│ HSI       │ 恆指     │ 26623  │ -468    │ 1.73%     │ 802億    │ -          │ 2018/10/04 16:09 │
├───────────┼──────────┼────────┼─────────┼───────────┼──────────┼────────────┼──────────────────┤
│ HSCEI     │ 國指     │ 10547  │ -239    │ 2.21%     │ 257億    │ -          │ 2018/10/04 16:08 │
├───────────┼──────────┼────────┼─────────┼───────────┼──────────┼────────────┼──────────────────┤
│ 000001.SH │ 上證指數 │ 2821   │ 29      │ 1.06%     │ 1254億   │ +          │ 2018/09/28 15:10 │
├───────────┼──────────┼────────┼─────────┼───────────┼──────────┼────────────┼──────────────────┤
│ 000300.SH │ 滬深 300 │ 3438   │ 35      │ 1.04%     │ 949億    │ +          │ 2018/09/28 15:10 │
├───────────┼──────────┼────────┼─────────┼───────────┼──────────┼────────────┼──────────────────┤
│ USDHKD    │ 港匯     │ 7.8337 │ -0.0037 │ -0.0472%  │          │ -          │                  │
└───────────┴──────────┴────────┴─────────┴───────────┴──────────┴────────────┴──────────────────┘

$ printable -t csv -f samples/sample.csv --grid markdown
| symbol    | desp     | last   | change  | changeper | turnover | changesign | lastupdate       |
|-----------|----------|--------|---------|-----------|----------|------------|------------------|
| HSI       | 恆指     | 26623  | -468    | 1.73%     | 802億    | -          | 2018/10/04 16:09 |
| HSCEI     | 國指     | 10547  | -239    | 2.21%     | 257億    | -          | 2018/10/04 16:08 |
| 000001.SH | 上證指數 | 2821   | 29      | 1.06%     | 1254億   | +          | 2018/09/28 15:10 |
| 000300.SH | 滬深 300 | 3438   | 35      | 1.04%     | 949億    | +          | 2018/09/28 15:10 |
| USDHKD    | 港匯     | 7.8337 | -0.0037 | -0.0472%  |          | -          |                  |
```
