pydantic docstrings

endpoints/karma.py

@@ -121,6 +121,7 @@ class Karma(FastAPI):
                                 data: Optional[ValidTopKarmaRequest] = None) -> JSONResponse:
         """
         Get top keywords for karma
+         - **n**: Number of top results to return (default: 10)
         """
 
         if not self.util.check_key(request.url.path, request.headers.get('X-Authd-With')):
@@ -148,7 +149,10 @@ class Karma(FastAPI):
     
     async def get_karma_handler(self, data: ValidKarmaRetrievalRequest,
                                 request: Request) -> JSONResponse:
-        """Get current karma value"""
+        """
+        Get current karma value
+        - **keyword**: Keyword to retrieve karma value for
+        """
         
         if not self.util.check_key(request.url.path, request.headers.get('X-Authd-With')):
             raise HTTPException(status_code=403, detail="Unauthorized")        
@@ -169,7 +173,12 @@ class Karma(FastAPI):
     
     async def modify_karma_handler(self, data: ValidKarmaUpdateRequest,
                                    request: Request) -> JSONResponse:
-        """Update karma count"""
+        """
+        Update karma count
+        - **granter**: User who granted the karma
+        - **keyword**: The keyword to modify
+        - **flag**: 0 to decrement (--), 1 to increment (++) 
+        """
 
         if not self.util.check_key(request.url.path, request.headers.get('X-Authd-With'), 2):
             raise HTTPException(status_code=403, detail="Unauthorized")

endpoints/lyric_search.py

@@ -82,6 +82,7 @@ class LyricSearch(FastAPI):
     async def artist_typeahead_handler(self, data: ValidTypeAheadRequest) -> JSONResponse:
         """
         Artist Type Ahead Handler
+        - **query**: The query
         """
         if not isinstance(data.query, str) or len(data.query) < 2:
             return JSONResponse(status_code=500, content={
@@ -96,6 +97,8 @@ class LyricSearch(FastAPI):
     async def song_typeahead_handler(self, data: ValidTypeAheadRequest) -> JSONResponse:
         """
         Song Type Ahead Handler
+        - **query**: The query
+        - **pre_query**: The pre-query (artist)
         """
         if not isinstance(data.pre_query, str)\
             or not isinstance(data.query, str):

endpoints/misc.py

@@ -10,7 +10,9 @@ import redis.asyncio as redis
 from lyric_search.sources import private, cache as LyricsCache, redis_cache
 
 class Misc(FastAPI):
-    """Misc Endpoints"""
+    """
+    Misc Endpoints
+    """
     def __init__(self, app: FastAPI, my_util,
                  constants, radio) -> None:  # pylint: disable=super-init-not-called
         self.app: FastAPI = app
@@ -47,8 +49,9 @@ class Misc(FastAPI):
         
             
     async def homepage_redis_widget(self) -> JSONResponse:
-        """Homepage Redis Widget Handler"""
+        """
-        
+        Homepage Redis Widget Handler
+        """
         # Measure response time w/ test lyric search
         time_start: float = time.time() # Start time for response_time
         test_lyrics_result = await self.redis_client.ft().search("@artist: test @song: test")
@@ -68,8 +71,9 @@ class Misc(FastAPI):
         })
         
     async def homepage_sqlite_widget(self) -> JSONResponse:
-        """Homepage SQLite Widget Handler"""
+        """
-                
+        Homepage SQLite Widget Handler
+        """        
         row_count: int = await self.lyr_cache.sqlite_rowcount()
         distinct_artists: int = await self.lyr_cache.sqlite_distinct("artist")
         lyrics_length: int = await self.lyr_cache.sqlite_lyrics_length()
@@ -80,7 +84,9 @@ class Misc(FastAPI):
         })
         
     async def homepage_lyrics_widget(self) -> dict:
