Small improvements to lib

- Fix mkdocs warnings
- Fix Python SyntaxWarning
- Add static exceptions for colour sensor
- Log warning when colour chip not present

Author: G3zz

README.md

@@ -60,6 +60,7 @@ Contributors
 * `Serge Schneider`_
 * `Dave Jones`_
 * `Tyler Laws`_
+* `George Boukeas`_
 
 Open Source
 ===========

docs/api.md

@@ -819,7 +819,7 @@ Note that, in the current implementation, the four values accessed through the `
 
 In sensors, the term "gain" can be understood as being synonymous to _sensitivity_. A higher gain setting means the output values will be greater for the same input. 
 
-There are four possible gain values for the colour sensor: `1`, `4`, `16` and `60`, with the default value being `1`. You can get or set the sensor gain through the `gain` property of the `ColourSensor` object. An attempt to set the gain to a value that is not valid will result in a `ValueError` exception being raised.
+There are four possible gain values for the colour sensor: `1`, `4`, `16` and `60`, with the default value being `1`. You can get or set the sensor gain through the `gain` property of the `ColourSensor` object. An attempt to set the gain to a value that is not valid will result in an `InvalidGainError` exception being raised.
 
 ```python
 from sense_hat import SenseHAT
@@ -846,7 +846,7 @@ When there is very little ambient light and the RGBC values are low, it makes se
 
 You can specify the number of _integration cycles_ required to generate a new set of sensor readings. Each integration cycle is 2.4 milliseconds long, so the number of integration cycles determines the _minimum_ amount of time required between consecutive readings.
 
