:py:mod:`calliope.musicbrainz`
==============================
.. py:module:: calliope.musicbrainz
.. autoapi-nested-parse::
Access data from `Musicbrainz `_.
See also: :program:`cpe musicbrainz` command.
This module wraps the `musicbrainzngs `_ library.
Authentication
--------------
Musicbrainz access requires that you set a User Agent string. A default is set
by the :obj:`MusicbrainzContext` object which can be overridden using its
config.
Caching
-------
Caching of data is handled using the :mod:`calliope.cache` module.
Submodules
----------
.. toctree::
:titlesonly:
:maxdepth: 1
includes/index.rst
resolve/index.rst
schema/index.rst
Package Contents
----------------
Classes
~~~~~~~
.. autoapisummary::
calliope.musicbrainz.MusicbrainzContext
Functions
~~~~~~~~~
.. autoapisummary::
calliope.musicbrainz.annotate
calliope.musicbrainz.resolve_image
Attributes
~~~~~~~~~~
.. autoapisummary::
calliope.musicbrainz.PlaylistItem
.. py:data:: PlaylistItem
.. py:class:: MusicbrainzContext(app=None, version=None, contact=None)
Configuration for Musicbrainz APIs.
:param \* ``app``: App name
:param \* ``version``: API version
:param \* ``contact``: Contact URL
These are passed as the user agent to the musicbrainz API.
.. py:function:: annotate(context, playlist, include_patterns, select_fun=None, update=False)
Annotate each item in a playlist with metadata from Musicbrainz.
The ``include_patterns`` parameter controls what subqueries are run,
via the MusicBrainz `include` query parameter.
This parameter takes keys like `areas` or `url-rels` which cause more data
to be fetched. MusicBrainz has different resource types, while in Calliope
everything is a :class:`playlist item `, so within
Calliope we specify keys as ``typename.key``. These are examples of
different include key fullnames:
* ``artist.areas``
* ``artist.url-rels``
* ``recording.url-rels``
In ``include_patterns`` you can pass literal key names, and you can use
``*`` as a wildcard. For example, you can get all ``url-rels`` information
with ``*.url-rels``, and all info about an artist with ``artist.*``.
For reference documentation of the `include` parameter, see:
.
Use :func:`calliope.includes.all_include_key_fullnames` to retrieve the
full list of include keys.
.. py:function:: resolve_image(context, playlist, max_size = 250)
Resolve a cover image using the Cover Art API.
See https://musicbrainz.org/doc/Cover_Art_Archive/API for more info.