DiscogsAPIClient¶

class minim.api.discogs.DiscogsAPIClient(*, auth_flow: str | None = None, consumer_key: str | None = None, consumer_secret: str | None = None, user_identifier: str | None = None, redirect_uri: str | None = None, access_token: str | None = None, access_token_secret: str | None = None, redirect_handler: str | None = None, open_browser: bool = False, enable_cache: bool = True, limit_rate: bool = True, store_tokens: bool = True, user_agent: str = 'minim/2.0.0-alpha +https://github.com/bbye98/minim')[source]¶

Bases: OAuth1APIClient

Discogs API client.

Parameters:

auth_flowstr or None; keyword-only

Authorization flow.

Valid values:

None – No authentication or authentication using a personal access token.
"two_legged" – Discogs Auth (Two-Legged) Flow.
"three_legged" – OAuth (Three-Legged) Flow.

consumer_keystr; keyword-only; optional

Consumer key. Required for the two-legged and three-legged flows unless set as system environment variable DISCOGS_API_CONSUMER_KEY or stored in the local token storage.

consumer_secretstr; keyword-only; optional

Consumer secret. Required for the two-legged and three-legged flows unless set as system environment variable DISCOGS_API_CONSUMER_SECRET or stored in the local token storage.

user_identifierstr; keyword-only; optional

Identifier for the user account. Used when store_tokens=True to distinguish between multiple accounts for the same consumer key and authorization flow.

If specified, it is used with the consumer key and authorization flow to locate a matching stored token. If none is found, a new token is obtained and stored under this identifier.

If not specified, the most recently accessed token for the consumer key and authorization flow is used. If none exists, a new token is obtained and stored using a user identifier (e.g., user ID) acquired from a successful authorization.

Prefixing the identifier with a tilde (~) bypasses token retrieval, forces reauthorization, and stores the new token under the suffix.

redirect_uristr; keyword-only; optional

Redirect URI (or OAuth callback). Required for the three-legged flow.

access_tokenstr; keyword-only; optional

OAuth or personal access token. If provided, the authorization process is bypassed.

access_token_secretstr; positional-only; optional

OAuth access token secret. Required for the three-legged flow when an access token is provided in access_token.

redirect_handlerstr or None; keyword-only; optional

Backend for handling redirects during the authorization flow. Redirect handling is only available for hosts localhost, 127.0.0.1, or ::1.

Valid values:

None – Show authorization URL in and have the user manually paste the redirect URL into the terminal.
"http.server" – Run a HTTP server to intercept the redirect after user authorization in any local browser.
"playwright" – Use a Playwright Firefox browser to complete the user authorization.

open_browserbool; keyword-only; default: False

Whether to automatically open the authorization URL in the default web browser for the three-legged flow. If False, the URL is printed to the terminal.

enable_cachebool; keyword-only; default: True

Whether to enable an in-memory time-to-live (TTL) cache with a least recently used (LRU) eviction policy for this client. If True, responses from semi-static endpoints are cached for one minute to one day, depending on their expected update frequency.

See also

get_tokens() – Retrieve specific or all stored access tokens for this client.

remove_tokens() – Remove specific or all stored access tokens for this client.

user_agentstr; keyword-only; default: "minim/X.Y.Z +https://github.com/bbye98/minim"

User-Agent value to include in the headers of HTTP requests.

Methods

`clear_cache`	Clear specific or all cache entries for this client.
`close`	Terminate the underlying HTTP client session.
`get_tokens`	Retrieve specific or all access tokens and their metadata for this client from local storage.
`open`	Initialize a new HTTP client session.
`remove_tokens`	Remove specific or all access tokens and their metadata for this client from local storage.
`set_access_token`	Set or update the access token and its related metadata.
`set_auth_flow`	Set or update the authorization flow and related parameters.
`set_cache_enabled`	Enable or disable the in-memory TTL cache for this client.

Attributes

`database`	Database API endpoints for the Discogs API.
`inventory`	Inventory Export and Inventory Upload API endpoints for the Discogs API.
`marketplace`	Marketplace API endpoints for the Discogs API.
`search`	Search API endpoints for the Discogs API.
`users`	User Identity, User Collection, User Wantlist, and User Lists API endpoints for the Discogs API.
`ACCESS_TOKEN_URL`	Access token endpoint.
`AUTH_URL`	Authorization endpoint.
`BASE_URL`	Base URL for API endpoints.
`REQUEST_TOKEN_URL`	Request token endpoint.

ACCESS_TOKEN_URL: str = 'https://api.discogs.com/oauth/access_token'¶: Access token endpoint.

AUTH_URL: str = 'https://www.discogs.com/oauth/authorize'¶: Authorization endpoint.

BASE_URL: str = 'https://api.discogs.com'¶: Base URL for API endpoints.

