dataframe-textual 0.3.2__py3-none-any.whl → 1.2.0__py3-none-any.whl

dataframe_textual/data_frame_viewer.py

@@ -1,7 +1,6 @@
 """DataFrame Viewer application and utilities."""
 
 import os
-import sys
 from functools import partial
 from pathlib import Path
 from textwrap import dedent
@@ -13,7 +12,7 @@ from textual.theme import BUILTIN_THEMES
 from textual.widgets import TabbedContent, TabPane
 from textual.widgets.tabbed_content import ContentTab, ContentTabs
 
-from .common import _next
+from .common import get_next_item, load_file
 from .data_frame_help_panel import DataFrameHelpPanel
 from .data_frame_table import DataFrameTable
 from .yes_no_screen import OpenFileScreen, SaveFileScreen
@@ -35,7 +34,7 @@ class DataFrameViewer(App):
         - **q** - 🚪 Quit application
 
         ## 🎨 View & Settings
-        - **?** or **h** - ❓ Toggle this help panel
+        - **Ctrl+H** - ❓ Toggle this help panel
         - **k** - 🌙 Cycle through themes
 
         ## ⭐ Features
@@ -52,7 +51,7 @@ class DataFrameViewer(App):
 
     BINDINGS = [
         ("q", "quit", "Quit"),
-        ("h,?", "toggle_help_panel", "Help"),
+        ("ctrl+h", "toggle_help_panel", "Help"),
         ("B", "toggle_tab_bar", "Toggle Tab Bar"),
         ("ctrl+o", "add_tab", "Add Tab"),
         ("ctrl+shift+s", "save_all_tabs", "Save All Tabs"),
@@ -79,29 +78,51 @@ class DataFrameViewer(App):
         }
     """
 
-    def __init__(self, *filenames):
+    def __init__(self, *sources: str) -> None:
+        """Initialize the DataFrame Viewer application.
+
+        Loads data from provided sources and prepares the tabbed interface.
+
+        Args:
+            sources: sources to load dataframes from, each as a tuple of
+                     (DataFrame | LazyFrame, filename, tabname).
+
+        Returns:
+            None
+        """
         super().__init__()
-        self.sources = _load_dataframe(filenames)
+        self.sources = sources
         self.tabs: dict[TabPane, DataFrameTable] = {}
         self.help_panel = None
 
     def compose(self) -> ComposeResult:
-        """Create tabbed interface for multiple files or direct table for single file."""
+        """Compose the application widget structure.
+
+        Creates a tabbed interface with one tab per file/sheet loaded. Each tab
+        contains a DataFrameTable widget for displaying and interacting with the data.
+
+        Yields:
+            TabPane: One tab per file or sheet for the tabbed interface.
+        """
         # Tabbed interface
         self.tabbed = TabbedContent(id="main_tabs")
         with self.tabbed:
             seen_names = set()
             for idx, (df, filename, tabname) in enumerate(self.sources, start=1):
+                tab_id = f"tab_{idx}"
+
+                if not tabname:
+                    tabname = Path(filename).stem or tab_id
+
                 # Ensure unique tab names
-                if tabname in seen_names:
-                    tabname = f"{tabname}_{idx}"
+                counter = 1
+                while tabname in seen_names:
+                    tabname = f"{tabname}_{counter}"
+                    counter += 1
                 seen_names.add(tabname)
 
-                tab_id = f"tab_{idx}"
                 try:
-                    table = DataFrameTable(
-                        df, filename, name=tabname, id=tab_id, zebra_stripes=True
-                    )
+                    table = DataFrameTable(df, filename, name=tabname, id=tab_id, zebra_stripes=True)
                     tab = TabPane(tabname, table, name=tabname, id=tab_id)
                     self.tabs[tab] = table
                     yield tab
@@ -109,51 +130,68 @@ class DataFrameViewer(App):
                     self.notify(f"Error loading {tabname}: {e}", severity="error")
 
     def on_mount(self) -> None:
-        """Set up the app when it starts."""
+        """Set up the application when it starts.
+
+        Initializes the app by hiding the tab bar for single-file mode and focusing
+        the active table widget.
+
+        Returns:
+            None
+        """
         if len(self.tabs) == 1:
             self.query_one(ContentTabs).display = False
             self._get_active_table().focus()
 
-    def on_key(self, event):
+    def on_key(self, event) -> None:
+        """Handle key press events at the application level.
+
+        Currently handles theme cycling with the 'k' key.
+
+        Args:
+            event: The key event object containing key information.
+
+        Returns:
+            None
+        """
         if event.key == "k":
-            self.theme = _next(list(BUILTIN_THEMES.keys()), self.theme)
-            self.notify(
-                f"Switched to theme: [on $primary]{self.theme}[/]", title="Theme"
-            )
-
-    def on_tabbed_content_tab_activated(
-        self, event: TabbedContent.TabActivated
-    ) -> None:
-        """Handle tab changes (only for multiple tabs)."""
-        # Only process if we have multiple files
-        if len(self.tabs) <= 1:
+            self.theme = get_next_item(list(BUILTIN_THEMES.keys()), self.theme)
+            self.notify(f"Switched to theme: [$success]{self.theme}[/]", title="Theme")
+
+    def on_tabbed_content_tab_activated(self, event: TabbedContent.TabActivated) -> None:
+        """Handle tab activation events.
+
+        When a tab is activated, focuses the table widget and loads its data if not already loaded.
+        Applies active styling to the clicked tab and removes it from others.
+
+        Args:
+            event: The tab activated event containing the activated tab pane.
+
+        Returns:
+            None
+        """
+        # Focus the table in the newly activated tab
+        if table := self._get_active_table():
+            table.focus()
+        else:
             return
 
+        if table.loaded_rows == 0:
+            table._setup_table()
+
         # Apply background color to active tab
         event.tab.add_class("active")
         for tab in self.tabbed.query(ContentTab):
             if tab != event.tab:
                 tab.remove_class("active")
 
-        try:
-            # Focus the table in the newly activated tab
-            if table := self._get_active_table():
-                table.focus()
-        except NoMatches:
-            pass
+    def action_toggle_help_panel(self) -> None:
+        """Toggle the help panel on or off.
 
