← XeFM crftwr/xefm on GitHub · craftware

XeFM Drives Dialog System

Overview

The Drives Dialog System is a unified interface for selecting and navigating to different storage locations in XeFM, including local filesystem directories and remote S3 buckets. This system enhances XeFM’s navigation capabilities by offering quick access to commonly used storage locations through a clean, consistent interface.

Features

Storage Types Supported

Local Filesystem

AWS S3 Storage

User Interface

Dialog Layout

Key Action
↑/↓ Navigate up/down through drives
Page Up/Down Navigate by pages
Home/End Jump to first/last drive
Type Filter drives by text
Enter Select and navigate to drive
ESC Cancel and close dialog

Technical Implementation

Architecture

The Drives Dialog follows XeFM’s modular dialog architecture with clean separation of concerns:

Core Components

DriveEntry Class
class DriveEntry:
    def __init__(self, name: str, path: str, description: str = "", icon: str = "💾")
    
    @property
    def display_name(self) -> str
    
    @property
    def full_description(self) -> str

Represents individual storage locations with:

DrivesDialog Class
class DrivesDialog(BaseListDialog):
    def __init__(self, config)
    def show(self)
    def exit(self)
    def handle_input(self, key)
    def draw(self, stdscr, safe_addstr_func)
    def get_selected_drive(self) -> Optional[DriveEntry]

Main dialog class extending BaseListDialog with:

DrivesDialogHelpers Class
class DrivesDialogHelpers:
    @staticmethod
    def navigate_to_drive(file_manager, drive_entry: DriveEntry)
    
    @staticmethod
    def get_local_drives() -> List[DriveEntry]
    
    @staticmethod
    def get_s3_drives() -> List[DriveEntry]

Static helper methods for:

Threading Support

Background S3 Scanning

def _scan_s3_buckets_thread(self):
    """Background thread for S3 bucket discovery"""
    try:
        # Discover S3 buckets using boto3
        s3_drives = DrivesDialogHelpers.get_s3_drives()
        
        # Thread-safe update of drive list
        with self._drives_lock:
            self.s3_drives = s3_drives
            self.drives_loaded = True
            self.content_changed = True
    except Exception as e:
        # Handle errors gracefully
        self._handle_s3_error(e)

Features:

Progress Animation

def _get_loading_indicator(self) -> str:
    """Animated loading indicator for S3 scanning"""
    if not self.scanning_s3:
        return ""
    
    frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']
    frame_index = (time.time() * 4) % len(frames)
    return frames[int(frame_index)]

Provides smooth visual feedback during background operations.

Error Handling

Local Filesystem Errors

S3 Errors

Error Recovery Patterns

def _handle_s3_error(self, error):
    """Handle S3 errors with appropriate user feedback"""
    if isinstance(error, NoCredentialsError):
        self._add_s3_placeholder("S3 (No Credentials)", 
                                "Configure AWS credentials to access S3 buckets")
    elif isinstance(error, ClientError):
        self._add_s3_placeholder("S3 (Access Error)", 
                                f"Error accessing S3: {error}")
    else:
        self._add_s3_placeholder("S3 (Error)", 
                                "Unable to load S3 buckets")

Performance Optimization

Efficient Filtering

def _filter_drives(self, filter_text: str) -> List[DriveEntry]:
    """Efficient case-insensitive filtering of drives"""
    if not filter_text:
        return self.all_drives
    
    filter_lower = filter_text.lower()
    return [drive for drive in self.all_drives 
            if filter_lower in drive.name.lower() 
            or filter_lower in drive.path.lower() 
            or filter_lower in drive.description.lower()]

Memory Management

Background Loading

Integration with XeFM

Main Application Integration

Initialization

# In FileManager.__init__()
self.drives_dialog = DrivesDialog(self.config)

Input Handling

# In FileManager.run() main loop
elif self.is_key_for_action(key, 'drives_dialog'):
    self.show_drives_dialog()

# Dialog input handling
if self.drives_dialog.mode:
    result = self.drives_dialog.handle_input(key)
    if result == 'select':
        selected_drive = self.drives_dialog.get_selected_drive()
        if selected_drive:
            DrivesDialogHelpers.navigate_to_drive(self, selected_drive)
        self.drives_dialog.exit()
    elif result == 'cancel':
        self.drives_dialog.exit()

Drawing Integration

# In main draw loop
def _draw_dialogs_if_needed(self):
    if self.drives_dialog.mode:
        self.drives_dialog.draw(self.stdscr, self.safe_addstr)

Pane Manager Integration

@staticmethod
def navigate_to_drive(file_manager, drive_entry: DriveEntry):
    """Navigate to selected drive in active pane"""
    try:
        # Update active pane path
        active_pane = file_manager.get_active_pane()
        active_pane['path'] = Path(drive_entry.path)
        active_pane['selected_files'] = set()
        active_pane['scroll_offset'] = 0
        
        # Refresh pane content
        file_manager.refresh_files()
        file_manager.needs_full_redraw = True
        
        # User feedback
        file_manager.show_status(f"Navigated to: {drive_entry.name}")
        
    except Exception as e:
        file_manager.show_error(f"Failed to navigate to {drive_entry.name}: {e}")

Configuration

Key Bindings

