yutipy 1.4.22__tar.gz → 1.5.1__tar.gz

{yutipy-1.4.22 → yutipy-1.5.1}/PKG-INFO

@@ -1,32 +1,11 @@
 Metadata-Version: 2.4
 Name: yutipy
-Version: 1.4.22
+Version: 1.5.1
 Summary: A simple package for retrieving music information from various music platforms APIs.
 Author: Cheap Nightbot
 Author-email: Cheap Nightbot <hi@cheapnightbot.slmail.me>
 Maintainer-email: Cheap Nightbot <hi@cheapnightbot.slmail.me>
-License: MIT License
-        
-        Copyright (c) 2025 Cheap Nightbot
-        
-        Permission is hereby granted, free of charge, to any person obtaining a copy
-        of this software and associated documentation files (the "Software"), to deal
-        in the Software without restriction, including without limitation the rights
-        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-        copies of the Software, and to permit persons to whom the Software is
-        furnished to do so, subject to the following conditions:
-        
-        The above copyright notice and this permission notice shall be included in all
-        copies or substantial portions of the Software.
-        
-        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-        SOFTWARE.
-        
+License-Expression: MIT
 Project-URL: Homepage, https://github.com/CheapNightbot/yutipy
 Project-URL: Documentation, https://yutipy.readthedocs.io/
 Project-URL: Repository, https://github.com/CheapNightbot/yutipy.git
