discogs-sdk

discogs-sdk is a modern Python client for the Discogs API covering every documented v2 endpoint, with a fluent chainable syntax and built-in response caching.

from discogs_sdk import Discogs

with Discogs() as client:
    release = client.releases.get(352665)
    print(f"{release.title} ({release.year})")

    for result in client.search(query="Nine Inch Nails", type="artist"):
        print(result.title)

Installation

pip install discogs-sdk
# or
uv add discogs-sdk

Requires Python 3.10+.

Features

• Complete Endpoint Coverage — Every route in the Discogs API v2 documentation
• Fluent API — Chain sub-resources naturally: client.releases.get(id).rating.get()
• Lazy Loading — No HTTP calls until you actually need the data
• Effortless Pagination — Browse results without managing pages or offsets
• Rate Limit Aware — Bounded retries with Retry-After support, the live budget on client.ratelimit, and a structured event per request
• Built-in Caching — Optional TTL-based caching reduces API calls
• Flexible Auth — Supports personal tokens, consumer key/secret, or full OAuth 1.0a
• Type Safe — Get autocomplete and IDE support
• Async & Sync — Full support for both synchronous and asynchronous workflows

How it compares

The established alternative is python3-discogs-client. Both load data lazily, paginate automatically, support OAuth 1.0a and back off on HTTP 429, so the differences that matter are:

† No inventory export or upload, release ratings or have/want stats, collection fields, folder creation, contributions or submissions.

Coming from python3-discogs-client? The migration guide maps each of its idioms to discogs-sdk and names the behaviour that differs.

Quick start

Create a personal access token in your Discogs developer settings and export it; the client reads it from the environment (other auth modes):

export DISCOGS_TOKEN="your-token-here"

from discogs_sdk import Discogs

with Discogs() as client:
    release = client.releases.get(352665)  # no request yet
    print(release.title)  # the GET is sent here → "The Downward Spiral"

    for rel in client.artists.get(3857).releases.list(sort="year"):
        print(f"{rel.title} ({rel.year})")

The async client has the same API. Await a lazy resource to fetch it, and iterate pages with async for:

import asyncio

from discogs_sdk import AsyncDiscogs


async def main():
    async with AsyncDiscogs() as client:
        release = await client.releases.get(352665)
        print(release.title)

        async for result in client.search(query="Nine Inch Nails", type="artist"):
            print(result.title)


asyncio.run(main())

Behaviors to know

• Lazy loading. .get() sends no request; the first data attribute access does, and that is where NotFoundError is raised. More
• Async. await a proxy for its data and use async for on pages. Awaiting returns the model, which has no sub-resources, so keep the proxy to chain (artist_proxy.releases.list()). More
• Pagination cost. search() and most .list() methods fetch pages on demand. Each page is a GET against the rate limit (60/min authenticated, 25/min anonymous); a cache hit costs nothing (one request if the entry no longer parses) and retries can cost more. More
• Retries. Reads retry; a mutation is never replayed after an ambiguous failure. More
• Caching. Off by default; only GET/HEAD are cached; a successful write clears the cache. More

Design principles

The SDK does more than relay requests: it pages, retries, renames keys and parses timestamps. These rules say what it may and may not do, and every new feature is checked against them.

