Add pin_factory to all relevant class docs

Also tell a whole load of lies about what's a keyword-only arg. In the vast majority of cases, pin_factory (and other args) *aren't* keyword-only ... but we'd really like them to be, it's just difficult while maintaining py2 compatibility.
2025-10-29 17:50:37 +00:00 · 2017-07-13 21:01:42 +01:00
parent 8958874a77
commit 9fdc093837
6 changed files with 33 additions and 29 deletions
--- a/docs/api_boards.rst
+++ b/docs/api_boards.rst
@@ -18,21 +18,21 @@ individually.
 LEDBoard
 ========

-.. autoclass:: LEDBoard(\*pins, pwm=False, active_high=True, initial_value=False, \*\*named_pins)
+.. autoclass:: LEDBoard(\*pins, pwm=False, active_high=True, initial_value=False, pin_factory=None, \*\*named_pins)
    :inherited-members:
    :members:

 LEDBarGraph
 ===========

-.. autoclass:: LEDBarGraph(\*pins, pwm=False, active_high=True, initial_value=0)
+.. autoclass:: LEDBarGraph(\*pins, pwm=False, active_high=True, initial_value=0, pin_factory=None)
    :inherited-members:
    :members:

 ButtonBoard
 ===========

-.. autoclass:: ButtonBoard(\*pins, pull_up=True, bounce_time=None, hold_time=1, hold_repeat=False, \*\*named_pins)
+.. autoclass:: ButtonBoard(\*pins, pull_up=True, bounce_time=None, hold_time=1, hold_repeat=False, pin_factory=None, \*\*named_pins)
    :inherited-members:
    :members:

@@ -130,14 +130,14 @@ Energenie
 StatusZero
 ==========

-.. autoclass:: StatusZero
+.. autoclass:: StatusZero(\*labels, pwm=False, active_high=True, initial_value=False, pin_factory=None)
    :inherited-members:
    :members:

 StatusBoard
 ===========

-.. autoclass:: StatusBoard
+.. autoclass:: StatusBoard(\*labels, pwm=False, active_high=True, initial_value=False, pin_factory=None)
    :inherited-members:
    :members:

@@ -168,17 +168,17 @@ to construct classes for their own devices.
 LEDCollection
 =============

-.. autoclass:: LEDCollection
+.. autoclass:: LEDCollection(\*pins, pwm=False, active_high=True, initial_value=False, pin_factory=None, \*\*named_pins)
    :members:

 CompositeOutputDevice
 =====================

-.. autoclass:: CompositeOutputDevice(\*args, _order=None, \*\*kwargs)
+.. autoclass:: CompositeOutputDevice(\*args, _order=None, pin_factory=None, \*\*kwargs)
    :members:

 CompositeDevice
 ===============

-.. autoclass:: CompositeDevice(\*args, _order=None, \*\*kwargs)
+.. autoclass:: CompositeDevice(\*args, _order=None, pin_factory=None, \*\*kwargs)
    :members:
--- a/docs/api_generic.rst
+++ b/docs/api_generic.rst
@@ -33,7 +33,7 @@ are represented in purple, while abstract classes are shaded lighter):
 Device
 ======

-.. autoclass:: Device
+.. autoclass:: Device(\*, pin_factory=None)
    :members: close, closed, value, is_active

 ValuesMixin
--- a/docs/api_input.rst
+++ b/docs/api_input.rst
@@ -16,35 +16,35 @@ everyday components. Components must be wired up correctly before use in code.
 Button
 ======

-.. autoclass:: Button(pin, pull_up=True, bounce_time=None, hold_time=1, hold_repeat=False, pin_factory=None)
+.. autoclass:: Button(pin, \*, pull_up=True, bounce_time=None, hold_time=1, hold_repeat=False, pin_factory=None)
    :members: wait_for_press, wait_for_release, pin, is_pressed, is_held, hold_time, held_time, hold_repeat, pull_up, when_pressed, when_released, when_held


 Line Sensor (TRCT5000)
 ======================

-.. autoclass:: LineSensor(pin, queue_len=5, sample_rate=100, threshold=0.5, partial=False, pin_factory=None)
+.. autoclass:: LineSensor(pin, \*, queue_len=5, sample_rate=100, threshold=0.5, partial=False, pin_factory=None)
    :members: wait_for_line, wait_for_no_line, pin, line_detected, when_line, when_no_line


 Motion Sensor (D-SUN PIR)
 =========================

-.. autoclass:: MotionSensor(pin, queue_len=1, sample_rate=10, threshold=0.5, partial=False, pin_factory=None)
+.. autoclass:: MotionSensor(pin, \*, queue_len=1, sample_rate=10, threshold=0.5, partial=False, pin_factory=None)
    :members: wait_for_motion, wait_for_no_motion, pin, motion_detected, when_motion, when_no_motion


 Light Sensor (LDR)
 ==================

-.. autoclass:: LightSensor(pin, queue_len=5, charge_time_limit=0.01, threshold=0.1, partial=False, pin_factory=None)
+.. autoclass:: LightSensor(pin, \*, queue_len=5, charge_time_limit=0.01, threshold=0.1, partial=False, pin_factory=None)
    :members: wait_for_light, wait_for_dark, pin, light_detected, when_light, when_dark


 Distance Sensor (HC-SR04)
 =========================

-.. autoclass:: DistanceSensor(echo, trigger, queue_len=30, max_distance=1, threshold_distance=0.3, partial=False, pin_factory=None)
+.. autoclass:: DistanceSensor(echo, trigger, \*, queue_len=30, max_distance=1, threshold_distance=0.3, partial=False, pin_factory=None)
    :members: wait_for_in_range, wait_for_out_of_range, trigger, echo, when_in_range, when_out_of_range, max_distance, distance, threshold_distance

 Base Classes