-You can set the number of integration cycles to any integer between `1` and `256`, through the `integration_cycles` property of the `ColourSensor` object. The default value is `1`. An attempt to set the number of integration cycles to a value that is not valid will result in a `ValueError` or `TypeError` exception being raised.
+You can set the number of integration cycles to any integer between `1` and `256`, through the `integration_cycles` property of the `ColourSensor` object. The default value is `1`. An attempt to set the number of integration cycles to a value that is not valid will result in a `InvalidIntegrationCyclesError` or `TypeError` exception being raised.
 
 ```python
 from sense_hat import SenseHAT
@@ -895,4 +895,10 @@ print(f"Maximum raw sensor reading: {sense.colour.max_raw}")
 sleep(sense.colour.integration_time + 0.1)  # try omitting this
 print(f"Current raw sensor readings: {sense.colour.colour_raw}")
 print(f"Scaled values: {sense.colour.colour}")
-```
+```
+
+## Exceptions
+
+Custom Sense HAT exceptions are statically defined in the `sense_hat.exceptions` module. 
+The exceptions relate to problems encountered while initialising the colour chip or due to setting invalid parameters. 
+Each exception includes a message describing the issue encountered, and is subclassed from the base class `SenseHatException`. 

examples/README.md docs/examples/README.md

@@ -5,8 +5,9 @@ repo_url: https://github.com/RPi-Distro/python-sense-hat
 site_description: Python module to control the Raspberry Pi Sense HAT used in the Astro Pi mission
 site_author: David Honess
 site_dir: pythonhosted
-google_analytics: ['UA-46270871-5', 'pythonhosted.org/sense-hat']
-pages:
+#google_analytics: ['UA-46270871-5', 'pythonhosted.org/sense-hat']
+nav:
 - 'Home': 'index.md'
 - 'API Reference': 'api.md'
+- 'Examples': 'examples/README.md'
 - 'Changelog': 'changelog.md'

examples/colour_cycle.py docs/examples/colour_cycle.py

@@ -4,8 +4,8 @@
 """
 
 from time import sleep
-
-_error_str = "Failed to initialise TCS34725 colour sensor."
+from .exceptions import ColourSensorInitialisationError, InvalidGainError, \
+    InvalidIntegrationCyclesError
 
 
 class HardwareInterface:
@@ -84,31 +84,31 @@ def get_raw(self):
 
     def get_red(self):
         """
-        Return a the raw value of the R (red) channel.
+        Return the raw value of the R (red) channel.
         The maximum for this raw value depends on the number of
         integration cycles and can be computed using `max_value`.
         """
         raise NotImplementedError
 
     def get_green(self):
         """
-        Return a the raw value of the G (green) channel.
+        Return the raw value of the G (green) channel.
         The maximum for this raw value depends on the number of
         integration cycles and can be computed using `max_value`.
         """
         raise NotImplementedError
 
     def get_blue(self):
         """
-        Return a the raw value of the B (blue) channel.
+        Return the raw value of the B (blue) channel.
         The maximum for this raw value depends on the number of
         integration cycles and can be computed using `max_value`.
         """
         raise NotImplementedError
 
     def get_clear(self):
         """
-        Return a the raw value of the C (clear light) channel.
+        Return the raw value of the C (clear light) channel.
         The maximum for this raw value depends on the number of
         integration cycles and can be computed using `max_value`.
         """
@@ -176,19 +176,16 @@ def __init__(self):
         try:
             self.bus = smbus.SMBus(self.BUS)
         except Exception as e:
-            explanation = " (I2C is not enabled)" if not self.i2c_enabled() else ""
-            raise RuntimeError(f'{_error_str}{explanation}') from e
-        
+            explanation = "(I2C is not enabled)" if not self.i2c_enabled() else ""
+            raise ColourSensorInitialisationError(explanation=explanation) from e
         try:
             id = self._read(self.ID)
         except Exception as e:
-            explanation = " (sensor not present)"
-            raise RuntimeError(f'{_error_str}{explanation}') from e
-
+            explanation = "(sensor not present)"
+            raise ColourSensorInitialisationError(explanation=explanation) from e
         if id != 0x44:
             explanation = f" (different device id detected: {id})"
-            raise RuntimeError(f'{_error_str}{explanation}')
-
+            raise ColourSensorInitialisationError(explanation=explanation) from e
     @staticmethod
     def i2c_enabled():
         """Returns True if I2C is enabled or False otherwise."""
@@ -314,7 +311,7 @@ def gain(self, gain):
         if gain in self.interface.GAIN_VALUES:
             self.interface.set_gain(gain)
         else:
-            raise ValueError(f'Cannot set gain to {gain}. Values: {self.interface.GAIN_VALUES}')
+            raise InvalidGainError(gain=gain, values=self.interface.GAIN_VALUES)
 
     @property
     def integration_cycles(self):
@@ -326,7 +323,7 @@ def integration_cycles(self, integration_cycles):
             self.interface.set_integration_cycles(integration_cycles)
             sleep(self.interface.CLOCK_STEP)
         else:
-            raise ValueError(f'Cannot set integration cycles to {integration_cycles} (1-256)')
+            raise InvalidIntegrationCyclesError(integration_cycles=integration_cycles)
 
     @property
     def integration_time(self):

examples/compass.py docs/examples/compass.py

@@ -0,0 +1,22 @@
+class SenseHatException(Exception):
+    """
+    The base exception class for all SenseHat exceptions.
+    """
+    fmt = 'An unspecified error occurred'
+
+    def __init__(self, **kwargs):
+        msg = self.fmt.format(**kwargs)
+        Exception.__init__(self, msg)
+        self.kwargs = kwargs
+
+
+class ColourSensorInitialisationError(SenseHatException):
+    fmt = "Failed to initialise TCS34725 colour sensor. {explanation}"
+
+
+class InvalidGainError(SenseHatException):
+    fmt = "Cannot set gain to '{gain}'. Values: {values}"
+
+
+class InvalidIntegrationCyclesError(SenseHatException):
+    fmt = "Cannot set integration cycles to {integration_cycles} (1-256)"

examples/evdev_joystick.py docs/examples/evdev_joystick.py

@@ -1,4 +1,5 @@
 #!/usr/bin/python
+import logging
 import struct
 import os
 import sys
@@ -16,6 +17,7 @@
 
 from .stick import SenseStick
 from .colour import ColourSensor
+from .exceptions import ColourSensorInitialisationError
 
 class SenseHat(object):
 
@@ -94,7 +96,8 @@ def __init__(
         # initialise the TCS34725 colour sensor (if possible)
         try:
             self._colour = ColourSensor()
-        except:
+        except Exception as e:
+            logging.warning(e)
             pass
 
     ####
@@ -206,7 +209,9 @@ def colour(self):
         try:
             return self._colour
         except AttributeError as e:
-            raise RuntimeError('This Sense HAT does not have a color sensor') from e
+            raise ColourSensorInitialisationError(
+                explanation="This Sense HAT" +
+                            " does not have a color sensor") from e
 
     color = colour
 
@@ -531,7 +536,7 @@ def gamma(self):
 
     @gamma.setter
     def gamma(self, buffer):
-        if len(buffer) is not 32:
+        if len(buffer) != 32:
             raise ValueError('Gamma array must be of length 32')
 
         if not all(b <= 31 for b in buffer):