PICARD-3118: Allow user to save/load current Picard session

[knguyen1]

Summary

• This is a…
  • Bug fix
  • Feature addition
  • Refactoring
  • Minor / simple change (like a typo)
  • Other
• Describe this change in 1-2 sentences: Implements session management functionality allowing users to save and restore their Picard workspace state, including file locations, metadata overrides, and configuration options.

Problem

• JIRA ticket (optional): PICARD-3118

Users lose their work state when closing Picard, including file placements, manual metadata edits, and album configurations.

Solution

Core Components

Session Data Structures (session_data.py):

• SessionItemLocation: Tracks file placement (unclustered, cluster, album, track, NAT)
• SessionData: Complete session container with version, options, items, and metadata overrides

Session Exporter (session_exporter.py):

• Captures workspace state including file locations and metadata deltas
• Exports only user-visible tags (excludes internal ~ tags)
• Supports optional MusicBrainz data caching

Session Loader (session_loader.py):

• Restores complete session with progress reporting
• Handles asynchronous file loading with retry mechanisms
• Applies metadata overrides after files are ready

Supporting Modules:

• location_detector.py: Determines file placement within session structure
• metadata_handler.py: Serializes/deserializes metadata with error handling
• track_mover.py: Handles file-to-track movement with retry logic
• retry_helper.py: Centralized retry mechanism

Key Features

• Safe Restore: Respects session_safe_restore setting to prevent overwriting unsaved changes
• Metadata Preservation: Saves only deltas vs original metadata
• Location Tracking: Supports all file placement types
• Configuration Persistence: Saves/restores file processing options
• UI State: Preserves album expansion state

File Format

• Extension: .mbps.gz (gzip-compressed YAML)
• Version: Format version 1 with extensibility

Configuration Options

Five new options added:

• session_safe_restore: Honor local edits on load (default: True)
• session_load_last_on_startup: Auto-load last session (default: False)
• session_autosave_interval_min: Auto-save interval in minutes (default: 0 = disabled)
• session_backup_on_crash: Keep backup on unexpected shutdown (default: True)
• session_include_mb_data: Include MB data in sessions (default: False)

Action

Additional actions required:

• Update Picard documentation (please include a reference to this PR) see: PICARD-3118: Add sessions usage/api documentation picard-docs#237
• Other (please specify below)

[zas]

Just few comments, I didn't test yet (I will soon).
That's a very promising improvement :)

[zas]

I'm not sure about the automatic saving (based on time).

[zas]

UI-wise it works well, thanks for all recent additions.
And it works well.

Though I have concerns about only saving 3 options, and IMHO this isn't enough (see my comment about that)

[knguyen1]

Try now. All test comments should have been addressed.

[zas]

LGTM