From fd52eba877312af69888809c194c9a272077f794 Mon Sep 17 00:00:00 2001 From: felix Date: Sun, 19 Apr 2020 20:21:05 +0300 Subject: [PATCH] Documentation changes --- docs/src/advanced_usage.rst | 46 +++++++------------ docs/src/examples/artist_follower.rst | 9 ++-- docs/src/examples/async_server.rst | 9 ++-- docs/src/examples/auth_server.rst | 11 ++--- docs/src/examples/client_configurations.rst | 28 +++++------ docs/src/examples/discord_bot.rst | 11 ++--- .../examples/scripts/albums_top_artist.rst | 8 ++-- .../scripts/analyse_from_playlist.rst | 8 ++-- .../src/examples/scripts/follow_by_search.rst | 8 ++-- .../scripts/follow_category_playlist.rst | 8 ++-- .../src/examples/scripts/play_saved_album.rst | 11 ++--- .../examples/scripts/recommended_playlist.rst | 8 ++-- .../scripts/related_artists_top_artist.rst | 8 ++-- .../src/examples/scripts/scrape_playlists.rst | 13 +++--- .../examples/scripts/tracks_new_release.rst | 8 ++-- docs/src/extras/performance/performance.rst | 20 ++++---- docs/src/getting_started.rst | 15 ++---- docs/src/index.rst | 8 ++-- docs/src/reference.rst | 6 ++- readme.rst | 8 ++-- readme_pypi.rst | 8 ++-- tekore/auth/__init__.py | 4 +- tekore/client/__init__.py | 4 +- tekore/convert.py | 6 +-- tekore/model/__init__.py | 4 +- tekore/scope.py | 4 +- tekore/sender.py | 29 +++++------- tekore/serialise.py | 4 +- tekore/util/config.py | 12 ++--- tekore/util/credentials.py | 10 ++-- 30 files changed, 151 insertions(+), 185 deletions(-) diff --git a/docs/src/advanced_usage.rst b/docs/src/advanced_usage.rst index 994ca2ae..4a6f40d6 100644 --- a/docs/src/advanced_usage.rst +++ b/docs/src/advanced_usage.rst @@ -75,7 +75,7 @@ However, they can be maximised when instantiating a client or as a context. .. code:: python - spotify = Spotify(max_limits_on=True) + spotify = tk.Spotify(max_limits_on=True) spotify.max_limits_on = False with spotify.max_limits(): @@ -89,7 +89,7 @@ To help with this restriction, those lists can be chunked. .. code:: python - spotify = Spotify(chunked_on=True) + spotify = tk.Spotify(chunked_on=True) spotify.chunked_on = False with spotify.chunked(): @@ -121,9 +121,8 @@ Functions that read configuration return a 3-tuple of configuration variables. .. code:: python - from tekore.util import config_from_environment, config_from_file - client_id, client_secret, redirect_uri = config_from_environment() - client_id, client_secret, redirect_uri = config_from_file(filename) + client_id, client_secret, redirect_uri = tk.config_from_environment() + client_id, client_secret, redirect_uri = tk.config_from_file(filename) They can then be used to retrieve access tokens. Note that if all configuration values are defined, @@ -131,10 +130,8 @@ it is possible to use unpacking to provide the configuration. .. code:: python - from tekore import util - - conf = util.config_from_environment() - token = util.prompt_for_user_token(*conf) + conf = tk.config_from_environment() + token = tk.prompt_for_user_token(*conf) Configuring a user refresh token is also possible. Define ``SPOTIFY_USER_REFRESH`` and pass in a boolean flag @@ -142,14 +139,14 @@ to read it as a fourth configuration value. .. code:: python - util.config_from_environment(return_refresh=True) + tk.config_from_environment(return_refresh=True) Configuration files can be written using another utility function. This is handy if a user's refresh token needs to be stored. .. code:: python - util.config_to_file(filename, (id_, secret, uri, refresh)) + tk.config_to_file(filename, (id_, secret, uri, refresh)) Using senders ------------- @@ -164,10 +161,7 @@ For example, per-instance sessions can be enabled with a .. code:: python - from tekore import Spotify - from tekore.sender import PersistentSender - - Spotify(sender=PersistentSender()) + tk.Spotify(sender=tk.PersistentSender()) Keepalive connections, retries and caching make up a performance-boosting and convenient sender setup, easily constructed from simple building blocks. @@ -176,14 +170,11 @@ busy applications that request the same static resources repeatedly. .. code:: python - from tekore import sender - from tekore.sender import CachingSender, RetryingSender, PersistentSender - - sender.default_sender_instance = CachingSender( + tk.sender.default_sender_instance = tk.CachingSender( max_size=256, - sender=RetryingSender( + sender=tk.RetryingSender( retries=2, - sender=PersistentSender() + sender=tk.PersistentSender() ) ) @@ -217,8 +208,8 @@ Async mode may be enabled when instantiating a client. .. code:: python - Credentials(*conf, asynchronous=True) - Spotify(token, asynchronous=True) + tk.Credentials(*conf, asynchronous=True) + tk.Spotify(token, asynchronous=True) Note that the boolean parameter above overrides any conflicting :class:`Sender ` that is set as default @@ -227,10 +218,7 @@ Alternatively, an asynchronous sender may be passed directly into a client. .. code:: python - from tekore import Spotify - from tekore.sender import AsyncPersistentSender - - spotify = Spotify(token, sender=AsyncPersistentSender()) + spotify = tk.Spotify(token, sender=tk.AsyncPersistentSender()) Now every call to an endpoint returns an awaitable instead of a response. :mod:`asyncio` can then be used to execute asynchronous requests. @@ -270,13 +258,11 @@ This is helpful for example in viewing names with non-latin alphabet. .. code:: python - from tekore import Spotify - from tekore.sender import PersistentSender from requests import Session sess = Session() sess.headers = {'Accept-Language': 'ru'} - spotify = Spotify(token, sender=PersistentSender(session=sess)) + spotify = tk.Spotify(token, sender=tk.PersistentSender(session=sess)) artist = spotify.artist('2LbinT29RFLaXOGAN0jfQN') print(artist.name) diff --git a/docs/src/examples/artist_follower.rst b/docs/src/examples/artist_follower.rst index 274adf86..277b5bed 100644 --- a/docs/src/examples/artist_follower.rst +++ b/docs/src/examples/artist_follower.rst @@ -5,18 +5,17 @@ from your playlists, and prompt you to do so. .. code:: python - from tekore import Spotify - from tekore.util import prompt_for_user_token, config_from_environment + import tekore as tk from tekore.scope import scopes, Scope - conf = config_from_environment() + conf = tk.config_from_environment() scope = Scope( scopes.user_follow_read, scopes.user_follow_modify, scopes.playlist_read_private ) - user_token = prompt_for_user_token(*conf, scope=scope) - s = Spotify(user_token, max_limits_on=True, chunked_on=True) + user_token = tk.prompt_for_user_token(*conf, scope=scope) + s = tk.Spotify(user_token, max_limits_on=True, chunked_on=True) def prompt_user(what: str) -> bool: diff --git a/docs/src/examples/async_server.rst b/docs/src/examples/async_server.rst index 3f079806..f34e0039 100644 --- a/docs/src/examples/async_server.rst +++ b/docs/src/examples/async_server.rst @@ -17,13 +17,12 @@ requests take about ten seconds, no matter how many are sent at once. .. code:: python - from tekore import util, Spotify - from tekore.sender import AsyncPersistentSender + import tekore as tk from aiohttp import web - conf = util.config_from_environment() - token = util.request_client_token(*conf[:2]) - spotify = Spotify(token, sender=AsyncPersistentSender()) + conf = tk.config_from_environment() + token = tk.request_client_token(*conf[:2]) + spotify = tk.Spotify(token, sender=tk.AsyncPersistentSender()) routes = web.RouteTableDef() diff --git a/docs/src/examples/auth_server.rst b/docs/src/examples/auth_server.rst index a818c49a..640273d8 100644 --- a/docs/src/examples/auth_server.rst +++ b/docs/src/examples/auth_server.rst @@ -20,15 +20,14 @@ Logging out deletes the cookie and server-stored access token. .. code:: python - from flask import Flask, request, redirect, session + import tekore as tk - from tekore import Spotify, Credentials - from tekore.util import config_from_environment from tekore.scope import every + from flask import Flask, request, redirect, session - conf = config_from_environment() - cred = Credentials(*conf) - spotify = Spotify() + conf = tk.config_from_environment() + cred = tk.Credentials(*conf) + spotify = tk.Spotify() users = {} diff --git a/docs/src/examples/client_configurations.rst b/docs/src/examples/client_configurations.rst index d961d485..19de5e48 100644 --- a/docs/src/examples/client_configurations.rst +++ b/docs/src/examples/client_configurations.rst @@ -12,15 +12,13 @@ authentication can be completed with some manual work. .. code:: python - from tekore import Spotify, util - from tekore.scope import every - from tekore.sender import PersistentSender + import tekore as tk - conf = util.config_from_environment() - token = util.prompt_for_user_token(*conf, scope=every) - s = Spotify(token=token, sender=PersistentSender()) + conf = tk.config_from_environment() + token = tk.prompt_for_user_token(*conf, scope=tk.scope.every) + spotify = tk.Spotify(token, sender=tk.PersistentSender()) - user = s.current_user() + user = spotify.current_user() Save the refresh token to avoid authenticating again when restarting. @@ -28,7 +26,7 @@ Save the refresh token to avoid authenticating again when restarting. # Load refresh token refresh_token = ... - token = util.refresh_user_token(*conf[:2], refresh_token) + token = tk.refresh_user_token(*conf[:2], refresh_token) Server application or multiple users @@ -39,21 +37,19 @@ using the application token and swapping in user tokens. .. code:: python - from tekore import Spotify, Credentials - from tekore.util import config_from_environment - from tekore.sender import PersistentSender + import tekore as tk - conf = config_from_environment() - cred = Credentials(*conf) + conf = tk.config_from_environment() + cred = tk.Credentials(*conf) app_token = cred.request_client_token() - s = Spotify(token=app_token, sender=PersistentSender()) + spotify = tk.Spotify(app_token, sender=tk.PersistentSender()) # Retrieve user token user_token = ... - with s.token_as(user_token): - user = s.current_user() + with spotify.token_as(user_token): + user = spotify.current_user() If multiple clients are instantiated, consider using a :class:`SingletonSender ` instead. diff --git a/docs/src/examples/discord_bot.rst b/docs/src/examples/discord_bot.rst index 4917164c..39c24675 100644 --- a/docs/src/examples/discord_bot.rst +++ b/docs/src/examples/discord_bot.rst @@ -18,19 +18,18 @@ Queries can be for example: .. code:: python + import tekore as tk + from discord import Game, Embed from discord.ext import commands - from tekore import Spotify - from tekore.util import request_client_token, config_from_environment - token_discord = "your_discord_token" - conf = config_from_environment() - token_spotify = request_client_token(*conf[:2]) + conf = tk.config_from_environment() + token_spotify = tk.request_client_token(*conf[:2]) description = "Spotify track search bot using Tekore" bot = commands.Bot(command_prefix='>tk ', description=description) - spotify = Spotify(token_spotify, asynchronous=True) + spotify = tk.Spotify(token_spotify, asynchronous=True) @bot.command(help="Multiword query in quotes") diff --git a/docs/src/examples/scripts/albums_top_artist.rst b/docs/src/examples/scripts/albums_top_artist.rst index 599f9c3b..e4d35148 100644 --- a/docs/src/examples/scripts/albums_top_artist.rst +++ b/docs/src/examples/scripts/albums_top_artist.rst @@ -7,14 +7,14 @@ and you have used Spotify enough to have top artists. .. code:: python - from tekore import util, Spotify + import tekore as tk from tekore.scope import scopes - conf = util.config_from_environment() + conf = tk.config_from_environment() scope = scopes.user_top_read - token = util.prompt_for_user_token(*conf, scope=scope) + token = tk.prompt_for_user_token(*conf, scope=scope) - spotify = Spotify(token) + spotify = tk.Spotify(token) artist = spotify.current_user_top_artists(limit=1).items[0] albums = spotify.artist_albums(artist.id) diff --git a/docs/src/examples/scripts/analyse_from_playlist.rst b/docs/src/examples/scripts/analyse_from_playlist.rst index 13b72de9..49280865 100644 --- a/docs/src/examples/scripts/analyse_from_playlist.rst +++ b/docs/src/examples/scripts/analyse_from_playlist.rst @@ -10,12 +10,12 @@ because they cannot be analysed. .. code:: python - from tekore import util, Spotify + import tekore as tk - conf = util.config_from_environment() - token = util.prompt_for_user_token(*conf) + conf = tk.config_from_environment() + token = tk.prompt_for_user_token(*conf) - spotify = Spotify(token) + spotify = tk.Spotify(token) playlist = spotify.followed_playlists(limit=1).items[0] track = spotify.playlist_tracks(playlist.id, limit=1).items[0].track name = f'"{track.name}" from {playlist.name}' diff --git a/docs/src/examples/scripts/follow_by_search.rst b/docs/src/examples/scripts/follow_by_search.rst index 7ed91c09..7a5489c3 100644 --- a/docs/src/examples/scripts/follow_by_search.rst +++ b/docs/src/examples/scripts/follow_by_search.rst @@ -7,13 +7,13 @@ It assumes that your credentials are saved in the environment. .. code:: python - from tekore import util, Spotify + import tekore as tk from tekore.scope import scopes - conf = util.config_from_environment() + conf = tk.config_from_environment() scope = scopes.user_follow_modify - token = util.prompt_for_user_token(*conf, scope=scope) - spotify = Spotify(token) + token = tk.prompt_for_user_token(*conf, scope=scope) + spotify = tk.Spotify(token) search = input('Search for an artist: ') artists, = spotify.search(search, types=('artist',), limit=1) diff --git a/docs/src/examples/scripts/follow_category_playlist.rst b/docs/src/examples/scripts/follow_category_playlist.rst index 607f31d4..3cb0e357 100644 --- a/docs/src/examples/scripts/follow_category_playlist.rst +++ b/docs/src/examples/scripts/follow_category_playlist.rst @@ -7,14 +7,14 @@ It assumes that your credentials are saved in the environment. .. code:: python - from tekore import util, Spotify + import tekore as tk from tekore.scope import scopes - conf = util.config_from_environment() + conf = tk.config_from_environment() scope = scopes.playlist_modify_private - token = util.prompt_for_user_token(*conf, scope=scope) + token = tk.prompt_for_user_token(*conf, scope=scope) - spotify = Spotify(token) + spotify = tk.Spotify(token) category = spotify.categories(limit=1).items[0] playlist = spotify.category_playlists(category.id, limit=1).items[0] diff --git a/docs/src/examples/scripts/play_saved_album.rst b/docs/src/examples/scripts/play_saved_album.rst index 0933f75d..b9801c5b 100644 --- a/docs/src/examples/scripts/play_saved_album.rst +++ b/docs/src/examples/scripts/play_saved_album.rst @@ -8,15 +8,14 @@ and you have an active Spotify application open. .. code:: python - from tekore import util, Spotify + import tekore as tk from tekore.scope import scopes - from tekore.convert import to_uri - conf = util.config_from_environment() + conf = tk.config_from_environment() scope = scopes.user_library_read + scopes.user_modify_playback_state - token = util.prompt_for_user_token(*conf, scope=scope) + token = tk.prompt_for_user_token(*conf, scope=scope) - spotify = Spotify(token) + spotify = tk.Spotify(token) album = spotify.saved_albums(limit=1).items[0].album - album_uri = to_uri('album', album.id) + album_uri = tk.to_uri('album', album.id) spotify.playback_start_context(album_uri) diff --git a/docs/src/examples/scripts/recommended_playlist.rst b/docs/src/examples/scripts/recommended_playlist.rst index 551e0d32..f8bf0aaf 100644 --- a/docs/src/examples/scripts/recommended_playlist.rst +++ b/docs/src/examples/scripts/recommended_playlist.rst @@ -8,14 +8,14 @@ and you have used Spotify enough to have top tracks. .. code:: python - from tekore import util, Spotify + import tekore as tk from tekore.scope import scopes - conf = util.config_from_environment() + conf = tk.config_from_environment() scope = scopes.user_top_read + scopes.playlist_modify_private - token = util.prompt_for_user_token(*conf, scope=scope) + token = tk.prompt_for_user_token(*conf, scope=scope) - spotify = Spotify(token) + spotify = tk.Spotify(token) top_tracks = spotify.current_user_top_tracks(limit=5).items top_track_ids = [t.id for t in top_tracks] recommendations = spotify.recommendations(track_ids=top_track_ids).tracks diff --git a/docs/src/examples/scripts/related_artists_top_artist.rst b/docs/src/examples/scripts/related_artists_top_artist.rst index 44546956..b15c7763 100644 --- a/docs/src/examples/scripts/related_artists_top_artist.rst +++ b/docs/src/examples/scripts/related_artists_top_artist.rst @@ -8,14 +8,14 @@ and you have used Spotify enough to have top artists. .. code:: python - from tekore import util, Spotify + import tekore as tk from tekore.scope import scopes - conf = util.config_from_environment() + conf = tk.config_from_environment() scope = scopes.user_top_read + scopes.user_follow_read - token = util.prompt_for_user_token(*conf, scope=scope) + token = tk.prompt_for_user_token(*conf, scope=scope) - spotify = Spotify(token) + spotify = tk.Spotify(token) artist = spotify.current_user_top_artists(limit=1).items[0] related = spotify.artist_related_artists(artist.id) followed = spotify.followed_artists(limit=50) diff --git a/docs/src/examples/scripts/scrape_playlists.rst b/docs/src/examples/scripts/scrape_playlists.rst index 2218e9d7..34907361 100644 --- a/docs/src/examples/scripts/scrape_playlists.rst +++ b/docs/src/examples/scripts/scrape_playlists.rst @@ -15,18 +15,17 @@ a :class:`RetryingSender ` is used. .. code:: python import asyncio - from collections import Counter + import tekore as tk - from tekore import util, Spotify from tekore.scope import scopes - from tekore.sender import AsyncPersistentSender, RetryingSender + from collections import Counter - conf = util.config_from_environment() + conf = tk.config_from_environment() scope = scopes.playlist_read_private - token = util.prompt_for_user_token(*conf, scope=scope) + token = tk.prompt_for_user_token(*conf, scope=scope) - sender = RetryingSender(sender=AsyncPersistentSender()) - spotify = Spotify(token, sender=sender, max_limits_on=True) + sender = tk.RetryingSender(sender=tk.AsyncPersistentSender()) + spotify = tk.Spotify(token, sender=sender, max_limits_on=True) def get_artist(track) -> str: diff --git a/docs/src/examples/scripts/tracks_new_release.rst b/docs/src/examples/scripts/tracks_new_release.rst index 76e2c9e4..04a89626 100644 --- a/docs/src/examples/scripts/tracks_new_release.rst +++ b/docs/src/examples/scripts/tracks_new_release.rst @@ -7,12 +7,12 @@ there is at least new release in the Spotify catalogue. .. code:: python - from tekore import util, Spotify + import tekore as tk - conf = util.config_from_environment() - token = util.request_client_token(*conf[:2]) + conf = tk.config_from_environment() + token = tk.request_client_token(*conf[:2]) - spotify = Spotify(token) + spotify = tk.Spotify(token) simple_album = spotify.new_releases(limit=1).items[0] album = spotify.album(simple_album.id) diff --git a/docs/src/extras/performance/performance.rst b/docs/src/extras/performance/performance.rst index 70b7d85e..7646ede6 100644 --- a/docs/src/extras/performance/performance.rst +++ b/docs/src/extras/performance/performance.rst @@ -43,20 +43,20 @@ Sleeping was used to avoid hitting rate limits, which would affect timing. import numpy as np import pandas as pd + import tekore as tk from time import sleep from timeit import timeit from random import choice - from tekore import Spotify, util, sender from matplotlib import pyplot as plt - conf = util.config_from_environment(return_refresh=True) - token = util.refresh_user_token(conf[0], conf[1], conf[3]) + conf = tk.config_from_environment(return_refresh=True) + token = tk.refresh_user_token(conf[0], conf[1], conf[3]) def mk_sender(size: int = None): - return sender.CachingSender( + return tk.CachingSender( max_size=size, - sender=sender.PersistentSender() + sender=tk.PersistentSender() ) Comparing Transient and Persistent senders: @@ -71,10 +71,10 @@ Comparing Transient and Persistent senders: spotify.album("1qD29n5sWzkZPnMOFSkCIC") sleep(pause) - spotify = Spotify(token, sender=sender.TransientSender()) + spotify = tk.Spotify(token, sender=tk.TransientSender()) t1 = timeit(f'simulate_requests({repeat})', number=1, globals=globals()) - spotify = Spotify(token, sender=sender.PersistentSender()) + spotify = tk.Spotify(token, sender=tk.PersistentSender()) t2 = timeit(f'simulate_requests({repeat})', number=1, globals=globals()) print(t1 - pause * repeat, t2 - pause * repeat) @@ -90,7 +90,7 @@ Requesting a single cacheable resource: stmt = 'spotify.album("1qD29n5sWzkZPnMOFSkCIC")' for n, number in enumerate(x): for i in range(repeat): - spotify = Spotify(token, sender=mk_sender(None)) + spotify = tk.Spotify(token, sender=mk_sender(None)) t[n, i] = timeit(stmt, number=number, globals=globals()) sleep(1) @@ -113,7 +113,7 @@ Effect of cache size: sizes = [1, 100, 25, 75, 50] t = np.zeros(len(sizes)) - spotify = Spotify(token, sender=sender.PersistentSender()) + spotify = tk.Spotify(token, sender=tk.PersistentSender()) tracks = spotify.playlist_tracks('37i9dQZF1DX5Ejj0EkURtP') tracks = spotify.all_items(tracks) track_ids = [t.track.id for t in tracks] @@ -125,7 +125,7 @@ Effect of cache size: sleep(pause) for i, s in enumerate(sizes): - spotify = Spotify(token, sender=mk_sender(s)) + spotify = tk.Spotify(token, sender=mk_sender(s)) simulate_requests(s * 2) t[i] = timeit(f'simulate_requests({repeat})', number=1, globals=globals()) diff --git a/docs/src/getting_started.rst b/docs/src/getting_started.rst index a423ecb3..60654ec8 100644 --- a/docs/src/getting_started.rst +++ b/docs/src/getting_started.rst @@ -17,12 +17,12 @@ and can be used to make basic calls to the API. .. code:: python - from tekore.util import request_client_token + import tekore as tk client_id = 'your_id_here' client_secret = 'your_secret_here' - app_token = request_client_token(client_id, client_secret) + app_token = tk.request_client_token(client_id, client_secret) Calling the API --------------- @@ -32,9 +32,7 @@ on an album given the album ID. .. code:: python - from tekore import Spotify - - spotify = Spotify(app_token) + spotify = tk.Spotify(app_token) album = spotify.album('3RBULTZJ97bvVzZLpxcB0j') for track in album.tracks.items: @@ -54,16 +52,13 @@ Paste the redirected URI in full to the shell to finalise token retrieval. .. code:: python - from tekore.scope import every - from tekore.util import prompt_for_user_token - redirect_uri = 'your_uri_here' - user_token = prompt_for_user_token( + user_token = tk.prompt_for_user_token( client_id, client_secret, redirect_uri, - scope=every + scope=tk.scope.every ) Calling the API as a user diff --git a/docs/src/index.rst b/docs/src/index.rst index 0e1d081f..ea948125 100644 --- a/docs/src/index.rst +++ b/docs/src/index.rst @@ -11,12 +11,12 @@ Here's five lines to get you full access and start playing your top songs. .. code:: python - from tekore import Spotify, util, scope + import tekore as tk - cred = (client_id, client_secret, redirect_uri) - token = util.prompt_for_user_token(*cred, scope=scope.every) + conf = (client_id, client_secret, redirect_uri) + token = tk.prompt_for_user_token(*conf, scope=tk.scope.every) - spotify = Spotify(token) + spotify = tk.Spotify(token) tracks = spotify.current_user_top_tracks(limit=10) spotify.playback_start_tracks([t.id for t in tracks.items]) diff --git a/docs/src/reference.rst b/docs/src/reference.rst index 93c7c268..80f51207 100644 --- a/docs/src/reference.rst +++ b/docs/src/reference.rst @@ -19,6 +19,8 @@ Here's a short summary of each module. serialise util -Two classes, :class:`Credentials ` and -:class:`Spotify ` +Most of the functions and classes defined in each module are made available in the top level :mod:`tekore` namespace. +Importing from the top level is strongly recommended, +because the module structure will be flattened in version 2.0. +For more information see GitHub issue :issue:`81`. diff --git a/readme.rst b/readme.rst index 080fad51..40dbaa4d 100644 --- a/readme.rst +++ b/readme.rst @@ -12,12 +12,12 @@ Here's five lines to get you full access and start playing your top songs. .. code:: python - from tekore import Spotify, util, scope + import tekore as tk - cred = (client_id, client_secret, redirect_uri) - token = util.prompt_for_user_token(*cred, scope=scope.every) + conf = (client_id, client_secret, redirect_uri) + token = tk.prompt_for_user_token(*conf, scope=tk.scope.every) - spotify = Spotify(token) + spotify = tk.Spotify(token) tracks = spotify.current_user_top_tracks(limit=10) spotify.playback_start_tracks([t.id for t in tracks.items]) diff --git a/readme_pypi.rst b/readme_pypi.rst index 888c4be4..5911f325 100644 --- a/readme_pypi.rst +++ b/readme_pypi.rst @@ -11,12 +11,12 @@ Here's five lines to get you full access and start playing your top songs. .. code:: python - from tekore import Spotify, util, scope + import tekore as tk - cred = (client_id, client_secret, redirect_uri) - token = util.prompt_for_user_token(*cred, scope=scope.every) + conf = (client_id, client_secret, redirect_uri) + token = tk.prompt_for_user_token(*conf, scope=tk.scope.every) - spotify = Spotify(token) + spotify = tk.Spotify(token) tracks = spotify.current_user_top_tracks(limit=10) spotify.playback_start_tracks([t.id for t in tracks.items]) diff --git a/tekore/auth/__init__.py b/tekore/auth/__init__.py index 6a667a0f..7da22359 100644 --- a/tekore/auth/__init__.py +++ b/tekore/auth/__init__.py @@ -24,9 +24,9 @@ .. code:: python - from tekore.auth import Credentials + import tekore as tk - cred = Credentials(client_id, client_secret, redirect_uri) + cred = tk.Credentials(client_id, client_secret, redirect_uri) # Client credentials flow app_token = cred.request_client_token() diff --git a/tekore/client/__init__.py b/tekore/client/__init__.py index d060d661..253eb4e8 100644 --- a/tekore/client/__init__.py +++ b/tekore/client/__init__.py @@ -7,10 +7,10 @@ .. code:: python - from tekore import Spotify + import tekore as tk # Initialise the client - spotify = Spotify(token) + spotify = tk.Spotify(token) # Call the API album = spotify.album('3RBULTZJ97bvVzZLpxcB0j') diff --git a/tekore/convert.py b/tekore/convert.py index 4dce2210..443812b2 100644 --- a/tekore/convert.py +++ b/tekore/convert.py @@ -16,14 +16,14 @@ .. code:: python - from tekore.convert import to_url, from_url + import tekore as tk # Create ULR for opening an album in the browser mountain = '3RBULTZJ97bvVzZLpxcB0j' - m_url = to_url('album', mountain) + m_url = tk.to_url('album', mountain) # Parse input - type_, id_ = from_url(m_url) + type_, id_ = tk.from_url(m_url) print(f'Got type `{type_}` with ID `{id_}`') """ diff --git a/tekore/model/__init__.py b/tekore/model/__init__.py index e08a48ae..8162b2ec 100644 --- a/tekore/model/__init__.py +++ b/tekore/model/__init__.py @@ -6,10 +6,10 @@ .. code:: python - from tekore import Spotify + import tekore as tk # Call the API - spotify = Spotify(token) + spotify = tk.Spotify(token) album = spotify.album('3RBULTZJ97bvVzZLpxcB0j') # Use the response diff --git a/tekore/scope.py b/tekore/scope.py index 90369a57..01cd17f9 100644 --- a/tekore/scope.py +++ b/tekore/scope.py @@ -7,12 +7,12 @@ .. code:: python + import tekore as tk from tekore.scope import scopes - from tekore.util import prompt_for_user_token cred = (client_id, client_secret, redirect_uri) scope = scopes.user_read_email + scopes.user_read_private - token = prompt_for_user_token(*cred, scope) + token = tk.prompt_for_user_token(*cred, scope) Some ready-made scopes are also made available. diff --git a/tekore/sender.py b/tekore/sender.py index f134000c..73a6be77 100644 --- a/tekore/sender.py +++ b/tekore/sender.py @@ -23,11 +23,10 @@ .. code:: python - from tekore import Spotify, Credentials - from tekore.sender import PersistentSender, AsyncTransientSender + import tekore as tk - Credentials(*conf, sender=PersistentSender()) - Spotify(sender=AsyncTransientSender()) + tk.Credentials(*conf, sender=tk.PersistentSender()) + tk.Spotify(sender=tk.AsyncTransientSender()) Synchronous senders wrap around the :mod:`requests` library, while asynchronous senders use :mod:`httpx`. @@ -36,13 +35,11 @@ .. code:: python - from tekore.sender import TransientSender - proxies = { 'http': 'http://10.10.10.10:8000', 'https': 'http://10.10.10.10:8000', } - TransientSender(proxies=proxies) + tk.TransientSender(proxies=proxies) Custom instances of :class:`requests.Session` or :class:`httpx.AsyncClient` can also be used. @@ -50,17 +47,15 @@ .. code:: python from requests import Session - from tekore.sender import PresistentSender, SingletonSender session = Session() session.proxies = proxies # Attach the session to a sender - PersistentSender(session) - SingletonSender.session = session + tk.PersistentSender(session) + tk.SingletonSender.session = session Default senders and keyword arguments can be changed. -Note that this requires importing the whole sender module. :attr:`default_sender_instance` has precedence over :attr:`default_sender_type`. Using an :class:`ExtendingSender` as the default type will raise an error as it tries to instantiate itself recursively. @@ -69,17 +64,15 @@ .. code:: python - from tekore import sender, Spotify - - sender.default_sender_type = sender.PersistentSender - sender.default_sender_instance = sender.RetryingSender() - sender.default_requests_kwargs = {'proxies': proxies} + tk.sender.default_sender_type = tk.PersistentSender + tk.sender.default_sender_instance = tk.RetryingSender() + tk.sender.default_requests_kwargs = {'proxies': proxies} # Now the following are equal Spotify() Spotify( - sender=sender.RetryingSender( - sender=sender.PersistentSender(proxies=proxies) + sender=tk.RetryingSender( + sender=tk.PersistentSender(proxies=proxies) ) ) """ diff --git a/tekore/serialise.py b/tekore/serialise.py index d1d4e0ca..cec4ff93 100644 --- a/tekore/serialise.py +++ b/tekore/serialise.py @@ -7,10 +7,10 @@ .. code:: python - from tekore import Spotify + import tekore as tk # Call the Web API - spotify = Spotify(user_token) + spotify = tk.Spotify(user_token) user = spotify.current_user() # Inspect the content diff --git a/tekore/util/config.py b/tekore/util/config.py index 634396f6..16218bfb 100644 --- a/tekore/util/config.py +++ b/tekore/util/config.py @@ -3,17 +3,17 @@ .. code:: python - from tekore.util import config_from_environment, config_from_file + import tekore as tk - client_id, client_secret, redirect_uri = config_from_environment() - client_id, client_secret, redirect_uri = config_from_file(filename) + client_id, client_secret, redirect_uri = tk.config_from_environment() + client_id, client_secret, redirect_uri = tk.config_from_file(filename) By default, only client ID, client secret and redirect URI are returned. To return a user's refresh token as well, set a boolean flag. .. code:: python - id_, secret, uri, refresh = config_from_environment(return_refresh=True) + id_, secret, uri, refresh = tk.config_from_environment(return_refresh=True) Values are read from preset names, which can be changed. Note that changing values requires importing the whole config module. @@ -31,7 +31,7 @@ .. code:: python - config_to_file(filename, (id_, secret, uri, refresh)) + tk.config_to_file(filename, (id_, secret, uri, refresh)) When reading configuration, if values are missing, a :class:`MissingConfigurationWarning` is issued. @@ -41,7 +41,7 @@ from warnings import simplefilter - simplefilter('ignore', MissingConfigurationWarning) + simplefilter('ignore', tk.MissingConfigurationWarning) """ from os import environ diff --git a/tekore/util/credentials.py b/tekore/util/credentials.py index e2f270b8..66279d0a 100644 --- a/tekore/util/credentials.py +++ b/tekore/util/credentials.py @@ -3,16 +3,16 @@ .. code:: python - from tekore import util + import tekore as tk - conf = util.config_from_environment() + conf = tk.config_from_environment() # Request tokens - app_token = util.request_client_token(*conf[:2]) - user_token = util.prompt_for_user_token(*conf) + app_token = tk.request_client_token(*conf[:2]) + user_token = tk.prompt_for_user_token(*conf) # Reload user token - user_token = util.refresh_user_token(*conf[:2], refresh_token) + user_token = tk.refresh_user_token(*conf[:2], refresh_token) """ import webbrowser