flexablelib 3.0.3__tar.gz → 3.2.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {flexablelib-3.0.3 → flexablelib-3.2.0}/CHANGELOG.md +57 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/MANIFEST.in +1 -0
- {flexablelib-3.0.3/flexablelib.egg-info → flexablelib-3.2.0}/PKG-INFO +131 -2
- {flexablelib-3.0.3 → flexablelib-3.2.0}/README.md +130 -1
- flexablelib-3.2.0/examples/dashboard.py +178 -0
- flexablelib-3.2.0/flexablelib/__init__.py +12 -0
- flexablelib-3.2.0/flexablelib/layout.py +1894 -0
- flexablelib-3.2.0/flexablelib/screen.py +247 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/flexablelib/table.py +540 -56
- flexablelib-3.2.0/flexablelib/widgets.py +624 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0/flexablelib.egg-info}/PKG-INFO +131 -2
- {flexablelib-3.0.3 → flexablelib-3.2.0}/flexablelib.egg-info/SOURCES.txt +6 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/package.json +1 -1
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/conftest.py +14 -10
- flexablelib-3.2.0/tests/test_v310_layout.py +573 -0
- flexablelib-3.2.0/tests/test_v320_tui.py +1013 -0
- flexablelib-3.0.3/flexablelib/__init__.py +0 -6
- {flexablelib-3.0.3 → flexablelib-3.2.0}/LICENSE +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/flexablelib/_speedups.c +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/flexablelib/_width_tables.h +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/flexablelib/box_topology.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/flexablelib/cells.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/flexablelib/colors.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/flexablelib/columns.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/flexablelib/fast.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/flexablelib/merges.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/flexablelib/options.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/flexablelib/py.typed +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/flexablelib/readers.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/flexablelib/style_compositions.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/flexablelib/table_strings.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/flexablelib/text_width.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/flexablelib/utils.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/flexablelib/writers.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/flexablelib.egg-info/dependency_links.txt +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/flexablelib.egg-info/requires.txt +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/flexablelib.egg-info/top_level.txt +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/pytest.ini +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/setup.cfg +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/setup.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/style_examples.md +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/helpers.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_align_indicators.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_box_topology.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_cells.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_columns.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_excel.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_features.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_issues.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_merge_edge_matrix.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_merge_fill.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_merges.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_public_api_edges.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_readme_examples.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_stress_matrix.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_style_line_widths.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_styles.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_text_width.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_two_pass_measurement.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_upstream_issues.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_v2021_fixes.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_v210_rows_copy.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_v2110_fixes.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_v211_fixes.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_v213_features.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_v214_features.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_v215_features.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_v216_features.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_v217_features.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_v218_features.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_v219_coverage.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_v219_fixes.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_v220_exports.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_v221_fixes.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_v222_fixes.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_v223_fixes.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_v224_fixes.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_v230_none.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_v231_fixes.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_v232_merge_ansi.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_v300_style_names.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tools/benchmark.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tools/generate_width_tables.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tools/readme_gallery.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tools/stress_matrix.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tools/style_examples.py +0 -0
- {flexablelib-3.0.3 → flexablelib-3.2.0}/tools/text_to_png.py +0 -0
|
@@ -2,6 +2,63 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
|
|
4
4
|
|
|
5
|
+
## [3.2.0] - 2026-11-11
|
|
6
|
+
|
|
7
|
+
### Added
|
|
8
|
+
- `Grid(column_widths=[...])`: fixed, `'auto'`, `'Nfr'`, `'N%'` and
|
|
9
|
+
`(size, min, max)` columns, or a dict of layouts per width (breakpoints).
|
|
10
|
+
Columns that cannot fit stack; `collapse_below` stacks below a width.
|
|
11
|
+
- `GridCell(row_span=n)`, with CSS-style sparse auto-placement, plus
|
|
12
|
+
`valign`, `title`, `title_align`, `color`, `stretch`, `padding` and
|
|
13
|
+
`hide_below` (hide a cell on narrow terminals). `Grid.add()` takes them.
|
|
14
|
+
- `Grid(border=...)`: one shared frame around and between the cells
|
|
15
|
+
(`single`, `rounded`, `double`, `heavy`, `ascii`) with correct junctions
|
|
16
|
+
for spans and row spans, a title per cell set into its top border,
|
|
17
|
+
`border_color`, `title_color` and cell `padding`.
|
|
18
|
+
- `Grid.render(width, height)` / `Grid(height=...)` and `row_heights`
|
|
19
|
+
(fixed, `auto`, fractions, bounds, per-width dicts): exact heights, spare
|
|
20
|
+
lines to fraction rows, overflow trimmed bottom-up with the frame kept
|
|
21
|
+
closed. Children that take a height (grids, `LogView`...) fill their slot.
|
|
22
|
+
- Widgets: `ProgressBar` (eighth-cell precision, thresholds, value formats),
|
|
23
|
+
`Sparkline`, `BarChart`, `StatusBar`, `KeyHints`, `LogView` (levels
|
|
24
|
+
coloured, tail to height), `Text` and `Rule`.
|
|
25
|
+
- `Screen`: header and footer pinned to the terminal's edges, the body gets
|
|
26
|
+
the lines in between. `Live`: redraw in place on the alternate screen, or
|
|
27
|
+
plain frames on a pipe; `run(step, interval, iterations)`.
|
|
28
|
+
- `examples/dashboard.py`: a complete terminal dashboard (three layouts by
|
|
29
|
+
width, themes, borders, `--live`).
|
|
30
|
+
|
|
31
|
+
### Unchanged
|
|
32
|
+
- A grid without the new options renders exactly as in 3.1.0.
|
|
33
|
+
|
|
34
|
+
## [3.1.0] - 2026-11-11
|
|
35
|
+
|
|
36
|
+
### Added
|
|
37
|
+
- `Card`: one record in a frame, in any of the 54 styles and the 15
|
|
38
|
+
themes. The title goes into the top border (`╭─ Title ───╮`) when the
|
|
39
|
+
style draws one; subtitle, `label value` fields (or a grid of tiles with
|
|
40
|
+
`field_columns=2`/`'auto'`), any renderable as `body`, footer and
|
|
41
|
+
`[ action ]` chips. Colours fill the card frame to frame; panel and
|
|
42
|
+
shadow work as on tables.
|
|
43
|
+
- `Grid` and `GridCell`: lay cards, tables, text and other grids out in
|
|
44
|
+
columns that reflow with the width (`columns='auto'` or n, `min_width`,
|
|
45
|
+
spans, nesting, equal-height rows) -- a grid of cards or a whole terminal
|
|
46
|
+
screen.
|
|
47
|
+
- `Table.render(width)` / `responsive=True`: the table when it fits, then
|
|
48
|
+
squeezed, then without low-priority columns (`column_priority`), then as
|
|
49
|
+
cards (`to_cards()`) in a responsive grid. `breakpoints`,
|
|
50
|
+
`card_options`, `render_mode()` and `natural_width()`.
|
|
51
|
+
- `Table.subtitle`, `title_position='border'`, `caption_position='border'`,
|
|
52
|
+
`title_align`, `title_color`. A border title never covers a corner or a
|
|
53
|
+
column junction; it falls back to a line above.
|
|
54
|
+
- `flexablelib.layout.wrap_panel` / `add_shadow`, shared by tables and
|
|
55
|
+
cards.
|
|
56
|
+
|
|
57
|
+
### Fixed
|
|
58
|
+
- Columns in `hide_columns` no longer count toward the width the fit pass
|
|
59
|
+
has to save, so a table that fits once they are hidden is no longer
|
|
60
|
+
squeezed as if they were still drawn.
|
|
61
|
+
|
|
5
62
|
## [3.0.3] - 2026-11-11
|
|
6
63
|
|
|
7
64
|
### Fixed
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: flexablelib
|
|
3
|
-
Version: 3.0
|
|
3
|
+
Version: 3.2.0
|
|
4
4
|
Summary: Fast, dependency-free terminal tables for Python: 54 border styles, ANSI colors, cell merges, decimal alignment, width fitting, and CSV/Markdown/HTML/Excel/LaTeX I/O.
|
|
5
5
|
Home-page: https://github.com/Opus-Perpetuus/flexablelib
|
|
6
6
|
Author: Benjamin Ramirez
|
|
@@ -504,6 +504,131 @@ table.merge_cells(0, 0, 2, 2, value='Total', align='r')
|
|
|
504
504
|
A merge never widens the table -- columns are still sized by their unmerged
|
|
505
505
|
content -- so text longer than its span is truncated.
|
|
506
506
|
|
|
507
|
+
## Cards, grids, responsive tables and terminal interfaces
|
|
508
|
+
|
|
509
|
+
`Card` draws one record in a frame, in any of the table styles. The title goes
|
|
510
|
+
into the top border when the style draws one:
|
|
511
|
+
|
|
512
|
+
```python
|
|
513
|
+
from flexablelib import Card
|
|
514
|
+
|
|
515
|
+
card = Card(title='Ana', subtitle='Norte',
|
|
516
|
+
fields={'Edad': 28, 'Ciudad': 'Guadalajara'},
|
|
517
|
+
footer='actualizado hoy')
|
|
518
|
+
print(card.render(width=30))
|
|
519
|
+
```
|
|
520
|
+
|
|
521
|
+
```
|
|
522
|
+
╭─ Ana ──────────────────────╮
|
|
523
|
+
│ Norte │
|
|
524
|
+
├────────────────────────────┤
|
|
525
|
+
│ Edad 28 │
|
|
526
|
+
│ Ciudad Guadalajara │
|
|
527
|
+
├────────────────────────────┤
|
|
528
|
+
│ actualizado hoy │
|
|
529
|
+
╰────────────────────────────╯
|
|
530
|
+
```
|
|
531
|
+
|
|
532
|
+
`field_columns=2` (or `'auto'`) lays the fields out as a grid of tiles, and
|
|
533
|
+
`actions` adds `[ Action ]` chips:
|
|
534
|
+
|
|
535
|
+
```
|
|
536
|
+
╭─ Pedido 42 ────────────────────╮
|
|
537
|
+
│ Cliente Total │
|
|
538
|
+
│ José $1,200 │
|
|
539
|
+
│ Estado Fecha │
|
|
540
|
+
│ Enviado 11/11 │
|
|
541
|
+
├────────────────────────────────┤
|
|
542
|
+
│ [ Ver ] [ Editar ] │
|
|
543
|
+
╰────────────────────────────────╯
|
|
544
|
+
```
|
|
545
|
+
|
|
546
|
+
Cards take `style_name`, `theme` (the table themes), `border_color`,
|
|
547
|
+
`title_color`, `label_color`, `value_colors`, `color` (a background for the
|
|
548
|
+
whole card), `zebra`, `panel` and `shadow`.
|
|
549
|
+
|
|
550
|
+
`table.render(width)` makes a table responsive: the normal table when it fits,
|
|
551
|
+
without its low-priority columns next, squeezed and wrapped after that, and
|
|
552
|
+
one card per row when nothing else fits. `width` defaults to
|
|
553
|
+
`max_width`, then the terminal width; `responsive=True` makes `print(table)` do
|
|
554
|
+
the same.
|
|
555
|
+
|
|
556
|
+
```python
|
|
557
|
+
table.title, table.title_position = 'Personas', 'border'
|
|
558
|
+
table.column_priority = {'Correo': 3} # hidden first
|
|
559
|
+
table.card_options = {'subtitle_field': 'Grupo', 'fields': ['Edad', 'Ciudad']}
|
|
560
|
+
table.render(width=80) # table
|
|
561
|
+
table.render(width=46) # table without "Correo"
|
|
562
|
+
table.render(width=30) # cards
|
|
563
|
+
```
|
|
564
|
+
|
|
565
|
+
```
|
|
566
|
+
╭─────────┬────────┬──────┬─ Personas ──┬──────────────────╮
|
|
567
|
+
│ Nombre │ Grupo │ Edad │ Ciudad │ Correo │
|
|
568
|
+
├─────────┼────────┼──────┼─────────────┼──────────────────┤
|
|
569
|
+
│ Ana │ Norte │ 28 │ Guadalajara │ ana@example.com │
|
|
570
|
+
│ Luna 🌸 │ Centro │ 22 │ Mérida │ luna@example.com │
|
|
571
|
+
╰─────────┴────────┴──────┴─────────────┴──────────────────╯
|
|
572
|
+
|
|
573
|
+
Personas
|
|
574
|
+
╭─ Ana ──────────────────────╮
|
|
575
|
+
│ Norte │
|
|
576
|
+
├────────────────────────────┤
|
|
577
|
+
│ Edad 28 │
|
|
578
|
+
│ Ciudad Guadalajara │
|
|
579
|
+
╰────────────────────────────╯
|
|
580
|
+
```
|
|
581
|
+
|
|
582
|
+
`Grid` places cards, tables, text and other grids in columns that reflow with
|
|
583
|
+
the width -- a grid of cards or a whole terminal screen:
|
|
584
|
+
|
|
585
|
+
```python
|
|
586
|
+
from flexablelib import Grid, GridCell
|
|
587
|
+
|
|
588
|
+
Grid(table.to_cards(), min_width=28).render(width=100) # 3 columns, 2 at 62, 1 at 40
|
|
589
|
+
Grid([GridCell('Ventas de noviembre', span=3),
|
|
590
|
+
GridCell(table, span=2), Grid(cards, columns=1)], columns=3)
|
|
591
|
+
```
|
|
592
|
+
|
|
593
|
+
### Terminal interfaces
|
|
594
|
+
|
|
595
|
+
Since 3.2.0 a grid can size its columns (`12`, `'auto'`, `'2fr'`, `'30%'`,
|
|
596
|
+
bounds, or one layout per width), span rows, share one border with proper
|
|
597
|
+
junctions and a title per cell, and fill an exact height. Widgets --
|
|
598
|
+
`ProgressBar`, `Sparkline`, `BarChart`, `StatusBar`, `KeyHints`, `LogView`,
|
|
599
|
+
`Text`, `Rule` -- drop into it, `Screen` pins a header and footer to the
|
|
600
|
+
terminal's edges and `Live` redraws in place:
|
|
601
|
+
|
|
602
|
+
```python
|
|
603
|
+
from flexablelib import (Grid, GridCell, LogView, ProgressBar, Sparkline,
|
|
604
|
+
Text)
|
|
605
|
+
|
|
606
|
+
Grid([
|
|
607
|
+
GridCell(Text('▸ Resumen\n Ventas\n Ajustes'), row_span=2, title='Menú'),
|
|
608
|
+
GridCell(ProgressBar(72, label='CPU', thresholds={0.7: 'yellow'}),
|
|
609
|
+
title='Recursos'),
|
|
610
|
+
GridCell(Sparkline([3, 5, 2, 8, 6, 9, 4, 7], label='rps', show_last=True),
|
|
611
|
+
title='Tráfico'),
|
|
612
|
+
GridCell(LogView(['10:00 INFO arranque', '10:01 WARN lento']), span=2,
|
|
613
|
+
title='Eventos'),
|
|
614
|
+
], column_widths=[14, '1fr', '1fr'], border='rounded').render(width=64)
|
|
615
|
+
```
|
|
616
|
+
|
|
617
|
+
```
|
|
618
|
+
╭─ Menú ───────┬─ Recursos ────────────┬─ Tráfico ─────────────╮
|
|
619
|
+
│ ▸ Resumen │ CPU ████████▋░░░ 72% │ rps ▂▄▁▇▅█▃▆ 7 │
|
|
620
|
+
│ Ventas ├─ Eventos ─────────────┴───────────────────────┤
|
|
621
|
+
│ Ajustes │ 10:00 INFO arranque │
|
|
622
|
+
│ │ 10:01 WARN lento │
|
|
623
|
+
╰──────────────┴───────────────────────────────────────────────╯
|
|
624
|
+
```
|
|
625
|
+
|
|
626
|
+
A whole dashboard with a sidebar, KPI cards, a coloured table with merges,
|
|
627
|
+
bars, sparklines and a log: [examples/dashboard.py](https://github.com/Opus-Perpetuus/flexablelib/blob/main/examples/dashboard.py)
|
|
628
|
+
(`python examples/dashboard.py --live 10`).
|
|
629
|
+
|
|
630
|
+
More in [docs/LAYOUT.md](https://github.com/Opus-Perpetuus/flexablelib/blob/main/docs/LAYOUT.md).
|
|
631
|
+
|
|
507
632
|
## Notes
|
|
508
633
|
|
|
509
634
|
- A column named ``"i"`` does not collide with the index column (`utils.IndexColumnTitle`).
|
|
@@ -517,14 +642,18 @@ Open work and the issue map: [docs/ISSUES.md](https://github.com/Opus-Perpetuus/
|
|
|
517
642
|
```
|
|
518
643
|
flexablelib/ # GitHub repository
|
|
519
644
|
├── flexablelib/ the Python package (no runtime dependencies)
|
|
520
|
-
│ ├── __init__.py public API: Table,
|
|
645
|
+
│ ├── __init__.py public API: Table, Card, Grid, widgets, Screen, Live
|
|
521
646
|
│ ├── table.py the Table class — state and render orchestration
|
|
647
|
+
│ ├── layout.py Card, Grid, GridCell, panel and shadow
|
|
648
|
+
│ ├── widgets.py ProgressBar, Sparkline, BarChart, StatusBar, LogView…
|
|
649
|
+
│ ├── screen.py Screen (sticky header/footer) and Live (redraw)
|
|
522
650
|
│ ├── columns.py type inference, alignment, column widths
|
|
523
651
|
│ ├── style_compositions.py the 54 border styles, as data
|
|
524
652
|
│ ├── table_strings.py separator lines and data rows
|
|
525
653
|
│ ├── cells.py cell padding, justification, wrapping
|
|
526
654
|
│ ├── options.py constants and defaults
|
|
527
655
|
│ └── utils.py type predicates and small helpers
|
|
656
|
+
├── examples/ runnable demos (dashboard.py)
|
|
528
657
|
├── tests/ pytest suite — see ARCHITECTURE.md#testing
|
|
529
658
|
├── docs/ issue history and design notes
|
|
530
659
|
├── logos/ brand assets — see logos/README.md
|
|
@@ -439,6 +439,131 @@ table.merge_cells(0, 0, 2, 2, value='Total', align='r')
|
|
|
439
439
|
A merge never widens the table -- columns are still sized by their unmerged
|
|
440
440
|
content -- so text longer than its span is truncated.
|
|
441
441
|
|
|
442
|
+
## Cards, grids, responsive tables and terminal interfaces
|
|
443
|
+
|
|
444
|
+
`Card` draws one record in a frame, in any of the table styles. The title goes
|
|
445
|
+
into the top border when the style draws one:
|
|
446
|
+
|
|
447
|
+
```python
|
|
448
|
+
from flexablelib import Card
|
|
449
|
+
|
|
450
|
+
card = Card(title='Ana', subtitle='Norte',
|
|
451
|
+
fields={'Edad': 28, 'Ciudad': 'Guadalajara'},
|
|
452
|
+
footer='actualizado hoy')
|
|
453
|
+
print(card.render(width=30))
|
|
454
|
+
```
|
|
455
|
+
|
|
456
|
+
```
|
|
457
|
+
╭─ Ana ──────────────────────╮
|
|
458
|
+
│ Norte │
|
|
459
|
+
├────────────────────────────┤
|
|
460
|
+
│ Edad 28 │
|
|
461
|
+
│ Ciudad Guadalajara │
|
|
462
|
+
├────────────────────────────┤
|
|
463
|
+
│ actualizado hoy │
|
|
464
|
+
╰────────────────────────────╯
|
|
465
|
+
```
|
|
466
|
+
|
|
467
|
+
`field_columns=2` (or `'auto'`) lays the fields out as a grid of tiles, and
|
|
468
|
+
`actions` adds `[ Action ]` chips:
|
|
469
|
+
|
|
470
|
+
```
|
|
471
|
+
╭─ Pedido 42 ────────────────────╮
|
|
472
|
+
│ Cliente Total │
|
|
473
|
+
│ José $1,200 │
|
|
474
|
+
│ Estado Fecha │
|
|
475
|
+
│ Enviado 11/11 │
|
|
476
|
+
├────────────────────────────────┤
|
|
477
|
+
│ [ Ver ] [ Editar ] │
|
|
478
|
+
╰────────────────────────────────╯
|
|
479
|
+
```
|
|
480
|
+
|
|
481
|
+
Cards take `style_name`, `theme` (the table themes), `border_color`,
|
|
482
|
+
`title_color`, `label_color`, `value_colors`, `color` (a background for the
|
|
483
|
+
whole card), `zebra`, `panel` and `shadow`.
|
|
484
|
+
|
|
485
|
+
`table.render(width)` makes a table responsive: the normal table when it fits,
|
|
486
|
+
without its low-priority columns next, squeezed and wrapped after that, and
|
|
487
|
+
one card per row when nothing else fits. `width` defaults to
|
|
488
|
+
`max_width`, then the terminal width; `responsive=True` makes `print(table)` do
|
|
489
|
+
the same.
|
|
490
|
+
|
|
491
|
+
```python
|
|
492
|
+
table.title, table.title_position = 'Personas', 'border'
|
|
493
|
+
table.column_priority = {'Correo': 3} # hidden first
|
|
494
|
+
table.card_options = {'subtitle_field': 'Grupo', 'fields': ['Edad', 'Ciudad']}
|
|
495
|
+
table.render(width=80) # table
|
|
496
|
+
table.render(width=46) # table without "Correo"
|
|
497
|
+
table.render(width=30) # cards
|
|
498
|
+
```
|
|
499
|
+
|
|
500
|
+
```
|
|
501
|
+
╭─────────┬────────┬──────┬─ Personas ──┬──────────────────╮
|
|
502
|
+
│ Nombre │ Grupo │ Edad │ Ciudad │ Correo │
|
|
503
|
+
├─────────┼────────┼──────┼─────────────┼──────────────────┤
|
|
504
|
+
│ Ana │ Norte │ 28 │ Guadalajara │ ana@example.com │
|
|
505
|
+
│ Luna 🌸 │ Centro │ 22 │ Mérida │ luna@example.com │
|
|
506
|
+
╰─────────┴────────┴──────┴─────────────┴──────────────────╯
|
|
507
|
+
|
|
508
|
+
Personas
|
|
509
|
+
╭─ Ana ──────────────────────╮
|
|
510
|
+
│ Norte │
|
|
511
|
+
├────────────────────────────┤
|
|
512
|
+
│ Edad 28 │
|
|
513
|
+
│ Ciudad Guadalajara │
|
|
514
|
+
╰────────────────────────────╯
|
|
515
|
+
```
|
|
516
|
+
|
|
517
|
+
`Grid` places cards, tables, text and other grids in columns that reflow with
|
|
518
|
+
the width -- a grid of cards or a whole terminal screen:
|
|
519
|
+
|
|
520
|
+
```python
|
|
521
|
+
from flexablelib import Grid, GridCell
|
|
522
|
+
|
|
523
|
+
Grid(table.to_cards(), min_width=28).render(width=100) # 3 columns, 2 at 62, 1 at 40
|
|
524
|
+
Grid([GridCell('Ventas de noviembre', span=3),
|
|
525
|
+
GridCell(table, span=2), Grid(cards, columns=1)], columns=3)
|
|
526
|
+
```
|
|
527
|
+
|
|
528
|
+
### Terminal interfaces
|
|
529
|
+
|
|
530
|
+
Since 3.2.0 a grid can size its columns (`12`, `'auto'`, `'2fr'`, `'30%'`,
|
|
531
|
+
bounds, or one layout per width), span rows, share one border with proper
|
|
532
|
+
junctions and a title per cell, and fill an exact height. Widgets --
|
|
533
|
+
`ProgressBar`, `Sparkline`, `BarChart`, `StatusBar`, `KeyHints`, `LogView`,
|
|
534
|
+
`Text`, `Rule` -- drop into it, `Screen` pins a header and footer to the
|
|
535
|
+
terminal's edges and `Live` redraws in place:
|
|
536
|
+
|
|
537
|
+
```python
|
|
538
|
+
from flexablelib import (Grid, GridCell, LogView, ProgressBar, Sparkline,
|
|
539
|
+
Text)
|
|
540
|
+
|
|
541
|
+
Grid([
|
|
542
|
+
GridCell(Text('▸ Resumen\n Ventas\n Ajustes'), row_span=2, title='Menú'),
|
|
543
|
+
GridCell(ProgressBar(72, label='CPU', thresholds={0.7: 'yellow'}),
|
|
544
|
+
title='Recursos'),
|
|
545
|
+
GridCell(Sparkline([3, 5, 2, 8, 6, 9, 4, 7], label='rps', show_last=True),
|
|
546
|
+
title='Tráfico'),
|
|
547
|
+
GridCell(LogView(['10:00 INFO arranque', '10:01 WARN lento']), span=2,
|
|
548
|
+
title='Eventos'),
|
|
549
|
+
], column_widths=[14, '1fr', '1fr'], border='rounded').render(width=64)
|
|
550
|
+
```
|
|
551
|
+
|
|
552
|
+
```
|
|
553
|
+
╭─ Menú ───────┬─ Recursos ────────────┬─ Tráfico ─────────────╮
|
|
554
|
+
│ ▸ Resumen │ CPU ████████▋░░░ 72% │ rps ▂▄▁▇▅█▃▆ 7 │
|
|
555
|
+
│ Ventas ├─ Eventos ─────────────┴───────────────────────┤
|
|
556
|
+
│ Ajustes │ 10:00 INFO arranque │
|
|
557
|
+
│ │ 10:01 WARN lento │
|
|
558
|
+
╰──────────────┴───────────────────────────────────────────────╯
|
|
559
|
+
```
|
|
560
|
+
|
|
561
|
+
A whole dashboard with a sidebar, KPI cards, a coloured table with merges,
|
|
562
|
+
bars, sparklines and a log: [examples/dashboard.py](https://github.com/Opus-Perpetuus/flexablelib/blob/main/examples/dashboard.py)
|
|
563
|
+
(`python examples/dashboard.py --live 10`).
|
|
564
|
+
|
|
565
|
+
More in [docs/LAYOUT.md](https://github.com/Opus-Perpetuus/flexablelib/blob/main/docs/LAYOUT.md).
|
|
566
|
+
|
|
442
567
|
## Notes
|
|
443
568
|
|
|
444
569
|
- A column named ``"i"`` does not collide with the index column (`utils.IndexColumnTitle`).
|
|
@@ -452,14 +577,18 @@ Open work and the issue map: [docs/ISSUES.md](https://github.com/Opus-Perpetuus/
|
|
|
452
577
|
```
|
|
453
578
|
flexablelib/ # GitHub repository
|
|
454
579
|
├── flexablelib/ the Python package (no runtime dependencies)
|
|
455
|
-
│ ├── __init__.py public API: Table,
|
|
580
|
+
│ ├── __init__.py public API: Table, Card, Grid, widgets, Screen, Live
|
|
456
581
|
│ ├── table.py the Table class — state and render orchestration
|
|
582
|
+
│ ├── layout.py Card, Grid, GridCell, panel and shadow
|
|
583
|
+
│ ├── widgets.py ProgressBar, Sparkline, BarChart, StatusBar, LogView…
|
|
584
|
+
│ ├── screen.py Screen (sticky header/footer) and Live (redraw)
|
|
457
585
|
│ ├── columns.py type inference, alignment, column widths
|
|
458
586
|
│ ├── style_compositions.py the 54 border styles, as data
|
|
459
587
|
│ ├── table_strings.py separator lines and data rows
|
|
460
588
|
│ ├── cells.py cell padding, justification, wrapping
|
|
461
589
|
│ ├── options.py constants and defaults
|
|
462
590
|
│ └── utils.py type predicates and small helpers
|
|
591
|
+
├── examples/ runnable demos (dashboard.py)
|
|
463
592
|
├── tests/ pytest suite — see ARCHITECTURE.md#testing
|
|
464
593
|
├── docs/ issue history and design notes
|
|
465
594
|
├── logos/ brand assets — see logos/README.md
|
|
@@ -0,0 +1,178 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""
|
|
3
|
+
A complete terminal dashboard built only with flexablelib.
|
|
4
|
+
|
|
5
|
+
python examples/dashboard.py # one frame, terminal size
|
|
6
|
+
python examples/dashboard.py --width 120 --height 40 --theme neon
|
|
7
|
+
python examples/dashboard.py --live 10 # redraw 10 times, 1 s apart
|
|
8
|
+
python examples/dashboard.py --no-color --border ascii
|
|
9
|
+
|
|
10
|
+
Pieces: Screen (sticky header and footer), a bordered Grid with column
|
|
11
|
+
widths, a row-spanning sidebar and cell titles, KPI cards, a coloured table
|
|
12
|
+
with merged cells, progress bars, sparklines, a bar chart and a log.
|
|
13
|
+
"""
|
|
14
|
+
|
|
15
|
+
import argparse
|
|
16
|
+
import math
|
|
17
|
+
import os
|
|
18
|
+
import sys
|
|
19
|
+
|
|
20
|
+
sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)),
|
|
21
|
+
'..'))
|
|
22
|
+
|
|
23
|
+
from flexablelib import (BarChart, Card, Grid, GridCell, KeyHints, # noqa
|
|
24
|
+
Live, LogView, ProgressBar, Screen, Sparkline,
|
|
25
|
+
StatusBar, Table, Text)
|
|
26
|
+
|
|
27
|
+
THEME_ACCENTS = {
|
|
28
|
+
'ocean': ('#7dc3ff', 'black on #7dc3ff', '#5f87af'),
|
|
29
|
+
'neon': ('#ff5fd7', 'black on #ff5fd7', '#af5fff'),
|
|
30
|
+
'forest': ('#87d787', 'black on #87d787', '#5f875f'),
|
|
31
|
+
'ember': ('#ffaf5f', 'black on #ffaf5f', '#af5f00'),
|
|
32
|
+
'midnight': ('#8787ff', 'white on #303070', '#5f5f87'),
|
|
33
|
+
'dark': ('#d0d0d0', 'black on #d0d0d0', '#6c6c6c'),
|
|
34
|
+
'mono': (None, 'reverse', None),
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
def wave(tick, n, base, amp, phase=0.0):
|
|
39
|
+
return [round(base + amp * math.sin((i + tick) / 2.3 + phase) +
|
|
40
|
+
amp * 0.4 * math.sin((i + tick) * 1.7 + phase), 1)
|
|
41
|
+
for i in range(n)]
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def sales_table(theme, colors):
|
|
45
|
+
t = Table(headers=['Región', 'Tienda', 'Ventas', 'Δ %', 'Estado'])
|
|
46
|
+
rows = [
|
|
47
|
+
['Norte', 'Monterrey', 18250.5, 12.4, 'OK'],
|
|
48
|
+
['Norte', 'Saltillo', 9120.0, -3.1, 'Revisar'],
|
|
49
|
+
['Centro', 'CDMX', 25400.75, 8.9, 'OK'],
|
|
50
|
+
['Centro', 'Puebla', 7310.2, 1.2, 'OK'],
|
|
51
|
+
['Sur', 'Mérida', 6890.0, -7.5, 'Alerta'],
|
|
52
|
+
['Sur', 'Oaxaca', 4210.4, 2.0, 'OK'],
|
|
53
|
+
]
|
|
54
|
+
for row in rows:
|
|
55
|
+
t.add_row(row)
|
|
56
|
+
t.apply_theme(theme)
|
|
57
|
+
t.style_name = 'single'
|
|
58
|
+
t.use_colors = colors
|
|
59
|
+
t.float_format = ',.1f'
|
|
60
|
+
t.expand_to_window = True
|
|
61
|
+
t.merge_cells(0, 0, last_row=1)
|
|
62
|
+
t.merge_cells(2, 0, last_row=3)
|
|
63
|
+
t.merge_cells(4, 0, last_row=5)
|
|
64
|
+
t.color_rule = lambda value, row, column: (
|
|
65
|
+
('red' if value < 0 else 'green') if column == 'Δ %' else
|
|
66
|
+
{'OK': 'green', 'Revisar': 'yellow', 'Alerta': 'bold red'}.get(value)
|
|
67
|
+
if column == 'Estado' else None)
|
|
68
|
+
t.column_priority = {'Estado': 2, 'Tienda': 3}
|
|
69
|
+
t.card_options = {'min_width': 24, 'fields': ['Ventas', 'Δ %']}
|
|
70
|
+
return t
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
def build(theme='ocean', border='rounded', colors=True, tick=0):
|
|
74
|
+
accent, bar_color, border_color = THEME_ACCENTS.get(
|
|
75
|
+
theme, THEME_ACCENTS['ocean'])
|
|
76
|
+
cpu = wave(tick, 40, 55, 25)
|
|
77
|
+
mem = wave(tick, 40, 62, 8, 1.0)
|
|
78
|
+
net = wave(tick, 40, 40, 30, 2.0)
|
|
79
|
+
|
|
80
|
+
kpis = [
|
|
81
|
+
Card(title='Ventas hoy', fields={'MXN': '$71,182', 'vs ayer': '+6.2%'},
|
|
82
|
+
field_columns=2, theme=theme, use_colors=colors,
|
|
83
|
+
value_colors={'vs ayer': 'green'}),
|
|
84
|
+
Card(title='Pedidos', fields={'Total': 1284, 'Abiertos': 37},
|
|
85
|
+
field_columns=2, theme=theme, use_colors=colors),
|
|
86
|
+
Card(title='Clientes', fields={'Activos': 942, 'Nuevos': 58},
|
|
87
|
+
field_columns=2, theme=theme, use_colors=colors),
|
|
88
|
+
Card(title='Ticket', fields={'Prom.': '$554', 'Máx.': '$9,870'},
|
|
89
|
+
field_columns=2, theme=theme, use_colors=colors),
|
|
90
|
+
]
|
|
91
|
+
menu_items = ['Resumen', 'Ventas', 'Inventario', 'Clientes', 'Envíos',
|
|
92
|
+
'Reportes', 'Ajustes']
|
|
93
|
+
menu = '\n'.join(
|
|
94
|
+
('\x1b[1m▸ {0}\x1b[0m'.format(item) if i == 0 else ' ' + item)
|
|
95
|
+
for i, item in enumerate(menu_items))
|
|
96
|
+
resources = Grid([
|
|
97
|
+
ProgressBar(cpu[-1], label='CPU', label_width=5, value_width=10,
|
|
98
|
+
thresholds={0.7: 'yellow', 0.9: 'red'}, use_colors=colors),
|
|
99
|
+
ProgressBar(mem[-1], label='RAM', label_width=5, value_width=10,
|
|
100
|
+
thresholds={0.7: 'yellow', 0.9: 'red'}, use_colors=colors),
|
|
101
|
+
ProgressBar(412, 512, label='Disco', label_width=5, value_width=10,
|
|
102
|
+
value_format='{value:.0f}/{total:.0f} GB',
|
|
103
|
+
thresholds={0.7: 'yellow', 0.9: 'red'}, use_colors=colors),
|
|
104
|
+
Sparkline(cpu, label='CPU', label_width=5, show_last=True, color=accent,
|
|
105
|
+
use_colors=colors),
|
|
106
|
+
Sparkline(net, label='Red', label_width=5, show_last=True, color='magenta',
|
|
107
|
+
use_colors=colors),
|
|
108
|
+
], columns=1, row_gap=0)
|
|
109
|
+
chart = BarChart({'Laptops': 412, 'Monitores': 268, 'Teclados': 190,
|
|
110
|
+
'Audífonos': 151, 'Cables': 87}, sort=True,
|
|
111
|
+
color=accent, use_colors=colors)
|
|
112
|
+
log = LogView([
|
|
113
|
+
'09:58:02 INFO sincronización de inventario completa',
|
|
114
|
+
'09:58:40 OK pedido #1281 enviado (Mérida)',
|
|
115
|
+
'09:59:13 WARN latencia de pagos 820 ms',
|
|
116
|
+
'09:59:57 INFO 12 usuarios conectados',
|
|
117
|
+
'10:00:21 ERROR timeout en la API de envíos (reintento 1/3)',
|
|
118
|
+
'10:00:24 OK API de envíos recuperada',
|
|
119
|
+
'10:01:{0:02d} INFO tick {1}'.format(tick % 60, tick),
|
|
120
|
+
], use_colors=colors)
|
|
121
|
+
|
|
122
|
+
body = Grid([
|
|
123
|
+
GridCell(Text(menu, use_colors=colors), row_span=3, title='Menú',
|
|
124
|
+
hide_below=110),
|
|
125
|
+
GridCell(Grid(kpis, min_width=22, row_gap=0, gap=1), span=2,
|
|
126
|
+
title='Indicadores'),
|
|
127
|
+
GridCell(sales_table(theme, colors), title='Ventas por región'),
|
|
128
|
+
GridCell(resources, title='Recursos', valign='middle'),
|
|
129
|
+
GridCell(chart, title='Top productos'),
|
|
130
|
+
GridCell(log, title='Eventos', stretch=True),
|
|
131
|
+
], # Three layouts: one column, two columns, sidebar + two columns.
|
|
132
|
+
column_widths={0: ['1fr'], 76: ['3fr', '2fr'],
|
|
133
|
+
110: [(16, 14, 18), '3fr', '2fr']},
|
|
134
|
+
row_heights={0: [], 76: ['auto', 'auto', '1fr']},
|
|
135
|
+
border=border, border_color=border_color,
|
|
136
|
+
title_color='bold ' + (accent or ''), use_colors=colors)
|
|
137
|
+
header = StatusBar('◆ flexablelib · Panel de ventas',
|
|
138
|
+
'Resumen', 'tick {0} · 11/11/2026 10:01'.format(tick),
|
|
139
|
+
color=bar_color, use_colors=colors)
|
|
140
|
+
footer = KeyHints({'q': 'Salir', '↑↓': 'Mover', 'Enter': 'Abrir',
|
|
141
|
+
'/': 'Buscar', 'F5': 'Refrescar', '?': 'Ayuda'},
|
|
142
|
+
key_color=bar_color, use_colors=colors)
|
|
143
|
+
return Screen(body=body, header=header, footer=footer)
|
|
144
|
+
|
|
145
|
+
|
|
146
|
+
def main(argv=None):
|
|
147
|
+
parser = argparse.ArgumentParser(description=__doc__.split('\n\n')[1])
|
|
148
|
+
parser.add_argument('--width', type=int)
|
|
149
|
+
parser.add_argument('--height', type=int)
|
|
150
|
+
parser.add_argument('--theme', default='ocean',
|
|
151
|
+
choices=sorted(THEME_ACCENTS))
|
|
152
|
+
parser.add_argument('--border', default='rounded',
|
|
153
|
+
choices=['single', 'rounded', 'double', 'heavy',
|
|
154
|
+
'ascii'])
|
|
155
|
+
parser.add_argument('--no-color', action='store_true')
|
|
156
|
+
parser.add_argument('--live', type=int, metavar='N',
|
|
157
|
+
help='redraw N frames, one per --interval seconds')
|
|
158
|
+
parser.add_argument('--interval', type=float, default=1.0)
|
|
159
|
+
args = parser.parse_args(argv)
|
|
160
|
+
colors = not args.no_color and (args.live is not None or None)
|
|
161
|
+
if colors is None:
|
|
162
|
+
from flexablelib.colors import supports_color
|
|
163
|
+
colors = supports_color()
|
|
164
|
+
if args.live:
|
|
165
|
+
live = Live(build(args.theme, args.border, colors), width=args.width,
|
|
166
|
+
height=args.height)
|
|
167
|
+
|
|
168
|
+
def step(i):
|
|
169
|
+
live.renderable = build(args.theme, args.border, colors, i)
|
|
170
|
+
live.run(step, interval=args.interval, iterations=args.live)
|
|
171
|
+
return 0
|
|
172
|
+
screen = build(args.theme, args.border, colors)
|
|
173
|
+
print(screen.render(width=args.width, height=args.height))
|
|
174
|
+
return 0
|
|
175
|
+
|
|
176
|
+
|
|
177
|
+
if __name__ == '__main__':
|
|
178
|
+
sys.exit(main())
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
from .table import Table
|
|
2
|
+
from .style_compositions import TableComposition, SeparatorLine
|
|
3
|
+
from .layout import Card, Grid, GridCell
|
|
4
|
+
from .widgets import (ProgressBar, Sparkline, BarChart, StatusBar, KeyHints,
|
|
5
|
+
LogView, Text, Rule)
|
|
6
|
+
from .screen import Screen, Live
|
|
7
|
+
|
|
8
|
+
# Names, not the objects themselves: `from flexablelib import *` walks this
|
|
9
|
+
# list and raises TypeError on anything that is not a string.
|
|
10
|
+
__all__ = ['Table', 'TableComposition', 'SeparatorLine', 'Card', 'Grid',
|
|
11
|
+
'GridCell', 'ProgressBar', 'Sparkline', 'BarChart', 'StatusBar',
|
|
12
|
+
'KeyHints', 'LogView', 'Text', 'Rule', 'Screen', 'Live']
|