dataframe-textual 3.3.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 (25) hide show
  1. {dataframe_textual-3.3.0 → dataframe_textual-3.5.0}/.gitignore +1 -0
  2. dataframe_textual-3.3.0/README.md → dataframe_textual-3.5.0/PKG-INFO +137 -38
  3. dataframe_textual-3.3.0/PKG-INFO → dataframe_textual-3.5.0/README.md +97 -78
  4. {dataframe_textual-3.3.0 → dataframe_textual-3.5.0}/pyproject.toml +11 -8
  5. {dataframe_textual-3.3.0 → dataframe_textual-3.5.0}/src/dataframe_textual/__init__.py +0 -1
  6. {dataframe_textual-3.3.0 → dataframe_textual-3.5.0}/src/dataframe_textual/__main__.py +14 -15
  7. {dataframe_textual-3.3.0 → dataframe_textual-3.5.0}/src/dataframe_textual/commands.py +43 -17
  8. {dataframe_textual-3.3.0 → dataframe_textual-3.5.0}/src/dataframe_textual/common.py +21 -13
  9. {dataframe_textual-3.3.0 → dataframe_textual-3.5.0}/src/dataframe_textual/console_panel.py +2 -1
  10. {dataframe_textual-3.3.0 → dataframe_textual-3.5.0}/src/dataframe_textual/data_frame_table.py +254 -62
  11. {dataframe_textual-3.3.0 → dataframe_textual-3.5.0}/src/dataframe_textual/data_frame_viewer.py +13 -8
  12. {dataframe_textual-3.3.0 → dataframe_textual-3.5.0}/src/dataframe_textual/file_picker_screen.py +3 -3
  13. {dataframe_textual-3.3.0 → dataframe_textual-3.5.0}/src/dataframe_textual/loading_screen.py +4 -3
  14. dataframe_textual-3.5.0/src/dataframe_textual/plot_screen.py +581 -0
  15. {dataframe_textual-3.3.0 → dataframe_textual-3.5.0}/src/dataframe_textual/run_command_screen.py +2 -1
  16. {dataframe_textual-3.3.0 → dataframe_textual-3.5.0}/src/dataframe_textual/table_screen.py +50 -92
  17. {dataframe_textual-3.3.0 → dataframe_textual-3.5.0}/src/dataframe_textual/text_screen.py +2 -1
  18. {dataframe_textual-3.3.0 → dataframe_textual-3.5.0}/src/dataframe_textual/theme_screen.py +4 -2
  19. {dataframe_textual-3.3.0 → dataframe_textual-3.5.0}/src/dataframe_textual/yes_no_screen.py +10 -10
  20. {dataframe_textual-3.3.0 → dataframe_textual-3.5.0}/uv.lock +82 -305
  21. {dataframe_textual-3.3.0 → dataframe_textual-3.5.0}/LICENSE +0 -0
  22. {dataframe_textual-3.3.0 → dataframe_textual-3.5.0}/main.py +0 -0
  23. {dataframe_textual-3.3.0 → dataframe_textual-3.5.0}/src/dataframe_textual/help_panel.py +0 -0
  24. {dataframe_textual-3.3.0 → dataframe_textual-3.5.0}/src/dataframe_textual/keybindings.py +0 -0
  25. {dataframe_textual-3.3.0 → dataframe_textual-3.5.0}/src/dataframe_textual/status_bar.py +0 -0
@@ -20,3 +20,4 @@ test.py
20
20
  *.jsonl
21
21
  *.vortex
22
22
  .DS_Store
23
+ *.zst
@@ -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
@@ -314,29 +355,31 @@ Useful examples from current bindings:
314
355
 
315
356
  #### Undo/Redo/Reset
316
357
 
317
- | Key | Action |
318
- | ---- | ----------------------- |
358
+ | Key | Action |
359
+ | --------- | ----------------------- |
319
360
  | `u` / `U` | Undo last action |
