discogs-sdk 0.1.0__py3-none-any.whl

discogs_sdk/__init__.py

@@ -0,0 +1,134 @@
+from discogs_sdk._async._client import AsyncDiscogs
+from discogs_sdk._sync._client import Discogs
+from discogs_sdk._exceptions import (
+    AuthenticationError,
+    DiscogsAPIError,
+    DiscogsConnectionError,
+    DiscogsError,
+    ForbiddenError,
+    NotFoundError,
+    RateLimitError,
+    ValidationError,
+)
+from discogs_sdk.models import (
+    Artist,
+    ArtistCredit,
+    ArtistRelease,
+    BasicInformation,
+    CollectionField,
+    CollectionFolder,
+    CollectionItem,
+    CollectionValue_,
+    Community,
+    CommunityRating,
+    CommunityRatingValue,
+    Company,
+    Condition,
+    CurrencyCode,
+    Export,
+    Fee,
+    Format,
+    Identifier,
+    Identity,
+    Image,
+    Label,
+    LabelCredit,
+    LabelRelease,
+    List_,
+    ListItem,
+    ListSummary,
+    Listing,
+    ListingRelease,
+    MarketplaceReleaseStats,
+    Master,
+    MasterVersion,
+    Member,
+    Order,
+    OrderItem,
+    OrderMessage,
+    OriginalPrice,
+    Price,
+    PriceSuggestions,
+    SDKModel,
+    Release,
+    ReleaseStats,
+    SearchResult,
+    ShippingInfo,
+    SleeveCondition,
+    SubLabel,
+    Track,
+    Upload,
+    User,
+    UserReleaseRating,
+    UserSummary,
+    Video,
+    Want,
+)
+
+__all__ = [
+    # Clients
+    "AsyncDiscogs",
+    "Discogs",
+    # Exceptions
+    "DiscogsError",
+    "DiscogsConnectionError",
+    "DiscogsAPIError",
+    "AuthenticationError",
+    "ForbiddenError",
+    "NotFoundError",
+    "RateLimitError",
+    "ValidationError",
+    # Models
+    "Artist",
+    "ArtistCredit",
+    "ArtistRelease",
+    "BasicInformation",
+    "CollectionField",
+    "CollectionFolder",
+    "CollectionItem",
+    "CollectionValue_",
+    "Community",
+    "CommunityRating",
+    "CommunityRatingValue",
+    "Company",
+    "Condition",
+    "CurrencyCode",
+    "Export",
+    "Fee",
+    "Format",
+    "Identifier",
+    "Identity",
+    "Image",
+    "Label",
+    "LabelCredit",
+    "LabelRelease",
+    "List_",
+    "ListItem",
+    "ListSummary",
+    "Listing",
+    "ListingRelease",
+    "MarketplaceReleaseStats",
+    "Master",
+    "MasterVersion",
+    "Member",
+    "Order",
+    "OrderItem",
+    "OrderMessage",
+    "OriginalPrice",
+    "Price",
+    "PriceSuggestions",
+    "SDKModel",
+    "Release",
+    "ReleaseStats",
+    "SearchResult",
+    "ShippingInfo",
+    "SleeveCondition",
+    "SubLabel",
+    "Track",
+    "Upload",
+    "User",
+    "UserReleaseRating",
+    "UserSummary",
+    "Video",
+    "Want",
+]

discogs_sdk/_async/__init__.py

@@ -0,0 +1,3 @@
+from discogs_sdk._async._client import AsyncDiscogs
+
+__all__ = ["AsyncDiscogs"]

discogs_sdk/_async/_client.py

