# 🟢 OxideSpotify

**OxideSpotify** is a high-performance Spotify Web API client built on the [OxideHTTP](https://git.miwory.dev/OxideHTTP/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:

```bash
uv add oxidespotify

```

---

## 🛠 Quick Start

### Playback Management

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

```python
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.

```python
# 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:

```toml
[[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.