🟢 OxideSpotify

OxideSpotify is a high-performance Spotify Web API client built on the OxideHTTP core. It combines the efficiency of Rust-backed networking with a strictly typed Pythonic interface, designed to handle Spotify's unique requirements like automatic retry logic and complex search filtering.

🔥 Why OxideSpotify?

The Spotify API requires precision in header management and often returns 504 Gateway Timeout or 204 No Content for player operations. OxideSpotify manages these edge cases automatically:

⚡ Oxide Core: Powered by pyreqwest (Rust) for minimal overhead in HTTP calls.
🔄 Intelligent Retries: Automatically re-processes requests on 504 errors to ensure stability in unstable network conditions.
🛡️ Rate Limit Resiliency: Integrates with Redis via OxideHTTP to stay within Spotify’s variable rate limits.
🏗️ Advanced Overloads: Provides precise type hinting for the /search endpoint—your IDE knows exactly which model is returned based on the search_type parameter.

📦 Installation

Configure your private registry in your uv environment, then run:

uv add oxidespotify

🛠 Quick Start

Playback Management

Spotify's player endpoints frequently return 204 No Content. OxideSpotify handles this transition gracefully.

import asyncio
from oxidespotify.api import SpotifyAPIClient

async def main():
    async with SpotifyAPIClient(
        redis_url="redis://localhost:6379"
    ) as spotify:
        # Get current playback state
        state = await spotify.get_playback_state(
            access_token="your_token",
            additional_types=['track']
        )

        if state:
            print(f"Now Playing: {state.item.name} by {state.item.artists[0].name}")

        # Add to queue (Handles 204 successfully)
        await spotify.add_item_to_playback_queue(
            access_token="your_token",
            uri="spotify:track:4cOdK2wGvS9II9Ja7pveUv",
            device_id="your_device_id"
        )

asyncio.run(main())

Type-Safe Searching

Thanks to Python @overload, your IDE provides full autocomplete for specific search results.

# The IDE knows 'results' is a SearchArtist model
results = await spotify.search_for_item(
    access_token="token",
    q="Daft Punk",
    search_type="artist"
)

for artist in results.artists.items:
    print(artist.name, artist.genres)

⚙️ Advanced: Configuration

Ensure your pyproject.toml is configured to find the Oxide ecosystem in your registry:

[[tool.uv.index]]
name = "OxideHTTP"
url = "https://git.miwory.dev/api/packages/OxideHTTP/pypi/simple"

Implementation Coverage

The client currently provides full Pydantic models and logic for:

Player: Playback state, queue management, and device control.
Search: Comprehensive filtering for albums, artists, tracks, playlists, etc.
Users: Profile retrieval and recently played history.
Tracks: Detailed track metadata retrieval.

3.0 KiB Raw Permalink Blame History Unescape Escape