Added some more Discogs API endpoints

Author: bbye98

.github/workflows/ci.yml

@@ -12,32 +12,31 @@ env:
   TIDAL_PRIVATE_CLIENT_SECRET: ${{ secrets.TIDAL_PRIVATE_CLIENT_SECRET }}
 jobs:
   build:
-    name: Continuous integration (Python ${{ matrix.python-version }})
+    name: continuous-integration-${{ matrix.os }}-python-${{ matrix.python-version }}
     strategy:
       matrix:
-        os: [macos-latest, ubuntu-latest, windows-latest]
+        os: [ubuntu-latest, windows-latest]
         python-version: ["3.9", "3.10", "3.11"]
     runs-on: ${{ matrix.os }}
     defaults:
       run:
         shell: bash -el {0}
     timeout-minutes: 60
-    steps:      
+    steps:
       - uses: actions/checkout@v3
       - uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
       - uses: FedericoCarboni/setup-ffmpeg@v2
         id: setup-ffmpeg
-      - name: Install required dependencies using pip
-        run: |
-          python3 -m pip install -r requirements_minimal.txt
-      - name: Lint with ruff
+      - name: pip-install-dependencies
+        run: python3 -m pip install -r requirements_minimal.txt
+      - name: ruff-lint
         run: |
           python3 -m pip install ruff
-          ruff --target-version=py39 .
+          ruff check --target-version=py39 .
         continue-on-error: true
-      - name: Test with coverage and pytest
+      - name: pytest-test
         run: |
-          python3 -m pip install coverage pytest
-          coverage run -m pytest
+          python3 -m pip install pytest
+          pytest

docs/.doctrees/api.doctree

@@ -4,7 +4,7 @@
     <meta name="viewport" content="width=device-width,initial-scale=1"/>
     <meta name="color-scheme" content="light dark"><link rel="index" title="Index" href="../genindex.html" /><link rel="search" title="Search" href="../search.html" />
 
-    <link rel="shortcut icon" href="../_static/favicon.ico"/><!-- Generated with Sphinx 7.2.6 and Furo 2023.09.10 -->
+    <link rel="shortcut icon" href="../_static/favicon.ico"/><!-- Generated with Sphinx 7.2.6 and Furo 2024.01.29 -->
         <title>Overview: module code - Minim 1.0.0 documentation</title>
       <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=a746c00c" />
     <link rel="stylesheet" type="text/css" href="../_static/styles/furo.css?v=135e06be" />

docs/.doctrees/api/minim.audio.Audio.doctree

@@ -4,7 +4,7 @@
     <meta name="viewport" content="width=device-width,initial-scale=1"/>
     <meta name="color-scheme" content="light dark"><link rel="index" title="Index" href="../../genindex.html" /><link rel="search" title="Search" href="../../search.html" />
 
-    <link rel="shortcut icon" href="../../_static/favicon.ico"/><!-- Generated with Sphinx 7.2.6 and Furo 2023.09.10 -->
+    <link rel="shortcut icon" href="../../_static/favicon.ico"/><!-- Generated with Sphinx 7.2.6 and Furo 2024.01.29 -->
         <title>minim.utility - Minim 1.0.0 documentation</title>
       <link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=a746c00c" />
     <link rel="stylesheet" type="text/css" href="../../_static/styles/furo.css?v=135e06be" />
@@ -173,6 +173,7 @@
 <li class="toctree-l3"><a class="reference internal" href="../../api/minim.audio.FLACAudio.html">FLACAudio</a></li>
 <li class="toctree-l3"><a class="reference internal" href="../../api/minim.audio.MP3Audio.html">MP3Audio</a></li>
 <li class="toctree-l3"><a class="reference internal" href="../../api/minim.audio.MP4Audio.html">MP4Audio</a></li>
+<li class="toctree-l3"><a class="reference internal" href="../../api/minim.audio.OggAudio.html">OggAudio</a></li>
 <li class="toctree-l3"><a class="reference internal" href="../../api/minim.audio.WAVEAudio.html">WAVEAudio</a></li>
 </ul>
 </li>
@@ -269,9 +270,9 @@ <h1>Source code for minim.utility</h1><div class="highlight"><pre>
 <span class="k">def</span> <span class="nf">format_multivalue</span><span class="p">(</span>
         <span class="n">value</span><span class="p">:</span> <span class="n">Any</span><span class="p">,</span> <span class="n">multivalue</span><span class="p">:</span> <span class="nb">bool</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n">primary</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span><span class="p">,</span>
         <span class="n">sep</span><span class="p">:</span> <span class="n">Union</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="nb">tuple</span><span class="p">[</span><span class="nb">str</span><span class="p">]]</span> <span class="o">=</span> <span class="p">(</span><span class="s2">&quot;, &quot;</span><span class="p">,</span> <span class="s2">&quot; &amp; &quot;</span><span class="p">))</span> <span class="o">-&gt;</span> <span class="n">Union</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="nb">list</span><span class="p">[</span><span class="n">Any</span><span class="p">]]:</span>
