References

Requests

class mbzero.mbzrequest.MbzRequest(user_agent: str, client: str | None = None)

Base class for requests

get(request: str, credentials: MbzCredentials | None = None, headers: dict[str, Any] | None = None, payload: dict[str, Any] | None = None, opts: _OptsDict | None = None)

Send a GET request

Parameters:

  • request – The path from the API root URL to the ressource to request. This must include the leading ‘/’

  • credentials – Credentials to use for the request. If not set, the request not be authenticated

  • headers – Additional request headers to add to the request

  • payload – Additional request parameters to add to the request

  • opts – Special options to modify the request

post(request: str, data: _Data, data_type: Literal['xml'], credentials: MbzCredentials | None, headers: dict[str, Any] | None = None, payload: dict[str, Any] | None = None, opts: _OptsDict | None = None)

Send a POST request

Parameters:

  • request – The path from the API root URL to the ressource to request. This must include the leading ‘/’

  • data – The content to submit

  • data_type – The content type (only “xml” is supported)

  • credentials – Credentials to use for the request

  • headers – Additional request headers to add to the request

  • payload – Additional request parameters to add to the request

  • opts – Special options to modify the request

set_url(url: str)

Change the API root URL

Parameters:

url – New API root URL

class mbzero.mbzrequest.MbzRequestBrowse(user_agent: str, entity_type: str, bw_entity_type: str, mbid: str, includes: list[str] = [])

Class for browse requests

send(credentials: MbzCredentials | None = None, opts: _OptsDict | None = None)

Format the request and send

Parameters:

  • credentials – Credentials to use for the request. If not set, the request not be authenticated

  • opts – Special options to modify the request

exception mbzero.mbzrequest.MbzRequestError(message=None, cause=None)

Request failed

class mbzero.mbzrequest.MbzRequestLookup(user_agent: str, entity_type: str, mbid: str, includes: list[str] = [])

Class for lookup requests

send(credentials: MbzCredentials | None = None, opts: _OptsDict | None = None)

Format the request and send

Parameters:

  • credentials – Credentials to use for the request. If not set, the request not be authenticated

  • opts – Special options to modify the request

class mbzero.mbzrequest.MbzRequestSearch(user_agent: str, entity_type: str, query: str)

Class for search requests

send(credentials: MbzCredentials | None = None, opts: _OptsDict | None = None)

Format the request and send

Parameters:

  • credentials – Credentials to use for the request. If not set, the request not be authenticated

  • opts – Special options to modify the request

class mbzero.mbzrequest.MbzSubmission(user_agent: str, entity_type: str, data: _Data, data_type: Literal['xml'], client: str | None = None)

Class for submissions

send(credentials: MbzCredentials | None = None, opts: _OptsDict | None = None)

Format the submission and send

Parameters:

  • credentials – Credentials to use for the request

  • opts – Special options to modify the request

exception mbzero.mbzrequest.MbzSubmissionError(message=None, cause=None)

Submission failed

Authentication

class mbzero.mbzauth.MbzCredentials(oauth2_url: str | None = None)

Class for Musicbrainz authentication.

auth() → Tuple[str | None, str | None]

Get username/password

auth_set(name: str | None, passwd: str | None)

Username/password authentication

has_auth() → bool

Returns true if name/passwd credentials have been set

has_oauth2() → bool

Returns true if OAuth2 has been set

oauth2_confirm(response_code: str, client_secret: str, url: str | None = None)

Confirm the authorization with the response code.

Parameters:

  • response_code – the response code given by the authentication URL

  • client_secret – client application secret

  • url – optional token endpoint (defaults to musicbrainz)

Returns:

the access token

oauth2_init(client_id: str, url: str | None = None, redirect_uri: str = 'urn:ietf:wg:oauth:2.0:oob', scope: list[str] = []) → str

Initialize the creation of tokens

Parameters:

  • client_id – client application ID

  • url – optional authentification endpoint(defaults to musicbrainz)

  • redirect_uri – optional redirect URI (defaults to the redirect URI defined in the Musicbrainz documentation)

  • scope – optional Musicbrainz scope

Returns:

an authorization URL to visit

oauth2_new(token: str | None, refresh_token: str | None = None, client_id: str | None = None, client_secret: str | None = None, redirect_uri: str = 'urn:ietf:wg:oauth:2.0:oob', scope: list[str] = [])

Create a session with existing tokens

Parameters:

  • token – access token to use for authentication

  • refresh_token – refresh token to use for refreshing

  • client_id – optional client application ID

  • client_secret – optional client application secret

  • redirect_uri – optional redirect URI (defaults to the redirect URI defined in the Musicbrainz documentation)

  • scope – optional Musicbrainz scope

oauth2_refresh(refresh_token=None, url: str | None = None)

Refresh an access token.

Parameters:

  • refresh_token – optional refresh token used to refresh the access token

  • url – optional token endpoint (defaults to musicbrainz)

Returns:

the new access token

oauth2_revoke(token=None, url: str | None = None)

Revoke a token pair

Parameters:

  • token – optional token used to refresh the access token. If not provided, the current session’s access_token is revoked.

  • url – optional revocation endpoint (defaults to musicbrainz)

oauth2_set_url(url)

Change the default OAuth2 endpoint

Cover Art Archive

class mbzero.caarequest.CaaRequest(user_agent, entity_type, mbid, item_request=None)
head(request, opts=None)

Send a request

Param:

request: the request to send to the server

Parameters:

url – Optional API endpoint (defaults is musicbrainz.org API)

send(head=False, opts=None)

Format the request and send

Parameters:

  • head – use a HEAD request instead of GET

  • opts – Optional dictionary of parameters. Valid option is url, extra_headers, extra_payload

Errors

exception mbzero.mbzerror.MbzError

Base class for all exceptions related to MusicBrainz.

exception mbzero.mbzerror.MbzOauth2Error(message=None, cause=None)

OAuth2 failure

exception mbzero.mbzerror.MbzWebServiceError(message=None, cause=None)

Error related to MusicBrainz API requests.