dataframe-textual 0.3.0__py3-none-any.whl → 1.0.0__py3-none-any.whl

dataframe_textual/__main__.py

@@ -6,41 +6,58 @@ from pathlib import Path
 
 from .data_frame_viewer import DataFrameViewer
 
+SUPPORTED_FORMATS = ["csv", "excel", "tsv", "parquet", "json", "ndjson"]
 
-def main():
-    """Run the DataFrame Viewer application."""
+
+def main() -> None:
+    """Run the DataFrame Viewer application.
+
+    Parses command-line arguments to determine input files or stdin, validates
+    file existence, and launches the interactive DataFrame Viewer application.
+
+    Returns:
+        None
+
+    Raises:
+        SystemExit: If invalid arguments are provided or required files are missing.
+    """
     parser = argparse.ArgumentParser(
-        description="Interactive CSV/Excel viewer for the terminal (Textual version)",
+        description="Interactive terminal based viewer/editor for tabular data (e.g., CSV/Excel).",
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog="Examples:\n"
-        "  dataframe-viewer data.csv\n"
-        "  dataframe-viewer file1.csv file2.csv file3.csv\n"
-        "  dataframe-viewer data.xlsx  (opens all sheets in tabs)\n"
-        "  cat data.csv | dataframe-viewer\n",
+        "  dataframe-textual data.csv\n"
+        "  dataframe-textual file1.csv file2.csv file3.csv\n"
+        "  dataframe-textual data.xlsx  (opens all sheets in tabs)\n"
+        "  cat data.csv | dataframe-textual --format csv\n",
     )
+    parser.add_argument("files", nargs="*", help="Files to view (or read from stdin)")
     parser.add_argument(
-        "files", nargs="*", help="CSV or Excel files to view (or read from stdin)"
+        "-f",
+        "--format",
+        choices=SUPPORTED_FORMATS,
+        help="Specify the format of the input files (csv, excel, tsv etc.)",
     )
+    parser.add_argument("-H", "--no-header", action="store_true", help="Specify that input files have no header row")
 
     args = parser.parse_args()
     filenames = []
 
     # Check if reading from stdin (pipe or redirect)
     if not sys.stdin.isatty():
-        filenames = ["-"]
-    elif args.files:
+        filenames.append("-")
+    if args.files:
         # Validate all files exist
         for filename in args.files:
             if not Path(filename).exists():
                 print(f"File not found: {filename}")
                 sys.exit(1)
-        filenames = args.files
+        filenames.extend(args.files)
 
     if not filenames:
         parser.print_help()
         sys.exit(1)
 
-    app = DataFrameViewer(*filenames)
+    app = DataFrameViewer(*filenames, file_format=args.format, has_header=not args.no_header)
     app.run()
 
 

dataframe_textual/common.py

@@ -7,6 +7,10 @@ from typing import Any
 import polars as pl
 from rich.text import Text
 