@@ -63,19 +63,19 @@ to construct classes for their own devices.
 DigitalInputDevice
 ==================

-.. autoclass:: DigitalInputDevice(pin, pull_up=False, bounce_time=None, pin_factory=None)
+.. autoclass:: DigitalInputDevice(pin, \*, pull_up=False, bounce_time=None, pin_factory=None)
    :members:

 SmoothedInputDevice
 ===================

-.. autoclass:: SmoothedInputDevice
+.. autoclass:: SmoothedInputDevice(pin, \*, pull_up=False, threshold=0.5, queue_len=5, sample_wait=0.0, partial=False, pin_factory=None)
    :members:

 InputDevice
 ===========

-.. autoclass:: InputDevice(pin, pull_up=False, pin_factory=None)
+.. autoclass:: InputDevice(pin, \*, pull_up=False, pin_factory=None)
    :members:

 GPIODevice
--- a/docs/api_output.rst
+++ b/docs/api_output.rst
@@ -16,44 +16,44 @@ everyday components. Components must be wired up correctly before use in code.
 LED
 ===

-.. autoclass:: LED(pin, active_high=True, initial_value=False)
+.. autoclass:: LED(pin, \*, active_high=True, initial_value=False, pin_factory=None)
    :members: on, off, toggle, blink, pin, is_lit

 PWMLED
 ======

-.. autoclass:: PWMLED(pin, active_high=True, initial_value=0, frequency=100)
+.. autoclass:: PWMLED(pin, \*, active_high=True, initial_value=0, frequency=100, pin_factory=None)
    :members: on, off, toggle, blink, pulse, pin, is_lit, value

 RGBLED
 ======

-.. autoclass:: RGBLED(red, green, blue, active_high=True, initial_value=(0, 0, 0), pwm=True)
+.. autoclass:: RGBLED(red, green, blue, \*, active_high=True, initial_value=(0, 0, 0), pwm=True, pin_factory=None)
    :members: on, off, toggle, blink, pulse, red, green, blue, is_lit, color

 Buzzer
 ======

-.. autoclass:: Buzzer(pin, active_high=True, initial_value=False)
+.. autoclass:: Buzzer(pin, \*, active_high=True, initial_value=False, pin_factory=None)
    :members: on, off, toggle, beep, pin, is_active

 Motor
 =====

-.. autoclass:: Motor(forward, backward, pwm=True)
+.. autoclass:: Motor(forward, backward, \*, pwm=True, pin_factory=None)
    :members: forward, backward, stop

 Servo
 =====

-.. autoclass:: Servo(pin, initial_value=0, min_pulse_width=1/1000, max_pulse_width=2/1000, frame_width=20/1000)
+.. autoclass:: Servo(pin, \*, initial_value=0, min_pulse_width=1/1000, max_pulse_width=2/1000, frame_width=20/1000, pin_factory=None)
    :inherited-members:
    :members:

 AngularServo
 ============

-.. autoclass:: AngularServo(pin, initial_angle=0, min_angle=-90, max_angle=90, min_pulse_width=1/1000, max_pulse_width=2/1000, frame_width=20/1000)
+.. autoclass:: AngularServo(pin, \*, initial_angle=0, min_angle=-90, max_angle=90, min_pulse_width=1/1000, max_pulse_width=2/1000, frame_width=20/1000, pin_factory=None)
    :inherited-members:
    :members:

@@ -73,25 +73,25 @@ to construct classes for their own devices.
 DigitalOutputDevice
 ===================

-.. autoclass:: DigitalOutputDevice(pin, active_high=True, initial_value=False)
+.. autoclass:: DigitalOutputDevice(pin, \*, active_high=True, initial_value=False, pin_factory=None)
    :members:

 PWMOutputDevice
 ===============

-.. autoclass:: PWMOutputDevice(pin, active_high=True, initial_value=0, frequency=100)
+.. autoclass:: PWMOutputDevice(pin, \*, active_high=True, initial_value=0, frequency=100, pin_factory=None)
    :members:

 OutputDevice
 ============

-.. autoclass:: OutputDevice(pin, active_high=True, initial_value=False)
+.. autoclass:: OutputDevice(pin, \*, active_high=True, initial_value=False, pin_factory=None)
    :members:

 GPIODevice
 ==========

-.. autoclass:: GPIODevice(pin)
+.. autoclass:: GPIODevice(pin, \*, pin_factory=None)
    :members:
    :noindex:

--- a/docs/api_spi.rst
+++ b/docs/api_spi.rst
@@ -64,6 +64,10 @@ omit any arguments from either scheme. The defaults are:
 * *clock_pin* defaults to 11, *mosi_pin* defaults to 10, *miso_pin* defaults
  to 9, and *select_pin* defaults to 8.

+* As with other GPIO based devices you can optionally specify a *pin_factory*
+  argument overriding the default pin factory (see :doc:`api_pins` for more
+  information).
+
 Hence the following constructors are all equivalent::

    from gpiozero import MCP3008
--- a/gpiozero/boards.py
+++ b/gpiozero/boards.py
@@ -961,7 +961,7 @@ class StatusBoard(CompositeOutputDevice):
        super(StatusBoard, self).__init__(
            _order=labels, pin_factory=pin_factory, **{
                label: CompositeOutputDevice(
-                    button=Button(button),
+                    button=Button(button, pin_factory=pin_factory),
                    lights=LEDBoard(
                        red=red, green=green, _order=('red', 'green'),
                        pin_factory=pin_factory, **kwargs