@@ -43,7 +22,6 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
@@ -90,6 +68,10 @@ A _**simple**_ Python package for searching and retrieving music information fro
     - [Available Music Platforms](#available-music-platforms)
 - [Installation](#installation)
 - [Usage Example](#usage-example)
+- [Command-Line Interface (CLI)](#command-line-interface-cli)
+    - [Search for Music](#search-for-music)
+        - [Options](#options)
+    - [Configuration Wizard](#configuration-wizard)
 - [Contributing](#contributing)
 - [License](#license)
 
@@ -121,9 +103,7 @@ pip install -U yutipy
 
 ## Usage Example
 
-Here's a quick example of how to use the `yutipy` package to search for a song:
-
-### Deezer
+Here's a quick example of how to use the `yutipy` package to search for a song on **Deezer**:
 
 ```python
 from yutipy.deezer import Deezer
@@ -135,6 +115,36 @@ with Deezer() as deezer:
 
 For more usage examples, see the [Usage Examples](https://yutipy.readthedocs.io/en/latest/usage_examples.html) page in docs.
 
+## Command-Line Interface (CLI)
+
+The `yutipy` package includes a CLI tool that allows you to search for music directly from the command line and configure API keys interactively.
+
+### Search for Music
+
+You can use the CLI tool to search for music across multiple platforms:
+
+```bash
+yutipy-cli "Rick Astley" "Never Gonna Give You Up" --limit 3 --normalize
+```
+
+#### Options:
+- `artist` (required): The name of the artist.
+- `song` (required): The title of the song.
+- `--limit`: The number of results to retrieve (default: 5).
+- `--normalize`: Normalize non-English characters for comparison.
+- `--verbose`: Enable logging in the terminal.
+- `--service`: Specify a single service to search (e.g., `deezer`, `spotify`, `itunes`).
+
+### Configuration Wizard
+
+To set up your API keys interactively, use the configuration wizard:
+
+```bash
+yutipy-config
+```
+
+The wizard will guide you through obtaining and setting up API keys for supported services like Spotify and KKBOX. If the required environment variables are already set, the wizard will skip those steps.
+
 ## Contributing
 
 Contributions are welcome! Please follow these steps:

{yutipy-1.4.22 → yutipy-1.5.1}/README.md

@@ -31,6 +31,10 @@ A _**simple**_ Python package for searching and retrieving music information fro
     - [Available Music Platforms](#available-music-platforms)
 - [Installation](#installation)
 - [Usage Example](#usage-example)
+- [Command-Line Interface (CLI)](#command-line-interface-cli)
+    - [Search for Music](#search-for-music)
+        - [Options](#options)
+    - [Configuration Wizard](#configuration-wizard)
 - [Contributing](#contributing)
 - [License](#license)
 
@@ -62,9 +66,7 @@ pip install -U yutipy
 
 ## Usage Example
 
-Here's a quick example of how to use the `yutipy` package to search for a song:
-
-### Deezer
+Here's a quick example of how to use the `yutipy` package to search for a song on **Deezer**:
 
 ```python
 from yutipy.deezer import Deezer
@@ -76,6 +78,36 @@ with Deezer() as deezer:
 
 For more usage examples, see the [Usage Examples](https://yutipy.readthedocs.io/en/latest/usage_examples.html) page in docs.
 
+## Command-Line Interface (CLI)
+
+The `yutipy` package includes a CLI tool that allows you to search for music directly from the command line and configure API keys interactively.
+
+### Search for Music
+
+You can use the CLI tool to search for music across multiple platforms:
+
+```bash
+yutipy-cli "Rick Astley" "Never Gonna Give You Up" --limit 3 --normalize
+```
+
+#### Options:
+- `artist` (required): The name of the artist.
+- `song` (required): The title of the song.
+- `--limit`: The number of results to retrieve (default: 5).
+- `--normalize`: Normalize non-English characters for comparison.
+- `--verbose`: Enable logging in the terminal.
+- `--service`: Specify a single service to search (e.g., `deezer`, `spotify`, `itunes`).
+
+### Configuration Wizard
+
+To set up your API keys interactively, use the configuration wizard:
+
+```bash
+yutipy-config
+```
+
+The wizard will guide you through obtaining and setting up API keys for supported services like Spotify and KKBOX. If the required environment variables are already set, the wizard will skip those steps.
+
 ## Contributing
 
 Contributions are welcome! Please follow these steps:

yutipy-1.5.1/docs/cli.rst

@@ -0,0 +1,38 @@
+========================
+Command-Line Interface
+========================
+
+The **yutipy** package includes two CLI tools:
+
+1. **yutipy-cli**: Search for music across multiple platforms.
+2. **yutipy-config**: Configure API keys interactively.
+
+yutipy-cli
+----------
+
+Search for music directly from the command line:
+
+.. code-block:: bash
+
+    yutipy-cli "Rick Astley" "Never Gonna Give You Up" --limit 3 --normalize
+
+Options:
+^^^^^^^^
+
+- **artist** (required): The name of the artist.
+- **song** (required): The title of the song.
+- **\-\-limit**: The number of results to retrieve (default: 5).
+- **\-\-normalize**: Normalize non-English characters for comparison.
+- **\-\-verbose**: Enable logging in the terminal.
+- **\-\-service**: Specify a single service to search (e.g., ``deezer``, ``spotify``, ``itunes``).
+
+yutipy-config
+-------------
+
+Set up API keys interactively:
+
+.. code-block:: bash
+
+    yutipy-config
+
+The wizard will guide you through obtaining and setting up API keys for supported services like Spotify and KKBOX.

{yutipy-1.4.22 → yutipy-1.5.1}/docs/faq.rst

@@ -70,6 +70,28 @@ Why am I receiving a ``KKBoxException`` when trying to use the ``KKBox`` class?
 Unfortunately, it's the same case as with Spotify. You will need a ``Client ID`` and ``Client Secret``
 obtained from the KKBOX for Developers website. Please visit https://developer.kkbox.com/ for more information.
 
+How do I use the CLI tool to search for music?
+----------------------------------------------
+
+You can use the CLI tool to search for music directly from the command line. For example:
+
+.. code-block:: bash
+
+    yutipy-cli "Rick Astley" "Never Gonna Give You Up" --limit 3 --normalize
+
+For more details, see the :doc:`usage_examples`.
+
+How do I set up API keys for the library?
+-----------------------------------------
+
+You can use the configuration wizard to set up API keys interactively:
+
+.. code-block:: bash
+
+    yutipy-config
+
+The wizard will guide you through obtaining and setting up API keys for supported services like Spotify and KKBOX.
+
 ----
 
 .. [#] There may be additional features in the future.

{yutipy-1.4.22 → yutipy-1.5.1}/docs/index.rst

@@ -45,8 +45,9 @@ Get Started
 
    installation
    available_platforms
-   api_reference
    usage_examples
+   api_reference
+   cli
    faq
 
 .. toctree::

{yutipy-1.4.22 → yutipy-1.5.1}/docs/usage_examples.rst

@@ -5,11 +5,20 @@ Usage Examples
 Here's a quick example of how to use the **yutipy** package to search for a song:
 
 .. important::
-    All examples here—except for the `YouTube Music`_—use the ``with`` context manager to initialize an instance of the respective class,
+    All examples here use the ``with`` context manager to initialize an instance of the respective class,
     as those classes internally use ``requests.Session()`` for making requests to APIs.
     This approach ensures that the session is automatically closed once you exit the context. Although using ``with`` is not mandatory,
     if you instantiate an object without it, you are responsible for closing the session after use by calling the ``close_session()`` method on that object.
 
+CLI Tool
+--------
+
+You can use the CLI tool to search for music directly from the command line:
+
+.. code-block:: bash
+
+    yutipy-cli "Rick Astley" "Never Gonna Give You Up" --limit 3 --normalize
+
 Deezer
 ------
 
@@ -107,9 +116,9 @@ YouTube Music
 
     from yutipy.musicyt import MusicYT
 
-    music_yt = MusicYT()
-    result = music_yt.search("Artist Name", "Song Title")
-    print(result)
+    with MusicYT() as music_yt:
+        result = music_yt.search("Artist Name", "Song Title")
+        print(result)
 
 Yutipy Music
 ------------

{yutipy-1.4.22 → yutipy-1.5.1}/pyproject.toml

@@ -22,7 +22,7 @@ maintainers = [
 ]
 description = "A simple package for retrieving music information from various music platforms APIs."
 readme = "README.md"
-license = {file = "LICENSE"}
+license = "MIT"
 keywords = ["music", "API", "Deezer", "iTunes", "KKBox", "Spotify", "YouTube Music", "search", "retrieve", "information", "yutify"]
 classifiers = [
   "Development Status :: 4 - Beta",
@@ -34,7 +34,6 @@ classifiers = [
   "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
-  "License :: OSI Approved :: MIT License",
   "Operating System :: OS Independent",
 ]
 
@@ -54,3 +53,7 @@ funding = "https://ko-fi.com/cheapnightbot"
 [tool.setuptools_scm]
 version_scheme = "guess-next-dev"
 local_scheme = "no-local-version"
+
+[project.scripts]
+yutipy-cli = "yutipy.cli.search:main"
+yutipy-config = "yutipy.cli.config:run_config_wizard"

{yutipy-1.4.22 → yutipy-1.5.1}/yutipy/__init__.py

@@ -1,7 +1,6 @@
 from .deezer import Deezer
 from .itunes import Itunes
 from .kkbox import KKBox
-from .models import MusicInfo
 from .musicyt import MusicYT
 from .spotify import Spotify
 from .yutipy_music import YutipyMusic
@@ -10,7 +9,6 @@ __all__ = [
     "Deezer",
     "Itunes",
     "KKBox",
-    "MusicInfo",
     "MusicYT",
     "Spotify",
     "YutipyMusic",

yutipy-1.5.1/yutipy/cli/config.py

@@ -0,0 +1,86 @@
+import os
+import webbrowser
+from dotenv import load_dotenv, set_key
+
+
+def run_config_wizard():
+    """Interactive configuration wizard for setting up API keys."""
+    print("Welcome to the yutipy Configuration Wizard!")
+    print("This wizard will help you set up your API keys for various services.\n")
+
+    # Load existing .env file if it exists
+    env_file = ".env"
+    load_dotenv(env_file)
+
+    # List of required environment variables and their instructions
+    required_vars = {
+        "SPOTIFY_CLIENT_ID": {
+            "description": "Spotify Client ID",
+            "url": "https://developer.spotify.com/dashboard",
+            "instructions": """
+1. Go to your Spotify Developer Dashboard: https://developer.spotify.com/dashboard
+2. Create a new app and fill in the required details.
+3. Copy the "Client ID" and "Client Secret" from the app's settings.
+4. Paste them here when prompted.
+            """,
+        },
+        "SPOTIFY_CLIENT_SECRET": {
+            "description": "Spotify Client Secret",
+            "url": "https://developer.spotify.com/dashboard",
+            "instructions": "See the steps above for Spotify Client ID.",
+        },
+        "KKBOX_CLIENT_ID": {
+            "description": "KKBox Client ID",
+            "url": "https://developer.kkbox.com/",
+            "instructions": """
+1. Go to the KKBOX Developer Portal: https://developer.kkbox.com/
+2. Log in and create a new application.
+3. Copy the "Client ID" and "Client Secret" from the app's settings.
+4. Paste them here when prompted.
+            """,
+        },
+        "KKBOX_CLIENT_SECRET": {
+            "description": "KKBox Client Secret",
+            "url": "https://developer.kkbox.com/",
+            "instructions": "See the steps above for KKBox Client ID.",
+        },
+    }
+
+    # Track whether the browser has already been opened for a service
+    browser_opened = set()
+
+    # Prompt the user for each variable
+    for var, details in required_vars.items():
+        current_value = os.getenv(var)
+        if current_value:
+            print(f"{details['description']} is already set.")
+            continue
+
+        print(f"\n{details['description']} is missing.")
+        print(details["instructions"])
+
+        # Check if the browser has already been opened for this service
+        if details["url"] not in browser_opened:
+            open_browser = (
+                input(
+                    f"Do you want to open the website to get your {details['description']}? (y/N): "
+                )
+                .strip()
+                .lower()
+            )
+            if open_browser == "y":
+                webbrowser.open(details["url"])
+                print(f"The website has been opened in your browser: {details['url']}")
+                browser_opened.add(details["url"])  # Mark this URL as opened
+
+        # Prompt the user to enter the value
+        new_value = input(f"Enter your {details['description']}: ").strip()
+        if new_value:
+            set_key(env_file, var, new_value)
+            print(f"{details['description']} has been saved to the .env file.")
+
+    print("\nConfiguration complete! Your API keys have been saved to the .env file.")
+
+
+if __name__ == "__main__":
+    run_config_wizard()

yutipy-1.5.1/yutipy/cli/search.py

@@ -0,0 +1,104 @@
+import argparse
+from dataclasses import asdict
+from pprint import pprint
+
+from importlib.metadata import version, PackageNotFoundError
+
+try:
+    __version__ = version("yutipy")
+except PackageNotFoundError:
+    __version__ = "unknown"
+
+from yutipy.deezer import Deezer
+from yutipy.itunes import Itunes
+from yutipy.kkbox import KKBox
+from yutipy.musicyt import MusicYT
+from yutipy.spotify import Spotify
+from yutipy.utils.logger import disable_logging, enable_logging
+from yutipy.yutipy_music import YutipyMusic
+
+
+def main():
+    disable_logging()
+
+    # Create the argument parser
+    parser = argparse.ArgumentParser(
+        description="Search for music information across multiple platforms using yutipy."
+    )
+    parser.add_argument("artist", type=str, help="The name of the artist.")
+    parser.add_argument("song", type=str, help="The title of the song.")
+    parser.add_argument(
+        "--limit",
+        type=int,
+        default=5,
+        help="The number of results to retrieve (default: 5).",
+    )
+    parser.add_argument(
+        "--normalize",
+        action="store_true",
+        help="Normalize non-English characters.",
+        default=False,
+    )
+    parser.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Enable logging in terminal",
+        default=False,
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"yutipy v{__version__}",
+        help="Show the version of the yutipy and exit.",
+    )
+    parser.add_argument(
+        "--service",
+        type=str,
+        choices=["deezer", "itunes", "kkbox", "spotify", "ytmusic"],
+        help="Specify a single service to search (e.g., deezer, itunes, kkbox, spotify, ytmusic).",
+    )
+
+    # Parse the arguments
+    args = parser.parse_args()
+
+    if args.verbose:
+        enable_logging()
+
+    # Use the specified service or default to YutipyMusic
+    try:
+        if args.service:
+            service_map = {
+                "deezer": Deezer,
+                "itunes": Itunes,
+                "kkbox": KKBox,
+                "spotify": Spotify,
+                "ytmusic": MusicYT,
+            }
+            service_class = service_map[args.service]
+            with service_class() as service:
+                result = service.search(
+                    artist=args.artist,
+                    song=args.song,
+                    limit=args.limit,
+                    normalize_non_english=args.normalize,
+                )
+        else:
+            with YutipyMusic() as yutipy_music:
+                result = yutipy_music.search(
+                    artist=args.artist,
+                    song=args.song,
+                    limit=args.limit,
+                    normalize_non_english=args.normalize,
+                )
+
+        if result:
+            print("\nSEARCH RESULTS:\n")
+            pprint(asdict(result))
+        else:
+            print("No results found.")
+    except Exception as e:
+        print(f"An error occurred: {e}")
+
+
+if __name__ == "__main__":
+    main()

{yutipy-1.4.22 → yutipy-1.5.1}/yutipy/deezer.py

@@ -1,3 +1,5 @@
+__all__ = ["Deezer", "DeezerException"]
+
 from pprint import pprint
 from typing import Dict, List, Optional
 
@@ -10,7 +12,8 @@ from yutipy.exceptions import (
     NetworkException,
 )
 from yutipy.models import MusicInfo
-from yutipy.utils.cheap_utils import are_strings_similar, is_valid_string
+from yutipy.utils.helpers import are_strings_similar, is_valid_string
+from yutipy.utils.logger import logger
 
 
 class Deezer:
@@ -86,22 +89,34 @@ class Deezer:
             query_url = endpoint + query
 
             try:
+                logger.info(
+                    f'Searching music info for `artist="{artist}"` and `song="{song}"`'
+                )
+                logger.debug(f"Query URL: {query_url}")
                 response = self._session.get(query_url, timeout=30)
+                logger.debug(f"Response status code: {response.status_code}")
                 response.raise_for_status()
             except requests.RequestException as e:
+                logger.error(f"Network error while fetching music info: {e}")
                 raise NetworkException(f"Network error occurred: {e}")
             except Exception as e:
+                logger.exception(f"Unexpected error while searching Deezer: {e}")
                 raise DeezerException(f"An error occurred while searching Deezer: {e}")
 
             try:
+                logger.debug(f"Parsing response JSON: {response.json()}")
                 result = response.json()["data"]
             except (IndexError, KeyError, ValueError) as e:
+                logger.error(f"Invalid response structure from Deezer: {e}")
                 raise InvalidResponseException(f"Invalid response received: {e}")
 
             music_info = self._parse_results(artist, song, result)
             if music_info:
                 return music_info
 
+        logger.warning(
+            f"No matching results found for artist='{artist}' and song='{song}'"
+        )
         return None
 
     def _get_upc_isrc(self, music_id: int, music_type: str) -> Optional[Dict]:
@@ -127,7 +142,7 @@ class Deezer:
         else:
             raise DeezerException(f"Invalid music type: {music_type}")
 
-    def _get_track_info(self, music_id: int) -> Optional[Dict]:
+    def _get_track_info(self, track_id: int) -> Optional[Dict]:
         """
         Retrieves track information for a given track ID.
 
@@ -141,18 +156,25 @@ class Deezer:
         Optional[Dict]
             A dictionary containing track information.
         """
-        query_url = f"{self.api_url}/track/{music_id}"
+        query_url = f"{self.api_url}/track/{track_id}"
         try:
+            logger.info(f"Fetching track info for track_id: {track_id}")
+            logger.debug(f"Query URL: {query_url}")
             response = self._session.get(query_url, timeout=30)
+            logger.debug(f"Response status code: {response.status_code}")
             response.raise_for_status()
         except requests.RequestException as e:
+            logger.error(f"Error fetching track info: {e}")
             raise NetworkException(f"Network error occurred: {e}")
         except Exception as e:
+            logger.error(f"Error fetching track info: {e}")
             raise DeezerException(f"An error occurred while fetching track info: {e}")
 
         try:
+            logger.debug(f"Response JSON: {response.json()}")
             result = response.json()
         except ValueError as e:
+            logger.error(f"Invalid response received from Deezer: {e}")
             raise InvalidResponseException(f"Invalid response received: {e}")
 
         return {
@@ -161,7 +183,7 @@ class Deezer:
             "tempo": result.get("bpm"),
         }
 
-    def _get_album_info(self, music_id: int) -> Optional[Dict]:
+    def _get_album_info(self, album_id: int) -> Optional[Dict]:
         """
         Retrieves album information for a given album ID.
 
@@ -175,18 +197,25 @@ class Deezer:
         Optional[Dict]
             A dictionary containing album information.
         """
-        query_url = f"{self.api_url}/album/{music_id}"
+        query_url = f"{self.api_url}/album/{album_id}"
         try:
+            logger.info(f"Fetching album info for album_id: {album_id}")
+            logger.debug(f"Query URL: {query_url}")
             response = self._session.get(query_url, timeout=30)
+            logger.info(f"Response status code: {response.status_code}")
             response.raise_for_status()
         except requests.RequestException as e:
+            logger.error(f"Error fetching album info: {e}")
             raise NetworkException(f"Network error occurred: {e}")
         except Exception as e:
+            logger.error(f"Error fetching album info: {e}")
             raise DeezerException(f"An error occurred while fetching album info: {e}")
 
         try:
+            logger.debug(f"Response JSON: {response.json()}")
             result = response.json()
         except ValueError as e:
+            logger.error(f"Invalid response received from Deezer: {e}")
             raise InvalidResponseException(f"Invalid response received: {e}")
 
         return {
@@ -293,6 +322,10 @@ class Deezer:
 
 
 if __name__ == "__main__":
+    import logging
+    from yutipy.utils.logger import enable_logging
+
+    enable_logging(level=logging.DEBUG)
     deezer = Deezer()
     try:
         artist_name = input("Artist Name: ")