The client provides options and toggles to customise behavior in a variety of ways.
The Web API limits the number of resources returned in many endpoints. By default, these limits are below their maximum values, matching API defaults. However, they can be maximised when instantiating a client or as a context.
Endpoints that accept lists of resources often limit the amount of items that can be passed in. To help with this restriction, those lists can be chunked.
It is generally advisable to separate configuration from code, and more importantly keep secrets outside public version control. To facilitate that, environment variables and configuration files can be used to provide application credentials. Set values in your environment or write a configuration file, then read the configuration.
These values can then be used to retrieve access tokens. Note that if all configuration values are defined, it is possible to use unpacking to provide the configuration.
Configuring a user refresh token is also possible.
SPOTIFY_USER_REFRESH and pass in a boolean flag
to read it as a fourth configuration value.
Configuration files can be written too. This is handy if a user’s refresh token needs to be stored.
tk.config_to_file(filename, (id_, secret, uri, refresh))
For more information see Configuration.
Customising request behavior
By default Tekore doesn’t do anything clever when sending requests. Its functionality, however, can be extended in a number of ways using different kinds of senders. Builtin senders can be used for retrying and caching.
Keepalive connections, retries and caching make up a performance-boosting and convenient setup, easily constructed from simple building blocks. Less errors, less requests and faster responses, particularly for busy applications that request the same static resources repeatedly.
At the lowest level,
httpx.Client instances which can further customise behavior.
For example, setting longer request timeouts and retrying on connection errors
is possible with the following setup.
With an async sender use
Traversing paging objects
Many Web API endpoints that would return a large number of the same type of object return paging objects for performance reasons. The client defines a few ways to navigate these pagings. Next and previous pages can be requested one at a time.
To retrieve the whole content additional methods are available.
Tekore provides support for asynchronous programming with async-await.
Async mode may be enabled when instantiating a
Alternatively, an asynchronous sender may be passed directly into a client.
The boolean parameter above overrides any conflicting sender that is set as default or simultaneously passed in to the client.
async def now_playing():
return await spotify.playback_currently_playing()
np = asyncio.run(now_playing())
Asynchronous execution can also be used for quick bursts of calls when combined
asyncio.gather(). See Scrape playlist artists for an example.
Credentials is supported, it is worth considering
that concurrently refreshing tokens may lead to multiple refreshes for one token.
Synchronous credentials clients are recommended.
Client context managers are async safe, meaning that they can be used in many tasks without affecting the state of other tasks. However, setting values outside of all contexts modifies the persistent value directly, and as such may affect other tasks.
Gradually expanding token scopes and methods that “know” their associated
scopes can be used to dynamically expand user scopes in a web application.
Unauthorised carries the scope information from failing calls
and can then be used to redirect users to authorise again.
except tk.Unauthorised as e:
return Redirect("/login?scope=" + str(e.scope))
Combined with refreshing the token on arrival to have the full scope and additionally redirecting the user back after authorisation, even static HTML applications using a Python backend become simple to implement.
Many API calls that retrieve track information accept a
country parameter with which only tracks or albums available in that
market are returned. This sometimes changes track IDs as well.
When calling with a user token, this country code can also be
from_token, in which case the results are for the user’s locale.
In addition to returning results relevant to a specific market, results can be requested in specific languages. This is helpful for example in viewing names with non-latin alphabet.