Improved listener docs and docstrings (#484)

Author: hardbyte

can/io/csv.py

@@ -19,6 +19,7 @@
 from can.listener import Listener
 from .generic import BaseIOHandler
 
+
 class CSVWriter(BaseIOHandler, Listener):
     """Writes a comma separated text file with a line for
     each message. Includes a header line.
@@ -37,13 +38,13 @@ class CSVWriter(BaseIOHandler, Listener):
     data             base64 encoded          WzQyLCA5XQ==
     ================ ======================= ===============
 
-    Each line is terminated with a platform specific line seperator.
+    Each line is terminated with a platform specific line separator.
     """
 
     def __init__(self, file, append=False):
         """
-        :param file: a path-like object or as file-like object to write to
-                     If this is a file-like object, is has to opened in text
+        :param file: a path-like object or a file-like object to write to.
+                     If this is a file-like object, is has to open in text
                      write mode, not binary write mode.
         :param bool append: if set to `True` messages are appended to
                             the file and no header line is written, else

can/io/logger.py

@@ -32,6 +32,8 @@ class Logger(BaseIOHandler, Listener):
       * .log :class:`can.CanutilsLogWriter`
       * other: :class:`can.Printer`
 
+    The log files may be incomplete until `stop()` is called due to buffering.
+
     .. note::
         This class itself is just a dispatcher, and any positional an keyword
         arguments are passed on to the returned instance.

can/io/sqlite.py

@@ -228,7 +228,7 @@ def _db_writer_thread(self):
 
     def stop(self):
         """Stops the reader an writes all remaining messages to the database. Thus, this
-        might take a while an block.
+        might take a while and block.
         """
         BufferedReader.stop(self)
         self._stop_running_event.set()

can/listener.py

@@ -35,6 +35,8 @@ class Listener(object):
         # or
         listener.on_message_received(msg)
 
+        # Important to ensure all outputs are flushed
+        listener.stop()
     """
 
     __metaclass__ = ABCMeta
@@ -59,7 +61,10 @@ def on_error(self, exc):
 
     def stop(self):
         """
-        Override to cleanup any open resources.
+        Stop handling new messages, carry out any final tasks to ensure
+        data is persisted and cleanup any open resources.
+
+        Concrete implementations override.
         """
 
 

can/notifier.py

@@ -18,8 +18,15 @@
 class Notifier(object):
 
     def __init__(self, bus, listeners, timeout=1.0, loop=None):
-        """Manages the distribution of **Messages** from a given bus/buses to a
-        list of listeners.
+        """Manages the distribution of :class:`can.Message` instances to listeners.
+
+        Supports multiple busses and listeners.
+
+        .. Note::
+
+            Remember to call `stop()` after all messages are received as
+            many listeners carry out flush operations to persist data.
+
 
         :param can.BusABC bus: A :ref:`bus` or a list of buses to listen to.
         :param list listeners: An iterable of :class:`~can.Listener`

doc/asyncio.rst

@@ -4,8 +4,9 @@ Asyncio support
 ===============
 
 The :mod:`asyncio` module built into Python 3.4 and later can be used to write
-asynchronos code in a single thread. This library supports receiving messages
-asynchronosly in an event loop using the :class:`can.Notifier` class.
+asynchronous code in a single thread. This library supports receiving messages
+asynchronously in an event loop using the :class:`can.Notifier` class.
+
 There will still be one thread per CAN bus but the user application will execute
 entirely in the event loop, allowing simpler concurrency without worrying about
 threading issues. Interfaces that have a valid file descriptor will however be

doc/listeners.rst

@@ -24,7 +24,7 @@ and are listed below.
 Some of them allow messages to be written to files, and the corresponding file
 readers are also documented here.
 
-.. warning ::
+.. note ::
 
     Please note that writing and the reading a message might not always yield a
     completely unchanged message again, since some properties are not (yet)