@@ -0,0 +1,258 @@
+from __future__ import annotations
+
+import logging
+import time
+
+if True:  # ASYNC
+    import asyncio
+from functools import cached_property
+from typing import TYPE_CHECKING, Any
+
+from typing_extensions import Self
+
+import httpx
+
+from discogs_sdk._base_client import DEFAULT_BASE_URL, DEFAULT_TIMEOUT, BaseClient, _RETRY_STATUSES
+from discogs_sdk._exceptions import DiscogsConnectionError
+from discogs_sdk._async.resources.artists import Artists
+from discogs_sdk._async.resources.exports import Exports
+from discogs_sdk._async.resources.labels import Labels
+from discogs_sdk._async.resources.lists import Lists
+from discogs_sdk._async.resources.marketplace import Marketplace
+from discogs_sdk._async.resources.masters import Masters
+from discogs_sdk._async.resources.releases import Releases
+from discogs_sdk._async.resources.search import SearchResource
+from discogs_sdk._async.resources.uploads import Uploads
+from discogs_sdk._async.resources.users import UserNamespace, Users
+
+if TYPE_CHECKING:
+    from discogs_sdk._async._paginator import AsyncPage
+    from discogs_sdk.models.search import SearchResult
+
+logger = logging.getLogger("discogs_sdk")
+
+
+class AsyncDiscogs(BaseClient):
+    """Async client for the Discogs API.
+
+    Use as a context manager to ensure the HTTP client is properly closed::
+
+        async with AsyncDiscogs(token="...") as client:
+            release = await client.releases.get(249504)
+            print(release.title)
+    """
+
+    def __init__(
+        self,
+        *,
+        token: str | None = None,
+        consumer_key: str | None = None,
+        consumer_secret: str | None = None,
+        access_token: str | None = None,
+        access_token_secret: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = 3,
+        cache: bool = False,
+        http_client: httpx.AsyncClient | None = None,
+        user_agent: str | None = None,
+    ) -> None:
+        """Create an async Discogs client.
+
+        Args:
+            token: Personal access token from https://www.discogs.com/settings/developers.
+            consumer_key: OAuth consumer key for app-level auth.
+            consumer_secret: OAuth consumer secret for app-level auth.
+            access_token: OAuth access token for user-level auth.
+            access_token_secret: OAuth access token secret for user-level auth.
+            base_url: API base URL.
+            timeout: Request timeout in seconds.
+            max_retries: Max retries on 429/5xx/connection errors.
+            cache: Enable HTTP caching (requires ``discogs-sdk[cache]``).
+            http_client: Custom ``httpx.AsyncClient`` to use instead of creating one.
+            user_agent: Custom User-Agent string. Replaces the default entirely.
+                Should follow RFC 1945 product token format for best compatibility with Discogs.
+        """
+        super().__init__(
+            token=token,
+            consumer_key=consumer_key,
+            consumer_secret=consumer_secret,
+            access_token=access_token,
+            access_token_secret=access_token_secret,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            user_agent=user_agent,
+        )
+        if http_client is not None:
+            self._http_client = http_client
+            self._owns_client = False
+        elif cache:
+            try:
+                from hishel.httpx import AsyncCacheClient  # ty: ignore[unresolved-import]
+            except ImportError:
+                raise ImportError(
+                    "hishel is required for caching support. Install it with: pip install discogs-sdk[cache]"
+                ) from None
+            self._http_client = AsyncCacheClient(
+                headers=self._build_headers(),
+                timeout=self.timeout,
+            )
+            self._owns_client = True
+        else:
+            self._http_client = httpx.AsyncClient(
+                headers=self._build_headers(),
+                timeout=self.timeout,
+            )
+            self._owns_client = True
+
+    async def _send(
+        self,
+        method: str,
+        url: str,
+        *,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+        files: dict[str, Any] | None = None,
+    ) -> httpx.Response:
+        kwargs: dict[str, Any] = {}
+        if json is not None:
+            kwargs["json"] = json
+        if params is not None:
+            kwargs["params"] = params
+        if files is not None:
+            kwargs["files"] = files
+        if self._uses_oauth:
+            kwargs.setdefault("headers", {})["Authorization"] = self._build_oauth_header_for_request()
+
+        for attempt in range(self.max_retries + 1):
+            logger.debug("HTTP request: %s %s", method, url)
+            t0 = time.monotonic()  # Unaffected by system clock adjustments (NTP, DST)
+            try:
+                response = await self._http_client.request(method, url, **kwargs)
+            except (httpx.ConnectError, httpx.TimeoutException) as exc:
+                elapsed_ms = (time.monotonic() - t0) * 1000
+                if attempt == self.max_retries:
+                    logger.debug("HTTP connection error after %.0fms: %s", elapsed_ms, exc)
+                    raise DiscogsConnectionError(str(exc)) from exc
+                delay = self._retry_delay(attempt)
+                logger.info(
+                    "Retrying %s %s (attempt %d/%d) after connection error (%.0fms), waiting %.1fs",
+                    method,
+                    url,
+                    attempt + 2,
+                    self.max_retries + 1,
+                    elapsed_ms,
+                    delay,
+                )
+                if True:  # ASYNC
+                    await asyncio.sleep(delay)
+                else:
+                    time.sleep(delay)
+                continue
+
+            elapsed_ms = (time.monotonic() - t0) * 1000
+            logger.debug(
+                "HTTP response: %s %s -> %d (%.0fms)",
+                method,
+                url,
+                response.status_code,
+                elapsed_ms,
+            )
+
+            if response.status_code not in _RETRY_STATUSES or attempt == self.max_retries:
+                return response
+
+            delay = self._retry_delay(attempt, retry_after=response.headers.get("Retry-After"))
+            logger.info(
+                "Retrying %s %s (attempt %d/%d) after status %d, waiting %.1fs",
+                method,
+                url,
+                attempt + 2,
+                self.max_retries + 1,
+                response.status_code,
+                delay,
+            )
+            if True:  # ASYNC
+                await asyncio.sleep(delay)
+            else:
+                time.sleep(delay)
+
+        return response  # pragma: no cover — unreachable but satisfies type checker
+
+    # --- Database ---
+
+    @cached_property
+    def artists(self) -> Artists:
+        return Artists(self)
+
+    @cached_property
+    def labels(self) -> Labels:
+        return Labels(self)
+
+    @cached_property
+    def masters(self) -> Masters:
+        return Masters(self)
+
+    @cached_property
+    def releases(self) -> Releases:
+        return Releases(self)
+
+    def search(self, **params: Any) -> AsyncPage[SearchResult]:
+        """Search the Discogs database.
+
+        Accepts any Discogs search parameter as a keyword argument
+        (e.g. ``query``, ``type``, ``title``, ``artist``, ``label``, ``genre``).
+
+        Returns an auto-paging iterator of search results.
+        """
+        return SearchResource(self)(**params)
+
+    # --- Marketplace ---
+
+    @cached_property
+    def marketplace(self) -> Marketplace:
+        return Marketplace(self)
+
+    # --- Inventory ---
+
+    @cached_property
+    def exports(self) -> Exports:
+        return Exports(self)
+
+    @cached_property
+    def uploads(self) -> Uploads:
+        return Uploads(self)
+
+    # --- Users ---
+
+    @cached_property
+    def user(self) -> UserNamespace:
+        return UserNamespace(self)
+
+    @cached_property
+    def users(self) -> Users:
+        return Users(self)
+
+    # --- Lists ---
+
+    @cached_property
+    def lists(self) -> Lists:
+        return Lists(self)
+
+    # --- Lifecycle ---
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client.
+
+        Only closes the client if it was created by this instance,
+        not if a custom ``http_client`` was passed to the constructor.
+        """
+        if self._owns_client:
+            await self._http_client.aclose()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()

discogs_sdk/_async/_lazy.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Callable
+
+from pydantic import BaseModel
+
+if TYPE_CHECKING:
+    from discogs_sdk._async._client import AsyncDiscogs
+
+
+class AsyncLazyResource:
+    """Proxy that defers the HTTP call until explicitly awaited (async)
+    or until a data attribute is accessed (sync, via generated code).
+
+    Sub-resource accessors (defined in ``sub_resources``) are returned
+    immediately without triggering any HTTP call in both variants.
+    """
+
+    def __init__(
+        self,
+        client: AsyncDiscogs,
+        path: str,
+        model_cls: type[BaseModel],
+        sub_resources: dict[str, Callable[[], Any]] | None = None,
+    ) -> None:
+        # Use object.__setattr__ to bypass __getattr__, which would trigger _resolve() and defeat lazy loading
+        object.__setattr__(self, "_client", client)
+        object.__setattr__(self, "_path", path)
+        object.__setattr__(self, "_model_cls", model_cls)
+        object.__setattr__(self, "_sub_resources", sub_resources or {})
+        object.__setattr__(self, "_resolved", None)
+
+    async def _resolve(self) -> BaseModel:
+        resolved = object.__getattribute__(self, "_resolved")
+        if resolved is not None:
+            return resolved
+
+        client = object.__getattribute__(self, "_client")
+        path = object.__getattribute__(self, "_path")
+        model_cls = object.__getattribute__(self, "_model_cls")
+
+        response = await client._send("GET", client._build_url(path))
+        body = response.json()
+        client._maybe_raise(response.status_code, body, retry_after=response.headers.get("Retry-After"))
+
+        resolved = model_cls.model_validate(body)
+        object.__setattr__(self, "_resolved", resolved)
+        return resolved
+
+    def __getattr__(self, name: str) -> Any:
+        # Check sub-resources first (no HTTP call)
+        sub_resources = object.__getattribute__(self, "_sub_resources")
+        if name in sub_resources:
+            resource = sub_resources[name]()
+            object.__setattr__(self, name, resource)
+            return resource
+
+        if True:  # ASYNC
+            # Already resolved (after await)? Delegate to model.
+            resolved = object.__getattribute__(self, "_resolved")
+            if resolved is not None:
+                return getattr(resolved, name)
+            raise AttributeError(
+                f"Cannot access '{name}' on unresolved AsyncLazyResource. Use: resolved = await resource"
+            )
+        else:
+            # Otherwise, resolve the model via HTTP and delegate
+            model = self._resolve()
+            return getattr(model, name)
+
+    def __getitem__(self, key: str) -> Any:
+        if True:  # ASYNC
+            resolved = object.__getattribute__(self, "_resolved")
+            if resolved is None:
+                raise TypeError("Cannot subscript unresolved AsyncLazyResource. Use: resolved = await resource")
+        else:
+            resolved = self._resolve()
+        getter = getattr(resolved, "__getitem__", None)
+        if getter is None:
+            raise TypeError(f"'{type(resolved).__name__}' object is not subscriptable")
+        return getter(key)  # pragma: no cover — no current model supports subscript
+
+    if True:  # ASYNC
+
+        def __await__(self):
+            return self._resolve().__await__()
+
+    def __repr__(self) -> str:
+        path = object.__getattribute__(self, "_path")
+        model_cls = object.__getattribute__(self, "_model_cls")
+        resolved = object.__getattribute__(self, "_resolved")
+        if resolved is not None:
+            return repr(resolved)
+        return f"<AsyncLazyResource {model_cls.__name__} path={path!r}>"

discogs_sdk/_async/_oauth.py

@@ -0,0 +1,100 @@
+"""OAuth 1.0a helpers for the Discogs API (PLAINTEXT signature method)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from urllib.parse import parse_qs
+
+import httpx
+
+from discogs_sdk._base_client import DEFAULT_BASE_URL, USER_AGENT, build_oauth_header
+
+_ACCESS_TOKEN_PATH = "/oauth/access_token"
+_AUTHORIZE_URL = "https://www.discogs.com/oauth/authorize"
+_REQUEST_TOKEN_PATH = "/oauth/request_token"
+
+
+@dataclass
+class RequestToken:
+    authorize_url: str
+    oauth_token_secret: str
+    oauth_token: str
+
+
+@dataclass
+class AccessToken:
+    oauth_token: str
+    oauth_token_secret: str
+
+
+async def get_request_token(
+    consumer_key: str,
+    consumer_secret: str,
+    callback_url: str = "oob",
+    *,
+    base_url: str = DEFAULT_BASE_URL,
+) -> RequestToken:
+    """Step 1-2 of the OAuth flow: obtain a request token and authorize URL.
+
+    Returns a RequestToken with the token, secret, and a URL to redirect
+    the user to for authorization.
+    """
+    auth_header = build_oauth_header(
+        callback=callback_url,
+        consumer_key=consumer_key,
+        consumer_secret=consumer_secret,
+    )
+    headers = {
+        "Content-Type": "application/x-www-form-urlencoded",
+        "Authorization": auth_header,
+        "User-Agent": USER_AGENT,
+    }
+    async with httpx.AsyncClient() as client:
+        response = await client.get(f"{base_url.rstrip('/')}{_REQUEST_TOKEN_PATH}", headers=headers)
+    response.raise_for_status()
+
+    parsed = parse_qs(response.text)
+    token = parsed["oauth_token"][0]
+    token_secret = parsed["oauth_token_secret"][0]
+    return RequestToken(
+        authorize_url=f"{_AUTHORIZE_URL}?oauth_token={token}",
+        oauth_token_secret=token_secret,
+        oauth_token=token,
+    )
+
+
+async def get_access_token(
+    consumer_key: str,
+    consumer_secret: str,
+    request_token: str,
+    request_token_secret: str,
+    verifier: str,
+    *,
+    base_url: str = DEFAULT_BASE_URL,
+) -> AccessToken:
+    """Step 4 of the OAuth flow: exchange the request token for an access token.
+
+    The verifier is obtained after the user authorizes the app at the
+    authorize URL from get_request_token().
+    """
+    auth_header = build_oauth_header(
+        consumer_key=consumer_key,
+        consumer_secret=consumer_secret,
+        token_secret=request_token_secret,
+        token=request_token,
+        verifier=verifier,
+    )
+    headers = {
+        "Content-Type": "application/x-www-form-urlencoded",
+        "Authorization": auth_header,
+        "User-Agent": USER_AGENT,
+    }
+    async with httpx.AsyncClient() as client:
+        response = await client.post(f"{base_url.rstrip('/')}{_ACCESS_TOKEN_PATH}", headers=headers)
+    response.raise_for_status()
+
+    parsed = parse_qs(response.text)
+    return AccessToken(
+        oauth_token=parsed["oauth_token"][0],
+        oauth_token_secret=parsed["oauth_token_secret"][0],
+    )

