Merge branch 'master' into master

.github/workflows/integration_tests.yml

@@ -11,9 +11,9 @@ jobs:
       SPOTIPY_CLIENT_SECRET: ${{ secrets.SPOTIPY_CLIENT_SECRET }}
       PYTHON_VERSION: "3.10"
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
       - name: Set up Python ${{ env.PYTHON_VERSION }}
-        uses: actions/setup-python@v1
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ env.PYTHON_VERSION }}
       - name: Install dependencies

.github/workflows/publish.yml

@@ -13,9 +13,9 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: "3.x"
       - name: Install pypa/build
@@ -33,7 +33,7 @@ jobs:
           --outdir dist/
           .
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: "2.x"
       - name: Install pypa/build

.github/workflows/pull_request.yml

@@ -8,8 +8,8 @@ jobs:
   changelog:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v1
-      - uses: dangoslen/changelog-enforcer@v1.1.1
+      - uses: actions/checkout@v4
+      - uses: dangoslen/changelog-enforcer@v3.6.1
         with:
           changeLogPath: 'CHANGELOG.md'
-          skipLabel: 'skip-changelog'
+          skipLabel: 'skip-changelog'

.github/workflows/pythonapp.yml

@@ -8,11 +8,11 @@ jobs:
     runs-on: ubuntu-20.04
     strategy:
       matrix:
-        python-version: ["3.7", "3.8", "3.9", "3.10"]
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v1
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install dependencies

.readthedocs.yaml

@@ -0,0 +1,16 @@
+# Read the Docs configuration file for Sphinx projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - requirements: docs/requirements.txt

CHANGELOG.md

@@ -9,20 +9,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- Added env_variable_setup.rst to docs and associated images to docs/images. This is a written walkthrough based on the environment variable authentication tutorial video.
-
-## [2.23.0] - 2023-12-12
-
-### Added
-
+- Added `MemcacheCacheHandler`, a cache handler that stores the token info using pymemcache.
 - Added support for audiobook endpoints: get_audiobook, get_audiobooks, and get_audiobook_chapters.
 - Added integration tests for audiobook endpoints.
 - Removed `python 2.7` from GitHub Actions CI workflow. Python v2.7 reached end of life support and is no longer supported by Ubuntu 20.04.
 - Removed `python 3.6` from GitHub Actions CI workflow. Ubuntu 20.04 is not available in GitHub Actions for `python 3.6`.
+- Added extra installation step to TUTORIAL.md for required installation packages.
+- Added Troubleshooting Tips section to TUTORIAL.md to address common installation issues.
+- Added link to Spotipy Tutorial for Beginners under Getting Started.
+- Added `update` field to `current_user_follow_playlist`.
+- Added env_variable_setup.rst to docs and associated images to docs/images. This is a written walkthrough based on the environment variable authentication tutorial video.
 
 ### Changed
 - Changes the YouTube video link for authentication tutorial (the old video was in low definition, the new one is in high definition)
+- Updated links to Spotify in documentation
+- Improve usability on README.md
+- Fix `user_playlists_contents` example. 
 - Updated links to Spotify in documentation 
+- Fixed error obfuscation when Spotify class is being inherited and an error is raised in the Child's `__init__`
+- Replaced `artist_albums(album_type=...)` with `artist_albums(include_groups=...)` due to an API change.
+- Restructured the tutorial in `index.rst` to improve logical flow and made some minor edits.
+- Updated _regex_spotify_url to ignore `/intl-<countrycode>` in Spotify links
+- Drop support for EOL Python 3.7.
+
+### Fixed
+- Fixed unused description parameter in playlist creation example
+- Readthedocs
+- Corrected various grammar errors and typos in the documentation.
+- Seperated the test_current_user_save_and_usave_tracks unit test into test_current_user_save_tracks and test_current_user_unsave_tracks in the user endpoint test suite to improve unit test clarity and effectiveness for their respective user endpoints methods (current_user_saved_tracks_add, current_user_saved_tracks).
 
 ## [2.23.0] - 2023-04-07
 
