PrivateQobuzAPIClient

class minim.api.qobuz.PrivateQobuzAPIClient(*, auth_flow: str | None = None, app_id: str | None = None, app_secret: str | None = None, auth_key: str | None = None, user_identifier: str | None = None, redirect_uri: str | None = None, user_auth_token: str | None = None, credential_handler: str | None = None, redirect_handler: str | None = None, open_browser: bool = False, enable_cache: bool = True, store_tokens: bool = True, user_agent: str | None = None, **kwargs: dict[str, Any])

Bases: OAuthAPIClient

Private Qobuz API client.

Attention

As the private Qobuz API is not designed to be publicly accessible, this client may break without warning if Qobuz makes internal changes or be disabled and removed at any time to ensure compliance with the Qobuz API Terms of Use.

Parameters:

auth_flowstr or None; keyword-only; optional

Authorization flow.

Valid values:

• None – No authentication.

• "ext_auth_code" – Qobuz authorization code flow.

• "password" – Qobuz Web Player login flow.

app_idstr; keyword-only; optional

Application ID. If not provided, it is loaded from the system environment variable PRIVATE_QOBUZ_API_APP_ID or from the local token storage if available, or retrieved from the Qobuz Web Player login page otherwise.

app_secretstr; keyword-only; optional

Application secret. If not provided, it is loaded from the system environment variable PRIVATE_QOBUZ_API_APP_SECRET or from the local token storage if available, or retrieved from the Qobuz Web Player login page otherwise.

auth_keystr; keyword-only; optional

Authorization key used in the Authorization Code flow. If not provided, it is loaded from the system environment variable PRIVATE_QOBUZ_API_AUTH_KEY if available, or retrieved from the Qobuz Web Player login page otherwise.

user_identifierstr; keyword-only; optional

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

If specified, it is used with the client ID 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 client ID 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. Required for the Authorization Code flow.

user_auth_tokenstr; keyword-only; optional

User authentication token. If provided, the authorization process is bypassed.

credential_handlerstr; keyword-only; optional

Backend for handling user credentials during the Qobuz Web Player login flow. If not specified, the client first looks for credentials in kwargs and falls back to prompting for them in an echo-free terminal.

Valid values:

• "kwargs" – User credentials (email or username and password or its MD5 hash) provided directly via the username and password keyword arguments, respectively.

• "getpass" – Prompt for credentials in an echo-free terminal.

• "playwright" – Open the Qobuz Web Player login page in a Playwright Firefox browser.

redirect_handlerstr or None; keyword-only; optional

Backend for handling redirects during the Authorization Code 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 Authorization Code 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

clear_cache() – Clear specific or all cache entries for this client.

store_tokensbool; keyword-only; default: True

Whether to enable the local token storage for this client. If True, existing user authentication tokens are retrieved when found in local storage, and newly acquired tokens and their metadata are stored for future retrieval. If False, the client neither retrieves nor stores tokens.

See also

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

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

user_agentstr; keyword-only; optional

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

**kwargsdict[str, Any]

Keyword arguments to pass to login().

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 user authentication tokens and their metadata for this client from local storage.
open	Initialize a new HTTP client session.
remove_tokens	Remove specific or all user authentication tokens and their metadata for this client from local storage.
set_access_token	Set or update the access token.
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.
set_user_auth_token	Set or update the user authentication token.

Attributes

albums	Albums API endpoints for the private Qobuz API.
artists	Artists API endpoints for the private Qobuz API.
catalog	Catalog API endpoints for the private Qobuz API.
dynamic	Dynamic Tracks API endpoints for the private Qobuz API.
favorites	Favorites API endpoints for the private Qobuz API.
labels	Labels API endpoints for the private Qobuz API.
genres	Genres API endpoints for the private Qobuz API.
playlists	Playlists API endpoints for the private Qobuz API.
purchases	Purchases API endpoints for the private Qobuz API.
search	Search-related endpoints for the private Qobuz API.
tracks	Tracks API endpoints for the private Qobuz API.
users	Users API endpoints for the private Qobuz API.
AUTH_URL	Authorization endpoint.
BASE_URL	Base URL for API endpoints.
TOKEN_URL	Token endpoint.
WEB_PLAYER_URL	Web Player URL.

AUTH_URL: str = 'https://www.qobuz.com/signin/oauth'

Authorization endpoint.

BASE_URL: str = 'https://www.qobuz.com/api.json/0.2'

Base URL for API endpoints.

TOKEN_URL = 'https://www.qobuz.com/api.json/0.2/oauth/callback'

Token endpoint.

WEB_PLAYER_URL = 'https://play.qobuz.com'

Web Player URL.

albums: PrivateAlbumsAPI

Albums API endpoints for the private Qobuz API.

artists: PrivateArtistsAPI

Artists API endpoints for the private Qobuz API.

