From 07971ff10d022b4a719de2127f14681449daa00d Mon Sep 17 00:00:00 2001 From: Peter Schorn Date: Sat, 10 Apr 2021 06:37:22 -0500 Subject: [PATCH] V3 (#665) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Added an exception clause that catches `FileNotFoundError` and logs a debug message in `SpotifyOAuth.get_cached_token`, `SpotifyPKCE.get_cached_token` and `SpotifyImplicitGrant.get_cached_token`. * Changed docs for `auth` parameter of `Spotify.init` to `access token` instead of `authorization token`. In issue #599, a user confused the access token with the authorization code. * Updated CHANGELOG.md * Removed `FileNotFoundError` because it does not exist in python 2.7 (*sigh*) and replaced it with a call to `os.path.exists`. * Replaced ` os.path.exists` with `error.errno == errno.ENOENT` to supress errors when the cache file does not exist. * Changed docs for `search` to mention that you can provide multiple multiple types to search for. The query parameters of requests are now logged. Added log messages for when the access token and refresh tokens are retrieved and when they are refreshed. Other small grammar fixes. * Removed duplicate word "multiple" from CHANGELOG * * Fixed the bugs in `SpotifyOAuth.refresh_access_token` and `SpotifyPKCE.refresh_access_token` which raised the incorrect exception upon receiving an error response from the server. This addresses #645. * Fixed a bug in `RequestHandler.do_GET` in which the non-existent `state` attribute of `SpotifyOauthError` is accessed. This bug occurs when the user clicks "cancel" in the permissions dialog that opens in the browser. * Cleaned up the documentation for `SpotifyClientCredentials.__init__`, `SpotifyOAuth.__init__`, and `SpotifyPKCE.__init__`. * Removed unneeded import * Added cache handler to `SpotifyClientCredentials` and fixed a bug in refresh tokens methods that raised the wrong exception (#655) * Added an exception clause that catches `FileNotFoundError` and logs a debug message in `SpotifyOAuth.get_cached_token`, `SpotifyPKCE.get_cached_token` and `SpotifyImplicitGrant.get_cached_token`. * Changed docs for `auth` parameter of `Spotify.init` to `access token` instead of `authorization token`. In issue #599, a user confused the access token with the authorization code. * Updated CHANGELOG.md * Removed `FileNotFoundError` because it does not exist in python 2.7 (*sigh*) and replaced it with a call to `os.path.exists`. * Replaced ` os.path.exists` with `error.errno == errno.ENOENT` to supress errors when the cache file does not exist. * Changed docs for `search` to mention that you can provide multiple multiple types to search for. The query parameters of requests are now logged. Added log messages for when the access token and refresh tokens are retrieved and when they are refreshed. Other small grammar fixes. * Removed duplicate word "multiple" from CHANGELOG * * Fixed the bugs in `SpotifyOAuth.refresh_access_token` and `SpotifyPKCE.refresh_access_token` which raised the incorrect exception upon receiving an error response from the server. This addresses #645. * Fixed a bug in `RequestHandler.do_GET` in which the non-existent `state` attribute of `SpotifyOauthError` is accessed. This bug occurs when the user clicks "cancel" in the permissions dialog that opens in the browser. * Cleaned up the documentation for `SpotifyClientCredentials.__init__`, `SpotifyOAuth.__init__`, and `SpotifyPKCE.__init__`. * Removed unneeded import Co-authored-by: Stéphane Bruckert * Made `CacheHandler` an abstract base class Added: * `Scope` - An enum which contains all of the authorization scopes (see [here](https://github.com/plamere/spotipy/issues/652#issuecomment-797461311)). * Added the following endpoints * `Spotify.current_user_saved_episodes` * `Spotify.current_user_saved_episodes_add` * `Spotify.current_user_saved_episodes_delete` * `Spotify.current_user_saved_episodes_contains` * `Spotify.available_markets * Fixed formatting issues. Removed python 2.7 from github workflows. * Added python 3.9 to github workflows. The type hints for set now uses the generic typing.Set instead of builtins.set. * Changed f-string to percent-formatted string. * Fixed the duplicate "###Changed" section in the change log. Co-authored-by: Stéphane Bruckert --- .github/workflows/pythonapp.yml | 3 +- CHANGELOG.md | 24 ++++++--- spotipy/__init__.py | 1 + spotipy/cache_handler.py | 15 +++--- spotipy/oauth2.py | 53 +++++++++++++++++-- spotipy/scope.py | 85 +++++++++++++++++++++++++++++++ spotipy/util.py | 17 ------- tests/unit/test_scopes.py | 90 +++++++++++++++++++++++++++++++++ 8 files changed, 251 insertions(+), 37 deletions(-) create mode 100644 spotipy/scope.py create mode 100644 tests/unit/test_scopes.py diff --git a/.github/workflows/pythonapp.yml b/.github/workflows/pythonapp.yml index a3d5dcc7..81bc9643 100644 --- a/.github/workflows/pythonapp.yml +++ b/.github/workflows/pythonapp.yml @@ -8,7 +8,8 @@ jobs: runs-on: ubuntu-20.04 strategy: matrix: - python-version: ["2.7", "3.6", "3.7", "3.8", "3.9", "3.10"] + python-version: [3.5, 3.6, 3.7, 3.8, 3.9, 3.10] + steps: - uses: actions/checkout@v2 - name: Set up Python ${{ matrix.python-version }} diff --git a/CHANGELOG.md b/CHANGELOG.md index ecb1974c..4c88c354 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,18 +5,30 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - ## Unreleased [3.0.0-alpha] While this is unreleased, please only add v3 features here. Rebasing master onto v3 doesn't require a changelog update. +### Added + +* `Scope` - An enum which contains all of the authorization scopes (see [here](https://github.com/plamere/spotipy/issues/652#issuecomment-797461311)). + +* Added the following endpoints + * `Spotify.current_user_saved_episodes` + * `Spotify.current_user_saved_episodes_add` + * `Spotify.current_user_saved_episodes_delete` + * `Spotify.current_user_saved_episodes_contains` + * `Spotify.available_markets` + ### Changed -Modified the return structure of the `audio_features` function (wrapping the [Get Audio Features for Several Tracks](https://developer.spotify.com/documentation/web-api/reference/#endpoint-get-several-audio-features) API) to conform to the return structure of similar APIs, such as: - - [Get Several Tracks](https://developer.spotify.com/documentation/web-api/reference/#endpoint-get-several-tracks) - - [Get Multiple Artists](https://developer.spotify.com/documentation/web-api/reference/#endpoint-get-multiple-artists) - - [Get Multiple Albums](https://developer.spotify.com/documentation/web-api/reference/#endpoint-get-multiple-albums) -The functions wrapping these APIs do not unwrap the single key JSON response, and this is currently the only function that does this. + +* Made `CacheHandler` an abstract base class + +* Modified the return structure of the `audio_features` function (wrapping the [Get Audio Features for Several Tracks](https://developer.spotify.com/documentation/web-api/reference/#endpoint-get-several-audio-features) API) to conform to the return structure of the similar methods listed below. The functions wrapping these APIs do not unwrap the single key JSON response, and this is currently the only function that does this. + * [Get Several Tracks](https://developer.spotify.com/documentation/web-api/reference/#endpoint-get-several-tracks) + * [Get Multiple Artists](https://developer.spotify.com/documentation/web-api/reference/#endpoint-get-multiple-artists) + * [Get Multiple Albums](https://developer.spotify.com/documentation/web-api/reference/#endpoint-get-multiple-albums) ## Unreleased [2.x.x] diff --git a/spotipy/__init__.py b/spotipy/__init__.py index 7f3d8599..bb2e2015 100644 --- a/spotipy/__init__.py +++ b/spotipy/__init__.py @@ -3,3 +3,4 @@ from .exceptions import * # noqa from .oauth2 import * # noqa from .util import * # noqa +from .scope import * # noqa diff --git a/spotipy/cache_handler.py b/spotipy/cache_handler.py index 2645f25b..1f4686eb 100644 --- a/spotipy/cache_handler.py +++ b/spotipy/cache_handler.py @@ -13,33 +13,32 @@ from spotipy.util import CLIENT_CREDS_ENV_VARS from redis import RedisError +from abc import ABC, abstractmethod logger = logging.getLogger(__name__) -class CacheHandler(): +class CacheHandler(ABC): """ An abstraction layer for handling the caching and retrieval of authorization tokens. - Custom extensions of this class must implement get_cached_token - and save_token_to_cache methods with the same input and output - structure as the CacheHandler class. + Clients are expected to subclass this class and override the + get_cached_token and save_token_to_cache methods with the same + type signatures of this class. """ + @abstractmethod def get_cached_token(self): """ Get and return a token_info dictionary object. """ - # return token_info - raise NotImplementedError() + @abstractmethod def save_token_to_cache(self, token_info): """ Save a token_info dictionary object to the cache and return None. """ - raise NotImplementedError() - return None class CacheFileHandler(CacheHandler): diff --git a/spotipy/oauth2.py b/spotipy/oauth2.py index 631a8658..bbc7c804 100644 --- a/spotipy/oauth2.py +++ b/spotipy/oauth2.py @@ -24,7 +24,11 @@ from six.moves.urllib_parse import parse_qsl, urlparse from spotipy.cache_handler import CacheFileHandler, CacheHandler -from spotipy.util import CLIENT_CREDS_ENV_VARS, get_host_port, normalize_scope + +from spotipy.util import CLIENT_CREDS_ENV_VARS, get_host_port +from spotipy.scope import Scope +from typing import Iterable +import re logger = logging.getLogger(__name__) @@ -72,6 +76,7 @@ def _ensure_value(value, env_key): class SpotifyAuthBase(object): + def __init__(self, requests_session): if isinstance(requests_session, requests.Session): self._session = requests_session @@ -83,7 +88,40 @@ def __init__(self, requests_session): self._session = api def _normalize_scope(self, scope): - return normalize_scope(scope) + """ + Accepts a string of scopes, or an iterable with elements of type + `Scope` or `str` and returns a space-separated string of scopes. + Returns `None` if the argument is `None`. + """ + + # TODO: do we need to sort the scopes? + + if isinstance(scope, str): + # allow for any separator(s) between the scopes other than a word + # character or a hyphen + scopes = re.split(pattern=r"[^\w-]+", string=scope) + return " ".join(sorted(scopes)) + + if isinstance(scope, Iterable): + + # Assume all of the iterable's elements are of the same type. + # If the iterable is empty, then return None. + first_element = next(iter(scope), None) + + if isinstance(first_element, str): + return " ".join(sorted(scope)) + if isinstance(first_element, Scope): + return Scope.make_string(scope) + if first_element is None: + return "" + + elif scope is None: + return None + + raise TypeError( + "Unsupported type for scopes: %s. Expected either a string of scopes, or " + "an Iterable with elements of type `Scope` or `str`." % type(scope) + ) @property def client_id(self): @@ -308,7 +346,11 @@ def __init__( * client_secret: Must be supplied or set as environment variable * redirect_uri: Must be supplied or set as environment variable * state: Optional, no verification is performed - * scope: Optional, either a list of scopes or comma separated string of scopes. + * scope: Optional, either a string of scopes, or an iterable with elements of type + `Scope` or `str`. E.g., + {Scope.user_modify_playback_state, Scope.user_library_read} + + iterable of scopes or comma separated string of scopes. e.g, "playlist-read-private,playlist-read-collaborative" * cache_path: (deprecated) Optional, will otherwise be generated (takes precedence over `username`) @@ -1050,8 +1092,9 @@ def __init__(self, * client_id: Must be supplied or set as environment variable * redirect_uri: Must be supplied or set as environment variable * state: May be supplied, no verification is performed - * scope: Optional, either a list of scopes or comma separated string of scopes. - e.g, "playlist-read-private,playlist-read-collaborative" + * scope: Optional, either a string of scopes, or an iterable with elements of type + `Scope` or `str`. E.g., + {Scope.user_modify_playback_state, Scope.user_library_read} * cache_handler: An instance of the `CacheHandler` class to handle getting and saving cached authorization tokens. May be supplied, will otherwise use `CacheFileHandler`. diff --git a/spotipy/scope.py b/spotipy/scope.py new file mode 100644 index 00000000..79a4adc3 --- /dev/null +++ b/spotipy/scope.py @@ -0,0 +1,85 @@ +# -*- coding: utf-8 -*- + +__all__ = ["Scope"] + +from enum import Enum +import re +from typing import Iterable, Set + + +class Scope(Enum): + """ + The Spotify authorization scopes + + Create a Scope from a string: + + scope = Scope("playlist-modify-private") + + Create a set of scopes: + + scopes = { + Scope.user_read_currently_playing, + Scope.playlist_read_collaborative, + Scope.playlist_modify_public + } + """ + + user_read_currently_playing = "user-read-currently-playing" + playlist_read_collaborative = "playlist-read-collaborative" + playlist_modify_private = "playlist-modify-private" + user_read_playback_position = "user-read-playback-position" + user_library_modify = "user-library-modify" + user_top_read = "user-top-read" + user_read_playback_state = "user-read-playback-state" + user_read_email = "user-read-email" + ugc_image_upload = "ugc-image-upload" + user_read_private = "user-read-private" + playlist_modify_public = "playlist-modify-public" + user_library_read = "user-library-read" + streaming = "streaming" + user_read_recently_played = "user-read-recently-played" + user_follow_read = "user-follow-read" + user_follow_modify = "user-follow-modify" + app_remote_control = "app-remote-control" + playlist_read_private = "playlist-read-private" + user_modify_playback_state = "user-modify-playback-state" + + @staticmethod + def all() -> Set['Scope']: + """Returns all of the authorization scopes""" + + return set(Scope) + + @staticmethod + def make_string(scopes: Iterable['Scope']) -> str: + """ + Converts an iterable of scopes to a space-separated string. + + * scopes: An iterable of scopes. + + returns: a space-separated string of scopes + """ + return " ".join([scope.value for scope in scopes]) + + @staticmethod + def from_string(scope_string: str) -> Set['Scope']: + """ + Converts a string of (usuallly space-separated) scopes into a + set of scopes + + Any scope-strings that do not match any of the known scopes are + ignored. + + * scope_string: a string of scopes + + returns: a set of scopes. + """ + scope_string_list = re.split(pattern=r"[^\w-]+", string=scope_string) + scopes = set() + for scope_string in sorted(scope_string_list): + try: + scope = Scope(scope_string) + scopes.add(scope) + except ValueError: + pass + return scopes diff --git a/spotipy/util.py b/spotipy/util.py index b949a618..a14815a7 100644 --- a/spotipy/util.py +++ b/spotipy/util.py @@ -7,7 +7,6 @@ import logging import os import warnings - import spotipy LOGGER = logging.getLogger(__name__) @@ -117,19 +116,3 @@ def get_host_port(netloc): port = None return host, port - - -def normalize_scope(scope): - if scope: - if isinstance(scope, str): - scopes = scope.split(',') - elif isinstance(scope, list) or isinstance(scope, tuple): - scopes = scope - else: - raise Exception( - "Unsupported scope value, please either provide a list of scopes, " - "or a string of scopes separated by commas" - ) - return " ".join(sorted(scopes)) - else: - return None diff --git a/tests/unit/test_scopes.py b/tests/unit/test_scopes.py new file mode 100644 index 00000000..dcaefe87 --- /dev/null +++ b/tests/unit/test_scopes.py @@ -0,0 +1,90 @@ +from unittest import TestCase +from spotipy.scope import Scope +from spotipy.oauth2 import SpotifyAuthBase + + +class SpotipyScopeTest(TestCase): + + @classmethod + def setUpClass(cls): + cls.auth_manager = SpotifyAuthBase(requests_session=True) + + def normalize_scope(self, scope): + return self.auth_manager._normalize_scope(scope) + + def test_empty_scope(self): + scopes = set() + scope_string = Scope.make_string(scopes) + + normalized_scope_string = self.normalize_scope(scopes) + normalized_scope_string_2 = self.normalize_scope(scope_string) + + self.assertEqual(scope_string, "") + self.assertEqual(normalized_scope_string, "") + self.assertEqual(normalized_scope_string_2, "") + + converted_scopes = Scope.from_string(scope_string) + self.assertEqual(converted_scopes, set()) + + def test_scopes(self): + scopes = { + Scope.playlist_modify_public, + Scope.playlist_read_collaborative, + Scope.user_read_playback_state, + Scope.ugc_image_upload + } + normalized_scope_string = self.normalize_scope(scopes) + scope_string = Scope.make_string(scopes) + self.assertEqual(scope_string, normalized_scope_string) + + normalized_scope_string_2 = self.normalize_scope(scope_string) + + converted_scopes = Scope.from_string(scope_string) + normalized_converted_scope = Scope.from_string(normalized_scope_string) + normalized_converted_scope_2 = Scope.from_string(normalized_scope_string_2) + self.assertEqual(scopes, converted_scopes) + self.assertEqual(scopes, normalized_converted_scope) + self.assertEqual(scopes, normalized_converted_scope_2) + + def test_single_scope(self): + scope_string = "user-modify-playback-state" + scope = Scope(scope_string) + self.assertEqual(scope, Scope.user_modify_playback_state) + self.assertEqual(scope_string, scope.value) + + def test_scope_string(self): + scope_string = ( + "user-read-currently-playing playlist-read-collaborative,user-library-read " + "playlist-read-private user-read-email" + ) + expected_scopes = { + Scope.user_read_currently_playing, + Scope.playlist_read_collaborative, + Scope.user_library_read, + Scope.playlist_read_private, + Scope.user_read_email + } + parsed_scopes = Scope.from_string(scope_string) + normalized_scope_string = self.normalize_scope(scope_string) + normalized_parsed_scopes = Scope.from_string(normalized_scope_string) + self.assertEqual(parsed_scopes, expected_scopes) + self.assertEqual(normalized_parsed_scopes, expected_scopes) + + def test_invalid_types(self): + + numbers = [1, 2, 3] + with self.assertRaises(TypeError): + self.normalize_scope(numbers) + + with self.assertRaises(TypeError): + self.normalize_scope(True) + + def test_normalize_scope(self): + + normalized_scope_string = self.normalize_scope([]) + self.assertEqual(normalized_scope_string, "") + + normalized_scope_string_2 = self.normalize_scope(()) + self.assertEqual(normalized_scope_string_2, "") + + self.assertIsNone(self.normalize_scope(None))