Sphinx documentation and API cleanup

[mpd-sima.git] / sima / lib / meta.py

diff --git a/sima/lib/meta.py b/sima/lib/meta.py
index 44369a272e8cc51f1313d9b60519e0e59ac4589f..ebf5026a7fa95dfce5eb0adc4472a1f33cb7e5ab 100644 (file)
--- a/sima/lib/meta.py
+++ b/sima/lib/meta.py
@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# Copyright (c) 2013, 2014 Jack Kaliko <kaliko@azylum.org>
+# Copyright (c) 2013, 2014, 2015 Jack Kaliko <kaliko@azylum.org>
 #
 #  This file is part of sima
 #
@@ -21,10 +21,17 @@
 Defines some object to handle audio file metadata
 """
 
+try:
+    from collections.abc import Set # python >= 3.3
+except ImportError:
+    from collections import Set # python 3.2
 import logging
 import re
 
 UUID_RE = r'^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89aAbB][a-f0-9]{3}-[a-f0-9]{12}$'
+# The Track Object is collapsing multiple tags into a single string using this
+# separator. It is used then to split back the string to tags list.
+SEPARATOR = chr(0x1F)  # ASCII Unit Separator
 
 def is_uuid4(uuid):
     regexp = re.compile(UUID_RE, re.IGNORECASE)
@@ -52,11 +59,18 @@ def mbidfilter(func):
 
 class Meta:
     """Generic Class for Meta object
-    Meta(name=<str>[, mbid=UUID4])
+
+    Using generic kwargs in constructor for convenience but the actual signature is:
+
+    >>> Meta(name, mbid=None, **kwargs)
+
+    :param string name: set name attribute
+    :param string mbid: set MusicBrainz ID (optional)
     """
     use_mbid = True
 
     def __init__(self, **kwargs):
+        """Meta(name=<str>[, mbid=UUID4])"""
         self.__name = None #TODO: should be immutable
         self.__mbid = None
         self.__aliases = set()
@@ -68,10 +82,10 @@ class Meta:
         if 'mbid' in kwargs and kwargs.get('mbid'):
             try:
                 is_uuid4(kwargs.get('mbid'))
-                self.__mbid = kwargs.pop('mbid')
+                self.__mbid = kwargs.pop('mbid').lower()
             except WrongUUID4:
-                self.log.warning('Wrong mbid {}:{}'.format(self.__name,
-                                                         kwargs.get('mbid')))
+                self.log.warning('Wrong mbid %s:%s', self.__name,
+                                 kwargs.get('mbid'))
             # mbid immutable as hash rests on
         self.__dict__.update(**kwargs)
 
@@ -88,8 +102,7 @@ class Meta:
         """
         #if hasattr(other, 'mbid'):  # better isinstance?
         if isinstance(other, Meta) and self.mbid and other.mbid:
-            if self.mbid and other.mbid:
-                return self.mbid == other.mbid
+            return self.mbid == other.mbid
         elif isinstance(other, Meta):
             return bool(self.names & other.names)
         elif getattr(other, '__str__', None):
@@ -130,34 +143,70 @@ class Meta:
 
 
 class Album(Meta):
+    """Album object"""
 
     @property
     def album(self):
         return self.name
 
 class Artist(Meta):
+    """Artist object deriving from :class:`Meta`.
+
+    :param string name: Artist name, default ``None``
+    :param string mbid: Musicbrainz artist ID, defautl ``None``
+    :param string artist: Overrides "name" argument
+    :param string albumartist: Overrides "name" and "artist" argument
+    :param string musicbrainz_artistid: Overrides "mbid" argument
+    :param string musicbrainz_albumartistid: Overrides "musicbrainz_artistid" argument
+
+    :Example:
+
+    >>> trk = {'artist':'Art Name',
+    >>>        'albumartist': 'Alb Art Name',           # optional
+    >>>        'musicbrainz_artistid': '<UUID4>',       # optional
+    >>>        'musicbrainz_albumartistid': '<UUID4>',  # optional
+    >>>       }
+    >>> artobj0 = Artist(**trk)
+    >>> artobj1 = Artist(name='Tool')
+    """
 
     @mbidfilter
     def __init__(self, name=None, mbid=None, **kwargs):
-        """Artist object built from a mapping dict containing at least an
-        "artist" entry:
-            >>> trk = {'artist':'Art Name',
-            >>>        'albumartist': 'Alb Art Name',           # optional
-            >>>        'musicbrainz_artistid': '<UUID4>'    ,   # optional
-            >>>        'musicbrainz_albumartistid': '<UUID4>',  # optional
-            >>>       }
-            >>> artobj0 = Artist(**trk)
-            >>> artobj1 = Artist(name='Tool')
-        """
-        name = kwargs.get('artist', name)
-        mbid = kwargs.get('musicbrainz_artistid', mbid)
+        if kwargs.get('artist', False):
+            name = kwargs.get('artist').split(SEPARATOR)[0]
+        if kwargs.get('musicbrainz_artistid', False):
+            mbid = kwargs.get('musicbrainz_artistid').split(SEPARATOR)[0]
         if (kwargs.get('albumartist', False) and
                 kwargs.get('albumartist') != 'Various Artists'):
-            name = kwargs.get('albumartist').split(', ')[0]
+            name = kwargs.get('albumartist').split(SEPARATOR)[0]
         if (kwargs.get('musicbrainz_albumartistid', False) and
                 kwargs.get('musicbrainz_albumartistid') != '89ad4ac3-39f7-470e-963a-56509c546377'):
-            mbid = kwargs.get('musicbrainz_albumartistid').split(', ')[0]
+            mbid = kwargs.get('musicbrainz_albumartistid').split(SEPARATOR)[0]
         super().__init__(name=name, mbid=mbid)
 
+class MetaContainer(Set):
+
+    def __init__(self, iterable):
+        self.elements = lst = []
+        for value in iterable:
+            if value not in lst:
+                lst.append(value)
+            else:
+                for inlst in lst:
+                    if value == inlst:
+                        inlst.add_alias(value)
+
+    def __iter__(self):
+        return iter(self.elements)
+
+    def __contains__(self, value):
+        return value in self.elements
+
+    def __len__(self):
+        return len(self.elements)
+
+    def __repr__(self):
+        return repr(self.elements)
+
 # VIM MODLINE
 # vim: ai ts=4 sw=4 sts=4 expandtab