-    def _get_active_table(self) -> DataFrameTable | None:
-        """Get the currently active table."""
-        try:
-            tabbed: TabbedContent = self.query_one(TabbedContent)
-            if active_pane := tabbed.active_pane:
-                return active_pane.query_one(DataFrameTable)
-        except (NoMatches, AttributeError):
-            pass
-        return None
+        Shows or hides the context-sensitive help panel. Creates it on first use.
 
-    def action_toggle_help_panel(self) -> None:
-        """Toggle the HelpPanel on/off."""
+        Returns:
+            None
+        """
         if self.help_panel:
             self.help_panel.display = not self.help_panel.display
         else:
@@ -161,50 +199,135 @@ class DataFrameViewer(App):
             self.mount(self.help_panel)
 
     def action_add_tab(self) -> None:
-        """Open file dialog to load file to new tab."""
-        self.push_screen(OpenFileScreen(), self._handle_file_open)
+        """Open file browser to load a file in a new tab.
 
-    def _handle_file_open(self, filename: str) -> None:
-        """Handle file selection from dialog."""
-        if filename and os.path.exists(filename):
-            try:
-                df = pl.read_csv(filename)
-                self._add_tab(df, filename)
-                self.notify(
-                    f"Opened: [on $primary]{Path(filename).name}[/]", title="Open"
-                )
-            except Exception as e:
-                self.notify(f"Error: {e}", severity="error")
+        Displays the file open dialog for the user to select a file to load
+        as a new tab in the interface.
+
+        Returns:
+            None
+        """
+        self.push_screen(OpenFileScreen(), self._do_add_tab)
 
     def action_save_all_tabs(self) -> None:
-        """Save all tabs to a Excel file."""
-        callback = partial(self._get_active_table()._on_save_file_screen, all_tabs=True)
+        """Save all open tabs to a single Excel file.
+
+        Displays a save dialog to choose filename and location, then saves all
+        open tabs as separate sheets in a single Excel workbook.
+
+        Returns:
+            None
+        """
+        callback = partial(self._get_active_table()._do_save_file, all_tabs=True)
         self.push_screen(
             SaveFileScreen("all-tabs.xlsx", title="Save All Tabs"),
             callback=callback,
         )
 
     def action_close_tab(self) -> None:
-        """Close current tab (only for multiple files)."""
+        """Close the currently active tab.
+
+        Closes the current tab. If this is the only tab, exits the application instead.
+
+        Returns:
+            None
+        """
         if len(self.tabs) <= 1:
             self.app.exit()
             return
         self._close_tab()
 
-    def action_next_tab(self, offset: int = 1) -> str:
-        """Switch to next tab (only for multiple files)."""
+    def action_next_tab(self, offset: int = 1) -> None:
+        """Switch to the next tab or previous tab.
+
+        Cycles through tabs by the specified offset. With offset=1, moves to next tab.
+        With offset=-1, moves to previous tab. Wraps around when reaching edges.
+
+        Args:
+            offset: Number of tabs to advance (+1 for next, -1 for previous). Defaults to 1.
+
+        Returns:
+            None
+        """
         if len(self.tabs) <= 1:
             return
         try:
             tabs: list[TabPane] = list(self.tabs.keys())
-            next_tab = _next(tabs, self.tabbed.active_pane, offset)
+            next_tab = get_next_item(tabs, self.tabbed.active_pane, offset)
             self.tabbed.active = next_tab.id
         except (NoMatches, ValueError):
             pass
 
-    def _add_tab(self, df: pl.DataFrame, filename: str) -> None:
-        """Add new table tab. If single file, replace table; if multiple, add tab."""
-        tabname = Path(filename).stem
+    def action_toggle_tab_bar(self) -> None:
+        """Toggle the tab bar visibility.
+
+        Shows or hides the tab bar at the bottom of the window. Useful for maximizing
+        screen space in single-tab mode.
+
+        Returns:
+            None
+        """
+        tabs = self.query_one(ContentTabs)
+        tabs.display = not tabs.display
+        # status = "shown" if tabs.display else "hidden"
+        # self.notify(f"Tab bar [$success]{status}[/]", title="Toggle")
+
+    def _get_active_table(self) -> DataFrameTable | None:
+        """Get the currently active DataFrameTable widget.
+
+        Retrieves the table from the currently active tab. Returns None if no
+        table is found or an error occurs.
+
+        Returns:
+            The active DataFrameTable widget, or None if not found.
+        """
+        try:
+            tabbed: TabbedContent = self.query_one(TabbedContent)
+            if active_pane := tabbed.active_pane:
+                return active_pane.query_one(DataFrameTable)
+        except (NoMatches, AttributeError):
+            self.notify("No active table found", title="Locate", severity="error")
+        return None
+
+    def _do_add_tab(self, filename: str) -> None:
+        """Add a tab for the opened file.
+
+        Loads the specified file and creates one or more tabs for it. For Excel files,
+        creates one tab per sheet. For other formats, creates a single tab.
+
+        Args:
+            filename: Path to the file to load and add as tab(s).
+
+        Returns:
+            None
+        """
+        if filename and os.path.exists(filename):
+            try:
+                n_tab = 0
+                for lf, filename, tabname in load_file(filename, prefix_sheet=True):
+                    self._add_tab(lf.collect(), filename, tabname)
+                    n_tab += 1
+                self.notify(f"Added [$accent]{n_tab}[/] tab(s) for [$success]{filename}[/]", title="Open")
+            except Exception as e:
+                self.notify(f"Error: {e}", title="Open", severity="error")
+        else:
+            self.notify(f"File does not exist: [$warning]{filename}[/]", title="Open", severity="warning")
+
+    def _add_tab(self, df: pl.DataFrame, filename: str, tabname: str) -> None:
+        """Add new tab for the given DataFrame.
+
+        Creates and adds a new tab with the provided DataFrame and configuration.
+        Ensures unique tab names by appending an index if needed. Shows the tab bar
+        if this is no longer the only tab.
+
+        Args:
+            df: The Polars DataFrame to display in the new tab.
+            filename: The source filename for this data (used in table metadata).
+            tabname: The display name for the tab.
+
+        Returns:
+            None
+        """
         if any(tab.name == tabname for tab in self.tabs):
             tabname = f"{tabname}_{len(self.tabs) + 1}"
 
@@ -218,9 +341,7 @@ class DataFrameViewer(App):
             tab_idx = pending_tab_idx
             break
 
-        table = DataFrameTable(
-            df, filename, zebra_stripes=True, id=tab_idx, name=tabname
-        )
+        table = DataFrameTable(df, filename, zebra_stripes=True, id=tab_idx, name=tabname)
         tab = TabPane(tabname, table, name=tabname, id=tab_idx)
         self.tabbed.add_pane(tab)
         self.tabs[tab] = table
@@ -233,7 +354,14 @@ class DataFrameViewer(App):
         table.focus()
 
     def _close_tab(self) -> None:
-        """Close current tab."""
+        """Close the currently active tab.
+
+        Removes the active tab from the interface. If only one tab remains and no more
+        can be closed, the application exits instead.
+
+        Returns:
+            None
+        """
         try:
             if len(self.tabs) == 1:
                 self.app.exit()
@@ -241,95 +369,6 @@ class DataFrameViewer(App):
                 if active_pane := self.tabbed.active_pane:
                     self.tabbed.remove_pane(active_pane.id)
                     self.tabs.pop(active_pane)
-                    self.notify(
-                        f"Closed tab [on $primary]{active_pane.name}[/]", title="Close"
-                    )
+                    self.notify(f"Closed tab [$success]{active_pane.name}[/]", title="Close")
         except NoMatches:
             pass
-
-    def action_toggle_tab_bar(self) -> None:
-        """Toggle tab bar visibility."""
-        tabs = self.query_one(ContentTabs)
-        tabs.display = not tabs.display
-        status = "shown" if tabs.display else "hidden"
-        self.notify(f"Tab bar [on $primary]{status}[/]", title="Toggle")
-
-
-def _load_dataframe(filenames: list[str]) -> list[tuple[pl.DataFrame, str, str]]:
-    """Load a DataFrame from a file spec.
-
-    Args:
-        filenames: List of filenames to load. If single filename is "-", read from stdin.
-
-    Returns:
-        List of tuples of (DataFrame, filename, tabname)
-    """
-    sources = []
-
-    # Single file
-    if len(filenames) == 1:
-        filename = filenames[0]
-        filepath = Path(filename)
-        ext = filepath.suffix.lower()
-
-        # Handle stdin
-        if filename == "-" or not sys.stdin.isatty():
-            from io import StringIO
-
-            # Read CSV from stdin into memory first (stdin is not seekable)
-            stdin_data = sys.stdin.read()
-            df = pl.read_csv(StringIO(stdin_data))
-
-            # Reopen stdin to /dev/tty for proper terminal interaction
-            try:
-                tty = open("/dev/tty")
-                os.dup2(tty.fileno(), sys.stdin.fileno())
-            except (OSError, FileNotFoundError):
-                pass
-
-            sources.append((df, "stdin.csv", "stdin"))
-        # Handle Excel files with multiple sheets
-        elif ext in (".xlsx", ".xls"):
-            sheets = pl.read_excel(filename, sheet_id=0)
-            for sheet_name, df in sheets.items():
-                sources.append((df, filename, sheet_name))
-        # Handle TSV files
-        elif ext in (".tsv", ".tab"):
-            df = pl.read_csv(filename, separator="\t")
-            sources.append((df, filename, filepath.stem))
-        # Handle JSON files
-        elif ext == ".json":
-            df = pl.read_json(filename)
-            sources.append((df, filename, filepath.stem))
-        # Handle Parquet files
-        elif ext == ".parquet":
-            df = pl.read_parquet(filename)
-            sources.append((df, filename, filepath.stem))
-        # Handle regular CSV files
-        else:
-            df = pl.read_csv(filename)
-            sources.append((df, filename, filepath.stem))
-    # Multiple files
-    else:
-        for filename in filenames:
-            filepath = Path(filename)
-            ext = filepath.suffix.lower()
-
-            if ext in (".xlsx", ".xls"):
-                # Read only the first sheet for multiple files
-                df = pl.read_excel(filename)
-                sources.append((df, filename, filepath.stem))
-            elif ext in (".tsv", ".tab"):
-                df = pl.read_csv(filename, separator="\t")
-                sources.append((df, filename, filepath.stem))
-            elif ext == ".json":
-                df = pl.read_json(filename)
-                sources.append((df, filename, filepath.stem))
-            elif ext == ".parquet":
-                df = pl.read_parquet(filename)
-                sources.append((df, filename, filepath.stem))
-            else:
-                df = pl.read_csv(filename)
-                sources.append((df, filename, filepath.stem))
-
-    return sources