Work on gpiozero#87

Implement a test suite, including Travis-CI integration

Author: waveform80

.travis.yml

@@ -0,0 +1,11 @@
+language: python
+python:
+    - "3.5"
+    - "3.4"
+    - "3.3"
+    - "3.2"
+    - "2.7"
+    - "pypy"
+    - "pypy3"
+install: "pip install -e .[test]"
+script: make test

Makefile

@@ -98,7 +98,7 @@ develop: tags
 	@# These have to be done separately to avoid a cockup...
 	$(PIP) install -U setuptools
 	$(PIP) install -U pip
-	$(PIP) install -e .
+	$(PIP) install -e .[doc,test]
 
 test:
 	$(COVERAGE) run -m $(PYTEST) tests -v

coverage.cfg

@@ -0,0 +1,20 @@
+[run]
+branch = True
+include = gpiozero/*
+;omit = */bar.py,*/baz.py
+
+[report]
+ignore_errors = True
+show_missing = True
+exclude_lines =
+    pragma: no cover
+    def __repr__
+    if self\.debug
+    raise AssertionError
+    raise NotImplementedError
+    if 0:
+    if __name__ == .__main__.:
+
+[html]
+directory = coverage
+

docs/api_exc.rst

@@ -0,0 +1,80 @@
+==========
+Exceptions
+==========
+
+.. currentmodule:: gpiozero
+
+The following exceptions are defined by GPIO Zero. Please note that multiple
+inheritance is heavily used in the exception hierarchy to make testing for
+exceptions easier. For example, to capture any exception generated by GPIO
+Zero's code::
+
+    from gpiozero import *
+
+    led = PWMLED(17)
+    try:
+        led.value = 2
+    except GPIOZeroError:
+        print('A GPIO Zero error occurred')
+
+Since all GPIO Zero's exceptions descend from :exc:`GPIOZeroError`, this will
+work. However, certain specific errors have multiple parents. For example, in
+the case that an out of range value is passed to :attr:`OutputDevice.value` you
+would expect a :exc:`ValueError` to be raised. In fact, a
+:exc:`OutputDeviceBadValue` error will be raised. However, note that this
+descends from both :exc:`GPIOZeroError` (indirectly) and from :exc:`ValueError`
+so you can still do::
+
+    from gpiozero import *
+
+    led = PWMLED(17)
+    try:
+        led.value = 2
+    except ValueError:
+        print('Bad value specified')
+
+
+.. autoexception:: GPIOZeroError
+
+.. autoexception:: CompositeDeviceError
+
+.. autoexception:: GPIODeviceError
+
+.. autoexception:: GPIODeviceClosed
+
+.. autoexception:: GPIOPinInUse
+
+.. autoexception:: GPIOPinMissing
+
+.. autoexception:: GPIOBadQueueLen
+
+.. autoexception:: InputDeviceError
+
+.. autoexception:: OutputDeviceError
+
+.. autoexception:: OutputDeviceBadValue
+
+.. autoexception:: PinError
+
+.. autoexception:: PinFixedFunction
+
+.. autoexception:: PinInvalidFunction
+
+.. autoexception:: PinInvalidState
+
+.. autoexception:: PinInvalidPull
+
+.. autoexception:: PinInvalidEdges
+
+.. autoexception:: PinSetInput
+
+.. autoexception:: PinFixedPull
+
+.. autoexception:: PinEdgeDetectUnsupported
+
+.. autoexception:: PinPWMError
+
+.. autoexception:: PinPWMUnsupported
+
+.. autoexception:: PinPWMFixedValue
+

docs/index.rst

@@ -13,5 +13,6 @@ Table of Contents
     api_boards
     api_generic
     api_pins
+    api_exc
     changelog
     license

gpiozero/__init__.py

@@ -5,7 +5,20 @@
     division,
 )
 
