Add docstrings, close #26

gpiozero/boards.py

@@ -6,6 +6,9 @@ from time import sleep
 
 
 class LEDBoard(object):
+    """
+    A Generic LED Board or collecfion of LEDs.
+    """
     def __init__(self, leds):
         self._leds = tuple(LED(led) for led in leds)
 
@@ -14,22 +17,53 @@ class LEDBoard(object):
         return self._leds
 
     def on(self):
+        """
+        Turn all the LEDs on.
+        """
         for led in self._leds:
             led.on()
 
     def off(self):
+        """
+        Turn all the LEDs off.
+        """
         for led in self._leds:
             led.off()
 
     def toggle(self):
+        """
+        Toggle all the LEDs. For each LED, if it's on, turn it off; if it's
+        off, turn it on.
+        """
         for led in self._leds:
             led.toggle()
 
     def blink(self, on_time=1, off_time=1):
+        """
+        Make all the LEDs turn on and off repeatedly in the background.
+
+        on_time: 1
+            Number of seconds to be on
+
+        off_time: 1
+            Number of seconds to be off
+        """
         for led in self._leds:
             led.blink(on_time, off_time)
 
     def flash(self, on_time=1, off_time=1, n=1):
+        """
+        Turn all the LEDs on and off a given number of times.
+
+        on_time: 1
+            Number of seconds on
+
+        off_time: 1
+            Number of seconds off
+
+        n: 1
+            Number of iterations
+        """
         for i in range(n):
             self.on()
             sleep(on_time)
@@ -39,12 +73,27 @@ class LEDBoard(object):
 
 
 class PiLiter(LEDBoard):
+    """
+    Ciseco Pi-LITEr: strip of 8 very bright LEDs.
+    """
     def __init__(self):
         leds = (4, 17, 27, 18, 22, 23, 24, 25)
         super(PiLiter, self).__init__(leds)
 
 
 class TrafficLights(LEDBoard):
+    """
+    Generic Traffic Lights set.
+
+    red: None
+        Red LED pin
+
+    amber: None
+        Amber LED pin
+
+    green: None
+        Green LED pin
+    """
     def __init__(self, red=None, amber=None, green=None):
         if not all([red, amber, green]):
             raise GPIODeviceError('Red, Amber and Green pins must be provided')
@@ -56,12 +105,19 @@ class TrafficLights(LEDBoard):
 
 
 class PiTraffic(TrafficLights):
+    """
+    Low Voltage Labs PI-TRAFFIC: vertical traffic lights board on pins 9, 10
+    and 11.
+    """
     def __init__(self):
         red, amber, green = (9, 10, 11)
         super(PiTraffic, self).__init__(red, amber, green)
 
 
 class FishDish(TrafficLights):
+    """
+    Pi Supply FishDish: horizontal traffic light LEDs, a button and a buzzer.
+    """
     def __init__(self):
         red, amber, green = (9, 22, 4)
         super(FishDish, self).__init__(red, amber, green)
@@ -74,27 +130,59 @@ class FishDish(TrafficLights):
         return self._all
 
     def on(self):
+        """
+        Turn all the board's components on.
+        """
         for thing in self._all:
             thing.on()
 
     def off(self):
+        """
+        Turn all the board's components off.
+        """
         for thing in self._all:
             thing.off()
 
     def toggle(self):
+        """
+        Toggle all the board's components. For each component, if it's on, turn
+        it off; if it's off, turn it on.
+        """
         for thing in self._all:
             thing.toggle()
 
     def lights_on(self):
+        """
+        Turn all the board's LEDs on.
+        """
         super(FishDish, self).on()
 
     def lights_off(self):
+        """
+        Turn all the board's LEDs off.
+        """
         super(FishDish, self).off()
 
     def toggle_lights(self):
+        """
+        Toggle all the board's LEDs. For each LED, if it's on, turn
+        it off; if it's off, turn it on.
+        """
         super(FishDish, self).toggle()
 
     def flash_lights(self, on_time=1, off_time=1, n=1):
+        """
+        Turn all the LEDs on and off a given number of times.
+
+        on_time: 1
+            Number of seconds on
+
+        off_time: 1
+            Number of seconds off
+
+        n: 1
+            Number of iterations
+        """
         for i in range(n):
             [led.on() for led in self.leds]
             sleep(on_time)
@@ -104,6 +192,9 @@ class FishDish(TrafficLights):
 
 
 class TrafficHat(FishDish):
+    """
+    Ryanteck Traffic HAT: horizontal traffic light LEDs, a button and a buzzer.
+    """
     def __init__(self):
         red, amber, green = (22, 23, 24)
         super(FishDish, self).__init__(red, amber, green)

gpiozero/devices.py

@@ -10,6 +10,9 @@ class GPIODeviceError(Exception):
 
 
 class GPIODevice(object):
+    """
+    Generic GPIO Device.
+    """
     def __init__(self, pin=None):
         if pin is None:
             raise GPIODeviceError('No GPIO pin number given')

