zeus-music-sdk 1.0.2

Zeus Music SDK for Python

Zeus Music SDK for Python

A fully-typed Python library for interacting with the Zeus Music Server API. This SDK makes it incredibly easy to authenticate users via OAuth 2.0 PKCE, manage tokens, and perform API calls to fetch tracks, manage user libraries, and more.

Features

• Fully typed Python client
• Support for synchronous and asynchronous HTTP requests
• Built-in OAuth 2.0 PKCE authentication flow helper
• Automatic token refreshing
• Clean, object-oriented design

Installation

pip install zeus-music-sdk

Getting Started

To use the SDK, you need a Developer API Key and a registered OAuth Client ID from the Zeus Music Developer Portal.

1. Initializing the Client

from zeus_music import ZeusClient

client = ZeusClient(
    client_id="YOUR_CLIENT_ID",
    api_key="YOUR_API_KEY",
    redirect_uri="http://localhost:3000/callback",
    scopes=["read_library", "read_profile", "write_library"],
    base_url="https://api.yourzeusdomain.com" # Default is http://localhost:8000
)

2. Authenticating a User (OAuth 2.0 PKCE)

The SDK handles the complicated PKCE flow for you.

# 1. Get the authorization URL and redirect your user to it
auth_url = client.get_authorization_url()
print(f"Please go here and authorize: {auth_url}")

# 2. After the user approves, they are redirected back to your `redirect_uri` with a `code`.
# Pass the full callback URL back into the client to complete the login:
callback_url = input("Paste the full redirect URL here: ")
client.handle_callback(callback_url)

if client.is_authenticated():
    print("Successfully authenticated!")

3. Using the API

Once authenticated, you can access the user's data using the .me namespace, or access public data globally.

Fetching Public Tracks

# Get a specific track by ID
track = client.tracks.get("TRACK_UUID")

# Get popular public tracks
popular_tracks = client.tracks.get_popular(limit=10)

User Library Management

# Get all saved tracks for the authenticated user
saved_tracks = client.me.library.get_saved_tracks()

# Save a new track to their library
client.me.library.save_track("TRACK_UUID")

# Remove a track from their library
client.me.library.remove_track("TRACK_UUID")

User Profile

# Get the authenticated user's profile
profile = client.me.profile.get()
print(f"Logged in as: {profile.get('email')}")

User Radio

# Generate a new radio station based on a track
station = client.me.radio.generate_station(seed_type="track", seed_id="TRACK_UUID")

# Get the next track in the radio queue
next_item = client.me.radio.get_next_queue_item(station["id"])

Advanced: Async Client

If you are building an async application (like a FastAPI backend or a Discord bot), you can use the AsyncZeusClient which has the exact same methods but uses await.

import asyncio
from zeus_music import AsyncZeusClient

async def main():
    client = AsyncZeusClient(
        client_id="YOUR_CLIENT_ID",
        api_key="YOUR_API_KEY",
        redirect_uri="http://localhost:3000/callback",
        scopes=["read_library"]
    )
    
    # ... authenticate ...
    
    tracks = await client.tracks.get_popular()
    print(tracks)

asyncio.run(main())

Exceptions

The SDK throws specific exceptions for error handling:

• ZeusAuthError: Raised when the OAuth flow fails, state mismatches, or tokens cannot be exchanged.
• ZeusAPIError: Raised when an API request fails (returns HTTP error status codes).

License

MIT License