api/endpoints/constructors.py

#!/usr/bin/env python3.12

from typing import Optional
from pydantic import BaseModel

# Constructors
# TODO: REORDER

"""
AI
"""

class ValidAISongRequest(BaseModel):
    """
    - **a**: artist
    - **s**: track title
    """
    
    a: str
    s: str
    
class ValidHookSongRequest(BaseModel):
    """
    - **a**: artist
    - **s**: track title
    - **hook**: hook to return
    """

    a: str
    s: str
    hook: str | None = ""    

"""
Karma
"""

class ValidKarmaUpdateRequest(BaseModel):
    """
    Requires authentication
    - **granter**: who updated the karma
    - **keyword**: keyword to update karma for
    - **flag**: either 0 (decrement) for --, or 1 (increment) for ++
    """

    granter: str
    keyword: str
    flag: int


class ValidKarmaRetrievalRequest(BaseModel):
    """
    - **keyword**: keyword to retrieve karma value of
    """

    keyword: str

class ValidTopKarmaRequest(BaseModel):
    """
    - **n**: Number of top results to return (default: 10)
    """
    n: int | None = 10

"""
LastFM
"""

class ValidArtistSearchRequest(BaseModel):
    """
    - **a**: artist name
    """

    a: str
    
    class Config: # pylint: disable=missing-class-docstring
        schema_extra = {
             "example": {
                  "a": "eminem"
                  }
                }    

class ValidAlbumDetailRequest(BaseModel):
    """
    - **a**: artist name
    - **a2**: album/release name (as sourced from here/LastFM)
    """

    a: str
    a2: str

    class Config: # pylint: disable=missing-class-docstring
        schema_extra = {
            "example": {
                "a": "eminem",
                "a2": "houdini"
                }
            }
                
class ValidTrackInfoRequest(BaseModel):
    """
    - **a**: artist name
    - **t**: track
    """

    a: str
    t: str

    class Config: # pylint: disable=missing-class-docstring
        schema_extra = {
            "example": {
                "a": "eminem",
                "t": "rap god"
                }
            }

"""
Rand Msg
"""

class RandMsgRequest(BaseModel):
    """
    - **short**: Short randmsg?
    """

    short: Optional[bool] = False

"""
YT
"""

class ValidYTSearchRequest(BaseModel):
    """
    - **t**: title to search
    """

    t: str = "rick astley - never gonna give you up"

"""
XC
"""

class ValidXCRequest(BaseModel):
    """
    - **key**: valid XC API key
    - **bid**: bot id
    - **cmd**: bot command
    - **data**: command data
    """

    key: str
    bid: int
    cmd: str
    data: dict | None = None 

"""
Transcriptions
"""

class ValidShowEpisodeListRequest(BaseModel):
    """
    - **s**: show id
    """

    s: int

class ValidShowEpisodeLineRequest(BaseModel):
    """
    - **s**: show id
    - **e**: episode id
    """

    s: int
    e: int

"""
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)
    """

    a: str | None = None
    s: str | None = None 
    t: str | None = None
    sub: str | None = None
    extra: bool | None = False
    lrc: bool | None = False
    src: str
    excluded_sources: list | None = None

    model_config = {
        "json_schema_extra": {
                "examples": [
                    {
                        "a": "eminem",
                        "s": "rap god",
                        "src": "WEB",
                        "extra": True,
                        "lrc": False,
                        "excluded_sources": [],
                    }]
            }
        }

        
class ValidTypeAheadRequest(BaseModel):
    """
    - **query**: query string
    """
    pre_query: str|None = None
    query: str

"""
Radio
"""

class RadioException(Exception):
    pass

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]
    """
    key: str
    artist: str | None = None
    song: str | None = None
    artistsong: str | None = None
    alsoSkip: bool = False
    
class ValidRadioNextRequest(BaseModel):
    """
    - **key**: API Key
    - **skipTo**: UUID to skip to [optional]
    """
    key: str
    skipTo: str|None = None
    
class ValidRadioReshuffleRequest(ValidRadioNextRequest):
    """
    - **key**: API Key
    """
    
class ValidRadioQueueShiftRequest(BaseModel):
    """
    - **key**: API Key
    - **uuid**: UUID to shift 
    - **next**: Play next if true, immediately if false, default False
    """
    key: str
    uuid: str
    next: bool = False
    
class ValidRadioQueueRemovalRequest(BaseModel):
    """
    - **key**: API Key
    - **uuid**: UUID to remove 
    """
    key: str
    uuid: str