docstrings / formatting

endpoints/constructors.py

@@ -15,7 +15,10 @@ class LastFMException(Exception):
 
 class ValidArtistSearchRequest(BaseModel):
     """
-    - **a**: artist name
+    Request model for searching an artist by name.
+
+    Attributes:
+    - **a** (str): Artist name.
     """
 
     a: str
@@ -33,8 +36,11 @@ class ValidArtistSearchRequest(BaseModel):
 
 class ValidAlbumDetailRequest(BaseModel):
     """
-    - **a**: artist name
-    - **release**: album/release name (as sourced from here/LastFM)
+    Request model for album details.
+
+    Attributes:
+    - **a** (str): Artist name.
+    - **release** (str): Album/release name.
     """
 
     a: str
@@ -54,8 +60,11 @@ class ValidAlbumDetailRequest(BaseModel):
 
 class ValidTrackInfoRequest(BaseModel):
     """
-    - **a**: artist name
-    - **t**: track
+    Request model for track info.
+
+    Attributes:
+    - **a** (str): Artist name.
+    - **t** (str): Track name.
     """
 
     a: str
@@ -80,7 +89,10 @@ Rand Msg
 
 class RandMsgRequest(BaseModel):
     """
-    - **short**: Short randmsg?
+    Request model for random message.
+
+    Attributes:
+    - **short** (Optional[bool]): Short randmsg?
     """
 
     short: Optional[bool] = False
@@ -93,7 +105,10 @@ YT
 
 class ValidYTSearchRequest(BaseModel):
     """
-    - **t**: title to search
+    Request model for YouTube search.
+
+    Attributes:
+    - **t** (str): Title to search.
     """
 
     t: str = "rick astley - never gonna give you up"
@@ -106,7 +121,10 @@ Transcriptions
 
 class ValidShowEpisodeListRequest(BaseModel):
     """
-    - **s**: show id
+    Request model for show episode list.
+
+    Attributes:
+    - **s** (int): Show ID.
     """
 
     s: int
@@ -114,8 +132,11 @@ class ValidShowEpisodeListRequest(BaseModel):
 
 class ValidShowEpisodeLineRequest(BaseModel):
     """
-    - **s**: show id
-    - **e**: episode id
+    Request model for show episode lines.
+
+    Attributes:
+    - **s** (int): Show ID.
+    - **e** (int): Episode ID.
     """
 
     s: int
@@ -129,14 +150,17 @@ Lyric Search
 
 class ValidLyricRequest(BaseModel):
     """
-    - **a**: artist
-    - **s**: song
-    - **t**: track (artist and song combined) [used only if a & s are not used]
-    - **extra**: include extra details in response [optional, default: false]
-    - **lrc**: Request LRCs?
-    - **sub**: text to search within lyrics, if found lyrics will begin at found verse [optional]
-    - **src**: the script/utility which initiated the request
-    - **excluded_sources**: sources to exclude (new only)
+    Request model for lyric search.
+
+    Attributes:
+    - **a** (Optional[str]): Artist.
+    - **s** (Optional[str]): Song.
+    - **t** (Optional[str]): Track (artist and song combined).
+    - **extra** (Optional[bool]): Include extra details in response.
+    - **lrc** (Optional[bool]): Request LRCs?
+    - **sub** (Optional[str]): Text to search within lyrics.
+    - **src** (str): The script/utility which initiated the request.
+    - **excluded_sources** (Optional[list]): Sources to exclude.
     """
 
     a: Optional[str] = None
@@ -166,7 +190,10 @@ class ValidLyricRequest(BaseModel):
 
 class ValidTypeAheadRequest(BaseModel):
     """
-    - **query**: query string
+    Request model for typeahead query.
+
+    Attributes:
+    - **query** (str): Query string.
     """
 
     query: str
@@ -183,11 +210,15 @@ class RadioException(Exception):
 
 class ValidRadioSongRequest(BaseModel):
     """
-    - **key**: API Key
-    - **artist**: artist to search
-    - **song**: song to search
-    - **artistsong**: may be used IN PLACE OF artist/song to perform a combined/string search in the format "artist - song"
-    - **alsoSkip**: Whether to skip immediately to this track [not implemented]
+    Request model for radio song request.
+
+    Attributes:
+    - **key** (str): API Key.
+    - **artist** (Optional[str]): Artist to search.
+    - **song** (Optional[str]): Song to search.
+    - **artistsong** (Optional[str]): Combined artist-song string.
+    - **alsoSkip** (Optional[bool]): Whether to skip immediately to this track.
+    - **station** (Station): Station name.
     """
 
     key: str
@@ -200,7 +231,10 @@ class ValidRadioSongRequest(BaseModel):
 
 class ValidRadioTypeaheadRequest(BaseModel):
     """
-    - **query**: Typeahead query
+    Request model for radio typeahead.
+
+    Attributes:
+    - **query** (str): Typeahead query.
     """
 
     query: str
@@ -208,8 +242,11 @@ class ValidRadioTypeaheadRequest(BaseModel):
 
 class ValidRadioQueueGetRequest(BaseModel):
     """
-    - **key**: API key (optional, needed if specifying a non-default limit)
-    - **limit**: optional, default: 15k
+    Request model for radio queue get.
+
+    Attributes:
+    - **key** (Optional[str]): API key.
+    - **limit** (Optional[int]): Result limit.
     """
 
     key: Optional[str] = None
@@ -218,9 +255,12 @@ class ValidRadioQueueGetRequest(BaseModel):
 
 class ValidRadioNextRequest(BaseModel):
     """
-    - **key**: API Key
-    - **skipTo**: UUID to skip to [optional]
-    - **station**: Station (default: "main")
+    Request model for radio next track.
+
+    Attributes:
+    - **key** (str): API Key.
+    - **skipTo** (Optional[str]): UUID to skip to.
+    - **station** (Station): Station name.
     """
 
     key: str
@@ -230,17 +270,23 @@ class ValidRadioNextRequest(BaseModel):
 
 class ValidRadioReshuffleRequest(ValidRadioNextRequest):
     """
-    - **key**: API Key
-    - **station**: Station (default: "main")
+    Request model for radio reshuffle.
+
+    Attributes:
+    - **key** (str): API Key.
+    - **station** (Station): Station name.
     """
 
 
 class ValidRadioQueueRequest(BaseModel):
     """
-    - **draw**: DataTables draw count, default 1
-    - **start**: paging start position, default 0
-    - **search**: Optional search query
-    - **station**: Station (default: "main")
+    Request model for radio queue.
+
+    Attributes:
+    - **draw** (Optional[int]): DataTables draw count.
+    - **start** (Optional[int]): Paging start position.
+    - **search** (Optional[str]): Search query.
+    - **station** (Station): Station name.
     """
 
     draw: Optional[int] = 1
@@ -251,10 +297,13 @@ class ValidRadioQueueRequest(BaseModel):
 
 class ValidRadioQueueShiftRequest(BaseModel):
     """
-    - **key**: API Key
-    - **uuid**: UUID to shift
-    - **next**: Play next if true, immediately if false, default False
-    - **station**: Station (default: "main")
+    Request model for radio queue shift.
+
+    Attributes:
+    - **key** (str): API Key.
+    - **uuid** (str): UUID to shift.
+    - **next** (Optional[bool]): Play next if true.
+    - **station** (Station): Station name.
     """
 
     key: str
@@ -265,9 +314,12 @@ class ValidRadioQueueShiftRequest(BaseModel):
 
 class ValidRadioQueueRemovalRequest(BaseModel):
     """
-    - **key**: API Key
-    - **uuid**: UUID to remove
-    - **station**: Station (default: "main")
+    Request model for radio queue removal.
+
+    Attributes:
+    - **key** (str): API Key.
+    - **uuid** (str): UUID to remove.
+    - **station** (Station): Station name.
     """
 
     key: str