Skip to content

Commit 55bdee6

Browse files
evaherradaevaherrada
committed
Reorganized pyi again
1 parent 855c203 commit 55bdee6

1 file changed

Lines changed: 112 additions & 125 deletions

File tree

  • shared-bindings/busio

‎shared-bindings/busio/SPI.c‎

Lines changed: 112 additions & 125 deletions
Original file line numberDiff line numberDiff line change
@@ -41,44 +41,44 @@
4141
#include "supervisor/shared/translate.h"
4242

4343

44-
//| .. currentmodule:: busio
44+
//|class SPI:
45+
//| """.. currentmodule:: busio
4546
//|
46-
//| :class:`SPI` -- a 3-4 wire serial protocol
47-
//| -----------------------------------------------
47+
//| `SPI` -- a 3-4 wire serial protocol
48+
//| -----------------------------------------------
4849
//|
49-
//| SPI is a serial protocol that has exclusive pins for data in and out of the
50-
//| master. It is typically faster than :py:class:`~busio.I2C` because a
51-
//| separate pin is used to control the active slave rather than a transitted
52-
//| address. This class only manages three of the four SPI lines: `!clock`,
53-
//| `!MOSI`, `!MISO`. Its up to the client to manage the appropriate slave
54-
//| select line. (This is common because multiple slaves can share the `!clock`,
55-
//| `!MOSI` and `!MISO` lines and therefore the hardware.)
50+
//| SPI is a serial protocol that has exclusive pins for data in and out of the
51+
//| master. It is typically faster than :py:class:`~busio.I2C` because a
52+
//| separate pin is used to control the active slave rather than a transitted
53+
//| address. This class only manages three of the four SPI lines: `!clock`,
54+
//| `!MOSI`, `!MISO`. Its up to the client to manage the appropriate slave
55+
//| select line. (This is common because multiple slaves can share the `!clock`,
56+
//| `!MOSI` and `!MISO` lines and therefore the hardware.)"""
5657
//|
57-
//| .. class:: SPI(clock, MOSI=None, MISO=None)
58+
//| def __init__(self, clock: microcontroller.Pin, MOSI: microcontroller.Pin = None, MISO: microcontroller.Pin = None):
5859
//|
59-
//| Construct an SPI object on the given pins.
60+
//| """Construct an SPI object on the given pins.
6061
//|
61-
//| ..note:: The SPI peripherals allocated in order of desirability, if possible,
62-
//| such as highest speed and not shared use first. For instance, on the nRF52840,
63-
//| there is a single 32MHz SPI peripheral, and multiple 8MHz peripherals,
64-
//| some of which may also be used for I2C. The 32MHz SPI peripheral is returned
65-
//| first, then the exclusive 8MHz SPI peripheral, and finally the shared 8MHz
66-
//| peripherals.
62+
//| ..note:: The SPI peripherals allocated in order of desirability, if possible,
63+
//| such as highest speed and not shared use first. For instance, on the nRF52840,
64+
//| there is a single 32MHz SPI peripheral, and multiple 8MHz peripherals,
65+
//| some of which may also be used for I2C. The 32MHz SPI peripheral is returned
66+
//| first, then the exclusive 8MHz SPI peripheral, and finally the shared 8MHz
67+
//| peripherals.
6768
//|
68-
//| .. seealso:: Using this class directly requires careful lock management.
69-
//| Instead, use :class:`~adafruit_bus_device.spi_device.SPIDevice` to
70-
//| manage locks.
69+
//| .. seealso:: Using this class directly requires careful lock management.
70+
//| Instead, use :class:`~adafruit_bus_device.spi_device.SPIDevice` to
71+
//| manage locks.
7172
//|
72-
//| .. seealso:: Using this class to directly read registers requires manual
73-
//| bit unpacking. Instead, use an existing driver or make one with
74-
//| :ref:`Register <register-module-reference>` data descriptors.
73+
//| .. seealso:: Using this class to directly read registers requires manual
74+
//| bit unpacking. Instead, use an existing driver or make one with
75+
//| :ref:`Register <register-module-reference>` data descriptors.
7576
//|
76-
//| :param ~microcontroller.Pin clock: the pin to use for the clock.
77-
//| :param ~microcontroller.Pin MOSI: the Master Out Slave In pin.
78-
//| :param ~microcontroller.Pin MISO: the Master In Slave Out pin.
79-
//|
80-
// class SPI:
81-
// def __init__(self, clock: microcontroller.Pin, MOSI: microcontroller.Pin = None, MISO: microcontroller.Pin = None): ...
77+
//| :param ~microcontroller.Pin clock: the pin to use for the clock.
78+
//| :param ~microcontroller.Pin MOSI: the Master Out Slave In pin.
79+
//| :param ~microcontroller.Pin MISO: the Master In Slave Out pin."""
80+
//| ...
81+
8282