-from .pins.exc import (
+from .pins import (
+    Pin,
+)
+from .exc import (
+    GPIOZeroError,
+    CompositeDeviceError,
+    GPIODeviceError,
+    GPIODeviceClosed,
+    GPIOPinInUse,
+    GPIOPinMissing,
+    GPIOBadQueueLen,
+    InputDeviceError,
+    OutputDeviceError,
+    OutputDeviceBadValue,
     PinError,
     PinFixedFunction,
     PinInvalidFunction,
@@ -19,15 +32,6 @@
     PinPWMUnsupported,
     PinPWMFixedValue,
 )
-from .pins import (
-    Pin,
-)
-from .exc import (
-    GPIODeviceClosed,
-    GPIODeviceError,
-    InputDeviceError,
-    OutputDeviceError,
-)
 from .devices import (
     GPIODevice,
     CompositeDevice,

gpiozero/compat.py

@@ -0,0 +1,27 @@
+from __future__ import (
+    unicode_literals,
+    absolute_import,
+    print_function,
+    division,
+    )
+str = type('')
+
+import cmath
+
+
+# Back-ported from python 3.5; see
+# github.com/PythonCHB/close_pep/blob/master/is_close.py for original
+# implementation
+def isclose(a, b, rel_tol=1e-9, abs_tol=0.0):
+    if rel_tol < 0.0 or abs_tol < 0.0:
+        raise ValueError('error tolerances must be non-negative')
+    if a == b: # fast-path for exact equality
+        return True
+    if cmath.isinf(a) or cmath.isinf(b):
+        return False
+    diff = abs(b - a)
+    return (
+        (diff <= abs(rel_tol * b)) or
+        (diff <= abs(rel_tol * a)) or
+        (diff <= abs_tol)
+        )

gpiozero/devices.py

@@ -13,7 +13,12 @@
 from collections import deque
 from types import FunctionType
 
-from .exc import GPIODeviceError, GPIODeviceClosed, InputDeviceError
+from .exc import (
+    GPIOPinMissing,
+    GPIOPinInUse,
+    GPIODeviceClosed,
+    GPIOBadQueueLen,
+    )
 
 # Get a pin implementation to use as the default; we prefer RPi.GPIO's here
 # as it supports PWM, and all Pi revisions. If no third-party libraries are
@@ -203,7 +208,8 @@ class GPIODevice(ValuesMixin, GPIOBase):
 
     :param int pin:
         The GPIO pin (in BCM numbering) that the device is connected to. If
-        this is ``None`` a :exc:`GPIODeviceError` will be raised.
+        this is ``None``, :exc:`GPIOPinMissing` will be raised. If the pin is
+        already in use by another device, :exc:`GPIOPinInUse` will be raised.
     """
     def __init__(self, pin=None):
         super(GPIODevice, self).__init__()
@@ -212,12 +218,12 @@ def __init__(self, pin=None):
         # value of pin until we've verified that it isn't already allocated
         self._pin = None
         if pin is None:
-            raise GPIODeviceError('No pin given')
+            raise GPIOPinMissing('No pin given')
         if isinstance(pin, int):
             pin = DefaultPin(pin)
         with _PINS_LOCK:
             if pin in _PINS:
-                raise GPIODeviceError(
+                raise GPIOPinInUse(
                     'pin %r is already in use by another gpiozero object' % pin
                 )
             _PINS.add(pin)
@@ -342,7 +348,7 @@ def __init__(self, parent, queue_len=5, sample_wait=0.0, partial=False):
         assert isinstance(parent, GPIODevice)
         super(GPIOQueue, self).__init__(target=self.fill)
         if queue_len < 1:
-            raise InputDeviceError('queue_len must be at least one')
+            raise GPIOBadQueueLen('queue_len must be at least one')
         self.queue = deque(maxlen=queue_len)
         self.partial = partial
         self.sample_wait = sample_wait

gpiozero/exc.py

@@ -4,16 +4,72 @@
     absolute_import,
     division,
 )
+str = type('')
 
-class GPIODeviceError(Exception):
-    pass
+
+class GPIOZeroError(Exception):
+    "Base class for all exceptions in GPIO Zero"
+
+class CompositeDeviceError(GPIOZeroError):
+    "Base class for errors specific to the CompositeDevice hierarchy"
+
+class GPIODeviceError(GPIOZeroError):
+    "Base class for errors specific to the GPIODevice hierarchy"
 
 class GPIODeviceClosed(GPIODeviceError):
-    pass
+    "Error raised when an operation is attempted on a closed device"
+
+class GPIOPinInUse(GPIODeviceError):
+    "Error raised when attempting to use a pin already in use by another device"
+
+class GPIOPinMissing(GPIODeviceError, ValueError):
+    "Error raised when a pin number is not specified"
+
+class GPIOBadQueueLen(GPIODeviceError, ValueError):
+    "Error raised when non-positive queue length is specified"
 
 class InputDeviceError(GPIODeviceError):
-    pass
+    "Base class for errors specific to the InputDevice hierarchy"
 
 class OutputDeviceError(GPIODeviceError):
-    pass
+    "Base class for errors specified to the OutputDevice hierarchy"
+
+class OutputDeviceBadValue(OutputDeviceError, ValueError):
+    "Error raised when ``value`` is set to an invalid value"
+
+class PinError(GPIOZeroError):
+    "Base class for errors related to pin implementations"
+
+class PinFixedFunction(PinError, AttributeError):
+    "Error raised when attempting to change the function of a fixed type pin"
+
+class PinInvalidFunction(PinError, ValueError):
+    "Error raised when attempting to change the function of a pin to an invalid value"
+
+class PinInvalidState(PinError, ValueError):
+    "Error raised when attempting to assign an invalid state to a pin"
+
+class PinInvalidPull(PinError, ValueError):
+    "Error raised when attempting to assign an invalid pull-up to a pin"
+
+class PinInvalidEdges(PinError, ValueError):
+    "Error raised when attempting to assign an invalid edge detection to a pin"
+
+class PinSetInput(PinError, AttributeError):
+    "Error raised when attempting to set a read-only pin"
+
+class PinFixedPull(PinError, AttributeError):
+    "Error raised when attempting to set the pull of a pin with fixed pull-up"
+
+class PinEdgeDetectUnsupported(PinError, AttributeError):
+    "Error raised when attempting to use edge detection on unsupported pins"
+
+class PinPWMError(PinError):
+    "Base class for errors related to PWM implementations"
+
+class PinPWMUnsupported(PinPWMError, AttributeError):
+    "Error raised when attempting to activate PWM on unsupported pins"
+
+class PinPWMFixedValue(PinPWMError, AttributeError):
+    "Error raised when attempting to initialize PWM on an input pin"
 

gpiozero/output_devices.py

@@ -10,7 +10,7 @@
 from threading import Lock
 from itertools import repeat, cycle, chain
 
-from .exc import OutputDeviceError, GPIODeviceError, GPIODeviceClosed
+from .exc import OutputDeviceBadValue, GPIOPinMissing, GPIODeviceClosed
 from .devices import GPIODevice, GPIOThread, CompositeDevice, SourceMixin
 
 
@@ -24,7 +24,7 @@ class OutputDevice(SourceMixin, GPIODevice):
 
     :param int pin:
         The GPIO pin (in BCM numbering) that the device is connected to. If
-        this is ``None`` a :exc:`GPIODeviceError` will be raised.
+        this is ``None`` a :exc:`GPIOPinMissing` will be raised.
 
     :param bool active_high:
         If ``True`` (the default), the :meth:`on` method will set the GPIO to
@@ -54,7 +54,7 @@ def _write(self, value):
             value = not value
         try:
             self.pin.state = bool(value)
-        except ValueError:
+        except AttributeError:
             self._check_open()
             raise
 
@@ -269,7 +269,7 @@ class PWMOutputDevice(OutputDevice):
     def __init__(self, pin=None, active_high=True, initial_value=0, frequency=100):
         self._blink_thread = None
         if not 0 <= initial_value <= 1:
-            raise OutputDeviceError("initial_value must be between 0 and 1")
+            raise OutputDeviceBadValue("initial_value must be between 0 and 1")
         super(PWMOutputDevice, self).__init__(pin, active_high)
         try:
             # XXX need a way of setting these together
@@ -299,7 +299,7 @@ def _write(self, value):
         if not self.active_high:
             value = 1 - value
         if not 0 <= value <= 1:
-            raise OutputDeviceError("PWM value must be between 0 and 1")
+            raise OutputDeviceBadValue("PWM value must be between 0 and 1")
         try:
             self.pin.state = value
         except AttributeError:
@@ -505,7 +505,7 @@ def __init__(
         self._leds = ()
         self._blink_thread = None
         if not all([red, green, blue]):
-            raise OutputDeviceError('red, green, and blue pins must be provided')
+            raise GPIOPinMissing('red, green, and blue pins must be provided')
         super(RGBLED, self).__init__()
         self._leds = tuple(PWMLED(pin, active_high) for pin in (red, green, blue))
         self.value = initial_value
@@ -680,7 +680,7 @@ class Motor(SourceMixin, CompositeDevice):
     """
     def __init__(self, forward=None, backward=None):
         if not all([forward, backward]):
-            raise OutputDeviceError(
+            raise GPIOPinMissing(
                 'forward and backward pins must be provided'
             )
         super(Motor, self).__init__()
@@ -722,7 +722,7 @@ def value(self):
     @value.setter
     def value(self, value):
         if not -1 <= value <= 1:
-            raise OutputDeviceError("Motor value must be between -1 and 1")
+            raise OutputDeviceBadValue("Motor value must be between -1 and 1")
         if value > 0:
             self.forward(value)
         elif value < 0: