Первый релиз

README.md

@@ -0,0 +1,100 @@
+# 🟢 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.