Refactoring & documentation.

docs/source/conf.py

@@ -67,9 +67,9 @@ def __getattr__(cls, name):
 # built documents.
 #
 # The short X.Y version.
-version = '1.3.8'
+version = '1.3.9'
 # The full version, including alpha/beta/rc tags.
-release = '1.3.8'
+release = '1.3.9'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/source/soar.update.rst

@@ -0,0 +1,6 @@
+soar\.update
+=========================
+
+.. automodule:: soar.update
+    :members:
+    :show-inheritance:

soar/__init__.py

@@ -15,13 +15,15 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #
 # soar/__init__.py
-""" Soar (Snakes on a Robot) v1.3.8
+""" Soar (Snakes on a Robot) v1.3.9
 
 An extensible Python framework for both simulating and interacting with robots.
 
 Copyright (C) 2017 Andrew Antonitis. Licensed under the LGPLv3.
 """
-__version__ = '1.3.8'
+
+
+__version__ = '1.3.9'
 blerb = 'Soar (Snakes on a Robot) v' + __version__ + ': A Python robotics framework.\n' \
                                                      'https://github.com/arantonitis/soar\n\n' \
                                                      'Copyright (C) 2017 Andrew Antonitis. Licensed under the LGPLv3.'

soar/common.py

@@ -2,6 +2,7 @@
 # Copyright (C) 2017 Andrew Antonitis. Licensed under the LGPLv3.
 #
 # soar/common.py
+# TODO: Move these into __init__?
 """ Soar common constants.
 
 Contains named constants for sending messages to the client and determining the type of a controller.

soar/errors.py

@@ -3,6 +3,7 @@
 #
 # soar/errors.py
 """ Soar error classes. """
+# TODO: In 2.0, move these into __init__
 import sys
 
 

soar/gui/plot_window.py

@@ -17,11 +17,11 @@
 
 Based on code written by Adam Hartz, August 1st 2012.
 """
-# Tk backends, used for plotting in various modes (GUI or headless)
 import matplotlib
 import platform
 if platform.system() == 'Darwin':  # Fix for Soar crashing on macOS
     matplotlib.use('TkAgg')
+# Tk backends, used for plotting in various modes (GUI or headless)
 from matplotlib.backends.backend_tkagg import FigureCanvasTkAgg, FigureCanvasAgg, NavigationToolbar2TkAgg
 import matplotlib.pyplot as plt
 from tkinter import Tk, Toplevel, TOP, BOTH

soar/gui/soar_ui.py

@@ -316,6 +316,7 @@ def future(self, func, *args, after_idle=False, **kwargs):
             return self.after(0, lambda: func(*args, **kwargs))
 
     def synchronous_future(self, func, *args, after_idle=False, **kwargs):
+        # TODO: This breaks if called from the main thread, fix that?
         """ Executes a function in the GUI event loop, waiting either for its return, or for a Tk exception. """
         e = ThreadEvent()
         q = Queue(maxsize=1)

soar/hooks.py

@@ -31,7 +31,7 @@ def tkinter_hook(widget, linked=True):  # TODO: Deprecate or merge with tkinter_
     return widget
 
 
-def tkinter_wrap(widget, linked=True):
+def tkinter_wrap(widget, linked=True):  # TODO: Move code here in 2.0
     """ Make Soar's UI aware of a Tk widget, and wrap its callables so that they run on the main thread.
 
     This function is redefined by the client before a brain is ever loaded.

soar/robot/arcos.py