-<span class="w">    </span>
+
 <span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>
-<span class="sd">    Format a field value based on whether multivalue for that field is </span>
+<span class="sd">    Format a field value based on whether multivalue for that field is</span>
 <span class="sd">    supported.</span>
 
 <span class="sd">    Parameters</span>
@@ -280,7 +281,7 @@ <h1>Source code for minim.utility</h1><div class="highlight"><pre>
 <span class="sd">        Field value to format.</span>
 
 <span class="sd">    multivalue : `bool`</span>
-<span class="sd">        Determines whether multivalue tags are supported. If </span>
+<span class="sd">        Determines whether multivalue tags are supported. If</span>
 <span class="sd">        :code:`False`, the items in `value` are concatenated using the</span>
 <span class="sd">        separator(s) specified in `sep`.</span>
 
@@ -289,11 +290,11 @@ <h1>Source code for minim.utility</h1><div class="highlight"><pre>
 <span class="sd">        `value` is a `list` and :code:`multivalue=False`.</span>
 
 <span class="sd">    sep : `str` or `tuple`, keyword-only, default: :code:`(&quot;, &quot;, &quot; &amp; &quot;)`</span>
-<span class="sd">        Separator(s) to use to concatenate multivalue tags. If a </span>
+<span class="sd">        Separator(s) to use to concatenate multivalue tags. If a</span>
 <span class="sd">        :code:`str` is provided, it is used to concatenate all values.</span>
 <span class="sd">        If a :code:`tuple` is provided, the first :code:`str` is used to</span>
-<span class="sd">        concatenate all values except the last, and the second </span>
-<span class="sd">        :code:`str` is used to append the final value. </span>
+<span class="sd">        concatenate all values except the last, and the second</span>
+<span class="sd">        :code:`str` is used to append the final value.</span>
 
 <span class="sd">    Returns</span>
 <span class="sd">    -------</span>
@@ -321,7 +322,7 @@ <h1>Source code for minim.utility</h1><div class="highlight"><pre>
     <span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Union</span><span class="p">[</span><span class="nb">float</span><span class="p">,</span> <span class="nb">list</span><span class="p">[</span><span class="nb">float</span><span class="p">],</span> <span class="s2">&quot;np.ndarray[float]&quot;</span><span class="p">]:</span>
 
 <span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>
-<span class="sd">    Compute the Gestalt or Ratcliff–Obershelp ratios, a measure of </span>
+<span class="sd">    Compute the Gestalt or Ratcliff–Obershelp ratios, a measure of</span>
 <span class="sd">    similarity, for strings with respect to a reference string.</span>
 
 <span class="sd">    Parameters</span>
@@ -336,8 +337,8 @@ <h1>Source code for minim.utility</h1><div class="highlight"><pre>
 <span class="sd">    -------</span>
 <span class="sd">    ratios : `float`, `list`, or `numpy.ndarray`</span>
 <span class="sd">        Gestalt or Ratcliff–Obershelp ratios. If `strings` is a `str`, a</span>
-<span class="sd">        `float` is returned. If `strings` is a `list`, a `numpy.ndarray` </span>
-<span class="sd">        is returned if NumPy is installed; otherwise, a `list` is </span>
+<span class="sd">        `float` is returned. If `strings` is a `list`, a `numpy.ndarray`</span>
+<span class="sd">        is returned if NumPy is installed; otherwise, a `list` is</span>
 <span class="sd">        returned.</span>
 <span class="sd">    &quot;&quot;&quot;</span>
 
@@ -371,15 +372,15 @@ <h1>Source code for minim.utility</h1><div class="highlight"><pre>
 <span class="sd">    -------</span>
 <span class="sd">    ratios : `float`, `list`, or `numpy.ndarray`</span>
 <span class="sd">        Levenshtein ratios. If `strings` is a `str`, a `float` is</span>
