Miwory
727af5899a
All checks were successful
Build And Publish Package / publish (push) Successful in 33s
101 lines
3.0 KiB
Markdown
101 lines
3.0 KiB
Markdown
# 🟢 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.
|