Merge pull request gpiozero#698 from RPi-Distro/connect-devices

bennuttall · web-flow · commit 96cf4038d771 · 2019-01-14T15:43:54.000Z
Allow source tools to take device object as well as device.values or just values, close gpiozero#640
diff --git a/docs/examples/button_led_2.py b/docs/examples/button_led_2.py
@@ -4,6 +4,6 @@
 led = LED(17)
 button = Button(2)
 
-led.source = button.values
+led.source = button
 
 pause()
diff --git a/docs/examples/combining_sources.py b/docs/examples/combining_sources.py
@@ -6,6 +6,6 @@
 button_b = Button(3)
 led = LED(17)
 
-led.source = all_values(button_a.values, button_b.values)
+led.source = all_values(button_a, button_b)
 
 pause()
diff --git a/docs/examples/cpu_temperature_bar_graph.py b/docs/examples/cpu_temperature_bar_graph.py
@@ -4,6 +4,6 @@
 cpu = CPUTemperature(min_temp=50, max_temp=90)
 leds = LEDBarGraph(2, 3, 4, 5, 6, 7, 8, pwm=True)
 
-leds.source = cpu.values
+leds.source = cpu
 
 pause()
diff --git a/docs/examples/custom_generator_finite.py b/docs/examples/custom_generator_finite.py
@@ -2,6 +2,7 @@
 from signal import pause
 
 led = LED(17)
+led.source_delay = 1
 led.source = [1, 0, 1, 1, 1, 0, 0, 1, 0, 1]
 
 pause()
diff --git a/docs/examples/internet_status_indicator.py b/docs/examples/internet_status_indicator.py
@@ -7,8 +7,8 @@
 
 google = PingServer('google.com')
 
-green.source = google.values
+green.source = google
 green.source_delay = 60
-red.source = negated(green.values)
+red.source = negated(green)
 
 pause()
diff --git a/docs/examples/led_button.py b/docs/examples/led_button.py
@@ -4,6 +4,6 @@
 led = LED(17)
 button = Button(2)
 
-led.source = button.values
+led.source = button
 
 pause()
diff --git a/docs/examples/led_button_remote_1.py b/docs/examples/led_button_remote_1.py
@@ -7,6 +7,6 @@
 button = Button(2)
 led = LED(17, pin_factory=factory)
 
-led.source = button.values
+led.source = button
 
 pause()
diff --git a/docs/examples/led_button_remote_2.py b/docs/examples/led_button_remote_2.py
@@ -10,6 +10,6 @@
 button_1 = Button(17, pin_factory=factory3)
 button_2 = Button(17, pin_factory=factory4)
 
-led.source = all_values(button_1.values, button_2.values)
+led.source = all_values(button_1, button_2)
 
 pause()
diff --git a/docs/examples/led_travis.py b/docs/examples/led_travis.py
@@ -15,6 +15,6 @@ def build_passed(repo):
 
 green.source = build_passed('RPi-Distro/python-gpiozero')
 green.source_delay = 60 * 5  # check every 5 minutes
-red.source = negated(green.values)
+red.source = negated(green)
 
 pause()
diff --git a/docs/examples/light_sensor_3.py b/docs/examples/light_sensor_3.py
@@ -4,6 +4,6 @@
 sensor = LightSensor(18)
 led = PWMLED(16)
 
-led.source = sensor.values
+led.source = sensor
 
 pause()
diff --git a/docs/examples/matching_leds.py b/docs/examples/matching_leds.py
@@ -5,7 +5,7 @@
 green = LED(15)
 button = Button(17)
 
-red.source = button.values
-green.source = red.values
+red.source = button
+green.source = red
 
 pause()
diff --git a/docs/examples/mock_demo.py b/docs/examples/mock_demo.py
@@ -9,7 +9,7 @@
 # devices
 led = LED(17)
 btn = Button(16)
-led.source = btn.values
+led.source = btn
 
 # Here the button isn't "pushed" so the LED's value should be False
 print(led.value)
diff --git a/docs/examples/multi_room_doorbell.py b/docs/examples/multi_room_doorbell.py
@@ -9,6 +9,6 @@
 buzzers = [Buzzer(pin, pin_factory=r) for r in remotes]  # buzzers on remote pins
 
 for buzzer in buzzers:
-    buzzer.source = button.values
+    buzzer.source = button
 
 pause()
