flexablelib 2.0.15__tar.gz → 2.0.17__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.
Files changed (59) hide show
  1. {flexablelib-2.0.15 → flexablelib-2.0.17}/CHANGELOG.md +62 -0
  2. {flexablelib-2.0.15 → flexablelib-2.0.17}/MANIFEST.in +4 -0
  3. flexablelib-2.0.17/PKG-INFO +494 -0
  4. flexablelib-2.0.17/README.md +429 -0
  5. {flexablelib-2.0.15 → flexablelib-2.0.17}/flexablelib/colors.py +20 -0
  6. flexablelib-2.0.17/flexablelib/py.typed +0 -0
  7. {flexablelib-2.0.15 → flexablelib-2.0.17}/flexablelib/readers.py +44 -3
  8. {flexablelib-2.0.15 → flexablelib-2.0.17}/flexablelib/table.py +473 -33
  9. {flexablelib-2.0.15 → flexablelib-2.0.17}/flexablelib/utils.py +26 -0
  10. {flexablelib-2.0.15 → flexablelib-2.0.17}/flexablelib/writers.py +34 -3
  11. flexablelib-2.0.17/flexablelib.egg-info/PKG-INFO +494 -0
  12. {flexablelib-2.0.15 → flexablelib-2.0.17}/flexablelib.egg-info/SOURCES.txt +10 -1
  13. {flexablelib-2.0.15 → flexablelib-2.0.17}/package.json +1 -1
  14. flexablelib-2.0.17/pytest.ini +7 -0
  15. flexablelib-2.0.17/setup.cfg +8 -0
  16. {flexablelib-2.0.15 → flexablelib-2.0.17}/setup.py +32 -6
  17. flexablelib-2.0.17/style_examples.md +769 -0
  18. flexablelib-2.0.17/tests/conftest.py +105 -0
  19. flexablelib-2.0.17/tests/helpers.py +60 -0
  20. flexablelib-2.0.17/tests/test_v216_features.py +155 -0
  21. flexablelib-2.0.17/tests/test_v217_features.py +139 -0
  22. {flexablelib-2.0.15 → flexablelib-2.0.17}/tools/benchmark.py +44 -4
  23. flexablelib-2.0.17/tools/readme_gallery.py +138 -0
  24. flexablelib-2.0.17/tools/text_to_png.py +179 -0
  25. flexablelib-2.0.15/PKG-INFO +0 -371
  26. flexablelib-2.0.15/README.md +0 -322
  27. flexablelib-2.0.15/flexablelib.egg-info/PKG-INFO +0 -371
  28. flexablelib-2.0.15/setup.cfg +0 -7
  29. {flexablelib-2.0.15 → flexablelib-2.0.17}/LICENSE +0 -0
  30. {flexablelib-2.0.15 → flexablelib-2.0.17}/flexablelib/__init__.py +0 -0
  31. {flexablelib-2.0.15 → flexablelib-2.0.17}/flexablelib/_speedups.c +0 -0
  32. {flexablelib-2.0.15 → flexablelib-2.0.17}/flexablelib/_width_tables.h +0 -0
  33. {flexablelib-2.0.15 → flexablelib-2.0.17}/flexablelib/cells.py +0 -0
  34. {flexablelib-2.0.15 → flexablelib-2.0.17}/flexablelib/columns.py +0 -0
  35. {flexablelib-2.0.15 → flexablelib-2.0.17}/flexablelib/fast.py +0 -0
  36. {flexablelib-2.0.15 → flexablelib-2.0.17}/flexablelib/merges.py +0 -0
  37. {flexablelib-2.0.15 → flexablelib-2.0.17}/flexablelib/options.py +0 -0
  38. {flexablelib-2.0.15 → flexablelib-2.0.17}/flexablelib/style_compositions.py +0 -0
  39. {flexablelib-2.0.15 → flexablelib-2.0.17}/flexablelib/table_strings.py +0 -0
  40. {flexablelib-2.0.15 → flexablelib-2.0.17}/flexablelib/text_width.py +0 -0
  41. {flexablelib-2.0.15 → flexablelib-2.0.17}/flexablelib.egg-info/dependency_links.txt +0 -0
  42. {flexablelib-2.0.15 → flexablelib-2.0.17}/flexablelib.egg-info/requires.txt +0 -0
  43. {flexablelib-2.0.15 → flexablelib-2.0.17}/flexablelib.egg-info/top_level.txt +0 -0
  44. {flexablelib-2.0.15 → flexablelib-2.0.17}/tests/test_cells.py +0 -0
  45. {flexablelib-2.0.15 → flexablelib-2.0.17}/tests/test_columns.py +0 -0
  46. {flexablelib-2.0.15 → flexablelib-2.0.17}/tests/test_excel.py +0 -0
  47. {flexablelib-2.0.15 → flexablelib-2.0.17}/tests/test_features.py +0 -0
  48. {flexablelib-2.0.15 → flexablelib-2.0.17}/tests/test_issues.py +0 -0
  49. {flexablelib-2.0.15 → flexablelib-2.0.17}/tests/test_merge_edge_matrix.py +0 -0
  50. {flexablelib-2.0.15 → flexablelib-2.0.17}/tests/test_merges.py +0 -0
  51. {flexablelib-2.0.15 → flexablelib-2.0.17}/tests/test_readme_examples.py +0 -0
  52. {flexablelib-2.0.15 → flexablelib-2.0.17}/tests/test_styles.py +0 -0
  53. {flexablelib-2.0.15 → flexablelib-2.0.17}/tests/test_text_width.py +0 -0
  54. {flexablelib-2.0.15 → flexablelib-2.0.17}/tests/test_two_pass_measurement.py +0 -0
  55. {flexablelib-2.0.15 → flexablelib-2.0.17}/tests/test_upstream_issues.py +0 -0
  56. {flexablelib-2.0.15 → flexablelib-2.0.17}/tests/test_v213_features.py +0 -0
  57. {flexablelib-2.0.15 → flexablelib-2.0.17}/tests/test_v214_features.py +0 -0
  58. {flexablelib-2.0.15 → flexablelib-2.0.17}/tests/test_v215_features.py +0 -0
  59. {flexablelib-2.0.15 → flexablelib-2.0.17}/tools/generate_width_tables.py +0 -0