8383
// TODO(tannewt): Support LSB SPI.
8484
STATIC mp_obj_t busio_spi_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
@@ -101,31 +101,25 @@ STATIC mp_obj_t busio_spi_make_new(const mp_obj_type_t *type, size_t n_args, con
101101
return MP_OBJ_FROM_PTR(self);
102102
}
103103

104-
//| .. method:: deinit()
105-
//|
106-
//| Turn off the SPI bus.
107-
//|
108-
// def deinit(self, ) -> Any: ...
104+
//| def deinit(self, ) -> Any:
105+
//| """Turn off the SPI bus."""
106+
//| ...
109107
STATIC mp_obj_t busio_spi_obj_deinit(mp_obj_t self_in) {
110108
busio_spi_obj_t *self = MP_OBJ_TO_PTR(self_in);
111109
common_hal_busio_spi_deinit(self);
112110
return mp_const_none;
113111
}
114112
MP_DEFINE_CONST_FUN_OBJ_1(busio_spi_deinit_obj, busio_spi_obj_deinit);
115113

116-
//| .. method:: __enter__()
117-
//|
118-
//| No-op used by Context Managers.
119-
//|
120-
// Provided by context manager helper.
121-
// def __enter__(self, ) -> Any: ...
114+
//| def __enter__(self, ) -> Any:
115+
//| """No-op used by Context Managers.
116+
//| Provided by context manager helper."""
117+
//| ...
122118

123-
//| .. method:: __exit__()
124-
//|
125-
//| Automatically deinitializes the hardware when exiting a context. See
126-
//| :ref:`lifetime-and-contextmanagers` for more info.
127-
//|
128-
// def __exit__(self, ) -> Any: ...
119+
//| def __exit__(self, ) -> Any:
120+
//| """Automatically deinitializes the hardware when exiting a context. See
121+
//| :ref:`lifetime-and-contextmanagers` for more info."""
122+
//| ...
129123
STATIC mp_obj_t busio_spi_obj___exit__(size_t n_args, const mp_obj_t *args) {
130124
(void)n_args;
131125
common_hal_busio_spi_deinit(args[0]);
@@ -146,30 +140,29 @@ STATIC void check_for_deinit(busio_spi_obj_t *self) {
146140
}
147141
}
148142