@@ -66,7 +80,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Incorrect `category_id` input for test_category
 - Assertion value for `test_categories_limit_low` and `test_categories_limit_high`
-- Pin Github Actions Runner to Ubuntu 20 for Py27
+- Pin GitHub Actions Runner to Ubuntu 20 for Py27
 - Fixed potential error where `found` variable in `test_artist_related_artists` is undefined if for loop never evaluates to true
 - Fixed false positive test `test_new_releases` which looks up the wrong property of the JSON response object and always evaluates to true
 
@@ -91,13 +105,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Added `RedisCacheHandler`, a cache handler that stores the token info in Redis.
-- Changed URI handling in `client.Spotify._get_id()` to remove qureies if provided by error.
+- Changed URI handling in `client.Spotify._get_id()` to remove queries if provided by error.
 - Added a new parameter to `RedisCacheHandler` to allow custom keys (instead of the default `token_info` key)
 - Simplify check for existing token in `RedisCacheHandler`
 
 ### Changed
 
-- Removed Python 3.5 and added Python 3.9 in Github Action
+- Removed Python 3.5 and added Python 3.9 in GitHub Action
 
 ## [2.19.0] - 2021-08-12
 
@@ -110,7 +124,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 
 - Fixed a bug in `CacheFileHandler.__init__`: The documentation says that the username will be retrieved from the environment, but it wasn't.
-- Fixed a bug in the initializers for the auth managers that produced a spurious warning message if you provide a cache handler and you set a value for the "SPOTIPY_CLIENT_USERNAME" environment variable.
+- Fixed a bug in the initializers for the auth managers that produced a spurious warning message if you provide a cache handler, and you set a value for the "SPOTIPY_CLIENT_USERNAME" environment variable.
 - Use generated MIT license and fix license type in `pip show`
 
 ## [2.18.0] - 2021-04-13
@@ -151,7 +165,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - The docs for the `auth` parameter of `Spotify.init` use the term "access token" instead of "authorization token"
 - Changed docs for `search` to mention that you can provide multiple types to search for
 - The query parameters of requests are now logged
-- Deprecate specifing `cache_path` or `username` directly to `SpotifyOAuth`, `SpotifyPKCE`, and `SpotifyImplicitGrant` constructors, instead directing users to use the `CacheFileHandler` cache handler
+- Deprecate specifying `cache_path` or `username` directly to `SpotifyOAuth`, `SpotifyPKCE`, and `SpotifyImplicitGrant` constructors, instead directing users to use the `CacheFileHandler` cache handler
 - Removed requirement for examples/app.py to specify port multiple times (only SPOTIPY_REDIRECT_URI needs to contain the port)
 
 ### Added
@@ -252,7 +266,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     authorization/authentication web api errors details.
 - Added `SpotifyStateError` subclass of `SpotifyOauthError`
 - Allow extending `SpotifyClientCredentials` and `SpotifyOAuth`
-- Added the market paramter to `album_tracks`
+- Added the market parameter to `album_tracks`
 
 ### Deprecated
 
@@ -303,7 +317,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     - retries
     - status_retries
     - backoff_factor
-- Spin up a local webserver to auto-fill authentication URL
+- Spin up a local webserver to autofill authentication URL
 - Use session in SpotifyAuthBase
 - Logging used instead of print statements
 
@@ -406,7 +420,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Support for `current_user_saved_albums_contains`
 - Support for `user_unfollow_artists`
 - Support for `user_unfollow_users`
-- Lint with flake8 using Github action
+- Lint with flake8 using GitHub action
 
 ### Changed
 
@@ -458,7 +472,7 @@ Fixed bug in auto retry logic
 
 ## [2.3.3] - 2015-04-01
 
-Aadded client credential flow
+Added client credential flow
 
 ## [2.3.2] - 2015-03-31
 
@@ -502,7 +516,7 @@ Support for "Your Music" tracks (add, delete, get), with examples
 
 ## [1.45.0] - 2014-07-07
 
-Support for related artists endpoint. Don't use cache auth codes when scope changes
+Support for related artists' endpoint. Don't use cache auth codes when scope changes
 
 ## [1.44.0] - 2014-07-03
 

