Doc reorganization

gpiozero/tools.py

@@ -28,7 +28,8 @@ def negated(values):
     Returns the negation of the supplied values (``True`` becomes ``False``,
     and ``False`` becomes ``True``). For example::
 
-        from gpiozero import Button, LED, negated
+        from gpiozero import Button, LED
+        from gpiozero.tools import negated
         from signal import pause
 
         led = LED(4)
@@ -45,7 +46,8 @@ def inverted(values):
     Returns the inversion of the supplied values (1 becomes 0, 0 becomes 1,
     0.1 becomes 0.9, etc.). For example::
 
-        from gpiozero import MCP3008, PWMLED, inverted
+        from gpiozero import MCP3008, PWMLED
+        from gpiozero.tools import inverted
         from signal import pause
 
         led = PWMLED(4)
@@ -57,36 +59,44 @@ def inverted(values):
         yield 1 - v
 
 
-def scaled(values, range_min, range_max, domain_min=0, domain_max=1):
+def scaled(values, output_min, output_max, input_min=0, input_max=1):
     """
-    Returns *values* scaled from *range_min* to *range_max*, assuming that all
-    items in *values* lie between *domain_min* and *domain_max* (which default
-    to 0 and 1 respectively). For example, to control the direction of a motor
-    (which is represented as a value between -1 and 1) using a potentiometer
-    (which typically provides values between 0 and 1)::
+    Returns *values* scaled from *output_min* to *output_max*, assuming that
+    all items in *values* lie between *input_min* and *input_max* (which
+    default to 0 and 1 respectively). For example, to control the direction of
+    a motor (which is represented as a value between -1 and 1) using a
+    potentiometer (which typically provides values between 0 and 1)::
 
-        from gpiozero import Motor, MCP3008, scaled
+        from gpiozero import Motor, MCP3008
+        from gpiozero.tools import scaled
         from signal import pause
 
         motor = Motor(20, 21)
         pot = MCP3008(channel=0)
         motor.source = scaled(pot.values, -1, 1)
         pause()
+
+    .. warning::
+
+        If *values* contains elements that lie outside *input_min* to
+        *input_max* (inclusive) then the function will not produce values that
+        lie within *output_min* to *output_max* (inclusive).
     """
-    domain_size = domain_max - domain_min
-    range_size = range_max - range_min
+    input_size = input_max - input_min
+    output_size = output_max - output_min
     for v in values:
-        yield (((v - domain_min) / domain_size) * range_size) + range_min
+        yield (((v - input_min) / input_size) * output_size) + output_min
 
 
-def clamped(values, range_min=0, range_max=1):
+def clamped(values, output_min=0, output_max=1):
     """
-    Returns *values* clamped from *range_min* to *range_max*, i.e. any items
-    less than *range_min* will be returned as *range_min* and any items
-    larger than *range_max* will be returned as *range_max* (these default to
+    Returns *values* clamped from *output_min* to *output_max*, i.e. any items
+    less than *output_min* will be returned as *output_min* and any items
+    larger than *output_max* will be returned as *output_max* (these default to
     0 and 1 respectively). For example::
 
-        from gpiozero import PWMLED, MCP3008, clamped
+        from gpiozero import PWMLED, MCP3008
+        from gpiozero.tools import clamped
         from signal import pause
 
         led = PWMLED(4)
@@ -95,19 +105,40 @@ def clamped(values, range_min=0, range_max=1):
         pause()
     """
     for v in values:
-        yield min(max(v, range_min), range_max)
+        yield min(max(v, output_min), output_max)
 
 
-def quantized(values, steps, range_min=0, range_max=1):
+def absoluted(values):
+    """
+    Returns *values* with all negative elements negated (so that they're
+    positive). For example::
+
+        from gpiozero import PWMLED, Motor, MCP3008
+        from gpiozero.tools import absoluted, scaled
+        from signal import pause
+
+        led = PWMLED(4)
+        motor = Motor(22, 27)
+        pot = MCP3008(channel=0)
+        motor.source = scaled(pot.values, -1, 1)
+        led.source = absoluted(motor.values)
+        pause()
+    """
+    for v in values:
+        yield abs(v)
+
+
+def quantized(values, steps, output_min=0, output_max=1):
     """
     Returns *values* quantized to *steps* increments. All items in *values* are
-    assumed to be between *range_min* and *range_max* (use :func:`scaled` to
+    assumed to be between *output_min* and *output_max* (use :func:`scaled` to
     ensure this if necessary).
 
     For example, to quantize values between 0 and 1 to 5 "steps" (0.0, 0.25,
     0.5, 0.75, 1.0)::
 
-        from gpiozero import PWMLED, MCP3008, quantized
+        from gpiozero import PWMLED, MCP3008
+        from gpiozero.tools import quantized
         from signal import pause
 
         led = PWMLED(4)
@@ -115,25 +146,26 @@ def quantized(values, steps, range_min=0, range_max=1):
         led.source = quantized(pot.values, 4)
         pause()
     """
