yutipy 1.0.0__py3-none-any.whl → 1.2.0__py3-none-any.whl

yutipy/exceptions.py

@@ -50,3 +50,7 @@ class InvalidResponseException(YutipyException):
     """Exception raised for invalid responses from APIs."""
 
     pass
+
+
+class KKBoxException(YutipyException):
+    """Exception raised for erros related to the KKBOX Open API."""

yutipy/kkbox.py

@@ -0,0 +1,373 @@
+import base64
+import os
+import time
+from pprint import pprint
+from typing import Optional, Union
+
+import requests
+from dotenv import load_dotenv
+
+from yutipy.exceptions import (
+    AuthenticationException,
+    InvalidResponseException,
+    InvalidValueException,
+    KKBoxException,
+    NetworkException,
+)
+from yutipy.models import MusicInfo
+from yutipy.utils.cheap_utils import are_strings_similar, is_valid_string
+
+load_dotenv()
+
+KKBOX_CLIENT_ID = os.getenv("KKBOX_CLIENT_ID")
+KKBOX_CLIENT_SECRET = os.getenv("KKBOX_CLIENT_SECRET")
+
+
+class KKBox:
+    """
+    A class to interact with KKBOX Open API.
+
+    This class reads the ``KKBOX_CLIENT_ID`` and ``KKBOX_CLIENT_SECRET`` from environment variables or the ``.env`` file by default.
+    Alternatively, you can manually provide these values when creating an object.
+    """
+
+    def __init__(
+        self, client_id: str = KKBOX_CLIENT_ID, client_secret: str = KKBOX_CLIENT_SECRET
+    ) -> None:
+        """
+        Initializes the KKBox class and sets up the session.
+
+        Parameters
+        ----------
+        client_id : str, optional
+            The Client ID for the KKBOX Open API. Defaults to ``KKBOX_CLIENT_ID`` from .env file.
+        client_secret : str, optional
+            The Client secret for the KKBOX Open API. Defaults to ``KKBOX_CLIENT_SECRET`` from .env file.
+        """
+        if not client_id or not client_secret:
+            raise KKBoxException(
+                "Failed to read `KKBOX_CLIENT_ID` and/or `KKBOX_CLIENT_SECRET` from environment variables. Client ID and Client Secret must be provided."
+            )
+
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self._session = requests.Session()
+        self.api_url = "https://api.kkbox.com/v1.1"
+        self.__header, self.__expires_in = self.__authenticate()
+        self.__start_time = time.time()
+        self._is_session_closed = False
+        self.valid_territories = ["HK", "JP", "MY", "SG", "TW"]
+
+    def __enter__(self):
+        """Enters the runtime context related to this object."""
+        return self
+
+    def __exit__(self, exc_type, exc_value, exc_traceback):
+        """Exits the runtime context related to this object."""
+        self._close_session()
+
+    def close_session(self) -> None:
+        """Closes the current session."""
+        if not self.is_session_closed:
+            self._session.close()
+            self._is_session_closed = True
+
+    @property
+    def is_session_closed(self) -> bool:
+        """Checks if the session is closed."""
+        return self._is_session_closed
+
+    def __authenticate(self) -> tuple:
+        """
+        Authenticates with the KKBOX Open API and returns the authorization header.
+
+        Returns
+        -------
+        dict
+            The authorization header.
+        """
+        try:
+            token, expires_in = self.__get_access_token()
+            return {"Authorization": f"Bearer {token}"}, expires_in
+        except Exception as e:
+            raise AuthenticationException(
+                "Failed to authenticate with KKBOX Open API"
+            ) from e
+
+    def __get_access_token(self) -> tuple:
+        """
+        Gets the KKBOX Open API token.
+
+        Returns
+        -------
+        str
+            The KKBOX Open API token.
+        """
+        auth_string = f"{self.client_id}:{self.client_secret}"
+        auth_base64 = base64.b64encode(auth_string.encode("utf-8")).decode("utf-8")
+
+        url = " https://account.kkbox.com/oauth2/token"
+        headers = {
+            "Authorization": f"Basic {auth_base64}",
+            "Content-Type": "application/x-www-form-urlencoded",
+        }
+        data = {"grant_type": "client_credentials"}
+
+        try:
+            response = self._session.post(
+                url=url, headers=headers, data=data, timeout=30
+            )
+            response.raise_for_status()
+        except requests.RequestException as e:
+            raise NetworkException(f"Network error occurred: {e}")
+
+        try:
+            response_json = response.json()
+            return response_json.get("access_token"), response_json.get("expires_in")
+        except (KeyError, ValueError) as e:
+            raise InvalidResponseException(f"Invalid response received: {e}")
+
+    def __refresh_token_if_expired(self):
+        """Refreshes the token if it has expired."""
+        if time.time() - self.__start_time >= self.__expires_in:
+            self.__header, self.__expires_in = self.__authenticate()
+            self.__start_time = time.time()
+
+    def search(
+        self, artist: str, song: str, territory: str = "TW"
+    ) -> Optional[MusicInfo]:
+        """
+        Searches for a song by artist and title.
+
+        Parameters
+        ----------
+        artist : str
+            The name of the artist.
+        song : str
+            The title of the song.
+        territory : str
+            Two-letter country codes from ISO 3166-1 alpha-2.
+            Allowed values: ``HK``, ``JP``, ``MY``, ``SG``, ``TW``.
+
+        Returns
+        -------
+        Optional[MusicInfo_]
+            The music information if found, otherwise None.
+        """
+        if not is_valid_string(artist) or not is_valid_string(song):
+            raise InvalidValueException(
+                "Artist and song names must be valid strings and can't be empty."
+            )
+
+        self.__refresh_token_if_expired()
+
+        query = f"?q={artist} - {song}&type=track,album&territory={territory}&limit=10"
+        query_url = f"{self.api_url}/search{query}"
+
+        try:
+            response = self._session.get(query_url, headers=self.__header, timeout=30)
+            response.raise_for_status()
+        except requests.RequestException as e:
+            raise NetworkException(f"Network error occurred: {e}")
+
+        if response.status_code != 200:
+            raise KKBoxException(f"Failed to search for music: {response.json()}")
+
+        return self._find_music_info(artist, song, response.json())
+
+    def get_html_widget(
+        self,
+        id: str,
+        content_type: str,
+        territory: str = "TW",
+        widget_lang: str = "EN",
+        autoplay: bool = False,
+        loop: bool = False,
+    ) -> str:
+        """
+        Return KKBOX HTML widget for "Playlist", "Album" or "Song". It does not return actual HTML code,
+        the URL returned can be used in an HTML ``iframe`` with the help of ``src`` attribute.
+
+        Parameters
+        ----------
+        id : str
+             ``ID`` of playlist, album or track.
+        content_type : str
+            Content type can be ``playlist``, ``album`` or ``song``.
+        territory : str, optional
+            Territory code, i.e. "TW", "HK", "JP", "SG", "MY", by default "TW"
+        widget_lang : str, optional
+            The display language of the widget. Can be "TC", "SC", "JA", "EN", "MS", by default "EN"
+        autoplay : bool, optional
+            Whether to start playing music automatically in widget, by default False
+        loop : bool, optional
+            Repeat/loop song(s), by default False
+
+        Returns
+        -------
+        str
+            KKBOX HTML widget URL.
+        """
+        valid_content_types = ["playlist", "album", "song"]
+        valid_widget_langs = ["TC", "SC", "JA", "EN", "MS"]
+        if content_type not in valid_content_types:
+            raise InvalidValueException(
+                f"`content_type` must be one of these: {valid_content_types} !"
+            )
+
+        if territory not in self.valid_territories:
+            raise InvalidValueException(
+                f"`territory` must be one of these: {self.valid_territories} !"
+            )
+
+        if widget_lang not in valid_widget_langs:
+            raise InvalidValueException(
+                f"`widget_lang` must be one of these: {valid_widget_langs} !"
+            )
+
+        return f"https://widget.kkbox.com/v1/?id={id}&type={content_type}&terr={territory}&lang={widget_lang}&autoplay={autoplay}&loop={loop}"
+
+    def _find_music_info(
+        self, artist: str, song: str, response_json: dict
+    ) -> Optional[MusicInfo]:
+        """
+        Finds the music information from the search results.
+
+        Parameters
+        ----------
+        artist : str
+            The name of the artist.
+        song : str
+            The title of the song.
+        response_json : dict
+            The JSON response from the API.
+
+        Returns
+        -------
+        Optional[MusicInfo]
+            The music information if found, otherwise None.
+        """
+        try:
+            for track in response_json["tracks"]["data"]:
+                music_info = self._find_track(song, artist, track)
+                if music_info:
+                    return music_info
+        except KeyError:
+            pass
+
+        try:
+            for album in response_json["albums"]["data"]:
+                music_info = self._find_album(song, artist, album)
+                if music_info:
+                    return music_info
+        except KeyError:
+            pass
+
+        return None
+
+    def _find_track(self, song: str, artist: str, track: dict) -> Optional[MusicInfo]:
+        """
+        Finds the track information from the search results.
+
+        Parameters
+        ----------
+        song : str
+            The title of the song.
+        artist : str
+            The name of the artist.
+        track : dict
+            A single track from the search results.
+        artist_ids : list
+            A list of artist IDs.
+
+        Returns
+        -------
+        Optional[MusicInfo]
+            The music information if found, otherwise None.
+        """
+        if not are_strings_similar(track["name"], song):
+            return None
+
+        artists_name = track["album"]["artist"]["name"]
+        matching_artists = (
+            artists_name if are_strings_similar(artists_name, artist) else None
+        )
+
+        if matching_artists:
+            return MusicInfo(
+                album_art=track["album"]["images"][2]["url"],
+                album_title=track["album"]["name"],
+                album_type=None,
+                artists=artists_name,
+                genre=None,
+                id=track["id"],
+                isrc=track["isrc"],
+                lyrics=None,
+                release_date=track["album"]["release_date"],
+                tempo=None,
+                title=track["name"],
+                type="track",
+                upc=None,
+                url=track["url"],
+            )
+
+        return None
+
+    def _find_album(self, song: str, artist: str, album: dict) -> Optional[MusicInfo]:
+        """
+        Finds the album information from the search results.
+
+        Parameters
+        ----------
+        song : str
+            The title of the song.
+        artist : str
+            The name of the artist.
+        album : dict
+            A single album from the search results.
+        artist_ids : list
+            A list of artist IDs.
+
+        Returns
+        -------
+        Optional[MusicInfo]
+            The music information if found, otherwise None.
+        """
+        if not are_strings_similar(album["name"], song):
+            return None
+
+        artists_name = album["artist"]["name"]
+        matching_artists = (
+            artists_name if are_strings_similar(artists_name, artist) else None
+        )
+
+        if matching_artists:
+            return MusicInfo(
+                album_art=album["images"][2]["url"],
+                album_title=album["name"],
+                album_type=None,
+                artists=artists_name,
+                genre=None,
+                id=album["id"],
+                isrc=None,
+                lyrics=None,
+                release_date=album["release_date"],
+                tempo=None,
+                title=album["name"],
+                type="album",
+                upc=None,
+                url=album["url"],
+            )
+
+        return None
+
+
+if __name__ == "__main__":
+    kkbox = KKBox(KKBOX_CLIENT_ID, KKBOX_CLIENT_SECRET)
+
+    try:
+        artist_name = input("Artist Name: ")
+        song_name = input("Song Name: ")
+        pprint(kkbox.search(artist_name, song_name))
+    finally:
+        kkbox.close_session()

