Skip to content

Commit 714521a

Browse files
tannewttannewt
committed
shared-bindings: Update docs to remove with statements from examples but add more detail to the design guide about their use.
1 parent c5e515b commit 714521a

28 files changed

Lines changed: 362 additions & 283 deletions

‎conf.py‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -319,6 +319,6 @@
319319

320320

321321
# Example configuration for intersphinx: refer to the Python standard library.
322-
intersphinx_mapping = {'https://docs.python.org/3/': None,
323-
'https://circuitpython.readthedocs.io/projects/bus_device/en/latest/': None,
324-
'https://circuitpython.readthedocs.io/projects/register/en/latest/': None}
322+
intersphinx_mapping = {"cpython": ('https://docs.python.org/3/', None),
323+
"bus_device": ('https://circuitpython.readthedocs.io/projects/bus_device/en/latest/', None),
324+
"register": ('https://circuitpython.readthedocs.io/projects/register/en/latest/', None)}

‎docs/design_guide.rst‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,8 @@ not have the ``adafruit_`` module or package prefix.
3333

3434
Both should have the CircuitPython repository topic on GitHub.
3535

36+
.. _lifetime-and-contextmanagers:
37+
3638
Lifetime and ContextManagers
3739
--------------------------------------------------------------------------------
3840

@@ -41,6 +43,49 @@ device requires deinitialization, then provide it through ``deinit()`` and also
4143
provide ``__enter__`` and ``__exit__`` to create a context manager usable with
4244
``with``.
4345

