rephonic 1.0.0__py3-none-any.whl

rephonic/__init__.py

@@ -0,0 +1,47 @@
+"""Official Python client for the Rephonic podcast API.
+
+Quick start::
+
+    from rephonic import Rephonic
+
+    client = Rephonic(api_key="...")
+    podcast = client.podcasts.get("huberman-lab")
+
+Or async::
+
+    from rephonic import AsyncRephonic
+
+    async with AsyncRephonic(api_key="...") as client:
+        podcast = await client.podcasts.get("huberman-lab")
+
+See https://rephonic.com/developers for the full API reference.
+"""
+
+from ._client import AsyncRephonic, Rephonic
+from ._exceptions import (
+    APIConnectionError,
+    APIStatusError,
+    AuthenticationError,
+    BadRequestError,
+    InternalServerError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    RephonicError,
+)
+from ._version import __version__
+
+__all__ = [
+    "Rephonic",
+    "AsyncRephonic",
+    "RephonicError",
+    "APIConnectionError",
+    "APIStatusError",
+    "AuthenticationError",
+    "BadRequestError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "RateLimitError",
+    "InternalServerError",
+    "__version__",
+]

rephonic/_base_client.py

@@ -0,0 +1,266 @@
+"""Low-level HTTP transport shared by all resources.
+
+Two flavours live here: :class:`BaseClient` (sync, uses ``httpx.Client``) and
+:class:`AsyncBaseClient` (async, uses ``httpx.AsyncClient``). Resource classes
+hold a reference to one of these and dispatch HTTP requests through it.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import random
+import time
+from typing import Any, Mapping, Union
+from urllib.parse import quote
+
+import httpx
+
+from ._exceptions import APIConnectionError, error_for_status
+from ._version import __version__
+
+
+def quote_path(segment: str) -> str:
+    """URL-encode a path segment so callers can't break out of the path.
+
+    ``safe=""`` means slashes, dots, and other reserved characters are all
+    percent-encoded. Use for every user-supplied value interpolated into a
+    path (podcast_id, episode_id, platform, country, category).
+    """
+    return quote(str(segment), safe="")
+
+DEFAULT_BASE_URL = "https://api.rephonic.com"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 2
+
+QueryValue = Union[str, int, float, bool, None]
+Query = Mapping[str, QueryValue]
+
+
+def _validate_api_key(api_key: str) -> None:
+    if not api_key:
+        raise ValueError(
+            "No API key provided. Pass api_key=... or set the REPHONIC_API_KEY "
+            "environment variable. Get one at https://rephonic.com/developers."
+        )
+
+
+def _validate_max_retries(max_retries: int) -> None:
+    if max_retries < 0:
+        raise ValueError(f"max_retries must be >= 0, got {max_retries}")
+
+
+def _default_headers() -> dict[str, str]:
+    return {"User-Agent": f"rephonic-python/{__version__}"}
+
+
+def _auth_headers(api_key: str) -> dict[str, str]:
+    return {"X-Rephonic-Api-Key": api_key}
+
+
+class BaseClient:
+    """Synchronous HTTP transport: auth, retries, error mapping.
+
+    Resource classes receive a ``BaseClient`` and call :meth:`request` with a
+    relative path and optional query params.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        _validate_api_key(api_key)
+        _validate_max_retries(max_retries)
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._max_retries = max_retries
+        self._owns_http_client = http_client is None
+        self._http_client = http_client or httpx.Client(timeout=timeout, headers=_default_headers())
+
+    def close(self) -> None:
+        """Close the underlying HTTP client if it was created by this instance."""
+        if self._owns_http_client:
+            self._http_client.close()
+
+    def __enter__(self) -> BaseClient:
+        return self
+
+    def __exit__(self, *exc_info: Any) -> None:
+        self.close()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Query | None = None,
+    ) -> dict[str, Any]:
+        """Make an authenticated request and return the parsed JSON body.
+
+        Retries on connection errors and on 429/5xx responses, with exponential
+        backoff plus jitter (or ``Retry-After`` when the server sends it).
+        """
+        url = f"{self._base_url}{path}"
+        cleaned = _clean_params(params) if params else None
+        headers = _auth_headers(self._api_key)
+
+        last_error: BaseException | None = None
+        for attempt in range(self._max_retries + 1):
+            try:
+                response = self._http_client.request(method, url, params=cleaned, headers=headers)
+            except httpx.HTTPError as exc:
+                last_error = exc
+                if attempt >= self._max_retries:
+                    raise APIConnectionError(f"Unable to reach Rephonic API: {exc}") from exc
+                time.sleep(_backoff_delay(attempt))
+                continue
+
+            if response.status_code < 400:
+                return _parse_json(response)
+
+            if _should_retry_status(response.status_code) and attempt < self._max_retries:
+                time.sleep(_sleep_for_response(attempt, response))
+                continue
+
+            raise _build_status_error(response)
+
+        assert last_error is not None
+        raise APIConnectionError(str(last_error)) from last_error
+
+    def get(self, path: str, *, params: Query | None = None) -> dict[str, Any]:
+        return self.request("GET", path, params=params)
+
+
+class AsyncBaseClient:
+    """Asynchronous HTTP transport. Mirrors :class:`BaseClient`."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        _validate_api_key(api_key)
+        _validate_max_retries(max_retries)
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._max_retries = max_retries
+        self._owns_http_client = http_client is None
+        self._http_client = http_client or httpx.AsyncClient(
+            timeout=timeout, headers=_default_headers()
+        )
+
+    async def aclose(self) -> None:
+        """Close the underlying HTTP client if it was created by this instance."""
+        if self._owns_http_client:
+            await self._http_client.aclose()
+
+    async def __aenter__(self) -> AsyncBaseClient:
+        return self
+
+    async def __aexit__(self, *exc_info: Any) -> None:
+        await self.aclose()
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Query | None = None,
+    ) -> dict[str, Any]:
+        url = f"{self._base_url}{path}"
+        cleaned = _clean_params(params) if params else None
+        headers = _auth_headers(self._api_key)
+
+        last_error: BaseException | None = None
+        for attempt in range(self._max_retries + 1):
+            try:
+                response = await self._http_client.request(
+                    method, url, params=cleaned, headers=headers
+                )
+            except httpx.HTTPError as exc:
+                last_error = exc
+                if attempt >= self._max_retries:
+                    raise APIConnectionError(f"Unable to reach Rephonic API: {exc}") from exc
+                await asyncio.sleep(_backoff_delay(attempt))
+                continue
+
+            if response.status_code < 400:
+                return _parse_json(response)
+
+            if _should_retry_status(response.status_code) and attempt < self._max_retries:
+                await asyncio.sleep(_sleep_for_response(attempt, response))
+                continue
+
+            raise _build_status_error(response)
+
+        assert last_error is not None
+        raise APIConnectionError(str(last_error)) from last_error
+
+    async def get(self, path: str, *, params: Query | None = None) -> dict[str, Any]:
+        return await self.request("GET", path, params=params)
+
+
+def _clean_params(params: Query) -> dict[str, str]:
+    """Drop ``None`` values and coerce booleans to lowercase strings."""
+    out: dict[str, str] = {}
+    for key, value in params.items():
+        if value is None:
+            continue
+        if isinstance(value, bool):
+            out[key] = "true" if value else "false"
+        else:
+            out[key] = str(value)
+    return out
+
+
+def _parse_json(response: httpx.Response) -> dict[str, Any]:
+    try:
+        data = response.json()
+    except json.JSONDecodeError as exc:
+        raise APIConnectionError(
+            f"Rephonic API returned non-JSON response (status {response.status_code})"
+        ) from exc
+    if not isinstance(data, dict):
+        raise APIConnectionError(
+            f"Rephonic API returned unexpected JSON shape: {type(data).__name__}"
+        )
+    return data
+
+
+def _build_status_error(response: httpx.Response) -> Exception:
+    body: dict[str, Any] | None = None
+    try:
+        parsed = response.json()
+        if isinstance(parsed, dict):
+            body = parsed
+    except json.JSONDecodeError:
+        pass
+    message = (body or {}).get("error") or response.text or response.reason_phrase
+    return error_for_status(response.status_code, message, body=body, response=response)
+
+
+def _should_retry_status(status: int) -> bool:
+    return status == 429 or status >= 500
+
+
+def _backoff_delay(attempt: int) -> float:
+    return float(min(2**attempt, 10)) + random.uniform(0, 0.25)
+
+
+def _sleep_for_response(attempt: int, response: httpx.Response) -> float:
+    retry_after = response.headers.get("Retry-After")
+    if retry_after:
+        try:
+            return float(retry_after)
+        except ValueError:
+            pass
+    return _backoff_delay(attempt)

rephonic/_client.py

@@ -0,0 +1,148 @@
+"""The top-level :class:`Rephonic` and :class:`AsyncRephonic` clients."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+from ._base_client import (
+    DEFAULT_BASE_URL,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_TIMEOUT,
+    AsyncBaseClient,
+    BaseClient,
+)
+from .resources import (
+    Account,
+    AsyncAccount,
+    AsyncCharts,
+    AsyncCommon,
+    AsyncEpisodes,
+    AsyncPodcasts,
+    AsyncSearch,
+    Charts,
+    Common,
+    Episodes,
+    Podcasts,
+    Search,
+)
+
+ENV_API_KEY = "REPHONIC_API_KEY"
+
+
+def _resolve_api_key(api_key: str | None) -> str:
+    resolved = api_key or os.environ.get(ENV_API_KEY)
+    if not resolved:
+        raise ValueError(
+            "No API key provided. Pass api_key=... or set the REPHONIC_API_KEY "
+            "environment variable. Get one at https://rephonic.com/developers."
+        )
+    return resolved
+
+
+class Rephonic:
+    """Official Python client for the Rephonic podcast API.
+
+    Get an API key at https://rephonic.com/developers.
+
+    Args:
+        api_key: Your Rephonic API key. Falls back to ``REPHONIC_API_KEY`` env.
+        base_url: Override the API base URL.
+        timeout: Request timeout in seconds.
+        max_retries: Retries on connection errors, 429s, and 5xxs (default 2).
+        http_client: Bring your own ``httpx.Client`` (for proxies, custom TLS).
+
+    Example::
+
+        from rephonic import Rephonic
+
+        client = Rephonic(api_key="...")
+        podcast = client.podcasts.get("huberman-lab")
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self._base_client = BaseClient(
+            api_key=_resolve_api_key(api_key),
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            http_client=http_client,
+        )
+
+        self.search = Search(self._base_client)
+        self.podcasts = Podcasts(self._base_client)
+        self.episodes = Episodes(self._base_client)
+        self.charts = Charts(self._base_client)
+        self.common = Common(self._base_client)
+        self.account = Account(self._base_client)
+
+    def close(self) -> None:
+        """Close the underlying HTTP client (if owned by this instance)."""
+        self._base_client.close()
+
+    def __enter__(self) -> Rephonic:
+        return self
+
+    def __exit__(self, *exc_info: Any) -> None:
+        self.close()
+
+
+class AsyncRephonic:
+    """Asynchronous client for the Rephonic podcast API.
+
+    Same surface as :class:`Rephonic`, but every resource method is a
+    coroutine. ``iter_*`` methods return async iterators.
+
+    Example::
+
+        from rephonic import AsyncRephonic
+
+        async with AsyncRephonic(api_key="...") as client:
+            podcast = await client.podcasts.get("huberman-lab")
+            async for p in client.search.iter_podcasts(query="ai", limit=100):
+                print(p["name"])
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._base_client = AsyncBaseClient(
+            api_key=_resolve_api_key(api_key),
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            http_client=http_client,
+        )
+
+        self.search = AsyncSearch(self._base_client)
+        self.podcasts = AsyncPodcasts(self._base_client)
+        self.episodes = AsyncEpisodes(self._base_client)
+        self.charts = AsyncCharts(self._base_client)
+        self.common = AsyncCommon(self._base_client)
+        self.account = AsyncAccount(self._base_client)
+
+    async def aclose(self) -> None:
+        """Close the underlying async HTTP client (if owned by this instance)."""
+        await self._base_client.aclose()
+
+    async def __aenter__(self) -> AsyncRephonic:
+        return self
+
+    async def __aexit__(self, *exc_info: Any) -> None:
+        await self.aclose()

