dataframe-textual 3.4.0__tar.gz → 3.5.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.
Files changed (26) hide show
  1. dataframe_textual-3.4.0/README.md → dataframe_textual-3.5.0/PKG-INFO +117 -20
  2. dataframe_textual-3.4.0/PKG-INFO → dataframe_textual-3.5.0/README.md +77 -60
  3. {dataframe_textual-3.4.0 → dataframe_textual-3.5.0}/pyproject.toml +7 -7
  4. {dataframe_textual-3.4.0 → dataframe_textual-3.5.0}/src/dataframe_textual/__init__.py +0 -1
  5. {dataframe_textual-3.4.0 → dataframe_textual-3.5.0}/src/dataframe_textual/__main__.py +12 -14
  6. {dataframe_textual-3.4.0 → dataframe_textual-3.5.0}/src/dataframe_textual/commands.py +43 -17
  7. {dataframe_textual-3.4.0 → dataframe_textual-3.5.0}/src/dataframe_textual/common.py +19 -11
  8. {dataframe_textual-3.4.0 → dataframe_textual-3.5.0}/src/dataframe_textual/console_panel.py +2 -1
  9. {dataframe_textual-3.4.0 → dataframe_textual-3.5.0}/src/dataframe_textual/data_frame_table.py +213 -48
  10. {dataframe_textual-3.4.0 → dataframe_textual-3.5.0}/src/dataframe_textual/data_frame_viewer.py +12 -7
  11. {dataframe_textual-3.4.0 → dataframe_textual-3.5.0}/src/dataframe_textual/file_picker_screen.py +3 -3
  12. {dataframe_textual-3.4.0 → dataframe_textual-3.5.0}/src/dataframe_textual/loading_screen.py +4 -3
  13. dataframe_textual-3.5.0/src/dataframe_textual/plot_screen.py +581 -0
  14. {dataframe_textual-3.4.0 → dataframe_textual-3.5.0}/src/dataframe_textual/run_command_screen.py +2 -1
  15. {dataframe_textual-3.4.0 → dataframe_textual-3.5.0}/src/dataframe_textual/table_screen.py +50 -92
  16. {dataframe_textual-3.4.0 → dataframe_textual-3.5.0}/src/dataframe_textual/text_screen.py +2 -1
  17. {dataframe_textual-3.4.0 → dataframe_textual-3.5.0}/src/dataframe_textual/theme_screen.py +4 -2
  18. {dataframe_textual-3.4.0 → dataframe_textual-3.5.0}/src/dataframe_textual/yes_no_screen.py +10 -10
  19. {dataframe_textual-3.4.0 → dataframe_textual-3.5.0}/uv.lock +67 -290
  20. dataframe_textual-3.4.0/keys.log +0 -1
  21. {dataframe_textual-3.4.0 → dataframe_textual-3.5.0}/.gitignore +0 -0
  22. {dataframe_textual-3.4.0 → dataframe_textual-3.5.0}/LICENSE +0 -0
  23. {dataframe_textual-3.4.0 → dataframe_textual-3.5.0}/main.py +0 -0
  24. {dataframe_textual-3.4.0 → dataframe_textual-3.5.0}/src/dataframe_textual/help_panel.py +0 -0
  25. {dataframe_textual-3.4.0 → dataframe_textual-3.5.0}/src/dataframe_textual/keybindings.py +0 -0
  26. {dataframe_textual-3.4.0 → dataframe_textual-3.5.0}/src/dataframe_textual/status_bar.py +0 -0
@@ -1,6 +1,46 @@
1
+ Metadata-Version: 2.5
2
+ Name: dataframe-textual
3
+ Version: 3.5.0
4
+ Summary: Interactive terminal viewer/editor (TUI) for CSV/TSV, Excel, Parquet, JSONL, etc.
5
+ Project-URL: Homepage, https://github.com/need47/dataframe-textual
6
+ Project-URL: Repository, https://github.com/need47/dataframe-textual.git
7
+ Project-URL: Documentation, https://github.com/need47/dataframe-textual#readme
8
+ Project-URL: Bug Tracker, https://github.com/need47/dataframe-textual/issues
9
+ Author-email: Tiejun Cheng <need47@gmail.com>
10
+ License: MIT
11
+ License-File: LICENSE
12
+ Keywords: csv,data-analysis,editor,excel,interactive,jsonl,parquet,polars,terminal,textual,tsv,tui,viewer
13
+ Classifier: Development Status :: 3 - Alpha
14
+ Classifier: Environment :: Console
15
+ Classifier: Intended Audience :: Developers
16
+ Classifier: Intended Audience :: End Users/Desktop
17
+ Classifier: License :: OSI Approved :: MIT License
18
+ Classifier: Natural Language :: English
19
+ Classifier: Operating System :: MacOS
20
+ Classifier: Operating System :: POSIX
21
+ Classifier: Operating System :: Unix
22
+ Classifier: Programming Language :: Python :: 3
23
+ Classifier: Programming Language :: Python :: 3.13
24
+ Classifier: Programming Language :: Python :: 3.14
25
+ Classifier: Programming Language :: Python :: 3.15
26
+ Classifier: Topic :: Office/Business
27
+ Classifier: Topic :: Utilities
28
+ Classifier: Typing :: Typed
29
+ Requires-Python: >=3.13
30
+ Requires-Dist: fastexcel>=0.16.0
31
+ Requires-Dist: polars>=2.1.0
32
+ Requires-Dist: textual[syntax]>=8.2.8
33
+ Requires-Dist: xlsxwriter>=3.2.9
34
+ Provides-Extra: dev
35
+ Requires-Dist: textual-dev>=1.8.0; extra == 'dev'
36
+ Provides-Extra: extra
37
+ Requires-Dist: plotext>=6.1.0; extra == 'extra'
38
+ Requires-Dist: vortex-data>=0.93.0; extra == 'extra'
39
+ Description-Content-Type: text/markdown
40
+
1
41
  # DataFrame Textual
