gitflow-analytics 1.0.0__py3-none-any.whl → 1.0.3__py3-none-any.whl

gitflow_analytics/tui/widgets/__init__.py

@@ -0,0 +1,7 @@
+"""Custom widgets for the GitFlow Analytics TUI."""
+
+from .progress_widget import AnalysisProgressWidget
+from .data_table import EnhancedDataTable
+from .export_modal import ExportModal
+
+__all__ = ["AnalysisProgressWidget", "EnhancedDataTable", "ExportModal"]

gitflow_analytics/tui/widgets/data_table.py

@@ -0,0 +1,257 @@
+"""Enhanced data table widget for GitFlow Analytics TUI."""
+
+from typing import Any, Dict, List, Optional, Union
+from datetime import datetime
+
+from textual.widgets import DataTable
+from textual.reactive import reactive
+from rich.text import Text
+
+
+class EnhancedDataTable(DataTable):
+    """
+    Enhanced data table with sorting, filtering, and formatting capabilities.
+    
+    WHY: The standard DataTable widget lacks features needed for displaying
+    complex analytics data like sorting, filtering, and intelligent formatting
+    of different data types (dates, numbers, etc.).
+    
+    DESIGN DECISION: Extends DataTable rather than creating from scratch to
+    maintain compatibility with Textual's data table features while adding
+    the necessary enhancements for analytics display.
+    """
+    
+    DEFAULT_CSS = """
+    EnhancedDataTable {
+        height: auto;
+    }
+    
+    EnhancedDataTable > .datatable--header {
+        background: $primary 10%;
+        color: $primary;
+        text-style: bold;
+    }
+    
+    EnhancedDataTable > .datatable--row-hover {
+        background: $accent 20%;
+    }
+    
+    EnhancedDataTable > .datatable--row-cursor {
+        background: $primary 30%;
+    }
+    """
+    
+    # Reactive attributes for dynamic updates
+    sort_column = reactive("")
+    sort_reverse = reactive(False)
+    filter_text = reactive("")
+    
+    def __init__(
+        self,
+        data: Optional[List[Dict[str, Any]]] = None,
+        *,
+        name: Optional[str] = None,
+        id: Optional[str] = None,
+        classes: Optional[str] = None
+    ) -> None:
+        super().__init__(name=name, id=id, classes=classes)
+        self._raw_data = data or []
+        self._filtered_data = []
+        self._column_formatters = {}
+        
+    def set_data(self, data: List[Dict[str, Any]]) -> None:
+        """
+        Set table data with automatic column detection and formatting.
+        
+        WHY: Automatically handles different data types and formats them
+        appropriately for display, reducing the need for manual formatting
+        in calling code.
+        """
+        self._raw_data = data
+        if not data:
+            return
+            
+        # Clear existing data
+        self.clear()
+        
+        # Get columns from first row
+        columns = list(data[0].keys())
+        
+        # Add columns with appropriate widths
+        for col in columns:
+            width = self._calculate_column_width(col, data)
+            self.add_column(self._format_column_header(col), width=width, key=col)
+        
+        # Set up formatters based on data types
+        self._setup_formatters(data)
+        
+        # Add data rows
+        self._apply_filter_and_sort()
+    
+    def _calculate_column_width(self, column: str, data: List[Dict[str, Any]]) -> int:
+        """
+        Calculate appropriate column width based on content.
+        
+        WHY: Dynamically sizes columns based on actual content to optimize
+        display space while ensuring all content is visible.
+        """
+        # Start with header width
+        max_width = len(self._format_column_header(column))
+        
+        # Check sample of data for width
+        sample_size = min(50, len(data))
+        for row in data[:sample_size]:
+            value = row.get(column, "")
+            formatted_value = self._format_cell_value(column, value)
+            max_width = max(max_width, len(str(formatted_value)))
+        
+        # Set reasonable bounds
+        return min(max(max_width + 2, 8), 50)
+    
+    def _format_column_header(self, column: str) -> str:
+        """Format column header for display."""
+        # Convert snake_case to Title Case
+        return column.replace('_', ' ').title()
+    
+    def _setup_formatters(self, data: List[Dict[str, Any]]) -> None:
+        """
+        Set up column formatters based on data types.
+        
+        WHY: Automatically detects data types and applies appropriate formatting
+        (dates, numbers, percentages) to improve readability.
+        """
+        if not data:
+            return
+            
+        sample_row = data[0]
+        
+        for column, value in sample_row.items():
+            if isinstance(value, datetime):
+                self._column_formatters[column] = self._format_datetime
+            elif isinstance(value, (int, float)):
+                # Check if it looks like a percentage
+                if any('pct' in column.lower() or 'percent' in column.lower() 
+                      or 'rate' in column.lower() for _ in [column]):
+                    self._column_formatters[column] = self._format_percentage
+                else:
+                    self._column_formatters[column] = self._format_number
+            elif isinstance(value, str) and len(value) > 50:
+                self._column_formatters[column] = self._format_long_text
+    
+    def _format_cell_value(self, column: str, value: Any) -> str:
+        """Format individual cell value."""
+        if value is None:
+            return ""
+            
+        formatter = self._column_formatters.get(column, str)
+        return formatter(value)
+    
+    def _format_datetime(self, value: datetime) -> str:
+        """Format datetime values."""
+        if isinstance(value, str):
+            try:
+                value = datetime.fromisoformat(value.replace('Z', '+00:00'))
+            except:
+                return str(value)
+        return value.strftime('%Y-%m-%d %H:%M')
+    
+    def _format_number(self, value: Union[int, float]) -> str:
+        """Format numeric values."""
+        if isinstance(value, float):
+            if value >= 1000:
+                return f"{value:,.1f}"
+            else:
+                return f"{value:.2f}"
+        return f"{value:,}"
+    
+    def _format_percentage(self, value: Union[int, float]) -> str:
+        """Format percentage values."""
+        return f"{value:.1f}%"
+    
+    def _format_long_text(self, value: str) -> str:
+        """Format long text values."""
+        if len(value) > 47:
+            return value[:44] + "..."
+        return value
+    
+    def _apply_filter_and_sort(self) -> None:
+        """
+        Apply current filter and sort settings to data.
+        
+        WHY: Provides real-time filtering and sorting capabilities that are
+        essential for exploring large datasets in the analytics results.
+        """
+        # Start with all data
+        filtered_data = self._raw_data.copy()
+        
+        # Apply filter if set
+        if self.filter_text:
+            filtered_data = [
+                row for row in filtered_data
+                if any(self.filter_text.lower() in str(value).lower() 
+                      for value in row.values())
+            ]
+        
+        # Apply sort if set
+        if self.sort_column and self.sort_column in (filtered_data[0] if filtered_data else {}):
+            try:
+                filtered_data.sort(
+                    key=lambda x: x.get(self.sort_column, ""),
+                    reverse=self.sort_reverse
+                )
+            except TypeError:
+                # Handle mixed types by converting to string
+                filtered_data.sort(
+                    key=lambda x: str(x.get(self.sort_column, "")),
+                    reverse=self.sort_reverse
+                )
+        
+        self._filtered_data = filtered_data
+        
+        # Clear and repopulate table
+        self.clear(columns=False)  # Keep columns, clear rows
+        
+        for row in filtered_data:
+            formatted_row = [
+                self._format_cell_value(col, row.get(col, ""))
+                for col in row.keys()
+            ]
+            self.add_row(*formatted_row)
+    
+    def sort_by_column(self, column: str, reverse: bool = False) -> None:
+        """Sort table by specified column."""
+        self.sort_column = column
+        self.sort_reverse = reverse
+        self._apply_filter_and_sort()
+    
+    def filter_data(self, filter_text: str) -> None:
+        """Filter table data by text search."""
+        self.filter_text = filter_text
+        self._apply_filter_and_sort()
+    
+    def export_to_csv(self, filename: str) -> None:
+        """
+        Export current filtered/sorted data to CSV.
+        
+        WHY: Allows users to export the specific view they've filtered and
+        sorted, maintaining their exploration context.
+        """
+        import csv
+        
+        if not self._filtered_data:
+            return
+            
+        with open(filename, 'w', newline='', encoding='utf-8') as csvfile:
+            if self._filtered_data:
+                fieldnames = list(self._filtered_data[0].keys())
+                writer = csv.DictWriter(csvfile, fieldnames=fieldnames)
+                writer.writeheader()
+                writer.writerows(self._filtered_data)
+    
+    def get_row_count(self) -> int:
+        """Get number of rows currently displayed."""
+        return len(self._filtered_data)
+    
+    def get_total_count(self) -> int:
+        """Get total number of rows in dataset."""
+        return len(self._raw_data)

