MusicBrainzAPI#

class beetsplug._utils.musicbrainz.MusicBrainzAPI[source]#

Bases: RequestHandler

High-level interface to the MusicBrainz WS/2 API.

Responsibilities:

  • Configure the API host and request rate from application configuration.

  • Offer helpers to fetch common entity types and to run searches.

  • Normalize MusicBrainz responses so relation lists are grouped by target type for easier downstream consumption.

Documentation: https://musicbrainz.org/doc/MusicBrainz_API

__init__() → None#

Public methods summary

browse_recordings(**kwargs)

Browse recordings related to the given entities.

browse_release_groups(**kwargs)

Browse release groups related to the given entities.

create_session()

Create a new HTTP session instance.

delete(*args, **kwargs)

Perform HTTP DELETE request with automatic error handling.

format_search_term(field, term)

Format a search term for the MusicBrainz API.

get(*args, **kwargs)

Perform HTTP GET request with automatic error handling.

get_json(*args, **kwargs)

Fetch and parse JSON data from an HTTP endpoint.

get_recording(id_, **kwargs)

Retrieve a recording by its MusicBrainz ID.

get_release(id_, **kwargs)

Retrieve a release by its MusicBrainz ID.

get_work(id_, **kwargs)

Retrieve a work by its MusicBrainz ID.

handle_http_error()

Convert standard HTTP errors to beets-specific exceptions.

put(*args, **kwargs)

Perform HTTP PUT request with automatic error handling.

request(*args, **kwargs)

Ensure all requests specify JSON response format by default.

search(entity, filters, **kwargs)

Search for MusicBrainz entities matching the given filters.

status_to_error(code)

Map HTTP status codes to beets-specific exception types.

Methods definition

create_session() → LimiterTimeoutSession[source]#

Create a new HTTP session instance.

Can be overridden by subclasses to provide custom session types.

request(*args, **kwargs) → Response[source]#

Ensure all requests specify JSON response format by default.

static format_search_term(field: str, term: str) → str[source]#

Format a search term for the MusicBrainz API.

See https://lucene.apache.org/core/4_3_0/queryparser/org/apache/lucene/queryparser/classic/package-summary.html

search(entity: Entity, filters: dict[str, str], **kwargs: Unpack[SearchKwargs]) → list[IDResponse][source]#

Search for MusicBrainz entities matching the given filters.

  • Query is constructed by combining the provided filters using AND logic

  • Each filter key-value pair is formatted as 'key:"value"' unless - 'key' is empty, in which case only the value is used, '"value"' - 'value' is empty, in which case the filter is ignored

  • Values are lowercased and stripped of whitespace.

get_release(id_: str, **kwargs: Unpack[LookupKwargs]) → JSONDict[source]#

Retrieve a release by its MusicBrainz ID.

get_recording(id_: str, **kwargs: Unpack[LookupKwargs]) → JSONDict[source]#

Retrieve a recording by its MusicBrainz ID.

get_work(id_: str, **kwargs: Unpack[LookupKwargs]) → JSONDict[source]#

Retrieve a work by its MusicBrainz ID.

browse_recordings(**kwargs: Unpack[BrowseRecordingsKwargs]) → list[JSONDict][source]#

Browse recordings related to the given entities.

At least one of artist, collection, release, or work must be provided.

browse_release_groups(**kwargs: Unpack[BrowseReleaseGroupsKwargs]) → list[JSONDict][source]#

Browse release groups related to the given entities.

At least one of artist, collection, or release must be provided. Optionally filter by type (e.g., "album|ep").

delete(*args, **kwargs) → Response#

Perform HTTP DELETE request with automatic error handling.

explicit_http_errors: ClassVar[list[type[BeetsHTTPError]]] = [<class 'beetsplug._utils.requests.HTTPNotFoundError'>]#

List of custom exceptions to be raised for specific status codes.

get(*args, **kwargs) → Response#

Perform HTTP GET request with automatic error handling.

get_json(*args, **kwargs)#

Fetch and parse JSON data from an HTTP endpoint.

handle_http_error() → Iterator[None]#

Convert standard HTTP errors to beets-specific exceptions.

Wraps operations that may raise HTTPError, automatically translating recognized status codes into their corresponding beets exception types. Unrecognized errors are re-raised unchanged.

put(*args, **kwargs) → Response#

Perform HTTP PUT request with automatic error handling.

status_to_error(code: int) → type[HTTPError] | None#

Map HTTP status codes to beets-specific exception types.

Searches the configured explicit HTTP errors for a matching status code. Returns None if no specific error type is registered for the given code.