From f47ea0665fbe284d79be937a9efbbc824120153a Mon Sep 17 00:00:00 2001 From: codey Date: Sun, 16 Feb 2025 08:17:27 -0500 Subject: [PATCH] pydantic docstrings --- endpoints/karma.py | 13 +++++++++++-- endpoints/lyric_search.py | 3 +++ endpoints/misc.py | 22 +++++++++++++++------- endpoints/radio.py | 17 +++++++++++++++++ endpoints/rand_msg.py | 1 + endpoints/transcriptions.py | 6 ++++-- 6 files changed, 51 insertions(+), 11 deletions(-) diff --git a/endpoints/karma.py b/endpoints/karma.py index 8291716..15986d4 100644 --- a/endpoints/karma.py +++ b/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") diff --git a/endpoints/lyric_search.py b/endpoints/lyric_search.py index ae1e301..02293e4 100644 --- a/endpoints/lyric_search.py +++ b/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): diff --git a/endpoints/misc.py b/endpoints/misc.py index ea74262..bd1eb82 100644 --- a/endpoints/misc.py +++ b/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={ diff --git a/endpoints/radio.py b/endpoints/radio.py index 2a45a29..9f8678d 100644 --- a/endpoints/radio.py +++ b/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") diff --git a/endpoints/rand_msg.py b/endpoints/rand_msg.py index 97c8008..d1aa7c0 100644 --- a/endpoints/rand_msg.py +++ b/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 diff --git a/endpoints/transcriptions.py b/endpoints/transcriptions.py index d6a45a9..4b5c762 100644 --- a/endpoints/transcriptions.py +++ b/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], - }) - \ No newline at end of file + }) \ No newline at end of file