320
361
  | `R` | Redo last undone action |
321
- | `gU` | Reset to initial state |
362
+ | `gU` | Reset to initial state |
322
363
 
323
364
  #### Navigation
324
365
 
325
- | Key | Action |
326
- | ------------------------ | ----------------------------------- |
327
- | `gg` | Go to first row |
328
- | `G` | Go to last row |
329
- | `Ctrl+G` | Go to specific row |
330
- | `←` / `↓` / `↑` / `→` | Move left/down/up/right |
331
- | `h` / `j` / `k` / `l` | Move left/down/up/right (Vim-style) |
332
- | `gh` / `g←` | Scroll to leftmost column |
333
- | `gj` / `g↓` | Scroll to last row |
334
- | `gk` / `g↑` | Scroll to first row |
335
- | `gl` / `g→` | Scroll to rightmost column |
336
- | `Home` / `End` | Go to first/last column |
337
- | `Ctrl+Home` / `Ctrl+End` | Go to page top/bottom |
338
- | `PageUp` / `Ctrl+B` | Page backward |
339
- | `PageDown` / `Ctrl+F` | Page forward |
366
+ | Key | Action |
367
+ | ------------------------------------------------- | ----------------------------------- |
368
+ | `gg` | Go to first row |
369
+ | `G` | Go to last row |
370
+ | `Ctrl+G` | Go to specific row |
371
+ | `←` / `↓` / `↑` / `→` | Move left/down/up/right |
372
+ | `h` / `j` / `k` / `l` | Move left/down/up/right (Vim-style) |
373
+ | `gh` / `g←` | Scroll to leftmost column |
374
+ | `gj` / `g↓` | Scroll to last row |
375
+ | `gk` / `g↑` | Scroll to first row |
376
+ | `gl` / `g→` | Scroll to rightmost column |
377
+ | `Home` / `End` | Go to first/last column |
378
+ | `Ctrl+Home` / `Ctrl+End` | Go to page top/bottom |
379
+ | `PageUp` / `Ctrl+B` | Page backward |
380
+ | `PageDown` / `Ctrl+F` | Page forward |
381
+ | `MouseScrollUp` / `MouseScrollDown` | Scroll vertically |
382
+ | `Ctrl + MouseScrollUp` / `Ctrl + MouseScrollDown` | Scroll horizontally |
340
383
 
341
384
  #### Display
342
385
 
@@ -366,6 +409,20 @@ Useful examples from current bindings:
366
409
  | `g^` | Set current row as the new header row |
367
410
  | `Shift+Tab` | Cycle cursor type (cell -> row -> column) |
368
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
+
369
426
  #### Editing
370
427
 
371
428
  | Key | Action |
@@ -375,9 +432,9 @@ Useful examples from current bindings:
375
432
  | `Shift+Delete` | Clear current column (set matching cells to NULL) |
376
433
  | `e` | Edit current cell (respects data type) |
377
434
  | `E` | Edit entire column with value/expression |
378
- | `a` | Add empty column after current |
379
- | `A` | Add column with name and value/expression |
380
- | `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 |
381
438
  | `za` | Add a link column from URL template |
382
439
  | `^` | Rename current column |
383
440
  | `*` | Delete selected columns or current column |
@@ -411,20 +468,22 @@ Useful examples from current bindings:
411
468
  | `g,` | Select rows with cell matches or those matching cursor value in all columns |
412
469
  | `\|` (pipe) | Select rows where expression matches in current column |
413
470
  | `g\|` | Select rows where expression matches in all columns |
414
- | `\` | Unselect selected rows where expression matches in current column |
415
- | `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 |
416
473
  | `{` | Go to previous selected row |
417
474
  | `}` | Go to next selected row |
418
475
  | `s` | Select/deselect current row |
419
476
  | `gs` | Select current row and all rows above |
420
477
  | `zs` | Select current row and all rows below |
