Merge pull request #800 from gpiozero/pin-factory-docs

Pin factory docs

docs/api_pins.rst

@@ -56,11 +56,50 @@ This is illustrated in the following flow-chart:
 .. image:: images/device_pin_flowchart.*
     :align: center
 
-The default factory is constructed when GPIO Zero is first imported; if no
+The default factory is constructed when the first device is initialised; if no
 default factory can be constructed (e.g. because no GPIO implementations are
-installed, or all of them fail to load for whatever reason), an
-:exc:`ImportError` will be raised.
+installed, or all of them fail to load for whatever reason), a
+:exc:`BadPinFactory` exception will be raised at construction time.
 
+After importing gpiozero, until constructing a gpiozero device, the pin factory
+is :data:`None`, but at the point of first construction the default pin factory
+will come into effect:
+
+.. code-block:: console
+
+    pi@raspberrypi:~ $ python3
+    Python 3.7.3 (default, Apr  3 2019, 05:39:12)
+    [GCC 8.2.0] on linux
+    Type "help", "copyright", "credits" or "license" for more information.
+    >>> from gpiozero import Device, LED
+    >>> print(Device.pin_factory)
+    None
+    >>> led = LED(2)
+    >>> Device.pin_factory
+    <gpiozero.pins.rpigpio.RPiGPIOFactory object at 0xb667ae30>
+    >>> led.pin_factory
+    <gpiozero.pins.rpigpio.RPiGPIOFactory object at 0xb6323530>
+
+As above, on a Raspberry Pi with the RPi.GPIO library installed, (assuming no
+environment variables are set), the default pin factory will be
+:class:`~gpiozero.pins.rpigpio.RPiGPIOFactory`.
+
+On a PC (with no pin libraries installed and no environment variables set),
+importing will work but attempting to create a device will raise
+:exc:`BadPinFactory`:
+
+.. code-block:: console
+
+    ben@magicman:~ $ python3
+    Python 3.6.8 (default, Aug 20 2019, 17:12:48)
+    [GCC 8.3.0] on linux
+    Type "help", "copyright", "credits" or "license" for more information.
+    >>> from gpiozero import Device, LED
+    >>> print(Device.pin_factory)
+    None
+    >>> led = LED(2)
+    ...
+    BadPinFactory: Unable to load any default pin factory!
 
 .. _changing-pin-factory:
 
@@ -72,39 +111,43 @@ The default pin factory can be replaced by specifying a value for the
 
 .. code-block:: console
 
-    $ GPIOZERO_PIN_FACTORY=native python
-    Python 3.4.2 (default, Oct 19 2014, 13:31:11)
-    [GCC 4.9.1] on linux
+    pi@raspberrypi:~ $ GPIOZERO_PIN_FACTORY=native python3
+    Python 3.7.3 (default, Apr  3 2019, 05:39:12)
+    [GCC 8.2.0] on linux
     Type "help", "copyright", "credits" or "license" for more information.
-    >>> import gpiozero
-    >>> gpiozero.Device.pin_factory
+    >>> from gpiozero import Device
+    >>> Device._default_pin_factory()
     <gpiozero.pins.native.NativeFactory object at 0x762c26b0>
 
 To set the :envvar:`GPIOZERO_PIN_FACTORY` for the rest of your session you can
 :command:`export` this value:
 
 .. code-block:: console
 
-    $ export GPIOZERO_PIN_FACTORY=native
-    $ python
-    Python 3.4.2 (default, Oct 19 2014, 13:31:11)
-    [GCC 4.9.1] on linux
+    pi@raspberrypi:~ $ export GPIOZERO_PIN_FACTORY=native
+    pi@raspberrypi:~ $ python3
+    Python 3.7.3 (default, Apr  3 2019, 05:39:12)
+    [GCC 8.2.0] on linux
     Type "help", "copyright", "credits" or "license" for more information.
     >>> import gpiozero
-    >>> gpiozero.Device.pin_factory
+    >>> Device._default_pin_factory()
     <gpiozero.pins.native.NativeFactory object at 0x762c26b0>
     >>> quit()
-    $ python
-    Python 3.4.2 (default, Oct 19 2014, 13:31:11)
-    [GCC 4.9.1] on linux
+    pi@raspberrypi:~ $ python3
+    Python 3.7.3 (default, Apr  3 2019, 05:39:12)
+    [GCC 8.2.0] on linux
     Type "help", "copyright", "credits" or "license" for more information.
     >>> import gpiozero
-    >>> gpiozero.Device.pin_factory
-    <gpiozero.pins.native.NativeFactory object at 0x76401330>
+    >>> Device._default_pin_factory()
+    <gpiozero.pins.native.NativeFactory object at 0x762c26b0>
 
 If you add the :command:`export` command to your :file:`~/.bashrc` file, you'll
 set the default pin factory for all future sessions too.
 
+If the environment variable is set, the corresponding pin factory will be used,
+otherwise each of the four GPIO pin factories will be attempted to be used in
+turn.
+
 The following values, and the corresponding :class:`Factory` and :class:`Pin`
 classes are listed in the table below. Factories are listed in the order that
 they are tried by default.
@@ -129,8 +172,7 @@ If you need to change the default pin factory from within a script, either set
 
     Device.pin_factory = NativeFactory()
 
-    # These will now implicitly use NativePin instead of
-    # RPiGPIOPin
+    # These will now implicitly use NativePin instead of RPiGPIOPin
     led1 = LED(16)
     led2 = LED(17)
 

docs/images/device_pin_flowchart.dot

@@ -7,13 +7,18 @@ digraph device_pins {
 
     constructor [label="LED(pin_spec, ...,\npin_factory=None)"];
     pin_factory_kwarg [shape=diamond,label="pin_factory\nis None?"];
-    default_factory [label="self.pin_factory =\nDevice.pin_factory"];
+    device_pin_factory [shape=diamond,label="Device.pin_factory\nis None?"];
+    set_default_factory [label="Device.pin_factory =\nDevice._default_pin_factory()"];
+    get_default_factory [label="self.pin_factory =\nDevice.pin_factory"];
     override_factory [label="self.pin_factory =\npin_factory"];
     factory_pin [label="self.pin =\nself.pin_factory.pin(pin_spec)"];
 
     constructor->pin_factory_kwarg;
-    pin_factory_kwarg->default_factory [label="yes"];
+    pin_factory_kwarg->device_pin_factory [label="yes"];
     pin_factory_kwarg->override_factory [label="no"];
-    default_factory->factory_pin;
+    device_pin_factory->set_default_factory [label="yes"];
+    device_pin_factory->get_default_factory [label="no"];
+    set_default_factory->get_default_factory;
+    get_default_factory->factory_pin;
     override_factory->factory_pin;
 }