docs: Update docstrings to reflect Show in Explorer changes

Author: Rikrdoga

tidal_dl_ng/download.py

@@ -1012,7 +1012,7 @@ def _perform_post_processing(
 
         Args:
             media (Track | Video): Media item.
-            path_media_dst (pathlib.Path): Destination file path.
+            path_media_src (pathlib.Path): Source file path.
             quality_audio (Quality | None): Audio quality setting.
             quality_video (QualityVideo | None): Video quality setting.
             quality_audio_old (Quality | None): Previous audio quality.

tidal_dl_ng/gui.py

@@ -2265,18 +2265,18 @@ def on_queue_download(
         quality_audio: Quality | None = None,
         quality_video: QualityVideo | None = None,
     ) -> tuple[QueueDownloadStatus, pathlib.Path]:
-        """Download media item(s) and return status and path.
+        """Download the specified media item(s) and return the result status and path.
 
         Args:
-            media: The TIDAL media object to download.
-            quality_audio: Desired audio quality for the download.
-            quality_video: Desired video quality for the download.
+            media (Track | Album | Playlist | Video | Mix | Artist): The media item(s) to download.
+            quality_audio (Quality | None, optional): Desired audio quality. Defaults to None.
+            quality_video (QualityVideo | None, optional): Desired video quality. Defaults to None.
 
         Returns:
-            Tuple of (download status, path to downloaded file/directory).
-            For Artists, returns the artist's root directory.
-            For Albums/Playlists, returns the album/playlist directory.
-            For Tracks/Videos, returns the file path.
+            tuple[QueueDownloadStatus, pathlib.Path]: Tuple of (download status, path to downloaded file/directory).
+                For Artists, returns the artist's root directory.
+                For Albums/Playlists, returns the album/playlist directory.
+                For Tracks/Videos, returns the file path.
         """
         result_status: QueueDownloadStatus
         path_file: pathlib.Path = pathlib.Path()
@@ -2328,17 +2328,17 @@ def download(
         quality_audio: Quality | None = None,
         quality_video: QualityVideo | None = None,
     ) -> tuple[QueueDownloadStatus, pathlib.Path | str]:
-        """Download a media item and return the result status.
+        """Download a media item and return the result status and path.
 
         Args:
-            media: The media item to download.
-            dl: The Download object to use.
-            delay_track: Whether to apply download delay.
-            quality_audio: Desired audio quality.
-            quality_video: Desired video quality.
+            media (Track | Album | Playlist | Video | Mix | Artist): The media item to download.
+            dl (Download): The Download object to use.
+            delay_track (bool, optional): Whether to apply download delay. Defaults to False.
+            quality_audio (Quality | None, optional): Desired audio quality. Defaults to None.
+            quality_video (QualityVideo | None, optional): Desired video quality. Defaults to None.
 
         Returns:
-            (QueueDownloadStatus, path_file): The status and the final file path.
+            tuple[QueueDownloadStatus, pathlib.Path | str]: The status and the final file path.
         """
         result_dl: bool
         path_file: str | pathlib.Path = ""
@@ -2505,7 +2505,11 @@ def on_download_album_from_track(self, point: QtCore.QPoint) -> None:
             logger_gui.warning("Could not retrieve album information from the selected track.")
 
     def on_show_in_explorer(self, path: pathlib.Path | None) -> None:
-        """Open the containing folder and (when possible) select/reveal the file in the OS file manager."""
+        """Open the containing folder and (when possible) select/reveal the file in the OS file manager.
+
+        Args:
+            path: Path to the file or directory to show in explorer.
+        """
         if not path:
             logger_gui.error("Attempted to show in explorer but no path was provided")
             return
@@ -2517,15 +2521,26 @@ def on_show_in_explorer(self, path: pathlib.Path | None) -> None:
         self._open_in_file_manager(resolved_path)
 
     def _resolve_path(self, path: pathlib.Path) -> pathlib.Path | None:
-        """Expand and resolve path, log errors if invalid."""
+        """Expand and resolve path, log errors if invalid.
+
+        Args:
+            path: The path to resolve.
+
+        Returns:
+            The resolved path, or None if invalid.
+        """
         try:
             return path.expanduser().resolve()
         except (OSError, RuntimeError) as e:
             logger_gui.error(f"Invalid path cannot be resolved: {path!s} → {e}")
             return None
 
     def _open_in_file_manager(self, path: pathlib.Path) -> None:
-        """Open path in system file manager with platform-specific command."""
+        """Open path in system file manager with platform-specific command.
+
+        Args:
+            path: The resolved path to open.
+        """
         try:
             if sys.platform == "win32":
                 self._open_windows(path)
@@ -2537,14 +2552,29 @@ def _open_in_file_manager(self, path: pathlib.Path) -> None:
             logger_gui.exception(f"Unexpected error opening file manager for {path}")
 
     def _open_windows(self, path: pathlib.Path) -> None:
+        """Open path in Windows Explorer.
+
+        Args:
+            path: The path to open.
+        """
         cmd = ["explorer", "/select,", str(path)] if path.is_file() else ["explorer", str(path)]
         subprocess.Popen(cmd, shell=True)  # noqa: S602  # Required for /select, on Windows; path is trusted
 
     def _open_macos(self, path: pathlib.Path) -> None:
+        """Open path in macOS Finder.
+
+        Args:
+            path: The path to open.
+        """
         cmd = ["open", "-R", str(path)] if path.is_file() else ["open", str(path)]
         subprocess.run(cmd, check=True)  # noqa: S603  # `open` is trusted system command
 
     def _open_linux(self, path: pathlib.Path) -> None:
+        """Open path in Linux file manager.
+
+        Args:
+            path: The path to open.
+        """
         target = path.parent if path.is_file() else path
         subprocess.run(["xdg-open", str(target)], check=True)  # noqa: S603, S607 # `xdg-open` is trusted system utility
 

tidal_dl_ng/model/gui_data.py

@@ -44,6 +44,18 @@ class StatusbarMessage:
 
 @dataclass
 class QueueDownloadItem:
+    """Download queue item model.
+
+    Attributes:
+        status (str): Current download status.
+        name (str): Display name of the media item.
+        type_media (str): Type of media (Track, Album, etc).
+        quality_audio (Quality): Audio quality setting.
+        quality_video (QualityVideo): Video quality setting.
+        obj (object): The actual media object.
+        file_path (pathlib.Path | None): Path to downloaded file/directory (thread-safe property).
+    """
+
     status: str
     name: str
     type_media: str
@@ -55,12 +67,20 @@ class QueueDownloadItem:
 
     @property
     def file_path(self) -> pathlib.Path | None:
-        """Get the downloaded file path (thread-safe)."""
+        """Get the downloaded file path (thread-safe).
+
+        Returns:
+            pathlib.Path | None: Path to the downloaded file or directory, or None if not yet set.
+        """
         with self._lock:
             return self._file_path
 
     @file_path.setter
     def file_path(self, path: pathlib.Path | None) -> None:
-        """Set the downloaded file path (thread-safe)."""
+        """Set the downloaded file path (thread-safe).
+
+        Args:
+            path (pathlib.Path | None): Path to the downloaded file or directory.
+        """
         with self._lock:
             self._file_path = path