yutipy/spotify.py

@@ -36,7 +36,9 @@ class Spotify:
     """
 
     def __init__(
-        self, client_id: str = SPOTIFY_CLIENT_ID, client_secret: str = SPOTIFY_CLIENT_SECRET
+        self,
+        client_id: str = SPOTIFY_CLIENT_ID,
+        client_secret: str = SPOTIFY_CLIENT_SECRET,
     ) -> None:
         """
         Initializes the Spotify class and sets up the session.
@@ -50,7 +52,7 @@ class Spotify:
         """
         if not client_id or not client_secret:
             raise SpotifyException(
-                "Failed to read `SPOTIFY_CLIENT_ID` and `SPOTIFY_CLIENT_SECRET` from environment variables. Client ID and Client Secret must be provided."
+                "Failed to read `SPOTIFY_CLIENT_ID` and/or `SPOTIFY_CLIENT_SECRET` from environment variables. Client ID and Client Secret must be provided."
             )
 
         self.client_id = client_id
@@ -157,22 +159,37 @@ class Spotify:
                 "Artist and song names must be valid strings and can't be empty."
             )
 
-        self.__refresh_token_if_expired()
+        music_info = None
+        queries = [
+            f"?q=artist:{artist} track:{song}&type=track&limit=10",
+            f"?q=artist:{artist} album:{song}&type=album&limit=10",
+        ]
 
-        query = f"?q=artist:{artist} track:{song}&type=track&limit=10"
-        query_url = f"{self.api_url}/search{query}"
+        for query in queries:
+            if music_info:
+                return music_info
 
-        try:
-            response = self._session.get(query_url, headers=self.__header, timeout=30)
-            response.raise_for_status()
-        except requests.RequestException as e:
-            raise NetworkException(f"Network error occurred: {e}")
+            self.__refresh_token_if_expired()
 
-        if response.status_code != 200:
-            raise SpotifyException(f"Failed to search for music: {response.json()}")
+            query_url = f"{self.api_url}/search{query}"
 
-        artist_ids = self._get_artists_ids(artist)
-        return self._find_music_info(artist, song, response.json(), artist_ids)
+            try:
+                response = self._session.get(
+                    query_url, headers=self.__header, timeout=30
+                )
+                response.raise_for_status()
+            except requests.RequestException as e:
+                raise NetworkException(f"Network error occurred: {e}")
+
+            if response.status_code != 200:
+                raise SpotifyException(f"Failed to search for music: {response.json()}")
+
+            artist_ids = self._get_artists_ids(artist)
+            music_info = self._find_music_info(
+                artist, song, response.json(), artist_ids
+            )
+
+        return music_info
 
     def search_advanced(
         self, artist: str, song: str, isrc: str = None, upc: str = None
@@ -282,7 +299,7 @@ class Spotify:
         """
         try:
             for track in response_json["tracks"]["items"]:
