dieser-niko
commented
4 months ago 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.
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
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!