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 2adac1376b3b972f29acb1ac48df645910448a5c..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
 #
@@ -29,6 +29,9 @@ 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)
@@ -56,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()
@@ -133,33 +143,45 @@ 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).split(', ')[0]
-        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):