[PR #695] Add type annotations for Spotify JSON objects #997

New issue

Open

opened 2026-02-28 00:03:10 +03:00 by kerem · 0 comments

kerem commented

2026-02-28 00:03:10 +03:00

Owner

📋 Pull Request Information

Original PR: https://github.com/spotipy-dev/spotipy/pull/695
Author: @akathorn
Created: 6/23/2021
Status: 🔄 Open

Base: v3_oldprsonly ← Head: typings

📝 Commits (10+)

49e42f9 Add representation for JSON return values
0047299 Add typing_extensions as dependency
a6804af Annotate util.py and exceptions.py
24416a3 Partly annotate client.py
6fdfc57 Annotate cache_handler.py
6eabb04 Small anotation in scope.py
c60a562 Annotate all arguments in client.py
cc90dda Annotate most of oauth2.py public api
61ce06c A big pass over client.py
95e4859 Annotate all return types in client.py

📊 Changes

8 files changed (+1144 additions, -202 deletions)

View changed files

📝 setup.py (+1 -0)
📝 spotipy/cache_handler.py (+13 -10)
📝 spotipy/client.py (+212 -130)
📝 spotipy/exceptions.py (+5 -1)
➕ spotipy/json_types.py (+847 -0)
📝 spotipy/oauth2.py (+62 -58)
📝 spotipy/scope.py (+2 -2)
📝 spotipy/util.py (+2 -1)

📄 Description

Working on #439. It is WIP but I would like some feedback before I validate the return types one by one.

All public methods are annotated. I haven't added anything that alters the runtime behavior in any way.
The arguments are straightforward since they are all basic types, but I had to define new types for the return values. The alternative is using Dict[str, Any] for all the JSON dicts, which would be more "lightweight" but provides near-zero typing information.

It works on nearly examples!

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/spotipy-dev/spotipy/pull/695 **Author:** [@akathorn](https://github.com/akathorn) **Created:** 6/23/2021 **Status:** 🔄 Open **Base:** `v3_oldprsonly` ← **Head:** `typings` --- ### 📝 Commits (10+) - [`49e42f9`](https://github.com/spotipy-dev/spotipy/commit/49e42f906b3ca41d3db5d2adf0a9e06a5af8447d) Add representation for JSON return values - [`0047299`](https://github.com/spotipy-dev/spotipy/commit/0047299e555e6d585b40ace9cf9a42eaad1a4be2) Add typing_extensions as dependency - [`a6804af`](https://github.com/spotipy-dev/spotipy/commit/a6804af835bd3fbf2c859f62fa7ae323358511a4) Annotate util.py and exceptions.py - [`24416a3`](https://github.com/spotipy-dev/spotipy/commit/24416a302ebe8c45e36cbc2004e4a77878815e8f) Partly annotate client.py - [`6fdfc57`](https://github.com/spotipy-dev/spotipy/commit/6fdfc5734a67e749e4cee94d1f64add39e02863c) Annotate cache_handler.py - [`6eabb04`](https://github.com/spotipy-dev/spotipy/commit/6eabb043a72565a613c04bcb09a0b196c000ff6d) Small anotation in scope.py - [`c60a562`](https://github.com/spotipy-dev/spotipy/commit/c60a562737ab42b17b73dcb2ec43de1eab5297db) Annotate all arguments in client.py - [`cc90dda`](https://github.com/spotipy-dev/spotipy/commit/cc90dda990d796d1ba9bfc1f603d23d6d1698d42) Annotate most of oauth2.py public api - [`61ce06c`](https://github.com/spotipy-dev/spotipy/commit/61ce06c75e08b7f2d4ca5f3ceb45bb4bfad6d527) A big pass over client.py - [`95e4859`](https://github.com/spotipy-dev/spotipy/commit/95e4859416bb67ae46dac6ca60da3086141280df) Annotate all return types in client.py ### 📊 Changes **8 files changed** (+1144 additions, -202 deletions) <details> <summary>View changed files</summary> 📝 `setup.py` (+1 -0) 📝 `spotipy/cache_handler.py` (+13 -10) 📝 `spotipy/client.py` (+212 -130) 📝 `spotipy/exceptions.py` (+5 -1) ➕ `spotipy/json_types.py` (+847 -0) 📝 `spotipy/oauth2.py` (+62 -58) 📝 `spotipy/scope.py` (+2 -2) 📝 `spotipy/util.py` (+2 -1) </details> ### 📄 Description Working on #439. It is WIP but I would like some feedback before I validate the return types one by one. All public methods are annotated. I haven't added anything that alters the runtime behavior in any way. The arguments are straightforward since they are all basic types, but I had to define new types for the return values. The alternative is using `Dict[str, Any]` for all the JSON dicts, which would be more "lightweight" but provides near-zero typing information. It works on nearly examples! --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>