@@ -2,6 +2,68 @@
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
+ ## [2.0.17] - 2026-10-31
6
+
7
+ ### Security
8
+ - ``to_html`` (interactive page): cell or header text containing
9
+ ``</script>`` could close the inline script and inject markup. The embedded
10
+ JSON now escapes ``<``, ``>`` and ``&`` as ``\uXXXX``; values are unchanged
11
+ once parsed.
12
+
13
+ ### Fixed
14
+ - ``border_text(..., offset=None, align='right' | 'center')`` and overlong
15
+ labels no longer overwrite the frame's closing corner.
16
+ - Rich/X11 percentage greys (``grey0`` … ``grey100``, ``gray`` too) are valid
17
+ colour names, e.g. ``table.zebra = 'on grey23'``; they map to the nearest
18
+ xterm-256 grey.
19
+
20
+ ### Performance
21
+ - Rendering skips the per-cell vertical-alignment lookup when every cell is
22
+ top-aligned (the default): 10,000 × 6 renders in ~157 ms instead of ~187 ms.
23
+ ``tools/benchmark.py`` now includes rich and a ``--pure`` mode; numbers in
24
+ ``docs/BENCHMARKS.md``.
25
+
26
+ ### Packaging
27
+ - ``py.typed`` marker (PEP 561); ``Typing :: Typed`` classifier.
28
+ - Development status **5 - Production/Stable**; richer keywords, classifiers
29
+ and ``project_urls`` (Source, Issues, Changelog, Documentation).
30
+ - The sdist now ships ``style_examples.md``, ``pytest.ini`` and ``tests/`` so
31
+ the suite runs from it (useful for distro / conda-forge packaging, #26).
32
+ - ``setup.cfg``: ``description_file`` (the hyphenated key is deprecated).
33
+
34
+ ### Docs
35
+ - README rewritten for adoption: quickstart, feature gallery (PNG renders
36
+ from ``tools/readme_gallery.py``), comparison with tabulate / prettytable /
37
+ rich, production notes, stability policy. Images and links use absolute
38
+ URLs so they render on PyPI.
39
+ - ``CONTRIBUTING.md``, ``SECURITY.md``, issue and PR templates,
40
+ ``docs/COMPARISON.md`` (89-library survey), ``docs/BENCHMARKS.md``.
41
+
42
+ ## [2.0.16] - 2026-10-28
43
+
44
+ ### Added
45
+ - ``Table.index_title``: rename the ``show_index`` column header (default ``i``).
46
+ - ``Table.roman_index``: render index values as Roman numerals.
47
+ - ``Table.number_columns``: display data headers as ``1``, ``2``, … (stored names kept).
48
+ - ``Table.strip_cells``: strip whitespace from string cells on display.
49
+ - ``Table.hrules`` / ``Table.vrules``: PrettyTable-style rule toggles
50
+ (``all`` / ``frame`` / ``header`` / ``none`` for hrules; ``all`` / ``frame`` /
51
+ ``none`` for vrules).
52
+ - ``Table.add_dividers(*indexes)`` and ``Table.divide_every(n, start=0)``.
53
+ - ``Table.fit_terminal(margin=0)``: pin ``max_width`` to the live terminal.
54
+ - Aliases ``max_table_width`` (``max_width``) and ``justify`` (``table_align``).
55
+ - ``Table.suppress_empty``: hide empty rows and columns together.
56
+ - CSV dialect extras on ``from_csv`` / ``to_csv``: ``dialect``, ``quoting``,
57
+ ``quotechar``, ``escapechar``, ``doublequote``, ``lineterminator``,
58
+ ``skipinitialspace``, ``strict``.
59
+ - Themes: ``solarized``, ``neon``, ``mono``, ``autumn``, ``contrast``,
60
+ ``forest``, ``ember``, ``slate``.
61
+ - ``paginate(..., freeze_header=True, page_label=False)``: opt-out of repeating
62
+ headers after page 1; optional ``page k/n`` title labels.
63
+
64
+ ### Notes
65
+ - ``from_html`` was already present (2.0.x); no API change this release.
66
+
5
67
  ## [2.0.15] - 2026-10-28
6
68
 
7
69
  ### Added
@@ -5,3 +5,7 @@ include package.json
5
5
  include flexablelib/_speedups.c
6
6
  include flexablelib/_width_tables.h
7
7
  recursive-include tools *.py
8
+ include style_examples.md
9
+ include flexablelib/py.typed
10
+ include pytest.ini
11
+ recursive-include tests *.py
@@ -0,0 +1,494 @@
1
+ Metadata-Version: 2.4
2
+ Name: flexablelib
3
+ Version: 2.0.17
4
+ Summary: Fast, dependency-free terminal tables for Python: 56 border styles, ANSI colors, cell merges, decimal alignment, width fitting, and CSV/Markdown/HTML/Excel/LaTeX I/O.
5
+ Home-page: https://github.com/Opus-Perpetuus/flexablelib
6
+ Author: Benjamin Ramirez
7
+ Author-email: chilerito12@gmail.com
8
+ License: MIT
9
+ Project-URL: Documentation, https://github.com/Opus-Perpetuus/flexablelib#readme
10
+ Project-URL: Source, https://github.com/Opus-Perpetuus/flexablelib
11
+ Project-URL: Issues, https://github.com/Opus-Perpetuus/flexablelib/issues
12
+ Project-URL: Changelog, https://github.com/Opus-Perpetuus/flexablelib/blob/main/CHANGELOG.md
13
+ Project-URL: Releases, https://github.com/Opus-Perpetuus/flexablelib/releases
14
+ Keywords: table,tables,terminal,console,cli,ascii-table,pretty-print,prettytable,tabulate,tabular-data,ansi,ansi-colors,unicode,box-drawing,markdown,html,csv,excel,latex,formatting
15
+ Classifier: Development Status :: 5 - Production/Stable
16
+ Classifier: Environment :: Console
17
+ Classifier: Intended Audience :: Developers
18
+ Classifier: Intended Audience :: System Administrators
19
+ Classifier: Intended Audience :: Science/Research
20
+ Classifier: License :: OSI Approved :: MIT License
21
+ Classifier: Operating System :: OS Independent
22
+ Classifier: Programming Language :: C
23
+ Classifier: Topic :: Terminals
24
+ Classifier: Topic :: Text Processing
25
+ Classifier: Topic :: Text Processing :: Markup
26
+ Classifier: Topic :: Software Development :: Libraries
27
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
28
+ Classifier: Topic :: Utilities
29
+ Classifier: Typing :: Typed
30
+ Classifier: Programming Language :: Python :: 3
31
+ Classifier: Programming Language :: Python :: 3.8
32
+ Classifier: Programming Language :: Python :: 3.9
33
+ Classifier: Programming Language :: Python :: 3.10
34
+ Classifier: Programming Language :: Python :: 3.11
35
+ Classifier: Programming Language :: Python :: 3.12
36
+ Classifier: Programming Language :: Python :: 3.13
37
+ Classifier: Programming Language :: Python :: 3.14
38
+ Classifier: Programming Language :: Python :: 3 :: Only
39
+ Requires-Python: >=3.8
40
+ Description-Content-Type: text/markdown
41
+ License-File: LICENSE
42
+ Provides-Extra: pandas
43
+ Requires-Dist: pandas>=1.0; extra == "pandas"
44
+ Provides-Extra: excel
45
+ Requires-Dist: openpyxl>=3.0; extra == "excel"
46
+ Provides-Extra: html
47
+ Requires-Dist: lxml>=4.0; extra == "html"
48
+ Provides-Extra: all
49
+ Requires-Dist: pandas>=1.0; extra == "all"
50
+ Requires-Dist: openpyxl>=3.0; extra == "all"
51
+ Requires-Dist: lxml>=4.0; extra == "all"
52
+ Dynamic: author
53
+ Dynamic: author-email
54
+ Dynamic: classifier
55
+ Dynamic: description
56
+ Dynamic: description-content-type
57
+ Dynamic: home-page
58
+ Dynamic: keywords
59
+ Dynamic: license
60
+ Dynamic: license-file
61
+ Dynamic: project-url
62
+ Dynamic: provides-extra
63
+ Dynamic: requires-python
64
+ Dynamic: summary
65
+
66
+ <p align="center">
67
+ <img src="https://raw.githubusercontent.com/Opus-Perpetuus/flexablelib/main/logos/export/logo-1024.png" alt="flexablelib" width="440">
68
+ </p>
69
+
70
+ <p align="center">
71
+ <strong>Fast, dependency-free terminal tables for Python.</strong><br>
72
+ 56 border styles · ANSI colours · cell merges · decimal alignment · width fitting · CSV / Markdown / HTML / Excel / LaTeX I/O
73
+ </p>
74
+
75
+ <p align="center">
76
+ <a href="https://pypi.org/project/flexablelib/"><img alt="PyPI version" src="https://img.shields.io/pypi/v/flexablelib?style=flat-square&color=4338CA&logo=pypi&logoColor=white"></a>
77
+ <a href="https://pypi.org/project/flexablelib/"><img alt="Python versions" src="https://img.shields.io/pypi/pyversions/flexablelib?style=flat-square&color=4338CA&logo=python&logoColor=white"></a>
78
+ <a href="https://github.com/Opus-Perpetuus/flexablelib/actions/workflows/tests.yml"><img alt="Tests" src="https://img.shields.io/github/actions/workflow/status/Opus-Perpetuus/flexablelib/tests.yml?branch=main&style=flat-square&label=tests"></a>
79
+ <a href="https://pypistats.org/packages/flexablelib"><img alt="Downloads per month" src="https://img.shields.io/pypi/dm/flexablelib?style=flat-square&color=F59E0B"></a>
80
+ <a href="https://pypi.org/project/flexablelib/"><img alt="Development status" src="https://img.shields.io/pypi/status/flexablelib?style=flat-square&color=F59E0B"></a>
81
+ <a href="https://github.com/Opus-Perpetuus/flexablelib/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/pypi/l/flexablelib?style=flat-square&color=64748B"></a>
82
+ <a href="https://github.com/Opus-Perpetuus/flexablelib/blob/main/flexablelib/py.typed"><img alt="Typed" src="https://img.shields.io/badge/typing-py.typed-64748B?style=flat-square"></a>
83
+ </p>
84
+
85
+ ---
86
+
87
+ **flexablelib** turns rows and columns into readable tables for terminals, logs,
88
+ reports and docs. It has **no runtime dependencies**, ships **prebuilt wheels
89
+ with an optional C speed-up**, and is covered by **1,000+ tests** on Python
90
+ 3.8 – 3.14.
91
+
92
+ <p align="center">
93
+ <img src="https://raw.githubusercontent.com/Opus-Perpetuus/flexablelib/main/docs/img/quickstart.png" alt="A rounded flexablelib table with a coloured header and a red value" width="600">
94
+ </p>
95
+
96
+ ## Install
97
+
98
+ ```bash
99
+ pip install flexablelib
100
+ ```
101
+
102
+ Optional extras: `pip install "flexablelib[pandas]"`, `"flexablelib[excel]"`,
103
+ `"flexablelib[html]"` or `"flexablelib[all]"`. The base install stays
104
+ dependency-free.
105
+
106
+ ## 30-second quickstart
107
+
108
+ ```python
109
+ from flexablelib import Table
110
+
111
+ table = Table(
112
+ rows=[
113
+ ["api-gateway", "eu-west-1", 99.982, 1240],
114
+ ["auth", "us-east-1", 99.9, 312],
115
+ ["billing", "us-east-1", 98.75, 87],
116
+ ],
117
+ headers=["Service", "Region", "Uptime %", "RPS"],
118
+ )
119
+ table.style_name = "rounded" # 56 styles, see style_examples.md
120
+ table.header_color = "bold cyan"
121
+ table.color_rule = lambda value, row, column: (
122
+ "red" if column == "Uptime %" and value < 99.5 else None
123
+ )
124
+ print(table)
125
+ ```
126
+
127
+ ```
128
+ ╭─────────────┬───────────┬──────────┬──────╮
129
+ │ Service │ Region │ Uptime % │ RPS │
130
+ ├─────────────┼───────────┼──────────┼──────┤
131
+ │ api-gateway │ eu-west-1 │ 99.982 │ 1240 │
132
+ │ auth │ us-east-1 │ 99.9 │ 312 │
133
+ │ billing │ us-east-1 │ 98.75 │ 87 │
134
+ ╰─────────────┴───────────┴──────────┴──────╯
135
+ ```
136
+
137
+ Numbers align on the decimal point, colours never break alignment, and the
138
+ same table exports anywhere:
139
+
140
+ ```python
141
+ table.to_markdown() # GitHub / docs
142
+ table.to_html("report.html") # self-contained, sortable, offline
143
+ table.to_csv("out.csv"); table.to_latex(); table.to_rst(); table.to_asciidoc()
144
+ table.to_excel("report.xlsx") # pip install "flexablelib[excel]"
145
+ Table.from_csv("sales.csv"); Table.from_markdown(md); Table.from_pandas(df)
146
+ ```
147
+
148
+ ## Feature gallery
149
+
150
+ <table>
151
+ <tr>
152
+ <td width="50%"><b>Styles</b> — 56 presets, from <code>ascii</code> to <code>blocks</code><br><img src="https://raw.githubusercontent.com/Opus-Perpetuus/flexablelib/main/docs/img/styles.png" alt="Several border styles" width="260"></td>
153
+ <td width="50%"><b>Themes</b> — <code>table.apply_theme("ocean")</code><br><img src="https://raw.githubusercontent.com/Opus-Perpetuus/flexablelib/main/docs/img/themes.png" alt="Theme presets" width="380"></td>
154
+ </tr>
155
+ <tr>
156
+ <td><b>Text on borders</b> — <code>table.border_text("Production", where="top")</code><br><img src="https://raw.githubusercontent.com/Opus-Perpetuus/flexablelib/main/docs/img/border_text.png" alt="Labels written into the table frame" width="380"></td>
157
+ <td><b>Cell merges</b> — <code>table.merge_cells(0, 0, last_row=1)</code><br><img src="https://raw.githubusercontent.com/Opus-Perpetuus/flexablelib/main/docs/img/merges.png" alt="Vertically merged cells" width="320"></td>
158
+ </tr>
159
+ <tr>
160
+ <td><b>Zebra rows, footer, caption</b><br><img src="https://raw.githubusercontent.com/Opus-Perpetuus/flexablelib/main/docs/img/zebra_footer.png" alt="Striped rows with a footer and caption" width="380"></td>
161
+ <td><b>Decimal alignment</b> — floats and scientific notation<br><img src="https://raw.githubusercontent.com/Opus-Perpetuus/flexablelib/main/docs/img/decimals.png" alt="Numbers aligned on the decimal point" width="220"></td>
162
+ </tr>
163
+ </table>
164
+
165
+ More: [all 56 styles](https://github.com/Opus-Perpetuus/flexablelib/blob/main/style_examples.md) ·
166
+ wrapping and ellipsis overflow · per-column / per-cell colour and alignment ·
167
+ vertical alignment · `paginate()` · `stream()` for live rows · `transpose()` ·
168
+ nested tables · `fit_terminal()` · `hide_columns` · `sort_by` · Roman / custom
169
+ index.
170
+
171
+ ## How it compares
172
+
173
+ A factual feature matrix from our
174
+ [survey of 89 table libraries](https://github.com/Opus-Perpetuus/flexablelib/blob/main/docs/COMPARISON.md). A dash means
175
+ the feature was not found in that library's documentation during the survey,
176
+ not a claim that it is impossible there.
177
+
178
+ | | flexablelib | tabulate | prettytable | rich |
179
+ | --- | :---: | :---: | :---: | :---: |
180
+ | Runtime dependencies | **none** | none | `wcwidth` | `markdown-it-py`, `pygments` |
181
+ | Border style presets | 56 | many `tablefmt` | — (hrules/vrules toggles) | box styles |
182
+ | Decimal-point alignment | ✓ | ✓ | — | — |
183
+ | Row **and** column cell merges | ✓ | — | — | — |
184
+ | ANSI colours (header, rows, cells, borders) | ✓ | — | — | ✓ |
185
+ | Zebra rows / caption / footer | ✓ | — | — | ✓ |
186
+ | Text written on borders | ✓ | — | — | — |
187
+ | Wrap / truncate / ellipsis overflow | ✓ | — | max width | ✓ |
188
+ | Sorting, pagination | ✓ | — | ✓ | — |
189
+ | Exports | CSV, MD, HTML, Excel, RST, AsciiDoc, LaTeX | HTML, LaTeX, MD, RST, org, jira, … | HTML, CSV, JSON, LaTeX | — (console) |
190
+ | Readers | CSV, Markdown, HTML, dicts, pandas, Excel | — | CSV, DB cursor, HTML | — |
191
+ | Nested tables | ✓ | — | — | ✓ (renderables) |
192
+
193
+ rich is a full terminal-rendering toolkit (markup, live displays, progress
194
+ bars) and tabulate covers many more markup dialects; pick flexablelib when you
195
+ want a dependency-free, table-focused library with styling, merges and I/O in
196
+ one place.
197
+
198
+ ## Production notes
199
+
200
+ - **Zero runtime dependencies.** Readers/writers that need a third-party
201
+ package (`pandas`, `openpyxl`, `lxml`) are opt-in extras and imported lazily.
202
+ - **Performance.** Rendering 10,000 rows × 6 columns takes ~157 ms with the C
203
+ extension (~172 ms pure Python), on par with prettytable, ~1.3× faster than
204
+ tabulate and ~18× faster than rich's table. pandas `to_string()` is faster
205
+ still (~85 ms). Full method and numbers:
206
+ [docs/BENCHMARKS.md](https://github.com/Opus-Perpetuus/flexablelib/blob/main/docs/BENCHMARKS.md).
207
+ - **Wheels.** Prebuilt for CPython 3.8 – 3.13 on Linux (manylinux, musllinux),
208
+ Windows x64 and macOS arm64. Anywhere else it builds from source or falls
209
+ back to pure Python — installation never fails for want of a compiler.
210
+ `from flexablelib.fast import implementation; implementation()` tells you
211
+ which backend is live.
212
+ - **Colour safety.** Escape sequences are emitted only to a TTY by default,
213
+ never when `NO_COLOR` is set; `FORCE_COLOR` or `table.use_colors = True`
214
+ overrides. Logs and files stay clean.
215
+ - **Unicode.** Widths are measured in terminal columns, so CJK, emoji and
216
+ coloured text stay aligned.
217
+ - **Windows.** Box-drawing styles need a UTF-8 console (`chcp 65001` or
218
+ `PYTHONUTF8=1`; Windows Terminal is usually UTF-8 already). ASCII styles
219
+ (`ascii`, `grid`, `psql`, `markdown`, …) work on any code page.
220
+ - **Typed.** Ships `py.typed` (PEP 561).
221
+ - **Stability.** flexablelib follows [semantic versioning](https://semver.org):
222
+ within 2.x, public `Table` attributes and methods are not removed or renamed
223
+ without a deprecation period; new features arrive in minor/patch releases
224
+ and every release is listed in the
225
+ [CHANGELOG](https://github.com/Opus-Perpetuus/flexablelib/blob/main/CHANGELOG.md).
226
+ - **Support.** Bugs and requests: [issues](https://github.com/Opus-Perpetuus/flexablelib/issues). Security reports:
227
+ [SECURITY.md](https://github.com/Opus-Perpetuus/flexablelib/blob/main/SECURITY.md). Contributions:
228
+ [CONTRIBUTING.md](https://github.com/Opus-Perpetuus/flexablelib/blob/main/CONTRIBUTING.md).
229
+
230
+ ### Windows console encoding
231
+
232
+ ```bat
233
+ chcp 65001
234
+ set PYTHONUTF8=1
235
+ ```
236
+
237
+ (PowerShell: `$env:PYTHONUTF8=1`.)
238
+
239
+ # Guide
240
+
241
+ ## Usage
242
+ Creating a table is simple.
243
+ ### Code Example
244
+ ```
245
+ from flexablelib import Table
246
+
247
+ new_table = Table()
248
+ print(new_table)
249
+ ```
250
+ ### Output
251
+ ```
252
+ ++
253
+ ++
254
+ ++
255
+ ```
256
+ This is an empty table. It has no data so it only displays this strange thing.
257
+
258
+ A table that has columns but no rows — a query that came back empty — shows
259
+ its headers rather than raising:
260
+
261
+ ```
262
+ ┌──────┬───────┐
263
+ │ name │ value │
264
+ ╞══════╪═══════╡
265
+ └──────┴───────┘
266
+ ```
267
+
268
+ It's possible to add data as columns or rows, or even alternating each one. Any untitled column will be named automatically.
269
+
270
+ ### Code Example
271
+ ```
272
+ new_table.add_column('Name', ['Jade', 'John', 'Jane'])
273
+ new_table.add_column('Age', [20, 30, 40])
274
+ new_table.add_column('Results', [9.651, 3, 245.7])
275
+ print(new_table)
276
+ ```
277
+
278
+ ### Output
279
+ ```
280
+ +----------------------+
281
+ | Name Age Results |
282
+ +======+=====+=========+
283
+ | Jade | 20 | 9.651 |
284
+ | John | 30 | 3 |
285
+ | Jane | 40 | 245.7 |
286
+ +------+-----+---------+
287
+ ```
288
+
289
+ ### Code Example
290
+ ```
291
+ new_table = Table()
292
+ new_table.add_column('Name', ['Jade', 'John', 'Jane'])
293
+ new_table.add_column('Age', [20, 30, 40])
294
+ new_table.add_column('Test\nResults', [9.651, 3, 245.7])
295
+ new_table.add_row(['Piotr\nBaltimore', 27, 3.5])
296
+ new_table.add_row(['Sam', 21, 0.6519])
297
+ print(new_table)
298
+ ```
299
+
300
+ ### Output
301
+ ```
302
+ +----------------------------+
303
+ | Name Age Test |
304
+ | Results |
305
+ +===========+=====+==========+
306
+ | Jade | 20 | 9.651 |
307
+ | John | 30 | 3 |
308
+ | Jane | 40 | 245.7 |
309
+ | Piotr | 27 | 3.5 |
310
+ | Baltimore | | |
311
+ | Sam | 21 | 0.6519 |
312
+ +-----------+-----+----------+
313
+ ```
314
+ As it is visible, the table will format automatically new lines and data types, for now without trying to parse strings that could be converted to another type.
315
+
316
+ The ``Table`` class offers a variety of options that allow things like showing the index of each row, changing the style of the table, hiding the headers, etc.
317
+
318
+ See style examples [here](https://github.com/Opus-Perpetuus/flexablelib/blob/main/style_examples.md).
319
+
320
+ ### Code Example
321
+ ```
322
+ new_table = Table()
323
+ new_table.add_column('Name', ['Jade', 'John'])
324
+ new_table.add_column('Age', [20, 30])
325
+ new_table.add_column('Test\nResults', [9.651, 3, 245.7])
326
+ new_table.add_row(['Piotr\nBaltimore', 27, 3.5])
327
+ new_table.add_row(['Sam', 21])
328
+ new_table.show_index = True
329
+ new_table.style_name = 'pretty_columns'
330
+ new_table.missing_value = '?'
331
+ print(new_table)
332
+ ```
333
+
334
+ ### Output
335
+ ```
336
+ ╒═══╤═══════════╤═════╤═════════╕
337
+ │ i │ Name │ Age │ Test │
338
+ │ │ │ │ Results │
339
+ ╞═══╪═══════════╪═════╪═════════╡
340
+ │ 0 │ Jade │ 20 │ 9.651 │
341
+ │ 1 │ John │ 30 │ 3 │
342
+ │ 2 │ ? │ ? │ 245.7 │
343
+ │ 3 │ Piotr │ 27 │ 3.5 │
344
+ │ │ Baltimore │ │ │
345
+ │ 4 │ Sam │ 21 │ ? │
346
+ ╘═══╧═══════════╧═════╧═════════╛
347
+ ```
348
+ The missing value aligns as if it was of the same type of the other data in the column.
349
+
350
+ This shows how to get the row and column count. If the index is shown, this count remains unaffected by that column, although, you can get the internal count.
351
+
352
+ ### Code Example
353
+ ```
354
+ new_table.show_index = False
355
+ new_table.show_headers = False
356
+ print(new_table)
357
+ print('row:', new_table.row_count)
358
+ print('columns:', new_table.column_count)
359
+ new_table.show_index = True
360
+ print(new_table)
361
+ print('internal_row_count:', new_table.internal_row_count)
362
+ print('internal_column_count:', new_table.internal_column_count)
363
+ ```
364
+
365
+ ### Output
366
+ ```
367
+ ╒═══════════╤════╤═════════╕
368
+ │ Jade │ 20 │ 9.651 │
369
+ │ John │ 30 │ 3 │
370
+ │ ? │ ? │ 245.7 │
371
+ │ Piotr │ 27 │ 3.5 │
372
+ │ Baltimore │ │ │
373
+ │ Sam │ 21 │ ? │
374
+ ╘═══════════╧════╧═════════╛
375
+ row: 5
376
+ columns: 3
377
+ ╒═══╤═══════════╤════╤═════════╕
378
+ │ 0 │ Jade │ 20 │ 9.651 │
379
+ │ 1 │ John │ 30 │ 3 │
380
+ │ 2 │ ? │ ? │ 245.7 │
381
+ │ 3 │ Piotr │ 27 │ 3.5 │
382
+ │ │ Baltimore │ │ │
383
+ │ 4 │ Sam │ 21 │ ? │
384
+ ╘═══╧═══════════╧════╧═════════╛
385
+ internal_row_count: 5
386
+ internal_column_count: 4
387
+ ```
388
+
389
+ ## Colour
390
+
391
+ Colour the header, the borders, whole columns, whole rows, or individual cells.
392
+ Specs accept names, attributes, 256-colour indexes and hex triples.
393
+
394
+ ```python
395
+ table.header_color = 'bold cyan'
396
+ table.border_color = 'grey'
397
+ table.column_colors = {'Service': 'bright_white'}
398
+ table.color_rule = lambda value, row, column: (
399
+ 'red' if column == 'Delta' and value < 0 else None
400
+ )
401
+ ```
402
+
403
+ `color_rule` receives the original value, so numeric comparisons work directly.
404
+
405
+ Colour is emitted only to a terminal by default, and never when `NO_COLOR` is
406
+ set. `FORCE_COLOR` or `table.use_colors = True` overrides that. Because
407
+ `compose()` returns a string you may send anywhere, the default errs toward not
408
+ embedding escape sequences in something bound for a file.
409
+
410
+ Widths are measured in terminal columns, not characters, so coloured cells and
411
+ CJK or emoji data stay aligned.
412
+
413
+ ## Reading and writing
414
+
415
+ ```python
416
+ Table.from_csv('sales.csv') # numeric columns parsed and aligned
417
+ Table.from_html(markup) # standard library parser, no dependency
418
+ Table.from_dicts(records)
419
+ Table.from_pandas(dataframe) # pip install flexablelib[pandas]
420
+ Table.from_excel('report.xlsx') # pip install flexablelib[excel]
421
+
422
+ table.to_csv('out.csv')
423
+ table.to_markdown()
424
+ table.to_html('report.html', paginate=25)
425
+ table.to_excel('report.xlsx')
426
+ ```
427
+
428
+ `to_html` writes one self-contained file — the stylesheet and the sorting,
429
+ filtering and pagination script are inline — so it works offline and from a
430
+ `file://` URL.
431
+
432
+ Text formats deliver everything as strings, and a column of strings is
433
+ left-aligned. `parse_str_numbers` converts numeric-looking text so it aligns as
434
+ numbers; the readers turn it on for you:
435
+
436
+ ```python
437
+ table.parse_str_numbers = True
438
+ ```
439
+
440
+ Values with leading zeros are left alone, so `'007'` stays a string.
441
+
442
+ ## Merging cells
443
+
444
+ Render a rectangular block as a single cell, across columns, down rows, or
445
+ both. Coordinates are inclusive, zero-based, and ignore the index column.
446
+
447
+ ```python
448
+ table.merge_cells(0, 0, last_column=2, value='Quarter summary')
449
+ table.merge_cells(1, 0, last_row=3) # keeps the top-left content
450
+ table.merge_cells(0, 0, 2, 2, value='Total', align='r')
451
+ ```
452
+
453
+ A merge never widens the table -- columns are still sized by their unmerged
454
+ content -- so text longer than its span is truncated.
455
+
456
+ ## Notes
457
+
458
+ - A column named ``"i"`` does not collide with the index column (`utils.IndexColumnTitle`).
459
+ - Exponential numbers align on the decimal / exponent axis with the rest of the float column.
460
+ - Shrinking a float column drops decimals instead of chopping characters, so decimal alignment survives a terminal fit ([#23](https://github.com/Opus-Perpetuus/flexablelib/issues/23)).
461
+
462
+ Open work and the issue map: [docs/ISSUES.md](https://github.com/Opus-Perpetuus/flexablelib/blob/main/docs/ISSUES.md).
463
+
464
+ ## Project Layout
465
+
466
+ ```
467
+ flexablelib/ # GitHub repository
468
+ ├── flexablelib/ the Python package (no runtime dependencies)
469
+ │ ├── __init__.py public API: Table, TableComposition, SeparatorLine
470
+ │ ├── table.py the Table class — state and render orchestration
471
+ │ ├── columns.py type inference, alignment, column widths
472
+ │ ├── style_compositions.py the 56 border styles, as data
473
+ │ ├── table_strings.py separator lines and data rows
474
+ │ ├── cells.py cell padding, justification, wrapping
475
+ │ ├── options.py constants and defaults
476
+ │ └── utils.py type predicates and small helpers
477
+ ├── tests/ pytest suite — see ARCHITECTURE.md#testing
478
+ ├── docs/ issue history and design notes
479
+ ├── logos/ brand assets — see logos/README.md
480
+ ├── ARCHITECTURE.md how it all fits together
481
+ ├── style_examples.md all 56 styles rendered
482
+ ├── package.json canonical version number; drives the release
483
+ └── setup.py reads the version from package.json
484
+ ```
485
+
486
+ Run the tests from the repository root:
487
+
488
+ ```
489
+ pip install -r requirements-dev.txt
490
+ python -m pytest
491
+ ```
492
+
493
+ See [**ARCHITECTURE.md**](https://github.com/Opus-Perpetuus/flexablelib/blob/main/ARCHITECTURE.md) for the rendering pipeline, how styles are defined,
494
+ and how to add one.