discogs_sdk/_async/_paginator.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, AsyncIterator, Generic, TypeVar
+
+from pydantic import BaseModel
+
+if TYPE_CHECKING:
+    from discogs_sdk._async._client import AsyncDiscogs
+
+T = TypeVar("T", bound=BaseModel)
+
+
+class AsyncPage(Generic[T]):
+    """Auto-paging async iterator over Discogs paginated responses.
+
+    Discogs pagination format::
+
+        {
+            "pagination": {"page": 1, "pages": 5, "urls": {"next": "..."}},
+            "<items_key>": [...]
+        }
+
+    For nested responses (e.g. submissions), set ``items_path`` to traverse
+    into the response body before extracting items::
+
+        {"submissions": {"releases": [...]}}
+        items_path=["submissions", "releases"]
+    """
+
+    def __init__(
+        self,
+        client: AsyncDiscogs,
+        path: str,
+        model_cls: type[T],
+        items_key: str,
+        *,
+        params: dict[str, Any] | None = None,
+        items_path: list[str] | None = None,
+    ) -> None:
+        self._client = client
+        self._path = path
+        self._params = {**(params or {}), "page": 1}
+        self._model_cls = model_cls
+        self._items_key = items_key
+        self._items_path = items_path
+
+        self._items: list[T] = []
+        self._index = 0
+        self._next_url: str | None = None
+        self._exhausted = False
+        self._first_page_fetched = False
+
+    async def _fetch_page(self) -> None:
+        if self._next_url:
+            response = await self._client._send("GET", self._next_url)
+        else:
+            response = await self._client._send(
+                "GET",
+                self._client._build_url(self._path),
+                params=self._params,
+            )
+
+        body = response.json()
+        self._client._maybe_raise(response.status_code, body, retry_after=response.headers.get("Retry-After"))
+
+        pagination = body.get("pagination", {})
+        urls = pagination.get("urls", {})
+        self._next_url = urls.get("next")
+        if not self._next_url:
+            self._exhausted = True
+
+        if self._items_path:
+            container = body
+            for key in self._items_path:
+                container = container.get(key, {})
+            raw_items = container if isinstance(container, list) else []
+        else:
+            raw_items = body.get(self._items_key, [])
+
+        self._items = [self._model_cls.model_validate(item) for item in raw_items]
+        self._index = 0
+        self._first_page_fetched = True
+
+    def __aiter__(self) -> AsyncIterator[T]:
+        return self
+
+    async def __anext__(self) -> T:
+        if not self._first_page_fetched:
+            await self._fetch_page()
+
+        if self._index >= len(self._items):
+            if self._exhausted:
+                raise StopAsyncIteration
+            await self._fetch_page()
+            if not self._items:
+                raise StopAsyncIteration
+
+        item = self._items[self._index]
+        self._index += 1
+        return item