docstrings / formatting

endpoints/rip.py

@@ -33,6 +33,7 @@ class RIP(FastAPI):
     """
 
     def __init__(self, app: FastAPI, my_util, constants) -> None:
+        """Initialize RIP endpoints."""
         self.app: FastAPI = app
         self.util = my_util
         self.trip_util = SRUtil()
@@ -72,7 +73,15 @@ class RIP(FastAPI):
             )
 
     def _format_job(self, job: Job):
-        """Helper to normalize job data into JSON."""
+        """
+        Helper to normalize job data into JSON.
+
+        Parameters:
+        - job (Job): The job object to format.
+
+        Returns:
+        - dict: Contains normalized job data.
+        """
         job_status: str | JobStatus = job.get_status()
         progress = job.meta.get("progress", 0)
         if progress == 100 and not job.meta.get("tarball"):
@@ -82,7 +91,13 @@ class RIP(FastAPI):
         tracks_out = len(job.meta.get("tracks", []))
         # `utils/rip_background.py` sets per-track status to 'Success' or 'Failed'
         # so check for 'success' case-insensitively and count matches.
-        succeeded_tracks = len([t for t in job.meta.get("tracks", []) if str(t.get("status", "")).lower() == "success"])
+        succeeded_tracks = len(
+            [
+                t
+                for t in job.meta.get("tracks", [])
+                if str(t.get("status", "")).lower() == "success"
+            ]
+        )
 
         return {
             "id": job.id,
@@ -103,10 +118,20 @@ class RIP(FastAPI):
     async def artists_by_name_handler(
         self, artist: str, request: Request, user=Depends(get_current_user)
     ) -> Response:
-        """Get artists by name"""
+        """
+        Get artists by name.
+
+        Parameters:
+        - **artist** (str): Artist name.
+        - **request** (Request): The request object.
+        - **user**: Current user (dependency).
+
+        Returns:
+        - **Response**: JSON response with artists or 404.
+        """
         # support optional grouping to return one primary per display name
         # with `alternatives` for disambiguation (use ?group=true)
-        group = bool(request.query_params.get("group", False)) 
+        group = bool(request.query_params.get("group", False))
         artists = await self.trip_util.get_artists_by_name(artist, group=group)
         if not artists:
             return Response(status_code=404, content="Not found")
@@ -115,7 +140,17 @@ class RIP(FastAPI):
     async def albums_by_artist_id_handler(
         self, artist_id: int, request: Request, user=Depends(get_current_user)
     ) -> Response:
-        """Get albums by artist ID"""
+        """
+        Get albums by artist ID.
+
+        Parameters:
+        - **artist_id** (int): Artist ID.
+        - **request** (Request): The request object.
+        - **user**: Current user (dependency).
+
+        Returns:
+        - **Response**: JSON response with albums or 404.
+        """
         albums = await self.trip_util.get_albums_by_artist_id(artist_id)
         if not albums:
             return Response(status_code=404, content="Not found")
@@ -128,7 +163,18 @@ class RIP(FastAPI):
         user=Depends(get_current_user),
         quality: Literal["FLAC", "Lossy"] = "FLAC",
     ) -> Response:
-        """Get tracks by album id"""
+        """
+        Get tracks by album ID.
+
+        Parameters:
+        - **album_id** (int): Album ID.
+        - **request** (Request): The request object.
+        - **quality** (Literal): Track quality ("FLAC" or "Lossy").
+        - **user**: Current user (dependency).
+
+        Returns:
+        - **Response**: JSON response with tracks or 404.
+        """
         tracks = await self.trip_util.get_tracks_by_album_id(album_id, quality)
         if not tracks:
             return Response(status_code=404, content="Not Found")
@@ -137,7 +183,18 @@ class RIP(FastAPI):
     async def tracks_by_artist_song_handler(
         self, artist: str, song: str, request: Request, user=Depends(get_current_user)
     ) -> Response:
-        """Get tracks by artist and song name"""
+        """
+        Get tracks by artist and song name.
+
+        Parameters:
+        - **artist** (str): Artist name.
+        - **song** (str): Song name.
+        - **request** (Request): The request object.
+        - **user**: Current user (dependency).
+
+        Returns:
+        - **Response**: JSON response with tracks or 404.
+        """
         logging.critical("Searching for tracks by artist: %s, song: %s", artist, song)
         tracks = await self.trip_util.get_tracks_by_artist_song(artist, song)
         if not tracks:
@@ -151,7 +208,18 @@ class RIP(FastAPI):
         quality: Literal["FLAC", "Lossy"] = "FLAC",
         user=Depends(get_current_user),
     ) -> Response:
-        """Get track by ID"""
+        """
+        Get track by ID.
+
+        Parameters:
+        - **track_id** (int): Track ID.
+        - **request** (Request): The request object.
+        - **quality** (Literal): Track quality ("FLAC" or "Lossy").
+        - **user**: Current user (dependency).
+
+        Returns:
+        - **Response**: JSON response with stream URL or 404.
+        """
         track = await self.trip_util.get_stream_url_by_track_id(track_id, quality)
         if not track:
             return Response(status_code=404, content="Not found")
@@ -163,7 +231,17 @@ class RIP(FastAPI):
         request: Request,
         user=Depends(get_current_user),
     ) -> Response:
-        """Bulk fetch a list of track IDs"""
+        """
+        Bulk fetch a list of track IDs.
+
+        Parameters:
+        - **data** (ValidBulkFetchRequest): Bulk fetch request data.
+        - **request** (Request): The request object.
+        - **user**: Current user (dependency).
+
+        Returns:
+        - **Response**: JSON response with job info or error.
+        """
         if not data or not data.track_ids or not data.target:
             return JSONResponse(
                 content={
@@ -204,7 +282,17 @@ class RIP(FastAPI):
     async def job_status_handler(
         self, job_id: str, request: Request, user=Depends(get_current_user)
     ):
-        """Get status and result of a single job"""
+        """
+        Get status and result of a single job.
+
+        Parameters:
+        - **job_id** (str): Job ID.
+        - **request** (Request): The request object.
+        - **user**: Current user (dependency).
+
+        Returns:
+        - **JSONResponse**: Job status and result or error.
+        """
 
         job = None
         try:
@@ -233,7 +321,16 @@ class RIP(FastAPI):
         return self._format_job(job)
 
     async def job_list_handler(self, request: Request, user=Depends(get_current_user)):
-        """List all jobs across all registries (queued, started, finished, failed, etc)."""
+        """
+        List all jobs across all registries.
+
+        Parameters:
+        - **request** (Request): The request object.
+        - **user**: Current user (dependency).
+
+        Returns:
+        - **JSONResponse**: List of jobs.
+        """
         jobs_info = []
         seen = set()