audd 1.4.0__py3-none-any.whl

audd/__init__.py

@@ -0,0 +1,46 @@
+"""Official Python SDK for the AudD music recognition API."""
+from audd._version import __version__
+from audd.client import AsyncAudD, AudD
+from audd.errors import (
+    AudDAPIError,
+    AudDAuthenticationError,
+    AudDBlockedError,
+    AudDConnectionError,
+    AudDCustomCatalogAccessError,
+    AudDError,
+    AudDInvalidAudioError,
+    AudDInvalidRequestError,
+    AudDNeedsUpdateError,
+    AudDNotReleasedError,
+    AudDQuotaError,
+    AudDRateLimitError,
+    AudDSerializationError,
+    AudDServerError,
+    AudDStreamLimitError,
+    AudDSubscriptionError,
+)
+from audd.longpoll import AsyncLongpollConsumer, LongpollConsumer
+
+__all__ = [
+    "AsyncAudD",
+    "AsyncLongpollConsumer",
+    "AudD",
+    "AudDAPIError",
+    "AudDAuthenticationError",
+    "AudDBlockedError",
+    "AudDConnectionError",
+    "AudDCustomCatalogAccessError",
+    "AudDError",
+    "AudDInvalidAudioError",
+    "AudDInvalidRequestError",
+    "AudDNeedsUpdateError",
+    "AudDNotReleasedError",
+    "AudDQuotaError",
+    "AudDRateLimitError",
+    "AudDSerializationError",
+    "AudDServerError",
+    "AudDStreamLimitError",
+    "AudDSubscriptionError",
+    "LongpollConsumer",
+    "__version__",
+]

audd/_callbacks.py