2
42
 
3
- A powerful, interactive terminal-based viewer/editor for CSV/TSV/Excel/[Parquet](https://parquet.apache.org/)/[Vortex](https://vortex.dev/)/JSON/[NDJSON](https://jsonlines.org/) built with Python, [Polars](https://pola.rs/), and [Textual](https://textual.textualize.io/). Inspired by [VisiData](https://www.visidata.org/), this tool provides smooth keyboard navigation, data manipulation, and a clean interface for exploring and analyzing tabular data directly in terminal with multi-tab support for multiple files!
43
+ A powerful, interactive terminal-based viewer/editor for CSV/TSV/Excel/[Parquet](https://parquet.apache.org/)/JSON/[NDJSON](https://jsonlines.org/)/[Vortex](https://vortex.dev/) built with Python, [Polars](https://pola.rs/), and [Textual](https://textual.textualize.io/). Inspired by [VisiData](https://www.visidata.org/), this tool provides smooth keyboard navigation, data manipulation, and a clean interface for exploring, analyzing, and plotting tabular data directly in terminal with multi-tab support for multiple files!
4
44
 
5
45
  ![Screenshot](https://raw.githubusercontent.com/need47/dataframe-textual/refs/heads/main/screenshots/main-table.png)
6
46
 
@@ -21,6 +61,7 @@ A powerful, interactive terminal-based viewer/editor for CSV/TSV/Excel/[Parquet]
21
61
  - 🔍 **Search & Filter** - Find values, highlight matches, and filter selected rows
22
62
  - ↔️ **Column/Row Reordering** - Move columns and rows with simple keyboard shortcuts
23
63
  - 📈 **Sorting & Statistics** - Multi-column sorting, frequency distribution, and histogram analysis
64
+ - 📊 **Plotting** - Draw line, scatter, box, bar, histogram, and confusion matrix plots via [plotext](https://github.com/piccolomo/plotext)
24
65
  - 💾 **Save & Undo** - Save edits back to file with full undo/redo support
25
66
 
26
67
  ### Advanced Features
@@ -64,8 +105,8 @@ uvx dataframe-textual <csvfile>
64
105
  git clone https://github.com/need47/dataframe-textual.git
65
106
  cd dataframe-textual
66
107
 
67
- # Install from local source with development dependencies
68
- pip install -e ".[dev]"
108
+ # Install from local source with development and extra dependencies
109
+ pip install -e ".[dev,extra]"
69
110
  ```
70
111
 
71
112
  ## Usage
@@ -368,6 +409,20 @@ Useful examples from current bindings:
368
409
  | `g^` | Set current row as the new header row |
369
410
  | `Shift+Tab` | Cycle cursor type (cell -> row -> column) |
370
411
 
412
+ #### Plotting
413
+
414
+ | Key | Action |
415
+ | ---- | ---------------------------------------------------------------------- |
416
+ | `pl` | Line plot: one numeric column against row position, or selected x/y |
417
+ | `ps` | Scatter plot: one numeric column against row position, or selected x/y |
418
+ | `po` | Box plot for selected numeric columns, or the current column |
419
+ | `pb` | Bar plot for selected numeric columns; a selected string column is x |
420
+ | `ph` | Histogram for selected numeric columns, or the current column |
421
+ | `pc` | Confusion matrix from two selected string columns |
422
+ | `pm` | Heatmap for selected numeric columns, or all visible columns |
423
+
424
+ Plot keys are leader sequences: press `p`, then the second key. They require the optional `plotext` package; install it with `pip install plotext`.
425
+
371
426
  #### Editing
372
427
 
373
428
  | Key | Action |
@@ -377,9 +432,9 @@ Useful examples from current bindings:
377
432
  | `Shift+Delete` | Clear current column (set matching cells to NULL) |
378
433
  | `e` | Edit current cell (respects data type) |
379
434
  | `E` | Edit entire column with value/expression |
380
- | `a` | Add empty column after current |
381
- | `A` | Add column with name and value/expression |
382
- | `i` | Add index column after current |
435
+ | `a` | Add an empty column after current |
436
+ | `A` | Add a column with name and value/expression |
437
+ | `i` | Add an index column after current |
383
438
  | `za` | Add a link column from URL template |
384
439
  | `^` | Rename current column |
385
440
  | `*` | Delete selected columns or current column |
@@ -413,20 +468,22 @@ Useful examples from current bindings:
413
468
  | `g,` | Select rows with cell matches or those matching cursor value in all columns |
414
469
  | `\|` (pipe) | Select rows where expression matches in current column |
415
470
  | `g\|` | Select rows where expression matches in all columns |
416
- | `\` | Unselect selected rows where expression matches in current column |
417
- | `g\` | Unselect selected rows where expression matches in all columns |
471
+ | `\` | Deselect selected rows where expression matches in current column |
472
+ | `g\` | Deselect selected rows where expression matches in all columns |
418
473
  | `{` | Go to previous selected row |
419
474
  | `}` | Go to next selected row |
420
475
  | `s` | Select/deselect current row |
421
476
  | `gs` | Select current row and all rows above |
422
477
  | `zs` | Select current row and all rows below |
423
- | `gu` | Unselect all rows |
478
+ | `gu` | Deselect all rows |
424
479
  | `'` (apostrophe) | Select/deselect current column |
425
480
  | `g'` | Select current column and all columns to the left |
426
481
  | `z'` | Select current column and all columns to the right |
427
482
  | `t` | Toggle row selections (invert) |
428
483
  | `T` | Clear all row/column selections and cell matches |
429
484
 
485
+ Column selections retain the order in which columns are selected, not their left-to-right table order. Each selected column header shows a check mark with a subscript number indicating its position in the selection. Deselecting and reselecting a column moves it to the end of selection. Selection order may affect subsequent operations. For example, scatter plot uses the first two selected columns as x and y.
486
+
430
487
  #### Find & Replace
431
488
 
432
489
  | Key | Action |
@@ -508,7 +565,7 @@ Useful examples from current bindings:
508
565
 
509
566
  These actions are the fastest way to get out of trouble after a mistaken edit, delete, sort, filter, or other table change.
510
567
 
511
- - `U`: Undo the last action and restore the previous state.
568
+ - `u` / `U`: Undo the last action and restore the previous state.
512
569
  - `R`: Redo the last undone action.
513
570
  - `gU`: Reset the table to its original loaded state if you want to start over.
514
571
 
@@ -688,13 +745,12 @@ The application provides multiple ways to select rows (for filtering or collecti
688
745
  - `g,` - Select rows with cell matches or those matching cursor value in all columns
689
746
  - `|` - Select rows where expression matches in the current column
690
747
  - `g|` - Select rows where expression matches in all columns
691
- - `\` - Unselect currently selected rows where expression matches in the current column
692
- - `g\` - Unselect currently selected rows where expression matches in all columns
748
+ - `\` - Deselect currently selected rows where expression matches in the current column
749
+ - `g\` - Deselect currently selected rows where expression matches in all columns
693
750
  - `s` - Select/deselect current row
694
751
  - `gs` - Select current row and all rows above
695
752
  - `zs` - Select current row and all rows below
696
- - `u` - Unselect the current row
697
- - `gu` - Unselect all rows
753
+ - `gu` - Deselect all rows
698
754
  - `'` (apostrophe) - Select/deselect current column
699
755
  - `g'` - Select current column and all columns to the left
700
756
  - `z'` - Select current column and all columns to the right
@@ -797,7 +853,7 @@ Both actions work on a subset of the original dataframe, but they serve differen
797
853
 
798
854
  **Collect** (`"`):
799
855
 
800
- - Creates a separate tab containing only the chosen rows/columns
856
+ - Creates a separate tab containing only the chosen rows and/or columns
801
857
  - The collected tab is independent from the source dataframe
802
858
  - Edits in the collected tab do not modify the original table
803
859
 
@@ -822,15 +878,16 @@ Editing covers cell updates, structural table changes, and quick cleanup.
822
878
 
823
879
  - `e` or **Double-click**: Edit the current cell with type-aware validation.
824
880
  - `^` or **Double-click** column header: Rename the current column.
825
- - `d`: Delete the selected rows, or the current row if nothing is selected.
881
+ - `d`: Delete the selected rows, or the current row if none is selected.
826
882
  - `gd`: Delete the current row and all rows above it.
827
883
  - `zd`: Delete the current row and all rows below it.
828
- - `*`: Delete selected columns, or the current column if nothing is selected.
884
+ - `*`: Delete selected columns, or the current column if none is selected.
829
885
  - `g*`: Delete the current column and all columns to its left.
830
886
  - `z*`: Delete the current column and all columns to its right.
831
887
  - `a`: Add an empty column after the current column.
832
888
  - `A`: Add a column after the current column using a value or expression such as `$age * 2`.
833
- - `i`: Insert an index column after the current column.
889
+ - `i`: Add an index column after the current column.
890
+ - `za`: Add a link column from URL template
834
891
  - `D`: Duplicate the current row.
835
892
  - `zD`: Duplicate the current column using a `_copy` suffix.
836
893
  - `zU`: Remove duplicate rows while keeping the first occurrence, based on visible-column values.
@@ -862,7 +919,7 @@ Editing covers cell updates, structural table changes, and quick cleanup.
862
919
  **Pin Column**: `!`
863
920
 
864
921
  - Moves the current column to the leftmost unfrozen position and freezes it
865
- - If columns are already frozen, appends to the frozen set (increments `fixed_columns`)
922
+ - If columns are already frozen, appends to the frozen set
866
923
 
867
924
  ### 16. Save File
868
925
 
@@ -947,6 +1004,13 @@ Complex values, filters, and advanced operations can be specified via Polars exp
947
1004
  - `$email.str.ends_with("@company.com")` - Email ends with domain
948
1005
  - `$code.str.starts_with("ABC")` - Code starts with "ABC"
949
1006
  - `$name.str.len_chars() < 7` - Length of name shorter than 7
1007
+ - `$name.str.to_lowercase() == "alice"` - Match regardless of letter case
1008
+ - `$name.str.strip_chars() == "Alice"` - Ignore leading and trailing whitespace
1009
+ - `$description.str.replace("old", "new") == "new value"` - Replace the first occurrence
1010
+ - `$description.str.replace_all("old", "new").str.contains("new")` - Replace all occurrences, then check the result
1011
+ - `$code.str.slice(0, 3) == "ABC"` - First three characters match "ABC"
1012
+ - `$path.str.split("/").list.last() == "report.csv"` - Last slash-separated part is "report.csv"
1013
+ - `$text.str.contains(r"\d+")` - Text contains one or more digits (regex)
950
1014
 
951
1015
  **Number Operations:**
952
1016
 
@@ -954,6 +1018,18 @@ Complex values, filters, and advanced operations can be specified via Polars exp
954
1018
  - `($salary + $bonus) > 150000` - Total compensation over 150,000
955
1019
  - `$percentage >= 50` - Percentage at least 50%
956
1020
 
1021
+ **List Operations:** ([Polars list API reference](https://docs.pola.rs/api/python/stable/reference/series/list.html))
1022
+
1023
+ - `$tags.list.contains("python")` - List column contains the value "python"
1024
+ - `$scores.list.len() > 3` - List has more than 3 elements
1025
+ - `$scores.list.max() >= 90` - Largest element at least 90
1026
+ - `$scores.list.min() < 10` - Smallest element less than 10
1027
+ - `$scores.list.sum() > 100` - Sum of elements greater than 100
1028
+ - `$scores.list.mean() >= 75` - Average of elements at least 75
1029
+ - `$items.list.first() == 'A'` - First element is 'A'
1030
+ - `$items.list.last() != 'Z'` - Last element is not 'Z'
1031
+ - `$items.list.get(1) == 'B'` - Second element (0-based index) is 'B'
1032
+
957
1033
  **Null Handling:**
958
1034
 
959
1035
  - `$column.is_null()` - Find null values
@@ -1045,6 +1121,26 @@ Use the built-in Python console for quick interactive transformations without le
1045
1121
 
1046
1122
  ![Python Console](https://raw.githubusercontent.com/need47/dataframe-textual/refs/heads/main/screenshots/python-console.png)
1047
1123
 
1124
+ ### 23. Plotting
1125
+
1126
+ Plot commands open a plot modal. Most plots require numeric data columns; confusion matrices use string labels, and bar plots can use string category labels. Install the optional dependency with `pip install plotext` if plotting is unavailable.
1127
+
1128
+ - `pl`: Line plot. With one selected numeric column, row position is used for x; with two selected numeric columns, the first is x and the second is y. With no selection, the cursor column is plotted against row position.
1129
+ - `ps`: Scatter plot with the same one-column or x/y selection behavior as line plots.
1130
+ - `po`: Box plots for selected numeric columns, or the cursor column if none are selected.
1131
+ - `pb`: Bar plot for selected numeric columns. When the first selected column is a string, it supplies category labels and the remaining selected columns are numeric series. Otherwise, selected numeric columns are plotted against row positions.
1132
+ - `ph`: Histograms for selected numeric columns, or the cursor column if none are selected.
1133
+ - `pc`: Confusion matrix from exactly two selected string columns. Select the actual/true-label column first and the predicted-label column second. Rows represent actual labels; columns represent predicted labels. Each cell shows the count for that label pair.
1134
+
1135
+ **Plot modal controls:**
1136
+
1137
+ - `q` / `Escape`: Closes the plot.
1138
+ - `x` / `y`: Independently toggles the corresponding axis between linear (default) and logarithmic scales. Logarithmic axes require strictly positive plotted coordinates, including baselines and cell edges.
1139
+ - `o`: Toggles vertical/horizontal orientation for bar, box and histgram plots
1140
+ - Bar plot: `s` toggles grouped/stacked bars, and `c` cycles data labels through none, counts, percentages, and counts plus percentages. Percentages are calculated within each series.
1141
+ - Histogram: `#` sets the bin count (default `10`), and `n` toggles normalization of bin counts to proportions.
1142
+ - Confusion matrix: `n` toggles between raw counts (default) and normalized percentages.
1143
+
1048
1144
  ## Handling Loading Errors
1049
1145
 
1050
1146
  Most loading failures come from malformed CSV/TSV input, quoting issues, or mixed column types. When this happens, the application prints a hint with a suggested retry option.
@@ -1109,11 +1205,12 @@ dv partially_broken.csv -E
1109
1205
  - **textual**: Terminal UI framework
1110
1206
  - **fastexcel**: Read Excel files
1111
1207
  - **xlsxwriter**: Write Excel files
1208
+ - **plotext**: Render interactive terminal plots (optional)
1112
1209
  - **vortex-data**: Read/Write Vortex files (optional)
1113
1210
 
1114
1211
  ## Requirements
1115
1212
 
1116
- - Python 3.11+
1213
+ - Python 3.13+
1117
1214
  - POSIX-compatible terminal (macOS, Linux, WSL)
1118
1215
  - Terminal supporting ANSI escape sequences and mouse events
1119
1216
 
@@ -1,46 +1,6 @@
1
- Metadata-Version: 2.5
2
- Name: dataframe-textual
3
- Version: 3.4.0
4
- Summary: Interactive terminal viewer/editor (TUI) for CSV/TSV, Excel, Parquet, JSONL, etc.
5
- Project-URL: Homepage, https://github.com/need47/dataframe-textual
6
- Project-URL: Repository, https://github.com/need47/dataframe-textual.git
7
- Project-URL: Documentation, https://github.com/need47/dataframe-textual#readme
8
- Project-URL: Bug Tracker, https://github.com/need47/dataframe-textual/issues
9
- Author-email: Tiejun Cheng <need47@gmail.com>
10
- License: MIT
11
- License-File: LICENSE
12
- Keywords: csv,data-analysis,editor,excel,interactive,jsonl,parquet,polars,terminal,textual,tsv,tui,viewer
13
- Classifier: Development Status :: 3 - Alpha
14
- Classifier: Environment :: Console
15
- Classifier: Intended Audience :: Developers
16
- Classifier: Intended Audience :: End Users/Desktop
17
- Classifier: License :: OSI Approved :: MIT License
18
- Classifier: Natural Language :: English
19
- Classifier: Operating System :: MacOS
20
- Classifier: Operating System :: POSIX
21
- Classifier: Operating System :: Unix
22
- Classifier: Programming Language :: Python :: 3
23
- Classifier: Programming Language :: Python :: 3.11
24
- Classifier: Programming Language :: Python :: 3.12
25
- Classifier: Programming Language :: Python :: 3.13
26
- Classifier: Programming Language :: Python :: 3.14
27
- Classifier: Topic :: Office/Business
28
- Classifier: Topic :: Utilities
29
- Classifier: Typing :: Typed
30
- Requires-Python: >=3.11
31
- Requires-Dist: fastexcel>=0.16.0
32
- Requires-Dist: polars>=2.1.0
33
- Requires-Dist: textual[syntax]>=8.0.2
34
- Requires-Dist: xlsxwriter>=3.2.9
35
- Provides-Extra: dev
36
- Requires-Dist: textual-dev>=1.8.0; extra == 'dev'
37
- Provides-Extra: vortex
38
- Requires-Dist: vortex-data>=0.75.0; extra == 'vortex'
39
- Description-Content-Type: text/markdown
40
-
41
1
  # DataFrame Textual
42
2
 
43
- A powerful, interactive terminal-based viewer/editor for CSV/TSV/Excel/[Parquet](https://parquet.apache.org/)/[Vortex](https://vortex.dev/)/JSON/[NDJSON](https://jsonlines.org/) built with Python, [Polars](https://pola.rs/), and [Textual](https://textual.textualize.io/). Inspired by [VisiData](https://www.visidata.org/), this tool provides smooth keyboard navigation, data manipulation, and a clean interface for exploring and analyzing tabular data directly in terminal with multi-tab support for multiple files!
3
+ A powerful, interactive terminal-based viewer/editor for CSV/TSV/Excel/[Parquet](https://parquet.apache.org/)/JSON/[NDJSON](https://jsonlines.org/)/[Vortex](https://vortex.dev/) built with Python, [Polars](https://pola.rs/), and [Textual](https://textual.textualize.io/). Inspired by [VisiData](https://www.visidata.org/), this tool provides smooth keyboard navigation, data manipulation, and a clean interface for exploring, analyzing, and plotting tabular data directly in terminal with multi-tab support for multiple files!
44
4
 
45
5
  ![Screenshot](https://raw.githubusercontent.com/need47/dataframe-textual/refs/heads/main/screenshots/main-table.png)
46
6
 
@@ -61,6 +21,7 @@ A powerful, interactive terminal-based viewer/editor for CSV/TSV/Excel/[Parquet]
61
21
  - 🔍 **Search & Filter** - Find values, highlight matches, and filter selected rows
62
22
  - ↔️ **Column/Row Reordering** - Move columns and rows with simple keyboard shortcuts
63
23
  - 📈 **Sorting & Statistics** - Multi-column sorting, frequency distribution, and histogram analysis
24
+ - 📊 **Plotting** - Draw line, scatter, box, bar, histogram, and confusion matrix plots via [plotext](https://github.com/piccolomo/plotext)
64
25
  - 💾 **Save & Undo** - Save edits back to file with full undo/redo support
65
26
 
66
27
  ### Advanced Features
@@ -104,8 +65,8 @@ uvx dataframe-textual <csvfile>
104
65
  git clone https://github.com/need47/dataframe-textual.git
105
66
  cd dataframe-textual
106
67
 
107
- # Install from local source with development dependencies
108
- pip install -e ".[dev]"
68
+ # Install from local source with development and extra dependencies
69
+ pip install -e ".[dev,extra]"
109
70
  ```
110
71
 
111
72
  ## Usage
@@ -408,6 +369,20 @@ Useful examples from current bindings:
408
369
  | `g^` | Set current row as the new header row |
409
370
  | `Shift+Tab` | Cycle cursor type (cell -> row -> column) |
410
371
 
372
+ #### Plotting
373
+
374
+ | Key | Action |
375
+ | ---- | ---------------------------------------------------------------------- |
376
+ | `pl` | Line plot: one numeric column against row position, or selected x/y |
377
+ | `ps` | Scatter plot: one numeric column against row position, or selected x/y |
378
+ | `po` | Box plot for selected numeric columns, or the current column |
379
+ | `pb` | Bar plot for selected numeric columns; a selected string column is x |
380
+ | `ph` | Histogram for selected numeric columns, or the current column |
381
+ | `pc` | Confusion matrix from two selected string columns |
382
+ | `pm` | Heatmap for selected numeric columns, or all visible columns |
383
+
384
+ Plot keys are leader sequences: press `p`, then the second key. They require the optional `plotext` package; install it with `pip install plotext`.
385
+
411
386
  #### Editing
412
387
 
413
388
  | Key | Action |
@@ -417,9 +392,9 @@ Useful examples from current bindings:
417
392
  | `Shift+Delete` | Clear current column (set matching cells to NULL) |
418
393
  | `e` | Edit current cell (respects data type) |
419
394
  | `E` | Edit entire column with value/expression |
420
- | `a` | Add empty column after current |
421
- | `A` | Add column with name and value/expression |
422
- | `i` | Add index column after current |
395
+ | `a` | Add an empty column after current |
396
+ | `A` | Add a column with name and value/expression |
397
+ | `i` | Add an index column after current |
423
398
  | `za` | Add a link column from URL template |
424
399
  | `^` | Rename current column |
425
400
  | `*` | Delete selected columns or current column |
@@ -453,20 +428,22 @@ Useful examples from current bindings:
453
428
  | `g,` | Select rows with cell matches or those matching cursor value in all columns |
454
429
  | `\|` (pipe) | Select rows where expression matches in current column |
455
430
  | `g\|` | Select rows where expression matches in all columns |
456
- | `\` | Unselect selected rows where expression matches in current column |
457
- | `g\` | Unselect selected rows where expression matches in all columns |
431
+ | `\` | Deselect selected rows where expression matches in current column |
432
+ | `g\` | Deselect selected rows where expression matches in all columns |
458
433
  | `{` | Go to previous selected row |
459
434
  | `}` | Go to next selected row |
460
435
  | `s` | Select/deselect current row |
461
436
  | `gs` | Select current row and all rows above |
462
437
  | `zs` | Select current row and all rows below |
463
- | `gu` | Unselect all rows |
438
+ | `gu` | Deselect all rows |
464
439
  | `'` (apostrophe) | Select/deselect current column |
465
440
  | `g'` | Select current column and all columns to the left |
466
441
  | `z'` | Select current column and all columns to the right |
467
442
  | `t` | Toggle row selections (invert) |
468
443
  | `T` | Clear all row/column selections and cell matches |
469
444
 
445
+ Column selections retain the order in which columns are selected, not their left-to-right table order. Each selected column header shows a check mark with a subscript number indicating its position in the selection. Deselecting and reselecting a column moves it to the end of selection. Selection order may affect subsequent operations. For example, scatter plot uses the first two selected columns as x and y.
446
+
470
447
  #### Find & Replace
471
448
 
472
449
  | Key | Action |
@@ -548,7 +525,7 @@ Useful examples from current bindings:
548
525
 
549
526
  These actions are the fastest way to get out of trouble after a mistaken edit, delete, sort, filter, or other table change.
550
527
 
551
- - `U`: Undo the last action and restore the previous state.
528
+ - `u` / `U`: Undo the last action and restore the previous state.
552
529
  - `R`: Redo the last undone action.
553
530
  - `gU`: Reset the table to its original loaded state if you want to start over.
554
531
 
@@ -728,13 +705,12 @@ The application provides multiple ways to select rows (for filtering or collecti
728
705
  - `g,` - Select rows with cell matches or those matching cursor value in all columns
729
706
  - `|` - Select rows where expression matches in the current column
730
707
  - `g|` - Select rows where expression matches in all columns
731
- - `\` - Unselect currently selected rows where expression matches in the current column
732
- - `g\` - Unselect currently selected rows where expression matches in all columns
708
+ - `\` - Deselect currently selected rows where expression matches in the current column
709
+ - `g\` - Deselect currently selected rows where expression matches in all columns
733
710
  - `s` - Select/deselect current row
734
711
  - `gs` - Select current row and all rows above
735
712
  - `zs` - Select current row and all rows below
736
- - `u` - Unselect the current row
737
- - `gu` - Unselect all rows
713
+ - `gu` - Deselect all rows
738
714
  - `'` (apostrophe) - Select/deselect current column
739
715
  - `g'` - Select current column and all columns to the left
740
716
  - `z'` - Select current column and all columns to the right
@@ -837,7 +813,7 @@ Both actions work on a subset of the original dataframe, but they serve differen
837
813
 
838
814
  **Collect** (`"`):
839
815
 
840
- - Creates a separate tab containing only the chosen rows/columns
816
+ - Creates a separate tab containing only the chosen rows and/or columns
841
817
  - The collected tab is independent from the source dataframe
842
818
  - Edits in the collected tab do not modify the original table
843
819
 
@@ -862,15 +838,16 @@ Editing covers cell updates, structural table changes, and quick cleanup.
862
838
 
863
839
  - `e` or **Double-click**: Edit the current cell with type-aware validation.
864
840
  - `^` or **Double-click** column header: Rename the current column.
865
- - `d`: Delete the selected rows, or the current row if nothing is selected.
841
+ - `d`: Delete the selected rows, or the current row if none is selected.
866
842
  - `gd`: Delete the current row and all rows above it.
867
843
  - `zd`: Delete the current row and all rows below it.
868
- - `*`: Delete selected columns, or the current column if nothing is selected.
844
+ - `*`: Delete selected columns, or the current column if none is selected.
869
845
  - `g*`: Delete the current column and all columns to its left.
870
846
  - `z*`: Delete the current column and all columns to its right.
871
847
  - `a`: Add an empty column after the current column.
872
848
  - `A`: Add a column after the current column using a value or expression such as `$age * 2`.
873
- - `i`: Insert an index column after the current column.
849
+ - `i`: Add an index column after the current column.
850
+ - `za`: Add a link column from URL template
874
851
  - `D`: Duplicate the current row.
875
852
  - `zD`: Duplicate the current column using a `_copy` suffix.
876
853
  - `zU`: Remove duplicate rows while keeping the first occurrence, based on visible-column values.
@@ -902,7 +879,7 @@ Editing covers cell updates, structural table changes, and quick cleanup.
902
879
  **Pin Column**: `!`
903
880
 
904
881
  - Moves the current column to the leftmost unfrozen position and freezes it
905
- - If columns are already frozen, appends to the frozen set (increments `fixed_columns`)
882
+ - If columns are already frozen, appends to the frozen set
906
883
 
907
884
  ### 16. Save File
908
885
 
@@ -987,6 +964,13 @@ Complex values, filters, and advanced operations can be specified via Polars exp
987
964
  - `$email.str.ends_with("@company.com")` - Email ends with domain
988
965
  - `$code.str.starts_with("ABC")` - Code starts with "ABC"
989
966
  - `$name.str.len_chars() < 7` - Length of name shorter than 7
967
+ - `$name.str.to_lowercase() == "alice"` - Match regardless of letter case
968
+ - `$name.str.strip_chars() == "Alice"` - Ignore leading and trailing whitespace
969
+ - `$description.str.replace("old", "new") == "new value"` - Replace the first occurrence
970
+ - `$description.str.replace_all("old", "new").str.contains("new")` - Replace all occurrences, then check the result
971
+ - `$code.str.slice(0, 3) == "ABC"` - First three characters match "ABC"
972
+ - `$path.str.split("/").list.last() == "report.csv"` - Last slash-separated part is "report.csv"
973
+ - `$text.str.contains(r"\d+")` - Text contains one or more digits (regex)
990
974
 
991
975
  **Number Operations:**
992
976
 
@@ -994,6 +978,18 @@ Complex values, filters, and advanced operations can be specified via Polars exp
994
978
  - `($salary + $bonus) > 150000` - Total compensation over 150,000
995
979
  - `$percentage >= 50` - Percentage at least 50%
996
980
 
981
+ **List Operations:** ([Polars list API reference](https://docs.pola.rs/api/python/stable/reference/series/list.html))
982
+
983
+ - `$tags.list.contains("python")` - List column contains the value "python"
984
+ - `$scores.list.len() > 3` - List has more than 3 elements
985
+ - `$scores.list.max() >= 90` - Largest element at least 90
986
+ - `$scores.list.min() < 10` - Smallest element less than 10
987
+ - `$scores.list.sum() > 100` - Sum of elements greater than 100
988
+ - `$scores.list.mean() >= 75` - Average of elements at least 75
989
+ - `$items.list.first() == 'A'` - First element is 'A'
990
+ - `$items.list.last() != 'Z'` - Last element is not 'Z'
991
+ - `$items.list.get(1) == 'B'` - Second element (0-based index) is 'B'
992
+
997
993
  **Null Handling:**
998
994
 
999
995
  - `$column.is_null()` - Find null values
@@ -1085,6 +1081,26 @@ Use the built-in Python console for quick interactive transformations without le
1085
1081
 
1086
1082
  ![Python Console](https://raw.githubusercontent.com/need47/dataframe-textual/refs/heads/main/screenshots/python-console.png)
1087
1083
 
1084
+ ### 23. Plotting
1085
+
1086
+ Plot commands open a plot modal. Most plots require numeric data columns; confusion matrices use string labels, and bar plots can use string category labels. Install the optional dependency with `pip install plotext` if plotting is unavailable.
1087
+
1088
+ - `pl`: Line plot. With one selected numeric column, row position is used for x; with two selected numeric columns, the first is x and the second is y. With no selection, the cursor column is plotted against row position.
1089
+ - `ps`: Scatter plot with the same one-column or x/y selection behavior as line plots.
1090
+ - `po`: Box plots for selected numeric columns, or the cursor column if none are selected.
1091
+ - `pb`: Bar plot for selected numeric columns. When the first selected column is a string, it supplies category labels and the remaining selected columns are numeric series. Otherwise, selected numeric columns are plotted against row positions.
1092
+ - `ph`: Histograms for selected numeric columns, or the cursor column if none are selected.
1093
+ - `pc`: Confusion matrix from exactly two selected string columns. Select the actual/true-label column first and the predicted-label column second. Rows represent actual labels; columns represent predicted labels. Each cell shows the count for that label pair.
1094
+
1095
+ **Plot modal controls:**
1096
+
1097
+ - `q` / `Escape`: Closes the plot.
1098
+ - `x` / `y`: Independently toggles the corresponding axis between linear (default) and logarithmic scales. Logarithmic axes require strictly positive plotted coordinates, including baselines and cell edges.
1099
+ - `o`: Toggles vertical/horizontal orientation for bar, box and histgram plots
1100
+ - Bar plot: `s` toggles grouped/stacked bars, and `c` cycles data labels through none, counts, percentages, and counts plus percentages. Percentages are calculated within each series.
1101
+ - Histogram: `#` sets the bin count (default `10`), and `n` toggles normalization of bin counts to proportions.
1102
+ - Confusion matrix: `n` toggles between raw counts (default) and normalized percentages.
1103
+
1088
1104
  ## Handling Loading Errors
1089
1105
 
1090
1106
  Most loading failures come from malformed CSV/TSV input, quoting issues, or mixed column types. When this happens, the application prints a hint with a suggested retry option.
@@ -1149,11 +1165,12 @@ dv partially_broken.csv -E
1149
1165
  - **textual**: Terminal UI framework
1150
1166
  - **fastexcel**: Read Excel files
1151
1167
  - **xlsxwriter**: Write Excel files
1168
+ - **plotext**: Render interactive terminal plots (optional)
1152
1169
  - **vortex-data**: Read/Write Vortex files (optional)
1153
1170
 
1154
1171
  ## Requirements
1155
1172
 
1156
- - Python 3.11+
1173
+ - Python 3.13+
1157
1174
  - POSIX-compatible terminal (macOS, Linux, WSL)
1158
1175
  - Terminal supporting ANSI escape sequences and mouse events
1159
1176
 
@@ -4,10 +4,10 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "dataframe-textual"
7
- version = "3.4.0"
7
+ version = "3.5.0"
8
8
  description = "Interactive terminal viewer/editor (TUI) for CSV/TSV, Excel, Parquet, JSONL, etc."
9
9
  readme = "README.md"
10
- requires-python = ">=3.11"
10
+ requires-python = ">=3.13"
11
11
  license = {text = "MIT"}
12
12
  authors = [
13
13
  {name = "Tiejun Cheng", email = "need47@gmail.com"}
@@ -24,10 +24,9 @@ classifiers = [
24
24
  "Operating System :: Unix",
25
25
  "Operating System :: POSIX",
26
26
  "Programming Language :: Python :: 3",
27
- "Programming Language :: Python :: 3.11",
28
- "Programming Language :: Python :: 3.12",
29
27
  "Programming Language :: Python :: 3.13",
30
28
  "Programming Language :: Python :: 3.14",
29
+ "Programming Language :: Python :: 3.15",
31
30
  "Topic :: Office/Business",
32
31
  "Topic :: Utilities",
33
32
  "Typing :: Typed",
@@ -35,7 +34,7 @@ classifiers = [
35
34
  dependencies = [
36
35
  "fastexcel>=0.16.0",
37
36
  "xlsxwriter>=3.2.9",
38
- "textual[syntax]>=8.0.2",
37
+ "textual[syntax]>=8.2.8",
39
38
  "polars>=2.1.0",
40
39
  ]
41
40
 
@@ -49,8 +48,9 @@ Documentation = "https://github.com/need47/dataframe-textual#readme"
49
48
  dev = [
50
49
  "textual-dev>=1.8.0",
51
50
  ]
52
- vortex = [
53
- "vortex-data>=0.75.0",
51
+ extra = [
52
+ "plotext>=6.1.0",
53
+ "vortex-data>=0.93.0",
54
54
  ]
55
55
 
56
56
  [[tool.uv.index]]
@@ -50,6 +50,5 @@ __all__ = [
50
50
  "SearchScreen",
51
51
  "StatisticsScreen",
52
52
  "TableScreen",
53
- "SearchScreen",
54
53
  "YesNoScreen",
55
54
  ]
@@ -314,21 +314,19 @@ def validate_args(args: argparse.Namespace) -> None:
314
314
  print("Cannot specify both delimiter and format.", file=sys.stderr)
315
315
  sys.exit(1)
316
316
 
317
- if args.output:
318
- if not guess_file_format(args.output):
319
- print(
320
- f"Unsupported output file format for `{args.output}`. Supported formats: {', '.join(SUPPORTED_FORMATS)}",
321
- file=sys.stderr,
322
- )
323
- sys.exit(1)
317
+ if args.output and not guess_file_format(args.output):
318
+ print(
319
+ f"Unsupported output file format for `{args.output}`. Supported formats: {', '.join(SUPPORTED_FORMATS)}",
320
+ file=sys.stderr,
321
+ )
322
+ sys.exit(1)
324
323
 
325
- if args.expr:
326
- if not tentative_expr(args.expr):
327
- print(
328
- f"Invalid expression: `{args.expr}`. Did you forget the `$` prefix for column references?",
329
- file=sys.stderr,
330
- )
331
- sys.exit(1)
324
+ if args.expr and not tentative_expr(args.expr):
325
+ print(
326
+ f"Invalid expression: `{args.expr}`. Did you forget the `$` prefix for column references?",
327
+ file=sys.stderr,
328
+ )
329
+ sys.exit(1)
332
330
 
333
331
 
334
332
  if __name__ == "__main__":