README.md

@@ -1,12 +1,26 @@
 # Spotipy
 
-##### A light weight Python library for the Spotify Web API
+##### Spotipy is a lightweight Python library for the [Spotify Web API](https://developer.spotify.com/documentation/web-api). With Spotipy you get full access to all of the music data provided by the Spotify platform.
 
-![Tests](https://github.com/plamere/spotipy/workflows/Tests/badge.svg?branch=master) [![Documentation Status](https://readthedocs.org/projects/spotipy/badge/?version=latest)](https://spotipy.readthedocs.io/en/latest/?badge=latest)
+![Tests](https://github.com/plamere/spotipy/workflows/Tests/badge.svg?branch=master) [![Documentation Status](https://readthedocs.org/projects/spotipy/badge/?version=master)](https://spotipy.readthedocs.io/en/latest/?badge=master)
+
+## Table of Contents
+
+- [Features](#features)
+- [Documentation](#documentation)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Reporting Issues](#reporting-issues)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Features
+
+Spotipy supports all of the features of the Spotify Web API including access to all end points, and support for user authorization. For details on the capabilities you are encouraged to review the [Spotify Web API](https://developer.spotify.com/web-api/) documentation.
 
 ## Documentation
 
-Spotipy's full documentation is online at [Spotipy Documentation](http://spotipy.readthedocs.org/).
+Spotipy's [full documentation is online](http://spotipy.readthedocs.org/). Some function may need a [specific scope](https://developer.spotify.com/documentation/web-api/concepts/scopes). If you do not define the scope properly `ERROR 401 Unauthorized, permission missing` may occur.
 
 ## Installation
 
@@ -30,10 +44,9 @@ pip install spotipy --upgrade
 
 A full set of examples can be found in the [online documentation](http://spotipy.readthedocs.org/) and in the [Spotipy examples directory](https://github.com/plamere/spotipy/tree/master/examples).
 
-To get started, install spotipy and create an app on https://developers.spotify.com/.
-Add your new ID and SECRET to your environment:
+To get started, [install spotipy](#installation), create a new account or log in on https://developers.spotify.com/. Go to the [dashboard](https://developer.spotify.com/dashboard), create an app and add your new ID and SECRET (ID and SECRET can be found on an app setting) to your environment ([step-by-step video](https://www.youtube.com/watch?v=kaBVN8uP358)):
 
-### Without user authentication
+### Example without user authentication
 
 ```python
 import spotipy
@@ -46,8 +59,20 @@ results = sp.search(q='weezer', limit=20)
 for idx, track in enumerate(results['tracks']['items']):
     print(idx, track['name'])
 ```
+Expected result:
+```
+0 Island In The Sun
+1 Say It Ain't So
+2 Buddy Holly
+.
+.
+.
+18 Troublemaker
+19 Feels Like Summer
+```
+
 
-### With user authentication
+### Example with user authentication
 
 A redirect URI must be added to your application at [My Dashboard](https://developer.spotify.com/dashboard/applications) to access user authenticated features.
 
@@ -65,6 +90,12 @@ for idx, item in enumerate(results['items']):
     track = item['track']
     print(idx, track['artists'][0]['name'], " – ", track['name'])
 ```
+Expected result will be the list of music that you liked. For example if you liked Red and Sunflower, the result will be:
+```
+0 Post Malone  –  Sunflower - Spider-Man: Into the Spider-Verse
+1 Taylor Swift  –  Red
+```
+
 
 ## Reporting Issues
 
@@ -77,3 +108,9 @@ Don’t forget to add the *Spotipy* tag, and any other relevant tags as well, be
 If you have suggestions, bugs or other issues specific to this library,
 file them [here](https://github.com/plamere/spotipy/issues).
 Or just send a pull request.
+
+## Contributing
+
+If you are a developer with Python experience, and you would like to contribute to Spotipy, please be sure to follow the guidelines listed on documentation page
+
+> #### [Visit the guideline](https://spotipy.readthedocs.io/en/#contribute)