gpiozero/input_devices.py

@@ -22,6 +22,9 @@ class InputDeviceError(GPIODeviceError):
 
 
 class InputDevice(GPIODevice):
+    """
+    Generic GPIO Input Device.
+    """
     def __init__(self, pin=None, pull_up=False):
         super(InputDevice, self).__init__(pin)
         self._pull_up = pull_up
@@ -42,6 +45,9 @@ class InputDevice(GPIODevice):
 
 
 class WaitableInputDevice(InputDevice):
+    """
+    A time-dependent Generic Input Device.
+    """
     def __init__(self, pin=None, pull_up=False):
         super(WaitableInputDevice, self).__init__(pin, pull_up)
         self._active_event = Event()
@@ -51,9 +57,23 @@ class WaitableInputDevice(InputDevice):
         self._last_state = None
 
     def wait_for_active(self, timeout=None):
+        """
+        Halt the program until the device is activated, or the timeout is
+        reached.
+
+        timeout: None
+            Number of seconds (?) to wait before proceeding
+        """
         return self._active_event.wait(timeout)
 
     def wait_for_inactive(self, timeout=None):
+        """
+        Halt the program until the device is inactivated, or the timeout is
+        reached.
+
+        timeout: None
+            Number of seconds (?) to wait before proceeding
+        """
         return self._inactive_event.wait(timeout)
 
     def _get_when_activated(self):
@@ -122,6 +142,9 @@ class WaitableInputDevice(InputDevice):
 
 
 class DigitalInputDevice(WaitableInputDevice):
+    """
+    A Generic Digital Input Device.
+    """
     def __init__(self, pin=None, pull_up=False, bouncetime=None):
         super(DigitalInputDevice, self).__init__(pin, pull_up)
         # Yes, that's really the default bouncetime in RPi.GPIO...
@@ -140,6 +163,9 @@ class DigitalInputDevice(WaitableInputDevice):
 
 
 class SmoothedInputDevice(WaitableInputDevice):
+    """
+    A Generic Digital Input Device with background polling.
+    """
     def __init__(
             self, pin=None, pull_up=False, threshold=0.5,
             queue_len=5, sample_wait=0.0, partial=False):
@@ -184,6 +210,9 @@ class SmoothedInputDevice(WaitableInputDevice):
 
 
 class Button(DigitalInputDevice):
+    """
+    A physical push button or switch.
+    """
     def __init__(self, pin=None, pull_up=True, bouncetime=None):
         super(Button, self).__init__(pin, pull_up, bouncetime)
 
@@ -195,6 +224,9 @@ class Button(DigitalInputDevice):
 
 
 class MotionSensor(SmoothedInputDevice):
+    """
+    A PIR (Passive Infra-Red) motion sensor.
+    """
     def __init__(
             self, pin=None, queue_len=5, sample_rate=10, threshold=0.5,
             partial=False):
@@ -214,6 +246,9 @@ class MotionSensor(SmoothedInputDevice):
 
 
 class LightSensor(SmoothedInputDevice):
+    """
+    An LDR (Light Dependent Resistor) Light Sensor.
+    """
     def __init__(
             self, pin=None, queue_len=5, charge_time_limit=0.01,
             threshold=0.1, partial=False):
@@ -260,6 +295,9 @@ class LightSensor(SmoothedInputDevice):
 
 
 class TemperatureSensor(W1ThermSensor):
+    """
+    A Digital Temperature Sensor.
+    """
     @property
     def value(self):
         return self.get_temperature()

gpiozero/output_devices.py

@@ -11,38 +11,96 @@ class OutputDeviceError(GPIODeviceError):
 
 
 class OutputDevice(GPIODevice):
+    """
+    Generic GPIO Output Device (on/off).
+    """
     def __init__(self, pin=None):
         super(OutputDevice, self).__init__(pin)
         GPIO.setup(pin, GPIO.OUT)
 
     def on(self):
+        """
+        Turns the device on.
+        """
         GPIO.output(self.pin, True)
 
     def off(self):
+        """
+        Turns the device off.
+        """
         GPIO.output(self.pin, False)
 
 
 class DigitalOutputDevice(OutputDevice):
+    """
+    Generic Digital GPIO Output Device (on/off/blink/toggle/flash).
+    """
     def __init__(self, pin=None):
         super(DigitalOutputDevice, self).__init__(pin)
         self._blink_thread = None
         self._lock = Lock()
 
     def on(self):
+        """
+        Turn the device on.
+        """
         self._stop_blink()
         super(DigitalOutputDevice, self).on()
 
     def off(self):
+        """
+        Turn the device off.
+        """
         self._stop_blink()
         super(DigitalOutputDevice, self).off()
 
     def blink(self, on_time=1, off_time=1):