+# Special string to represent null value
+NULL = "NULL"
+NULL_DISPLAY = "-"
+
 # Boolean string mappings
 BOOLS = {
     "true": True,
@@ -21,34 +25,45 @@ BOOLS = {
     "0": False,
 }
 
-# itype is used by Input widget for input validation
-# fmt: off
-STYLES = {
-    "Int64": {"style": "cyan", "justify": "right", "itype": "integer", "convert": int},
-    "Float64": {"style": "magenta", "justify": "right", "itype": "number", "convert": float},
-    "String": {"style": "green", "justify": "left", "itype": "text", "convert": str},
-    "Boolean": {"style": "blue", "justify": "center", "itype": "text", "convert": lambda x: BOOLS[x.lower()]},
-    "Date": {"style": "blue", "justify": "center", "itype": "text", "convert": str},
-    "Datetime": {"style": "blue", "justify": "center", "itype": "text", "convert": str},
-}
-# fmt: on
-
 
 @dataclass
-class DtypeConfig:
+class DtypeClass:
+    gtype: str  # generic, high-level type
     style: str
     justify: str
     itype: str
     convert: Any
 
-    def __init__(self, dtype: pl.DataType):
-        dc = STYLES.get(
-            str(dtype), {"style": "", "justify": "", "itype": "text", "convert": str}
-        )
-        self.style = dc["style"]
-        self.justify = dc["justify"]
-        self.itype = dc["itype"]
-        self.convert = dc["convert"]
+
+# itype is used by Input widget for input validation
+# fmt: off
+STYLES = {
+    # str
+    pl.String: DtypeClass(gtype="string", style="green", justify="left", itype="text", convert=str),
+    # int
+    pl.Int8: DtypeClass(gtype="integer", style="cyan", justify="right", itype="integer", convert=int),
+    pl.Int16: DtypeClass(gtype="integer", style="cyan", justify="right", itype="integer", convert=int),
+    pl.Int32: DtypeClass(gtype="integer", style="cyan", justify="right", itype="integer", convert=int),
+    pl.Int64: DtypeClass(gtype="integer", style="cyan", justify="right", itype="integer", convert=int),
+    pl.Int128: DtypeClass(gtype="integer", style="cyan", justify="right", itype="integer", convert=int),
+    pl.UInt8: DtypeClass(gtype="integer", style="cyan", justify="right", itype="integer", convert=int),
+    pl.UInt16: DtypeClass(gtype="integer", style="cyan", justify="right", itype="integer", convert=int),
+    pl.UInt32: DtypeClass(gtype="integer", style="cyan", justify="right", itype="integer", convert=int),
+    pl.UInt64: DtypeClass(gtype="integer", style="cyan", justify="right", itype="integer", convert=int),
+    # float
+    pl.Float32: DtypeClass(gtype="float", style="magenta", justify="right", itype="number", convert=float),
+    pl.Float64: DtypeClass(gtype="float", style="magenta", justify="right", itype="number", convert=float),
+    pl.Decimal: DtypeClass(gtype="float", style="magenta", justify="right", itype="number", convert=float),
+    # bool
+    pl.Boolean: DtypeClass(gtype="boolean", style="blue", justify="center", itype="text", convert=lambda x: BOOLS[x.lower()]),
+    # temporal
+    pl.Date: DtypeClass(gtype="temporal", style="yellow", justify="center", itype="text", convert=str),
+    pl.Datetime: DtypeClass(gtype="temporal", style="yellow", justify="center", itype="text", convert=str),
+    pl.Time: DtypeClass(gtype="temporal", style="yellow", justify="center", itype="text", convert=str),
+    # unknown
+    pl.Unknown: DtypeClass(gtype="unknown", style="", justify="", itype="text", convert=str),
+}
+# fmt: on
 
 
 # Subscript digits mapping for sort indicators
@@ -68,18 +83,47 @@ SUBSCRIPT_DIGITS = {
 # Cursor types ("none" removed)
 CURSOR_TYPES = ["row", "column", "cell"]
 
-# Pagination settings
-INITIAL_BATCH_SIZE = 100  # Load this many rows initially
-BATCH_SIZE = 50  # Load this many rows when scrolling
+# For row index column
+RIDX = "^_ridx_^"
+
 
+def DtypeConfig(dtype: pl.DataType) -> DtypeClass:
+    """Get the DtypeClass configuration for a given Polars data type.
 
-def _format_row(vals, dtypes, apply_justify=True) -> list[Text]:
+    Retrieves styling and formatting configuration based on the Polars data type,
+    including style (color), justification, and type conversion function.
+
+    Args:
+        dtype: A Polars data type to get configuration for.
+
+    Returns:
+        A DtypeClass containing style, justification, input type, and conversion function.
+    """
+    if dc := STYLES.get(dtype):
+        return dc
+    elif isinstance(dtype, pl.Datetime):
+        return STYLES[pl.Datetime]
+    elif isinstance(dtype, pl.Date):
+        return STYLES[pl.Date]
+    elif isinstance(dtype, pl.Time):
+        return STYLES[pl.Time]
+    else:
+        return STYLES[pl.Unknown]
+
+
+def format_row(vals, dtypes, apply_justify=True, thousand_separator=False) -> list[Text]:
     """Format a single row with proper styling and justification.
 
+    Converts raw row values to formatted Rich Text objects with appropriate
+    styling (colors), justification, and null value handling based on data types.
+
     Args:
         vals: The list of values in the row.
         dtypes: The list of data types corresponding to each value.
         apply_justify: Whether to apply justification styling. Defaults to True.
+
+    Returns:
+        A list of Rich Text objects with proper formatting applied.
     """
     formatted_row = []
 
@@ -88,9 +132,11 @@ def _format_row(vals, dtypes, apply_justify=True) -> list[Text]:
 
         # Format the value
         if val is None:
-            text_val = "-"
-        elif str(dtype).startswith("Float"):
-            text_val = f"{val:.4g}"
+            text_val = NULL_DISPLAY
+        elif dc.gtype == "integer" and thousand_separator:
+            text_val = f"{val:,}"
+        elif dc.gtype == "float" and thousand_separator:
+            text_val = f"{val:,}"
         else:
             text_val = str(val)
 
@@ -105,16 +151,42 @@ def _format_row(vals, dtypes, apply_justify=True) -> list[Text]:
     return formatted_row
 
 
-def _rindex(lst: list, value) -> int:
-    """Return the last index of value in a list. Return -1 if not found."""
+def rindex(lst: list, value) -> int:
+    """Return the last index of value in a list. Return -1 if not found.
+
+    Searches through the list in reverse order to find the last occurrence
+    of the given value.
+
+    Args:
+        lst: The list to search through.
+        value: The value to find.
+
+    Returns:
+        The index (0-based) of the last occurrence, or -1 if not found.
+    """
     for i, item in enumerate(reversed(lst)):
         if item == value:
             return len(lst) - 1 - i
     return -1
 
 
-def _next(lst: list[Any], current, offset=1) -> Any:
-    """Return the next item in the list after the current item, cycling if needed."""
+def get_next_item(lst: list[Any], current, offset=1) -> Any:
+    """Return the next item in the list after the current item, cycling if needed.
+
+    Finds the current item in the list and returns the item at position (current_index + offset),
+    wrapping around to the beginning if necessary.
+
+    Args:
+        lst: The list to cycle through.
+        current: The current item (must be in the list).
+        offset: The number of positions to advance. Defaults to 1.
+
+    Returns:
+        The next item in the list after advancing by the offset.
+
+    Raises:
+        ValueError: If the current item is not found in the list.
+    """
     if current not in lst:
         raise ValueError("Current item not in list")
     current_index = lst.index(current)
@@ -122,83 +194,127 @@ def _next(lst: list[Any], current, offset=1) -> Any:
     return lst[next_index]
 
 
-def parse_filter_expression(
-    expression: str, df: pl.DataFrame, current_col_idx: int
-) -> str:
-    """Parse and convert a filter expression to Polars syntax.
+def parse_polars_expression(expression: str, df: pl.DataFrame, current_col_idx: int) -> str:
+    """Parse and convert an expression to Polars syntax.
 
-    Supports:
+    Replaces column references with Polars col() expressions:
     - $_ - Current selected column
+    - $# - Row index (1-based, requires '^__ridx__^' column to be present)
     - $1, $2, etc. - Column by 1-based index
-    - $col_name - Column by name
-    - Comparison operators: ==, !=, <, >, <=, >=
-    - Logical operators: &&, ||
-    - String literals: 'text', "text"
-    - Numeric literals: integers and floats
+    - $col_name - Column by name (valid identifier starting with _ or letter)
 
     Examples:
     - "$_ > 50" -> "pl.col('current_col') > 50"
+    - "$# > 10" -> "pl.col('^__ridx__^') > 10"
     - "$1 > 50" -> "pl.col('col0') > 50"
     - "$name == 'Alex'" -> "pl.col('name') == 'Alex'"
-    - "$1 > 3 && $name == 'Alex'" -> "(pl.col('col0') > 3) & (pl.col('name') == 'Alex')"
     - "$age < $salary" -> "pl.col('age') < pl.col('salary')"
 
     Args:
-        expression: The filter expression as a string.
+        expression: The input expression as a string.
         df: The DataFrame to validate column references.
         current_col_idx: The index of the currently selected column (0-based). Used for $_ reference.
 
     Returns:
-        A Python expression string that can be eval'd with Polars symbols.
+        A Python expression string with $references replaced by pl.col() calls.
 
     Raises:
-        ValueError: If the expression contains invalid column references.
-        SyntaxError: If the expression has invalid syntax.
+        ValueError: If a column reference is invalid.
     """
-    # Tokenize the expression
-    # Pattern matches: $_, $index, $identifier, strings, operators, numbers, etc.
-    token_pattern = r'\$_|\$\d+|\$\w+|\'[^\']*\'|"[^"]*"|&&|\|\||<=|>=|!=|==|[+\-*/%<>=()]|\d+\.?\d*|\w+|.'
-
-    tokens = re.findall(token_pattern, expression)
-
-    if not tokens:
-        raise ValueError("Expression is empty")
-
-    # Convert tokens to Polars expression syntax
-    converted_tokens = []
-    for token in tokens:
-        if token.startswith("$"):
-            # Column reference
-            col_ref = token[1:]
-
-            # Special case: $_ refers to the current selected column
-            if col_ref == "_":
-                col_name = df.columns[current_col_idx]
-            # Check if it's a numeric index
-            elif col_ref.isdigit():
-                col_idx = int(col_ref) - 1  # Convert to 0-based index
-                if col_idx < 0 or col_idx >= len(df.columns):
-                    raise ValueError(f"Column index out of range: ${col_ref}")
-                col_name = df.columns[col_idx]
-            else:
-                # It's a column name
-                if col_ref not in df.columns:
-                    raise ValueError(f"Column not found: ${col_ref}")
-                col_name = col_ref
-
-            converted_tokens.append(f"pl.col('{col_name}')")
-
-        elif token in ("&&", "||"):
-            # Convert logical operators and wrap surrounding expressions in parentheses
-            if token == "&&":
-                converted_tokens.append(") & (")
-            else:
-                converted_tokens.append(") | (")
-
+    # Early return if no $ present
+    if "$" not in expression:
+        if "pl." in expression:
+            # This may be valid Polars expression already
+            return expression
         else:
-            # Keep as-is (operators, numbers, strings, parentheses)
-            converted_tokens.append(token)
+            # Return as a literal string
+            return f"pl.lit({expression})"
+
+    # Pattern to match $ followed by either:
+    # - _ (single underscore)
+    # - # (hash for row index)
+    # - digits (integer)
+    # - identifier (starts with letter or _, followed by letter/digit/_)
+    pattern = r"\$(_|#|\d+|[a-zA-Z_]\w*)"
+
+    def replace_column_ref(match):
+        col_ref = match.group(1)
+
+        if col_ref == "_":
+            # Current selected column
+            col_name = df.columns[current_col_idx]
+        elif col_ref == "#":
+            # RIDX is used to store 0-based row index; add 1 for 1-based index
+            return f"(pl.col('{RIDX}') + 1)"
+        elif col_ref.isdigit():
+            # Column by 1-based index
+            col_idx = int(col_ref) - 1
+            if col_idx < 0 or col_idx >= len(df.columns):
+                raise ValueError(f"Column index out of range: ${col_ref}")
+            col_name = df.columns[col_idx]
+        else:
+            # Column by name
+            if col_ref not in df.columns:
+                raise ValueError(f"Column not found: ${col_ref}")
+            col_name = col_ref
+
+        return f"pl.col('{col_name}')"
 
-    # Join tokens with space to ensure proper separation
-    result = "(" + " ".join(converted_tokens) + ")"
+    result = re.sub(pattern, replace_column_ref, expression)
     return result
+
+
+def tentative_expr(term: str) -> bool:
+    """Check if the given term could be a Polars expression.
+
+    Heuristically determines whether a string might represent a Polars expression
+    based on common patterns like column references ($) or direct Polars syntax (pl.).
+
+    Args:
+        term: The string to check.
+
+    Returns:
+        True if the term appears to be a Polars expression, False otherwise.
+    """
+    if "$" in term and not term.endswith("$"):
+        return True
+    if "pl." in term:
+        return True
+    return False
+
+
+def validate_expr(term: str, df: pl.DataFrame, current_col_idx: int) -> pl.Expr | None:
+    """Validate and return the expression.
+
+    Parses a user-provided expression string and validates it as a valid Polars expression.
+    Converts special syntax like $_ references to proper Polars col() expressions.
+
+    Args:
+        term: The input expression as a string.
+        df: The DataFrame to validate column references against.
+        current_col_idx: The index of the currently selected column (0-based). Used for $_ reference.
+
+    Returns:
+        A valid Polars expression object if validation succeeds.
+
+    Raises:
+        ValueError: If the expression is invalid, contains non-existent column references, or cannot be evaluated.
+    """
+    term = term.strip()
+
+    try:
+        # Parse the expression
+        expr_str = parse_polars_expression(term, df, current_col_idx)
+
+        # Validate by evaluating it
+        try:
+            expr = eval(expr_str, {"pl": pl})
+            if not isinstance(expr, pl.Expr):
+                raise ValueError(f"Expression evaluated to `{type(expr).__name__}` instead of a Polars expression")
+
+            # Expression is valid
+            return expr
+        except Exception as e:
+            raise ValueError(f"Failed to evaluate expression `{expr_str}`: {e}") from e
+    except Exception as ve:
+        raise ValueError(f"Failed to validate expression `{term}`: {ve}") from ve

dataframe_textual/data_frame_help_panel.py

@@ -2,6 +2,7 @@
 
 from textwrap import dedent
 
+from textual.app import ComposeResult
 from textual.containers import VerticalScroll
 from textual.css.query import NoMatches
 from textual.widget import Widget
@@ -19,8 +20,8 @@ class DataFrameHelpPanel(Widget):
         DataFrameHelpPanel {
             split: right;
             width: 33%;
-            min-width: 30;
-            max-width: 60;
+            min-width: 40;
+            max-width: 80;
             border-left: vkey $foreground 30%;
             padding: 0 1;
             height: 1fr;
@@ -68,7 +69,16 @@ class DataFrameHelpPanel(Widget):
 
     DEFAULT_CLASSES = "-textual-system"
 
-    def on_mount(self):
+    def on_mount(self) -> None:
+        """Set up help panel when mounted.
+
+        Initializes the help panel by setting up a watcher for focused widget changes
+        to dynamically update help text based on which widget has focus.
+
+        Returns:
+            None
+        """
+
         def update_help(focused_widget: Widget | None):
             self.update_help(focused_widget)
 
@@ -94,5 +104,13 @@ class DataFrameHelpPanel(Widget):
             except NoMatches:
                 pass
 
-    def compose(self):
+    def compose(self) -> ComposeResult:
+        """Compose the help panel widget structure.
+
+        Creates and returns the widget hierarchy for the help panel,
+        including a VerticalScroll container with a Markdown display area.
+
+        Yields:
+            VerticalScroll: The main container with Markdown widget for help text.
+        """
         yield VerticalScroll(Markdown(id="widget-help"))