gitflow_analytics/tui/widgets/export_modal.py

@@ -0,0 +1,301 @@
+"""Export modal dialog for GitFlow Analytics TUI."""
+
+from pathlib import Path
+from typing import Optional, Dict, Any, List, Callable
+
+from textual.widgets import Button, Input, Label, Select, Switch, Static
+from textual.containers import Container, Horizontal, Vertical
+from textual.screen import ModalScreen
+from textual.binding import Binding
+from textual.message import Message
+
+
+class ExportModal(ModalScreen[Optional[Dict[str, Any]]]):
+    """
+    Modal dialog for configuring and executing data exports.
+    
+    WHY: Provides a comprehensive export interface that allows users to
+    choose format, location, and export options without cluttering the
+    main interface. Modal design ensures focused interaction.
+    
+    DESIGN DECISION: Returns export configuration as a dictionary rather
+    than executing export directly, allowing the calling code to handle
+    the actual export operation with proper error handling and progress feedback.
+    """
+    
+    DEFAULT_CSS = """
+    ExportModal {
+        align: center middle;
+    }
+    
+    #export-dialog {
+        background: $surface;
+        border: thick $primary;
+        width: 80;
+        height: 25;
+        padding: 1;
+    }
+    
+    .modal-title {
+        text-align: center;
+        text-style: bold;
+        color: $primary;
+        margin-bottom: 1;
+    }
+    
+    .section-title {
+        text-style: bold;
+        color: $secondary;
+        margin: 1 0;
+    }
+    
+    .button-bar {
+        dock: bottom;
+        height: 3;
+        align: center middle;
+    }
+    
+    .form-row {
+        height: 3;
+        margin: 1 0;
+    }
+    
+    .form-label {
+        width: 20;
+        padding: 1 0;
+    }
+    """
+    
+    BINDINGS = [
+        Binding("escape", "cancel", "Cancel"),
+        Binding("ctrl+s", "export", "Export"),
+    ]
+    
+    class ExportRequested(Message):
+        """Message sent when export is requested."""
+        
+        def __init__(self, config: Dict[str, Any]) -> None:
+            super().__init__()
+            self.config = config
+    
+    def __init__(
+        self,
+        available_formats: Optional[List[str]] = None,
+        default_path: Optional[Path] = None,
+        data_info: Optional[Dict[str, Any]] = None
+    ) -> None:
+        super().__init__()
+        self.available_formats = available_formats or ["CSV", "JSON", "Markdown"]
+        self.default_path = default_path or Path("./reports")
+        self.data_info = data_info or {}
+        
+    def compose(self):
+        """Compose the export modal dialog."""
+        with Container(id="export-dialog"):
+            yield Label("Export Data", classes="modal-title")
+            
+            # Format selection
+            yield Label("Export Format:", classes="section-title")
+            format_options = [(fmt, fmt.lower()) for fmt in self.available_formats]
+            yield Select(format_options, value=format_options[0][1], id="format-select")
+            
+            # File path
+            yield Label("Export Location:", classes="section-title")
+            with Horizontal(classes="form-row"):
+                yield Label("Directory:", classes="form-label")
+                yield Input(
+                    value=str(self.default_path),
+                    placeholder="Path to export directory",
+                    id="path-input"
+                )
+            
+            with Horizontal(classes="form-row"):
+                yield Label("Filename:", classes="form-label")
+                yield Input(
+                    value=self._generate_default_filename(),
+                    placeholder="Export filename",
+                    id="filename-input"
+                )
+            
+            # Export options
+            yield Label("Export Options:", classes="section-title")
+            
+            with Horizontal(classes="form-row"):
+                yield Label("Include headers:", classes="form-label")
+                yield Switch(value=True, id="include-headers")
+            
+            with Horizontal(classes="form-row"):
+                yield Label("Anonymize data:", classes="form-label")
+                yield Switch(value=False, id="anonymize-data")
+            
+            # Data info
+            if self.data_info:
+                yield Label("Data Summary:", classes="section-title")
+                info_text = self._format_data_info()
+                yield Static(info_text, id="data-info")
+            
+            # Button bar
+            with Horizontal(classes="button-bar"):
+                yield Button("Cancel", variant="default", id="cancel-btn")
+                yield Button("Export", variant="primary", id="export-btn")
+    
+    def _generate_default_filename(self) -> str:
+        """
+        Generate default filename based on export format and current date.
+        
+        WHY: Provides sensible defaults to reduce user input while ensuring
+        unique filenames that won't accidentally overwrite existing files.
+        """
+        from datetime import datetime
+        
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        data_type = self.data_info.get('type', 'export')
+        return f"{data_type}_{timestamp}"
+    
+    def _format_data_info(self) -> str:
+        """Format data information for display."""
+        info_lines = []
+        
+        if 'row_count' in self.data_info:
+            info_lines.append(f"• Rows: {self.data_info['row_count']:,}")
+        
+        if 'column_count' in self.data_info:
+            info_lines.append(f"• Columns: {self.data_info['column_count']}")
+        
+        if 'date_range' in self.data_info:
+            info_lines.append(f"• Date range: {self.data_info['date_range']}")
+        
+        if 'data_types' in self.data_info:
+            types_str = ", ".join(self.data_info['data_types'])
+            info_lines.append(f"• Data types: {types_str}")
+        
+        return "\n".join(info_lines)
+    
+    def on_button_pressed(self, event: Button.Pressed) -> None:
+        """Handle button press events."""
+        if event.button.id == "cancel-btn":
+            self.action_cancel()
+        elif event.button.id == "export-btn":
+            self.action_export()
+    
+    def action_cancel(self) -> None:
+        """Cancel the export operation."""
+        self.dismiss(None)
+    
+    def action_export(self) -> None:
+        """
+        Validate inputs and request export operation.
+        
+        WHY: Performs comprehensive validation before submitting export
+        request to prevent errors and provide immediate feedback to users.
+        """
+        try:
+            # Collect form data
+            format_select = self.query_one("#format-select", Select)
+            path_input = self.query_one("#path-input", Input)
+            filename_input = self.query_one("#filename-input", Input)
+            include_headers = self.query_one("#include-headers", Switch)
+            anonymize_data = self.query_one("#anonymize-data", Switch)
+            
+            # Validate inputs
+            export_path = Path(path_input.value.strip())
+            filename = filename_input.value.strip()
+            
+            if not filename:
+                self.notify("Please enter a filename", severity="error")
+                return
+            
+            # Add extension if not present
+            selected_format = format_select.value
+            if selected_format == "csv" and not filename.lower().endswith('.csv'):
+                filename += '.csv'
+            elif selected_format == "json" and not filename.lower().endswith('.json'):
+                filename += '.json'
+            elif selected_format == "markdown" and not filename.lower().endswith('.md'):
+                filename += '.md'
+            
+            full_path = export_path / filename
+            
+            # Check if file exists
+            if full_path.exists():
+                # In a real implementation, you'd show a confirmation dialog
+                # For now, we'll just proceed with overwrite warning
+                pass
+            
+            # Create export configuration
+            export_config = {
+                'format': selected_format,
+                'path': full_path,
+                'include_headers': include_headers.value,
+                'anonymize': anonymize_data.value,
+            }
+            
+            # Send export request message
+            self.post_message(self.ExportRequested(export_config))
+            self.dismiss(export_config)
+            
+        except Exception as e:
+            self.notify(f"Export configuration error: {e}", severity="error")
+    
+    def on_select_changed(self, event: Select.Changed) -> None:
+        """Handle format selection changes."""
+        if event.select.id == "format-select":
+            # Update filename extension when format changes
+            filename_input = self.query_one("#filename-input", Input)
+            current_filename = filename_input.value
+            
+            # Remove existing extension
+            name_without_ext = current_filename.rsplit('.', 1)[0]
+            
+            # Add new extension
+            new_format = event.value
+            if new_format == "csv":
+                new_filename = f"{name_without_ext}.csv"
+            elif new_format == "json":
+                new_filename = f"{name_without_ext}.json"
+            elif new_format == "markdown":
+                new_filename = f"{name_without_ext}.md"
+            else:
+                new_filename = name_without_ext
+            
+            filename_input.value = new_filename
+    
+    def validate_export_path(self, path: Path) -> tuple[bool, str]:
+        """
+        Validate export path and return validation result.
+        
+        WHY: Prevents export failures by validating paths before attempting
+        to write files, providing clear error messages to users.
+        
+        @param path: Path to validate
+        @return: Tuple of (is_valid, error_message)
+        """
+        try:
+            # Check if parent directory exists or can be created
+            parent_dir = path.parent
+            if not parent_dir.exists():
+                try:
+                    parent_dir.mkdir(parents=True, exist_ok=True)
+                except PermissionError:
+                    return False, f"Permission denied: Cannot create directory {parent_dir}"
+                except Exception as e:
+                    return False, f"Cannot create directory {parent_dir}: {e}"
+            
+            # Check write permissions
+            if not parent_dir.exists():
+                return False, f"Directory does not exist: {parent_dir}"
+            
+            # Try creating a test file to check permissions
+            test_file = parent_dir / f".test_write_{hash(str(path))}"
+            try:
+                test_file.touch()
+                test_file.unlink()
+            except PermissionError:
+                return False, f"Permission denied: Cannot write to {parent_dir}"
+            except Exception as e:
+                return False, f"Cannot write to {parent_dir}: {e}"
+            
+            return True, ""
+            
+        except Exception as e:
+            return False, f"Path validation error: {e}"