Cleanup and docs.

modules/core/engine.py

@@ -51,7 +51,6 @@ class SoundSystem():
     channels = None
     scheduler = None
     monitoring = None
-    #error_data = None #FIXME Can be removed
     auramailer = None
     is_liquidsoap_running = False
     connection_attempts = 0
@@ -63,7 +62,6 @@ class SoundSystem():
     active_channel_type = None
     active_channel = None
     player_state = None
-    # active_entries = None
 
 
     def __init__(self, config):
@@ -253,6 +251,8 @@ class SoundSystem():
         Plays a new `Entry`. In case of a new schedule (or some intented, immediate transition),
         a clean channel is selected and transitions between old and new channel is performed.
 
+        This method expects that the entry is pre-loaded using `load(..)` before being played.
+
         Args:
             entry (PlaylistEntry):          The audio source to be played
             transition (TransitionType):    The type of transition to use e.g. fade-out.
@@ -285,6 +285,9 @@ class SoundSystem():
         """
         Event Handler which is called by soundsystem implementation (i.e. Liquidsoap) 
         when some entry is actually playing.
+
+        Args:
+            source (String):    The URI of the media source currently being played
         """
         self.logger.info(SimpleUtil.pink("Source '%s' started playing" % source))
 
@@ -473,22 +476,10 @@ class SoundSystem():
 
         Args:
             entry (Entry):  The entry to be pre-loaded
+
         Returns:
             (Boolean):  `True` if successfull
         """
-
-        # Hack to avoid Liquidsoap SSL Error "Connection failed: 
-        #   `SSL connection() error: error:1408F10B:SSL routines:ssl3_get_record:wrong version number`
-        # when passing HTTPS URLs without the port number.
-        # if EngineUtil.get_channel_type(entry.source) == ChannelType.HTTPS:
-
-        #     old_url = urlparse(entry.source)
-        #     new_url = ParseResult(scheme=old_url.scheme, netloc="{}:{}".format(old_url.hostname, 443),
-        #                     path=old_url.path, params=old_url.params, query=old_url.query, fragment=old_url.fragment)
-        #     self.logger.warn("Replacing entry.source HTTPS URL '%s' with '%s'" % (str(old_url.geturl()), str(new_url.geturl())))
-        #     entry.Source = new_url.geturl()
-
-
         self.stream_load(entry.channel, entry.source)
         time.sleep(1)
 
@@ -511,6 +502,13 @@ class SoundSystem():
         """
         Preloads the stream URL on the given channel. Note this method is blocking
         some serious amount of time; hence it's worth being called asynchroneously.
+
+        Args:
+            channel (Channel): The stream channel
+            uri (String):      The stream URL
+
+        Returns:
+            (Boolean):  `True` if successful
         """
         result = None
 
@@ -542,6 +540,13 @@ class SoundSystem():
         """
         Checks if the stream on the given channel is ready to play. Note this method is blocking
         some serious amount of time even when successfull; hence it's worth being called asynchroneously.
+
+        Args:
+            channel (Channel): The stream channel
+            uri (String):      The stream URL
+
+        Returns:
+            (Boolean):  `True` if successful
         """
         result = None
 
@@ -636,9 +641,11 @@ class SoundSystem():
         Adds an filesystem URI to the given `ChannelType.FILESYSTEM` channel.
 
         Args:
-            uri (String):   The URI of the file
+            channel (Channel): The channel to push the file to
+            uri (String):      The URI of the file
+
         Returns:
-            (Boolean):  `True` if successfull
+            (Boolean):  `True` if successful
         """
         if channel not in ChannelType.FILESYSTEM.channels:
             raise InvalidChannelException
@@ -658,7 +665,11 @@ class SoundSystem():
         Forwards the player of the given `ChannelType.FILESYSTEM` channel by (n) seconds.
 
         Args:
+            channel (Channel): The channel to push the file to
             seconds_to_seeks (Float):   The seconds to skip
+
+        Returns:
+            (String):   Liquidsoap response
         """
         if channel not in ChannelType.FILESYSTEM.channels:
             raise InvalidChannelException
@@ -674,6 +685,12 @@ class SoundSystem():
     def playlist_clear(self, channel):
         """
         Removes all tracks currently queued in the given `ChannelType.FILESYSTEM` channel.
+
+        Args:
+            channel (Channel): The channel to push the file to
+
+        Returns:
+            (String):   Liquidsoap response
         """
         if channel not in ChannelType.FILESYSTEM.channels:
             raise InvalidChannelException
@@ -696,6 +713,12 @@ class SoundSystem():
         """
         Performs a fade-in for the given `entry` to the `entry.volume` loudness
         at channel `entry.channel`.
+
+        Args:
+            entry (Entry):  The entry to fade
+        
+        Returns:
+            (Boolean):  `True` if successful
         """
         try:
             fade_in_time = float(self.config.get("fade_in_time"))
@@ -736,6 +759,12 @@ class SoundSystem():
     def fade_out(self, entry):
         """
         Performs a fade-out for the given `entry` at channel `entry.channel`.
+        
+        Args:
+            entry (Entry):  The entry to fade
+        
+        Returns:
+            (Boolean):  `True` if successful
         """
         try:
             fade_out_time = float(self.config.get("fade_out_time"))