421
- | `gu` | Unselect all rows |
478
+ | `gu` | Deselect all rows |
422
479
  | `'` (apostrophe) | Select/deselect current column |
423
480
  | `g'` | Select current column and all columns to the left |
424
481
  | `z'` | Select current column and all columns to the right |
425
482
  | `t` | Toggle row selections (invert) |
426
483
  | `T` | Clear all row/column selections and cell matches |
427
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
+
428
487
  #### Find & Replace
429
488
 
430
489
  | Key | Action |
@@ -506,7 +565,7 @@ Useful examples from current bindings:
506
565
 
507
566
  These actions are the fastest way to get out of trouble after a mistaken edit, delete, sort, filter, or other table change.
508
567
 
509
- - `U`: Undo the last action and restore the previous state.
568
+ - `u` / `U`: Undo the last action and restore the previous state.
510
569
  - `R`: Redo the last undone action.
511
570
  - `gU`: Reset the table to its original loaded state if you want to start over.
512
571
 
@@ -686,13 +745,12 @@ The application provides multiple ways to select rows (for filtering or collecti
686
745
  - `g,` - Select rows with cell matches or those matching cursor value in all columns
687
746
  - `|` - Select rows where expression matches in the current column
688
747
  - `g|` - Select rows where expression matches in all columns
689
- - `\` - Unselect currently selected rows where expression matches in the current column
690
- - `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
691
750
  - `s` - Select/deselect current row
692
751
  - `gs` - Select current row and all rows above
693
752
  - `zs` - Select current row and all rows below
694
- - `u` - Unselect the current row
695
- - `gu` - Unselect all rows
753
+ - `gu` - Deselect all rows
696
754
  - `'` (apostrophe) - Select/deselect current column
697
755
  - `g'` - Select current column and all columns to the left
698
756
  - `z'` - Select current column and all columns to the right
@@ -795,7 +853,7 @@ Both actions work on a subset of the original dataframe, but they serve differen
795
853
 
796
854
  **Collect** (`"`):
797
855
 
798
- - Creates a separate tab containing only the chosen rows/columns
856
+ - Creates a separate tab containing only the chosen rows and/or columns
799
857
  - The collected tab is independent from the source dataframe
800
858
  - Edits in the collected tab do not modify the original table
801
859
 
@@ -820,15 +878,16 @@ Editing covers cell updates, structural table changes, and quick cleanup.
820
878
 
821
879
  - `e` or **Double-click**: Edit the current cell with type-aware validation.
822
880
  - `^` or **Double-click** column header: Rename the current column.
823
- - `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.
824
882
  - `gd`: Delete the current row and all rows above it.
825
883
  - `zd`: Delete the current row and all rows below it.
826
- - `*`: Delete selected columns, or the current column if nothing is selected.
884
+ - `*`: Delete selected columns, or the current column if none is selected.
827
885
  - `g*`: Delete the current column and all columns to its left.
828
886
  - `z*`: Delete the current column and all columns to its right.
829
887
  - `a`: Add an empty column after the current column.
830
888
  - `A`: Add a column after the current column using a value or expression such as `$age * 2`.
831
- - `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
832
891
  - `D`: Duplicate the current row.
833
892
  - `zD`: Duplicate the current column using a `_copy` suffix.
834
893
  - `zU`: Remove duplicate rows while keeping the first occurrence, based on visible-column values.
@@ -860,7 +919,7 @@ Editing covers cell updates, structural table changes, and quick cleanup.
860
919
  **Pin Column**: `!`
861
920
 
862
921
  - Moves the current column to the leftmost unfrozen position and freezes it
863
- - If columns are already frozen, appends to the frozen set (increments `fixed_columns`)
922
+ - If columns are already frozen, appends to the frozen set
864
923
 
865
924
  ### 16. Save File
866
925
 
@@ -945,6 +1004,13 @@ Complex values, filters, and advanced operations can be specified via Polars exp
945
1004
  - `$email.str.ends_with("@company.com")` - Email ends with domain
946
1005
  - `$code.str.starts_with("ABC")` - Code starts with "ABC"
947
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)
948
1014
 
