checkleaked-spotify-api 1.0.0__py3-none-any.whl

checkleaked_spotify_api-1.0.0.dist-info/METADATA

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: checkleaked-spotify-api
+Version: 1.0.0
+Summary: Typed Python SDK for the CheckLeaked Spotify Data API and RapidAPI spotify81.
+Project-URL: Homepage, https://spotify-proxy.checkleaked.cc
+Project-URL: Documentation, https://spotify-proxy.checkleaked.cc/docs
+Project-URL: Repository, https://github.com/eduair94/checkleaked-spotify-api-python
+Project-URL: Issues, https://github.com/eduair94/checkleaked-spotify-api-python/issues
+Project-URL: OpenAPI, https://spotify-proxy.checkleaked.cc/openapi.json
+Author-email: Eduardo Airaudo <airaudoeduardo@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: charts,checkleaked,concerts,lyrics,music,rapidapi,sdk,spotify,spotify-api,spotify-data,spotify81
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Requires-Dist: requests>=2.25
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Requires-Dist: types-requests; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# checkleaked-spotify-api
+
+[![PyPI version](https://img.shields.io/pypi/v/checkleaked-spotify-api.svg)](https://pypi.org/project/checkleaked-spotify-api/)
+[![Python versions](https://img.shields.io/pypi/pyversions/checkleaked-spotify-api.svg)](https://pypi.org/project/checkleaked-spotify-api/)
+[![CI](https://github.com/eduair94/checkleaked-spotify-api-python/actions/workflows/ci.yml/badge.svg)](https://github.com/eduair94/checkleaked-spotify-api-python/actions/workflows/ci.yml)
+[![license: MIT](https://img.shields.io/pypi/l/checkleaked-spotify-api.svg)](./LICENSE)
+
+Typed Python SDK for the **Spotify Data API**, covering the same 110 methods
+and 25 namespaces as
+[`@checkleaked/spotify-api`](https://www.npmjs.com/package/@checkleaked/spotify-api).
+It works with both the
+[RapidAPI spotify81 API](https://rapidapi.com/airaudoeduardo/api/spotify81)
+and the direct
+[CheckLeaked proxy](https://spotify-proxy.checkleaked.cc/docs).
+
+This is a data API client. It does not require Spotify OAuth credentials.
+
+## Install
+
+```bash
+pip install checkleaked-spotify-api
+```
+
+## Quick start
+
+```python
+from spotify_api_sdk import SpotifyApiClient
+
+spotify = SpotifyApiClient(api_key="your-rapidapi-key")
+
+results = spotify.search.search(
+    "daft punk",
+    type="artists",
+    limit=5,
+)
+
+artist = spotify.artists.overview(
+    "spotify:artist:4tZwfgrHOc3mvqYlEYSvVi"
+)
+
+lyrics = spotify.tracks.lyrics(
+    "https://open.spotify.com/track/0DiWol3AO6WpXZgp0goxAV",
+    format="lrc",
+)
+```
+
+Methods return the API's unwrapped `data` payload. Use
+`client.request_raw(...)` when you need the complete success envelope.
+
+## Providers
+
+RapidAPI is the default and automatically adds
+`x-rapidapi-host: spotify81.p.rapidapi.com`:
+
+```python
+spotify = SpotifyApiClient(
+    api_key="your-rapidapi-key",
+    provider="rapidapi",
+)
+```
+
+The direct proxy exposes the same methods and paths. Use a key issued by the
+direct portal:
+
+```python
+spotify = SpotifyApiClient(
+    api_key="your-direct-proxy-key",
+    provider="proxy",
+)
+```
+
+The API key may be omitted when `SPOTIFY_API_KEY` or `RAPIDAPI_KEY` is set.
+
+## Pythonic and npm-compatible names
+
+Python methods use `snake_case`, while npm-style `camelCase` aliases are also
+available:
+
+```python
+spotify.artists.top_tracks(id, market="US")
+spotify.artists.topTracks(id, market="US")  # exact npm-style alias
+```
+
+Every method supports per-call `request_timeout`, `request_retries`,
+`request_headers`, and an additional `extra_query` mapping. POST methods also
+accept a free-form `body` mapping.
+
+## IDs, URIs, and URLs
+
+Spotify IDs may be supplied as bare IDs, Spotify URIs, or open.spotify.com
+URLs. Multi-ID methods accept comma-separated strings or Python sequences.
+
+```python
+from spotify_api_sdk import normalize_id, normalize_ids
+
+normalize_id("spotify:track:0DiWol3AO6WpXZgp0goxAV")
+normalize_ids([
+    "spotify:artist:4tZwfgrHOc3mvqYlEYSvVi",
+    "https://open.spotify.com/artist/06HL4z0CvFAxyc27GXpf02",
+])
+```
+
+## Pagination
+
+```python
+from spotify_api_sdk import collect
+
+items = collect(
+    lambda **page: spotify.artists.albums(id=artist_id, **page),
+    get_items=lambda response: (
+        response.get("data", {})
+        .get("artist", {})
+        .get("discography", {})
+        .get("albums", {})
+        .get("items", [])
+    ),
+    limit=50,
+    max_items=500,
+)
+```
+
+## Errors
+
+```python
+from spotify_api_sdk import (
+    AuthError,
+    HttpError,
+    RateLimitError,
+    SpotifyApiError,
+    TimeoutError,
+)
+
+try:
+    spotify.search.search("daft punk")
+except RateLimitError as error:
+    print(error.retry_after_ms)
+except AuthError:
+    print("Invalid or unsubscribed API key")
+except SpotifyApiError as error:
+    print(error.status, error.code, error.url)
+```
+
+## Configuration
+
+```python
+spotify = SpotifyApiClient(
+    api_key="...",
+    provider="rapidapi",   # rapidapi (default) | proxy
+    timeout=30,
+    retries=2,
+    retry_delay=0.5,
+    headers={"x-my-header": "value"},
+    debug=True,
+    on_request=lambda info: print("request", info["url"]),
+    on_response=lambda info: print("response", info["status"]),
+    on_retry=lambda info: print("retry", info["attempt"]),
+)
+```
+
+The client is also a context manager:
+
+```python
+with SpotifyApiClient(api_key="...") as spotify:
+    markets = spotify.markets.get()
+```
+
+See [API_REFERENCE.md](./API_REFERENCE.md) for every namespace and method.

checkleaked_spotify_api-1.0.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+spotify_api_sdk/__init__.py,sha256=xfaEZRCd9Swchh3zN6YoJlxjECHaGnjfES9u261qnJs,991
+spotify_api_sdk/_resource.py,sha256=XaoLgNeavhdIaZPSHKCnp9A48D8MU8C6u24HwbAOijU,2603
+spotify_api_sdk/client.py,sha256=lb6coFMXCsHiPL2Mj_P9EZVq4N_ygn1DmdH5I10ZqZg,2054
+spotify_api_sdk/config.py,sha256=PCK4WSnJqYE4QmTIa-SBgSA_zyNqU9-cem9hT-KvOu8,3837
+spotify_api_sdk/errors.py,sha256=Kk7hlBl1uRcelngpXusYzrmBqnU0jivqzfAIvDUWcFE,1513
+spotify_api_sdk/http.py,sha256=U_kTCZs189OBapCsg-vuXitfnfVnLk3kR1ZiCtDRXro,13292
+spotify_api_sdk/ids.py,sha256=eDltbjCWTx1ZhHfj6AeQZW0r0aqi1FfBV6IV5JeH2Kc,1059
+spotify_api_sdk/pagination.py,sha256=BfBTxtf7RqzBTc7MV6uR9Jaun6EEuSPAgJid7tz81Oo,1873
+spotify_api_sdk/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+spotify_api_sdk/resources.py,sha256=WrNBwXVXwh1EWt_wom3DscvFsGlHmruGoIXGn_XQ2ME,72838
+spotify_api_sdk/types.py,sha256=M3aTr2JPjL3tu6r9-uCCWdvXhAAg3LDzkSvT7uZ0xPY,818
+checkleaked_spotify_api-1.0.0.dist-info/METADATA,sha256=ei6WqaQCjAniqbBmcszPnEmGxAILCLt8pwOaSvAjoVE,5942
+checkleaked_spotify_api-1.0.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+checkleaked_spotify_api-1.0.0.dist-info/licenses/LICENSE,sha256=23E_lxAHxPs2-W7_j2ZgS_hLCXUgsgR0Snj0nCrns74,1073
+checkleaked_spotify_api-1.0.0.dist-info/RECORD,,

checkleaked_spotify_api-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

checkleaked_spotify_api-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Eduardo Airaudo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

spotify_api_sdk/__init__.py

@@ -0,0 +1,53 @@
+"""Python SDK for the CheckLeaked Spotify Data API."""
+
+from .client import SpotifyApiClient, SpotifyClient, create_client
+from .errors import (
+    AuthError,
+    HttpError,
+    NetworkError,
+    RateLimitError,
+    SpotifyApiError,
+    TimeoutError,
+    ValidationError,
+)
+from .ids import normalize_id, normalize_ids
+from .pagination import collect, paginate
+from .types import (
+    ErrorEnvelope,
+    Headers,
+    IdInput,
+    IdList,
+    JsonValue,
+    QueryParams,
+    QueryValue,
+    SuccessEnvelope,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "AuthError",
+    "ErrorEnvelope",
+    "Headers",
+    "HttpError",
+    "IdInput",
+    "IdList",
+    "JsonValue",
+    "NetworkError",
+    "QueryParams",
+    "QueryValue",
+    "RateLimitError",
+    "SpotifyApiClient",
+    "SpotifyApiError",
+    "SpotifyClient",
+    "SuccessEnvelope",
+    "TimeoutError",
+    "ValidationError",
+    "__version__",
+    "collect",
+    "create_client",
+    "normalize_id",
+    "normalize_ids",
+    "paginate",
+]
+

spotify_api_sdk/_resource.py

@@ -0,0 +1,81 @@
+"""Resource primitives used by generated namespace classes."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, Mapping, Optional, Sequence, Tuple
+from urllib.parse import quote
+
+from .errors import ValidationError
+from .ids import normalize_id
+from .types import Headers, QueryValue
+
+
+@dataclass(frozen=True)
+class Endpoint:
+    key: str
+    method: str
+    path: str
+    path_fields: Tuple[Tuple[str, str], ...] = ()
+    query_fields: Tuple[Tuple[str, str], ...] = ()
+    body_fields: Tuple[Tuple[str, str], ...] = ()
+
+
+class Resource:
+    """Base class for generated resource namespaces."""
+
+    def __init__(self, client: Any) -> None:
+        self._client = client
+
+    def _invoke(self, endpoint: Endpoint, values: Mapping[str, Any]) -> Any:
+        path = endpoint.path
+        for python_name, wire_name in endpoint.path_fields:
+            value = values.get(python_name)
+            if value is None:
+                raise ValidationError(
+                    f"{endpoint.key}: {python_name} is required",
+                    code="VALIDATION",
+                )
+            path = path.replace(
+                "{" + wire_name + "}",
+                quote(normalize_id(value), safe=""),
+            )
+
+        query_value = (
+            values.get("extra_query")
+            if "extra_query" in values
+            else values.get("query")
+        )
+        query: Dict[str, QueryValue] = dict(query_value or {})
+        for python_name, wire_name in endpoint.query_fields:
+            value = values.get(python_name)
+            if value is not None:
+                query[wire_name] = value
+
+        body = values.get("body")
+        explicit_body = {
+            wire_name: values[python_name]
+            for python_name, wire_name in endpoint.body_fields
+            if values.get(python_name) is not None
+        }
+        if explicit_body:
+            if body is None:
+                body = explicit_body
+            elif isinstance(body, Mapping):
+                body = {**body, **explicit_body}
+            else:
+                raise ValidationError(
+                    f"{endpoint.key}: body must be a mapping when body fields "
+                    "are supplied",
+                    code="VALIDATION",
+                )
+
+        return self._client.request(
+            endpoint.method,
+            path,
+            query=query or None,
+            body=body,
+            timeout=values.get("request_timeout"),
+            retries=values.get("request_retries"),
+            headers=values.get("request_headers"),
+        )

spotify_api_sdk/client.py

@@ -0,0 +1,71 @@
+"""High-level Spotify Data API client."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional
+
+from .config import Debug, Hook, ResolvedConfig, resolve_config
+from .http import SpotifyHttpClient
+from .resources import RESOURCE_CLASSES, ClientResources
+
+
+class SpotifyApiClient(ClientResources, SpotifyHttpClient):
+    """Client exposing all 25 typed Spotify Data API namespaces."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        provider: str = "rapidapi",
+        transport: Optional[str] = None,
+        base_url: Optional[str] = None,
+        host: Optional[str] = None,
+        timeout: float = 30.0,
+        retries: int = 2,
+        retry_delay: float = 0.5,
+        headers: Optional[Mapping[str, str]] = None,
+        user_agent: Optional[str] = None,
+        session: Any = None,
+        debug: Debug = False,
+        on_request: Optional[Hook] = None,
+        on_response: Optional[Hook] = None,
+        on_retry: Optional[Hook] = None,
+    ) -> None:
+        config: ResolvedConfig = resolve_config(
+            api_key,
+            provider=provider,
+            transport=transport,
+            base_url=base_url,
+            host=host,
+            timeout=timeout,
+            retries=retries,
+            retry_delay=retry_delay,
+            headers=headers,
+            user_agent=user_agent,
+            session=session,
+            debug=debug,
+            on_request=on_request,
+            on_response=on_response,
+            on_retry=on_retry,
+        )
+        super().__init__(config)
+        for name, resource_class in RESOURCE_CLASSES.items():
+            setattr(self, name, resource_class(self))
+
+    def __enter__(self) -> "SpotifyApiClient":
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+
+SpotifyClient = SpotifyApiClient
+
+
+def create_client(
+    api_key: Optional[str] = None,
+    **config: Any,
+) -> SpotifyApiClient:
+    """Create a :class:`SpotifyApiClient`."""
+
+    return SpotifyApiClient(api_key, **config)

spotify_api_sdk/config.py

@@ -0,0 +1,134 @@
+"""Client configuration and provider presets."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, Mapping, Optional, Union
+
+from .errors import ValidationError
+
+RAPIDAPI_BASE_URL = "https://spotify81.p.rapidapi.com"
+RAPIDAPI_HOST = "spotify81.p.rapidapi.com"
+PROXY_BASE_URL = "https://spotify-proxy.checkleaked.cc/spotify-data"
+DEFAULT_USER_AGENT = (
+    "checkleaked-spotify-api-python/1.0.0 "
+    "(+https://pypi.org/project/checkleaked-spotify-api/)"
+)
+
+Hook = Callable[[Mapping[str, Any]], None]
+Debug = Union[bool, Callable[[str, Optional[Any]], None]]
+
+
+@dataclass(frozen=True)
+class Channel:
+    """A resolved base URL and its optional RapidAPI host header."""
+
+    base_url: str
+    host: Optional[str] = None
+
+
+@dataclass
+class ResolvedConfig:
+    api_key: str
+    provider: str
+    channel: Channel
+    timeout_s: float
+    retries: int
+    retry_delay_s: float
+    headers: Dict[str, str]
+    user_agent: str
+    session: Any
+    debug: Optional[Callable[[str, Optional[Any]], None]]
+    on_request: Optional[Hook]
+    on_response: Optional[Hook]
+    on_retry: Optional[Hook]
+
+
+def _debug_logger(value: Debug) -> Optional[Callable[[str, Optional[Any]], None]]:
+    if value is True:
+        def log(message: str, detail: Optional[Any] = None) -> None:
+            suffix = "" if detail is None else f" {detail!r}"
+            print(f"[spotify-api] {message}{suffix}")
+
+        return log
+    if callable(value):
+        return value
+    return None
+
+
+def resolve_config(
+    api_key: Optional[str] = None,
+    *,
+    provider: str = "rapidapi",
+    transport: Optional[str] = None,
+    base_url: Optional[str] = None,
+    host: Optional[str] = None,
+    timeout: float = 30.0,
+    retries: int = 2,
+    retry_delay: float = 0.5,
+    headers: Optional[Mapping[str, str]] = None,
+    user_agent: Optional[str] = None,
+    session: Any = None,
+    debug: Debug = False,
+    on_request: Optional[Hook] = None,
+    on_response: Optional[Hook] = None,
+    on_retry: Optional[Hook] = None,
+) -> ResolvedConfig:
+    """Resolve and validate a client configuration."""
+
+    if transport is not None:
+        provider = transport
+    if provider not in ("rapidapi", "proxy"):
+        raise ValidationError(
+            f"Invalid provider: {provider!r}. Expected 'rapidapi' or 'proxy'.",
+            code="CONFIG",
+        )
+
+    resolved_key = (
+        api_key
+        or os.environ.get("SPOTIFY_API_KEY")
+        or os.environ.get("RAPIDAPI_KEY")
+    )
+    if not isinstance(resolved_key, str) or not resolved_key.strip():
+        raise ValidationError(
+            "api_key is required (or set SPOTIFY_API_KEY / RAPIDAPI_KEY)",
+            code="CONFIG",
+        )
+    if timeout <= 0:
+        raise ValidationError("timeout must be greater than 0", code="CONFIG")
+    if retry_delay < 0:
+        raise ValidationError("retry_delay must be at least 0", code="CONFIG")
+
+    if provider == "rapidapi":
+        channel = Channel(
+            base_url=(base_url or RAPIDAPI_BASE_URL).rstrip("/"),
+            host=RAPIDAPI_HOST if host is None else host,
+        )
+    else:
+        channel = Channel(
+            base_url=(base_url or PROXY_BASE_URL).rstrip("/"),
+            host=host,
+        )
+
+    if session is None:
+        import requests
+
+        session = requests.Session()
+
+    return ResolvedConfig(
+        api_key=resolved_key.strip(),
+        provider=provider,
+        channel=channel,
+        timeout_s=float(timeout),
+        retries=max(0, int(retries)),
+        retry_delay_s=float(retry_delay),
+        headers=dict(headers or {}),
+        user_agent=user_agent or DEFAULT_USER_AGENT,
+        session=session,
+        debug=_debug_logger(debug),
+        on_request=on_request,
+        on_response=on_response,
+        on_retry=on_retry,
+    )
+

spotify_api_sdk/errors.py

@@ -0,0 +1,68 @@
+"""Structured errors raised by the Spotify Data API SDK."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class SpotifyApiError(Exception):
+    """Base error for all SDK failures."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: Optional[int] = None,
+        code: Optional[str] = None,
+        body: Any = None,
+        url: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.body = body
+        self.url = url
+
+
+class HttpError(SpotifyApiError):
+    """A non-successful HTTP response."""
+
+
+class AuthError(HttpError):
+    """Authentication failed."""
+
+
+class RateLimitError(HttpError):
+    """The API returned HTTP 429."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int = 429,
+        code: Optional[str] = None,
+        body: Any = None,
+        url: Optional[str] = None,
+        retry_after_ms: Optional[int] = None,
+    ) -> None:
+        super().__init__(
+            message,
+            status=status,
+            code=code,
+            body=body,
+            url=url,
+        )
+        self.retry_after_ms = retry_after_ms
+
+
+class NetworkError(SpotifyApiError):
+    """A transport-level network failure."""
+
+
+class TimeoutError(NetworkError):  # noqa: A001 - intentional public API
+    """The request timed out."""
+
+
+class ValidationError(SpotifyApiError):
+    """Invalid SDK configuration or method arguments."""
+