dataframe-textual 1.2.0__tar.gz → 1.5.0__tar.gz

{dataframe_textual-1.2.0 → dataframe_textual-1.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dataframe-textual
-Version: 1.2.0
+Version: 1.5.0
 Summary: Interactive terminal viewer/editor for tabular data
 Project-URL: Homepage, https://github.com/need47/dataframe-textual
 Project-URL: Repository, https://github.com/need47/dataframe-textual.git
@@ -29,7 +29,7 @@ Classifier: Topic :: Utilities
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Requires-Dist: polars>=1.34.0
-Requires-Dist: textual>=6.5.0
+Requires-Dist: textual[syntax]>=6.5.0
 Provides-Extra: dev
 Requires-Dist: textual-dev>=1.8.0; extra == 'dev'
 Provides-Extra: excel
@@ -48,7 +48,21 @@ A powerful, interactive terminal-based viewer/editor for CSV/TSV/Excel/Parquet/J
 ### Data Viewing
 - 🚀 **Fast Loading** - Powered by Polars for efficient data handling
 - 🎨 **Rich Terminal UI** - Beautiful, color-coded columns with various data types (e.g., integer, float, string)
-- ⌨️ **Comprehensive Keyboard Navigation** - Intuitive controls for browsing, editing, and manipulating data
+- ⌨️ **Comprehensive Keyboard Navigation** - Intuitive controls
+# Skip first 5 lines (comments, metadata)
+dv -l 5 data_with_metadata.csv
+
+# Skip 1 row after header (e.g., units row)
+dv -a 1 data_with_units.csv
+
+# Complex CSV with comments and units row
+dv -l 3 -a 1 -I messy_scientific_data.csv
+
+# Combine all options: skip lines, skip after header, no header, no inference, gzipped
+dv -l 2 -a 1 -H -I complex_data.csv.gz
+
+# Process compressed data from stdin with line skipping
+zcat compressed_data.csv.gz | dv -f csv -l 2editing, and manipulating data
 - 📊 **Flexible Input** - Read from files and/or stdin (pipes/redirects)
 - 🔄 **Smart Pagination** - Lazy load rows on demand for handling large datasets
 
@@ -64,6 +78,7 @@ A powerful, interactive terminal-based viewer/editor for CSV/TSV/Excel/Parquet/J
 - 🔄 **Tab Management** - Seamlessly switch between open files with keyboard shortcuts
 - 📌 **Freeze Rows/Columns** - Keep important rows and columns visible while scrolling
 - 🎯 **Cursor Type Cycling** - Switch between cell, row, and column selection modes
+- 🔗 **Link Column Creation** - Generate clickable URLs using template expressions with placeholder support
 
 ## Installation
 
@@ -129,6 +144,13 @@ uv run python main.py pokemon.csv
 # Read from stdin (auto-detects format; defaults to TSV if not recognized)
 cat data.tsv | dv
 dv < data.tsv
+
+# Gzipped files are supported
+dv data.csv.gz
+dv large_dataset.tsv.gz
+
+# Specify format for gzipped stdin
+zcat data.csv.gz | dv -f csv
 ```
 
 ### Multi-File Usage - Multiple Tabs
@@ -142,6 +164,9 @@ dv file.xlsx
 
 # Mix files and stdin (read from stdin, then open file)
 dv data1.tsv < data2.tsv
+
+# Mix regular and gzipped files
+dv data1.csv data2.csv.gz data3.tsv.gz
 ```
 
 When multiple files are opened:
@@ -151,6 +176,87 @@ When multiple files are opened:
 - Close the current tab with `Ctrl+W`
 - Each file maintains its own state (edits, sort order, selections, history, etc.)
 
+## Command Line Options
+
+```
+usage: dv [-h] [-f {csv,excel,tsv,parquet,json,ndjson}] [-H] [-I] [-E] [-c COMMENT_PREFIX] [-q QUOTE_CHAR] [-l SKIP_LINES] [-a SKIP_ROWS_AFTER_HEADER] [-u NULL [NULL ...]] [files ...]
+
+Interactive terminal based viewer/editor for tabular data (e.g., CSV/Excel).
+
+positional arguments:
+  files                 Files to view (or read from stdin)
+
+options:
+  -h, --help            show this help message and exit
+  -f, --format {csv,excel,tsv,parquet,json,ndjson}
+                        Specify the format of the input files
+  -H, --no-header       Specify that input files have no header row
+  -I, --no-inferrence   Do not infer data types when reading CSV/TSV
+  -E, --ignore-errors   Ignore errors when reading CSV/TSV
+  -c, --comment-prefix COMMENT_PREFIX
+                        Comment lines are skipped when reading CSV/TSV (default: skip none)
+  -q, --quote-char QUOTE_CHAR
+                        Quote character for reading CSV/TSV (default: "; use None to disable)
+  -l, --skip-lines SKIP_LINES
+                        Skip lines when reading CSV/TSV (default: 0)
+  -a, --skip-rows-after-header SKIP_ROWS_AFTER_HEADER
+                        Skip rows after header when reading CSV/TSV (default: 0)
+  -u, --null NULL [NULL ...]
+                        Values to interpret as null values when reading CSV/TSV
+```
+
+### CLI Examples
+
+```bash
+# View CSV file without header row
+dv -H data_no_header.csv
+
+# Disable type inference for faster loading
+dv -I large_data.csv
+
+# Ignore parsing errors in malformed CSV
+dv -E data_with_errors.csv
+
+# Skip first 3 lines of file (e.g., comments, metadata)
+dv -l 3 data_with_comments.csv
+
+# Skip 1 row after header (e.g., units row)
+dv -a 1 data_with_units.csv
+
+# Treat specific values as null/missing (e.g., 'NA', 'N/A', '-')
+dv -u NA N/A - data.csv
+
+# Multiple null values with different formats
+dv -u NULL NA "" "Not Available" messy_data.csv
+
+# Disable quote character processing for TSV with embedded quotes
+dv -q "" data.tsv
+
+# Use different quote character (e.g., single quote for CSV)
+dv -q "'" data.csv
+
+# Complex CSV with comments and units row
+dv -l 3 -a 1 -I messy_scientific_data.csv
+
+# Combine all options: skip lines, skip after header, no header, no inference, gzipped
+dv -l 2 -a 1 -H -I complex_data.csv.gz
+
+# Process compressed data from stdin with line skipping
+zcat compressed_data.csv.gz | dv -f csv -l 2
+
+# CSV with custom null values and no header
+dv -H -u NA "N/A" "-" raw_data.csv
+
+# Skip lines, specify null values, and disable type inference
+dv -l 5 -u NA "" data_with_metadata.csv
+
+# TSV file with problematic quotes in data fields
+dv -q None data.tsv
+
+# CSV with comment lines and custom null values
+dv -c "#" -u NA "N/A" commented_data.csv
+```
+
 ## Keyboard Shortcuts
 
 ### App-Level Controls
@@ -161,7 +267,7 @@ When multiple files are opened:
 |-----|--------|
 | `Ctrl+O` | Open file in a new tab |
 | `Ctrl+W` | Close current tab |
-| `Ctrl+Shift+S` | Save all open tabs to Excel file |
+| `Ctrl+A` | Save all open tabs to Excel file |
 | `>` or `b` | Move to next tab |
 | `<` | Move to previous tab |
 | `B` | Toggle tab bar visibility |
@@ -171,7 +277,7 @@ When multiple files are opened:
 
 | Key | Action |
 |-----|--------|
-| `Ctrl+H` | Toggle help panel |
+| `F1` | Toggle help panel |
 | `k` | Cycle through themes |
 
 ---
@@ -189,6 +295,8 @@ When multiple files are opened:
 | `Home` / `End` | Jump to first/last column in current row |
 | `Ctrl + Home` / `Ctrl + End` | Jump to top/bottom in current page |
 | `PageDown` / `PageUp` | Scroll down/up one page |
+| `Ctrl+F` | Page down |
+| `Ctrl+B` | Page up |
 
 #### Viewing & Display
 
@@ -200,6 +308,7 @@ When multiple files are opened:
 | `S` | Show statistics for entire dataframe |
 | `K` | Cycle cursor type: cell → row → column → cell |
 | `~` | Toggle row labels |
+| `_` (underscore) | Expand column to full width |
 
 #### Data Editing
 
@@ -211,9 +320,8 @@ When multiple files are opened:
 | `E` | Edit entire column with expression |
 | `a` | Add empty column after current |
 | `A` | Add column with name and value/expression |
+| `@` | Add a link column from template expression |
 | `-` (minus) | Delete current column |
-| `_` (underscore) | Delete current column and all columns after |
-| `Ctrl+-` | Delete current column and all columns before |
 | `x` | Delete current row |
 | `X` | Delete current row and all rows below |
 | `Ctrl+X` | Delete current row and all rows above |
@@ -241,12 +349,19 @@ When multiple files are opened:
 | `v` | View only rows by selected rows and/or matches or cursor value |
 | `V` | View only rows by expression |
 
+#### SQL Interface
+
+| Key | Action |
+|-----|--------|
+| `l` | Simple SQL interface (select columns & WHERE clause) |
+| `L` | Advanced SQL interface (full SQL queries) |
+
 #### Find & Replace
 
 | Key | Action |
 |-----|--------|
-| `f` | Find across all columns with cursor value |
-| `Ctrl+F` | Find across all columns with expression |
+| `;` | Find across all columns with cursor value |
+| `:` | Find across all columns with expression |
 | `r` | Find and replace in current column (interactive or replace all) |
 | `R` | Find and replace across all columns (interactive or replace all) |
 
@@ -274,7 +389,6 @@ When multiple files are opened:
 | `%` | Cast current column to float (Float64) |
 | `!` | Cast current column to boolean |
 | `$` | Cast current column to string |
-| `@` | Make URLs in current column clickable with Ctrl/Cmd + click|
 
 #### Data Management
 
@@ -322,8 +436,8 @@ The application provides multiple search modes for different use cases:
 **Find Operations** - Find by value/expression:
 - **`/` - Column Find**: Find cursor value within current column
 - **`?` - Column Expression Find**: Open dialog to search current column with expression
-- **`f` - Global Find**: Find cursor value across all columns
-- **`Ctrl+f` - Global Expression Find**: Open dialog to search all columns with expression
+- **`;` - Global Find**: Find cursor value across all columns
+- **`:` - Global Expression Find**: Open dialog to search all columns with expression
 
 **Selection & Filtering**:
 - **`'` - Toggle Row Selection**: Select/deselect current row (marks it for filtering)
@@ -696,12 +810,38 @@ Press `K` to cycle through selection modes:
 2. **Row mode**: Highlight entire row
 3. **Column mode**: Highlight entire column
 
-### 18. URL Handling
+### 18. SQL Interface
+
+The SQL interface provides two modes for querying your dataframe:
+
+#### Simple SQL Interface (`l`)
+Select specific columns and apply WHERE conditions without writing full SQL:
+- Choose which columns to include in results
+- Specify WHERE clause for filtering
+- Ideal for quick filtering and column selection
 
-Press `@` to make URLs in the current column clickable:
-- **Ctrl/Cmd + click** on URLs to open them in your default browser
-- **Scans** all cells in the current column for URLs starting with `http://` or `https://`
-- **Applies** link styling to make them clickable and dataframe remains unchanged
+#### Advanced SQL Interface (`L`)
+Execute complete SQL queries for advanced data manipulation:
+- Write full SQL queries with standard [SQL syntax](https://docs.pola.rs/api/python/stable/reference/sql/index.html)
+- Support for JOINs, GROUP BY, aggregations, and more
+- Access to all SQL capabilities for complex transformations
+- Always use `self` as the table name
+
+**Examples:**
+```sql
+-- Filter and select specific rows and/or columns
+SELECT name, age FROM self WHERE age > 30
+
+-- Aggregate with GROUP BY
+SELECT department, COUNT(*) as count, AVG(salary) as avg_salary
+FROM self
+GROUP BY department
+
+-- Complex filtering with multiple conditions
+SELECT *
+FROM self
+WHERE (age > 25 AND salary > 50000) OR department = 'Management'
+```
 
 ### 19. Clipboard Operations
 
@@ -712,6 +852,73 @@ Press `Ctrl+C` to copy:
 - Press `Ctrl+C` to copy column values
 - Press `Ctrl+R` to copy row values (delimited by tab)
 
+### 20. Link Column Creation
+
+Press `@` to create a new column containing dynamically generated URLs using template expressions.
+
+**Template Placeholders:**
+
+The link template supports multiple placeholder types for maximum flexibility:
+
+- **`$_`** - Current column (the column where cursor was when `@` was pressed)
+  - Example: `https://example.com/search/$_` - Uses values from the current column
+  - Useful for quick links based on the focused column
+
+- **`$1`, `$2`, `$3`, etc.** - Column by 1-based position index
+  - Example: `https://example.com/product/$1/details/$2` - Uses 1st and 2nd columns
+  - Useful for structured templates spanning multiple columns
+  - Index corresponds to column display order (left-to-right)
+
+- **`$name`** - Column by name (use actual column names)
+  - Example: `https://pubchem.ncbi.nlm.nih.gov/search?q=$product_id` - Uses `product_id` column
+  - Example: `https://example.com/$region/$city/data` - Uses `region` and `city` columns
+  - Useful for readable, self-documenting templates
+
+**Features:**
+
+- **Vectorized Expression**: All rows processed efficiently using Polars' vectorized operations
+- **Type Casting**: Column values automatically converted to strings for URL construction
+- **Multiple Placeholders**: Mix and match placeholders in a single template
+- **URL Prefix**: Automatically prepends `https://` if URL doesn't start with `http://` or `https://`
+- **PubChem Support**: Special shorthand - replace `PC` with full PubChem URL
+
+**Examples:**
+
+```
+Template: https://example.com/$_
+Current column: product_id
+Result: https://example.com/ABC123 (for each row's product_id value)
+
+Template: https://database.org/view?id=$1&lang=$2
+Column 1: item_code, Column 2: language
+Result: https://database.org/view?id=X001&lang=en
+
+Template: https://example.com/$username/profile
+Column: username (must exist in dataframe)
+Result: https://example.com/john_doe/profile
+
+Template: https://example.com/$region/$city
+Columns: region, city
+Result: https://example.com/north/seattle
+
+Template: PC/compound/$1
+Column 1: pubchem_cid
+Result: https://pubchem.ncbi.nlm.nih.gov/compound/12345
+```
+
+**Error Handling:**
+
+- **Invalid column index**: `$5` when only 3 columns exist → Error message showing valid range
+- **Non-existent column name**: `$invalid_column` → Error message with available columns
+- **No placeholders**: Template treated as constant → All rows get identical URL
+
+**Tips:**
+
+- Use descriptive column names for `$name` placeholders to make templates self-documenting
+- Test with a small dataset first to verify template correctness
+- Use full undo (`u`) if template produces unexpected URLs
+- For complex multi-column URLs, use column names (`$name`) for clarity over positions (`$1`)
+
 ## Examples
 
 ### Single File Examples
@@ -722,6 +929,30 @@ dv pokemon.csv
 
 # Chain with other command and specify input file format
 cut -d',' -f1,2,3 pokemon.csv | dv -f csv
+
+# Work with gzipped files
+dv large_dataset.csv.gz
+
+# CSV file without header row
+dv -H raw_data.csv
+
+# Skip type inference for faster loading
+dv -I huge_file.csv
+
+# Skip first 5 lines (comments, metadata)
+dv -L 5 data_with_metadata.csv
+
+# Skip 1 row after header (units row)
+dv -K 1 data_with_units.csv
+
+# Complex CSV with comments and units row
+dv -L 3 -K 1 -I messy_scientific_data.csv
+
+# Combine all options: skip lines, skip after header, no header, no inference, gzipped
+dv -L 2 -K 1 -H -I complex_data.csv.gz
+
+# Process compressed data from stdin with line skipping
+zcat compressed_data.csv.gz | dv -f csv -L 2
 ```
 
 ### Multi-File/Tab Examples
@@ -730,8 +961,8 @@ cut -d',' -f1,2,3 pokemon.csv | dv -f csv
 # Open multiple sheets as tabs in a single Excel
 dv sales.xlsx
 
-# Open multiple files as tabs
-dv pokemon.csv titanic.csv
+# Open multiple files as tabs (including gzipped)
+dv pokemon.csv titanic.csv large_data.csv.gz
 
 # Start with one file, then open others using Ctrl+O
 dv initial_data.csv