References

Requests

class mbzero.mbzrequest.MbzAddToCollection(user_agent: str, collection_mbid: str, entity_type: str, entities_mbid: List[str], client: str | None = None)

Class for adding entities to a user collection

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

Format the request and send

Parameters:

• credentials – Credentials to use for the request

• opts – Special options to modify the request

class mbzero.mbzrequest.MbzRemoveFromCollection(user_agent: str, collection_mbid: str, entity_type: str, entities_mbid: List[str], client: str | None = None)

Class for removing entities from a user collection

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

Format the request and send

Parameters:

• credentials – Credentials to use for the request

• opts – Special options to modify the request

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

Base class for requests

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

Send a DELETE 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

• 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

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, 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

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

Send a PUT 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

• 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

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, opts: _OptsDict | None = None)

Format the submission and send

Parameters:

• credentials – Credentials to use for the request

• opts – Special options to modify the request

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.MbzBadRequestError

Error raised when the request does not have valid and sufficient authentication for accessing the resource

exception mbzero.mbzerror.MbzError

Base class for all exceptions related to MusicBrainz.

exception mbzero.mbzerror.MbzNotFoundError

Error raised when an entity is not found

exception mbzero.mbzerror.MbzOauth2Error

OAuth2 failure

exception mbzero.mbzerror.MbzUnauthorizedError

Error raised when the request does not have valid and sufficient authentication for accessing the resource

exception mbzero.mbzerror.MbzWebServiceError

Error related to MusicBrainz API requests.