diff --git a/docs/examples/multi_room_motion_alert.py b/docs/examples/multi_room_motion_alert.py
@@ -9,6 +9,6 @@
 sensors = [MotionSensor(17, pin_factory=r) for r in remotes]  # remote sensors
 
 for led, sensor in zip(leds, sensors):
-    led.source = sensor.values
+    led.source = sensor
 
 pause()
diff --git a/docs/examples/negated.py b/docs/examples/negated.py
@@ -5,6 +5,6 @@
 led = LED(4)
 btn = Button(17)
 
-led.source = negated(btn.values)
+led.source = negated(btn)
 
 pause()
diff --git a/docs/examples/pot_2.py b/docs/examples/pot_2.py
@@ -3,5 +3,7 @@
 
 graph = LEDBarGraph(5, 6, 13, 19, 26, pwm=True)
 pot = MCP3008(channel=0)
-graph.source = pot.values
+
+graph.source = pot
+
 pause()
diff --git a/docs/examples/pwmled_pot.py b/docs/examples/pwmled_pot.py
@@ -4,6 +4,6 @@
 led = PWMLED(17)
 pot = MCP3008()
 
-led.source = pot.values
+led.source = pot
 
 pause()
diff --git a/docs/examples/pwmled_pot_values.py b/docs/examples/pwmled_pot_values.py
@@ -0,0 +1,9 @@
+from gpiozero import PWMLED, MCP3008
+from signal import pause
+
+led = PWMLED(17)
+pot = MCP3008()
+
+led.source = pot.values
+
+pause()
diff --git a/docs/examples/robot_pots_2.py b/docs/examples/robot_pots_2.py
@@ -7,6 +7,6 @@
 left = MCP3008(0)
 right = MCP3008(1)
 
-robot.source = zip(scaled(left.values, -1, 1), scaled(right.values, -1, 1))
+robot.source = zip(scaled(left, -1, 1), scaled(right, -1, 1))
 
 pause()
diff --git a/docs/examples/source_value_processing.py b/docs/examples/source_value_processing.py
@@ -1,13 +1,13 @@
 from gpiozero import Button, LED
 from signal import pause
 
-def opposite(values):
-    for value in values:
+def opposite(device):
+    for value in device.values:
         yield not value
 
 led = LED(4)
 btn = Button(17)
 
-led.source = opposite(btn.values)
+led.source = opposite(btn)
 
 pause()
diff --git a/docs/examples/timed_heat_lamp.py b/docs/examples/timed_heat_lamp.py
@@ -5,7 +5,7 @@
 lamp = Energenie(1)
 daytime = TimeOfDay(time(8), time(20))
 
-lamp.source = daytime.values
+lamp.source = daytime
 lamp.source_delay = 60
 
 pause()
diff --git a/docs/examples/whos_home_leds.py b/docs/examples/whos_home_leds.py
@@ -15,8 +15,8 @@
 }
 
 for server, leds in statuses.items():
-    leds.green.source = server.values
+    leds.green.source = server
     leds.green.source_delay = 60
-    leds.red.source = negated(leds.green.values)
+    leds.red.source = negated(leds.green)
 
 pause()
diff --git a/docs/examples/whos_home_status.py b/docs/examples/whos_home_status.py
@@ -11,8 +11,8 @@
 }
 
 for server, leds in statuses.items():
-    leds.green.source = server.values
+    leds.green.source = server
     leds.green.source_delay = 60
-    leds.red.source = negated(leds.green.values)
+    leds.red.source = negated(leds.green)
 
 pause()