-        """Homepage Lyrics Widget Handler"""
+        """
+        Homepage Lyrics Widget Handler
+        """
         found_counts: dict = await self.redis_cache.get_found_counts()
         if not isinstance(found_counts, dict):
             return {
@@ -90,7 +96,9 @@ class Misc(FastAPI):
         return found_counts
     
     async def homepage_radio_widget(self) -> JSONResponse:
-        """Homepage Radio Widget Handler"""
+        """
+        Homepage Radio Widget Handler
+        """
         radio_np: str = await self.get_radio_np()
         if not radio_np:
             return JSONResponse(status_code=500, content={

endpoints/radio.py

@@ -55,6 +55,8 @@ class Radio(FastAPI):
                          request: Request) -> JSONResponse:
         """
         Skip to the next track in the queue, or to uuid specified in skipTo if provided
+        - **key**: API key
+        - **skipTo**: Optional UUID to skip to
         """
         try:
             if not self.util.check_key(path=request.url.path, req_type=4, key=data.key):
@@ -86,6 +88,7 @@ class Radio(FastAPI):
                               request: Request) -> JSONResponse:
         """
         Reshuffle the play queue
+        - **key**: API key
         """
         if not self.util.check_key(path=request.url.path, req_type=4, key=data.key):
             raise HTTPException(status_code=403, detail="Unauthorized")
@@ -100,6 +103,7 @@ class Radio(FastAPI):
                               limit: Optional[int] = 15_000) -> JSONResponse:
         """
         Get current play queue, up to limit [default: 15k]
+        - **limit**: Number of queue items to return, default 15k
         """
         queue_out: list[dict] = []
         for x, item in enumerate(self.radio_util.active_playlist[0:limit]):
@@ -121,6 +125,9 @@ class Radio(FastAPI):
         """
         Shift position of a UUID within the queue
         [currently limited to playing next or immediately]
+        - **key**: API key
+        - **uuid**: UUID to shift
+        - **next**: Play track next? If False, skips to the track
         """
         if not self.util.check_key(path=request.url.path, req_type=4, key=data.key):
             raise HTTPException(status_code=403, detail="Unauthorized")
@@ -144,6 +151,8 @@ class Radio(FastAPI):
                                  request: Request) -> JSONResponse:
         """
         Remove an item from the current play queue
+        - **key**: API key
+        - **uuid**: UUID of queue item to remove
         """
         if not self.util.check_key(path=request.url.path, req_type=4, key=data.key):
             raise HTTPException(status_code=403, detail="Unauthorized")
@@ -163,6 +172,7 @@ class Radio(FastAPI):
         """
         Get album art, optional parameter track_id may be specified.
         Otherwise, current track album art will be pulled.
+        - **track_id**: Optional, if provided, will attempt to retrieve the album art of this track_id. Current track used otherwise.
         """
         try:
             if not track_id:
@@ -198,6 +208,8 @@ class Radio(FastAPI):
         """
         Get next track
         Track will be removed from the queue in the process.
+        - **key**: API key
+        - **skipTo**: Optional UUID to skip to
         """
         if not self.util.check_key(path=request.url.path, req_type=4, key=data.key):
                 raise HTTPException(status_code=403, detail="Unauthorized")
@@ -250,6 +262,11 @@ class Radio(FastAPI):
     async def radio_request(self, data: ValidRadioSongRequest, request: Request) -> JSONResponse:
         """
         Song request handler
+        - **key**: API key
+        - **artist**: Artist to search
+        - **song**: Song to search
+        - **artistsong**: Optional "Artist - Song" pair to search, in place of artist/song
+        - **alsoSkip**: If True, skips to the track; otherwise, track will be placed next up in queue
         """
         if not self.util.check_key(path=request.url.path, req_type=4, key=data.key):
                 raise HTTPException(status_code=403, detail="Unauthorized")

endpoints/rand_msg.py

@@ -24,6 +24,7 @@ class RandMsg(FastAPI):
     async def randmsg_handler(self, data: RandMsgRequest) -> JSONResponse:
         """
         Get a randomly generated message
+        - **short**: Optional, if True, will limit length of returned random messages to <=126 characters (Discord restriction related)
         """
         random.seed()
         short: bool = data.short if data.short else False

endpoints/transcriptions.py

@@ -29,6 +29,7 @@ class Transcriptions(FastAPI):
     async def get_episodes_handler(self, data: ValidShowEpisodeListRequest) -> JSONResponse:
         """
         Get list of episodes by show id
+        - **s**: Show ID to query
         """
         show_id: int = data.s
         db_path: Optional[Union[str, LiteralString]] = None
@@ -86,6 +87,8 @@ class Transcriptions(FastAPI):
     async def get_episode_lines_handler(self, data: ValidShowEpisodeLineRequest) -> JSONResponse:
         """
         Get lines for a particular episode
+        - **s**: Show ID to query
+        - **e**: Episode ID to query
         """
         show_id: int = int(data.s)
         episode_id: int = int(data.e)
@@ -124,5 +127,4 @@ class Transcriptions(FastAPI):
                             'speaker': item[1].strip(),
                             'line': item[2].strip(),
                             } for item in result],
-                })
+                })
-