-                music_info = self._find_tracks(song, artist, track, artist_ids)
+                music_info = self._find_track(song, artist, track, artist_ids)
                 if music_info:
                     return music_info
         except KeyError:
@@ -298,7 +315,7 @@ class Spotify:
 
         return None
 
-    def _find_tracks(
+    def _find_track(
         self, song: str, artist: str, track: dict, artist_ids: list
     ) -> Optional[MusicInfo]:
         """
@@ -404,11 +421,11 @@ class Spotify:
 
 
 if __name__ == "__main__":
-    Spotify = Spotify(SPOTIFY_CLIENT_ID, SPOTIFY_CLIENT_SECRET)
+    spotify = Spotify(SPOTIFY_CLIENT_ID, SPOTIFY_CLIENT_SECRET)
 
     try:
         artist_name = input("Artist Name: ")
         song_name = input("Song Name: ")
-        pprint(Spotify.search(artist_name, song_name))
+        pprint(spotify.search(artist_name, song_name))
     finally:
-        Spotify.close_session()
+        spotify.close_session()

{yutipy-1.0.0.dist-info → yutipy-1.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: yutipy
-Version: 1.0.0
+Version: 1.2.0
 Summary: A simple package for retrieving music information from various music platforms APIs.
 Author: Cheap Nightbot
 Author-email: Cheap Nightbot <hi@cheapnightbot.slmail.me>
@@ -85,6 +85,7 @@ A _**simple**_ Python package for searching and retrieving music information fro
 ## Table of Contents
 
 - [Features](#features)
+    - [Available Music Platforms](#available-music-platforms)
 - [Installation](#installation)
 - [Usage Example](#usage-example)
 - [Contributing](#contributing)
@@ -97,6 +98,17 @@ A _**simple**_ Python package for searching and retrieving music information fro
 - It uses `RapidFuzz` to compare & return the best match so that you can be sure you got what you asked for without having to worry and doing all that work by yourself.
 - Retrieve detailed music information, including album art, release dates, lyrics, ISRC, and UPC codes.
 
+### Available Music Platforms
+
+Right now, the following music platforms are available in yutipy for searching music. New platforms will be added in the future.
+Feel free to request any music platform you would like me to add by opening an issue on [GitHub](https://github.com/CheapNightbot/yutipy/issues) or by emailing me.
+
+- `Deezer`: https://www.deezer.com
+- `iTunes`: https://music.apple.com
+- `KKBOX`: https://www.kkbox.com
+- `Spotify`: https://spotify.com
+- `YouTube Music`: https://music.youtube.com
+
 ## Installation
 
 You can install the package using pip. Make sure you have Python 3.8 or higher installed.

{yutipy-1.0.0.dist-info → yutipy-1.2.0.dist-info}/RECORD

@@ -1,14 +1,15 @@
 yutipy/__init__.py,sha256=t0w-pRLjIGD3UtDyd-JpeL-RrMona7YTV_0lZCpGLEc,232
 yutipy/deezer.py,sha256=TbPk6f1ytrtk9GHXOoRZ948fcgOi0619-rQC9xfTYu0,8641
-yutipy/exceptions.py,sha256=QDfOkaeZtSNg1lhXZ872yNJwbof68eVHDezZeZh8DiU,1029
+yutipy/exceptions.py,sha256=4L0Oe1PwFP34LoFTy-Fruipk7uB-JkaackRmkjlaZJU,1138
 yutipy/itunes.py,sha256=NhrllA3U0PUY3dNoMyiG1oZuyvdMQKYRBHzYSkt8ikM,5843
+yutipy/kkbox.py,sha256=yuyEanxxOXsiL2ZTtJMraETQxDetWfUu9K8IULSKQrQ,12186
 yutipy/models.py,sha256=RnfWjoNO1UoNsRvNRYd-4TpkU-4jHKu5t394vIqOOgw,1360
 yutipy/musicyt.py,sha256=kvRYuhlNVuvy-WahJq895T3JAzmGTTiKB89r_uTMTAI,7155
-yutipy/spotify.py,sha256=ZFn73iHtXczO4Dq3ZfYquwtP_fyfHBK2sJTFrcv_xYE,13232
+yutipy/spotify.py,sha256=CZA9XF0EV5wSrLrN9cURtiFKSEHsIvqVlXLKkvb4JEM,13609
 yutipy/utils/__init__.py,sha256=7UFcFZ7fBtNXOTngjnRD3MeobT3x5UT2Gag94TXVgLk,169
 yutipy/utils/cheap_utils.py,sha256=LIuEHib_97NuLahXxdHJUD9v-ccXNUc3NrLYk8EQ52A,1652
-yutipy-1.0.0.dist-info/LICENSE,sha256=_89JsS2QnBG8tAb5-VWbJDj_uJ002zPJAYBJJdh3DPY,1071
-yutipy-1.0.0.dist-info/METADATA,sha256=b8VSSJH__Ii-QJOfCszX4pBWEx6sKAmHcL9t4_qPVHQ,5897
-yutipy-1.0.0.dist-info/WHEEL,sha256=jB7zZ3N9hIM9adW7qlTAyycLYW9npaWKLRzaoVcLKcM,91
-yutipy-1.0.0.dist-info/top_level.txt,sha256=t2A5V2_mUcfnHkbCy6tAQlb3909jDYU5GQgXtA4756I,7
-yutipy-1.0.0.dist-info/RECORD,,
+yutipy-1.2.0.dist-info/LICENSE,sha256=_89JsS2QnBG8tAb5-VWbJDj_uJ002zPJAYBJJdh3DPY,1071
+yutipy-1.2.0.dist-info/METADATA,sha256=GZOfBMev_zfoZ2JWhFM60t85GkOU2rerxowo1CFqR4c,6467
+yutipy-1.2.0.dist-info/WHEEL,sha256=jB7zZ3N9hIM9adW7qlTAyycLYW9npaWKLRzaoVcLKcM,91
+yutipy-1.2.0.dist-info/top_level.txt,sha256=t2A5V2_mUcfnHkbCy6tAQlb3909jDYU5GQgXtA4756I,7
+yutipy-1.2.0.dist-info/RECORD,,