rephonic/_exceptions.py

@@ -0,0 +1,93 @@
+"""Exception classes raised by the Rephonic client."""
+
+from typing import Any, Dict, Optional
+
+
+class RephonicError(Exception):
+    """Base class for all Rephonic client errors.
+
+    Attributes:
+        message: Human-readable error description.
+        status_code: HTTP status code, or ``None`` for non-HTTP errors.
+        body: Parsed JSON body of the error response, if available.
+        response: The underlying ``httpx.Response`` object, if available.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: Optional[int] = None,
+        body: Optional[Dict[str, Any]] = None,
+        response: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.body = body
+        self.response = response
+
+    def __str__(self) -> str:
+        if self.status_code is not None:
+            return f"[{self.status_code}] {self.message}"
+        return self.message
+
+
+class APIConnectionError(RephonicError):
+    """Raised when the client cannot reach the Rephonic API (network error, DNS, timeout)."""
+
+
+class APIStatusError(RephonicError):
+    """Base class for errors returned by the API with a non-2xx status code."""
+
+
+class BadRequestError(APIStatusError):
+    """Raised for HTTP 400 responses. Usually indicates a malformed request or invalid parameter."""
+
+
+class AuthenticationError(APIStatusError):
+    """Raised for HTTP 401 responses. Indicates a missing or invalid API key."""
+
+
+class PermissionDeniedError(APIStatusError):
+    """Raised for HTTP 403 responses. The API key is valid but lacks access to the resource."""
+
+
+class NotFoundError(APIStatusError):
+    """Raised for HTTP 404 responses.
+
+    Note: the Rephonic API returns ``400 Bad Request`` (``BadRequestError``)
+    for missing resources, not 404 — this class is reserved for future use
+    and for explicitly catching any endpoint that might adopt 404 semantics.
+    """
+
+
+class RateLimitError(APIStatusError):
+    """Raised for HTTP 429 responses. You have exceeded your request quota or rate limit."""
+
+
+class InternalServerError(APIStatusError):
+    """Raised for HTTP 5xx responses. The Rephonic API is experiencing an internal error."""
+
+
+_STATUS_TO_ERROR = {
+    400: BadRequestError,
+    401: AuthenticationError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    429: RateLimitError,
+}
+
+
+def error_for_status(
+    status_code: int,
+    message: str,
+    *,
+    body: Optional[Dict[str, Any]] = None,
+    response: Any = None,
+) -> APIStatusError:
+    """Map an HTTP status code to the most specific error subclass."""
+    cls = _STATUS_TO_ERROR.get(status_code)
+    if cls is None:
+        cls = InternalServerError if status_code >= 500 else APIStatusError
+    return cls(message, status_code=status_code, body=body, response=response)

rephonic/_version.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"

rephonic/pagination.py

@@ -0,0 +1,84 @@
+"""Pagination helpers — sync and async.
+
+The Rephonic API paginates via ``page`` / ``per_page`` query parameters. Each
+paginated endpoint returns items under a fixed key (e.g. ``podcasts``,
+``episodes``, ``reviews``) and the helpers here provide iterators that
+transparently fetch subsequent pages.
+"""
+
+from __future__ import annotations
+
+from typing import (
+    Any,
+    AsyncIterator,
+    Awaitable,
+    Callable,
+    Iterator,
+)
+
+
+def _should_continue(response: dict[str, Any], num_items: int, per_page: int) -> bool:
+    """Decide whether to request another page.
+
+    ``more`` is authoritative when the endpoint returns it (search endpoints).
+    Otherwise fall back to the "short page means last page" heuristic.
+    """
+    more = response.get("more")
+    if more is True:
+        return True
+    if more is False:
+        return False
+    return num_items >= per_page
+
+
+def iter_pages(
+    fetch_page: Callable[[int, int], dict[str, Any]],
+    *,
+    items_key: str,
+    per_page: int,
+    start_page: int = 1,
+    limit: int | None = None,
+) -> Iterator[dict[str, Any]]:
+    """Yield items one at a time across paginated responses.
+
+    Stops when the response's ``more`` field is ``False`` (or, for endpoints
+    that don't send it, when the page is shorter than ``per_page``), or when
+    ``limit`` is reached.
+    """
+    page = start_page
+    yielded = 0
+    while True:
+        response = fetch_page(page, per_page)
+        items = response.get(items_key) or []
+        for item in items:
+            if limit is not None and yielded >= limit:
+                return
+            yield item
+            yielded += 1
+        if not _should_continue(response, len(items), per_page):
+            return
+        page += 1
+
+
+async def aiter_pages(
+    fetch_page: Callable[[int, int], Awaitable[dict[str, Any]]],
+    *,
+    items_key: str,
+    per_page: int,
+    start_page: int = 1,
+    limit: int | None = None,
+) -> AsyncIterator[dict[str, Any]]:
+    """Async counterpart to :func:`iter_pages`."""
+    page = start_page
+    yielded = 0
+    while True:
+        response = await fetch_page(page, per_page)
+        items = response.get(items_key) or []
+        for item in items:
+            if limit is not None and yielded >= limit:
+                return
+            yield item
+            yielded += 1
+        if not _should_continue(response, len(items), per_page):
+            return
+        page += 1

rephonic/resources/__init__.py

@@ -0,0 +1,21 @@
+from .account import Account, AsyncAccount
+from .charts import AsyncCharts, Charts
+from .common import AsyncCommon, Common
+from .episodes import AsyncEpisodes, Episodes
+from .podcasts import AsyncPodcasts, Podcasts
+from .search import AsyncSearch, Search
+
+__all__ = [
+    "Account",
+    "AsyncAccount",
+    "Charts",
+    "AsyncCharts",
+    "Common",
+    "AsyncCommon",
+    "Episodes",
+    "AsyncEpisodes",
+    "Podcasts",
+    "AsyncPodcasts",
+    "Search",
+    "AsyncSearch",
+]

rephonic/resources/account.py

@@ -0,0 +1,28 @@
+"""Account endpoints: quota and usage."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .._base_client import AsyncBaseClient, BaseClient
+
+
+class Account:
+    """Account-level endpoints."""
+
+    def __init__(self, client: BaseClient) -> None:
+        self._client = client
+
+    def quota(self) -> dict[str, Any]:
+        """API request quota and usage for the current month."""
+        return self._client.get("/api/accounts/quota/")
+
+
+class AsyncAccount:
+    """Async counterpart to :class:`Account`."""
+
+    def __init__(self, client: AsyncBaseClient) -> None:
+        self._client = client
+
+    async def quota(self) -> dict[str, Any]:
+        return await self._client.get("/api/accounts/quota/")