: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.PlaylistItem
calliope.musicbrainz.MusicbrainzContext
Functions
~~~~~~~~~
.. autoapisummary::
calliope.musicbrainz.annotate
calliope.musicbrainz.resolve_image
.. py:class:: PlaylistItem(data=None)
Bases: :py:obj:`dict`
Represents a single item in a Calliope playlist.
Initialize self. See help(type(self)) for accurate signature.
.. py:method:: id()
.. py:method:: __hash__()
Return hash(self).
.. py:method:: __str__()
Return str(self).
.. py:method:: add_warning(namespace, message)
.. py:class:: MusicbrainzContext(config)
Configuration for Musicbrainz APIs.
Keys used from ``config`` dict:
* ``musicbrainz.app``: App name
* ``musicbrainz.version``: API version
* ``musicbrainz.contact``: Contact URL
If unset, the defaults reference Calliope and API version 1.
.. 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.