Create Graphical Interface and Test Suite

Author: nicholassaylor

.gitignore

@@ -12,6 +12,11 @@
 /.idea/
 # Output files
 /OutputClouds/
+*.png
+*.jpg
+*.bmp
+*.gif
+*.webp
 # Pycache
 /__pycache__/
 # Build/Distribution Files

README.md

@@ -1,40 +1,49 @@
-# Music Artist Word Bubble
-### Note: This project is currently in development. Features may not be fully functional and implementation details are subject to change.
-
-## Description
-This program pull lyrics from [Genius](https://genius.com/) for a particular artist and creates a word cloud with their lyrics.
+# Artist Word Cloud
+This program pulls lyrics from [Genius](https://genius.com/) for a particular artist and creates a word cloud with their lyrics.
 A word cloud is a visual representation of the frequency of words within a particular work, with more frequent words being larger.
 Word clouds can either be in the shape of a particular graphic or simply fill a canvas, this program does the latter.
 
 ## Using This Software
 
 #### Instructions
 1. Download the Program
-   * Go to the [Releases Tab](https://github.com/nicholassaylor/Artist-Word-Bubble/releases) and Download the Latest Release
+   * Go to the [Releases Tab](https://github.com/nicholassaylor/Artist-Word-Cloud/releases) and download your desired version of the program
+     * `artistwordcloud_cli.exe` is the command line version
+     * `artistwordcloud_gui.exe` is the graphical version
 2. Run the Executable
-   * Double-clicking the program will open the program in a new window and prompt the user for artists
-     * Opening may take a few seconds
-   * In a terminal opened in the folder, type `musicwordcloud.exe ["ARTIST_NAME" ... ]` to automatically run the program on the listed artists
-   * Output will be in the form of a file named `<artist-name>.png` in a folder named `OutputClouds` where the exe was run
+   * **Command Line Version**
+      * Double-clicking the program will open the program in a new window and prompt the user for artists
+        * Opening may take a few seconds and require confirmation from your operating system
+      * In a terminal opened in the folder, type `artistwordcloud_cli.exe ["ARTIST_NAME" ... ]` to automatically run the program on the listed artists
+      * Output will be in the form of a file named `<artist-name>.png` in the folder the program was run
+   * **Graphical Interface Version**
+     * Double-clicking the program will open the interface to create and save word clouds
+       * Opening may take a few seconds and require confirmation from your operating system
+     *  You will be prompted to choose the location of your saved files
 
 ## Running from Source
 
 #### Requirements
 * [Python 3.11](https://www.python.org/downloads/release/python-3119/)
   * pip must be installed to install requirements
+  * Python should be added to your PATH if prompted
 
 #### Instructions
 1. Download the Code
-   * Go to the [Releases Tab](https://github.com/nicholassaylor/Artist-Word-Bubble/releases) and Download the Latest Release
+   * Go to the [Releases Tab](https://github.com/nicholassaylor/Artist-Word-Cloud/releases) and Download the Latest Release
    * Select "Source code (zip)", save the file, and unzip the folder
 2. Install Requirements
    * Use `pip install -r requirements.txt` to install the required python packages
-3. Run the Code
-   * Typing `python.exe musicwordcloud.py` in a terminal opened in the project folder will run the code
-   * Artists may be specified through the CLI using the following format:  
-     `python.exe musicwordcloud.py ["ARTIST_NAME" ... ]`
-   * Output will be in the form of a file named `<artist-name>.png` in a folder named `OutputClouds` where the code was run
-
+3. Running the Code
+   * **Command Line Version** 
+     * Typing `python.exe artistwordcloud/artistwordcloud.py` in a terminal opened in the project folder or opening the file directly in Python will run the command line interface
+     * Artists may be specified through the CLI using the following format:  
+     `python.exe artistwordcloud/artistwordcloud.py ["ARTIST_NAME" ... ]`
+     * Output will be in the form of a file named `<artist-name>.png` in the folder the program was run
+   * **Graphical Interface Version**
+     * Typing `python.exe artistwordcloud/gui.py` in a terminal opened in the project folder or opening the file directly in Python will run the graphical interface to interact with
+     * Specifying artists through the command line is not supported
+     * You will be prompted to choose the location of your saved files
 
 ## FAQs
 * Is *insert language here* supported?
@@ -43,5 +52,3 @@ Word clouds can either be in the shape of a particular graphic or simply fill a
   * Due to limitations with the underlying systems, only a single script supported at a time. Currently, there are no plans to add this functionality.
 * Can I limit the word cloud to a specific album?
   * Not currently, however that is planned to be released at a later date.
-* Is there a GUI for this program?
-  * Currently, there is not a GUI, but this is anticipated to be added at a later date.

artistwordcloud/__init__.py

@@ -3,16 +3,22 @@
 import sys
 from multiprocessing import Pool, freeze_support
 
-import matplotlib.pyplot as plot
 import requests
 from bs4 import BeautifulSoup
 from unidecode import unidecode
 from wordcloud import WordCloud
 
-from constants import ARTIST_RE, CLEAN_PUNC_RE, COMBINED_STOPWORDS, HTML_TAG_RE, LYRIC_CLASS, SECTION_RE
+from artistwordcloud.constants import (
+    ARTIST_RE,
+    CLEAN_PUNC_RE,
+    COMBINED_STOPWORDS,
+    HTML_TAG_RE,
+    LYRIC_CLASS,
+    SECTION_RE,
+)
 
 
-def remove_fluff(element) -> str:
+def _remove_fluff(element) -> str:
     """
     Removes html tags, section names, and additional non-lyric text from lyrics
     """
@@ -32,27 +38,37 @@ def build_artist_page(artist_name: str) -> str:
     return base_url + constructed_url + "/songs"
 
 
-def build_song_links(artist_page: str, artist_name: str) -> list:
+def find_api(page: str, name: str) -> str:
     """
-    Compiles a list of song links associated to a particular artist
-    Pulls data from Genius's API
+    Finds the api key for an artist on their artist page
     """
-    response = requests.get(artist_page)
+    response = requests.get(page)
     candidates = re.findall(r"artists/[0-9]+", response.text)
     api_string = ""
     for candidate in candidates:
         content = requests.get(f"https://genius.com/api/{candidate}").json()
-        if (unidecode(re.sub(r"\W", "", artist_name.lower())) in
-                unidecode(re.sub(r"\W", "", content["response"]["artist"]["name"].lower()))):
+        if unidecode(re.sub(r"\W", "", name.lower())) in unidecode(
+            re.sub(r"\W", "", content["response"]["artist"]["name"].lower())
+        ):
             api_string = re.sub(r"artists/", "", candidate)
-            break
+            return api_string
+    return api_string
+
+
+def _build_song_links(artist_page: str, artist_name: str) -> list:
+    """
+    Compiles a list of song links associated to a particular artist
+    Pulls data from Genius's API
+    """
+    api_string = find_api(artist_page, artist_name)
     if api_string == "":
         raise ValueError()
     print(
         "Collecting links...\nDepending on the size of the artist's library, this may take a while..."
     )
     content = requests.get(
-        f"https://genius.com/api/artists/{api_string}/songs?page=1&per_page=20&sort=popularity&text_format=html").json()
+        f"https://genius.com/api/artists/{api_string}/songs?page=1&per_page=20&sort=popularity&text_format=html"
+    ).json()
     link_list = []
     while True:
         for entry in content["response"]["songs"]:
@@ -68,7 +84,7 @@ def build_song_links(artist_page: str, artist_name: str) -> list:
     return link_list
 
 
-def process_lyrics(url: str) -> str:
+def _process_lyrics(url: str) -> str:
     """
     Processes the lyrics for a particular webpage and returns them as a nicely formatted string
     This function is called by convert_lyrics as part of a multiprocessing pool
@@ -77,12 +93,12 @@ def process_lyrics(url: str) -> str:
     soup = BeautifulSoup(response.text, "html.parser")
     lyrics_elements = soup.find_all("div", class_=LYRIC_CLASS)
     portions = [
-        remove_fluff(item.decode_contents().lower()) for item in lyrics_elements
+        _remove_fluff(item.decode_contents().lower()) for item in lyrics_elements
     ]
     return " ".join(re.sub(r"\s+", " ", portion) for portion in portions)
 
 
-def convert_lyrics(song_links: list[str]) -> str:
+def _convert_lyrics(song_links: list[str]) -> str:
     """
     Processes the content of the webpage links lists into neatly formatted lyrics strings.
     """
@@ -91,17 +107,39 @@ def convert_lyrics(song_links: list[str]) -> str:
         print("This may take a while...")
     # Multiprocess lyrics
     with Pool() as pool:
-        data_set = pool.map(process_lyrics, song_links)
+        data_set = pool.map(_process_lyrics, song_links)
         pool.close()
     return " ".join(data_set)
 
 
-def build_cloud(data_set: str) -> None:
+def _build_cloud(data_set: str) -> None:
     """
     Processes the string into a word cloud, which are saved as .png files.
     Files are named after the artist as they appear in the Genius links
     """
     print("Generating word cloud...")
+    output_name = re.sub(ARTIST_RE, "", unidecode(artist).replace(" ", "-").lower())
+    try:
+        WordCloud(
+            width=1080,
+            height=1080,
+            background_color="black",
+            stopwords=COMBINED_STOPWORDS,
+            min_font_size=8,
+            max_words=150,
+            relative_scaling=0.7,
+        ).generate(unidecode(data_set)).to_file(f"{output_name}.png")
+        print(f"Saved word cloud as {output_name}.png!")
+    except OSError:
+        print(
+            f"Could not save {output_name}.png\nYou may not have access to write in this directory."
+        )
+
+
+def _export_cloud(data_set: str) -> WordCloud:
+    """
+    Processes the string into a word cloud, returning the cloud
+    """
     wordcloud = WordCloud(
         width=1080,
         height=1080,
@@ -111,23 +149,23 @@ def build_cloud(data_set: str) -> None:
         max_words=150,
         relative_scaling=0.7,
     ).generate(unidecode(data_set))
-    plot.figure(figsize=(8, 8), facecolor=None)
-    plot.imshow(wordcloud)
-    plot.axis("off")
-    plot.tight_layout(pad=0)
-    output_name = re.sub(ARTIST_RE, '', unidecode(artist).replace(' ', '-').lower())
+    return wordcloud
+
+
+def cloud_hook(artist_name: str) -> WordCloud or None:
+    decode_artist = unidecode(artist_name)
     try:
-        plot.savefig(fname=f"./OutputClouds/{output_name}.png")
-        print(f"Saved word cloud as {output_name}.png!")
-    except OSError:
-        print(f"Could not save {output_name}.png\nYou may not have access to write in this directory.")
+        links = _build_song_links(build_artist_page(decode_artist), decode_artist)
+        return _export_cloud(_convert_lyrics(links))
+    except ValueError:
+        return None
 
 
 if __name__ == "__main__":
     freeze_support()
     cmd_args = sys.argv[1:]
     try:
-        os.mkdir("./OutputClouds/")
+        os.mkdir("../OutputClouds/")
     except FileExistsError:
         pass
     if len(cmd_args) == 0:
@@ -136,8 +174,11 @@ def build_cloud(data_set: str) -> None:
             try:
                 if artist == "":
                     break
-                song_list = build_song_links(build_artist_page(unidecode(artist)), unidecode(artist))
-                build_cloud(convert_lyrics(song_list))
+                decoded_artist = unidecode(artist)
+                song_list = _build_song_links(
+                    build_artist_page(decoded_artist), decoded_artist
+                )
+                _build_cloud(_convert_lyrics(song_list))
             except ValueError:
                 artist = input(
                     f"Artist {artist} could not be found on Genius.\n"
@@ -149,8 +190,11 @@ def build_cloud(data_set: str) -> None:
         for artist in artists:
             try:
                 print(f"\n\nCurrent artist: {artist}")
-                song_list = build_song_links(build_artist_page(unidecode(artist)), unidecode(artist))
-                build_cloud(convert_lyrics(song_list))
+                decoded_artist = unidecode(artist)
+                song_list = _build_song_links(
+                    build_artist_page(decoded_artist), decoded_artist
+                )
+                _build_cloud(_convert_lyrics(song_list))
             except ValueError:
                 print(
                     f"Artist {artist} could not be found on Genius. "