refactor & comment player

can/io/player.py

@@ -8,7 +8,7 @@
 
 from __future__ import absolute_import
 
-import time
+from time import time, sleep
 import logging
 
 from .generic import BaseIOHandler
@@ -73,8 +73,8 @@ class MessageSync(object):
     def __init__(self, messages, timestamps=True, gap=0.0001, skip=60):
         """Creates an new **MessageSync** instance.
 
-        :param messages: An iterable of :class:`can.Message` instances.
-        :param bool timestamps: Use the messages' timestamps.
+        :param Iterable[can.Message] messages: An iterable of :class:`can.Message` instances.
+        :param bool timestamps: Use the messages' timestamps. If False, uses the *gap* parameter as the time between messages.
         :param float gap: Minimum time between sent messages in seconds
         :param float skip: Skip periods of inactivity greater than this (in seconds).
         """
@@ -84,26 +84,25 @@ def __init__(self, messages, timestamps=True, gap=0.0001, skip=60):
         self.skip = skip
 
     def __iter__(self):
-        log.debug("Iterating over messages at real speed")
-
-        playback_start_time = time.time()
+        playback_start_time = time()
         recorded_start_time = None
 
-        for m in self.raw_messages:
-            if recorded_start_time is None:
-                recorded_start_time = m.timestamp
+        for message in self.raw_messages:
 
+            # Work out the correct wait time
             if self.timestamps:
-                # Work out the correct wait time
-                now = time.time()
+                if recorded_start_time is None:
+                    recorded_start_time = message.timestamp
+
+                now = time()
                 current_offset = now - playback_start_time
-                recorded_offset_from_start = m.timestamp - recorded_start_time
-                remaining_gap = recorded_offset_from_start - current_offset
+                recorded_offset_from_start = message.timestamp - recorded_start_time
+                remaining_gap = max(0.0, recorded_offset_from_start - current_offset)
 
                 sleep_period = max(self.gap, min(self.skip, remaining_gap))
             else:
                 sleep_period = self.gap
 
-            time.sleep(sleep_period)
+            sleep(sleep_period)
 
-            yield m
+            yield message