Documentation

.github/workflows/docs.yml

@@ -0,0 +1,48 @@
+name: website
+
+# build the documentation whenever there are new commits on main
+on:
+  push:
+    branches:
+      - main
+    # Alternative: only build for tags.
+    # tags:
+    #   - '*'
+
+# security: restrict permissions for CI jobs.
+permissions:
+  contents: read
+
+jobs:
+  # Build the documentation and upload the static HTML files as an artifact.
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+
+      # ADJUST THIS: install all dependencies (including pdoc)
+      - run: pip install -e .[docs]
+      # ADJUST THIS: build your documentation into docs/.
+      - run: pdoc soundcloud --docformat google -o docs -t pdoc
+
+      - uses: actions/upload-pages-artifact@v2
+        with:
+          path: docs/
+
+  # Deploy the artifact to GitHub pages.
+  # This is a separate job so that only actions/deploy-pages has the necessary permissions.
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v2

README.md

@@ -9,7 +9,7 @@
 
 Python wrapper for some of the internal v2 SoundCloud API (read/GET only methods). Does not require an API key.
 
-## NOTE: This is NOT the official [SoundCloud developer API](https://developers.soundcloud.com/docs/api/guide)
+### NOTE: This is NOT the official [SoundCloud developer API](https://developers.soundcloud.com/docs/api/guide)
 
 SoundCloud is not accepting any more application registration requests [^1] so
 I made this library so developers can use SoundCloud's internal API for their projects.

pdoc/module.html.jinja2

@@ -0,0 +1,2 @@
+{% extends "default/module.html.jinja2" %}
+{% macro inherited(cls) %}{% endmacro %}

setup.py

