[GH-ISSUE #1034] Add better typing support for Spotipy #619

New issue

Open

opened 2026-02-28 00:00:20 +03:00 by kerem · 1 comment

kerem commented

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

Owner

Originally created by @unownone on GitHub (Oct 22, 2023).
Original GitHub issue: https://github.com/spotipy-dev/spotipy/issues/1034

The Problem

Spotipy is a great library to extend the spotipy API . It is a really great wrapper around the spotipy API. But most of the return types lack a defined type, which makes it harder for a developer to work with Spotipy as there's almost no type hints and they would end up having to refer to documentation extensively.

The solution: Auto Synching with Spotify OpenAPI Specs

Spotify already provides a great official openapi spec which seems to have good documentation attached to it too! (link to openapi specs). Ideally manually doing this job would require a lot of boring work which needs to be done every time we do something.

There are already projects out there which let you create a wrapper / sdk around a OPENAPI docs but to my knowledge this is still subpar to what spotipy provides/ would provide.

The ideal solution to this problem would be that we set up a cron ( a github action ) that periodically replicates the spotify official openapi spec and compares it with the last openapi spec and generates docstrings ( from the spec ) as well as typehints / types ( preferably using pydantic ) ( there's a project called datamodel-code-generator which can also help us generate datamodels for our api responses easily.

The cronjob would run daily to update the datamodels ( or can be run manually too ) such that we can always get a class object with definitions and docstrings instead of a naked object with no predefinitions.

Additionally, this can be added as a separate package/ add-on instead of adding directly into the current code as it would introduce breaking changes.

Alternatives

Writing our own converter that can help us do the same thing datamodel-code-generator does, but I feel that's just repititive work.

Additional context
Working with Spotipy is fun, but working with return values which doesn't define what is coming in makes everything a lot hard. Initially my solution to this was to handle this by writing a bunch of Pydantic classes and doing a bunch of if else to determine if I got the right data or not. Something like this can easily be handled by Spotipy too which can make everyone's life ( who wish to have types ) a lot lot better!

Originally created by @unownone on GitHub (Oct 22, 2023). Original GitHub issue: https://github.com/spotipy-dev/spotipy/issues/1034 # The Problem Spotipy is a great library to extend the spotipy API . It is a really great wrapper around the spotipy API. But most of the return types lack a defined type, which makes it harder for a developer to work with Spotipy as there's almost no type hints and they would end up having to refer to documentation extensively. # The solution: **Auto Synching with Spotify OpenAPI Specs** Spotify already provides a great official openapi spec which seems to have good documentation attached to it too! ([link to openapi specs](https://developer.spotify.com/reference/web-api/open-api-schema.yaml)). Ideally manually doing this job would require a lot of boring work which needs to be done every time we do something. There are already projects out there which let you create a wrapper / sdk around a OPENAPI docs but to my knowledge this is still subpar to what spotipy provides/ would provide. The ideal solution to this problem would be that we set up a cron ( a github action ) that periodically replicates the spotify official openapi spec and compares it with the last openapi spec and generates docstrings ( from the spec ) as well as typehints / types ( preferably using [pydantic](https://github.com/pydantic/pydantic) ) ( there's a project called [datamodel-code-generator](https://docs.pydantic.dev/latest/integrations/datamodel_code_generator/) which can also help us generate datamodels for our api responses easily. The cronjob would run daily to update the datamodels ( or can be run manually too ) such that we can always get a class object with definitions and docstrings instead of a naked object with no predefinitions. Additionally, this can be added as a separate package/ add-on instead of adding directly into the current code as it would introduce breaking changes. **Alternatives** - Writing our own converter that can help us do the same thing datamodel-code-generator does, but I feel that's just repititive work. **Additional context** Working with Spotipy is fun, but working with return values which doesn't define what is coming in makes everything a lot hard. Initially my solution to this was to handle this by writing a bunch of Pydantic classes and doing a bunch of if else to determine if I got the right data or not. Something like this can easily be handled by Spotipy too which can make everyone's life ( who wish to have types ) a lot lot better!

kerem added the

enhancement

label

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

kerem commented

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

Author

Owner

@dieser-niko commented on GitHub (May 6, 2024):

Hi there, sorry for the late answer. This has been discussed for quite a while (https://github.com/spotipy-dev/spotipy/issues/975), but it was never verified that the OpenAPI specs are actually up-to-date with the documentation and the actual functionality of the API.

@dieser-niko commented on GitHub (May 6, 2024): Hi there, sorry for the late answer. This has been discussed for quite a while (https://github.com/spotipy-dev/spotipy/issues/975), but it was never verified that the OpenAPI specs are actually up-to-date with the documentation and the actual functionality of the API.