• Requests stay predictable. A low-level method sends only the requests its documentation names. Combining calls is fine; the method documents the cost, and every call is observable through on_request. Auto-paging sends one GET per page as you iterate (cost), a lazy proxy sends one GET on its first data access (lazy loading), and a retried read emits one RequestEvent whose attempts counts every send (observability).
• Data may be normalized (names, types, timestamps, URLs) when nothing is lost, because raw keeps the original; when the result is computed from the response alone; and when the normalization is documented. Examples are renamed keys, timestamps parsed into aware datetimes and the absolute uri on search results. A guess the SDK cannot avoid is measured, documented and checkable through raw, like the America/Los_Angeles zone it assumes for a timestamp sent without an offset.
• Data is never made up. The SDK invents no value that the API did not send or that cannot be computed from what it sent, such as a guessed currency. A timestamp it cannot parse becomes None, not an estimate.
• Helpers may combine calls for common use cases. They send requests only through the SDK's public methods, so the cache, retries and on_request apply to them as to any other call.
• Defaults are safe, sane and unsurprising. In particular, helpers don't cap their effort by default. A caller who wants a bound passes one, and a capped result says whether it is complete.
• Undocumented behaviour is quarantined. A helper that depends on API behaviour Discogs does not document lives in discogs_sdk.experimental. It documents that dependency and its consequences, such as whether its result can be trusted to be complete; it raises when it detects that the behaviour clearly no longer holds; and it may change or be removed without a deprecation period. Core methods never depend on undocumented behaviour.

Experimental helpers

discogs_sdk.experimental holds helpers that depend on API behaviour Discogs does not document, under the rules above: each may change or be removed without a deprecation period.

releases_added_since() answers a question the API has no filter for: which releases matching a search were added to Discogs on or after a date. It takes a Discogs client; async_releases_added_since() takes an AsyncDiscogs one.

from datetime import date

from discogs_sdk import Discogs
from discogs_sdk.experimental import releases_added_since

with Discogs() as client:
    result = releases_added_since(client, date(2026, 10, 1), artist="Nine Inch Nails")
    for release in result.releases:  # newest first
        print(release.date_added, release.title)
    print(result.complete)  # False only when max_requests stopped the scan

• Completeness assumes an undocumented sort. The helper searches with sort="date_added" and sort_order="desc", which Discogs answers newest-added first without documenting it, and looks up each result to read its date_added, stopping at the first release added before the date. Every release it returns has a verified date, but a newer release that Discogs sorts after an older one is never seen. A date_added newer than the one before it shows the sort is not holding and raises DiscogsError.
• Cost. One search request per page scanned, plus one lookup per release in the window, plus one for the release that ends the scan (none when the results run out first). A release without a date_added is skipped and costs a lookup too. Cache hits cost nothing, and each retry is one more send.
• No cap by default. max_requests=N bounds the HTTP sends, retries included. Once the sends reach it the helper returns what it found with complete=False; a request already started may still retry, so the total can exceed N by up to client.max_retries.

A date means the start of that day in UTC; a datetime must be timezone-aware. type may only be "release", and sort, sort_order and page belong to the helper: passing them raises ValueError before any request.

Documentation

The full guide lives in docs/:

• Getting started — behaviors to know, installation, fetching, search, sub-resources, async usage
• Pagination — what a page costs, stopping early, fetching one page, page attributes
• Authentication — personal token, consumer key/secret, OAuth 1.0a, credential precedence
• Collection and marketplace — folders, instances, wantlist, listings, orders
• Errors and retries — rate limits, retries, the exception hierarchy
• Configuration — every client parameter
• Caching — the response cache, no_cache(), cache_only(), custom backends
• Observability — client.ratelimit and on_request events
• Concurrency — sharing a client across threads and tasks
• Custom HTTP clients — injecting an httpx2 client
• Models — field naming, search result links, timestamps, original API values
• Migrating from python3-discogs-client — idiom-by-idiom translation and behaviour differences
• Endpoint map — which SDK call reaches which Discogs endpoint
• AI coding agents — installing the packaged agent skill, and a rules snippet for other agents

Examples

The examples/ directory has runnable scripts for every feature:

• quickstart.py — first requests, lazy loading, search
• authentication.py — all auth modes including OAuth 1.0a
• database.py — releases, artists, masters, labels, search
• marketplace.py — listings, orders, fees, inventory
• collection.py — folders, instances, fields, wantlist
• async_usage.py — async client with await and async for
• advanced.py — error handling, caching, custom HTTP clients, exports

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines.

License

discogs-sdk is licensed under the Apache License 2.0.