46+
For example, a user can then use ``deinit()```::
47+
48+
import digitalio
49+
import board
50+
51+
led = digitalio.DigitalInOut(board.D13)
52+
led.direction = digitalio.DigitalInOut.Direction.OUT
53+
54+
for i in range(10):
55+
led.value = True
56+
time.sleep(0.5)
57+
58+
led.value = False
59+
time.sleep(0.5)
60+
led.deinit()
61+
62+
This will deinit the underlying hardware at the end of the program as long as no
63+
exceptions occur.
64+
65+
Alternatively, using a ``with`` statement ensures that the hardware is deinitialized::
66+
67+
import digitalio
68+
import board
69+
70+
with digitalio.DigitalInOut(board.D13) as led:
71+
led.direction = digitalio.DigitalInOut.Direction.OUT
72+
73+
for i in range(10):
74+
led.value = True
75+
time.sleep(0.5)
76+
77+
led.value = False
78+
time.sleep(0.5)
79+
80+
Python's ``with`` statement ensures that the deinit code is run regardless of
81+
whether the code within the with statement executes without exceptions.
82+
83+
For small programs like the examples this isn't a major concern because all
84+
user usable hardware is reset after programs are run or the REPL is run. However,
85+
for more complex programs that may use hardware intermittently and may also
86+
handle exceptions on their own, deinitializing the hardware using a with
87+
statement will ensure hardware isn't enabled longer than needed.
88+
4489
Verify your device
4590
--------------------------------------------------------------------------------
4691

‎shared-bindings/analogio/AnalogIn.c‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -45,8 +45,8 @@
4545
//| import analogio
4646
//| from board import *
4747
//|
48-
//| with analogio.AnalogIn(A1) as adc:
49-
//| val = adc.value
48+
//| adc = analogio.AnalogIn(A1)
49+
//| val = adc.value
5050
//|
5151

5252
//| .. class:: AnalogIn(pin)
@@ -93,7 +93,8 @@ MP_DEFINE_CONST_FUN_OBJ_1(analogio_analogin_deinit_obj, analogio_analogin_deinit
9393

9494
//| .. method:: __exit__()
9595
//|
96-
//| Automatically deinitializes the hardware when exiting a context.
96+
//| Automatically deinitializes the hardware when exiting a context. See
97+
//| :ref:`lifetime-and-contextmanagers` for more info.
9798
//|
9899
STATIC mp_obj_t analogio_analogin___exit__(size_t n_args, const mp_obj_t *args) {
99100
(void)n_args;

‎shared-bindings/analogio/AnalogOut.c‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -45,8 +45,8 @@
4545
//| import analogio
4646
//| from microcontroller import pin
4747
//|
48-
//| with analogio.AnalogOut(pin.PA02) as dac: # output on pin PA02
49-
//| dac.value = 32768 # makes PA02 1.65V
48+
//| dac = analogio.AnalogOut(pin.PA02) # output on pin PA02
49+
//| dac.value = 32768 # makes PA02 1.65V
5050
//|
5151

5252
//| .. class:: AnalogOut(pin)
@@ -91,7 +91,8 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_1(analogio_analogout_deinit_obj, analogio_analogo
9191

9292
//| .. method:: __exit__()
9393
//|
94-
//| Automatically deinitializes the hardware when exiting a context.
94+
//| Automatically deinitializes the hardware when exiting a context. See
95+
//| :ref:`lifetime-and-contextmanagers` for more info.
9596
//|
9697
STATIC mp_obj_t analogio_analogout___exit__(size_t n_args, const mp_obj_t *args) {
9798
(void)n_args;

‎shared-bindings/analogio/__init__.c‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -53,21 +53,24 @@
5353
//| AnalogIn
5454
//| AnalogOut
5555
//|
56-
//| All libraries change hardware state and should be deinitialized when they
57-
//| are no longer needed. To do so, either call :py:meth:`!deinit` or use a
58-
//| context manager.
56+
//| All classes change hardware state and should be deinitialized when they
57+
//| are no longer needed if the program continues after use. To do so, either
58+
//| call :py:meth:`!deinit` or use a context manager. See
59+
//| :ref:`lifetime-and-contextmanagers` for more info.
5960
//|
6061
//| For example::
6162
//|
6263
//| import analogio
6364
//| from board import *
6465
//|
65-
//| with analogio.AnalogIn(A0) as pin:
66-
//| print(pin.value)
66+
//| pin = analogio.AnalogIn(A0)
67+
//| print(pin.value)
68+
//| pin.deinit()
6769
//|
6870
//| This example will initialize the the device, read
6971
//| :py:data:`~analogio.AnalogIn.value` and then
70-
//| :py:meth:`~analogio.AnalogIn.deinit` the hardware.
72+
//| :py:meth:`~analogio.AnalogIn.deinit` the hardware. The last step is optional
73+
//| because CircuitPython will do it automatically after the program finishes.
7174
//|
7275

7376
STATIC const mp_rom_map_elem_t analogio_module_globals_table[] = {

‎shared-bindings/audioio/AudioOut.c‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -66,10 +66,10 @@
6666
//| for i in range(length):
6767
//| b[i] = int(math.sin(math.pi * 2 * i / 18) * (2 ** 15) + 2 ** 15)
6868
//|
69-
//| with audioio.AudioOut(board.SPEAKER, sin_wave) as sample:
70-
//| sample.play(loop=True)
71-
//| time.sleep(1)
72-
//| sample.stop()
69+
//| sample = audioio.AudioOut(board.SPEAKER, sin_wave)
70+
//| sample.play(loop=True)
71+
//| time.sleep(1)
72+
//| sample.stop()
7373
//|
7474
//| Playing a wave file from flash::
7575
//|
@@ -136,7 +136,8 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_1(audioio_audioout_deinit_obj, audioio_audioout_d
136136

137137
//| .. method:: __exit__()
138138
//|
139-
//| Automatically deinitializes the hardware when exiting a context.
139+
//| Automatically deinitializes the hardware when exiting a context. See
140+
//| :ref:`lifetime-and-contextmanagers` for more info.
140141
//|
141142
STATIC mp_obj_t audioio_audioout_obj___exit__(size_t n_args, const mp_obj_t *args) {
142143
(void)n_args;

‎shared-bindings/audioio/__init__.c‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -49,9 +49,10 @@
4949
//|
5050
//| AudioOut
5151
//|
52-
//| All libraries change hardware state and should be deinitialized when they
53-
//| are no longer needed. To do so, either call :py:meth:`!deinit` or use a
54-
//| context manager.
52+
//| All classes change hardware state and should be deinitialized when they
53+
//| are no longer needed if the program continues after use. To do so, either
54+
//| call :py:meth:`!deinit` or use a context manager. See
55+
//| :ref:`lifetime-and-contextmanagers` for more info.
5556
//|
5657

5758
STATIC const mp_rom_map_elem_t audioio_module_globals_table[] = {

‎shared-bindings/bitbangio/I2C.c‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -90,7 +90,8 @@ MP_DEFINE_CONST_FUN_OBJ_1(bitbangio_i2c_deinit_obj, bitbangio_i2c_obj_deinit);
9090

9191
//| .. method:: I2C.__exit__()
9292
//|
93-
//| Automatically deinitializes the hardware on context exit.
93+
//| Automatically deinitializes the hardware on context exit. See
94+
//| :ref:`lifetime-and-contextmanagers` for more info.
9495
//|
9596
STATIC mp_obj_t bitbangio_i2c_obj___exit__(size_t n_args, const mp_obj_t *args) {
9697
(void)n_args;

‎shared-bindings/bitbangio/OneWire.c‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -55,11 +55,11 @@
5555
//| import bitbangio
5656
//| import board
5757
//|
58-
//| with bitbangio.OneWire(board.D7) as onewire:
59-
//| onewire.reset()
60-
//| onewire.write_bit(True)
61-
//| onewire.write_bit(False)
62-
//| print(onewire.read_bit())
58+
//| onewire = bitbangio.OneWire(board.D7)
59+
//| onewire.reset()
60+
//| onewire.write_bit(True)
61+
//| onewire.write_bit(False)
62+
//| print(onewire.read_bit())
6363
//|
6464
STATIC mp_obj_t bitbangio_onewire_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *pos_args) {
6565
mp_arg_check_num(n_args, n_kw, 1, MP_OBJ_FUN_ARGS_MAX, true);
@@ -101,7 +101,8 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_1(bitbangio_onewire_deinit_obj, bitbangio_onewire
101101

102102
//| .. method:: __exit__()
103103
//|
104-
//| Automatically deinitializes the hardware when exiting a context.
104+
//| Automatically deinitializes the hardware when exiting a context. See
105+
//| :ref:`lifetime-and-contextmanagers` for more info.
105106
//|
106107
STATIC mp_obj_t bitbangio_onewire_obj___exit__(size_t n_args, const mp_obj_t *args) {
107108
(void)n_args;

‎shared-bindings/bitbangio/SPI.c‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -102,7 +102,8 @@ MP_DEFINE_CONST_FUN_OBJ_1(bitbangio_spi_deinit_obj, bitbangio_spi_obj_deinit);
102102

103103
//| .. method:: SPI.__exit__()
104104
//|
105-
//| Automatically deinitializes the hardware when exiting a context.
105+
//| Automatically deinitializes the hardware when exiting a context. See
106+
//| :ref:`lifetime-and-contextmanagers` for more info.
106107
//|
107108
STATIC mp_obj_t bitbangio_spi_obj___exit__(size_t n_args, const mp_obj_t *args) {
108109
(void)n_args;

0 commit comments

Comments
 (0)