v3.0 (#171)

* Added vcr support for consistent tests * added vcr to tests * changed displaying types attributes as table in docs * add vcrpy to requirements * test tox.ini * Revert "test tox.ini" This reverts commit 33f096c. * removed except in tests * merge pr/109 into docs * merge pr/109 into docs * - added checking for the instrumental attribute in song info - added a couple comments * added instrumental attribute to types.Song * Revert "merge pr/109 into docs" This reverts commit c1221ae. * add Song.instrumental to docs * - add instrumental to to_dict - use dict.get to determine instrumental value * set retries to 3 * - Genius: removed checking instrumental in search_artist (genius.artist_songs doesn't return that key in song info) - types.Song: removed Song.instrumental - clean_str(): change normalization method to NKFC - docs/snippets: changes in snippets titles * add some description for charts * remove Song.instrumental references * added raising TypeError when no token/empty token is passed * - renamed album.songs to album.tracks - added Track type - docs: added 'release_data' to sort options in artist_songs - docs: added track docs * added importing Track from types * - fixed issues in Track - added __repr__ for track * - reconfigured get_user_token to accept code and state parameters - updated snippets - added InvalidState for when self.state and passed state don't match * - updated get_user_token docstring - moved InvalidState exception to errors.py * - removed test_get_user_token_client_flow as its unnecessary - fixed prompt_user to allow the code flow * - refactored get_user_token to allow use by token flow - added some tests for auth * removed redundant requirements.txt file * fixed tests issue * - added page_data endpoint to PublicAPI - added newline after docstring where missing * handle instance where error response might not be json * added test for page_data * fix typo in artist ID in example and test * fixed TypeError when instantiating PublicAPI directly with no token present in env vars fixed page_data for song which returned 404 * use built-in class name to define public api constructor * genius.lyrics: broke down urlthing parameter into song_url and song_id * added non-breaking space to punctuation words (genius adds this character before strings that their first letter is lower case) * linked to the snippets page in the usage page * Revert "add vcrpy to requirements" This reverts commit 92816fd. * Revert adding vcrpy to tests * Remove VCR from test_base.py * Remove VCR from test_genius.py and test_public_methods.py * Update version to 3.0.0 * added release notes for 3.0.0 * Set release date to 2021-02-08 Co-authored-by: ludehon <[email protected]> Co-authored-by: johnwmillr <[email protected]>
johnwmillr · Feb 9, 2021 · 4b89d42 · 4b89d42
1 parent 47109a3
commit 4b89d42
Show file tree

Hide file tree

Showing 34 changed files with 609 additions and 195 deletions.
diff --git a/docs/src/examples/snippets.rst b/docs/src/examples/snippets.rst
@@ -5,11 +5,11 @@ Snippets
 ==================
 Here are some snippets showcasing how the library can be used.
 
-- `Authenticating using OAuth2`_
 - `All the songs of an artist`_
 - `Artist's least popular song`_
-- `Getting songs that have a tag`
+- `Authenticating using OAuth2`_
 - `Getting song lyrics by URL or ID`_
+- `Getting songs by tag (genre)`_
 - `Getting the lyrics for all songs of a search`_
 - `Searching for a song by lyrics`_
 - `YouTube URL of artist's songs`_
@@ -23,7 +23,7 @@ Getting song lyrics by URL or ID
 
     # Using Song URL
     url = "https://genius.com/Andy-shauf-begin-again-lyrics"
-    genius.lyrics(url)
+    genius.lyrics(song_url=url)
 
     # Using Song ID
     # Requires an extra request to get song URL
@@ -101,8 +101,8 @@ Using :meth:`search_all <Genius.search_all>`:
     for hit in request['sections'][2]['hits']:
         print(hit['result']['title'])
 
-Getting songs that have a tag
------------------------------
+Getting songs by tag (genre)
+----------------------------
 Genius has the following main tags:
 ``rap``, ``pop``, ``r-b``, ``rock``, ``country``, ``non-music``
 To discover more tags, visit the `Genius Tags`_ page.
@@ -121,7 +121,7 @@ Genius probably has more than 1000 songs with the pop tag.
     while page:
         res = genius.tag('pop', page=page)
         for hit in res['hits']:
-            song_lyrics = genius.lyrics(hit['url'])
+            song_lyrics = genius.lyrics(song_url=hit['url'])
             lyrics.append(song_lyrics)
         page = res['next_page']
 
@@ -135,7 +135,7 @@ Getting the lyrics for all songs of a search
     songs = genius.search_songs('Begin Again Andy Shauf')
     for song in songs['hits']:
         url = song['result']['url']
-        song_lyrics = genius.lyrics(url)
+        song_lyrics = genius.lyrics(song_url=url)
         # id = song['result']['id']
         # song_lyrics = genius.lyrics(id)
         lyrics.append(song_lyrics)
@@ -170,7 +170,6 @@ URI will work (for example ``http://example.com/callback``)
 
     from lyricsgenius import OAuth2, Genius
 
-    # you can also use OAuth2.full_code_exchange()
     auth = OAuth2.client_only_app(
         'my_client_id',
         'my_redirect_uri',
@@ -199,14 +198,18 @@ Authenticating another user
         'my_client_id',
         'my_redirect_uri',
         'my_client_secret',
-        scope='all'
+        scope='all',
+        state='some_unique_value'
     )
 
     # this part is the same
     url_for_user = auth.url
     print('Redirecting you to ' + url_for_user)
-    redirected_url = 'https://example.com/?code=some_code'
-    token = auth.get_user_token(redirected_url)
+    
+    # If we were using Flask:
+    code = request.args.get('code')
+    state = request.args.get('state')
+    token = auth.get_user_token(code, state)
 
     genius = Genius(token)
 

diff --git a/docs/src/reference/types.rst b/docs/src/reference/types.rst
@@ -25,17 +25,67 @@ Classes
    :nosignatures:
 
    Stats
+   Track
 
 .. autoclass:: Stats
     :members:
     :member-order: bysource
     :no-show-inheritance:
 
+.. autoclass:: Track
+    :members:
+    :member-order: bysource
+    :no-show-inheritance:
+
 
 Album
 ------
 An album from Genius that has the album's songs and their lyrics.
 
+Attributes
+^^^^^^^^^^
+.. list-table::
+   :header-rows: 1
+
+   * - Attribute
+     - Type
+
+   * - _type
+     - :obj:`str`
+
+   * - api_path
+     - :obj:`str`
+
+   * - artist
+     - :class:`Artist`
+
+   * - cover_art_thumbnail_url
+     - :obj:`str`
+
+   * - cover_art_url
+     - :obj:`str`
+
+   * - full_title
+     - :obj:`str`
+
+   * - id
+     - :obj:`int`
+
+   * - name
+     - :obj:`str`
+
+   * - name_with_artist
+     - :obj:`str`
+
+   * - release_date_components
+     - :class:`datetime`
+
+   * - tracks
+     - :obj:`list` of :class:`Track`
+
+   * - url
+     - :obj:`str`
+
 
 Methods
 ^^^^^^^^
@@ -59,6 +109,41 @@ Artist
 The Artist object which holds the details of the artist
 and the `Song`_ objects of that artist.
 
+Attributes
+^^^^^^^^^^
+.. list-table::
+   :header-rows: 1
+
+   * - Attribute
+     - Type
+
+
+   * - api_path
+     - :obj:`str`
+
+   * - header_image_url
+     - :obj:`str`
+
+   * - id
+     - :obj:`int`
+
+   * - image_url
+     - :obj:`str`
+
+   * - is_meme_verified
+     - :obj:`bool`
+
+   * - is_verified
+     - :obj:`bool`
+
+   * - name
+     - :obj:`str`
+
+   * - songs
+     - :obj:`list`
+
+   * - url
+     - :obj:`str`
 
 Methods
 ^^^^^^^^
@@ -83,6 +168,72 @@ Song
 ----
 This is the Song object which holds the details of the song.
 
+Attributes
+^^^^^^^^^^
+.. list-table::
+   :header-rows: 1
+
+   * - Attribute
+     - Type
+
+
+   * - annotation_count
+     - :obj:`int`
+
+   * - api_path
+     - :obj:`str`
+
+   * - artist
+     - :obj:`str`
+
+   * - full_title
+     - :obj:`str`
+
+   * - header_image_thumbnail_url
+     - :obj:`str`
+
+   * - header_image_url
+     - :obj:`str`
+
+   * - id
+     - :obj:`int`
+
+   * - lyrics
+     - :obj:`str`
+
+   * - lyrics_owner_id
+     - :obj:`int`
+
+   * - lyrics_state
+     - :obj:`str`
+
+   * - path
+     - :obj:`str`
+
+   * - primary_artist
+     - :class:`Artist`
+
+   * - pyongs_count
+     - :obj:`int`
+
+   * - song_art_image_thumbnail_url
+     - :obj:`str`
+
+   * - song_art_image_url
+     - :obj:`str`
+
+   * - stats
+     - :class:`Stats`
+
+   * - title
+     - :obj:`str`
+
+   * - title_with_featured
+     - :obj:`str`
+
+   * - url
+     - :obj:`str`
+
 Methods
 ^^^^^^^^
 .. autosummary::

diff --git a/docs/src/release_notes.rst b/docs/src/release_notes.rst
@@ -3,6 +3,56 @@
 
 Release notes
 =============
+3.0.0 (2021-02-08)
+------------------
+New
+***
+
+-  All requests now go through the ``Sender`` object. This provides
+   features such as retries ``genius.retries`` and handling HTTP and
+   timeout errors. For more info have a look at the guide about `request
+   error handling`_.
+-  Added ``OAuth2`` class to help with OAuth2 authentication.
+-  Added ``PublicAPI`` class to allow accessing methods of the public
+   API (genius.com/api). Check `this page`_ for a list of available
+   methods.
+-  Added the ``Album`` type and the ``genius.search_album()`` method.
+-  Added the ``genius.tag()`` method to get songs by tag.
+-  All API endpoints are now supported (e.g. ``upvote_annotation``).
+-  New additions to the docs.
+
+Changed
+*******
+
+-  ``GENIUS_CLIENT_ACCESS_TOKEN`` env var has been renamed to
+   ``GENIUS_ACCESS_TOKEN``.
+-  ``genius.client_access_token`` has been renamed to
+   ``genius.access_token``.
+-  ``genius.search_song()`` will also accept ``song_id``.
+-  Lyrics won't be fetched for instrumental songs and their lyrics will
+   be set to ``""``. You can check to see if a song is instrumental
+   using ``Song.instrumental``.
+-  Renamed all interface methods to remove redundant ``get_``
+   (``genius.get_song`` is now ``genius.song``).
+-  Renamed the lyrics method to ``genius.lyrics()`` to allow use by
+   users. It accepts song URLs and song IDs.
+-  Reformatted the types. Some attributes won't be available anymore.
+   More info on the `types page`_.
+-  ``save_lyrics()`` will save songs with ``utf8`` encoding when
+   ``extension='txt'``.
+-  Using ``Genius()`` will check for the env var
+   ``GENIUS_ACCESS_TOKEN``.
+
+Other (CI, etc)
+***************
+
+-  Bumped ``Sphinx`` to 3.3.0
+
+.. _request error handling: https://lyricsgenius.readthedocs.io/en/master/other_guides.html#request-errors
+.. _this page: https://lyricsgenius.readthedocs.io/en/latest/reference/genius.html
+.. _types page: https://lyricsgenius.readthedocs.io/en/latest/reference/types.html#types
+
+
 2.0.2 (2020-09-26)
 ------------------
 Added
@@ -15,6 +65,7 @@ Added
    :meth:`Artist.save_lyrics <types.Artist.save_lyrics>`
    and :meth:`Artist.to_json <types.Artist.to_json>`
 
+
 2.0.1 (2020-09-20)
 ------------------
 Changed

diff --git a/docs/src/usage.rst b/docs/src/usage.rst
@@ -87,7 +87,7 @@ Search for five songs by ‘The Beatles’ and save the lyrics:
    python3 -m lyricsgenius artist "The Beatles" --max-songs 5 --save
 
 
-There also examples under the docs of some methods.
+You might also like checking out the :ref:`snippets` page. 
 
 
 .. toctree::

diff --git a/lyricsgenius/__init__.py b/lyricsgenius/__init__.py
@@ -14,4 +14,4 @@
 __url__ = 'https://github.com/johnwmillr/LyricsGenius'
 __description__ = 'A Python wrapper around the Genius API'
 __license__ = 'MIT'
-__version__ = '2.0.2'
+__version__ = '3.0.0'
diff --git a/lyricsgenius/api/api.py b/lyricsgenius/api/api.py
@@ -312,7 +312,7 @@ def artist_songs(self, artist_id, per_page=None, page=None, sort='title'):
         Args:
             artist_id (:obj:`int`): Genius artist ID
             sort (:obj:`str`, optional): Sorting preference.
-                Either based on 'title' or 'popularity'.
+                Either based on 'title', 'popularity' or 'release_date'.
             per_page (:obj:`int`, optional): Number of results to
                 return per request. It can't be more than 50.
             page (:obj:`int`, optional): Paginated offset (number of the page).
@@ -526,11 +526,17 @@ def __init__(
         retries=0,
         **kwargs
     ):
+
+        # If PublicAPI was instantiated directly
+        # there is no need for a token anymore
+        public_api_constructor = False if self.__class__.__name__ == 'Genius' else True
+
         # Genius PublicAPI Constructor
         super().__init__(
             response_format=response_format,
             timeout=timeout,
             sleep_time=sleep_time,
             retries=retries,
+            public_api_constructor=public_api_constructor,
             **kwargs
         )