REQUEST_TOKEN_URL: str = 'https://api.discogs.com/oauth/request_token'¶: Request token endpoint.

clear_cache(endpoint_methods: str | Callable[..., Any] | Collection[str | Callable[..., Any]] | None = None, /) → None¶

Clear specific or all cache entries for this client.

Warning

If endpoint_methods is not provided, all cache entries are cleared.

Parameters:

endpoint_methodsstr, Callable, or Collection[str | Callable]; positional-only; optional: Endpoint methods whose cache entries should be cleared.

close() → None¶: Terminate the underlying HTTP client session.

database: DatabaseAPI¶: Database API endpoints for the Discogs API.

Retrieve specific or all access tokens and their metadata for this client from local storage.

Parameters:

auth_flowsstr or list[str]; keyword-only; optional: Authorization flows.
consumer_keysstr or list[str]; keyword-only; optional: Consumer keys.
user_identifiersstr or list[str]; keyword-only; optional: Identifiers for the user accounts.

inventory: InventoryAPI¶: Inventory Export and Inventory Upload API endpoints for the Discogs API.

marketplace: MarketplaceAPI¶: Marketplace API endpoints for the Discogs API.

open() → None¶: Initialize a new HTTP client session.

Remove specific or all access tokens and their metadata for this client from local storage.

Warning

If none of auth_flows, consumer_keys, or user_identifiers are provided, all tokens for this client will be removed from local storage.

Parameters:

auth_flowsstr or list[str]; keyword-only; optional: Authorization flows.
consumer_keysstr or list[str]; keyword-only; optional: Consumer keys.
user_identifiersstr or list[str]; keyword-only; optional: Identifiers for the user accounts.

search: SearchAPI¶: Search API endpoints for the Discogs API.

set_access_token(access_token: str | None = None, access_token_secret: str | None = None, /) → None[source]¶

Set or update the access token and its related metadata.

Warning

Calling this method replaces all existing values with the provided parameters. Parameters not provided explicitly will be overwritten by their default values.

Parameters:

access_tokenstr or None; positional-only; optional: OAuth or personal access token.

Important

If the access token was acquired via a different authorization flow or client, call set_auth_flow() first to ensure that all other relevant authorization parameters are set correctly.
access_token_secretstr; positional-only; optional: OAuth access token secret. Required for the three-legged flow when an access token is provided in access_token.

set_auth_flow(auth_flow: str | None, /, *, consumer_key: str | None = None, consumer_secret: str | None = None, user_identifier: str | None = None, redirect_uri: str | None = None, redirect_handler: str | None = None, signature_method: str = 'PLAINTEXT', open_browser: bool = False, store_tokens: bool = True, authenticate: bool = True) → None[source]¶

Set or update the authorization flow and related parameters.

Warning

Calling this method replaces all existing values with the provided parameters. Parameters not provided explicitly will be overwritten by their default values.

Parameters:

auth_flowstr or None; keyword-only

Authorization flow.

Valid values:

None – No authentication or authentication using a personal access token.
"two_legged" – Discogs Auth (Two-Legged) Flow.
"three_legged" – OAuth (Three-Legged) Flow.

consumer_keystr; keyword-only; optional

Consumer key. Required for the two-legged and three-legged flows unless set as system environment variable DISCOGS_API_CONSUMER_KEY or stored in the local token storage.

consumer_secretstr; keyword-only; optional

Consumer secret. Required for the two-legged and three-legged flows unless set as system environment variable DISCOGS_API_CONSUMER_SECRET or stored in the local token storage.

user_identifierstr; keyword-only; optional

Identifier for the user account. Used when store_tokens=True to distinguish between multiple accounts for the same consumer key and authorization flow.

If specified, it is used with the consumer key and authorization flow to locate a matching stored token. If none is found, a new token is obtained and stored under this identifier.

Prefixing the identifier with a tilde (~) bypasses token retrieval, forces reauthorization, and stores the new token under the suffix.

redirect_uristr; keyword-only; optional

Redirect URI (or OAuth callback). Required for the three-legged flow.

redirect_handlerstr or None; keyword-only; optional

Backend for handling redirects during the authorization flow. Redirect handling is only available for hosts localhost, 127.0.0.1, or ::1.

Valid values:

None – Show authorization URL in and have the user manually paste the redirect URL into the terminal.
"http.server" – Run a HTTP server to intercept the redirect after user authorization in any local browser.
"playwright" – Use a Playwright Firefox browser to complete the user authorization.

signature_methodstr; keyword-only; default: "PLAINTEXT"

Mechanism used to sign requests.

Valid value:

"PLAINTEXT" – Uses the consumer secret and the access token secret directly as the signature.

open_browserbool; keyword-only; default: False

Whether to automatically open the authorization URL in the default web browser for the three-legged flow. If False, the URL is printed to the terminal.

store_tokensbool; keyword-only; default: True