Documentation changes

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,35 +121,32 @@ 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,
 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
 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 <tekore.sender.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)

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:

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()
 

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 = {}
 

docs/src/examples/client_configurations.rst

@@ -12,23 +12,21 @@ 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.
 
 .. code:: python
 
     # 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 <tekore.sender.SingletonSender>` instead.

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")

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)
 

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}'

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)

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]
 

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)

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