949
1015
  **Number Operations:**
950
1016
 
@@ -952,6 +1018,18 @@ Complex values, filters, and advanced operations can be specified via Polars exp
952
1018
  - `($salary + $bonus) > 150000` - Total compensation over 150,000
953
1019
  - `$percentage >= 50` - Percentage at least 50%
954
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
+
955
1033
  **Null Handling:**
956
1034
 
957
1035
  - `$column.is_null()` - Find null values
@@ -1043,6 +1121,26 @@ Use the built-in Python console for quick interactive transformations without le
1043
1121
 
1044
1122
  ![Python Console](https://raw.githubusercontent.com/need47/dataframe-textual/refs/heads/main/screenshots/python-console.png)
1045
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
+
1046
1144
  ## Handling Loading Errors
1047
1145
 
1048
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.
@@ -1107,11 +1205,12 @@ dv partially_broken.csv -E
1107
1205
  - **textual**: Terminal UI framework
1108
1206
  - **fastexcel**: Read Excel files
1109
1207
  - **xlsxwriter**: Write Excel files
1208
+ - **plotext**: Render interactive terminal plots (optional)
1110
1209
  - **vortex-data**: Read/Write Vortex files (optional)
1111
1210
 
1112
1211
  ## Requirements
1113
1212
 
1114
- - Python 3.11+
1213
+ - Python 3.13+
1115
1214
  - POSIX-compatible terminal (macOS, Linux, WSL)
1116
1215
  - Terminal supporting ANSI escape sequences and mouse events
1117
1216
 
@@ -1,46 +1,6 @@
1
- Metadata-Version: 2.5
2
- Name: dataframe-textual
3
- Version: 3.3.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>=1.41.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
@@ -354,29 +315,31 @@ Useful examples from current bindings:
354
315
 
355
316
  #### Undo/Redo/Reset
356
317
 
357
- | Key | Action |
358
- | ---- | ----------------------- |
318
+ | Key | Action |
319
+ | --------- | ----------------------- |
359
320
  | `u` / `U` | Undo last action |
360
321
  | `R` | Redo last undone action |
361
- | `gU` | Reset to initial state |
322
+ | `gU` | Reset to initial state |
362
323
 
363
324
  #### Navigation
364
325
 
365
- | Key | Action |
366
- | ------------------------ | ----------------------------------- |
367
- | `gg` | Go to first row |
368
- | `G` | Go to last row |
369
- | `Ctrl+G` | Go to specific row |
370
- | `←` / `↓` / `↑` / `→` | Move left/down/up/right |
371
- | `h` / `j` / `k` / `l` | Move left/down/up/right (Vim-style) |
372
- | `gh` / `g←` | Scroll to leftmost column |
373
- | `gj` / `g↓` | Scroll to last row |
374
- | `gk` / `g↑` | Scroll to first row |
375
- | `gl` / `g→` | Scroll to rightmost column |
376
- | `Home` / `End` | Go to first/last column |
377
- | `Ctrl+Home` / `Ctrl+End` | Go to page top/bottom |
378
- | `PageUp` / `Ctrl+B` | Page backward |
379
- | `PageDown` / `Ctrl+F` | Page forward |
326
+ | Key | Action |
327
+ | ------------------------------------------------- | ----------------------------------- |
328
+ | `gg` | Go to first row |
329
+ | `G` | Go to last row |
330
+ | `Ctrl+G` | Go to specific row |
331
+ | `←` / `↓` / `↑` / `→` | Move left/down/up/right |
332
+ | `h` / `j` / `k` / `l` | Move left/down/up/right (Vim-style) |
333
+ | `gh` / `g←` | Scroll to leftmost column |
334
+ | `gj` / `g↓` | Scroll to last row |
335
+ | `gk` / `g↑` | Scroll to first row |
336
+ | `gl` / `g→` | Scroll to rightmost column |
337
+ | `Home` / `End` | Go to first/last column |
338
+ | `Ctrl+Home` / `Ctrl+End` | Go to page top/bottom |
339
+ | `PageUp` / `Ctrl+B` | Page backward |
340
+ | `PageDown` / `Ctrl+F` | Page forward |
341
+ | `MouseScrollUp` / `MouseScrollDown` | Scroll vertically |
342
+ | `Ctrl + MouseScrollUp` / `Ctrl + MouseScrollDown` | Scroll horizontally |
380
343
 
381
344
  #### Display
382
345
 
@@ -406,6 +369,20 @@ Useful examples from current bindings:
406
369
  | `g^` | Set current row as the new header row |
407
370
  | `Shift+Tab` | Cycle cursor type (cell -> row -> column) |
408
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
+
409
386
  #### Editing
410
387
 
411
388
  | Key | Action |
@@ -415,9 +392,9 @@ Useful examples from current bindings:
415
392
  | `Shift+Delete` | Clear current column (set matching cells to NULL) |
416
393
  | `e` | Edit current cell (respects data type) |
417
394
  | `E` | Edit entire column with value/expression |
418
- | `a` | Add empty column after current |
419
- | `A` | Add column with name and value/expression |
420
- | `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 |
421
398
  | `za` | Add a link column from URL template |
422
399
  | `^` | Rename current column |
423
400
  | `*` | Delete selected columns or current column |
@@ -451,20 +428,22 @@ Useful examples from current bindings:
451
428
  | `g,` | Select rows with cell matches or those matching cursor value in all columns |
452
429
  | `\|` (pipe) | Select rows where expression matches in current column |
453
430
  | `g\|` | Select rows where expression matches in all columns |
454
- | `\` | Unselect selected rows where expression matches in current column |
455
- | `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 |
456
433
  | `{` | Go to previous selected row |
457
434
  | `}` | Go to next selected row |
458
435
  | `s` | Select/deselect current row |
459
436
  | `gs` | Select current row and all rows above |
460
437
  | `zs` | Select current row and all rows below |
461
- | `gu` | Unselect all rows |
438
+ | `gu` | Deselect all rows |
462
439
  | `'` (apostrophe) | Select/deselect current column |
463
440
  | `g'` | Select current column and all columns to the left |
464
441
  | `z'` | Select current column and all columns to the right |
465
442
  | `t` | Toggle row selections (invert) |
466
443
  | `T` | Clear all row/column selections and cell matches |
467
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
+
468
447
  #### Find & Replace
469
448
 
470
449
  | Key | Action |
@@ -546,7 +525,7 @@ Useful examples from current bindings:
546
525
 
547
526
  These actions are the fastest way to get out of trouble after a mistaken edit, delete, sort, filter, or other table change.
548
527
 
549
- - `U`: Undo the last action and restore the previous state.
528
+ - `u` / `U`: Undo the last action and restore the previous state.
550
529
  - `R`: Redo the last undone action.
551
530
  - `gU`: Reset the table to its original loaded state if you want to start over.
552
531
 
@@ -726,13 +705,12 @@ The application provides multiple ways to select rows (for filtering or collecti
726
705
  - `g,` - Select rows with cell matches or those matching cursor value in all columns
727
706
  - `|` - Select rows where expression matches in the current column
728
707
  - `g|` - Select rows where expression matches in all columns
729
- - `\` - Unselect currently selected rows where expression matches in the current column
730
- - `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
731
710
  - `s` - Select/deselect current row
732
711
  - `gs` - Select current row and all rows above
733
712
  - `zs` - Select current row and all rows below
734
- - `u` - Unselect the current row
735
- - `gu` - Unselect all rows
713
+ - `gu` - Deselect all rows
736
714
  - `'` (apostrophe) - Select/deselect current column
737
715
  - `g'` - Select current column and all columns to the left
738
716
  - `z'` - Select current column and all columns to the right
@@ -835,7 +813,7 @@ Both actions work on a subset of the original dataframe, but they serve differen
835
813
 
836
814
  **Collect** (`"`):
837
815
 
838
- - Creates a separate tab containing only the chosen rows/columns
816
+ - Creates a separate tab containing only the chosen rows and/or columns
839
817
  - The collected tab is independent from the source dataframe
840
818
  - Edits in the collected tab do not modify the original table
841
819
 
@@ -860,15 +838,16 @@ Editing covers cell updates, structural table changes, and quick cleanup.
860
838
 
861
839
  - `e` or **Double-click**: Edit the current cell with type-aware validation.
862
840
  - `^` or **Double-click** column header: Rename the current column.
863
- - `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.
864
842
  - `gd`: Delete the current row and all rows above it.
865
843
  - `zd`: Delete the current row and all rows below it.
866
- - `*`: Delete selected columns, or the current column if nothing is selected.
844
+ - `*`: Delete selected columns, or the current column if none is selected.
867
845
  - `g*`: Delete the current column and all columns to its left.
868
846
  - `z*`: Delete the current column and all columns to its right.
869
847
  - `a`: Add an empty column after the current column.
870
848
  - `A`: Add a column after the current column using a value or expression such as `$age * 2`.
871
- - `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
872
851
  - `D`: Duplicate the current row.
873
852
  - `zD`: Duplicate the current column using a `_copy` suffix.
874
853
  - `zU`: Remove duplicate rows while keeping the first occurrence, based on visible-column values.
@@ -900,7 +879,7 @@ Editing covers cell updates, structural table changes, and quick cleanup.
900
879
  **Pin Column**: `!`
901
880
 
902
881
  - Moves the current column to the leftmost unfrozen position and freezes it
903
- - If columns are already frozen, appends to the frozen set (increments `fixed_columns`)
882
+ - If columns are already frozen, appends to the frozen set
904
883
 
905
884
  ### 16. Save File
906
885
 
@@ -985,6 +964,13 @@ Complex values, filters, and advanced operations can be specified via Polars exp
985
964
  - `$email.str.ends_with("@company.com")` - Email ends with domain
986
965
  - `$code.str.starts_with("ABC")` - Code starts with "ABC"
987
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)
988
974
 
989
975
  **Number Operations:**
990
976
 
@@ -992,6 +978,18 @@ Complex values, filters, and advanced operations can be specified via Polars exp
992
978
  - `($salary + $bonus) > 150000` - Total compensation over 150,000
993
979
  - `$percentage >= 50` - Percentage at least 50%
994
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
+
995
993
  **Null Handling:**
996
994
 
997
995
  - `$column.is_null()` - Find null values
@@ -1083,6 +1081,26 @@ Use the built-in Python console for quick interactive transformations without le
1083
1081
 
1084
1082
  ![Python Console](https://raw.githubusercontent.com/need47/dataframe-textual/refs/heads/main/screenshots/python-console.png)
1085
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
+
1086
1104
  ## Handling Loading Errors
1087
1105
 
1088
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.
@@ -1147,11 +1165,12 @@ dv partially_broken.csv -E
1147
1165
  - **textual**: Terminal UI framework
1148
1166
  - **fastexcel**: Read Excel files
1149
1167
  - **xlsxwriter**: Write Excel files
1168
+ - **plotext**: Render interactive terminal plots (optional)
1150
1169
  - **vortex-data**: Read/Write Vortex files (optional)
1151
1170
 
1152
1171
  ## Requirements
1153
1172
 
1154
- - Python 3.11+
1173
+ - Python 3.13+
1155
1174
  - POSIX-compatible terminal (macOS, Linux, WSL)
1156
1175
  - Terminal supporting ANSI escape sequences and mouse events
1157
1176