-    range_size = range_max - range_min
-    for v in scaled(values, 0, 1, range_min, range_max):
-        yield ((int(v * steps) / steps) * range_size) + range_min
+    output_size = output_max - output_min
+    for v in scaled(values, 0, 1, output_min, output_max):
+        yield ((int(v * steps) / steps) * output_size) + output_min
 
 
-def conjunction(*values):
+def all_values(*values):
     """
     Returns the `logical conjunction`_ of all supplied values (the result is
     only ``True`` if and only if all input values are simultaneously ``True``).
     One or more *values* can be specified. For example, to light an
     :class:`LED` only when *both* buttons are pressed::
 
-        from gpiozero import LED, Button, conjunction
+        from gpiozero import LED, Button
+        from gpiozero.tools import all_values
         from signal import pause
 
         led = LED(4)
         btn1 = Button(20)
         btn2 = Button(21)
-        led.source = conjunction(btn1.values, btn2.values)
+        led.source = all_values(btn1.values, btn2.values)
         pause()
 
     .. _logical conjunction: https://en.wikipedia.org/wiki/Logical_conjunction
@@ -142,20 +174,21 @@ def conjunction(*values):
         yield all(v)
 
 
-def disjunction(*values):
+def any_values(*values):
     """
     Returns the `logical disjunction`_ of all supplied values (the result is
     ``True`` if any of the input values are currently ``True``). One or more
     *values* can be specified. For example, to light an :class:`LED` when
     *any* button is pressed::
 
-        from gpiozero import LED, Button, conjunction
+        from gpiozero import LED, Button
+        from gpiozero.tools import any_values
         from signal import pause
 
         led = LED(4)
         btn1 = Button(20)
         btn2 = Button(21)
-        led.source = disjunction(btn1.values, btn2.values)
+        led.source = any_values(btn1.values, btn2.values)
         pause()
 
     .. _logical disjunction: https://en.wikipedia.org/wiki/Logical_disjunction
@@ -170,7 +203,8 @@ def averaged(*values):
     specified. For example, to light a :class:`PWMLED` as the average of
     several potentiometers connected to an :class:`MCP3008` ADC::
 
-        from gpiozero import MCP3008, PWMLED, averaged
+        from gpiozero import MCP3008, PWMLED
+        from gpiozero.tools import averaged
         from signal import pause
 
         pot1 = MCP3008(channel=0)
@@ -190,7 +224,8 @@ def queued(values, qsize):
     determined by *qsize*) and begins yielding values only when the queue is
     full. For example, to "cascade" values along a sequence of LEDs::
 
-        from gpiozero import LEDBoard, Button, queued
+        from gpiozero import LEDBoard, Button
+        from gpiozero.tools import queued
         from signal import pause
 
         leds = LEDBoard(5, 6, 13, 19, 26)
@@ -236,7 +271,8 @@ def random_values():
     Provides an infinite source of random values between 0 and 1. For example,
     to produce a "flickering candle" effect with an LED::
 
-        from gpiozero import PWMLED, random_values
+        from gpiozero import PWMLED
+        from gpiozero.tools import random_values
         from signal import pause
 
         led = PWMLED(4)
@@ -256,13 +292,14 @@ def sin_values():
     that increments by one for each requested value. For example, to produce a
     "siren" effect with a couple of LEDs::
 
-        from gpiozero import PWMLED, sin_values, scaled, inverted
+        from gpiozero import PWMLED
+        from gpiozero.tools import sin_values, scaled, inverted
         from signal import pause
 
         red = PWMLED(2)
         blue = PWMLED(3)
-        red.source_delay = 0.1
-        blue.source_delay = 0.1
+        red.source_delay = 0.01
+        blue.source_delay = 0.01
         red.source = scaled(sin_values(), 0, 1, -1, 1)
         blue.source = inverted(red.values)
         pause()
@@ -280,11 +317,14 @@ def cos_values():
     counter that increments by one for each requested value. For example, to
     produce a "siren" effect with a couple of LEDs::
 
-        from gpiozero import PWMLED, cos_values, scaled, inverted
+        from gpiozero import PWMLED
+        from gpiozero.tools import cos_values, scaled, inverted
         from signal import pause
 
         red = PWMLED(2)
         blue = PWMLED(3)
+        red.source_delay = 0.01
+        blue.source_delay = 0.01
         red.source = scaled(cos_values(), 0, 1, -1, 1)
         blue.source = inverted(red.values)
         pause()