+        """
+        Make the device turn on and off repeatedly in the background.
+
+        on_time: 1
+            Number of seconds on
+
+        off_time: 1
+            Number of seconds off
+        """
         self._stop_blink()
         self._blink_thread = GPIOThread(
             target=self._blink_led, args=(on_time, off_time)
         )
         self._blink_thread.start()
 
+    def toggle(self):
+        """
+        Reverse the state of the device.
+        If it's on, turn it off; if it's off, turn it on.
+        """
+        with self._lock:
+            if self.is_active:
+                self.off()
+            else:
+                self.on()
+
+    def flash(self, on_time=1, off_time=1, n=1):
+        """
+        Turn the device on and off a given number of times.
+
+        on_time: 1
+            Number of seconds on
+
+        off_time: 1
+            Number of seconds off
+
+        n: 1
+            Number of iterations
+        """
+        for i in range(n):
+            self.on()
+            sleep(on_time)
+            self.off()
+            if i+1 < n:  # don't sleep on final iteration
+                sleep(off_time)
+
     def _stop_blink(self):
         if self._blink_thread:
             self._blink_thread.stop()
@@ -57,35 +115,96 @@ class DigitalOutputDevice(OutputDevice):
             if self._blink_thread.stopping.wait(off_time):
                 break
 
-    def toggle(self):
-        with self._lock:
-            if self.is_active:
-                self.off()
-            else:
-                self.on()
-
-    def flash(self, on_time=1, off_time=1, n=1):
-        for i in range(n):
-            self.on()
-            sleep(on_time)
-            self.off()
-            if i+1 < n:  # don't sleep on final iteration
-                sleep(off_time)
-
 
 class LED(DigitalOutputDevice):
-    pass
+    """
+    An LED (Light Emmitting Diode) component.
+    """
+    def on(self):
+        """
+        Turn the LED on.
+        """
+        super(LED, self).on()
 
+    def off(self):
+        """
+        Turn the LED off.
+        """
+        super(LED, self).off()
+
+    def blink(self, on_time=1, off_time=1):
+        """
+        Make the LED turn on and off repeatedly in the background.
+
+        on_time: 1
+            Number of seconds on
+
+        off_time: 1
+            Number of seconds off
+        """
+        super(LED, self).blink()
+
+    def toggle(self):
+        """
+        Reverse the state of the LED.
+        If it's on, turn it off; if it's off, turn it on.
+        """
+        super(LED, self).toggle()
 
 class Buzzer(DigitalOutputDevice):
-    pass
+    """
+    A Buzzer component.
+    """
+    def on(self):
+        """
+        Turn the Buzzer on.
+        """
+        super(Buzzer, self).on()
+
+    def off(self):
+        """
+        Turn the Buzzer off.
+        """
+        super(Buzzer, self).off()
+
+    def blink(self, on_time=1, off_time=1):
+        """
+        Make the Buzzer turn on and off repeatedly in the background.
+
+        on_time: 1
+            Number of seconds on
+
+        off_time: 1
+            Number of seconds off
+        """
+        super(Buzzer, self).blink()
+
+    def toggle(self):
+        """
+        Reverse the state of the Buzzer.
+        If it's on, turn it off; if it's off, turn it on.
+        """
+        super(Buzzer, self).toggle()
 
 
 class Motor(OutputDevice):
-    pass
+    def on(self):
+        """
+        Turns the Motor on.
+        """
+        super(Motor, self).toggle()
+
+    def off(self):
+        """
+        Turns the Motor off.
+        """
+        super(Motor, self).toggle()
 
 
 class Robot(object):
+    """
+    Generic single-direction dual-motor Robot.
+    """
     def __init__(self, left=None, right=None):
         if not all([left, right]):
             raise GPIODeviceError('left and right pins must be provided')
@@ -94,18 +213,36 @@ class Robot(object):
         self._right = Motor(right)
 
     def left(self, seconds=None):
+        """
+        Turns left for a given number of seconds.
+
+        seconds: None
+            Number of seconds to turn left for
+        """
         self._left.on()
         if seconds is not None:
             sleep(seconds)
             self._left.off()
 
     def right(self, seconds=None):
+        """
+        Turns right for a given number of seconds.
+
+        seconds: None
+            Number of seconds to turn right for
+        """
         self._right.on()
         if seconds is not None:
             sleep(seconds)
             self._right.off()
 
     def forwards(self, seconds=None):
+        """
+        Drives forward for a given number of seconds.
+
+        seconds: None
+            Number of seconds to drive forward for
+        """
         self.left()
         self.right()
         if seconds is not None:
@@ -113,5 +250,8 @@ class Robot(object):
             self.stop()
 
     def stop(self):
+        """
+        Stops both motors.
+        """
         self._left.off()
         self._right.off()

setup.py

@@ -8,7 +8,7 @@ def read(fname):
 
 setup(
     name="gpiozero",
-    version="0.4.0",
+    version="0.5.0",
     author="Ben Nuttall",
     description="A simple interface to everyday GPIO components used with Raspberry Pi",
     license="BSD",