@@ -0,0 +1,69 @@
+"""Pure helpers used by streams.* and callbacks. No HTTP, no SDK state."""
+from __future__ import annotations
+
+import hashlib
+from typing import Any
+from urllib.parse import parse_qs, urlencode, urlparse, urlunparse
+
+from audd.errors import AudDInvalidRequestError
+from audd.models import StreamCallbackPayload
+
+
+class DuplicateReturnParameterError(AudDInvalidRequestError):
+    """Raised when streams.set_callback_url is given both a URL containing
+    ?return=... AND a return_metadata argument — conflicting intent."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            error_code=0,
+            message=(
+                "URL already contains a `return` query parameter; pass return_metadata=None "
+                "or remove the parameter from the URL — refusing to silently overwrite."
+            ),
+            http_status=0,
+            request_id=None,
+        )
+
+
+def derive_longpoll_category(api_token: str, radio_id: int) -> str:
+    """Compute the 9-char longpoll category locally from token + radio_id.
+
+    Formula (per docs.audd.io/streams.md): hex-MD5 of (hex-MD5 of api_token,
+    concatenated with the radio_id rendered as a decimal string), truncated
+    to the first 9 hex chars.
+    """
+    inner = hashlib.md5(api_token.encode("utf-8")).hexdigest()
+    full = hashlib.md5((inner + str(radio_id)).encode("utf-8")).hexdigest()
+    return full[:9]
+
+
+def parse_callback(body: dict[str, Any]) -> StreamCallbackPayload:
+    """Parse a callback POST body into a typed payload."""
+    return StreamCallbackPayload.parse(body)
+
+
+def add_return_to_url(
+    url: str,
+    return_metadata: str | list[str] | None,
+) -> str:
+    """Append `?return=<metadata>` (or merge as `&return=`) to the callback URL.
+
+    If `return_metadata` is None, return the URL unchanged.
+    If the URL already has a `return` query parameter, raise to avoid silent overwrite.
+    """
+    if return_metadata is None:
+        return url
+
+    metadata = (
+        ",".join(return_metadata)
+        if isinstance(return_metadata, list)
+        else return_metadata
+    )
+
+    parsed = urlparse(url)
+    qs = parse_qs(parsed.query, keep_blank_values=True)
+    if "return" in qs:
+        raise DuplicateReturnParameterError()
+    qs["return"] = [metadata]
+    new_query = urlencode([(k, v) for k, vs in qs.items() for v in vs])
+    return urlunparse(parsed._replace(query=new_query))

audd/_http.py

@@ -0,0 +1,182 @@
+"""HTTP transport. Sync (HTTPClient) and async (AsyncHTTPClient) wrappers around httpx."""
+from __future__ import annotations
+
+import threading
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from audd._user_agent import user_agent
+
+DEFAULT_TIMEOUTS = httpx.Timeout(connect=30.0, read=60.0, write=60.0, pool=30.0)
+ENTERPRISE_TIMEOUTS = httpx.Timeout(connect=30.0, read=3600.0, write=3600.0, pool=30.0)
+
+
+@dataclass(frozen=True)
+class HTTPResponse:
+    json_body: Any  # parsed JSON body, or None on parse failure
+    http_status: int
+    request_id: str | None  # x-request-id header, if present
+    raw_text: str  # original response body text (for AudDSerializationError diagnostics)
+
+
+def _request_id(headers: Mapping[str, str]) -> str | None:
+    return headers.get("x-request-id") or headers.get("X-Request-ID")
+
+
+class HTTPClient:
+    def __init__(
+        self,
+        api_token: str,
+        *,
+        timeouts: httpx.Timeout = DEFAULT_TIMEOUTS,
+        httpx_client: httpx.Client | None = None,
+    ) -> None:
+        self._token_lock = threading.Lock()
+        self._api_token = api_token
+        self._owned = httpx_client is None
+        self._client = httpx_client or httpx.Client(
+            timeout=timeouts,
+            headers={"User-Agent": user_agent()},
+        )
+        if not self._owned and "User-Agent" not in self._client.headers:
+            self._client.headers["User-Agent"] = user_agent()
+
+    def set_api_token(self, new_token: str) -> None:
+        """Atomically swap the token used for subsequent requests."""
+        with self._token_lock:
+            self._api_token = new_token
+
+    def _current_token(self) -> str:
+        with self._token_lock:
+            return self._api_token
+
+    def post_form(
+        self,
+        url: str,
+        data: dict[str, Any],
+        *,
+        timeout: httpx.Timeout | None = None,
+        files: Mapping[str, Any] | None = None,
+    ) -> HTTPResponse:
+        """POST multipart/form-data with api_token always included."""
+        full_data = dict(data)
+        full_data["api_token"] = self._current_token()
+        kwargs: dict[str, Any] = {}
+        if timeout is not None:
+            kwargs["timeout"] = timeout
+        if files is not None:
+            kwargs["files"] = files
+        r = self._client.post(url, data=full_data, **kwargs)
+        return self._wrap(r)
+
+    def get(
+        self,
+        url: str,
+        params: dict[str, Any],
+        *,
+        timeout: httpx.Timeout | None = None,
+    ) -> HTTPResponse:
+        full = dict(params)
+        full.setdefault("api_token", self._current_token())
+        kwargs: dict[str, Any] = {}
+        if timeout is not None:
+            kwargs["timeout"] = timeout
+        r = self._client.get(url, params=full, **kwargs)
+        return self._wrap(r)
+
+    def _wrap(self, r: httpx.Response) -> HTTPResponse:
+        try:
+            body: Any = r.json()
+        except Exception:
+            body = None
+        return HTTPResponse(
+            json_body=body,
+            http_status=r.status_code,
+            request_id=_request_id(r.headers),
+            raw_text=r.text,
+        )
+
+    def close(self) -> None:
+        if self._owned:
+            self._client.close()
+
+
+class AsyncHTTPClient:
+    def __init__(
+        self,
+        api_token: str,
+        *,
+        timeouts: httpx.Timeout = DEFAULT_TIMEOUTS,
+        httpx_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._token_lock = threading.Lock()
+        self._api_token = api_token
+        self._owned = httpx_client is None
+        self._client = httpx_client or httpx.AsyncClient(
+            timeout=timeouts,
+            headers={"User-Agent": user_agent()},
+        )
+        if not self._owned and "User-Agent" not in self._client.headers:
+            self._client.headers["User-Agent"] = user_agent()
+
+    def set_api_token(self, new_token: str) -> None:
+        """Atomically swap the token used for subsequent requests."""
+        with self._token_lock:
+            self._api_token = new_token
+
+    def _current_token(self) -> str:
+        with self._token_lock:
+            return self._api_token
+
+    async def post_form(
+        self,
+        url: str,
+        data: dict[str, Any],
+        *,
+        timeout: httpx.Timeout | None = None,
+        files: Mapping[str, Any] | None = None,
+    ) -> HTTPResponse:
+        full_data = dict(data)
+        full_data["api_token"] = self._current_token()
+        kwargs: dict[str, Any] = {}
+        if timeout is not None:
+            kwargs["timeout"] = timeout
+        if files is not None:
+            kwargs["files"] = files
+        r = await self._client.post(url, data=full_data, **kwargs)
+        return _wrap_async(r)
+
+    async def get(
+        self,
+        url: str,
+        params: dict[str, Any],
+        *,
+        timeout: httpx.Timeout | None = None,
+    ) -> HTTPResponse:
+        full = dict(params)
+        full.setdefault("api_token", self._current_token())
+        kwargs: dict[str, Any] = {}
+        if timeout is not None:
+            kwargs["timeout"] = timeout
+        r = await self._client.get(url, params=full, **kwargs)
+        return _wrap_async(r)
+
+    async def aclose(self) -> None:
+        if self._owned:
+            await self._client.aclose()
+
+
+def _wrap_async(r: httpx.Response) -> HTTPResponse:
+    try:
+        body: Any = r.json()
+    except Exception:
+        body = None
+    return HTTPResponse(
+        json_body=body,
+        http_status=r.status_code,
+        request_id=_request_id(r.headers),
+        raw_text=r.text,
+    )

audd/_retry.py

@@ -0,0 +1,150 @@
+"""Cost-aware retry policy."""
+from __future__ import annotations
+
+import asyncio
+import enum
+import random
+import time
+from collections.abc import Awaitable
+from dataclasses import dataclass
+from typing import Callable, TypeVar
+
+import httpx
+
+from audd._http import HTTPResponse
+
+
+class RetryClass(enum.Enum):
+    """Determines which conditions are retryable for a given endpoint.
+
+    READ        — idempotent reads (streams.list, streams.get_callback_url):
+                  retry on 408/429/5xx + any connection error.
+    RECOGNITION — recognize, recognize_enterprise, advanced.find_lyrics:
+                  retry on pre-upload connection failures + 5xx.
+                  DO NOT retry on read-timeout-after-upload (cost protection).
+    MUTATING    — streams.set_callback_url, streams.add, streams.delete, etc.,
+                  custom_catalog.add: retry only on pre-upload connection failures.
+                  DO NOT retry 5xx (the side effect may have happened).
+    """
+
+    READ = "read"
+    RECOGNITION = "recognition"
+    MUTATING = "mutating"
+
+
+@dataclass(frozen=True)
+class RetryPolicy:
+    retry_class: RetryClass
+    max_attempts: int = 3
+    backoff_factor: float = 0.5
+    backoff_max: float = 30.0
+
+
+T = TypeVar("T")
+
+
+def _sync_sleep(seconds: float) -> None:
+    time.sleep(seconds)
+
+
+async def _async_sleep(seconds: float) -> None:
+    await asyncio.sleep(seconds)
+
+
+def _backoff_delay(attempt: int, policy: RetryPolicy) -> float:
+    base = min(policy.backoff_factor * (2**attempt), policy.backoff_max)
+    jitter = 0.5 + random.random()
+    return float(base * jitter)
+
+
+def _is_pre_upload_connection_error(exc: BaseException) -> bool:
+    """Errors raised before the request body finished uploading (safe to retry)."""
+    return isinstance(exc, (httpx.ConnectError, httpx.ConnectTimeout, httpx.WriteError))
+
+
+_HTTP_REQUEST_TIMEOUT = 408
+_HTTP_TOO_MANY_REQUESTS = 429
+_HTTP_SERVER_ERROR_FLOOR = 500
+
+
+def _should_retry_response(resp: HTTPResponse, retry_class: RetryClass) -> bool:
+    s = resp.http_status
+    if retry_class == RetryClass.READ:
+        retryable_specific = (_HTTP_REQUEST_TIMEOUT, _HTTP_TOO_MANY_REQUESTS)
+        return s in retryable_specific or s >= _HTTP_SERVER_ERROR_FLOOR
+    if retry_class == RetryClass.RECOGNITION:
+        return s >= _HTTP_SERVER_ERROR_FLOOR
+    if retry_class == RetryClass.MUTATING:
+        return False
+    raise AssertionError(f"unhandled RetryClass {retry_class!r}")
+
+
+def _should_retry_exception(exc: BaseException, retry_class: RetryClass) -> bool:
+    if retry_class == RetryClass.READ:
+        return isinstance(exc, httpx.RequestError)
+    if retry_class == RetryClass.RECOGNITION:
+        return _is_pre_upload_connection_error(exc)
+    if retry_class == RetryClass.MUTATING:
+        return _is_pre_upload_connection_error(exc)
+    raise AssertionError(f"unhandled RetryClass {retry_class!r}")
+
+
+def retry_sync(fn: Callable[[], HTTPResponse], policy: RetryPolicy) -> HTTPResponse:
+    last_exc: BaseException | None = None
+    last_resp: HTTPResponse | None = None
+    for attempt in range(policy.max_attempts):
+        try:
+            resp = fn()
+        except BaseException as exc:
+            last_exc = exc
+            last_resp = None
+            if not _should_retry_exception(exc, policy.retry_class):
+                raise
+            if attempt + 1 >= policy.max_attempts:
+                raise
+            _sync_sleep(_backoff_delay(attempt, policy))
+            continue
+
+        if not _should_retry_response(resp, policy.retry_class):
+            return resp
+        last_resp = resp
+        last_exc = None
+        if attempt + 1 >= policy.max_attempts:
+            return resp
+        _sync_sleep(_backoff_delay(attempt, policy))
+    if last_resp is not None:
+        return last_resp
+    assert last_exc is not None
+    raise last_exc
+
+
+async def retry_async(
+    fn: Callable[[], Awaitable[HTTPResponse]],
+    policy: RetryPolicy,
+) -> HTTPResponse:
+    last_exc: BaseException | None = None
+    last_resp: HTTPResponse | None = None
+    for attempt in range(policy.max_attempts):
+        try:
+            resp = await fn()
+        except BaseException as exc:
+            last_exc = exc
+            last_resp = None
+            if not _should_retry_exception(exc, policy.retry_class):
+                raise
+            if attempt + 1 >= policy.max_attempts:
+                raise
+            await _async_sleep(_backoff_delay(attempt, policy))
+            continue
+
+        if not _should_retry_response(resp, policy.retry_class):
+            return resp
+        last_resp = resp
+        last_exc = None
+        if attempt + 1 >= policy.max_attempts:
+            return resp
+        await _async_sleep(_backoff_delay(attempt, policy))
+    if last_resp is not None:
+        return last_resp
+    assert last_exc is not None
+    raise last_exc

audd/_source.py

@@ -0,0 +1,99 @@
+"""Auto-detect what kind of audio source the caller passed and convert to the
+right multipart fields.
+
+We return a *re-opener* — a 0-arg callable that yields fresh form-data on
+each call. The client invokes it inside the retry-wrapped request closure.
+
+httpx specifically auto-seeks file handles between `post()` calls, so a
+naive once-open implementation would not actually break in our case. The
+re-opener is defensive: (a) it doesn't depend on any specific HTTP-library
+behavior, (b) it raises cleanly on unseekable streams when a retry is
+attempted (rather than silently sending an empty body), and (c) sibling
+SDKs in other languages must follow this pattern because their HTTP
+libraries may not auto-seek. The shape stays consistent across the family.
+"""
+from __future__ import annotations
+
+from io import IOBase
+from pathlib import Path
+from typing import Any, Callable, Optional, Union
+
+# Source: URL string, filesystem path (str or Path), file-like, or raw bytes.
+Source = Union[str, Path, IOBase, bytes, bytearray]
+
+# Output: (data, files_or_None). `files` may be None for URL-source.
+PreparedRequest = tuple[dict[str, Any], Optional[dict[str, Any]]]
+
+
+def _looks_like_url(s: str) -> bool:
+    return s.startswith("http://") or s.startswith("https://")
+
+
+def prepare_source(source: Any) -> Callable[[], PreparedRequest]:
+    """Return a re-opener: a 0-arg callable that yields fresh (data, files) on each call.
+
+    URLs go in `data["url"]`; paths/file-likes/bytes go in `files["file"]`.
+
+    For file paths and bytes, each call returns a fresh handle/buffer so that
+    retried requests don't read from an exhausted source. For file-like
+    objects (IOBase), each call seeks back to the original position before
+    returning, if the object is seekable; if not, retrying that source
+    raises immediately on attempt 2 (we'd send zero bytes otherwise).
+    """
+    # URL source: cheap, no body re-creation needed.
+    if isinstance(source, str) and _looks_like_url(source):
+        url = source
+        def _do_url() -> PreparedRequest:
+            return ({"url": url}, None)
+        return _do_url
+
+    # Filesystem path (str or Path): open a fresh handle each attempt.
+    if isinstance(source, (str, Path)):
+        path = Path(source)
+        if isinstance(source, str) and not path.exists():
+            # User probably mistyped a URL — give them a hint instead of FileNotFoundError.
+            raise TypeError(
+                f"{source!r} is not an HTTP URL (must start with http:// or https://) "
+                f"and is not an existing file path. Pass a URL, a Path, a file-like, or bytes."
+            )
+
+        def _do_path() -> PreparedRequest:
+            return ({}, {"file": (path.name, path.open("rb"), "application/octet-stream")})
+        return _do_path
+
+    # Raw bytes: each attempt sends a copy.
+    if isinstance(source, (bytes, bytearray)):
+        buf = bytes(source)
+        def _do_bytes() -> PreparedRequest:
+            return ({}, {"file": ("upload.bin", buf, "application/octet-stream")})
+        return _do_bytes
+
+    # File-like object: seek back to the original position on each attempt.
+    if hasattr(source, "read"):
+        fl: Any = source
+        name = getattr(fl, "name", "upload.bin")
+        try:
+            start = fl.tell()
+            seekable = True
+        except (AttributeError, OSError):
+            start = None
+            seekable = False
+        first_call = [True]
+
+        def _do_filelike() -> PreparedRequest:
+            if first_call[0]:
+                first_call[0] = False
+            else:
+                if not seekable or start is None:
+                    raise RuntimeError(
+                        "Cannot retry an unseekable file-like source. Pass bytes "
+                        "(buffer the content yourself) or use a Path / URL."
+                    )
+                fl.seek(start)
+            return ({}, {"file": (name, fl, "application/octet-stream")})
+        return _do_filelike
+
+    raise TypeError(
+        f"Unsupported source type {type(source).__name__}; "
+        "pass a URL string, a path (str or Path), a file-like object, or bytes."
+    )

audd/_user_agent.py

@@ -0,0 +1,13 @@
+"""Build the User-Agent string sent on every request."""
+from __future__ import annotations
+
+import platform
+import sys
+
+from audd._version import __version__
+
+
+def user_agent() -> str:
+    """Return e.g. 'audd-python/0.1.0 python/3.12.1 (linux)'."""
+    py = ".".join(map(str, sys.version_info[:3]))
+    return f"audd-python/{__version__} python/{py} ({platform.system().lower()})"

audd/_version.py

@@ -0,0 +1,3 @@
+"""Single source of truth for the package version. Hatch reads this."""
+
+__version__ = "1.4.0"

audd/advanced.py

@@ -0,0 +1,86 @@
+"""Advanced namespace — lyrics search + raw escape hatch.
+
+Reach this only via audd.advanced.* — deliberately not on the main client.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from audd._http import AsyncHTTPClient, HTTPClient
+from audd._retry import RetryPolicy, retry_async, retry_sync
+from audd.errors import (
+    AudDConnectionError,
+    AudDSerializationError,
+    raise_from_error_response,
+)
+from audd.models import LyricsResult
+
+API_BASE = "https://api.audd.io"
+
+
+class Advanced:
+    def __init__(self, http: HTTPClient, read: RetryPolicy) -> None:
+        self._http = http
+        self._read = read
+
+    def find_lyrics(self, query: str) -> list[LyricsResult]:
+        body = self.raw_request("findLyrics", {"q": query})
+        if body.get("status") == "error":
+            raise_from_error_response(body, http_status=200, request_id=None)
+        return [LyricsResult.model_validate(r) for r in (body.get("result") or [])]
+
+    def raw_request(
+        self,
+        method: str,
+        params: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Hit any AudD endpoint by method name and return the raw JSON dict.
+
+        Useful for endpoints not yet wrapped by typed methods on this SDK.
+        """
+        data = dict(params or {})
+
+        def _do() -> Any:
+            return self._http.post_form(f"{API_BASE}/{method}/", data=data)
+
+        try:
+            resp = retry_sync(_do, self._read)
+        except httpx.RequestError as exc:
+            raise AudDConnectionError(str(exc), original=exc) from exc
+        body = resp.json_body
+        if not isinstance(body, dict):
+            raise AudDSerializationError("Unparseable response")
+        return body
+
+
+class AsyncAdvanced:
+    def __init__(self, http: AsyncHTTPClient, read: RetryPolicy) -> None:
+        self._http = http
+        self._read = read
+
+    async def find_lyrics(self, query: str) -> list[LyricsResult]:
+        body = await self.raw_request("findLyrics", {"q": query})
+        if body.get("status") == "error":
+            raise_from_error_response(body, http_status=200, request_id=None)
+        return [LyricsResult.model_validate(r) for r in (body.get("result") or [])]
+
+    async def raw_request(
+        self,
+        method: str,
+        params: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        data = dict(params or {})
+
+        async def _do() -> Any:
+            return await self._http.post_form(f"{API_BASE}/{method}/", data=data)
+
+        try:
+            resp = await retry_async(_do, self._read)
+        except httpx.RequestError as exc:
+            raise AudDConnectionError(str(exc), original=exc) from exc
+        body = resp.json_body
+        if not isinstance(body, dict):
+            raise AudDSerializationError("Unparseable response")
+        return body