tidal-dl/docs/gui_refactoring.md

Architecture GUI Refactorée

Vue d'ensemble

Le fichier gui.py a été refactorisé pour améliorer la maintenabilité en divisant la classe MainWindow monolithique (1837 lignes) en plusieurs modules organisés dans le dossier gui/.

Structure des fichiers

tidal_dl_ng/
├── gui/
│   ├── __init__.py              # Point d'entrée du module GUI
│   ├── activate.py              # Fonction d'activation de l'application GUI
│   ├── main_window.py           # Classe MainWindow principale
│   ├── initialization.py        # Mixin: Initialisation des composants UI
│   ├── tidal_session.py         # Mixin: Gestion de la session Tidal
│   ├── signals.py               # Mixin: Gestion des signaux Qt
│   ├── progress.py              # Mixin: Barres de progression
│   ├── ui_helpers.py            # Mixin: Helpers UI (spinners, logs, statusbar)
│   ├── track_extras.py          # Mixin: Cache et gestion des extras de tracks
│   ├── updates.py               # Mixin: Vérification des mises à jour
│   ├── downloads.py             # Mixin: Gestion des téléchargements
│   ├── trees_results.py         # Mixin: Gestion des arbres et résultats
│   ├── context_menus.py         # Mixin: Menus contextuels et actions
│   ├── history.py               # Mixin: Historique et prévention des doublons
│   ├── covers.py                # Manager de couvertures
│   ├── playlist.py              # Manager de playlists
│   ├── queue.py                 # Manager de queue
│   └── search.py                # Manager de recherche
├── gui.py                       # Point de compatibilité (redirige vers gui/)

Mixins et Responsabilités

1. InitializationMixin (initialization.py)

Responsable de l'initialisation de tous les composants de l'interface utilisateur.

Méthodes:

• _init_gui() - Configuration de la fenêtre principale
• _init_threads() - Initialisation du pool de threads
• _init_dl() - Configuration de l'objet Download
• _init_progressbar() - Initialisation des barres de progression
• _init_info() - Configuration de l'image de couverture par défaut
• _init_tree_results() - Configuration de l'arbre des résultats
• _init_tree_results_model() - Configuration du modèle de l'arbre
• _init_tree_queue() - Configuration de la queue de téléchargement
• _init_tree_lists() - Configuration de l'arbre des listes utilisateur
• _init_menu_actions() - Ajout d'actions de menu personnalisées
• _populate_quality() - Remplissage des options de qualité
• _populate_search_types() - Remplissage des types de recherche

2. TidalSessionMixin (tidal_session.py)

Gère l'authentification et la session Tidal.

Méthodes:

• init_tidal() - Initialisation de la session Tidal avec gestion du login
• on_logout() - Déconnexion de Tidal

3. SignalsMixin (signals.py)

Configure toutes les connexions de signaux Qt.

Méthodes:

• _init_signals() - Connexion de tous les signaux aux slots
• on_result_item_clicked() - Gestion du clic sur un élément de résultat
• on_quality_set_audio() - Configuration de la qualité audio
• on_quality_set_video() - Configuration de la qualité vidéo

4. ProgressMixin (progress.py)

Gère les barres de progression.

Méthodes:

• on_progress_reset() - Réinitialisation des barres de progression
• on_progress_list() - Mise à jour de la barre de progression de liste
• on_progress_item() - Mise à jour de la barre de progression d'élément
• on_progress_item_name() - Définition du nom d'élément
• on_progress_list_name() - Définition du nom de liste

5. UIHelpersMixin (ui_helpers.py)

Fournit des fonctions utilitaires pour l'interface utilisateur.

Méthodes:

• on_spinner_start() - Démarrage d'un spinner de chargement
• on_spinner_stop() - Arrêt de tous les spinners
• on_statusbar_message() - Affichage d'un message dans la barre d'état
• _log_output() - Redirection des logs vers l'interface
• button_reload_status() - Mise à jour du statut du bouton de rechargement

6. TrackExtrasMixin (track_extras.py)

Gère le cache et la récupération des informations supplémentaires des tracks.

Méthodes:

• get_track_extras() - Récupération des extras (avec cache)
• _on_invoke_callback() - Invocation du callback dans le thread principal
• _decorate_extras() - Ajout de champs formatés aux extras
• preload_covers_for_playlist() - Préchargement des couvertures

7. UpdatesMixin (updates.py)

Gère la vérification des mises à jour de l'application.