@@ -9,16 +9,16 @@ def readme():
 
 setup(
     name="soundcloud-v2",
-    version="1.3.8",
-    description="Python wrapper for the v2 SoundCloud API",
+    version="1.3.9",
+    description="Python wrapper for the internal v2 SoundCloud API. Does not require an API key.",
     long_description=readme(),
     long_description_content_type="text/markdown",
     author="7x11x13",
     author_email="[email protected]",
     url="https://github.com/7x11x13/soundcloud.py",
     packages=["soundcloud", "soundcloud.resource"],
     install_requires=["dacite", "python-dateutil>=2.8.2", "requests"],
-    extras_require={"test": ["coveralls", "pytest", "pytest-dotenv"]},
+    extras_require={"test": ["coveralls", "pytest", "pytest-dotenv"], "docs": ["pdoc"]},
     classifiers=[
         "Programming Language :: Python :: 3.7",
         "Programming Language :: Python :: 3.8",

soundcloud/__init__.py

@@ -1,23 +1,58 @@
-from soundcloud.resource.aliases import (Like, RepostItem, SearchItem,
-                                         StreamItem)
-from soundcloud.resource.comment import Comment, CommentSelf, CommentTrack
-from soundcloud.resource.conversation import Conversation
-from soundcloud.resource.download import OriginalDownload
-from soundcloud.resource.history import HistoryItem
-from soundcloud.resource.like import PlaylistLike, TrackLike
-from soundcloud.resource.message import Message
-from soundcloud.resource.playlist import (AlbumPlaylist, AlbumPlaylistNoTracks,
-                                          BasicAlbumPlaylist)
-from soundcloud.resource.stream import (PlaylistStreamItem,
-                                        PlaylistStreamRepostItem,
-                                        TrackStreamItem, TrackStreamRepostItem)
-from soundcloud.resource.track import (BasicTrack, CommentTrack, Format, Media,
-                                       MiniTrack, PublisherMetadata, Track,
-                                       Transcoding)
-from soundcloud.resource.user import (Badges, BasicUser, CreatorSubscription,
-                                      Product, User, UserEmail)
-from soundcloud.resource.visuals import Visual, Visuals
-from soundcloud.resource.web_profile import WebProfile
-from soundcloud.soundcloud import SoundCloud
-
-__version__ = "1.3.8"
+"""
+# soundcloud.py
+
+[![Tests](https://github.com/7x11x13/soundcloud.py/actions/workflows/ci.yml/badge.svg)](https://github.com/7x11x13/soundcloud.py/actions/workflows/ci.yml)
+[![Coverage Status](https://coveralls.io/repos/github/7x11x13/soundcloud.py/badge.svg?branch=main)](https://coveralls.io/github/7x11x13/soundcloud.py?branch=main)
+[![Supported Python Versions](https://img.shields.io/badge/python-3.7%2C%203.8%2C%203.9%2C%203.10%2C%203.11%2C%203.12-blue.svg)](https://pypi.org/project/soundcloud-v2/)
+[![Version](https://img.shields.io/pypi/v/soundcloud-v2.svg)](https://pypi.org/project/soundcloud-v2/)
+[![License](https://img.shields.io/pypi/l/soundcloud-v2.svg)](https://pypi.org/project/soundcloud-v2/)
+[![Monthly Downloads](https://pepy.tech/badge/soundcloud-v2/month)](https://pepy.tech/project/soundcloud-v2)
+
+Python wrapper for some of the internal v2 SoundCloud API (read/GET only methods). Does not require an API key.
+
+### Note: This is NOT the official [SoundCloud developer API](https://developers.soundcloud.com/docs/api/guide)
+
+SoundCloud is not accepting any more application registration requests [^1] so
+I made this library so developers can use SoundCloud's internal API for their projects.
+
+
+[^1]: https://docs.google.com/forms/d/e/1FAIpQLSfNxc82RJuzC0DnISat7n4H-G7IsPQIdaMpe202iiHZEoso9w/closedform
+
+## Installation
+
+```bash
+pip install soundcloud-v2
+```
+
+## Example
+
+```python
+from soundcloud import SoundCloud
+
+sc = SoundCloud(auth_token="auth_token")
+assert sc.is_client_id_valid()
+assert sc.is_auth_token_valid()
+me = sc.get_user_by_username("7x11x13")
+assert me.permalink == "7x11x13"
+```
+
+## Notes on `auth_token`
+Some methods require authentication in the form of an OAuth2 access token.
+You can find your token in your browser cookies for SoundCloud under the name "oauth_token".
+A new token will be generated each time you log out and log back in.
+
+## License
+[MIT](https://choosealicense.com/licenses/mit/)
+
+"""
+
+from soundcloud.exceptions import *
+from soundcloud.exceptions import __all__ as ex_all
+from soundcloud.resource import *
+from soundcloud.resource import __all__ as res_all
+from soundcloud.soundcloud import *
+from soundcloud.soundcloud import __all__ as sc_all
+
+__version__ = "1.3.9"
+
+__all__ = sc_all + ex_all + res_all

soundcloud/exceptions.py

@@ -0,0 +1,7 @@
+class ClientIDGenerationError(Exception):
+    """
+    Raised when a client ID could not be dynamically generated.
+    """
+
+
+__all__ = ["ClientIDGenerationError"]

soundcloud/resource/__init__.py

@@ -0,0 +1,78 @@
+from soundcloud.resource.aliases import Like, RepostItem, SearchItem, StreamItem
+from soundcloud.resource.comment import BasicComment, Comment, CommentSelf
+from soundcloud.resource.conversation import Conversation
+from soundcloud.resource.download import OriginalDownload
+from soundcloud.resource.history import HistoryItem
+from soundcloud.resource.like import PlaylistLike, TrackLike
+from soundcloud.resource.message import Message
+from soundcloud.resource.playlist import (
+    AlbumPlaylist,
+    AlbumPlaylistNoTracks,
+    BasicAlbumPlaylist,
+)
+from soundcloud.resource.stream import (
+    PlaylistStreamItem,
+    PlaylistStreamRepostItem,
+    TrackStreamItem,
+    TrackStreamRepostItem,
+)
+from soundcloud.resource.track import (
+    BasicTrack,
+    CommentTrack,
+    Format,
+    Media,
+    MiniTrack,
+    PublisherMetadata,
+    Track,
+    Transcoding,
+)
+from soundcloud.resource.user import (
+    Badges,
+    BasicUser,
+    CreatorSubscription,
+    Product,
+    User,
+    UserEmail,
+)
+from soundcloud.resource.visuals import Visual, Visuals
+from soundcloud.resource.web_profile import WebProfile
+
+__all__ = [
+    "Like",
+    "RepostItem",
+    "SearchItem",
+    "StreamItem",
+    "BasicComment",
+    "Comment",
+    "CommentSelf",
+    "Conversation",
+    "OriginalDownload",
+    "HistoryItem",
+    "PlaylistLike",
+    "TrackLike",
+    "Message",
+    "AlbumPlaylist",
+    "AlbumPlaylistNoTracks",
+    "BasicAlbumPlaylist",
+    "PlaylistStreamItem",
+    "PlaylistStreamRepostItem",
+    "TrackStreamItem",
+    "TrackStreamRepostItem",
+    "BasicTrack",
+    "Format",
+    "Media",
+    "MiniTrack",
+    "PublisherMetadata",
+    "Track",
+    "Transcoding",
+    "CommentTrack",
+    "Badges",
+    "BasicUser",
+    "CreatorSubscription",
+    "Product",
+    "User",
+    "UserEmail",
+    "Visual",
+    "Visuals",
+    "WebProfile",
+]

soundcloud/resource/aliases.py

@@ -9,6 +9,13 @@
 from soundcloud.resource.user import User
 
 Like = Union[TrackLike, PlaylistLike]
+"""Generic like"""
+
 RepostItem = Union[TrackStreamRepostItem, PlaylistStreamRepostItem]
+"""Generic repost"""
+
 SearchItem = Union[User, Track, AlbumPlaylist]
+"""Generic search result"""
+
 StreamItem = Union[TrackStreamItem, PlaylistStreamItem, TrackStreamRepostItem, PlaylistStreamRepostItem]
+"""Generic feed item"""

soundcloud/resource/comment.py

@@ -5,12 +5,14 @@
 from soundcloud.resource.track import CommentTrack
 from soundcloud.resource.user import BasicUser
 
+
 @dataclass
 class CommentSelf(BaseData):
     urn: str
 
 @dataclass
 class BasicComment(BaseData):
+    """Comment without a specified track"""
     kind: str
     id: int
     body: str
@@ -20,7 +22,8 @@ class BasicComment(BaseData):
     user_id: int
     self: CommentSelf
     user: BasicUser
-    
+
 @dataclass
 class Comment(BasicComment):
-    track: CommentTrack
+    """Comment with a specified track"""
+    track: CommentTrack

soundcloud/resource/conversation.py

@@ -9,6 +9,7 @@
 
 @dataclass
 class Conversation(BaseData):
+    """DM conversation between two users"""
     id: str
     last_message: Message
     read: bool

soundcloud/resource/download.py

@@ -2,6 +2,8 @@
 
 from soundcloud.resource.base import BaseData
 
+
 @dataclass
 class OriginalDownload(BaseData):
-    redirectUri: str
+    """Contains a download link for a track"""
+    redirectUri: str

soundcloud/resource/history.py

@@ -1,10 +1,12 @@
 from dataclasses import dataclass
+
 from soundcloud.resource.base import BaseData
 from soundcloud.resource.track import BasicTrack
 
 
 @dataclass
 class HistoryItem(BaseData):
+    """Item in user's listen history"""
     played_at: int
     track: BasicTrack
-    track_id: int
+    track_id: int

soundcloud/resource/like.py

@@ -5,15 +5,18 @@
 from soundcloud.resource.playlist import AlbumPlaylistNoTracks
 from soundcloud.resource.track import BasicTrack
 
+
 @dataclass
 class BaseLike(BaseData):
     created_at: datetime.datetime
     kind: str     
 
 @dataclass
 class TrackLike(BaseLike):
+    """Like on a track"""
     track: BasicTrack
 
 @dataclass
 class PlaylistLike(BaseLike):
-    playlist: AlbumPlaylistNoTracks
+    """Like on a playlist"""
+    playlist: AlbumPlaylistNoTracks

soundcloud/resource/message.py

@@ -5,11 +5,13 @@
 from soundcloud.resource.base import BaseData
 from soundcloud.resource.user import BasicUser, MissingUser
 
+
 @dataclass
 class Message(BaseData):
+    """Single DM between two users"""
     content: str
     conversation_id: str
     sender: Union[BasicUser, MissingUser]
     sender_urn: str
     sender_type: str
-    sent_at: datetime.datetime
+    sent_at: datetime.datetime