diff options
Diffstat (limited to 'docs/playlist_api_architecture.md')
| -rw-r--r-- | docs/playlist_api_architecture.md | 93 |
1 files changed, 93 insertions, 0 deletions
diff --git a/docs/playlist_api_architecture.md b/docs/playlist_api_architecture.md new file mode 100644 index 0000000..d6d601f --- /dev/null +++ b/docs/playlist_api_architecture.md @@ -0,0 +1,93 @@ +# Architecture des appels API pour les playlists + +## Vue d'ensemble + +Tous les appels API liés aux playlists ont été centralisés dans un seul module pour une meilleure maintenabilité et cohérence. + +## Fichier centralisé : `tidal_dl_ng/helper/playlist_api.py` + +Ce module contient toutes les fonctions d'interaction avec l'API Tidal pour les playlists : + +### Fonctions disponibles + +#### 1. `get_user_playlists(session: Session) -> list[UserPlaylist]` +- **Description**: Récupère toutes les playlists de l'utilisateur +- **Paramètres**: Session Tidal authentifiée +- **Retour**: Liste d'objets UserPlaylist +- **Exceptions**: RequestException, ValueError + +#### 2. `get_playlist_items(playlist: UserPlaylist) -> list[Track]` +- **Description**: Récupère tous les morceaux d'une playlist +- **Paramètres**: Objet UserPlaylist +- **Retour**: Liste d'objets Track +- **Exceptions**: RequestException + +#### 3. `add_track_to_playlist(session: Session, playlist_id: str, track_id: str) -> None` +- **Description**: Ajoute un morceau à une playlist +- **Paramètres**: + - session: Session Tidal + - playlist_id: UUID de la playlist + - track_id: UUID du morceau +- **Exceptions**: RequestException, ValueError + +#### 4. `remove_track_from_playlist(session: Session, playlist_id: str, track_id: str) -> None` +- **Description**: Retire un morceau d'une playlist +- **Paramètres**: + - session: Session Tidal + - playlist_id: UUID de la playlist + - track_id: UUID du morceau +- **Exceptions**: RequestException, ValueError +- **Note**: Gère automatiquement la recherche de l'index du morceau + +#### 5. `get_playlist_metadata(playlist: UserPlaylist) -> dict[str, str | int]` +- **Description**: Extrait les métadonnées d'une playlist +- **Paramètres**: Objet UserPlaylist +- **Retour**: Dictionnaire avec `name`, `item_count`, `id` + +## Modules utilisant l'API centralisée + +### 1. `tidal_dl_ng/gui/dialog_playlist_manager.py` +Utilise : +- `add_track_to_playlist()` - Pour ajouter des morceaux via l'interface +- `remove_track_from_playlist()` - Pour retirer des morceaux via l'interface + +### 2. `tidal_dl_ng/gui/playlist_membership.py` +Utilise : +- `get_user_playlists()` - Pour charger les playlists au démarrage +- `get_playlist_items()` - Pour construire le cache de memberships +- `get_playlist_metadata()` - Pour afficher les noms et comptes + +## Avantages de cette architecture + +1. **Maintenabilité** : Un seul endroit pour modifier la logique API +2. **Cohérence** : Même gestion d'erreurs partout +3. **Testabilité** : Facile de mocker les fonctions API +4. **Logging centralisé** : Tous les logs API au même endroit +5. **Évolutivité** : Facile d'ajouter de nouvelles fonctions + +## Gestion des erreurs + +Toutes les fonctions : +- Loggent les erreurs avec `logger_gui` +- Propagent les exceptions (RequestException) pour que l'appelant puisse gérer +- Gèrent automatiquement les cas limites (playlist vide, morceau non trouvé, etc.) + +## Exemple d'utilisation + +```python +from tidal_dl_ng.helper.playlist_api import add_track_to_playlist, get_user_playlists + +# Récupérer les playlists +playlists = get_user_playlists(session) + +# Ajouter un morceau +try: + add_track_to_playlist(session, playlist_id="abc123", track_id="def456") + print("Morceau ajouté avec succès") +except RequestException as e: + print(f"Erreur: {e}") +``` + +## Migration future + +Si besoin de passer à une autre bibliothèque API ou d'ajouter un cache HTTP, il suffit de modifier `playlist_api.py` sans toucher aux autres fichiers. |