Fix extremely long filenames causing file not found

[knguyen1]

Fix for Extremely Long Filename FileNotFoundErrors

Problem

Users were experiencing FileNotFoundError exceptions when downloading tracks with extremely long filenames, particularly classical music with detailed metadata. The error occurred because the generated file paths exceeded filesystem limits (typically 260 characters on Windows).

Example error:

[01:17:19] ERROR    Error downloading track 'Pulcinella, ballet with song in one act, K034: XIV. Tarantella', retrying: [Errno 2] No such file or directory: 'M:/Toronto Symphony Orchestra, Gustavo Gimeno, Isabel Leonard, Paul Appleby, Derek Welton - Stravinsky Pulcinella, ballet with song in one act, K034 XIV. Tarantella (2025) [FLAC] [24B-96kHz]\\01. Toronto Symphony Orchestra - Pulcinella, ballet with song in one act, K034 XIV. Tarantella.flac'

Solution

Core Changes

1. Enhanced clean_filepath() Function

• Added max_length parameter (default: 200 characters)
• Implements path truncation with trailing whitespace removal
• Prevents filesystem path length issues while maintaining readability

2. Album Folder Path Handling (streamrip/media/album.py)

• Updated _album_folder() to use clean_filepath() with max_length=150
• Leaves room for parent path and track filenames within overall path limits
• Handles extremely long artist/album names gracefully

3. Track Path Management (streamrip/media/track.py)

• Enhanced _set_download_path() with comprehensive path length checking
• Implements two-tier truncation:
  • Config-based truncation via truncate_to setting
  • Automatic path length limiting (250 characters max)
• Added fallback directory creation when path creation fails
• Strips trailing whitespace after truncation

4. Robust Error Handling (streamrip/media/track.py)

• Enhanced preprocess() method with try-catch for directory creation
• Automatic fallback to temporary directory when primary path fails
• Recalculates download path with shorter fallback directory

Test Coverage

Comprehensive Unit Tests

tests/test_filepath_utils.py (287 lines)

• Byte-level truncation testing: Ensures truncate_str() respects 255-byte limits
• Unicode handling: Tests proper UTF-8 character boundary handling
• Path length validation: Parametrized tests for various max_length values
• Character restriction: Tests both enabled/disabled restriction modes
• Real-world scenarios: Tests with actual problematic paths from error reports

tests/test_track_filepath_handling.py (365 lines)

• Path length enforcement: Validates 250-character maximum path length
• Config truncation: Tests truncate_to setting with various values (50, 100, 200)
• Character sanitization: Ensures restricted characters are properly handled
• Directory creation fallback: Tests fallback behavior when directory creation fails
• Extension preservation: Validates file extensions are maintained across all scenarios
• Whitespace handling: Ensures trailing spaces are stripped after truncation

tests/test_album_filepath_handling.py (369 lines)

• Album folder truncation: Tests 150-character limit for album folder names
• Source subdirectories: Validates proper handling with source-based organization
• Unicode support: Tests international characters in album/artist names
• Real-world examples: Uses actual problematic album names from user reports
• Configuration scenarios: Tests various combinations of settings

tests/test_filepath_integration.py (434 lines)

• End-to-end scenarios: Tests complete album + track path generation
• Windows compatibility: Specific tests for Windows path length limits
• Error case simulation: Reproduces exact error conditions from user reports
• Unicode integration: Tests full pipeline with international characters
• Configuration matrix: Tests all combinations of settings (restrict_characters, source_subdirs, etc.)

Test Scenarios Covered

1. Normal-length paths: Ensures existing functionality remains unchanged
2. Extremely long paths: Validates proper truncation and error prevention
3. Unicode characters: Tests international character support
4. Special characters: Validates sanitization of filesystem-invalid characters
5. Directory creation failures: Tests fallback mechanisms
6. Configuration variations: Tests all relevant config combinations
7. Real-world error cases: Reproduces and validates fixes for reported issues

Validation

The fix has been validated against the original error case:

• Original problematic path: 300+ characters
• Fixed path: ≤250 characters with preserved essential information
• Fallback mechanism: Tested with impossible directory paths
• Cross-platform compatibility: Works on Windows, macOS, and Linux filesystem limits

This comprehensive solution ensures robust handling of extremely long filenames while maintaining backward compatibility and user experience.