Metadata aggregation API

Release:0.8.0
class flacmanager.MetadataError(message, context_hint=None, cause=None)[source]

Bases: flacmanager.FLACManagerError

The type of exception raised when metadata operations fail.

Parameters:
  • message (str) – error message for logging or display
  • context_hint – describes the error context
  • cause (Exception) – the exception that caused this error

The optional context_hint is not part of the message, and may take any type or form. Exception handlers that catch FLACManagerError may choose to do something with the context hint, or may ignore it.

The optional cause is the (caught) exception that caused this FLACManagerError.

class flacmanager.MetadataCollector(toc)[source]

Bases: object

Base class for collecting album and track metadata.

Parameters:toc (flacmanager.TOC) – a disc’s table of contents
reset()[source]

Initialize all collection fields to default (empty).

collect()[source]

Fetch metadata from a service.

class flacmanager.GracenoteCDDBMetadataCollector(toc)[source]

Bases: flacmanager._HTTPMetadataCollector

A Gracenote CDDB client that populates album and track metadata choices for a disc identified by its offsets.

Parameters:toc (flacmanager.TOC) – a disc’s table of contents
API_HOST_TEMPLATE = 'c%s.web.cddbp.net'

Host name format string for Gracenote.

API_PATH = '/webapi/xml/1.0/'

Request path for Gracenote service calls.

REGISTER_XML = '<QUERIES><QUERY CMD="REGISTER"><CLIENT>%s</CLIENT></QUERY></QUERIES>'

Request body for a Gracenote User ID.

ALBUM_TOC_XML = '<QUERIES><AUTH><CLIENT>%s</CLIENT><USER>%s</USER></AUTH><LANG>eng</LANG><COUNTRY>usa</COUNTRY><QUERY CMD="ALBUM_TOC"><TOC><OFFSETS>%s</OFFSETS></TOC></QUERY></QUERIES>'

Request body for Gracenote Album summary metadata.

ALBUM_FETCH_XML = '<QUERIES><AUTH><CLIENT>%s</CLIENT><USER>%s</USER></AUTH><LANG>eng</LANG><COUNTRY>usa</COUNTRY><QUERY CMD="ALBUM_FETCH"><GN_ID>%s</GN_ID><OPTION><PARAMETER>SELECT_EXTENDED</PARAMETER><VALUE>COVER</VALUE></OPTION><OPTION><PARAMETER>COVER_SIZE</PARAMETER><VALUE>MEDIUM,LARGE,SMALL,THUMBNAIL,XLARGE</VALUE></OPTION><OPTION><PARAMETER>SELECT_DETAIL</PARAMETER><VALUE>GENRE:3LEVEL</VALUE></OPTION></QUERY></QUERIES>'

Request body for Gracenote Album and Track detail metadata.

collect()[source]

Populate all Gracenote album metadata choices.

class flacmanager.MusicBrainzMetadataCollector(toc)[source]

Bases: flacmanager._HTTPMetadataCollector

A MusicBrainz client that populates album and track metadata choices for a disc identified by its MusicBrainz ID.

Parameters:toc (flacmanager.TOC) – a disc’s table of contents
API_HOST = 'musicbrainz.org'

Host name for all MusicBrainz service calls.

API_PATH_PREFIX = '/ws/2'

Request path prefix for all MusicBrainz service calls.

COVERART_URL_TEMPLATE = 'http://coverartarchive.org/release/%s/front-500'

URL format string for cover image requests.

USER_AGENT_TEMPLATE = 'FLACManager/0.8.0 Python/3.5.2 ( %s )'

HTTP User-Agent format string for MusicBrainz requests.

NAMESPACES = {'mb': 'http://musicbrainz.org/ns/mmd-2.0#'}

XML namespace mapping for parsing MusicBrainz responses.

classmethod initialize_libdiscid()[source]

Load the libdiscid shared library.

classmethod calculate_disc_id(toc)[source]

Return the MusicBrainz Disc ID for the disc toc.

Parameters:toc (flacmanager.TOC) – a disc’s table of contents
Returns:a MusicBrainz Disc ID for toc
Return type:str
collect()[source]

Populate all MusicBrainz album metadata choices.

class flacmanager.MetadataPersistence(toc)[source]

Bases: flacmanager.MetadataCollector

A pseudo-client that populates persisted album and track metadata choices for a disc.

Parameters:toc (flacmanager.TOC) – a disc’s table of contents
reset()[source]

Initialize all collection fields to default (empty).

collect()[source]

Populate metadata choices from persisted data.

store(metadata)[source]

Persist a disc’s metadata field values.

Parameters:metadata (dict) – the finalized metadata for a disc

Persisting the metadata field values allows for easy error recovery in the event that ripping/encoding fails (i.e. the user will not need to re-choose and/or re-enter values).

Note

The presence of persisted metadata for a disc does not prevent metadata aggregation. Metadata is still aggregated, but any persisted values take precedence.

Warning

Only the first value (i.e. the entered or selected value) for each metadata field is persisted. This value is assumed to be the preferred/intended value for the field.

class flacmanager.MetadataAggregator(toc)[source]

Bases: flacmanager.MetadataCollector, threading.Thread

The thread that aggregates metadata from multiple sources.

Parameters:toc (flacmanager.TOC) – a disc’s table of contents
run()[source]

Run the collect() method in another thread.

collect()[source]

Collect metadata from all music databases.

Note

Persisted metadata, if it exists, is also collected by this method.

aggregate()[source]

Combine metadata from all music databases into a single mapping.

Note

If persisted metadata was collected, the persisted value for each metadata field will take precedence over any other collected values.