doc: Update docstrings

diff --git a/sima/lib/meta.py b/sima/lib/meta.py
index 9d15c69dacef0594f9bdcd7ecd76ac75f04b6c77..725bfb00afde57b80d4caf39acb9e1968ca394ab 100644 (file)
--- a/sima/lib/meta.py
+++ b/sima/lib/meta.py
@@ -27,7 +27,7 @@ import logging
 import re
 
 UUID_RE = r'^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[89AB][a-f0-9]{3}-[a-f0-9]{12}$'
-# The Track Object is collapsing multiple tags into a single string using this
+#: 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
 

diff --git a/sima/lib/simadb.py b/sima/lib/simadb.py
index d08a6cca5edb46fac24fe60568989350d4f21b2b..75119aafbd94c0d473531db32f936b26be6cff05 100644 (file)
--- a/sima/lib/simadb.py
+++ b/sima/lib/simadb.py
@@ -19,8 +19,10 @@
 """SQlite database library
 """
 
+#: DB Version
 __DB_VERSION__ = 4
-__HIST_DURATION__ = int(30 * 24)  # in hours
+#: Default history duration for both request and purge in hours
+__HIST_DURATION__ = int(30 * 24)
 
 import sqlite3
 
@@ -198,7 +200,7 @@ class SimaDB:
         connection.close()
 
     def _remove_blocklist_id(self, blid, with_connection=None):
-        """Remove id"""
+        """Remove a blocklist id"""
         if with_connection:
             connection = with_connection
         else:
@@ -369,6 +371,7 @@ class SimaDB:
 
     def get_track(self, track, with_connection=None, add=True):
         """Get a track id from Tracks table, add if not existing,
+
         :param sima.lib.track.Track track: track to use
         :param bool add: add non existing track to database"""
         if not track.file:
@@ -438,8 +441,9 @@ class SimaDB:
 
     def add_history(self, track, date=None):
         """Record last play date of track (ie. not a real play history).
-        :param track sima.lib.track.Track: track to add to history
-        :param date datetime.datetime: UTC datetime object (use "datetime.now(timezone.utc)" is not set)"""
+
+        :param sima.lib.track.Track track: track to add to history
+        :param datetime.datetime date: UTC datetime object (use "datetime.now(timezone.utc)" is not set)"""
         if not date:
             date = datetime.now(timezone.utc)
         connection = self.get_database_connection()
@@ -456,8 +460,8 @@ class SimaDB:
 
     def purge_history(self, duration=__HIST_DURATION__):
         """Remove old entries in history
-        :param duration int: Purge history record older than duration in hours
-                            (defaults to __HIST_DURATION__)"""
+
+        :param int duration: Purge history record older than duration in hours"""
         connection = self.get_database_connection()
         connection.execute("DELETE FROM history WHERE last_play"
                            " < datetime('now', '-%i hours')" % duration)
@@ -468,6 +472,7 @@ class SimaDB:
     def fetch_albums_history(self, needle=None, duration=__HIST_DURATION__):
         """
         :param sima.lib.meta.Artist needle: When specified, returns albums history for this artist.
+        :param int duration: How long ago to fetch history from (in hours)
         """
         date = datetime.now(timezone.utc) - timedelta(hours=duration)
         connection = self.get_database_connection()
@@ -510,8 +515,10 @@ class SimaDB:
 
     def fetch_artists_history(self, needle=None, duration=__HIST_DURATION__):
         """Returns a list of Artist objects
-        :param sima.lib.meta.Artist|sima.lib.meta.MetaContainer needle: When specified, returns history for this artist, it's actually testing the artist presence in history.
+
         :param sima.lib.meta.MetaContainer needle: When specified, returns history for these artists only
+        :param int duration: How long ago to fetch history from (in hours)
+        :type needle: sima.lib.meta.Artist or sima.lib.meta.MetaContainer
         """
         date = datetime.now(timezone.utc) - timedelta(hours=duration)
         connection = self.get_database_connection()
@@ -545,6 +552,11 @@ class SimaDB:
         return hist
 
     def fetch_genres_history(self, duration=__HIST_DURATION__, limit=20):
+        """Returns genre history
+
+        :param int duration: How long ago to fetch history from (in hours)
+        :param int limit: number of genre to fetch
+        """
         date = datetime.now(timezone.utc) - timedelta(hours=duration)
         connection = self.get_database_connection()
         rows = connection.execute("""
@@ -567,8 +579,9 @@ class SimaDB:
 
     def fetch_history(self, artist=None, duration=__HIST_DURATION__):
         """Fetches tracks history, more recent first
+
         :param sima.lib.meta.Artist artist: limit history to this artist
-        :param int duration: How long ago to fetch history from
+        :param int duration: How long ago to fetch history from (in hours)
         """
         date = datetime.now(timezone.utc) - timedelta(hours=duration)
         connection = self.get_database_connection()
@@ -609,6 +622,7 @@ class SimaDB:
 
     def get_bl_track(self, track, with_connection=None, add=True):
         """Add a track to blocklist
+
         :param sima.lib.track.Track track: Track object to add to blocklist
         :param sqlite3.Connection with_connection: sqlite3.Connection to reuse, else create a new one
         :param bool add: Default is to add a new record, set to False to fetch associated record"""
@@ -636,6 +650,7 @@ class SimaDB:
 
     def get_bl_album(self, album, with_connection=None, add=True):
         """Add an album to blocklist
+
         :param sima.lib.meta.Album: Album object to add to blocklist
         :param sqlite3.Connection with_connection: sqlite3.Connection to reuse, else create a new one
         :param bool add: Default is to add a new record, set to False to fetch associated record"""
@@ -663,6 +678,7 @@ class SimaDB:
 
     def get_bl_artist(self, artist, with_connection=None, add=True):
         """Add an artist to blocklist
+
         :param sima.lib.meta.Artist: Artist object to add to blocklist
         :param sqlite3.Connection with_connection: sqlite3.Connection to reuse, else create a new one
         :param bool add: Default is to add a new record, set to False to fetch associated record"""

diff --git a/sima/lib/track.py b/sima/lib/track.py
index 503008b6b1a5a844a58b4538c404421dba394589..a1a452af07fd8f1b955a63ca3e10f9d30e5f5bc8 100644 (file)
--- a/sima/lib/track.py
+++ b/sima/lib/track.py
@@ -25,6 +25,7 @@ import time
 
 from .meta import Artist, Album, SEPARATOR
 
+
 class Track:
     """
     Track object.
@@ -52,7 +53,7 @@ class Track:
                                  'genre', 'albumartist',
                                  'musicbrainz_artistid',
                                  'musicbrainz_albumartistid']
-        #  have tags been collapsed?
+        # Which tags have been collapsed?
         self.collapsed_tags = list()
         # Needed for multiple tags which returns a list instead of a string
         self._collapse_tags()
@@ -80,9 +81,9 @@ class Track:
 
     def __str__(self):
         return '{artist} - {album} - {title} ({length})'.format(
-                length=self.length,
-                **self.__dict__
-                )
+            length=self.length,
+            **self.__dict__
+        )
 
     def __int__(self):
         return int(self.duration)
@@ -128,8 +129,9 @@ class Track:
     def genres(self):
         """Fetches Genres for the track
         Multivalue genre are dealt with:
-          * when genre tag is multivalued
-          * when single tag uses coma or semi-colon separator
+
+        * when genre tag is multivalued
+        * when single tag uses coma or semi-colon separator
         """
         if 'genre' not in self.__dict__:
             return []