Default configuration in xefm/_config.py:

KEY_BINDINGS = {
    # ... other bindings ...
    'drives_dialog': ['d', 'D'],  # Show drives/storage selection dialog
}

Customization Options

The drives dialog respects existing XeFM configuration:

Usage Examples

Basic Usage

  1. Open Dialog: Press d or D to open the drives dialog
  2. Navigate: Use arrow keys to navigate through available drives
  3. Filter: Type to filter drives (e.g., type “s3” to show only S3 buckets)
  4. Select: Press Enter to navigate to selected drive
  5. Cancel: Press ESC to cancel and close dialog

Filtering Examples

S3 Integration Scenarios

With AWS Credentials Configured

Without AWS Credentials

Testing

Test Coverage

Unit Tests (test/test_drives_dialog.py)

Integration Tests (test/test_drives_dialog_integration.py)

Test Scenarios

  1. Drive Discovery
    • Local filesystem enumeration
    • S3 bucket discovery with valid credentials
    • Error handling with invalid/missing credentials
  2. User Interface
    • Navigation controls (up/down, page up/down, home/end)
    • Real-time filtering
    • Progress animation during loading
    • Visual indicators and icons
  3. Integration
    • Pane navigation after drive selection
    • State management and cleanup
    • Error handling and user feedback
  4. Threading
    • Background S3 scanning
    • Thread safety and cancellation
    • Race condition prevention

Test Results

All tests pass successfully:

Dependencies

Required Dependencies

Optional Dependencies

Installation Notes

The drives dialog is automatically available when XeFM is installed. For S3 functionality:

# Install AWS SDK
pip install boto3

# Configure AWS credentials
aws configure
# or set environment variables
export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
export AWS_DEFAULT_REGION=us-west-2

Benefits

User Experience Benefits

Developer Benefits

Technical Benefits

Troubleshooting

Common Issues

S3 Buckets Not Showing

Symptoms: No S3 buckets appear in the drives dialog Solutions:

Slow Loading

Symptoms: Dialog takes long time to show S3 buckets Causes:

Permission Errors

Symptoms: Some drives show access errors Causes:

Debug Information

Enable debug logging to troubleshoot issues:

Error Messages

Common error messages and their meanings:

Future Enhancements

Planned Features

Additional Storage Types

  1. SFTP/SSH Remote Directories
    • SSH key authentication
    • Password authentication
    • Connection management
  2. FTP Servers
    • FTP and FTPS support
    • Anonymous and authenticated access
    • Directory browsing
  3. Network Shares
    • SMB/CIFS support
    • Windows network drives
    • Authentication handling
  4. Cloud Storage
    • Google Drive integration
    • Dropbox support
    • OneDrive connectivity

Enhanced Features

  1. Favorite Drives Management
    • User-defined favorite locations
    • Quick access shortcuts
    • Custom aliases and descriptions
  2. Recent Drives History
    • Track recently accessed drives
    • Quick access to recent locations
    • Configurable history size
  3. Drive Usage Statistics
    • Access frequency tracking
    • Usage patterns analysis
    • Smart recommendations

Advanced S3 Features

  1. Multi-region Support
    • Cross-region bucket discovery
    • Region-specific filtering
    • Regional performance optimization
  2. Bucket Metadata Display
    • Storage class information
    • Versioning status
    • Encryption settings
    • Cost estimation
  3. Access Policy Information
    • Bucket policy summary
    • Permission analysis
    • Security recommendations

Implementation Roadmap

Phase 1: Core Enhancements

Phase 2: Additional Storage Types

Phase 3: Advanced Features

API Reference

DriveEntry Class

class DriveEntry:
    def __init__(self, name: str, path: str, description: str = "", icon: str = "💾")
    
    @property
    def display_name(self) -> str
        """Get formatted display name with icon"""
    
    @property
    def full_description(self) -> str
        """Get complete description including path"""

DrivesDialog Class

class DrivesDialog(BaseListDialog):
    def __init__(self, config)
        """Initialize drives dialog with configuration"""
    
    def show(self)
        """Show the drives dialog and start S3 scanning"""
    
    def exit(self)
        """Exit dialog and cleanup resources"""
    
    def handle_input(self, key) -> str
        """Handle keyboard input, returns 'select', 'cancel', or None"""
    
    def get_selected_drive(self) -> Optional[DriveEntry]
        """Get currently selected drive entry"""

DrivesDialogHelpers Class

class DrivesDialogHelpers:
    @staticmethod
    def navigate_to_drive(file_manager, drive_entry: DriveEntry)
        """Navigate XeFM to the specified drive"""
    
    @staticmethod
    def get_local_drives() -> List[DriveEntry]
        """Get list of local filesystem drives"""
    
    @staticmethod
    def get_s3_drives() -> List[DriveEntry]
        """Get list of accessible S3 buckets"""

Conclusion

The XeFM Drives Dialog System successfully enhances XeFM’s navigation capabilities by providing a unified, user-friendly interface for accessing both local and remote storage locations. The implementation follows XeFM’s established patterns, includes comprehensive error handling, and provides a solid foundation for future enhancements.

Key Achievements

The system is production-ready and provides immediate value to XeFM users who work with both local files and cloud storage, while maintaining the performance and reliability standards expected from XeFM.