Méthodes:

• on_update_check() - Vérification des mises à jour disponibles
• on_version() - Affichage du dialogue de version

8. DownloadsMixin (downloads.py)

Gère la queue de téléchargement et les opérations de téléchargement.

Méthodes:

• on_download_results() - Téléchargement des résultats sélectionnés
• queue_download_media() - Ajout d'un élément à la queue
• watcher_queue_download() - Surveillance de la queue
• on_queue_download() - Exécution d'un téléchargement
• download() - Téléchargement d'un élément média
• Méthodes de gestion de statut: on_queue_download_item_downloading(), etc.

9. TreesResultsMixin (trees_results.py)

Gère les arbres de vue et l'affichage des résultats.

Méthodes:

• handle_filter_activated() - Gestion des filtres d'en-tête
• populate_tree_results() - Remplissage de l'arbre des résultats
• populate_tree_result_child() - Création d'un élément enfant
• on_tr_results_expanded() - Gestion de l'expansion des résultats
• tr_results_expanded() - Chargement des enfants d'un élément
• list_items_show_result() - Affichage des éléments d'une liste
• tidal_user_lists() - Récupération des listes utilisateur
• on_populate_tree_lists() - Remplissage de l'arbre des listes
• on_track_hover_confirmed() - Gestion du survol d'un track
• on_track_hover_left() - Gestion de la sortie du survol

10. ContextMenusMixin (context_menus.py)

Gère les menus contextuels et leurs actions.

Méthodes:

• menu_context_tree_results() - Menu contextuel pour les résultats
• menu_context_queue_download() - Menu contextuel pour la queue
• on_copy_url_share() - Copie de l'URL de partage
• on_download_album_from_track() - Téléchargement de l'album d'un track
• on_download_all_albums_from_playlist() - Téléchargement de tous les albums
• _extract_album_ids_from_tracks() - Extraction des IDs d'albums
• _load_albums_with_rate_limiting() - Chargement avec limitation de débit
• on_search_in_app() - Recherche dans l'application
• on_search_in_browser() - Ouverture de recherche dans le navigateur

11. HistoryMixin (history.py)

Gère l'historique des téléchargements et la prévention des doublons.

Méthodes:

• on_view_history() - Affichage du dialogue d'historique
• on_toggle_duplicate_prevention() - Activation/désactivation de la prévention
• on_mark_track_as_downloaded() - Marquer un track comme téléchargé
• on_mark_track_as_not_downloaded() - Retirer le marquage
• _update_downloaded_column() - Mise à jour de la colonne UI
• on_preferences() - Ouverture du dialogue de préférences
• on_settings_save() - Sauvegarde des paramètres

Classe MainWindow

La classe MainWindow hérite de tous les mixins et de QtWidgets.QMainWindow + Ui_MainWindow:

class MainWindow(
    QtWidgets.QMainWindow,
    Ui_MainWindow,
    InitializationMixin,
    TidalSessionMixin,
    SignalsMixin,
    ProgressMixin,
    UIHelpersMixin,
    TrackExtrasMixin,
    UpdatesMixin,
    DownloadsMixin,
    TreesResultsMixin,
    ContextMenusMixin,
    HistoryMixin,
):
    ...

Compatibilité

Le fichier gui.py original est maintenu comme point de compatibilité :

• Redirige les imports vers tidal_dl_ng.gui
• Conserve les directives de compilation nuitka
• Permet une migration progressive

Avantages de cette architecture

1. Maintenabilité : Chaque mixin a une responsabilité claire et limitée
2. Lisibilité : Fichiers plus petits et focalisés (100-300 lignes vs 1837)
3. Testabilité : Les mixins peuvent être testés individuellement
4. Extensibilité : Facile d'ajouter de nouvelles fonctionnalités
5. Réutilisabilité : Les mixins peuvent être réutilisés si nécessaire
6. Organisation : Structure logique par fonctionnalité

Migration

Pour utiliser la nouvelle structure :

# Ancienne méthode (toujours supportée)
from tidal_dl_ng.gui import gui_activate

# Nouvelle méthode recommandée
from tidal_dl_ng.gui import MainWindow
from tidal_dl_ng.gui.activate import gui_activate

Notes

• Les avertissements IDE sur les "unresolved attributes" dans les mixins sont normaux
• Les mixins accèdent à self qui sera fourni par MainWindow via l'héritage multiple
• L'ordre des mixins dans l'héritage est important pour la résolution de méthode (MRO)