diff --git a/docs/index.rst b/docs/index.rst index a6fa61b8..0528ea16 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -76,32 +76,77 @@ API `_ documentation. Installation ============ -Install or upgrade *Spotipy* with:: +**Installing Spotipy on Windows**: + +- Install Python: Download and install Python from the official Python website (https://www.python.org/downloads/). + +- Install Spotipy: Open a command prompt and run pip install spotipy. +Open command prompt and run the following:: + + pip install spotipy + +- Authenticate your app: Register your app on the Spotify Developer Dashboard and obtain a client ID and client secret. + +**Installing Spotipy on macOS**: + + +- Install Homebrew: Install Homebrew, a package manager for macOS. + +- Run the followng command:: + + /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" + +- Install Python: Run brew install python in the terminal:: + + brew install python + +- Install Spotipy: Run pip install spotipy in the terminal:: + + pip install spotipy + +- Authenticate your app: Register your app on the Spotify Developer Dashboard and obtain a client ID and client secret. + +**Installing Spotipy on Linux**: + +- Install Python: Use your Linux distribution's package manager to install Python using the following command:: + + sudo apt-get install python3 + +- Install pip: Use your Linux distribution's package manager to install pip using the command:: + + sudo apt-get install python3-pip + +- Install Spotipy: Run pip install spotipy in the terminal:: + + pip install spotipy + +- Authenticate your app: Register your app on the Spotify Developer Dashboard and obtain a client ID and client secret. + + + .. Install or upgrade *Spotipy* with:: pip install spotipy --upgrade -Or you can get the source from github at https://github.com/plamere/spotipy +You can get the source from github at https://github.com/plamere/spotipy -Getting Started +Getting Started with Spotipy =============== -All methods require user authorization. You will need to register your app at -`My Dashboard `_ -to get the credentials necessary to make authorized calls -(a *client id* and *client secret*). +Before you can use Spotipy, there are a few things you need to do: -*Spotipy* supports two authorization flows: +Register your app: To make authorized calls to the Spotify Web API, you need to register your app and obtain a client ID and client secret. You can register your app at My Dashboard _. Make sure to keep your client ID and client secret secure. - - The **Authorization Code flow** This method is suitable for long-running applications +Choose an authorization flow: Spotipy supports two authorization flows: the Authorization Code flow and the Client Credentials flow. Choose the one that's suitable for your application. + - **Authorization Code flow** This method is suitable for long-running applications which the user logs into once. It provides an access token that can be refreshed. - .. note:: Requires you to add a redirect URI to your application at + .. note:: This method requires you to add a redirect URI to your application at `My Dashboard `_. See `Redirect URI`_ for more details. - - The **Client Credentials flow** The method makes it possible - to authenticate your requests to the Spotify Web API and to obtain - a higher rate limit than you would with the Authorization Code flow. + - **The Client Credentials flow** This is suitable for short-lived applications that don't require user permission. It makes it possible to authenticate your requests to the Spotify Web API and to obtain a higher rate limit than you would with the Authorization Code flow. + +Before you can use Spotipy's methods, you need to authorize your app by registering it at My Dashboard _. This will give you a *client id* and *client secret* that you'll need to use in your code. Authorization Code Flow @@ -288,6 +333,23 @@ If you think you've found a bug, let us know at `Spotify Issues `_ +Troubleshooting +======= + +This section aims to address common issues that users may encounter while working with Spotipy and provide practical solutions to resolve them. + +**Authentication errors**: Make sure that you have correctly set up your credentials and are using the correct authorization flow to avoid authenthication erros. Ensure that your client ID and client secret are correct and that you have added the appropriate redirect URIs to your Spotify Developer Dashboard. + +**Playlist creation errors**: If you're having trouble creating a playlist, check that your user ID is correct, and that the user has the necessary permissions to create playlists. Additionally, make sure that your code is formatted correctly, along with the fact that you are sending the appropriate request to the Spotify API. + +**Search errors**: If you're having problems when searching for music, make sure that you are providing the correct search query parameters. You should also check the Spotify API documentation to ensure that the endpoint you're using supports the search parameters you are providing. + +**API changes**: Sometimes the Spotify API may change, causing errors in your application. To fix this, check the Spotify API documentation to see if there are any changes that may affect your code and update it accordingly. + +**Rate limiting**: Making too many requests to the Spotify API within a short period of time, will result in you hitting the rate limit. To prevent this, use caching and backoff mechanisms in your code + +**Authorization errors**: If you encounter authorization errors, make sure that you have correctly set up your credentials and are using the correct authorization flow. You may also need to check if your access token has expired and obtain a new one if necessary. + Contribute ========== diff --git a/examples/artist_recommendations.py b/examples/artist_recommendations.py index 40a95a23..d1f75e3f 100644 --- a/examples/artist_recommendations.py +++ b/examples/artist_recommendations.py @@ -19,6 +19,12 @@ def get_args(): return parser.parse_args() +def get_related_artists(artist_id): + results = sp.artist_related_artists(artist_id) + related_artists = [artist['name'] for artist in results['artists']] + return related_artists + + def get_artist(name): results = sp.search(q='artist:' + name, type='artist') items = results['artists']['items'] diff --git a/setup.py b/setup.py index dd1ab177..9de919de 100644 --- a/setup.py +++ b/setup.py @@ -1,32 +1,37 @@ +# Import required packages from setuptools import setup -with open("README.md", "r") as f: - long_description = f.read() +# Open the README file and read the contents into a variable +with open("README.md", "r") as readme_file: + long_description = readme_file.read() -test_reqs = [ - 'mock==2.0.0' +# Define lists of test and documentation requirements +test_requirements = [ + "mock==2.0.0" ] -doc_reqs = [ - 'Sphinx>=1.5.2' +doc_requirements = [ + "Sphinx>=1.5.2" ] -extra_reqs = { - 'doc': doc_reqs, - 'test': test_reqs +# Define a dictionary of extra requirements +extra_requirements = { + "doc": doc_requirements, + "test": test_requirements } +# Configure the setup function with required and optional parameters setup( - name='spotipy', - version='2.23.0', - description='A light weight Python library for the Spotify Web API', + name="spotipy", + version="2.23.0", + description="A lightweight Python library for the Spotify Web API", long_description=long_description, long_description_content_type="text/markdown", author="@plamere", author_email="paul@echonest.com", - url='https://spotipy.readthedocs.org/', + url="https://spotipy.readthedocs.org/", project_urls={ - 'Source': 'https://github.com/plamere/spotipy', + "Source": "https://github.com/plamere/spotipy", }, install_requires=[ "redis>=3.5.3", @@ -35,7 +40,8 @@ "six>=1.15.0", "urllib3>=1.26.0" ], - tests_require=test_reqs, - extras_require=extra_reqs, - license='MIT', - packages=['spotipy']) + tests_require=test_requirements, + extras_require=extra_requirements, + license="MIT", + packages=["spotipy"] +) diff --git a/tests/unit/test_search.py b/tests/unit/test_search.py new file mode 100644 index 00000000..387903dd --- /dev/null +++ b/tests/unit/test_search.py @@ -0,0 +1,45 @@ +import unittest +from spotipy.oauth2 import SpotifyClientCredentials +import spotipy +import traceback + + +class artist_info_test_case(unittest.TestCase): + def test_artist_info_with_search_str(self): + search_str = 'Radiohead' + sp = spotipy.Spotify(client_credentials_manager=SpotifyClientCredentials( + client_id='id_client', client_secret='secret_client')) + result = sp.search(search_str) + + # Assert that the 'tracks' key is present in the result + self.assertIn('tracks', result) + + # Assert that the 'items' key is present in the 'tracks' dictionary + self.assertIn('items', result['tracks']) + + # Assert that the 'items' list is not empty + self.assertTrue(len(result['tracks']['items']) > 0) + + +class exception_test_case(unittest.TestCase): + def test_empty_search_query(self): + search_str = "Radiohead" + sp = spotipy.Spotify(client_credentials_manager=SpotifyClientCredentials( + client_id='id_client', client_secret='secret_client')) + result = sp.search(search_str) + + # Assert that the 'tracks' key is present in the result + self.assertIn('tracks', result) + + def test_invalid_search_query(self): + search_str = "1234" + sp = spotipy.Spotify(client_credentials_manager=SpotifyClientCredentials( + client_id='id_client', client_secret='secret_client')) + result = sp.search(search_str) + + # Make sure at least some tracks are returned + self.assertNotEqual(result['tracks']['total'], 0) + + +if __name__ == '__main__': + unittest.main(verbosity=2)