71class SoundCloud:
 72    """
 73    SoundCloud v2 API client
 74    """
 75
 76    _DEFAULT_USER_AGENT = (
 77        "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:93.0) Gecko/20100101 Firefox/93.0"
 78    )
 79    _ASSETS_SCRIPTS_REGEX = re.compile(
 80        r"src=\"(https:\/\/a-v2\.sndcdn\.com/assets/.*\.js)\""
 81    )
 82    _CLIENT_ID_REGEX = re.compile(r"client_id:\"([^\"]+)\"")
 83    client_id: str
 84    """SoundCloud client ID. Needed for all requests."""
 85    _user_agent: str
 86    _auth_token: Optional[str]
 87    _authorization: Optional[str]
 88
 89    def __init__(
 90        self,
 91        client_id: Optional[str] = None,
 92        auth_token: Optional[str] = None,
 93        user_agent: str = _DEFAULT_USER_AGENT,
 94        impersonate: BrowserTypeLiteral = "chrome",
 95    ) -> None:
 96        self._impersonate = impersonate
 97        self._session: requests.Session = requests.Session(impersonate=impersonate)
 98        if not client_id:
 99            client_id = self.generate_client_id(impersonate=impersonate)
100
101        self.client_id = client_id
102        self._user_agent = user_agent
103        self._auth_token = None
104        self._authorization = None
105        self.auth_token = auth_token
106
107    @property
108    def auth_token(self) -> Optional[str]:
109        """SoundCloud auth token. Only needed for some requests."""
110        return self._auth_token
111
112    @auth_token.setter
113    def auth_token(self, new_auth_token: Optional[str]) -> None:
114        if new_auth_token is not None:
115            if new_auth_token.startswith("OAuth"):
116                new_auth_token = new_auth_token.split()[-1]
117        self._authorization = f"OAuth {new_auth_token}" if new_auth_token else None
118        self._auth_token = new_auth_token
119
120    @auth_token.deleter
121    def auth_token(self):
122        self.auth_token = None
123
124    def _get_default_headers(self) -> Dict[str, str]:
125        return {"User-Agent": self._user_agent}
126
127    @classmethod
128    def generate_client_id(cls, impersonate: BrowserTypeLiteral = "chrome") -> str:
129        """Generates a SoundCloud client ID
130
131        Raises:
132            ClientIDGenerationError: Client ID could not be generated.
133
134        Returns:
135            str: Valid client ID
136        """
137        with requests.Session(impersonate=impersonate) as s:
138            r = s.get("https://soundcloud.com")
139            r.raise_for_status()
140            matches = cls._ASSETS_SCRIPTS_REGEX.findall(r.text)
141            if not matches:
142                raise ClientIDGenerationError("No asset scripts found")
143            for url in matches:
144                r = s.get(url)
145                r.raise_for_status()
146                client_id = cls._CLIENT_ID_REGEX.search(r.text)
147                if client_id:
148                    return client_id.group(1)
149            raise ClientIDGenerationError(f"Could not find client_id in script '{url}'")
150
151    def is_client_id_valid(self) -> bool:
152        """
153        Checks if current client_id is valid
154        """
155        try:
156            TrackRequest(self, track_id=1032303631, use_auth=False)
157            return True
158        except HTTPError as err:
159            if err.response.status_code == 401:
160                return False
161            else:
162                raise
163
164    def is_auth_token_valid(self) -> bool:
165        """
166        Checks if current auth_token is valid
167        """
168        try:
169            MeRequest(self)
170            return True
171        except HTTPError as err:
172            if err.response.status_code == 401:
173                return False
174            else:
175                raise
176
177    def get_me(self) -> Optional[User]:
178        """
179        Gets the user associated with client's auth token
180        """
181        return MeRequest(self)
182
183    def get_my_history(self, **kwargs) -> Generator[HistoryItem, None, None]:
184        """
185        Returns the stream of recently listened tracks
186        for the client's auth token
187        """
188        return MeHistoryRequest(self, **kwargs)
189
190    def get_my_stream(self, **kwargs) -> Generator[StreamItem, None, None]:
191        """
192        Returns the stream of recent uploads/reposts
193        for the client's auth token
194        """
195        return MeStreamRequest(self, **kwargs)
196
197    def resolve(self, url: str) -> Optional[SearchItem]:
198        """
199        Returns the resource at the given URL if it
200        exists, otherwise return None
201        """
202        return ResolveRequest(self, url=url)
203
204    def search(self, query: str, **kwargs) -> Generator[SearchItem, None, None]:
205        """
206        Search for users, tracks, and playlists
207        """
208        return SearchRequest(self, q=query, **kwargs)
209
210    def search_albums(
211        self, query: str, **kwargs
212    ) -> Generator[AlbumPlaylist, None, None]:
213        """
214        Search for albums (not playlists)
215        """
216        return SearchAlbumsRequest(self, q=query, **kwargs)
217
218    def search_playlists(
219        self, query: str, **kwargs
220    ) -> Generator[AlbumPlaylist, None, None]:
221        """
222        Search for playlists
223        """
224        return SearchPlaylistsRequest(self, q=query, **kwargs)
225
226    def search_tracks(self, query: str, **kwargs) -> Generator[Track, None, None]:
227        """
228        Search for tracks
229        """
230        return SearchTracksRequest(self, q=query, **kwargs)
231
232    def search_users(self, query: str, **kwargs) -> Generator[User, None, None]:
233        """
234        Search for users
235        """
236        return SearchUsersRequest(self, q=query, **kwargs)
237
238    def get_tag_tracks_recent(self, tag: str, **kwargs) -> Generator[Track, None, None]:
239        """
240        Get most recent tracks for this tag
241        """
242        return TagRecentTracksRequest(self, tag=tag, **kwargs)
243
244    def get_playlist(self, playlist_id: int) -> Optional[BasicAlbumPlaylist]:
245        """
246        Returns the playlist with the given playlist_id.
247        If the ID is invalid, return None
248        """
249        return PlaylistRequest(self, playlist_id=playlist_id)
250
251    def post_playlist(
252        self, sharing: Literal["private", "public"], title: str, tracks: List[int]
253    ) -> Optional[BasicAlbumPlaylist]:
254        """
255        Create a new playlist
256        """
257        body = {"playlist": {"sharing": sharing, "title": title, "tracks": tracks}}
258        return PostPlaylistRequest(self, body=body)
259
260    def delete_playlist(self, playlist_id: int) -> Optional[NoContentResponse]:
261        """
262        Delete a playlist
263        """
264        return DeletePlaylistRequest(self, playlist_id=playlist_id)
265
266    def get_playlist_likers(
267        self, playlist_id: int, **kwargs
268    ) -> Generator[User, None, None]:
269        """
270        Get people who liked this playlist
271        """
272        return PlaylistLikersRequest(self, playlist_id=playlist_id, **kwargs)
273
274    def get_playlist_reposters(
275        self, playlist_id: int, **kwargs
276    ) -> Generator[User, None, None]:
277        """
278        Get people who reposted this playlist
279        """
280        return PlaylistRepostersRequest(self, playlist_id=playlist_id, **kwargs)
281
282    def get_track(self, track_id: int) -> Optional[BasicTrack]:
283        """
284        Returns the track with the given track_id.
285        If the ID is invalid, return None
286        """
287        return TrackRequest(self, track_id=track_id)
288
289    def get_tracks(
290        self,
291        track_ids: List[int],
292        playlistId: Optional[int] = None,
293        playlistSecretToken: Optional[str] = None,
294        **kwargs,
295    ) -> List[BasicTrack]:
296        """
297        Returns the tracks with the given track_ids.
298        Can be used to get track info for hidden tracks in a hidden playlist.
299        """
300        if playlistId is not None:
301            kwargs["playlistId"] = playlistId
302        if playlistSecretToken is not None:
303            kwargs["playlistSecretToken"] = playlistSecretToken
304        return TracksRequest(
305            self, ids=",".join([str(id) for id in track_ids]), **kwargs
306        )
307
308    def get_track_albums(
309        self, track_id: int, **kwargs
310    ) -> Generator[BasicAlbumPlaylist, None, None]:
311        """
312        Get albums that this track is in
313        """
314        return TrackAlbumsRequest(self, track_id=track_id, **kwargs)
315
316    def get_track_playlists(
317        self, track_id: int, **kwargs
318    ) -> Generator[BasicAlbumPlaylist, None, None]:
319        """
320        Get playlists that this track is in
321        """
322        return TrackPlaylistsRequest(self, track_id=track_id, **kwargs)
323
324    def get_track_comments(
325        self, track_id: int, threaded: int = 0, **kwargs
326    ) -> Generator[BasicComment, None, None]:
327        """
328        Get comments on this track
329        """
330        return TrackCommentsRequest(
331            self, track_id=track_id, threaded=threaded, **kwargs
332        )
333
334    def get_track_comments_with_interactions(
335        self, track_id: int, threaded: int = 0, **kwargs
336    ) -> Generator[CommentWithInteractions, None, None]:
337        """
338        Get comments on this track with interaction data. Requires authentication.
339        """
340        track = self.get_track(track_id)
341        if not track:
342            return
343        track_urn = track.urn
344        creator_urn = track.user.urn
345        comments = self.get_track_comments(track_id, threaded, **kwargs)
346        while True:
347            chunk = list(itertools.islice(comments, 10))
348            if not chunk:
349                return
350            comment_urns = [comment.self.urn for comment in chunk]
351            result = UserInteractionsRequest(
352                self,
353                UserInteractionsQueryParams(
354                    creator_urn,
355                    "sc:interactiontype:reaction",
356                    track_urn,
357                    comment_urns,
358                ),
359            )
360            if not result:
361                return
362            comments_with_interactions = []
363            for comment, user_interactions, creator_interactions in zip(
364                chunk, result.user, result.creator
365            ):
366                assert user_interactions.interactionCounts is not None
367                likes = list(
368                    filter(
369                        lambda x: (
370                            x.interactionTypeValueUrn == "sc:interactiontypevalue:like"
371                        ),
372                        user_interactions.interactionCounts,
373                    )
374                )
375                num_likes = likes[0].count if likes else 0
376                comments_with_interactions.append(
377                    CommentWithInteractions(
378                        comment=comment,
379                        likes=num_likes or 0,
380                        liked_by_creator=creator_interactions.userInteraction
381                        == "sc:interactiontypevalue:like",
382                        liked_by_user=user_interactions.userInteraction
383                        == "sc:interactiontypevalue:like",
384                    )
385                )
386            yield from comments_with_interactions
387
388    def get_track_likers(self, track_id: int, **kwargs) -> Generator[User, None, None]:
389        """
390        Get users who liked this track
391        """
392        return TrackLikersRequest(self, track_id=track_id, **kwargs)
393
394    def get_track_related(
395        self, track_id: int, **kwargs
396    ) -> Generator[BasicTrack, None, None]:
397        """
398        Get related tracks
399        """
400        return TrackRelatedRequest(self, track_id=track_id, **kwargs)
401
402    def get_track_reposters(
403        self, track_id: int, **kwargs
404    ) -> Generator[User, None, None]:
405        """
406        Get users who reposted this track
407        """
408        return TrackRepostersRequest(self, track_id=track_id, **kwargs)
409
410    def get_track_original_download(
411        self, track_id: int, token: Optional[str] = None
412    ) -> Optional[str]:
413        """
414        Get track original download link. If track is private,
415        requires secret token to be provided (last part of secret URL).
416        Requires authentication.
417        """
418        if token is not None:
419            download = TrackOriginalDownloadRequest(
420                self, track_id=track_id, secret_token=token
421            )
422        else:
423            download = TrackOriginalDownloadRequest(self, track_id=track_id)
424        if download is None:
425            return None
426        else:
427            return download.redirectUri
428
429    def get_user(self, user_id: int) -> Optional[User]:
430        """
431        Returns the user with the given user_id.
432        If the ID is invalid, return None
433        """
434        return UserRequest(self, user_id=user_id)
435
436    def get_user_by_username(self, username: str) -> Optional[User]:
437        """
438        Returns the user with the given username.
439        If the username is invalid, return None
440        """
441        resource = self.resolve(f"https://soundcloud.com/{username}")
442        if resource and isinstance(resource, User):
443            return resource
444        else:
445            return None
446
447    def get_user_comments(
448        self, user_id: int, **kwargs
449    ) -> Generator[Comment, None, None]:
450        """
451        Get comments by this user
452        """
453        return UserCommentsRequest(self, user_id=user_id, **kwargs)
454
455    def get_conversation_messages(
456        self, user_id: int, conversation_id: int, **kwargs
457    ) -> Generator[Message, None, None]:
458        """
459        Get messages in this conversation
460        """
461        return UserConversationMessagesRequest(
462            self, user_id=user_id, conversation_id=conversation_id, **kwargs
463        )
464
465    def get_conversations(
466        self, user_id: int, **kwargs
467    ) -> Generator[Conversation, None, None]:
468        """
469        Get conversations including this user
470        """
471        return UserConversationsRequest(self, user_id=user_id, **kwargs)
472
473    def get_unread_conversations(
474        self, user_id: int, **kwargs
475    ) -> Generator[Conversation, None, None]:
476        """
477        Get conversations unread by this user
478        """
479        return UserConversationsUnreadRequest(self, user_id=user_id, **kwargs)
480
481    def get_user_emails(
482        self, user_id: int, **kwargs
483    ) -> Generator[UserEmail, None, None]:
484        """
485        Get user's email addresses. Requires authentication.
486        """
487        return UserEmailsRequest(self, user_id=user_id, **kwargs)
488
489    def get_user_featured_profiles(
490        self, user_id: int, **kwargs
491    ) -> Generator[User, None, None]:
492        """
493        Get profiles featured by this user
494        """
495        return UserFeaturedProfilesRequest(self, user_id=user_id, **kwargs)
496
497    def get_user_followers(self, user_id: int, **kwargs) -> Generator[User, None, None]:
498        """
499        Get user's followers
500        """
501        return UserFollowersRequest(self, user_id=user_id, **kwargs)
502
503    def get_user_following(self, user_id: int, **kwargs) -> Generator[User, None, None]:
504        """
505        Get users this user is following
506        """
507        return UserFollowingsRequest(self, user_id=user_id, **kwargs)
508
509    def get_user_likes(self, user_id: int, **kwargs) -> Generator[Like, None, None]:
510        """
511        Get likes by this user
512        """
513        return UserLikesRequest(self, user_id=user_id, **kwargs)
514
515    def get_user_related_artists(
516        self, user_id: int, **kwargs
517    ) -> Generator[User, None, None]:
518        """
519        Get artists related to this user
520        """
521        return UserRelatedArtistsRequest(self, user_id=user_id, **kwargs)
522
523    def get_user_reposts(
524        self, user_id: int, **kwargs
525    ) -> Generator[RepostItem, None, None]:
526        """
527        Get reposts by this user
528        """
529        return UserRepostsRequest(self, user_id=user_id, **kwargs)
530
531    def get_user_stream(
532        self, user_id: int, **kwargs
533    ) -> Generator[StreamItem, None, None]:
534        """
535        Returns generator of track uploaded by given user and
536        reposts by this user
537        """
538        return UserStreamRequest(self, user_id=user_id, **kwargs)
539
540    def get_user_tracks(
541        self, user_id: int, **kwargs
542    ) -> Generator[BasicTrack, None, None]:
543        """
544        Get tracks uploaded by this user
545        """
546        return UserTracksRequest(self, user_id=user_id, **kwargs)
547
548    def get_user_popular_tracks(
549        self, user_id: int, **kwargs
550    ) -> Generator[BasicTrack, None, None]:
551        """
552        Get popular tracks uploaded by this user
553        """
554        return UserToptracksRequest(self, user_id=user_id, **kwargs)
555
556    def get_user_albums(
557        self, user_id: int, **kwargs
558    ) -> Generator[BasicAlbumPlaylist, None, None]:
559        """
560        Get albums uploaded by this user
561        """
562        return UserAlbumsRequest(self, user_id=user_id, **kwargs)
563
564    def get_user_playlists(
565        self, user_id: int, **kwargs
566    ) -> Generator[BasicAlbumPlaylist, None, None]:
567        """
568        Get playlists uploaded by this user
569        """
570        return UserPlaylistsRequest(self, user_id=user_id, **kwargs)
571
572    def get_user_links(self, user_urn: str, **kwargs) -> List[WebProfile]:
573        """
574        Get links in this user's description
575        """
576        return UserWebProfilesRequest(self, user_urn=user_urn, **kwargs)