Support short links (#301)

docs/src/advanced_usage.rst

@@ -224,6 +224,22 @@ 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.
 
+Short links
+-----------
+The Spotify emits shortened URLs for e.g. playlists when sharing them
+through the mobile application. Unfortunately, they are not usable as
+they are, but they can be expanded to their full form. Tekore provides
+two utilities for processing them: :func:`is_short_link` and
+:meth:`Spotify.follow_short_link`.
+
+.. autolink-preface:: from tekore import Spotify as spotify, is_short_link, from_url
+.. code:: python
+
+    link = '...'
+    if is_short_link(link):
+        link = spotify.follow_short_link(link)
+    type, id_ = from_url(link)
+
 Localisation
 ------------
 Many API calls that retrieve track information accept a ``market`` or

docs/src/reference/client.rst

@@ -85,12 +85,16 @@ Non-endpoint methods
    Spotify.chunked
    Spotify.max_limits
    Spotify.token_as
+   Spotify.follow_short_link
+   is_short_link
    Spotify.send
    Spotify.close
 
 .. automethod:: Spotify.chunked
 .. automethod:: Spotify.max_limits
 .. automethod:: Spotify.token_as
+.. automethod:: Spotify.follow_short_link
+.. autofunction:: is_short_link
 .. automethod:: Spotify.send
 .. automethod:: Spotify.close
 

docs/src/release_notes.rst

@@ -13,6 +13,11 @@ Fixed
   class to a nullable string, complying with the `API Documentation 
   <https://developer.spotify.com/documentation/web-api/reference/get-an-episode>`_
 
+Added
+*****
+- Add support for short URLs as :func:`is_short_link` and
+  :meth:`follow_short_link <Spotify.follow_short_link>` (:issue:`301`)
+
 5.1.1 (2023-10-14)
 ------------------
 Fixed

src/tekore/__init__.py

@@ -27,7 +27,7 @@
     request_client_token,
     scope,
 )
-from ._client import Spotify
+from ._client import Spotify, is_short_link
 from ._config import (
     MissingConfigurationWarning,
     config_from_environment,

src/tekore/_client/__init__.py

@@ -1 +1,2 @@
 from .full import Spotify
+from .short_link import is_short_link

src/tekore/_client/full.py

@@ -20,6 +20,7 @@
     SpotifyUser,
 )
 from .paging import SpotifyPaging
+from .short_link import SpotifyShortLink
 
 
 class Spotify(
@@ -40,6 +41,7 @@ class Spotify(
     SpotifyTrack,
     SpotifyUser,
     SpotifyPaging,
+    SpotifyShortLink,
 ):
     """
     Bases: :class:`tekore.Client`.

src/tekore/_client/short_link.py

@@ -0,0 +1,39 @@
+from .._sender import Request, Response, send_and_process
+from .._sender.base import Sender
+from .base import SpotifyBase
+
+
+def is_short_link(url: str) -> bool:
+    """Determine if URL is a Spotify short link."""
+    return "spotify.link/" in url
+
+
+def _process_short_link(request: Request, response: Response) -> str:
+    if response.status_code == 307:
+        return response.headers["location"]
+    else:
+        return request.url
+
+
+@send_and_process(_process_short_link)
+def _send_short_link(self: Sender, request: Request):
+    return request
+
+
+class SpotifyShortLink(SpotifyBase):
+    """Spotify short link."""
+
+    def follow_short_link(self, link: str) -> str:
+        """
+        Follow redirect of a short link to get the underlying resource URL.
+
+        Safely also accept a direct link, request a redirect and return
+        the original URL. Also use the underlying sender for an unauthenticated request.
+
+        Returns
+        -------
+        url
+            result of the short link redirect
+        """
+        request = self._request("HEAD", link)
+        return _send_short_link(self.sender, request)

tests/client/_resources.py

@@ -30,6 +30,8 @@
 user_id_hash = "a#a"
 user_ids = [user_id, "samsmithworld"]
 
+short_link = "https://spotify.link/hRkBrwub9xb"
+
 show_id = "0Lsi13D8nWRkwbEkfNeItS"
 show_ids = [show_id, "7Arl2fVUFHCGyNZwM39bJO"]
 episode_id = "3YPKYYsqrWZUdZTzF6dZ3F"

tests/client/full.py

@@ -174,6 +174,7 @@ def test_all_endpoints_have_scope_attributes(self, client):
             "chunked",
             "max_limits",
             "token_as",
+            "follow_short_link",
         }
         for name, method in getmembers(client, predicate=ismethod):
             if name.startswith("_") or name in skips:

tests/client/short_link.py

@@ -0,0 +1,42 @@
+import pytest
+
+from tekore import from_url, is_short_link
+
+from ._resources import short_link, track_id
+
+
+class TestSpotifyShortLink:
+    def test_random_string_is_not_short_link(self):
+        assert not is_short_link("asdf")
+
+    def test_random_url_is_not_short_link(self):
+        assert not is_short_link("https://spotify.org/resource")
+
+    def test_valid_short_link(self):
+        assert is_short_link("https://spotify.link/resource")
+
+    def test_short_link_does_not_need_https(self):
+        assert is_short_link("spotify.link/resource")
+
+    def test_follow_short_link(self, app_client):
+        resolved = app_client.follow_short_link(short_link)
+        assert short_link != resolved
+        from_url(resolved)
+
+    @pytest.mark.asyncio
+    async def test_async_follow_short_link(self, app_aclient):
+        resolved = await app_aclient.follow_short_link(short_link)
+        assert short_link != resolved
+        from_url(resolved)
+
+    def test_follow_short_link_already_resolved(self, app_client):
+        link = "https://open.spotify.com/track/" + track_id
+        resolved = app_client.follow_short_link(link)
+        assert link == resolved
+        from_url(resolved)
+
+    def test_follow_short_link_does_not_authorise(self, app_client, httpx_mock):
+        httpx_mock.add_response(200)
+        app_client.follow_short_link(short_link)
+        (request,) = httpx_mock.get_requests()
+        assert "authorization" not in request.headers