149-
//| .. method:: configure(*, baudrate=100000, polarity=0, phase=0, bits=8)
150-
//|
151-
//| Configures the SPI bus. The SPI object must be locked.
152-
//|
153-
//| :param int baudrate: the desired clock rate in Hertz. The actual clock rate may be higher or lower
154-
//| due to the granularity of available clock settings.
155-
//| Check the `frequency` attribute for the actual clock rate.
156-
//| :param int polarity: the base state of the clock line (0 or 1)
157-
//| :param int phase: the edge of the clock that data is captured. First (0)
158-
//| or second (1). Rising or falling depends on clock polarity.
159-
//| :param int bits: the number of bits per word
160-
//|
161-
//| .. note:: On the SAMD21, it is possible to set the baudrate to 24 MHz, but that
162-
//| speed is not guaranteed to work. 12 MHz is the next available lower speed, and is
163-
//| within spec for the SAMD21.
164-
//|
165-
//| .. note:: On the nRF52840, these baudrates are available: 125kHz, 250kHz, 1MHz, 2MHz, 4MHz,
166-
//| and 8MHz.
167-
//| If you pick a a baudrate other than one of these, the nearest lower
168-
//| baudrate will be chosen, with a minimum of 125kHz.
169-
//| Two SPI objects may be created, except on the Circuit Playground Bluefruit,
170-
//| which allows only one (to allow for an additional I2C object).
171-
//|
172-
// def configure(self, *, baudrate: int = 100000, polarity: int = 0, phase: int = 0, bits: int = 8) -> Any: ...
143+
//| def configure(self, *, baudrate: int = 100000, polarity: int = 0, phase: int = 0, bits: int = 8) -> Any:
144+
//| """Configures the SPI bus. The SPI object must be locked.
145+
//|
146+
//| :param int baudrate: the desired clock rate in Hertz. The actual clock rate may be higher or lower
147+
//| due to the granularity of available clock settings.
148+
//| Check the `frequency` attribute for the actual clock rate.
149+
//| :param int polarity: the base state of the clock line (0 or 1)
150+
//| :param int phase: the edge of the clock that data is captured. First (0)
151+
//| or second (1). Rising or falling depends on clock polarity.
152+
//| :param int bits: the number of bits per word
153+
//|
154+
//| .. note:: On the SAMD21, it is possible to set the baudrate to 24 MHz, but that
155+
//| speed is not guaranteed to work. 12 MHz is the next available lower speed, and is
156+
//| within spec for the SAMD21.
157+
//|
158+
//| .. note:: On the nRF52840, these baudrates are available: 125kHz, 250kHz, 1MHz, 2MHz, 4MHz,
159+
//| and 8MHz.
160+
//| If you pick a a baudrate other than one of these, the nearest lower
161+
//| baudrate will be chosen, with a minimum of 125kHz.
162+
//| Two SPI objects may be created, except on the Circuit Playground Bluefruit,
163+
//| which allows only one (to allow for an additional I2C object)."""
164+
//| ...
165+
173166
STATIC mp_obj_t busio_spi_configure(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
174167
enum { ARG_baudrate, ARG_polarity, ARG_phase, ARG_bits };
175168
static const mp_arg_t allowed_args[] = {
@@ -205,25 +198,23 @@ STATIC mp_obj_t busio_spi_configure(size_t n_args, const mp_obj_t *pos_args, mp_
205198
}
206199
MP_DEFINE_CONST_FUN_OBJ_KW(busio_spi_configure_obj, 1, busio_spi_configure);
207200

208-
//| .. method:: try_lock()
209-
//|
210-
//| Attempts to grab the SPI lock. Returns True on success.
201+
//| def try_lock(self, ) -> Any:
202+
//| """Attempts to grab the SPI lock. Returns True on success.
211203
//|
212-
//| :return: True when lock has been grabbed
213-
//| :rtype: bool
214-
//|
215-
// def try_lock(self, ) -> Any: ...
204+
//| :return: True when lock has been grabbed
205+
//| :rtype: bool"""
206+
//| ...
207+
216208
STATIC mp_obj_t busio_spi_obj_try_lock(mp_obj_t self_in) {
217209
busio_spi_obj_t *self = MP_OBJ_TO_PTR(self_in);
218210
return mp_obj_new_bool(common_hal_busio_spi_try_lock(self));
219211
}
220212
MP_DEFINE_CONST_FUN_OBJ_1(busio_spi_try_lock_obj, busio_spi_obj_try_lock);
221213

222-
//| .. method:: unlock()
223-
//|
224-
//| Releases the SPI lock.
225-
//|
226-
// def unlock(self, ) -> Any: ...
214+
//| def unlock(self, ) -> Any:
215+
//| """Releases the SPI lock."""
216+
//| ...
217+
227218
STATIC mp_obj_t busio_spi_obj_unlock(mp_obj_t self_in) {
228219
busio_spi_obj_t *self = MP_OBJ_TO_PTR(self_in);
229220
check_for_deinit(self);
@@ -232,16 +223,15 @@ STATIC mp_obj_t busio_spi_obj_unlock(mp_obj_t self_in) {
232223
}
233224
MP_DEFINE_CONST_FUN_OBJ_1(busio_spi_unlock_obj, busio_spi_obj_unlock);
234225

235-
//| .. method:: write(buffer, *, start=0, end=None)
236-
//|
237-
//| Write the data contained in ``buffer``. The SPI object must be locked.
238-
//| If the buffer is empty, nothing happens.
226+
//| def write(self, buffer: bytearray, *, start: Any = 0, end: int = None) -> Any: ...
227+
//| """Write the data contained in ``buffer``. The SPI object must be locked.
228+
//| If the buffer is empty, nothing happens.
239229
//|
240-
//| :param bytearray buffer: Write out the data in this buffer
241-
//| :param int start: Start of the slice of ``buffer`` to write out: ``buffer[start:end]``
242-
//| :param int end: End of the slice; this index is not included. Defaults to ``len(buffer)``
243-
//|
244-
// def write(self, buffer: bytearray, *, start: Any = 0, end: int = None) -> Any: ...
230+
//| :param bytearray buffer: Write out the data in this buffer
231+
//| :param int start: Start of the slice of ``buffer`` to write out: ``buffer[start:end]``
232+
//| :param int end: End of the slice; this index is not included. Defaults to ``len(buffer)``"""
233+
//| ...
234+
245235
STATIC mp_obj_t busio_spi_write(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
246236
enum { ARG_buffer, ARG_start, ARG_end };
247237
static const mp_arg_t allowed_args[] = {
@@ -274,18 +264,17 @@ STATIC mp_obj_t busio_spi_write(size_t n_args, const mp_obj_t *pos_args, mp_map_
274264
MP_DEFINE_CONST_FUN_OBJ_KW(busio_spi_write_obj, 2, busio_spi_write);
275265

276266

277-
//| .. method:: readinto(buffer, *, start=0, end=None, write_value=0)
278-
//|
279-
//| Read into ``buffer`` while writing ``write_value`` for each byte read.
280-
//| The SPI object must be locked.
281-
//| If the number of bytes to read is 0, nothing happens.
282-
//|
283-
//| :param bytearray buffer: Read data into this buffer
284-
//| :param int start: Start of the slice of ``buffer`` to read into: ``buffer[start:end]``
285-
//| :param int end: End of the slice; this index is not included. Defaults to ``len(buffer)``
286-
//| :param int write_value: Value to write while reading. (Usually ignored.)
267+
//| def readinto(self, buffer: bytearray, *, start: Any = 0, end: int = None, write_value: int = 0) -> Any:
268+
//| """Read into ``buffer`` while writing ``write_value`` for each byte read.
269+
//| The SPI object must be locked.
270+
//| If the number of bytes to read is 0, nothing happens.
287271
//|
288-
// def readinto(self, buffer: bytearray, *, start: Any = 0, end: int = None, write_value: int = 0) -> Any: ...
272+
//| :param bytearray buffer: Read data into this buffer
273+
//| :param int start: Start of the slice of ``buffer`` to read into: ``buffer[start:end]``
274+
//| :param int end: End of the slice; this index is not included. Defaults to ``len(buffer)``
275+
//| :param int write_value: Value to write while reading. (Usually ignored.)"""
276+
//| ...
277+
289278
STATIC mp_obj_t busio_spi_readinto(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
290279
enum { ARG_buffer, ARG_start, ARG_end, ARG_write_value };
291280
static const mp_arg_t allowed_args[] = {
@@ -318,22 +307,21 @@ STATIC mp_obj_t busio_spi_readinto(size_t n_args, const mp_obj_t *pos_args, mp_m
318307
}
319308
MP_DEFINE_CONST_FUN_OBJ_KW(busio_spi_readinto_obj, 2, busio_spi_readinto);
320309

321-
//| .. method:: write_readinto(buffer_out, buffer_in, *, out_start=0, out_end=None, in_start=0, in_end=None)
322-
//|
323-
//| Write out the data in ``buffer_out`` while simultaneously reading data into ``buffer_in``.
324-
//| The SPI object must be locked.
325-
//| The lengths of the slices defined by ``buffer_out[out_start:out_end]`` and ``buffer_in[in_start:in_end]``
326-
//| must be equal.
327-
//| If buffer slice lengths are both 0, nothing happens.
328-
//|
329-
//| :param bytearray buffer_out: Write out the data in this buffer
330-
//| :param bytearray buffer_in: Read data into this buffer
331-
//| :param int out_start: Start of the slice of buffer_out to write out: ``buffer_out[out_start:out_end]``
332-
//| :param int out_end: End of the slice; this index is not included. Defaults to ``len(buffer_out)``
333-
//| :param int in_start: Start of the slice of ``buffer_in`` to read into: ``buffer_in[in_start:in_end]``
334-
//| :param int in_end: End of the slice; this index is not included. Defaults to ``len(buffer_in)``
335-
//|
336-
// def write_readinto(self, buffer_out: bytearray, buffer_in: bytearray, *, out_start: Any = 0, out_end: int = None, in_start: Any = 0, in_end: int = None) -> Any: ...
310+
//| def write_readinto(self, buffer_out: bytearray, buffer_in: bytearray, *, out_start: Any = 0, out_end: int = None, in_start: Any = 0, in_end: int = None) -> Any:
311+
//| """Write out the data in ``buffer_out`` while simultaneously reading data into ``buffer_in``.
312+
//| The SPI object must be locked.
313+
//| The lengths of the slices defined by ``buffer_out[out_start:out_end]`` and ``buffer_in[in_start:in_end]``
314+
//| must be equal.
315+
//| If buffer slice lengths are both 0, nothing happens.
316+
//|
317+
//| :param bytearray buffer_out: Write out the data in this buffer
318+
//| :param bytearray buffer_in: Read data into this buffer
319+
//| :param int out_start: Start of the slice of buffer_out to write out: ``buffer_out[out_start:out_end]``
320+
//| :param int out_end: End of the slice; this index is not included. Defaults to ``len(buffer_out)``
321+
//| :param int in_start: Start of the slice of ``buffer_in`` to read into: ``buffer_in[in_start:in_end]``
322+
//| :param int in_end: End of the slice; this index is not included. Defaults to ``len(buffer_in)``"""
323+
//| ...
324+
337325
STATIC mp_obj_t busio_spi_write_readinto(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
338326
enum { ARG_buffer_out, ARG_buffer_in, ARG_out_start, ARG_out_end, ARG_in_start, ARG_in_end };
339327
static const mp_arg_t allowed_args[] = {
@@ -381,12 +369,11 @@ STATIC mp_obj_t busio_spi_write_readinto(size_t n_args, const mp_obj_t *pos_args
381369
}
382370
MP_DEFINE_CONST_FUN_OBJ_KW(busio_spi_write_readinto_obj, 2, busio_spi_write_readinto);
383371

384-
//| .. attribute:: frequency
385-
//|
386-
//| The actual SPI bus frequency. This may not match the frequency requested
387-
//| due to internal limitations.
388-
//|
389-
// frequency: Any = ...
372+
//| frequency: Any =
373+
//| """The actual SPI bus frequency. This may not match the frequency requested
374+
//| due to internal limitations."""
375+
//| ...
376+
390377
STATIC mp_obj_t busio_spi_obj_get_frequency(mp_obj_t self_in) {
391378
busio_spi_obj_t *self = MP_OBJ_TO_PTR(self_in);
392379
check_for_deinit(self);

0 commit comments

Comments
 (0)