catalog: PrivateCatalogAPI

Catalog API endpoints for the private Qobuz API.

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.

dynamic: PrivateDynamicAPI

Dynamic Tracks API endpoints for the private Qobuz API.

favorites: PrivateFavoritesAPI

Favorites API endpoints for the private Qobuz API.

genres: PrivateGenresAPI

Genres API endpoints for the private Qobuz API.

classmethod get_tokens(*, auth_flows: str | Collection[str] | None = None, app_ids: str | Collection[str] | None = None, user_identifiers: str | Collection[str] | None = None) → list[dict[str, Any]] | None

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

Parameters:

auth_flowsstr or Collection[str]; keyword-only; optional

Authorization flows.

app_idsstr or Collection[str]; keyword-only; optional

Application IDs.

user_identifiersstr or Collection[str]; keyword-only; optional

Identifiers for the user accounts.

labels: PrivateLabelsAPI

Labels API endpoints for the private Qobuz API.

open() → None

Initialize a new HTTP client session.

playlists: PrivatePlaylistsAPI

Playlists API endpoints for the private Qobuz API.

purchases: PrivatePurchasesAPI

Purchases API endpoints for the private Qobuz API.

classmethod remove_tokens(*, auth_flows: str | Collection[str] | None = None, app_ids: str | Collection[str] | None = None, user_identifiers: str | Collection[str] | None = None) → None

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

Warning

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

Parameters:

auth_flowsstr or Collection[str]; keyword-only; optional

Authorization flows.

app_idsstr or Collection[str]; keyword-only; optional

Application IDs.

user_identifiersstr or Collection[str]; keyword-only; optional

Identifiers for the user accounts.

search: PrivateSearchAPI

Search-related endpoints for the private Qobuz API.

set_access_token(access_token: str) → None

Set or update the access token.

Note

For this API client, access tokens are user authentication tokens.

See also

set_user_auth_token() – Set or update the user authentication token.

Parameters:

access_tokenstr or None; positional-only

Access token.

set_auth_flow(auth_flow: str | None, /, *, app_id: str | None = None, app_secret: str | None = None, auth_key: str | None = None, user_identifier: str | None = None, redirect_uri: str | None = None, credential_handler: str | None = None, redirect_handler: str | None = None, open_browser: bool = False, store_tokens: bool = True, authenticate: bool = True, **kwargs: dict[str, Any]) → None

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.

• "ext_auth_code" – Qobuz authorization code flow.

• "password" – Qobuz Web Player login flow.

app_idstr; keyword-only; optional

Application ID. If not provided, it is loaded from the system environment variable PRIVATE_QOBUZ_API_APP_ID.

app_secretstr; keyword-only; optional

Application secret. If not provided, it is loaded from the system environment variable PRIVATE_QOBUZ_API_APP_SECRET.

auth_keystr; keyword-only; optional

Authorization key used in the Authorization Code flow. If not provided, it is loaded from the system environment variable PRIVATE_QOBUZ_API_AUTH_KEY.

user_identifierstr; keyword-only; optional

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

If specified, it is used with the client ID 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 client ID 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. Required for the Authorization Code flow.

credential_handlerstr; keyword-only; optional

Backend for handling user credentials during the Qobuz Web Player login flow. If not specified, the client first looks for credentials in kwargs and falls back to prompting for them in an echo-free terminal.

Valid values:

• "kwargs" – Use credentials provided directly via the username and password keyword arguments.

• "getpass" – Prompt for credentials in an echo-free terminal.

• "playwright" – Open the Qobuz Web Player login page in a Playwright Firefox browser.

redirect_handlerstr or None; keyword-only; optional

Backend for handling redirects during the Authorization Code 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 Authorization Code flow. If False, the URL is printed to the terminal.

store_tokensbool; keyword-only; default: True

Whether to enable the local token storage for this client. If True, existing user authentication tokens are retrieved when found in local storage, and newly acquired tokens and their metadata are stored for future retrieval. If False, the client neither retrieves nor stores tokens.

See also

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

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

authenticatebool; keyword-only; default: True

Whether to immediately initiate the authorization flow to acquire a user authentication token.

Important

Unless set_user_auth_token() is called immediately after, this should be left as True to ensure the client’s existing token is compatible with the new authorization flow.

**kwargsdict[str, Any]

Keyword arguments to pass to login().

set_cache_enabled(enable: bool, /) → None

Enable or disable the in-memory TTL cache for this client.

Parameters:

enablebool; positional-only

Whether to enable the cache.

set_user_auth_token(user_auth_token: str | None, /) → None

Set or update the user authentication token.

Parameters:

user_auth_tokenstr or None; positional-only

User authentication token.

tracks: PrivateTracksAPI

Tracks API endpoints for the private Qobuz API.

users: PrivateUsersAPI

Users API endpoints for the private Qobuz API.