diff --git a/docs/source_values.rst b/docs/source_values.rst
@@ -29,8 +29,8 @@ their value set to alter the state of the device::
 Every device also has a :attr:`~ValuesMixin.values` property (a generator
 continuously yielding the device's current value). All output devices have a
 :attr:`~SourceMixin.source` property which can be set to any iterator. The
-device will iterate over the values provided, setting the device's value to
-each element at a rate specified in the :attr:`~SourceMixin.source_delay`
+device will iterate over the values of the device provided, setting the device's
+value to each element at a rate specified in the :attr:`~SourceMixin.source_delay`
 property.
 
 .. image:: images/source_values.*
@@ -42,9 +42,19 @@ example would be a potentiometer controlling the brightness of an LED:
 
 .. literalinclude:: examples/pwmled_pot.py
 
+The way this works is that the device's :attr:`~ValuesMixin.values` property
+is used to feed values into the device. Prior to v1.5, the :attr:`~SourceMixin.source`
+had to be set directly to a device's :attr:`~ValuesMixin.values` property:
+
+.. literalinclude:: examples/pwmled_pot_values.py
+
+.. note::
+
+    Although this method is still supported, the recommended way is now to set
+    the :attr:`~SourceMixin.source` to a device object.
+
 It is also possible to set an output device's :attr:`~SourceMixin.source` to
-the :attr:`~ValuesMixin.values` of another output device, to keep them
-matching:
+another output device, to keep them matching:
 
 .. literalinclude:: examples/matching_leds.py
 
@@ -122,6 +132,12 @@ In this example, the LED is lit only when the button is not pressed:
 
 .. literalinclude:: examples/negated.py
 
+.. note::
+
+    Note that source tools which take one or more ``value`` parameters support
+    passing either :class:`~ValuesMixin` derivatives, or iterators, including a
+    device's :attr:`~ValuesMixin.values` property.
+
 Some tools combine the values of multiple sources:
 
 .. image:: images/combining_sources.*
diff --git a/gpiozero/boards.py b/gpiozero/boards.py
@@ -492,7 +492,9 @@ class LEDBarGraph(LEDCollection):
 
         graph = LEDBarGraph(2, 3, 4, 5, 6, pwm=True)
         pot = MCP3008(channel=0)
-        graph.source = pot.values
+
+        graph.source = pot
+
         pause()
 
     :param int \*pins:
diff --git a/gpiozero/mixins.py b/gpiozero/mixins.py
@@ -52,10 +52,10 @@ def values(self):
 
 class SourceMixin(object):
     """
-    Adds a :attr:`source` property to the class which, given an iterable, sets
-    :attr:`value` to each member of that iterable until it is exhausted.  This
-    mixin is generally included in novel output devices to allow their state to
-    be driven from another device.
+    Adds a :attr:`source` property to the class which, given an iterable or
+    a :class:``ValuesMixin`` descendent, sets :attr:`value` to each member of
+    that iterable until it is exhausted. This mixin is generally included in
+    novel output devices to allow their state to be driven from another device.
 
     .. note::
 
@@ -111,6 +111,8 @@ def source(self, value):
         if getattr(self, '_source_thread', None):
             self._source_thread.stop()
         self._source_thread = None
+        if isinstance(value, ValuesMixin):
+            value = value.values
         self._source = value
         if value is not None:
             self._source_thread = GPIOThread(target=self._copy_values, args=(value,))
@@ -510,4 +512,3 @@ def fill(self):
         except ReferenceError:
             # Parent is dead; time to die!
             pass
-
diff --git a/gpiozero/other_devices.py b/gpiozero/other_devices.py
@@ -43,7 +43,7 @@ class PingServer(InternalDevice):
         led = LED(4)
 
         led.source_delay = 60  # check once per minute
-        led.source = google.values
+        led.source = google
 
         pause()
 
@@ -92,7 +92,7 @@ class CPUTemperature(InternalDevice):
         print('Initial temperature: {}C'.format(cpu.temperature))
 
         graph = LEDBarGraph(5, 6, 13, 19, 25, pwm=True)
-        graph.source = cpu.values
+        graph.source = cpu
 
         pause()
 
@@ -166,7 +166,7 @@ class LoadAverage(InternalDevice):
         la = LoadAverage(min_load_average=0, max_load_average=2)
         graph = LEDBarGraph(5, 6, 13, 19, 25, pwm=True)
 
-        graph.source = la.values
+        graph.source = la
 
         pause()
 
@@ -257,7 +257,7 @@ class TimeOfDay(InternalDevice):
         lamp = Energenie(1)
         morning = TimeOfDay(time(7), time(8))
 
-        lamp.source = morning.values
+        lamp.source = morning
 
         pause()
 
diff --git a/gpiozero/spi_devices.py b/gpiozero/spi_devices.py
@@ -108,7 +108,7 @@ class AnalogInputDevice(SPIDevice):
 
         pot = MCP3008(0)
         led = PWMLED(17)
-        led.source = pot.values
+        led.source = pot
 
     The :attr:`voltage` attribute reports values between 0.0 and *max_voltage*
     (which defaults to 3.3, the logic level of the GPIO pins).
@@ -544,4 +544,3 @@ def __init__(self, channel=0, differential=False, max_voltage=3.3, **spi_args):
         if not 0 <= channel < 8:
             raise SPIBadChannel('channel must be between 0 and 7')
         super(MCP3304, self).__init__(channel, differential, max_voltage, **spi_args)
-
diff --git a/gpiozero/tools.py b/gpiozero/tools.py
diff --git a/tests/test_tools.py b/tests/test_tools.py