-<span class="sd">        returned. If `strings` is a `list`, a `numpy.ndarray` is </span>
+<span class="sd">        returned. If `strings` is a `list`, a `numpy.ndarray` is</span>
 <span class="sd">        returned if NumPy is installed; otherwise, a `list` is returned.</span>
 <span class="sd">    &quot;&quot;&quot;</span>
 
     <span class="k">if</span> <span class="ow">not</span> <span class="n">FOUND_LEVENSHTEIN</span><span class="p">:</span>
         <span class="n">emsg</span> <span class="o">=</span> <span class="p">(</span><span class="s2">&quot;The Levenshtein module was not found, so &quot;</span>
                 <span class="s2">&quot;minim.utility.levenshtein_ratio() is unavailable.&quot;</span><span class="p">)</span>
         <span class="k">raise</span> <span class="ne">ImportError</span><span class="p">(</span><span class="n">emsg</span><span class="p">)</span>
-    
+
     <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">strings</span><span class="p">,</span> <span class="nb">str</span><span class="p">):</span>
         <span class="k">return</span> <span class="n">Levenshtein</span><span class="o">.</span><span class="n">ratio</span><span class="p">(</span><span class="n">reference</span><span class="p">,</span> <span class="n">strings</span><span class="p">)</span>
     <span class="n">gen</span> <span class="o">=</span> <span class="p">(</span><span class="n">Levenshtein</span><span class="o">.</span><span class="n">ratio</span><span class="p">(</span><span class="n">reference</span><span class="p">,</span> <span class="n">s</span><span class="p">)</span> <span class="k">for</span> <span class="n">s</span> <span class="ow">in</span> <span class="n">strings</span><span class="p">)</span>
@@ -399,7 +400,7 @@ <h1>Source code for minim.utility</h1><div class="highlight"><pre>
         <div class="bottom-of-page">
           <div class="left-details">
             <div class="copyright">
-                Copyright &#169; 2023, Benjamin Ye
+                Copyright &#169; 2023–2024 Benjamin Ye
             </div>
             Made with <a href="https://www.sphinx-doc.org/">Sphinx</a> and <a class="muted-link" href="https://pradyunsg.me">@pradyunsg</a>'s
 

docs/.doctrees/api/minim.audio.FLACAudio.doctree

@@ -60,8 +60,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "audio_files = [f for f in (Path().resolve().parents[3] \n",
-    "                           / \"tests/data/previews\").glob(\"**/*\") \n",
+    "audio_files = [f for f in (Path().resolve().parents[3]\n",
+    "                           / \"tests/data/previews\").glob(\"**/*\")\n",
     "               if f.suffix == \".flac\"]"
    ]
   },
@@ -86,7 +86,7 @@
     "            if field in {\"artwork\", \"lyrics\"}:\n",
     "                if value:\n",
     "                    value = type(value)\n",
-    "            field = (field.upper() if field == \"isrc\" \n",
+    "            field = (field.upper() if field == \"isrc\"\n",
     "                     else field.replace(\"_\", \" \").capitalize())\n",
     "            print(f\"{field}: {value}\")"
    ]
@@ -325,14 +325,14 @@
     "itunes_track = itunes_results[\n",
     "    np.argmax(\n",
     "        utility.levenshtein_ratio(\n",
-    "            query, \n",
-    "            [f\"{r['artistName']} {r['trackName']}\".lower() \n",
+    "            query,\n",
+    "            [f\"{r['artistName']} {r['trackName']}\".lower()\n",
     "             for r in itunes_results]\n",
     "        )\n",
     "    )\n",
     "]\n",
     "itunes_album = client_itunes.lookup(itunes_track[\"collectionId\"])[\"results\"][0]\n",
-    "audio_file.set_metadata_using_itunes(itunes_track, album_data=itunes_album, \n",
+    "audio_file.set_metadata_using_itunes(itunes_track, album_data=itunes_album,\n",
     "                                     overwrite=True)\n",
     "print_metadata(audio_file)"
    ]
@@ -401,14 +401,14 @@
     "spotify_track = spotify_results[\n",
     "    np.argmax(\n",
     "        utility.levenshtein_ratio(\n",
-    "            query, \n",
-    "            [f\"{r['artists'][0]['name']} {r['name']}\".lower() \n",
+    "            query,\n",
+    "            [f\"{r['artists'][0]['name']} {r['name']}\".lower()\n",
     "             for r in spotify_results]\n",
     "        )\n",
     "    )\n",
     "]\n",
     "audio_file.set_metadata_using_spotify(\n",
-    "    spotify_track, \n",
+    "    spotify_track,\n",
     "    audio_features=client_spotify.get_track_audio_features(spotify_track[\"id\"])\n",
     ")\n",
     "print_metadata(audio_file)"
@@ -422,7 +422,7 @@
     "\n",
     "* searching for the track on TIDAL via `minim.tidal.PrivateAPI.search()`,\n",
     "* selecting the correct result by matching the ISRC,\n",
