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.
- dataframe_textual-3.4.0/README.md → dataframe_textual-3.5.0/PKG-INFO +117 -20
- dataframe_textual-3.4.0/PKG-INFO → dataframe_textual-3.5.0/README.md +77 -60
- {dataframe_textual-3.4.0 → dataframe_textual-3.5.0}/pyproject.toml +7 -7
- {dataframe_textual-3.4.0 → dataframe_textual-3.5.0}/src/dataframe_textual/__init__.py +0 -1
- {dataframe_textual-3.4.0 → dataframe_textual-3.5.0}/src/dataframe_textual/__main__.py +12 -14
- {dataframe_textual-3.4.0 → dataframe_textual-3.5.0}/src/dataframe_textual/commands.py +43 -17
- {dataframe_textual-3.4.0 → dataframe_textual-3.5.0}/src/dataframe_textual/common.py +19 -11
- {dataframe_textual-3.4.0 → dataframe_textual-3.5.0}/src/dataframe_textual/console_panel.py +2 -1
- {dataframe_textual-3.4.0 → dataframe_textual-3.5.0}/src/dataframe_textual/data_frame_table.py +213 -48
- {dataframe_textual-3.4.0 → dataframe_textual-3.5.0}/src/dataframe_textual/data_frame_viewer.py +12 -7
- {dataframe_textual-3.4.0 → dataframe_textual-3.5.0}/src/dataframe_textual/file_picker_screen.py +3 -3
- {dataframe_textual-3.4.0 → dataframe_textual-3.5.0}/src/dataframe_textual/loading_screen.py +4 -3
- dataframe_textual-3.5.0/src/dataframe_textual/plot_screen.py +581 -0
- {dataframe_textual-3.4.0 → dataframe_textual-3.5.0}/src/dataframe_textual/run_command_screen.py +2 -1
- {dataframe_textual-3.4.0 → dataframe_textual-3.5.0}/src/dataframe_textual/table_screen.py +50 -92
- {dataframe_textual-3.4.0 → dataframe_textual-3.5.0}/src/dataframe_textual/text_screen.py +2 -1
- {dataframe_textual-3.4.0 → dataframe_textual-3.5.0}/src/dataframe_textual/theme_screen.py +4 -2
- {dataframe_textual-3.4.0 → dataframe_textual-3.5.0}/src/dataframe_textual/yes_no_screen.py +10 -10
- {dataframe_textual-3.4.0 → dataframe_textual-3.5.0}/uv.lock +67 -290
- dataframe_textual-3.4.0/keys.log +0 -1
- {dataframe_textual-3.4.0 → dataframe_textual-3.5.0}/.gitignore +0 -0
- {dataframe_textual-3.4.0 → dataframe_textual-3.5.0}/LICENSE +0 -0
- {dataframe_textual-3.4.0 → dataframe_textual-3.5.0}/main.py +0 -0
- {dataframe_textual-3.4.0 → dataframe_textual-3.5.0}/src/dataframe_textual/help_panel.py +0 -0
- {dataframe_textual-3.4.0 → dataframe_textual-3.5.0}/src/dataframe_textual/keybindings.py +0 -0
- {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/)/[
|
|
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
|

|
|
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
|
-
| `\` |
|
|
417
|
-
| `g\` |
|
|
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` |
|
|
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
|
-
- `\` -
|
|
692
|
-
- `g\` -
|
|
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
|
-
- `
|
|
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
|
|
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
|
|
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`:
|
|
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
|
|
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
|

|
|
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.
|
|
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/)/[
|
|
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
|

|
|
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
|
-
| `\` |
|
|
457
|
-
| `g\` |
|
|
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` |
|
|
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
|
-
- `\` -
|
|
732
|
-
- `g\` -
|
|
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
|
-
- `
|
|
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
|
|
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
|
|
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`:
|
|
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
|
|
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
|

|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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
|
-
|
|
53
|
-
"
|
|
51
|
+
extra = [
|
|
52
|
+
"plotext>=6.1.0",
|
|
53
|
+
"vortex-data>=0.93.0",
|
|
54
54
|
]
|
|
55
55
|
|
|
56
56
|
[[tool.uv.index]]
|
|
@@ -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
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
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
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
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__":
|