@@ -366,7 +366,7 @@ def connect(self, forced_ports=None):
         Raises:
             `ARCOSError`: If unable to connect to any available ports.
         """
-        if forced_ports is not None:
+        if forced_ports:
             ports = forced_ports
         else:
             ports = [port_info.device for port_info in comports()]  # Try every available port until we find a robot
@@ -397,7 +397,7 @@ def connect_with_baudrate(baudrate):
                     self.start()
                     return
         # If we have tried every available port without success, raise an exception
-        raise ARCOSError('Unable to sync with an ARCOS server--is the robot connected and its port accessible?')
+        raise ARCOSError('Unable to sync with an ARCOS server. Is the robot connected and its port accessible?')
 
     def disconnect(self):
         """ Stop the ARCOS server and close the connection if running. """
@@ -492,10 +492,8 @@ def update(self):
     def start(self):
         """ Open the ARCOS servers, enable the sonars, and start the pulse & update coroutines. """
         self.send_packet(OPEN)
-        pulse = Thread(target=self.pulse, daemon=True)
-        pulse.start()
-        update = Thread(target=self.update, daemon=True)
-        update.start()
+        Thread(target=self.pulse, daemon=True).start()
+        Thread(target=self.update, daemon=True).start()
         self.wait_or_timeout(self.standard_event, 5.0, 'Failed to receive SIPs from the robot')
         for i in range(5):  # Try multiple times to enable the sonars
             if self.standard['FLAGS'] & 0x2 != 0x2:

soar/robot/names.py

@@ -7,6 +7,13 @@
 from math import sqrt, ceil
 
 
+names = ['Ariel', 'Bailey', 'Casey', 'Dallas', 'Eli', 'Frankie', 'Gabriel', 'Harley', 'Jayden', 'Kai', 'Lee', 'Mickey',
+         'Neo', 'Ocean', 'Parris', 'Quinn', 'Reagan', 'Shiloh', 'Taylor', 'Udo', 'Val', 'Winter', 'Xue', 'Yoshi',
+         'Zephyr', 'Narin', 'Ollie', 'Dakota', 'Marlie', 'Brooke', 'Shannon', 'Nour', 'Reese', 'Storm', 'Sydney',
+         'Omari', 'Ola', 'Ryley', 'Esmai', 'Leslie', 'Finley', 'Hildred', 'Lynn', 'Shelby', 'Sequoia', 'Tashi',
+         'Dominique', 'Garnet', 'Gray', 'Cameron']
+
+
 def is_prime(n):
     if n < 4:
         return False if n == 1 else True
@@ -15,12 +22,6 @@ def is_prime(n):
             return False
     return True
 
-names = ['Ariel', 'Bailey', 'Casey', 'Dallas', 'Eli', 'Frankie', 'Gabriel', 'Harley', 'Jayden', 'Kai', 'Lee', 'Mickey',
-         'Neo', 'Ocean', 'Parris', 'Quinn', 'Reagan', 'Shiloh', 'Taylor', 'Udo', 'Val', 'Winter', 'Xue', 'Yoshi',
-         'Zephyr', 'Narin', 'Ollie', 'Dakota', 'Marlie', 'Brooke', 'Shannon', 'Nour', 'Reese', 'Storm', 'Sydney',
-         'Omari', 'Ola', 'Ryley', 'Esmai', 'Leslie', 'Finley', 'Hildred', 'Lynn', 'Shelby', 'Sequoia', 'Tashi',
-         'Dominique', 'Garnet', 'Gray', 'Cameron']
-
 
 def name_from_sernum(sernum):
     # Pull out only the digits from the serial number

soar/update.py

@@ -2,17 +2,27 @@
 # Copyright (C) 2017 Andrew Antonitis. Licensed under the LGPLv3.
 #
 # soar/update.py
+""" Function to check for updates on PyPI, and return a message for the user. """
 import re
-from math import inf
 from urllib import request
 
 from soar import __version__
 
 
+PYPI_URL = 'https://pypi.python.org/pypi/Soar'  # This may change in the future
+INF = float('inf')  # Use older infinity so as not to require Python 3.5
+
+
 def get_update_message():
+    """ Fetch the HTML of Soar's PyPI page, check for a newer version, and return a notification string.
+
+    Returns:
+        str: An empty string if no update is available, a notification message if one is, and an error
+    message if something went wrong.
+    """
     # Try and determine if a newer version of Soar is available, and notify the user
     try:
-        r = request.urlopen('https://pypi.python.org/pypi/Soar', data=None)
+        r = request.urlopen(PYPI_URL, data=None)
         assert(r.getcode() == 200)
         body = str(r.read(), encoding='utf-8')
         start = body.find('Soar')
@@ -22,7 +32,7 @@ def get_update_message():
 
         def version_parse(x):  # Parse version increment strings into integers
             if x is None:
-                return inf  # Non-development releases have an effective development release value of infinity
+                return INF  # Non-development releases have an effective development release value of infinity
             else:
                 return int(x)
 
@@ -37,13 +47,13 @@ def version_parse(x):  # Parse version increment strings into integers
                 need_update = False
                 break
         if need_update:
-            if pypi_version[3] != inf:
+            if pypi_version[3] != INF:
                 pypi_version[3] = 'dev' + str(pypi_version[3])
             else:
                 pypi_version = pypi_version[:-1]  # Slice off the irrelevant infinite dev version
             version_string = '.'.join([str(x) for x in pypi_version])
             return 'A newer version of Soar is available: v' + version_string + '\nPlease update your installation.'
         else:
             return ''
-    except Exception:  # If anything at all goes wrong, silently fail
-        return ''
+    except Exception:  # If anything at all goes wrong, notify the user
+        return 'Unable to check for updates.'