-    "* getting the track's composers and lyrics using `minim.tidal.PrivateAPI.get_track_composers()` and `minim.tidal.PrivateAPI.get_track_lyrics()`, respectively, and\n",
+    "* getting the track's composers using `minim.tidal.PrivateAPI.get_track_composers()`, and\n",
     "* populating the file handler's metadata with the JSON results using `minim.audio.FLACAudio.set_metadata_using_tidal()`."
    ]
   },
@@ -469,16 +469,15 @@
     "tidal_results = client_tidal.search(query)[\"tracks\"][\"items\"]\n",
     "tidal_track = next((r for r in tidal_results if r[\"isrc\"] == audio_file.isrc), None)\n",
     "tidal_composers = client_tidal.get_track_composers(tidal_track[\"id\"])\n",
-    "tidal_lyrics = client_tidal.get_track_lyrics(tidal_track[\"id\"])\n",
-    "audio_file.set_metadata_using_tidal(tidal_track, composers=tidal_composers, lyrics=tidal_lyrics)\n",
+    "audio_file.set_metadata_using_tidal(tidal_track, composers=tidal_composers)\n",
     "print_metadata(audio_file)"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The metadata for the track is now complete. (For this example, TIDAL did not have songwriting credits for the track. This happens sometimes when the track is not very popular.)\n",
+    "The metadata for the track is now practically complete. Lyrics are available through either `minim.spotify.PrivateLyricsService.get_lyrics()` or `minim.tidal.PrivateAPI.get_track_lyrics()` with active subscriptions. (For this example, TIDAL did not have songwriting credits for the track. This happens sometimes when the track is not very popular.)\n",
     "\n",
     "Don't forget to write the changes to file using `minim.audio.FLACAudio.write()`!"
    ]
@@ -604,7 +603,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The file has a poorly formatted copyright string and is missing lyrics, tempo, and cover art information. We can fix this by querying the three APIs as we did in the previous example, and overwrite the existing metadata:"
+    "The file has a poorly formatted copyright string and is missing tempo and cover art information. We can fix this by querying the three APIs as we did in the previous example, and overwrite the existing metadata:"
    ]
   },
   {
@@ -620,40 +619,38 @@
     "itunes_track = itunes_results[\n",
     "    np.argmax(\n",
     "        utility.levenshtein_ratio(\n",
-    "            query, \n",
-    "            [f\"{r['artistName']} {r['trackName']}\".lower() \n",
+    "            query,\n",
+    "            [f\"{r['artistName']} {r['trackName']}\".lower()\n",
     "             for r in itunes_results]\n",
     "        )\n",
     "    )\n",
     "]\n",
     "itunes_album = client_itunes.lookup(itunes_track[\"collectionId\"])[\"results\"][0]\n",
-    "audio_file.set_metadata_using_itunes(itunes_track, album_data=itunes_album, \n",
+    "audio_file.set_metadata_using_itunes(itunes_track, album_data=itunes_album,\n",
     "                                     overwrite=True)\n",
     "\n",
     "# Spotify Web API\n",
     "spotify_results = client_spotify.search(query, type=\"track\")[\"items\"]\n",
     "spotify_track = spotify_results[\n",
     "    np.argmax(\n",
     "        utility.levenshtein_ratio(\n",
-    "            query, \n",
-    "            [f\"{r['artists'][0]['name']} {r['name']}\".lower() \n",
+    "            query,\n",
+    "            [f\"{r['artists'][0]['name']} {r['name']}\".lower()\n",
     "             for r in spotify_results]\n",
     "        )\n",
     "    )\n",
     "]\n",
     "audio_file.set_metadata_using_spotify(\n",
-    "    spotify_track, \n",
+    "    spotify_track,\n",
     "    audio_features=client_spotify.get_track_audio_features(spotify_track[\"id\"])\n",
     ")\n",
     "\n",
     "# Private TIDAL API\n",
     "tidal_results = client_tidal.search(query)[\"tracks\"][\"items\"]\n",
-    "tidal_track = next((r for r in tidal_results if r[\"isrc\"] == audio_file.isrc), \n",
+    "tidal_track = next((r for r in tidal_results if r[\"isrc\"] == audio_file.isrc),\n",
     "                   None)\n",
     "tidal_composers = client_tidal.get_track_composers(tidal_track[\"id\"])\n",
-    "tidal_lyrics = client_tidal.get_track_lyrics(tidal_track[\"id\"])\n",
-    "audio_file.set_metadata_using_tidal(tidal_track, composers=tidal_composers, \n",
-    "                                    lyrics=tidal_lyrics)"
+    "audio_file.set_metadata_using_tidal(tidal_track, composers=tidal_composers)"
    ]
   },
   {