From bd3c36ce6d3b440dcb7591cacccbd2bc72a2268c Mon Sep 17 00:00:00 2001 From: Scott Shawcroft Date: Mon, 14 Jan 2019 18:08:45 -0800 Subject: fixup m0 and nrf --- shared-bindings/socket/__init__.c | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) (limited to 'shared-bindings/socket/__init__.c') diff --git a/shared-bindings/socket/__init__.c b/shared-bindings/socket/__init__.c index d860c40c8..29d47de56 100644 --- a/shared-bindings/socket/__init__.c +++ b/shared-bindings/socket/__init__.c @@ -39,20 +39,20 @@ //| :mod:`socket` --- TCP, UDP and RAW socket support //| ================================================= -//| +//| //| .. module:: socket //| :synopsis: TCP, UDP and RAW sockets //| :platform: SAMD21, SAMD51 //| //| Create TCP, UDP and RAW sockets for communicating over the Internet. -//| +//| STATIC const mp_obj_type_t socket_type; //| .. currentmodule:: socket //| //| .. class:: socket(family, type, proto, ...) -//| +//| //| Create a new socket //| //| :param ~int family: AF_INET or AF_INET6 @@ -60,8 +60,8 @@ STATIC const mp_obj_type_t socket_type; //| :param ~int proto: IPPROTO_TCP, IPPROTO_UDP or IPPROTO_RAW (ignored) //| -STATIC mp_obj_t socket_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *args) { - mp_arg_check_num(n_args, n_kw, 0, 4, false); +STATIC mp_obj_t socket_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *args, mp_map_t *kw_args) { + mp_arg_check_num(n_args, kw_args, 0, 4, false); // create socket object (not bound to any NIC yet) mod_network_socket_obj_t *s = m_new_obj_with_finaliser(mod_network_socket_obj_t); @@ -245,8 +245,8 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_2(socket_send_obj, socket_send); //| Reads some bytes from the connected remote address. //| Suits sockets of type SOCK_STREAM //| Returns a bytes() of length <= bufsize -//| -//| :param ~int bufsize: maximum number of bytes to receive +//| +//| :param ~int bufsize: maximum number of bytes to receive STATIC mp_obj_t socket_recv(mp_obj_t self_in, mp_obj_t len_in) { mod_network_socket_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -313,7 +313,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_3(socket_sendto_obj, socket_sendto); //| * a bytes() of length <= bufsize //| * a remote_address, which is a tuple of ip address and port number //| -//| :param ~int bufsize: maximum number of bytes to receive +//| :param ~int bufsize: maximum number of bytes to receive //| STATIC mp_obj_t socket_recvfrom(mp_obj_t self_in, mp_obj_t len_in) { @@ -469,10 +469,10 @@ STATIC const mp_obj_type_t socket_type = { }; //| .. function:: getaddrinfo(host, port) -//| +//| //| Gets the address information for a hostname and port //| -//| Returns the appropriate family, socket type, socket protocol and +//| Returns the appropriate family, socket type, socket protocol and //| address information to call socket.socket() and socket.connect() with, //| as a tuple. //| -- cgit v1.2.3 From e23bad3a3af2c334573d6233508cf2fd3b111b66 Mon Sep 17 00:00:00 2001 From: Joshua Coats Date: Sat, 23 Mar 2019 10:49:43 -0700 Subject: shared-bindings/socket: add socket_recv_into --- shared-bindings/socket/__init__.c | 53 +++++++++++++++++++++++++++++++++++---- 1 file changed, 48 insertions(+), 5 deletions(-) (limited to 'shared-bindings/socket/__init__.c') diff --git a/shared-bindings/socket/__init__.c b/shared-bindings/socket/__init__.c index 29d47de56..c59724efc 100644 --- a/shared-bindings/socket/__init__.c +++ b/shared-bindings/socket/__init__.c @@ -240,6 +240,52 @@ STATIC mp_obj_t socket_send(mp_obj_t self_in, mp_obj_t buf_in) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(socket_send_obj, socket_send); + +// helper function for socket_recv and socket_recv_into to handle common operations of both +STATIC mp_int_t _socket_recv_into(mod_network_socket_obj_t *sock, byte *buf, mp_int_t len) { + int _errno; + mp_int_t ret = sock->nic_type->recv(sock, buf, len, &_errno); + if (ret == -1) { + mp_raise_OSError(_errno); + } + return len; +} + + +//| .. method:: recv_into(buffer[, bufsize]) +//| +//| Reads some bytes from the connected remote address, writing +//| into the provided buffer. If bufsize <= len(buffer) is given, +//| a maximum of bufsize bytes will be read into the buffer. If no +//| valid value is given for bufsize, the default is the length of +//| the given buffer. +//| +//| Suits sockets of type SOCK_STREAM +//| Returns an int of number of bytes read. +//| +//| :param bytearray buffer: buffer to receive into +//| :param int bufsize: optionally, a maximum number of bytes to read. + +STATIC mp_obj_t socket_recv_into(size_t n_args, const mp_obj_t *args) { + mod_network_socket_obj_t *self = MP_OBJ_TO_PTR(args[0]); + if (self->nic == MP_OBJ_NULL) { + // not connected + mp_raise_OSError(MP_ENOTCONN); + } + mp_buffer_info_t bufinfo; + mp_get_buffer_raise(args[1], &bufinfo, MP_BUFFER_WRITE); + mp_int_t len; + if (n_args == 3) { + len = mp_obj_get_int(args[2]); + } + if (n_args == 2 || (size_t) len > bufinfo.len) { + len = bufinfo.len; + } + mp_int_t ret = _socket_recv_into(self, (byte*)bufinfo.buf, len); + return mp_obj_new_int_from_uint(ret); +} +STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(socket_recv_into_obj, 2, 3, socket_recv_into); + //| .. method:: recv(bufsize) //| //| Reads some bytes from the connected remote address. @@ -257,11 +303,7 @@ STATIC mp_obj_t socket_recv(mp_obj_t self_in, mp_obj_t len_in) { mp_int_t len = mp_obj_get_int(len_in); vstr_t vstr; vstr_init_len(&vstr, len); - int _errno; - mp_int_t ret = self->nic_type->recv(self, (byte*)vstr.buf, len, &_errno); - if (ret == -1) { - mp_raise_OSError(_errno); - } + mp_int_t ret = _socket_recv_into(self, (byte*)vstr.buf, len); if (ret == 0) { return mp_const_empty_bytes; } @@ -436,6 +478,7 @@ STATIC const mp_rom_map_elem_t socket_locals_dict_table[] = { { MP_ROM_QSTR(MP_QSTR_recv), MP_ROM_PTR(&socket_recv_obj) }, { MP_ROM_QSTR(MP_QSTR_sendto), MP_ROM_PTR(&socket_sendto_obj) }, { MP_ROM_QSTR(MP_QSTR_recvfrom), MP_ROM_PTR(&socket_recvfrom_obj) }, + { MP_ROM_QSTR(MP_QSTR_recv_into), MP_ROM_PTR(&socket_recv_into_obj) }, { MP_ROM_QSTR(MP_QSTR_setsockopt), MP_ROM_PTR(&socket_setsockopt_obj) }, { MP_ROM_QSTR(MP_QSTR_settimeout), MP_ROM_PTR(&socket_settimeout_obj) }, { MP_ROM_QSTR(MP_QSTR_setblocking), MP_ROM_PTR(&socket_setblocking_obj) }, -- cgit v1.2.3 From 58d1d997013c717d5b6e17d53aa44eb5940c202a Mon Sep 17 00:00:00 2001 From: Nick Moore Date: Tue, 16 Apr 2019 17:57:05 +1000 Subject: Fix socket.recv() buffer length from e23bad3a --- shared-bindings/socket/__init__.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'shared-bindings/socket/__init__.c') diff --git a/shared-bindings/socket/__init__.c b/shared-bindings/socket/__init__.c index c59724efc..8e34c3700 100644 --- a/shared-bindings/socket/__init__.c +++ b/shared-bindings/socket/__init__.c @@ -248,7 +248,7 @@ STATIC mp_int_t _socket_recv_into(mod_network_socket_obj_t *sock, byte *buf, mp_ if (ret == -1) { mp_raise_OSError(_errno); } - return len; + return ret; } -- cgit v1.2.3 From f29de5132562cd6e88661d150fa1ee3ab8b771e1 Mon Sep 17 00:00:00 2001 From: Scott Shawcroft Date: Mon, 13 May 2019 17:31:30 -0700 Subject: Check native object in case of early access If a native displayio object is accessed before it's super().__init__() has been called, then a placeholder is given that will cause a crash if accessed. This is tricky to get right so we detect this case and raise a NotInplementedError instead of crashing. Fixes #1881 --- py/objtype.c | 10 ++++++++++ py/objtype.h | 2 ++ shared-bindings/_stage/__init__.c | 1 + shared-bindings/displayio/Display.c | 8 +++----- shared-bindings/displayio/Group.c | 7 ++++++- shared-bindings/displayio/Group.h | 1 + shared-bindings/displayio/TileGrid.c | 2 ++ shared-bindings/socket/__init__.c | 13 +++++++------ 8 files changed, 32 insertions(+), 12 deletions(-) (limited to 'shared-bindings/socket/__init__.c') diff --git a/py/objtype.c b/py/objtype.c index 88e918827..5133d849f 100644 --- a/py/objtype.c +++ b/py/objtype.c @@ -117,6 +117,16 @@ mp_obj_instance_t *mp_obj_new_instance(const mp_obj_type_t *class, const mp_obj_ return o; } +// When instances are first created they have the base_init wrapper as their native parent's +// instance because make_new combines __new__ and __init__. This object is invalid for the native +// code so it must call this method to ensure that the given object has been __init__'d and is +// valid. +void mp_obj_assert_native_inited(mp_obj_t native_object) { + if (native_object == MP_OBJ_FROM_PTR(&native_base_init_wrapper_obj)) { + mp_raise_NotImplementedError(translate("Call super().__init__() before accessing native object.")); + } +} + // TODO // This implements depth-first left-to-right MRO, which is not compliant with Python3 MRO // http://python-history.blogspot.com/2010/06/method-resolution-order.html diff --git a/py/objtype.h b/py/objtype.h index 13613f01f..a32c87496 100644 --- a/py/objtype.h +++ b/py/objtype.h @@ -37,6 +37,8 @@ typedef struct _mp_obj_instance_t { // TODO maybe cache __getattr__ and __setattr__ for efficient lookup of them } mp_obj_instance_t; +void mp_obj_assert_native_inited(mp_obj_t native_object); + #if MICROPY_CPYTHON_COMPAT // this is needed for object.__new__ mp_obj_instance_t *mp_obj_new_instance(const mp_obj_type_t *cls, const mp_obj_type_t **native_base); diff --git a/shared-bindings/_stage/__init__.c b/shared-bindings/_stage/__init__.c index 03775b1de..be8315efe 100644 --- a/shared-bindings/_stage/__init__.c +++ b/shared-bindings/_stage/__init__.c @@ -85,6 +85,7 @@ STATIC mp_obj_t stage_render(size_t n_args, const mp_obj_t *args) { mp_obj_t native_display = mp_instance_cast_to_native_base(args[6], &displayio_display_type); + mp_obj_assert_native_inited(native_display); if (!MP_OBJ_IS_TYPE(native_display, &displayio_display_type)) { mp_raise_TypeError(translate("argument num/types mismatch")); } diff --git a/shared-bindings/displayio/Display.c b/shared-bindings/displayio/Display.c index 52ab2ef31..84302a175 100644 --- a/shared-bindings/displayio/Display.c +++ b/shared-bindings/displayio/Display.c @@ -31,6 +31,7 @@ #include "lib/utils/context_manager_helpers.h" #include "py/binary.h" #include "py/objproperty.h" +#include "py/objtype.h" #include "py/runtime.h" #include "shared-bindings/displayio/Group.h" #include "shared-bindings/microcontroller/Pin.h" @@ -172,6 +173,7 @@ STATIC mp_obj_t displayio_display_make_new(const mp_obj_type_t *type, size_t n_a // Helper to ensure we have the native super class instead of a subclass. static displayio_display_obj_t* native_display(mp_obj_t display_obj) { mp_obj_t native_display = mp_instance_cast_to_native_base(display_obj, &displayio_display_type); + mp_obj_assert_native_inited(native_display); return MP_OBJ_TO_PTR(native_display); } @@ -184,11 +186,7 @@ STATIC mp_obj_t displayio_display_obj_show(mp_obj_t self_in, mp_obj_t group_in) displayio_display_obj_t *self = native_display(self_in); displayio_group_t* group = NULL; if (group_in != mp_const_none) { - mp_obj_t native_layer = mp_instance_cast_to_native_base(group_in, &displayio_group_type); - if (native_layer == MP_OBJ_NULL) { - mp_raise_ValueError(translate("Must be a Group subclass.")); - } - group = MP_OBJ_TO_PTR(native_layer); + group = MP_OBJ_TO_PTR(native_group(group_in)); } common_hal_displayio_display_show(self, group); diff --git a/shared-bindings/displayio/Group.c b/shared-bindings/displayio/Group.c index c7a72891a..bbf7190a3 100644 --- a/shared-bindings/displayio/Group.c +++ b/shared-bindings/displayio/Group.c @@ -31,6 +31,7 @@ #include "lib/utils/context_manager_helpers.h" #include "py/binary.h" #include "py/objproperty.h" +#include "py/objtype.h" #include "py/runtime.h" #include "supervisor/shared/translate.h" @@ -80,8 +81,12 @@ STATIC mp_obj_t displayio_group_make_new(const mp_obj_type_t *type, size_t n_arg } // Helper to ensure we have the native super class instead of a subclass. -static displayio_group_t* native_group(mp_obj_t group_obj) { +displayio_group_t* native_group(mp_obj_t group_obj) { mp_obj_t native_group = mp_instance_cast_to_native_base(group_obj, &displayio_group_type); + if (native_group == MP_OBJ_NULL) { + mp_raise_ValueError_varg(translate("Must be a %q subclass."), MP_QSTR_Group); + } + mp_obj_assert_native_inited(native_group); return MP_OBJ_TO_PTR(native_group); } diff --git a/shared-bindings/displayio/Group.h b/shared-bindings/displayio/Group.h index fa3c32964..0570735cf 100644 --- a/shared-bindings/displayio/Group.h +++ b/shared-bindings/displayio/Group.h @@ -31,6 +31,7 @@ extern const mp_obj_type_t displayio_group_type; +displayio_group_t* native_group(mp_obj_t group_obj); void common_hal_displayio_group_construct(displayio_group_t* self, uint32_t max_size, uint32_t scale, mp_int_t x, mp_int_t y); uint32_t common_hal_displayio_group_get_scale(displayio_group_t* self); diff --git a/shared-bindings/displayio/TileGrid.c b/shared-bindings/displayio/TileGrid.c index 2b41eb8fd..6d18ac78f 100644 --- a/shared-bindings/displayio/TileGrid.c +++ b/shared-bindings/displayio/TileGrid.c @@ -31,6 +31,7 @@ #include "lib/utils/context_manager_helpers.h" #include "py/binary.h" #include "py/objproperty.h" +#include "py/objtype.h" #include "py/runtime.h" #include "shared-bindings/displayio/Bitmap.h" #include "shared-bindings/displayio/ColorConverter.h" @@ -139,6 +140,7 @@ STATIC mp_obj_t displayio_tilegrid_make_new(const mp_obj_type_t *type, size_t n_ // Helper to ensure we have the native super class instead of a subclass. static displayio_tilegrid_t* native_tilegrid(mp_obj_t tilegrid_obj) { mp_obj_t native_tilegrid = mp_instance_cast_to_native_base(tilegrid_obj, &displayio_tilegrid_type); + mp_obj_assert_native_inited(native_tilegrid); return MP_OBJ_TO_PTR(native_tilegrid); } diff --git a/shared-bindings/socket/__init__.c b/shared-bindings/socket/__init__.c index 8e34c3700..085d4e690 100644 --- a/shared-bindings/socket/__init__.c +++ b/shared-bindings/socket/__init__.c @@ -257,7 +257,7 @@ STATIC mp_int_t _socket_recv_into(mod_network_socket_obj_t *sock, byte *buf, mp_ //| Reads some bytes from the connected remote address, writing //| into the provided buffer. If bufsize <= len(buffer) is given, //| a maximum of bufsize bytes will be read into the buffer. If no -//| valid value is given for bufsize, the default is the length of +//| valid value is given for bufsize, the default is the length of //| the given buffer. //| //| Suits sockets of type SOCK_STREAM @@ -274,13 +274,14 @@ STATIC mp_obj_t socket_recv_into(size_t n_args, const mp_obj_t *args) { } mp_buffer_info_t bufinfo; mp_get_buffer_raise(args[1], &bufinfo, MP_BUFFER_WRITE); - mp_int_t len; + mp_int_t len = bufinfo.len; if (n_args == 3) { - len = mp_obj_get_int(args[2]); - } - if (n_args == 2 || (size_t) len > bufinfo.len) { - len = bufinfo.len; + mp_int_t given_len = mp_obj_get_int(args[2]); + if (given_len < len) { + len = given_len; + } } + mp_int_t ret = _socket_recv_into(self, (byte*)bufinfo.buf, len); return mp_obj_new_int_from_uint(ret); } -- cgit v1.2.3 From cfe24b85322a029758c3376eed2726657397bf33 Mon Sep 17 00:00:00 2001 From: Scott Shawcroft Date: Thu, 30 May 2019 19:01:27 -0700 Subject: Improve rST consistency for rst2pyi use --- shared-bindings/_pixelbuf/PixelBuf.c | 42 +++++++++++++++------------- shared-bindings/_pixelbuf/__init__.c | 38 ++++++++++++------------- shared-bindings/audiobusio/PDMIn.c | 2 +- shared-bindings/audioio/WaveFile.c | 4 +-- shared-bindings/bitbangio/I2C.c | 18 ++++++------ shared-bindings/bitbangio/SPI.c | 22 +++++++-------- shared-bindings/bleio/AddressType.c | 2 +- shared-bindings/bleio/CharacteristicBuffer.c | 2 +- shared-bindings/bleio/UUID.c | 18 ++++++++---- shared-bindings/board/__init__.c | 6 ++-- shared-bindings/busio/I2C.c | 22 +++++++-------- shared-bindings/busio/SPI.c | 26 ++++++++--------- shared-bindings/busio/UART.c | 4 +-- shared-bindings/displayio/TileGrid.c | 2 +- shared-bindings/displayio/__init__.c | 2 +- shared-bindings/help.c | 2 +- shared-bindings/microcontroller/Pin.c | 2 +- shared-bindings/microcontroller/RunMode.c | 14 +++++++--- shared-bindings/microcontroller/__init__.c | 16 ++++++----- shared-bindings/neopixel_write/__init__.c | 4 +-- shared-bindings/network/__init__.c | 2 +- shared-bindings/pulseio/PWMOut.c | 2 +- shared-bindings/pulseio/PulseIn.c | 2 +- shared-bindings/socket/__init__.c | 2 +- shared-bindings/storage/__init__.c | 6 ++-- shared-bindings/struct/__init__.c | 8 +++--- shared-bindings/time/__init__.c | 33 +++++++++++----------- shared-bindings/uheap/__init__.c | 2 +- shared-bindings/ustack/__init__.c | 6 ++-- shared-bindings/wiznet/wiznet5k.c | 2 +- 30 files changed, 165 insertions(+), 148 deletions(-) (limited to 'shared-bindings/socket/__init__.c') diff --git a/shared-bindings/_pixelbuf/PixelBuf.c b/shared-bindings/_pixelbuf/PixelBuf.c index 7c2766aa3..420720e62 100644 --- a/shared-bindings/_pixelbuf/PixelBuf.c +++ b/shared-bindings/_pixelbuf/PixelBuf.c @@ -51,7 +51,7 @@ extern const int32_t colorwheel(float pos); //| //| :class:`~_pixelbuf.PixelBuf` implements an RGB[W] bytearray abstraction. //| -//| .. class:: PixelBuf(size, buf, byteorder=BGR, bpp=3) +//| .. class:: PixelBuf(size, buf, byteorder=BGR, brightness=0, rawbuf=None, offset=0, dotstar=False, auto_write=False, write_function=None, write_args=None) //| //| Create a PixelBuf object of the specified size, byteorder, and bits per pixel. //| @@ -66,14 +66,14 @@ extern const int32_t colorwheel(float pos); //| //| :param ~int size: Number of pixelsx //| :param ~bytearray buf: Bytearray to store pixel data in -//| :param ~_pixelbuf.ByteOrder byteorder: Byte order constant from `_pixelbuf` (also sets the bpp) +//| :param ~_pixelbuf.ByteOrder byteorder: Byte order constant from `_pixelbuf` //| :param ~float brightness: Brightness (0 to 1.0, default 1.0) //| :param ~bytearray rawbuf: Bytearray to store raw pixel colors in //| :param ~int offset: Offset from start of buffer (default 0) //| :param ~bool dotstar: Dotstar mode (default False) //| :param ~bool auto_write: Whether to automatically write pixels (Default False) //| :param ~callable write_function: (optional) Callable to use to send pixels -//| :param ~list write_args: (optional) Tuple or list of args to pass to ``write_function``. The +//| :param ~list write_args: (optional) Tuple or list of args to pass to ``write_function``. The //| PixelBuf instance is appended after these args. //| STATIC mp_obj_t pixelbuf_pixelbuf_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { @@ -95,7 +95,7 @@ STATIC mp_obj_t pixelbuf_pixelbuf_make_new(const mp_obj_type_t *type, size_t n_a mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)]; mp_arg_parse_all(n_args, pos_args, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args); - if (mp_obj_is_subclass_fast(args[ARG_byteorder].u_obj, &pixelbuf_byteorder_type)) + if (mp_obj_is_subclass_fast(args[ARG_byteorder].u_obj, &pixelbuf_byteorder_type)) mp_raise_TypeError_varg(translate("byteorder is not an instance of ByteOrder (got a %s)"), mp_obj_get_type_str(args[ARG_byteorder].u_obj)); pixelbuf_byteorder_obj_t *byteorder = (args[ARG_byteorder].u_obj == mp_const_none) ? MP_OBJ_FROM_PTR(&byteorder_BGR) : args[ARG_byteorder].u_obj; @@ -122,7 +122,7 @@ STATIC mp_obj_t pixelbuf_pixelbuf_make_new(const mp_obj_type_t *type, size_t n_a if (!MP_OBJ_IS_TYPE(args[ARG_write_args].u_obj, &mp_type_list) && !MP_OBJ_IS_TYPE(args[ARG_write_args].u_obj, &mp_type_tuple) && - args[ARG_write_args].u_obj != mp_const_none) + args[ARG_write_args].u_obj != mp_const_none) { mp_raise_ValueError(translate("write_args must be a list, tuple, or None")); } @@ -186,8 +186,8 @@ STATIC mp_obj_t pixelbuf_pixelbuf_make_new(const mp_obj_type_t *type, size_t n_a else if (self->brightness > 1) self->brightness = 1; } - - if (self->dotstar_mode) { + + if (self->dotstar_mode) { // Initialize the buffer with the dotstar start bytes. // Header and end must be setup by caller for (uint i = 0; i < self->pixels * 4; i += 4) { @@ -197,7 +197,7 @@ STATIC mp_obj_t pixelbuf_pixelbuf_make_new(const mp_obj_type_t *type, size_t n_a } } } - + return MP_OBJ_FROM_PTR(self); } @@ -227,7 +227,7 @@ const mp_obj_property_t pixelbuf_pixelbuf_bpp_obj = { //| setting this value causes a recomputation of the values in buf. //| If only a buf was provided, then the brightness only applies to //| future pixel changes. -//| In DotStar mode +//| In DotStar mode //| STATIC mp_obj_t pixelbuf_pixelbuf_obj_get_brightness(mp_obj_t self_in) { mp_check_self(MP_OBJ_IS_TYPE(self_in, &pixelbuf_pixelbuf_type)); @@ -266,7 +266,7 @@ void pixelbuf_recalculate_brightness(pixelbuf_pixelbuf_obj_t *self) { // Compensate for shifted buffer (bpp=3 dotstar) for (uint i = 0; i < self->bytes; i++) { // Don't adjust per-pixel luminance bytes in dotstar mode - if (!self->dotstar_mode || (i % 4 != 0)) + if (!self->dotstar_mode || (i % 4 != 0)) buf[i] = rawbuf[i] * self->brightness; } } @@ -367,11 +367,13 @@ void call_write_function(pixelbuf_pixelbuf_obj_t *self) { } } - - -//| .. method:: [] +//| .. method:: __getitem__(index) +//| +//| Returns the pixel value at the given index. //| -//| Get or set pixels. Supports individual pixels and slices. +//| .. method:: __setitem__(index, value) +//| +//| Sets the pixel value at the given index. //| STATIC mp_obj_t pixelbuf_pixelbuf_subscr(mp_obj_t self_in, mp_obj_t index_in, mp_obj_t value) { mp_check_self(MP_OBJ_IS_TYPE(self_in, &pixelbuf_pixelbuf_type)); @@ -380,7 +382,7 @@ STATIC mp_obj_t pixelbuf_pixelbuf_subscr(mp_obj_t self_in, mp_obj_t index_in, mp // delete item // slice deletion return MP_OBJ_NULL; // op not supported - } + } pixelbuf_pixelbuf_obj_t *self = MP_OBJ_TO_PTR(self_in); if (0) { @@ -390,7 +392,7 @@ STATIC mp_obj_t pixelbuf_pixelbuf_subscr(mp_obj_t self_in, mp_obj_t index_in, mp if (!mp_seq_get_fast_slice_indexes(self->bytes, index_in, &slice)) mp_raise_NotImplementedError(translate("Only slices with step=1 (aka None) are supported")); - if ((slice.stop * self->pixel_step) > self->bytes) + if ((slice.stop * self->pixel_step) > self->bytes) mp_raise_IndexError(translate("Range out of bounds")); if (value == MP_OBJ_SENTINEL) { // Get @@ -422,8 +424,8 @@ STATIC mp_obj_t pixelbuf_pixelbuf_subscr(mp_obj_t self_in, mp_obj_t index_in, mp for (size_t i = slice.start; i < slice.stop; i++) { mp_obj_t *item = src_objs[i-slice.start]; if (MP_OBJ_IS_TYPE(value, &mp_type_list) || MP_OBJ_IS_TYPE(value, &mp_type_tuple) || MP_OBJ_IS_INT(value)) { - pixelbuf_set_pixel(self->buf + (i * self->pixel_step), - self->two_buffers ? self->rawbuf + (i * self->pixel_step) : NULL, + pixelbuf_set_pixel(self->buf + (i * self->pixel_step), + self->two_buffers ? self->rawbuf + (i * self->pixel_step) : NULL, self->brightness, item, &self->byteorder, self->dotstar_mode); } } @@ -438,14 +440,14 @@ STATIC mp_obj_t pixelbuf_pixelbuf_subscr(mp_obj_t self_in, mp_obj_t index_in, mp } else { // Single index rather than slice. size_t index = mp_get_index(self->base.type, self->pixels, index_in, false); size_t offset = (index * self->pixel_step); - if (offset > self->bytes) + if (offset > self->bytes) mp_raise_IndexError(translate("Pixel beyond bounds of buffer")); if (value == MP_OBJ_SENTINEL) { // Get uint8_t *pixelstart = (uint8_t *)(self->two_buffers ? self->rawbuf : self->buf) + offset; return pixelbuf_get_pixel(pixelstart, &self->byteorder, self->dotstar_mode); } else { // Store - pixelbuf_set_pixel(self->buf + offset, self->two_buffers ? self->rawbuf + offset : NULL, + pixelbuf_set_pixel(self->buf + offset, self->two_buffers ? self->rawbuf + offset : NULL, self->brightness, value, &self->byteorder, self->dotstar_mode); if (self->auto_write) call_write_function(self); diff --git a/shared-bindings/_pixelbuf/__init__.c b/shared-bindings/_pixelbuf/__init__.c index 31defc7fb..48b9f1cef 100644 --- a/shared-bindings/_pixelbuf/__init__.c +++ b/shared-bindings/_pixelbuf/__init__.c @@ -53,7 +53,7 @@ //| //| PixelBuf -//| .. class:: ByteOrder +//| .. class:: ByteOrder() //| //| Classes representing byteorders for circuitpython @@ -169,34 +169,34 @@ const int32_t colorwheel(float pos) { /// RGB -//| .. class:: RGB +//| .. data:: RGB //| //| * **order** Red, Green, Blue //| * **bpp** 3 PIXELBUF_BYTEORDER(RGB, 3, 0, 1, 2, 3, false, false) -//| .. class:: RBG +//| .. data:: RBG //| //| * **order** Red, Blue, Green //| * **bpp** 3 PIXELBUF_BYTEORDER(RBG, 3, 0, 2, 1, 3, false, false) -//| .. class:: GRB +//| .. data:: GRB //| //| * **order** Green, Red, Blue //| * **bpp** 3 //| //| Commonly used by NeoPixel. PIXELBUF_BYTEORDER(GRB, 3, 1, 0, 2, 3, false, false) -//| .. class:: GBR +//| .. data:: GBR //| //| * **order** Green, Blue, Red //| * **bpp** 3 PIXELBUF_BYTEORDER(GBR, 3, 1, 2, 0, 3, false, false) -//| .. class:: BRG +//| .. data:: BRG //| //| * **order** Blue, Red, Green //| * **bpp** 3 PIXELBUF_BYTEORDER(BRG, 3, 2, 0, 1, 3, false, false) -//| .. class:: BGR +//| .. data:: BGR //| //| * **order** Blue, Green, Red //| * **bpp** 3 @@ -205,19 +205,19 @@ PIXELBUF_BYTEORDER(BRG, 3, 2, 0, 1, 3, false, false) PIXELBUF_BYTEORDER(BGR, 3, 2, 1, 0, 3, false, false) // RGBW -//| .. class:: RGBW +//| .. data:: RGBW //| //| * **order** Red, Green, Blue, White //| * **bpp** 4 //| * **has_white** True PIXELBUF_BYTEORDER(RGBW, 4, 0, 1, 2, 3, true, false) -//| .. class:: RBGW +//| .. data:: RBGW //| //| * **order** Red, Blue, Green, White //| * **bpp** 4 //| * **has_white** True PIXELBUF_BYTEORDER(RBGW, 4, 0, 2, 1, 3, true, false) -//| .. class:: GRBW +//| .. data:: GRBW //| //| * **order** Green, Red, Blue, White //| * **bpp** 4 @@ -225,19 +225,19 @@ PIXELBUF_BYTEORDER(RBGW, 4, 0, 2, 1, 3, true, false) //| //| Commonly used by RGBW NeoPixels. PIXELBUF_BYTEORDER(GRBW, 4, 1, 0, 2, 3, true, false) -//| .. class:: GBRW +//| .. data:: GBRW //| //| * **order** Green, Blue, Red, White //| * **bpp** 4 //| * **has_white** True PIXELBUF_BYTEORDER(GBRW, 4, 1, 2, 0, 3, true, false) -//| .. class:: BRGW +//| .. data:: BRGW //| //| * **order** Blue, Red, Green, White //| * **bpp** 4 //| * **has_white** True PIXELBUF_BYTEORDER(BRGW, 4, 2, 0, 1, 3, true, false) -//| .. class:: BGRW +//| .. data:: BGRW //| //| * **order** Blue, Green, Red, White //| * **bpp** 4 @@ -248,37 +248,37 @@ PIXELBUF_BYTEORDER(BGRW, 4, 2, 1, 0, 3, true, false) // Luminosity chosen because the luminosity of a Dotstar at full bright // burns the eyes like looking at the Sun. // https://www.thesaurus.com/browse/luminosity?s=t -//| .. class:: LRGB +//| .. data:: LRGB //| //| * **order** *Luminosity*, Red, Green, Blue //| * **bpp** 4 //| * **has_luminosity** True PIXELBUF_BYTEORDER(LRGB, 4, 1, 2, 3, 0, false, true) -//| .. class:: LRBG +//| .. data:: LRBG //| //| * **order** *Luminosity*, Red, Blue, Green //| * **bpp** 4 //| * **has_luminosity** True PIXELBUF_BYTEORDER(LRBG, 4, 1, 3, 2, 0, false, true) -//| .. class:: LGRB +//| .. data:: LGRB //| //| * **order** *Luminosity*, Green, Red, Blue //| * **bpp** 4 //| * **has_luminosity** True PIXELBUF_BYTEORDER(LGRB, 4, 2, 1, 3, 0, false, true) -//| .. class:: LGBR +//| .. data:: LGBR //| //| * **order** *Luminosity*, Green, Blue, Red //| * **bpp** 4 //| * **has_luminosity** True PIXELBUF_BYTEORDER(LGBR, 4, 2, 3, 1, 0, false, true) -//| .. class:: LBRG +//| .. data:: LBRG //| //| * **order** *Luminosity*, Blue, Red, Green //| * **bpp** 4 //| * **has_luminosity** True PIXELBUF_BYTEORDER(LBRG, 4, 3, 1, 2, 0, false, true) -//| .. class:: LBGR +//| .. data:: LBGR //| //| * **order** *Luminosity*, Blue, Green, Red //| * **bpp** 4 diff --git a/shared-bindings/audiobusio/PDMIn.c b/shared-bindings/audiobusio/PDMIn.c index 5dca3fa59..0f19e2587 100644 --- a/shared-bindings/audiobusio/PDMIn.c +++ b/shared-bindings/audiobusio/PDMIn.c @@ -43,7 +43,7 @@ //| //| PDMIn can be used to record an input audio signal on a given set of pins. //| -//| .. class:: PDMIn(clock_pin, data_pin, \*, sample_rate=16000, bit_depth=8, mono=True, oversample=64, startup_delay=0.11) +//| .. class:: PDMIn(clock_pin, data_pin, *, sample_rate=16000, bit_depth=8, mono=True, oversample=64, startup_delay=0.11) //| //| Create a PDMIn object associated with the given pins. This allows you to //| record audio signals from the given pins. Individual ports may put further diff --git a/shared-bindings/audioio/WaveFile.c b/shared-bindings/audioio/WaveFile.c index cddeef769..a4e37231a 100644 --- a/shared-bindings/audioio/WaveFile.c +++ b/shared-bindings/audioio/WaveFile.c @@ -41,11 +41,11 @@ //| A .wav file prepped for audio playback. Only mono and stereo files are supported. Samples must //| be 8 bit unsigned or 16 bit signed. //| -//| .. class:: WaveFile(filename) +//| .. class:: WaveFile(file) //| //| Load a .wav file for playback with `audioio.AudioOut` or `audiobusio.I2SOut`. //| -//| :param bytes-like file: Already opened wave file +//| :param typing.BinaryIO file: Already opened wave file //| //| Playing a wave file from flash:: //| diff --git a/shared-bindings/bitbangio/I2C.c b/shared-bindings/bitbangio/I2C.c index 374268e3d..a74f08b0b 100644 --- a/shared-bindings/bitbangio/I2C.c +++ b/shared-bindings/bitbangio/I2C.c @@ -42,7 +42,7 @@ //| :class:`I2C` --- Two wire serial protocol //| ------------------------------------------ //| -//| .. class:: I2C(scl, sda, \*, frequency=400000) +//| .. class:: I2C(scl, sda, *, frequency=400000, timeout) //| //| I2C is a two-wire protocol for communicating between devices. At the //| physical level it consists of 2 wires: SCL and SDA, the clock and data @@ -75,7 +75,7 @@ STATIC mp_obj_t bitbangio_i2c_make_new(const mp_obj_type_t *type, size_t n_args, return (mp_obj_t)self; } -//| .. method:: I2C.deinit() +//| .. method:: deinit() //| //| Releases control of the underlying hardware so other classes can use it. //| @@ -86,13 +86,13 @@ STATIC mp_obj_t bitbangio_i2c_obj_deinit(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(bitbangio_i2c_deinit_obj, bitbangio_i2c_obj_deinit); -//| .. method:: I2C.__enter__() +//| .. method:: __enter__() //| //| No-op used in Context Managers. //| // Provided by context manager helper. -//| .. method:: I2C.__exit__() +//| .. method:: __exit__() //| //| Automatically deinitializes the hardware on context exit. See //| :ref:`lifetime-and-contextmanagers` for more info. @@ -110,7 +110,7 @@ static void check_lock(bitbangio_i2c_obj_t *self) { } } -//| .. method:: I2C.scan() +//| .. method:: scan() //| //| Scan all I2C addresses between 0x08 and 0x77 inclusive and return a list of //| those that respond. A device responds if it pulls the SDA line low after @@ -132,7 +132,7 @@ STATIC mp_obj_t bitbangio_i2c_scan(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(bitbangio_i2c_scan_obj, bitbangio_i2c_scan); -//| .. method:: I2C.try_lock() +//| .. method:: try_lock() //| //| Attempts to grab the I2C lock. Returns True on success. //| @@ -143,7 +143,7 @@ STATIC mp_obj_t bitbangio_i2c_obj_try_lock(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(bitbangio_i2c_try_lock_obj, bitbangio_i2c_obj_try_lock); -//| .. method:: I2C.unlock() +//| .. method:: unlock() //| //| Releases the I2C lock. //| @@ -155,7 +155,7 @@ STATIC mp_obj_t bitbangio_i2c_obj_unlock(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(bitbangio_i2c_unlock_obj, bitbangio_i2c_obj_unlock); -//| .. method:: I2C.readfrom_into(address, buffer, \*, start=0, end=len(buffer)) +//| .. method:: readfrom_into(address, buffer, *, start=0, end=None) //| //| Read into ``buffer`` from the slave specified by ``address``. //| The number of bytes read will be the length of ``buffer``. @@ -203,7 +203,7 @@ STATIC mp_obj_t bitbangio_i2c_readfrom_into(size_t n_args, const mp_obj_t *pos_a } MP_DEFINE_CONST_FUN_OBJ_KW(bitbangio_i2c_readfrom_into_obj, 3, bitbangio_i2c_readfrom_into); -//| .. method:: I2C.writeto(address, buffer, \*, start=0, end=len(buffer), stop=True) +//| .. method:: writeto(address, buffer, *, start=0, end=None, stop=True) //| //| Write the bytes from ``buffer`` to the slave specified by ``address``. //| Transmits a stop bit if ``stop`` is set. diff --git a/shared-bindings/bitbangio/SPI.c b/shared-bindings/bitbangio/SPI.c index 974ec99e2..9d00264cd 100644 --- a/shared-bindings/bitbangio/SPI.c +++ b/shared-bindings/bitbangio/SPI.c @@ -84,7 +84,7 @@ STATIC mp_obj_t bitbangio_spi_make_new(const mp_obj_type_t *type, size_t n_args, return (mp_obj_t)self; } -//| .. method:: SPI.deinit() +//| .. method:: deinit() //| //| Turn off the SPI bus. //| @@ -95,13 +95,13 @@ STATIC mp_obj_t bitbangio_spi_obj_deinit(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(bitbangio_spi_deinit_obj, bitbangio_spi_obj_deinit); -//| .. method:: SPI.__enter__() +//| .. method:: __enter__() //| //| No-op used by Context Managers. //| // Provided by context manager helper. -//| .. method:: SPI.__exit__() +//| .. method:: __exit__() //| //| Automatically deinitializes the hardware when exiting a context. See //| :ref:`lifetime-and-contextmanagers` for more info. @@ -120,7 +120,7 @@ static void check_lock(bitbangio_spi_obj_t *self) { } } -//| .. method:: SPI.configure(\*, baudrate=100000, polarity=0, phase=0, bits=8) +//| .. method:: configure(*, baudrate=100000, polarity=0, phase=0, bits=8) //| //| Configures the SPI bus. Only valid when locked. //| @@ -162,7 +162,7 @@ STATIC mp_obj_t bitbangio_spi_configure(size_t n_args, const mp_obj_t *pos_args, } MP_DEFINE_CONST_FUN_OBJ_KW(bitbangio_spi_configure_obj, 1, bitbangio_spi_configure); -//| .. method:: SPI.try_lock() +//| .. method:: try_lock() //| //| Attempts to grab the SPI lock. Returns True on success. //| @@ -176,7 +176,7 @@ STATIC mp_obj_t bitbangio_spi_obj_try_lock(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(bitbangio_spi_try_lock_obj, bitbangio_spi_obj_try_lock); -//| .. method:: SPI.unlock() +//| .. method:: unlock() //| //| Releases the SPI lock. //| @@ -188,7 +188,7 @@ STATIC mp_obj_t bitbangio_spi_obj_unlock(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(bitbangio_spi_unlock_obj, bitbangio_spi_obj_unlock); -//| .. method:: SPI.write(buf) +//| .. method:: write(buf) //| //| Write the data contained in ``buf``. Requires the SPI being locked. //| If the buffer is empty, nothing happens. @@ -212,7 +212,7 @@ STATIC mp_obj_t bitbangio_spi_write(mp_obj_t self_in, mp_obj_t wr_buf) { MP_DEFINE_CONST_FUN_OBJ_2(bitbangio_spi_write_obj, bitbangio_spi_write); -//| .. method:: SPI.readinto(buf) +//| .. method:: readinto(buf) //| //| Read into the buffer specified by ``buf`` while writing zeroes. //| Requires the SPI being locked. @@ -236,7 +236,7 @@ STATIC mp_obj_t bitbangio_spi_readinto(size_t n_args, const mp_obj_t *args) { } MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(bitbangio_spi_readinto_obj, 2, 2, bitbangio_spi_readinto); -//| .. method:: SPI.write_readinto(buffer_out, buffer_in, \*, out_start=0, out_end=len(buffer_out), in_start=0, in_end=len(buffer_in)) +//| .. method:: write_readinto(buffer_out, buffer_in, *, out_start=0, out_end=None, in_start=0, in_end=None) //| //| Write out the data in ``buffer_out`` while simultaneously reading data into ``buffer_in``. //| The lengths of the slices defined by ``buffer_out[out_start:out_end]`` and ``buffer_in[in_start:in_end]`` @@ -246,9 +246,9 @@ MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(bitbangio_spi_readinto_obj, 2, 2, bitbangio_ //| :param bytearray buffer_out: Write out the data in this buffer //| :param bytearray buffer_in: Read data into this buffer //| :param int out_start: Start of the slice of buffer_out to write out: ``buffer_out[out_start:out_end]`` -//| :param int out_end: End of the slice; this index is not included +//| :param int out_end: End of the slice; this index is not included. Defaults to ``len(buffer_out)`` //| :param int in_start: Start of the slice of ``buffer_in`` to read into: ``buffer_in[in_start:in_end]`` -//| :param int in_end: End of the slice; this index is not included +//| :param int in_end: End of the slice; this index is not included. Defaults to ``len(buffer_in)`` //| STATIC mp_obj_t bitbangio_spi_write_readinto(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_buffer_out, ARG_buffer_in, ARG_out_start, ARG_out_end, ARG_in_start, ARG_in_end }; diff --git a/shared-bindings/bleio/AddressType.c b/shared-bindings/bleio/AddressType.c index cf2151c94..7edf3c170 100644 --- a/shared-bindings/bleio/AddressType.c +++ b/shared-bindings/bleio/AddressType.c @@ -31,7 +31,7 @@ //| :class:`AddressType` -- defines the type of a BLE address //| ============================================================= //| -//| .. class:: bleio.AddressType +//| .. class:: AddressType() //| //| Enum-like class to define the type of a BLE address, see also `bleio.Address`. //| diff --git a/shared-bindings/bleio/CharacteristicBuffer.c b/shared-bindings/bleio/CharacteristicBuffer.c index c368de361..3604aeedb 100644 --- a/shared-bindings/bleio/CharacteristicBuffer.c +++ b/shared-bindings/bleio/CharacteristicBuffer.c @@ -47,7 +47,7 @@ STATIC void raise_error_if_not_connected(bleio_characteristic_buffer_obj_t *self //| //| Accumulates a Characteristic's incoming values in a FIFO buffer. //| -//| .. class:: CharacteristicBuffer(Characteristic, *, timeout=1, buffer_size=64) +//| .. class:: CharacteristicBuffer(characteristic, *, timeout=1, buffer_size=64) //| //| Create a new Characteristic object identified by the specified UUID. //| diff --git a/shared-bindings/bleio/UUID.c b/shared-bindings/bleio/UUID.c index c6ad9e626..fa2472b48 100644 --- a/shared-bindings/bleio/UUID.c +++ b/shared-bindings/bleio/UUID.c @@ -47,9 +47,10 @@ //| The value can be one of: //| //| - an `int` value in range 0 to 0xFFFF (Bluetooth SIG 16-bit UUID) -//| - a buffer object (bytearray, bytes) of 16 bytes in little-endian order (128-bit UUID) +//| - a buffer object (bytearray, bytes) of 16 bytes in little-endian order (128-bit UUID) //| -//| :param int/buffer value: The uuid value to encapsulate +//| :param value: The uuid value to encapsulate +//| :type value: int or typing.ByteString //| STATIC mp_obj_t bleio_uuid_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { mp_arg_check_num(n_args, kw_args, 1, 1, false); @@ -124,6 +125,8 @@ STATIC mp_obj_t bleio_uuid_make_new(const mp_obj_type_t *type, size_t n_args, co //| //| The 16-bit part of the UUID. (read-only) //| +//| :type: int +//| STATIC mp_obj_t bleio_uuid_get_uuid16(mp_obj_t self_in) { bleio_uuid_obj_t *self = MP_OBJ_TO_PTR(self_in); return MP_OBJ_NEW_SMALL_INT(common_hal_bleio_uuid_get_uuid16(self)); @@ -140,9 +143,11 @@ const mp_obj_property_t bleio_uuid_uuid16_obj = { //| .. attribute:: uuid128 //| -//| The 128-bit value of the UUID, returned as bytes. +//| The 128-bit value of the UUID //| Raises AttributeError if this is a 16-bit UUID. (read-only) //| +//| :type: bytes +//| STATIC mp_obj_t bleio_uuid_get_uuid128(mp_obj_t self_in) { bleio_uuid_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -164,9 +169,10 @@ const mp_obj_property_t bleio_uuid_uuid128_obj = { //| .. attribute:: size //| -//| Returns 128 if this UUID represents a 128-bit vendor-specific UUID. -//| Returns 16 if this UUID represents a 16-bit Bluetooth SIG assigned UUID. (read-only) -//| 32-bit UUIDs are not currently supported. +//| 128 if this UUID represents a 128-bit vendor-specific UUID. 16 if this UUID represents a +//| 16-bit Bluetooth SIG assigned UUID. (read-only) 32-bit UUIDs are not currently supported. +//| +//| :type: int //| STATIC mp_obj_t bleio_uuid_get_size(mp_obj_t self_in) { bleio_uuid_obj_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/board/__init__.c b/shared-bindings/board/__init__.c index 82a0cab67..b4cc8cb12 100644 --- a/shared-bindings/board/__init__.c +++ b/shared-bindings/board/__init__.c @@ -42,7 +42,7 @@ //| .. warning:: The board module varies by board. The APIs documented here may or may not be //| available on a specific board. -//| .. method:: I2C() +//| .. function:: I2C() //| //| Returns the `busio.I2C` object for the board designated SDA and SCL pins. It is a singleton. //| @@ -66,7 +66,7 @@ mp_obj_t board_i2c(void) { MP_DEFINE_CONST_FUN_OBJ_0(board_i2c_obj, board_i2c); -//| .. method:: SPI() +//| .. function:: SPI() //| //| Returns the `busio.SPI` object for the board designated SCK, MOSI and MISO pins. It is a //| singleton. @@ -90,7 +90,7 @@ mp_obj_t board_spi(void) { #endif MP_DEFINE_CONST_FUN_OBJ_0(board_spi_obj, board_spi); -//| .. method:: UART() +//| .. function:: UART() //| //| Returns the `busio.UART` object for the board designated TX and RX pins. It is a singleton. //| diff --git a/shared-bindings/busio/I2C.c b/shared-bindings/busio/I2C.c index e17a72b48..1c50c07b0 100644 --- a/shared-bindings/busio/I2C.c +++ b/shared-bindings/busio/I2C.c @@ -41,7 +41,7 @@ //| :class:`I2C` --- Two wire serial protocol //| ------------------------------------------ //| -//| .. class:: I2C(scl, sda, \*, frequency=400000) +//| .. class:: I2C(scl, sda, *, frequency=400000, timeout=255) //| //| I2C is a two-wire protocol for communicating between devices. At the //| physical level it consists of 2 wires: SCL and SDA, the clock and data @@ -82,7 +82,7 @@ STATIC mp_obj_t busio_i2c_make_new(const mp_obj_type_t *type, size_t n_args, con return (mp_obj_t)self; } -//| .. method:: I2C.deinit() +//| .. method:: deinit() //| //| Releases control of the underlying hardware so other classes can use it. //| @@ -93,13 +93,13 @@ STATIC mp_obj_t busio_i2c_obj_deinit(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(busio_i2c_deinit_obj, busio_i2c_obj_deinit); -//| .. method:: I2C.__enter__() +//| .. method:: __enter__() //| //| No-op used in Context Managers. //| // Provided by context manager helper. -//| .. method:: I2C.__exit__() +//| .. method:: __exit__() //| //| Automatically deinitializes the hardware on context exit. See //| :ref:`lifetime-and-contextmanagers` for more info. @@ -118,7 +118,7 @@ static void check_lock(busio_i2c_obj_t *self) { } } -//| .. method:: I2C.scan() +//| .. method:: scan() //| //| Scan all I2C addresses between 0x08 and 0x77 inclusive and return a //| list of those that respond. @@ -142,7 +142,7 @@ STATIC mp_obj_t busio_i2c_scan(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(busio_i2c_scan_obj, busio_i2c_scan); -//| .. method:: I2C.try_lock() +//| .. method:: try_lock() //| //| Attempts to grab the I2C lock. Returns True on success. //| @@ -156,7 +156,7 @@ STATIC mp_obj_t busio_i2c_obj_try_lock(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(busio_i2c_try_lock_obj, busio_i2c_obj_try_lock); -//| .. method:: I2C.unlock() +//| .. method:: unlock() //| //| Releases the I2C lock. //| @@ -168,7 +168,7 @@ STATIC mp_obj_t busio_i2c_obj_unlock(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(busio_i2c_unlock_obj, busio_i2c_obj_unlock); -//| .. method:: I2C.readfrom_into(address, buffer, \*, start=0, end=len(buffer)) +//| .. method:: readfrom_into(address, buffer, *, start=0, end=None) //| //| Read into ``buffer`` from the slave specified by ``address``. //| The number of bytes read will be the length of ``buffer``. @@ -181,7 +181,7 @@ MP_DEFINE_CONST_FUN_OBJ_1(busio_i2c_unlock_obj, busio_i2c_obj_unlock); //| :param int address: 7-bit device address //| :param bytearray buffer: buffer to write into //| :param int start: Index to start writing at -//| :param int end: Index to write up to but not include +//| :param int end: Index to write up to but not include. Defaults to ``len(buffer)`` //| STATIC mp_obj_t busio_i2c_readfrom_into(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_address, ARG_buffer, ARG_start, ARG_end }; @@ -216,7 +216,7 @@ STATIC mp_obj_t busio_i2c_readfrom_into(size_t n_args, const mp_obj_t *pos_args, } MP_DEFINE_CONST_FUN_OBJ_KW(busio_i2c_readfrom_into_obj, 3, busio_i2c_readfrom_into); -//| .. method:: I2C.writeto(address, buffer, \*, start=0, end=len(buffer), stop=True) +//| .. method:: writeto(address, buffer, *, start=0, end=None, stop=True) //| //| Write the bytes from ``buffer`` to the slave specified by ``address``. //| Transmits a stop bit if ``stop`` is set. @@ -231,7 +231,7 @@ MP_DEFINE_CONST_FUN_OBJ_KW(busio_i2c_readfrom_into_obj, 3, busio_i2c_readfrom_in //| :param int address: 7-bit device address //| :param bytearray buffer: buffer containing the bytes to write //| :param int start: Index to start writing from -//| :param int end: Index to read up to but not include +//| :param int end: Index to read up to but not include. Defaults to ``len(buffer)`` //| :param bool stop: If true, output an I2C stop condition after the //| buffer is written //| diff --git a/shared-bindings/busio/SPI.c b/shared-bindings/busio/SPI.c index f690eea18..bd788365e 100644 --- a/shared-bindings/busio/SPI.c +++ b/shared-bindings/busio/SPI.c @@ -95,7 +95,7 @@ STATIC mp_obj_t busio_spi_make_new(const mp_obj_type_t *type, size_t n_args, con return (mp_obj_t)self; } -//| .. method:: SPI.deinit() +//| .. method:: deinit() //| //| Turn off the SPI bus. //| @@ -106,13 +106,13 @@ STATIC mp_obj_t busio_spi_obj_deinit(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(busio_spi_deinit_obj, busio_spi_obj_deinit); -//| .. method:: SPI.__enter__() +//| .. method:: __enter__() //| //| No-op used by Context Managers. //| // Provided by context manager helper. -//| .. method:: SPI.__exit__() +//| .. method:: __exit__() //| //| Automatically deinitializes the hardware when exiting a context. See //| :ref:`lifetime-and-contextmanagers` for more info. @@ -131,7 +131,7 @@ static void check_lock(busio_spi_obj_t *self) { } } -//| .. method:: SPI.configure(\*, baudrate=100000, polarity=0, phase=0, bits=8) +//| .. method:: configure(*, baudrate=100000, polarity=0, phase=0, bits=8) //| //| Configures the SPI bus. The SPI object must be locked. //| @@ -188,7 +188,7 @@ STATIC mp_obj_t busio_spi_configure(size_t n_args, const mp_obj_t *pos_args, mp_ } MP_DEFINE_CONST_FUN_OBJ_KW(busio_spi_configure_obj, 1, busio_spi_configure); -//| .. method:: SPI.try_lock() +//| .. method:: try_lock() //| //| Attempts to grab the SPI lock. Returns True on success. //| @@ -202,7 +202,7 @@ STATIC mp_obj_t busio_spi_obj_try_lock(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(busio_spi_try_lock_obj, busio_spi_obj_try_lock); -//| .. method:: SPI.unlock() +//| .. method:: unlock() //| //| Releases the SPI lock. //| @@ -214,14 +214,14 @@ STATIC mp_obj_t busio_spi_obj_unlock(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(busio_spi_unlock_obj, busio_spi_obj_unlock); -//| .. method:: SPI.write(buffer, \*, start=0, end=len(buffer)) +//| .. method:: write(buffer, *, start=0, end=None) //| //| Write the data contained in ``buffer``. The SPI object must be locked. //| If the buffer is empty, nothing happens. //| //| :param bytearray buffer: Write out the data in this buffer //| :param int start: Start of the slice of ``buffer`` to write out: ``buffer[start:end]`` -//| :param int end: End of the slice; this index is not included +//| :param int end: End of the slice; this index is not included. Defaults to ``len(buffer)`` //| STATIC mp_obj_t busio_spi_write(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_buffer, ARG_start, ARG_end }; @@ -255,7 +255,7 @@ STATIC mp_obj_t busio_spi_write(size_t n_args, const mp_obj_t *pos_args, mp_map_ MP_DEFINE_CONST_FUN_OBJ_KW(busio_spi_write_obj, 2, busio_spi_write); -//| .. method:: SPI.readinto(buffer, \*, start=0, end=len(buffer), write_value=0) +//| .. method:: readinto(buffer, *, start=0, end=None, write_value=0) //| //| Read into ``buffer`` while writing ``write_value`` for each byte read. //| The SPI object must be locked. @@ -263,7 +263,7 @@ MP_DEFINE_CONST_FUN_OBJ_KW(busio_spi_write_obj, 2, busio_spi_write); //| //| :param bytearray buffer: Read data into this buffer //| :param int start: Start of the slice of ``buffer`` to read into: ``buffer[start:end]`` -//| :param int end: End of the slice; this index is not included +//| :param int end: End of the slice; this index is not included. Defaults to ``len(buffer)`` //| :param int write_value: Value to write while reading. (Usually ignored.) //| STATIC mp_obj_t busio_spi_readinto(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { @@ -298,7 +298,7 @@ STATIC mp_obj_t busio_spi_readinto(size_t n_args, const mp_obj_t *pos_args, mp_m } MP_DEFINE_CONST_FUN_OBJ_KW(busio_spi_readinto_obj, 2, busio_spi_readinto); -//| .. method:: SPI.write_readinto(buffer_out, buffer_in, \*, out_start=0, out_end=len(buffer_out), in_start=0, in_end=len(buffer_in)) +//| .. method:: write_readinto(buffer_out, buffer_in, *, out_start=0, out_end=None, in_start=0, in_end=None) //| //| Write out the data in ``buffer_out`` while simultaneously reading data into ``buffer_in``. //| The SPI object must be locked. @@ -309,9 +309,9 @@ MP_DEFINE_CONST_FUN_OBJ_KW(busio_spi_readinto_obj, 2, busio_spi_readinto); //| :param bytearray buffer_out: Write out the data in this buffer //| :param bytearray buffer_in: Read data into this buffer //| :param int out_start: Start of the slice of buffer_out to write out: ``buffer_out[out_start:out_end]`` -//| :param int out_end: End of the slice; this index is not included +//| :param int out_end: End of the slice; this index is not included. Defaults to ``len(buffer_out)`` //| :param int in_start: Start of the slice of ``buffer_in`` to read into: ``buffer_in[in_start:in_end]`` -//| :param int in_end: End of the slice; this index is not included +//| :param int in_end: End of the slice; this index is not included. Defaults to ``len(buffer_in)`` //| STATIC mp_obj_t busio_spi_write_readinto(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_buffer_out, ARG_buffer_in, ARG_out_start, ARG_out_end, ARG_in_start, ARG_in_end }; diff --git a/shared-bindings/busio/UART.c b/shared-bindings/busio/UART.c index 94ad1bd3e..eeffb62ef 100644 --- a/shared-bindings/busio/UART.c +++ b/shared-bindings/busio/UART.c @@ -46,7 +46,7 @@ //| ================================================= //| //| -//| .. class:: UART(tx, rx, \*, baudrate=9600, bits=8, parity=None, stop=1, timeout=1, receiver_buffer_size=64) +//| .. class:: UART(tx, rx, *, baudrate=9600, bits=8, parity=None, stop=1, timeout=1, receiver_buffer_size=64) //| //| A common bidirectional serial protocol that uses an an agreed upon speed //| rather than a shared clock line. @@ -292,7 +292,7 @@ STATIC mp_obj_t busio_uart_obj_reset_input_buffer(mp_obj_t self_in) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(busio_uart_reset_input_buffer_obj, busio_uart_obj_reset_input_buffer); -//| .. class:: busio.UART.Parity +//| .. class:: busio.UART.Parity() //| //| Enum-like class to define the parity used to verify correct data transfer. //| diff --git a/shared-bindings/displayio/TileGrid.c b/shared-bindings/displayio/TileGrid.c index 6d18ac78f..10bed4c77 100644 --- a/shared-bindings/displayio/TileGrid.c +++ b/shared-bindings/displayio/TileGrid.c @@ -64,7 +64,7 @@ //| :param int height: Height of the grid in tiles. //| :param int tile_width: Width of a single tile in pixels. Defaults to the full Bitmap and must evenly divide into the Bitmap's dimensions. //| :param int tile_height: Height of a single tile in pixels. Defaults to the full Bitmap and must evenly divide into the Bitmap's dimensions. -//| :param in default_tile: Default tile index to show. +//| :param int default_tile: Default tile index to show. //| :param int x: Initial x position of the left edge within the parent. //| :param int y: Initial y position of the top edge within the parent. //| diff --git a/shared-bindings/displayio/__init__.c b/shared-bindings/displayio/__init__.c index 44b1e0b07..9dc17103b 100644 --- a/shared-bindings/displayio/__init__.c +++ b/shared-bindings/displayio/__init__.c @@ -69,7 +69,7 @@ //| -//| .. method:: release_displays() +//| .. function:: release_displays() //| //| Releases any actively used displays so their busses and pins can be used again. This will also //| release the builtin display on boards that have one. You will need to reinitialize it yourself diff --git a/shared-bindings/help.c b/shared-bindings/help.c index e0770ff3c..4e7c3a78b 100644 --- a/shared-bindings/help.c +++ b/shared-bindings/help.c @@ -27,7 +27,7 @@ //| :func:`help` - Built-in method to provide helpful information //| ============================================================== //| -//| .. method:: help(object=None) +//| .. function:: help(object=None) //| //| Prints a help method about the given object. When ``object`` is none, //| prints general port information. diff --git a/shared-bindings/microcontroller/Pin.c b/shared-bindings/microcontroller/Pin.c index e79663107..3635f0afb 100644 --- a/shared-bindings/microcontroller/Pin.c +++ b/shared-bindings/microcontroller/Pin.c @@ -40,7 +40,7 @@ //| //| Identifies an IO pin on the microcontroller. //| -//| .. class:: Pin +//| .. class:: Pin() //| //| Identifies an IO pin on the microcontroller. They are fixed by the //| hardware so they cannot be constructed on demand. Instead, use diff --git a/shared-bindings/microcontroller/RunMode.c b/shared-bindings/microcontroller/RunMode.c index 7c3f84fca..913242ad2 100644 --- a/shared-bindings/microcontroller/RunMode.c +++ b/shared-bindings/microcontroller/RunMode.c @@ -31,24 +31,30 @@ //| :class:`RunMode` -- run state of the microcontroller //| ============================================================= //| -//| .. class:: microcontroller.RunMode +//| .. class:: RunMode() //| //| Enum-like class to define the run mode of the microcontroller and //| CircuitPython. //| -//| .. data:: NORMAL +//| .. attribute:: NORMAL //| //| Run CircuitPython as normal. //| -//| .. data:: SAFE_MODE +//| :type microcontroller.RunMode: +//| +//| .. attribute:: SAFE_MODE //| //| Run CircuitPython in safe mode. User code will not be run and the //| file system will be writeable over USB. //| -//| .. data:: BOOTLOADER +//| :type microcontroller.RunMode: +//| +//| .. attribute:: BOOTLOADER //| //| Run the bootloader. //| +//| :type microcontroller.RunMode: +//| const mp_obj_type_t mcu_runmode_type; const mcu_runmode_obj_t mcu_runmode_normal_obj = { diff --git a/shared-bindings/microcontroller/__init__.c b/shared-bindings/microcontroller/__init__.c index da8d0bd94..090c4564d 100644 --- a/shared-bindings/microcontroller/__init__.c +++ b/shared-bindings/microcontroller/__init__.c @@ -62,14 +62,14 @@ //| RunMode //| -//| .. attribute:: cpu +//| .. data:: cpu //| //| CPU information and control, such as ``cpu.temperature`` and ``cpu.frequency`` //| (clock frequency). //| This object is the sole instance of `microcontroller.Processor`. //| -//| .. method:: delay_us(delay) +//| .. function:: delay_us(delay) //| //| Dedicated delay method used for very short delays. **Do not** do long delays //| because this stops all other functions from completing. Think of this as an empty @@ -87,7 +87,7 @@ STATIC mp_obj_t mcu_delay_us(mp_obj_t delay_obj) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(mcu_delay_us_obj, mcu_delay_us); -//| .. method:: disable_interrupts() +//| .. function:: disable_interrupts() //| //| Disable all interrupts. Be very careful, this can stall everything. //| @@ -97,7 +97,7 @@ STATIC mp_obj_t mcu_disable_interrupts(void) { } STATIC MP_DEFINE_CONST_FUN_OBJ_0(mcu_disable_interrupts_obj, mcu_disable_interrupts); -//| .. method:: enable_interrupts() +//| .. function:: enable_interrupts() //| //| Enable the interrupts that were enabled at the last disable. //| @@ -107,7 +107,7 @@ STATIC mp_obj_t mcu_enable_interrupts(void) { } STATIC MP_DEFINE_CONST_FUN_OBJ_0(mcu_enable_interrupts_obj, mcu_enable_interrupts); -//| .. method:: on_next_reset(run_mode) +//| .. function:: on_next_reset(run_mode) //| //| Configure the run mode used the next time the microcontroller is reset but //| not powered down. @@ -132,7 +132,7 @@ STATIC mp_obj_t mcu_on_next_reset(mp_obj_t run_mode_obj) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(mcu_on_next_reset_obj, mcu_on_next_reset); -//| .. method:: reset() +//| .. function:: reset() //| //| Reset the microcontroller. After reset, the microcontroller will enter the //| run mode last set by `on_next_reset`. @@ -148,11 +148,13 @@ STATIC mp_obj_t mcu_reset(void) { } STATIC MP_DEFINE_CONST_FUN_OBJ_0(mcu_reset_obj, mcu_reset); -//| .. attribute:: nvm +//| .. data:: nvm //| //| Available non-volatile memory. //| This object is the sole instance of `nvm.ByteArray` when available or ``None`` otherwise. //| +//| :type: nvm.ByteArray or None +//| //| :mod:`microcontroller.pin` --- Microcontroller pin names //| -------------------------------------------------------- diff --git a/shared-bindings/neopixel_write/__init__.c b/shared-bindings/neopixel_write/__init__.c index 05d6fd97a..1ee66337b 100644 --- a/shared-bindings/neopixel_write/__init__.c +++ b/shared-bindings/neopixel_write/__init__.c @@ -55,11 +55,11 @@ //| pixel_off = bytearray([0, 0, 0]) //| neopixel_write.neopixel_write(pin, pixel_off) //| -//| .. method:: neopixel_write.neopixel_write(digitalinout, buf) +//| .. function:: neopixel_write(digitalinout, buf) //| //| Write buf out on the given DigitalInOut. //| -//| :param ~digitalio.DigitalInOut gpio: the DigitalInOut to output with +//| :param ~digitalio.DigitalInOut digitalinout: the DigitalInOut to output with //| :param bytearray buf: The bytes to clock out. No assumption is made about color order //| STATIC mp_obj_t neopixel_write_neopixel_write_(mp_obj_t digitalinout_obj, mp_obj_t buf) { diff --git a/shared-bindings/network/__init__.c b/shared-bindings/network/__init__.c index 1067ea549..01763a73c 100644 --- a/shared-bindings/network/__init__.c +++ b/shared-bindings/network/__init__.c @@ -49,7 +49,7 @@ //| It is used by the 'socket' module to look up a suitable //| NIC when a socket is created. //| -//| .. function:: route +//| .. function:: route() //| //| Returns a list of all configured NICs. //| diff --git a/shared-bindings/pulseio/PWMOut.c b/shared-bindings/pulseio/PWMOut.c index 37939a07a..a7a90fb0d 100644 --- a/shared-bindings/pulseio/PWMOut.c +++ b/shared-bindings/pulseio/PWMOut.c @@ -42,7 +42,7 @@ //| //| PWMOut can be used to output a PWM signal on a given pin. //| -//| .. class:: PWMOut(pin, \*, duty_cycle=0, frequency=500, variable_frequency=False) +//| .. class:: PWMOut(pin, *, duty_cycle=0, frequency=500, variable_frequency=False) //| //| Create a PWM object associated with the given pin. This allows you to //| write PWM signals out on the given pin. Frequency is fixed after init diff --git a/shared-bindings/pulseio/PulseIn.c b/shared-bindings/pulseio/PulseIn.c index 426ac4384..9f37c65c9 100644 --- a/shared-bindings/pulseio/PulseIn.c +++ b/shared-bindings/pulseio/PulseIn.c @@ -45,7 +45,7 @@ //| The pulsed signal consists of timed active and idle periods. Unlike PWM, //| there is no set duration for active and idle pairs. //| -//| .. class:: PulseIn(pin, maxlen=2, \*, idle_state=False) +//| .. class:: PulseIn(pin, maxlen=2, *, idle_state=False) //| //| Create a PulseIn object associated with the given pin. The object acts as //| a read-only sequence of pulse lengths with a given max length. When it is diff --git a/shared-bindings/socket/__init__.c b/shared-bindings/socket/__init__.c index 085d4e690..6d04a9893 100644 --- a/shared-bindings/socket/__init__.c +++ b/shared-bindings/socket/__init__.c @@ -51,7 +51,7 @@ STATIC const mp_obj_type_t socket_type; //| .. currentmodule:: socket //| -//| .. class:: socket(family, type, proto, ...) +//| .. class:: socket(family, type, proto) //| //| Create a new socket //| diff --git a/shared-bindings/storage/__init__.c b/shared-bindings/storage/__init__.c index 4db3a9fec..ba439b951 100644 --- a/shared-bindings/storage/__init__.c +++ b/shared-bindings/storage/__init__.c @@ -48,7 +48,7 @@ //| directly. //| -//| .. function:: mount(filesystem, mount_path, \*, readonly=False) +//| .. function:: mount(filesystem, mount_path, *, readonly=False) //| //| Mounts the given filesystem object at the given path. //| @@ -183,7 +183,7 @@ STATIC const mp_rom_map_elem_t storage_module_globals_table[] = { //| this property can only be set when the device is writable by the //| microcontroller. //| - //| .. method:: mkfs + //| .. method:: mkfs() //| //| Format the block device, deleting any data that may have been there //| @@ -216,7 +216,7 @@ STATIC const mp_rom_map_elem_t storage_module_globals_table[] = { //| //| Don't call this directly, call `storage.mount`. //| - //| .. method:: umount + //| .. method:: umount() //| //| Don't call this directly, call `storage.umount`. //| diff --git a/shared-bindings/struct/__init__.c b/shared-bindings/struct/__init__.c index 9240a15bb..ea14b3763 100644 --- a/shared-bindings/struct/__init__.c +++ b/shared-bindings/struct/__init__.c @@ -67,9 +67,9 @@ STATIC mp_obj_t struct_calcsize(mp_obj_t fmt_in) { } MP_DEFINE_CONST_FUN_OBJ_1(struct_calcsize_obj, struct_calcsize); -//| .. function:: pack(fmt, v1, v2, ...) +//| .. function:: pack(fmt, *values) //| -//| Pack the values v1, v2, ... according to the format string fmt. +//| Pack the values according to the format string fmt. //| The return value is a bytes object encoding the values. //| @@ -85,9 +85,9 @@ STATIC mp_obj_t struct_pack(size_t n_args, const mp_obj_t *args) { } MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(struct_pack_obj, 1, MP_OBJ_FUN_ARGS_MAX, struct_pack); -//| .. function:: pack_into(fmt, buffer, offset, v1, v2, ...) +//| .. function:: pack_into(fmt, buffer, offset, *values) //| -//| Pack the values v1, v2, ... according to the format string fmt into a buffer +//| Pack the values according to the format string fmt into a buffer //| starting at offset. offset may be negative to count from the end of buffer. //| diff --git a/shared-bindings/time/__init__.c b/shared-bindings/time/__init__.c index 3babe2db4..70c01c2d8 100644 --- a/shared-bindings/time/__init__.c +++ b/shared-bindings/time/__init__.c @@ -47,7 +47,7 @@ //| written in MicroPython will work in CPython but not necessarily the other //| way around. //| -//| .. method:: monotonic() +//| .. function:: monotonic() //| //| Returns an always increasing value of time with an unknown reference //| point. Only use it to compare against other values from `monotonic`. @@ -62,7 +62,7 @@ STATIC mp_obj_t time_monotonic(void) { } MP_DEFINE_CONST_FUN_OBJ_0(time_monotonic_obj, time_monotonic); -//| .. method:: sleep(seconds) +//| .. function:: sleep(seconds) //| //| Sleep for a given number of seconds. //| @@ -95,19 +95,20 @@ mp_obj_t struct_time_make_new(const mp_obj_type_t *type, size_t n_args, const mp return namedtuple_make_new(type, 9, tuple->items, NULL); } -//| .. class:: struct_time((tm_year, tm_mon, tm_mday, tm_hour, tm_min, tm_sec, tm_wday, tm_yday, tm_isdst)) +//| .. class:: struct_time(time_tuple) //| //| Structure used to capture a date and time. Note that it takes a tuple! //| -//| :param int tm_year: the year, 2017 for example -//| :param int tm_mon: the month, range [1, 12] -//| :param int tm_mday: the day of the month, range [1, 31] -//| :param int tm_hour: the hour, range [0, 23] -//| :param int tm_min: the minute, range [0, 59] -//| :param int tm_sec: the second, range [0, 61] -//| :param int tm_wday: the day of the week, range [0, 6], Monday is 0 -//| :param int tm_yday: the day of the year, range [1, 366], -1 indicates not known -//| :param int tm_isdst: 1 when in daylight savings, 0 when not, -1 if unknown. +//| :param Tuple[tm_year, tm_mon, tm_mday, tm_hour, tm_min, tm_sec, tm_wday, tm_yday, tm_isdst] time_tuple: Tuple of time info. +//| * the year, 2017 for example +//| * the month, range [1, 12] +//| * the day of the month, range [1, 31] +//| * the hour, range [0, 23] +//| * the minute, range [0, 59] +//| * the second, range [0, 61] +//| * the day of the week, range [0, 6], Monday is 0 +//| * the day of the year, range [1, 366], -1 indicates not known +//| * 1 when in daylight savings, 0 when not, -1 if unknown. //| const mp_obj_namedtuple_type_t struct_time_type_obj = { .base = { @@ -190,7 +191,7 @@ mp_obj_t MP_WEAK rtc_get_time_source_time(void) { mp_raise_RuntimeError(translate("RTC is not supported on this board")); } -//| .. method:: time() +//| .. function:: time() //| //| Return the current time in seconds since since Jan 1, 1970. //| @@ -206,7 +207,7 @@ STATIC mp_obj_t time_time(void) { } MP_DEFINE_CONST_FUN_OBJ_0(time_time_obj, time_time); -//| .. method:: monotonic_ns() +//| .. function:: monotonic_ns() //| //| Return the time of the specified clock clk_id in nanoseconds. //| @@ -219,7 +220,7 @@ STATIC mp_obj_t time_monotonic_ns(void) { } MP_DEFINE_CONST_FUN_OBJ_0(time_monotonic_ns_obj, time_monotonic_ns); -//| .. method:: localtime([secs]) +//| .. function:: localtime([secs]) //| //| Convert a time expressed in seconds since Jan 1, 1970 to a struct_time in //| local time. If secs is not provided or None, the current time as returned @@ -245,7 +246,7 @@ STATIC mp_obj_t time_localtime(size_t n_args, const mp_obj_t *args) { } MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(time_localtime_obj, 0, 1, time_localtime); -//| .. method:: mktime(t) +//| .. function:: mktime(t) //| //| This is the inverse function of localtime(). Its argument is the //| struct_time or full 9-tuple (since the dst flag is needed; use -1 as the diff --git a/shared-bindings/uheap/__init__.c b/shared-bindings/uheap/__init__.c index df18237ac..0d699cd28 100644 --- a/shared-bindings/uheap/__init__.c +++ b/shared-bindings/uheap/__init__.c @@ -38,7 +38,7 @@ //| :synopsis: Heap size analysis //| -//| .. method:: info(object) +//| .. function:: info(object) //| //| Prints memory debugging info for the given object and returns the //| estimated size. diff --git a/shared-bindings/ustack/__init__.c b/shared-bindings/ustack/__init__.c index c4391c132..08b772e41 100644 --- a/shared-bindings/ustack/__init__.c +++ b/shared-bindings/ustack/__init__.c @@ -39,7 +39,7 @@ //| #if MICROPY_MAX_STACK_USAGE -//| .. method:: max_stack_usage() +//| .. function:: max_stack_usage() //| //| Return the maximum excursion of the stack so far. //| @@ -50,7 +50,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_0(max_stack_usage_obj, max_stack_usage); #endif // MICROPY_MAX_STACK_USAGE -//| .. method:: stack_size() +//| .. function:: stack_size() //| //| Return the size of the entire stack. //| Same as in micropython.mem_info(), but returns a value instead @@ -61,7 +61,7 @@ STATIC mp_obj_t stack_size(void) { } STATIC MP_DEFINE_CONST_FUN_OBJ_0(stack_size_obj, stack_size); -//| .. method:: stack_usage() +//| .. function:: stack_usage() //| //| Return how much stack is currently in use. //| Same as micropython.stack_use(); duplicated here for convenience. diff --git a/shared-bindings/wiznet/wiznet5k.c b/shared-bindings/wiznet/wiznet5k.c index 878095b2a..ac89cc691 100644 --- a/shared-bindings/wiznet/wiznet5k.c +++ b/shared-bindings/wiznet/wiznet5k.c @@ -138,7 +138,7 @@ const mp_obj_property_t wiznet5k_dhcp_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. method:: ifconfig(...) +//| .. method:: ifconfig(params=None) //| //| Called without parameters, returns a tuple of //| (ip_address, subnet_mask, gateway_address, dns_server) -- cgit v1.2.3 From 238e12123690debaf2cf8488fb2a4d4003a06506 Mon Sep 17 00:00:00 2001 From: Jeff Epler Date: Tue, 3 Dec 2019 14:50:37 -0600 Subject: protocols: Allow them to be (optionally) type-safe Protocols are nice, but there is no way for C code to verify whether a type's "protocol" structure actually implements some particular protocol. As a result, you can pass an object that implements the "vfs" protocol to one that expects the "stream" protocol, and the opposite of awesomeness ensues. This patch adds an OPTIONAL (but enabled by default) protocol identifier as the first member of any protocol structure. This identifier is simply a unique QSTR chosen by the protocol designer and used by each protocol implementer. When checking for protocol support, instead of just checking whether the object's type has a non-NULL protocol field, use `mp_proto_get` which implements the protocol check when possible. The existing protocols are now named: protocol_framebuf protocol_i2c protocol_pin protocol_stream protocol_spi protocol_vfs (most of these are unused in CP and are just inherited from MP; vfs and stream are definitely used though) I did not find any crashing examples, but here's one to give a flavor of what is improved, using `micropython_coverage`. Before the change, the vfs "ioctl" protocol is invoked, and the result is not intelligible as json (but it could have resulted in a hard fault, potentially): >>> import uos, ujson >>> u = uos.VfsPosix('/tmp') >>> ujson.load(u) Traceback (most recent call last): File "", line 1, in ValueError: syntax error in JSON After the change, the vfs object is correctly detected as not supporting the stream protocol: >>> ujson.load(p) Traceback (most recent call last): File "", line 1, in OSError: stream operation not supported --- extmod/machine_i2c.c | 21 +++++------ extmod/machine_i2c.h | 2 ++ extmod/machine_pinbase.c | 1 + extmod/machine_signal.c | 8 ++--- extmod/machine_spi.c | 7 ++-- extmod/machine_spi.h | 2 ++ extmod/modframebuf.c | 16 +++++---- extmod/modlwip.c | 1 + extmod/modussl_axtls.c | 1 + extmod/modussl_mbedtls.c | 1 + extmod/moduzlib.c | 1 + extmod/modwebrepl.c | 1 + extmod/modwebsocket.c | 1 + extmod/vfs.c | 2 +- extmod/vfs.h | 2 ++ extmod/vfs_fat.c | 1 + extmod/vfs_fat_file.c | 2 ++ extmod/vfs_posix.c | 1 + extmod/vfs_posix_file.c | 2 ++ extmod/virtpin.c | 5 +-- extmod/virtpin.h | 2 ++ lib/utils/sys_stdio_mphal.c | 2 ++ ports/unix/coverage.c | 2 ++ ports/unix/file.c | 2 ++ ports/unix/modusocket.c | 1 + py/modio.c | 2 ++ py/objstringio.c | 2 ++ py/proto.c | 50 +++++++++++++++++++++++++++ py/proto.h | 43 +++++++++++++++++++++++ py/py.mk | 1 + py/stream.c | 11 +++--- py/stream.h | 4 ++- shared-bindings/_bleio/CharacteristicBuffer.c | 1 + shared-bindings/busio/UART.c | 1 + shared-bindings/socket/__init__.c | 1 + shared-bindings/terminalio/Terminal.c | 1 + shared-bindings/usb_midi/PortIn.c | 1 + shared-bindings/usb_midi/PortOut.c | 1 + 38 files changed, 170 insertions(+), 36 deletions(-) create mode 100644 py/proto.c create mode 100644 py/proto.h (limited to 'shared-bindings/socket/__init__.c') diff --git a/extmod/machine_i2c.c b/extmod/machine_i2c.c index 85b46a9f6..4129ace0a 100644 --- a/extmod/machine_i2c.c +++ b/extmod/machine_i2c.c @@ -318,7 +318,7 @@ MP_DEFINE_CONST_FUN_OBJ_KW(machine_i2c_init_obj, 1, machine_i2c_obj_init); STATIC mp_obj_t machine_i2c_scan(mp_obj_t self_in) { mp_obj_base_t *self = MP_OBJ_TO_PTR(self_in); - mp_machine_i2c_p_t *i2c_p = (mp_machine_i2c_p_t*)self->type->protocol; + mp_machine_i2c_p_t *i2c_p = (mp_machine_i2c_p_t*)mp_proto_get(self, QSTR_protocol_i2c); mp_obj_t list = mp_obj_new_list(0, NULL); // 7-bit addresses 0b0000xxx and 0b1111xxx are reserved for (int addr = 0x08; addr < 0x78; ++addr) { @@ -333,7 +333,7 @@ MP_DEFINE_CONST_FUN_OBJ_1(machine_i2c_scan_obj, machine_i2c_scan); STATIC mp_obj_t machine_i2c_start(mp_obj_t self_in) { mp_obj_base_t *self = (mp_obj_base_t*)MP_OBJ_TO_PTR(self_in); - mp_machine_i2c_p_t *i2c_p = (mp_machine_i2c_p_t*)self->type->protocol; + mp_machine_i2c_p_t *i2c_p = (mp_machine_i2c_p_t*)mp_proto_get(self, QSTR_protocol_i2c); if (i2c_p->start == NULL) { mp_raise_msg(&mp_type_OSError, translate("I2C operation not supported")); } @@ -347,7 +347,7 @@ MP_DEFINE_CONST_FUN_OBJ_1(machine_i2c_start_obj, machine_i2c_start); STATIC mp_obj_t machine_i2c_stop(mp_obj_t self_in) { mp_obj_base_t *self = (mp_obj_base_t*)MP_OBJ_TO_PTR(self_in); - mp_machine_i2c_p_t *i2c_p = (mp_machine_i2c_p_t*)self->type->protocol; + mp_machine_i2c_p_t *i2c_p = (mp_machine_i2c_p_t*)mp_proto_get(self, QSTR_protocol_i2c); if (i2c_p->stop == NULL) { mp_raise_msg(&mp_type_OSError, translate("I2C operation not supported")); } @@ -361,7 +361,7 @@ MP_DEFINE_CONST_FUN_OBJ_1(machine_i2c_stop_obj, machine_i2c_stop); STATIC mp_obj_t machine_i2c_readinto(size_t n_args, const mp_obj_t *args) { mp_obj_base_t *self = (mp_obj_base_t*)MP_OBJ_TO_PTR(args[0]); - mp_machine_i2c_p_t *i2c_p = (mp_machine_i2c_p_t*)self->type->protocol; + mp_machine_i2c_p_t *i2c_p = (mp_machine_i2c_p_t*)mp_proto_get(self, QSTR_protocol_i2c); if (i2c_p->read == NULL) { mp_raise_msg(&mp_type_OSError, translate("I2C operation not supported")); } @@ -385,7 +385,7 @@ MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(machine_i2c_readinto_obj, 2, 3, machine_i2c_ STATIC mp_obj_t machine_i2c_write(mp_obj_t self_in, mp_obj_t buf_in) { mp_obj_base_t *self = (mp_obj_base_t*)MP_OBJ_TO_PTR(self_in); - mp_machine_i2c_p_t *i2c_p = (mp_machine_i2c_p_t*)self->type->protocol; + mp_machine_i2c_p_t *i2c_p = (mp_machine_i2c_p_t*)mp_proto_get(self, QSTR_protocol_i2c); if (i2c_p->write == NULL) { mp_raise_msg(&mp_type_OSError, translate("I2C operation not supported")); } @@ -407,7 +407,7 @@ MP_DEFINE_CONST_FUN_OBJ_2(machine_i2c_write_obj, machine_i2c_write); STATIC mp_obj_t machine_i2c_readfrom(size_t n_args, const mp_obj_t *args) { mp_obj_base_t *self = (mp_obj_base_t*)MP_OBJ_TO_PTR(args[0]); - mp_machine_i2c_p_t *i2c_p = (mp_machine_i2c_p_t*)self->type->protocol; + mp_machine_i2c_p_t *i2c_p = (mp_machine_i2c_p_t*)mp_proto_get(self, QSTR_protocol_i2c); mp_int_t addr = mp_obj_get_int(args[1]); vstr_t vstr; vstr_init_len(&vstr, mp_obj_get_int(args[2])); @@ -422,7 +422,7 @@ MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(machine_i2c_readfrom_obj, 3, 4, machine_i2c_ STATIC mp_obj_t machine_i2c_readfrom_into(size_t n_args, const mp_obj_t *args) { mp_obj_base_t *self = (mp_obj_base_t*)MP_OBJ_TO_PTR(args[0]); - mp_machine_i2c_p_t *i2c_p = (mp_machine_i2c_p_t*)self->type->protocol; + mp_machine_i2c_p_t *i2c_p = (mp_machine_i2c_p_t*)mp_proto_get(self, QSTR_protocol_i2c); mp_int_t addr = mp_obj_get_int(args[1]); mp_buffer_info_t bufinfo; mp_get_buffer_raise(args[2], &bufinfo, MP_BUFFER_WRITE); @@ -437,7 +437,7 @@ MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(machine_i2c_readfrom_into_obj, 3, 4, machine STATIC mp_obj_t machine_i2c_writeto(size_t n_args, const mp_obj_t *args) { mp_obj_base_t *self = (mp_obj_base_t*)MP_OBJ_TO_PTR(args[0]); - mp_machine_i2c_p_t *i2c_p = (mp_machine_i2c_p_t*)self->type->protocol; + mp_machine_i2c_p_t *i2c_p = (mp_machine_i2c_p_t*)mp_proto_get(self, QSTR_protocol_i2c); mp_int_t addr = mp_obj_get_int(args[1]); mp_buffer_info_t bufinfo; mp_get_buffer_raise(args[2], &bufinfo, MP_BUFFER_READ); @@ -453,7 +453,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(machine_i2c_writeto_obj, 3, 4, machin STATIC int read_mem(mp_obj_t self_in, uint16_t addr, uint32_t memaddr, uint8_t addrsize, uint8_t *buf, size_t len) { mp_obj_base_t *self = (mp_obj_base_t*)MP_OBJ_TO_PTR(self_in); - mp_machine_i2c_p_t *i2c_p = (mp_machine_i2c_p_t*)self->type->protocol; + mp_machine_i2c_p_t *i2c_p = (mp_machine_i2c_p_t*)mp_proto_get(self, QSTR_protocol_i2c); uint8_t memaddr_buf[4]; size_t memaddr_len = 0; for (int16_t i = addrsize - 8; i >= 0; i -= 8) { @@ -473,7 +473,7 @@ STATIC int read_mem(mp_obj_t self_in, uint16_t addr, uint32_t memaddr, uint8_t a STATIC int write_mem(mp_obj_t self_in, uint16_t addr, uint32_t memaddr, uint8_t addrsize, const uint8_t *buf, size_t len) { mp_obj_base_t *self = (mp_obj_base_t*)MP_OBJ_TO_PTR(self_in); - mp_machine_i2c_p_t *i2c_p = (mp_machine_i2c_p_t*)self->type->protocol; + mp_machine_i2c_p_t *i2c_p = (mp_machine_i2c_p_t*)mp_proto_get(self, QSTR_protocol_i2c); // need some memory to create the buffer to send; try to use stack if possible uint8_t buf2_stack[MAX_MEMADDR_SIZE + BUF_STACK_SIZE]; @@ -621,6 +621,7 @@ int mp_machine_soft_i2c_write(mp_obj_base_t *self_in, const uint8_t *src, size_t } STATIC const mp_machine_i2c_p_t mp_machine_soft_i2c_p = { + MP_PROTO_IMPLEMENT(MP_QSTR_protocol_i2c) .start = (int(*)(mp_obj_base_t*))mp_hal_i2c_start, .stop = (int(*)(mp_obj_base_t*))mp_hal_i2c_stop, .read = mp_machine_soft_i2c_read, diff --git a/extmod/machine_i2c.h b/extmod/machine_i2c.h index f5af6656f..7f5ee568e 100644 --- a/extmod/machine_i2c.h +++ b/extmod/machine_i2c.h @@ -27,10 +27,12 @@ #define MICROPY_INCLUDED_EXTMOD_MACHINE_I2C_H #include "py/obj.h" +#include "py/proto.h" // I2C protocol // the first 4 methods can be NULL, meaning operation is not supported typedef struct _mp_machine_i2c_p_t { + MP_PROTOCOL_HEAD int (*start)(mp_obj_base_t *obj); int (*stop)(mp_obj_base_t *obj); int (*read)(mp_obj_base_t *obj, uint8_t *dest, size_t len, bool nack); diff --git a/extmod/machine_pinbase.c b/extmod/machine_pinbase.c index 997a6fd99..6cd14c187 100644 --- a/extmod/machine_pinbase.c +++ b/extmod/machine_pinbase.c @@ -74,6 +74,7 @@ mp_uint_t pinbase_ioctl(mp_obj_t obj, mp_uint_t request, uintptr_t arg, int *err } STATIC const mp_pin_p_t pinbase_pin_p = { + MP_PROTO_IMPLEMENT(MP_QSTR_protocol_pin) .ioctl = pinbase_ioctl, }; diff --git a/extmod/machine_signal.c b/extmod/machine_signal.c index 62658cbb1..50501e34f 100644 --- a/extmod/machine_signal.c +++ b/extmod/machine_signal.c @@ -47,12 +47,7 @@ STATIC mp_obj_t signal_make_new(const mp_obj_type_t *type, size_t n_args, const bool invert = false; #if defined(MICROPY_PY_MACHINE_PIN_MAKE_NEW) - mp_pin_p_t *pin_p = NULL; - - if (MP_OBJ_IS_OBJ(pin)) { - mp_obj_base_t *pin_base = (mp_obj_base_t*)MP_OBJ_TO_PTR(args[0]); - pin_p = (mp_pin_p_t*)pin_base->type->protocol; - } + mp_pin_p_t *pin_p = (mp_pin_t*)mp_proto_get(QSTR_pin_protocol, pin); if (pin_p == NULL) { // If first argument isn't a Pin-like object, we filter out "invert" @@ -170,6 +165,7 @@ STATIC const mp_rom_map_elem_t signal_locals_dict_table[] = { STATIC MP_DEFINE_CONST_DICT(signal_locals_dict, signal_locals_dict_table); STATIC const mp_pin_p_t signal_pin_p = { + MP_PROTO_IMPLEMENT(MP_QSTR_protocol_pin) .ioctl = signal_ioctl, }; diff --git a/extmod/machine_spi.c b/extmod/machine_spi.c index c5707a3d0..4ead321d9 100644 --- a/extmod/machine_spi.c +++ b/extmod/machine_spi.c @@ -67,7 +67,7 @@ mp_obj_t mp_machine_spi_make_new(const mp_obj_type_t *type, size_t n_args, const STATIC mp_obj_t machine_spi_init(size_t n_args, const mp_obj_t *args, mp_map_t *kw_args) { mp_obj_base_t *s = (mp_obj_base_t*)MP_OBJ_TO_PTR(args[0]); - mp_machine_spi_p_t *spi_p = (mp_machine_spi_p_t*)s->type->protocol; + mp_machine_spi_p_t *spi_p = (mp_machine_spi_p_t*)mp_proto_get(QSTR_protocol_spi, s); spi_p->init(s, n_args - 1, args + 1, kw_args); return mp_const_none; } @@ -75,7 +75,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_KW(machine_spi_init_obj, 1, machine_spi_init); STATIC mp_obj_t machine_spi_deinit(mp_obj_t self) { mp_obj_base_t *s = (mp_obj_base_t*)MP_OBJ_TO_PTR(self); - mp_machine_spi_p_t *spi_p = (mp_machine_spi_p_t*)s->type->protocol; + mp_machine_spi_p_t *spi_p = (mp_machine_spi_p_t*)mp_proto_get(QSTR_protocol_spi, s); if (spi_p->deinit != NULL) { spi_p->deinit(s); } @@ -85,7 +85,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_1(machine_spi_deinit_obj, machine_spi_deinit); STATIC void mp_machine_spi_transfer(mp_obj_t self, size_t len, const void *src, void *dest) { mp_obj_base_t *s = (mp_obj_base_t*)MP_OBJ_TO_PTR(self); - mp_machine_spi_p_t *spi_p = (mp_machine_spi_p_t*)s->type->protocol; + mp_machine_spi_p_t *spi_p = (mp_machine_spi_p_t*)mp_proto_get(QSTR_protocol_spi, s); spi_p->transfer(s, len, src, dest); } @@ -268,6 +268,7 @@ STATIC void mp_machine_soft_spi_transfer(mp_obj_base_t *self_in, size_t len, con } const mp_machine_spi_p_t mp_machine_soft_spi_p = { + MP_PROTO_IMPLEMENT(MP_QSTR_protocol_spi) .init = mp_machine_soft_spi_init, .deinit = NULL, .transfer = mp_machine_soft_spi_transfer, diff --git a/extmod/machine_spi.h b/extmod/machine_spi.h index db21e1cd3..365b44d6e 100644 --- a/extmod/machine_spi.h +++ b/extmod/machine_spi.h @@ -27,11 +27,13 @@ #define MICROPY_INCLUDED_EXTMOD_MACHINE_SPI_H #include "py/obj.h" +#include "py/proto.h" #include "py/mphal.h" #include "drivers/bus/spi.h" // SPI protocol typedef struct _mp_machine_spi_p_t { + MP_PROTOCOL_HEAD void (*init)(mp_obj_base_t *obj, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args); void (*deinit)(mp_obj_base_t *obj); // can be NULL void (*transfer)(mp_obj_base_t *obj, size_t len, const uint8_t *src, uint8_t *dest); diff --git a/extmod/modframebuf.c b/extmod/modframebuf.c index 561b842bc..a51d1c380 100644 --- a/extmod/modframebuf.c +++ b/extmod/modframebuf.c @@ -28,6 +28,7 @@ #include #include "py/runtime.h" +#include "py/proto.h" #if MICROPY_PY_FRAMEBUF @@ -46,6 +47,7 @@ typedef uint32_t (*getpixel_t)(const mp_obj_framebuf_t*, int, int); typedef void (*fill_rect_t)(const mp_obj_framebuf_t *, int, int, int, int, uint32_t); typedef struct _mp_framebuf_p_t { + MP_PROTOCOL_HEAD setpixel_t setpixel; getpixel_t getpixel; fill_rect_t fill_rect; @@ -227,13 +229,13 @@ STATIC void gs8_fill_rect(const mp_obj_framebuf_t *fb, int x, int y, int w, int } STATIC mp_framebuf_p_t formats[] = { - [FRAMEBUF_MVLSB] = {mvlsb_setpixel, mvlsb_getpixel, mvlsb_fill_rect}, - [FRAMEBUF_RGB565] = {rgb565_setpixel, rgb565_getpixel, rgb565_fill_rect}, - [FRAMEBUF_GS2_HMSB] = {gs2_hmsb_setpixel, gs2_hmsb_getpixel, gs2_hmsb_fill_rect}, - [FRAMEBUF_GS4_HMSB] = {gs4_hmsb_setpixel, gs4_hmsb_getpixel, gs4_hmsb_fill_rect}, - [FRAMEBUF_GS8] = {gs8_setpixel, gs8_getpixel, gs8_fill_rect}, - [FRAMEBUF_MHLSB] = {mono_horiz_setpixel, mono_horiz_getpixel, mono_horiz_fill_rect}, - [FRAMEBUF_MHMSB] = {mono_horiz_setpixel, mono_horiz_getpixel, mono_horiz_fill_rect}, + [FRAMEBUF_MVLSB] = {MP_PROTO_IMPLEMENT(MP_QSTR_protocol_framebuf) mvlsb_setpixel, mvlsb_getpixel, mvlsb_fill_rect}, + [FRAMEBUF_RGB565] = {MP_PROTO_IMPLEMENT(MP_QSTR_protocol_framebuf) rgb565_setpixel, rgb565_getpixel, rgb565_fill_rect}, + [FRAMEBUF_GS2_HMSB] = {MP_PROTO_IMPLEMENT(MP_QSTR_protocol_framebuf) gs2_hmsb_setpixel, gs2_hmsb_getpixel, gs2_hmsb_fill_rect}, + [FRAMEBUF_GS4_HMSB] = {MP_PROTO_IMPLEMENT(MP_QSTR_protocol_framebuf) gs4_hmsb_setpixel, gs4_hmsb_getpixel, gs4_hmsb_fill_rect}, + [FRAMEBUF_GS8] = {MP_PROTO_IMPLEMENT(MP_QSTR_protocol_framebuf) gs8_setpixel, gs8_getpixel, gs8_fill_rect}, + [FRAMEBUF_MHLSB] = {MP_PROTO_IMPLEMENT(MP_QSTR_protocol_framebuf) mono_horiz_setpixel, mono_horiz_getpixel, mono_horiz_fill_rect}, + [FRAMEBUF_MHMSB] = {MP_PROTO_IMPLEMENT(MP_QSTR_protocol_framebuf) mono_horiz_setpixel, mono_horiz_getpixel, mono_horiz_fill_rect}, }; static inline void setpixel(const mp_obj_framebuf_t *fb, int x, int y, uint32_t col) { diff --git a/extmod/modlwip.c b/extmod/modlwip.c index e5e92c42b..776b81ee5 100644 --- a/extmod/modlwip.c +++ b/extmod/modlwip.c @@ -1261,6 +1261,7 @@ STATIC const mp_rom_map_elem_t lwip_socket_locals_dict_table[] = { STATIC MP_DEFINE_CONST_DICT(lwip_socket_locals_dict, lwip_socket_locals_dict_table); STATIC const mp_stream_p_t lwip_socket_stream_p = { + MP_PROTO_IMPLEMENT(MP_QSTR_protocol_stream) .read = lwip_socket_read, .write = lwip_socket_write, .ioctl = lwip_socket_ioctl, diff --git a/extmod/modussl_axtls.c b/extmod/modussl_axtls.c index cfa652585..032dea09f 100644 --- a/extmod/modussl_axtls.c +++ b/extmod/modussl_axtls.c @@ -221,6 +221,7 @@ STATIC const mp_rom_map_elem_t ussl_socket_locals_dict_table[] = { STATIC MP_DEFINE_CONST_DICT(ussl_socket_locals_dict, ussl_socket_locals_dict_table); STATIC const mp_stream_p_t ussl_socket_stream_p = { + MP_PROTO_IMPLEMENT(MP_QSTR_protocol_stream) .read = socket_read, .write = socket_write, .ioctl = socket_ioctl, diff --git a/extmod/modussl_mbedtls.c b/extmod/modussl_mbedtls.c index 08807d20b..9abdeb966 100644 --- a/extmod/modussl_mbedtls.c +++ b/extmod/modussl_mbedtls.c @@ -305,6 +305,7 @@ STATIC const mp_rom_map_elem_t ussl_socket_locals_dict_table[] = { STATIC MP_DEFINE_CONST_DICT(ussl_socket_locals_dict, ussl_socket_locals_dict_table); STATIC const mp_stream_p_t ussl_socket_stream_p = { + MP_PROTO_IMPLEMENT(MP_QSTR_protocol_stream) .read = socket_read, .write = socket_write, .ioctl = socket_ioctl, diff --git a/extmod/moduzlib.c b/extmod/moduzlib.c index 7f15d02a8..3a081bc45 100644 --- a/extmod/moduzlib.c +++ b/extmod/moduzlib.c @@ -134,6 +134,7 @@ STATIC const mp_rom_map_elem_t decompio_locals_dict_table[] = { STATIC MP_DEFINE_CONST_DICT(decompio_locals_dict, decompio_locals_dict_table); STATIC const mp_stream_p_t decompio_stream_p = { + MP_PROTO_IMPLEMENT(MP_QSTR_protocol_stream) .read = decompio_read, }; diff --git a/extmod/modwebrepl.c b/extmod/modwebrepl.c index 06da210d1..fb4d97358 100644 --- a/extmod/modwebrepl.c +++ b/extmod/modwebrepl.c @@ -331,6 +331,7 @@ STATIC const mp_rom_map_elem_t webrepl_locals_dict_table[] = { STATIC MP_DEFINE_CONST_DICT(webrepl_locals_dict, webrepl_locals_dict_table); STATIC const mp_stream_p_t webrepl_stream_p = { + MP_PROTO_IMPLEMENT(MP_QSTR_protocol_stream) .read = webrepl_read, .write = webrepl_write, .ioctl = webrepl_ioctl, diff --git a/extmod/modwebsocket.c b/extmod/modwebsocket.c index 997c7e262..496e4b5bb 100644 --- a/extmod/modwebsocket.c +++ b/extmod/modwebsocket.c @@ -286,6 +286,7 @@ STATIC const mp_rom_map_elem_t websocket_locals_dict_table[] = { STATIC MP_DEFINE_CONST_DICT(websocket_locals_dict, websocket_locals_dict_table); STATIC const mp_stream_p_t websocket_stream_p = { + MP_PROTO_IMPLEMENT(MP_QSTR_protocol_stream) .read = websocket_read, .write = websocket_write, .ioctl = websocket_ioctl, diff --git a/extmod/vfs.c b/extmod/vfs.c index 7d6e6999b..2bb4057e7 100644 --- a/extmod/vfs.c +++ b/extmod/vfs.c @@ -126,7 +126,7 @@ mp_import_stat_t mp_vfs_import_stat(const char *path) { } // If the mounted object has the VFS protocol, call its import_stat helper - const mp_vfs_proto_t *proto = mp_obj_get_type(vfs->obj)->protocol; + const mp_vfs_proto_t *proto = (mp_vfs_proto_t*)mp_proto_get(MP_QSTR_protocol_vfs, vfs->obj); if (proto != NULL) { return proto->import_stat(MP_OBJ_TO_PTR(vfs->obj), path_out); } diff --git a/extmod/vfs.h b/extmod/vfs.h index 38c77943c..6c0692365 100644 --- a/extmod/vfs.h +++ b/extmod/vfs.h @@ -28,6 +28,7 @@ #include "py/lexer.h" #include "py/obj.h" +#include "py/proto.h" // return values of mp_vfs_lookup_path // ROOT is 0 so that the default current directory is the root directory @@ -47,6 +48,7 @@ // At the moment the VFS protocol just has import_stat, but could be extended to other methods typedef struct _mp_vfs_proto_t { + MP_PROTOCOL_HEAD mp_import_stat_t (*import_stat)(void *self, const char *path); } mp_vfs_proto_t; diff --git a/extmod/vfs_fat.c b/extmod/vfs_fat.c index 20d3e3e5c..60f4393f4 100644 --- a/extmod/vfs_fat.c +++ b/extmod/vfs_fat.c @@ -488,6 +488,7 @@ STATIC const mp_rom_map_elem_t fat_vfs_locals_dict_table[] = { STATIC MP_DEFINE_CONST_DICT(fat_vfs_locals_dict, fat_vfs_locals_dict_table); STATIC const mp_vfs_proto_t fat_vfs_proto = { + MP_PROTO_IMPLEMENT(MP_QSTR_protocol_vfs) .import_stat = fat_vfs_import_stat, }; diff --git a/extmod/vfs_fat_file.c b/extmod/vfs_fat_file.c index 6aad1884c..3ea9cee52 100644 --- a/extmod/vfs_fat_file.c +++ b/extmod/vfs_fat_file.c @@ -254,6 +254,7 @@ STATIC MP_DEFINE_CONST_DICT(rawfile_locals_dict, rawfile_locals_dict_table); #if MICROPY_PY_IO_FILEIO STATIC const mp_stream_p_t fileio_stream_p = { + MP_PROTO_IMPLEMENT(MP_QSTR_protocol_stream) .read = file_obj_read, .write = file_obj_write, .ioctl = file_obj_ioctl, @@ -272,6 +273,7 @@ const mp_obj_type_t mp_type_vfs_fat_fileio = { #endif STATIC const mp_stream_p_t textio_stream_p = { + MP_PROTO_IMPLEMENT(MP_QSTR_protocol_stream) .read = file_obj_read, .write = file_obj_write, .ioctl = file_obj_ioctl, diff --git a/extmod/vfs_posix.c b/extmod/vfs_posix.c index d28dfe451..56a5de303 100644 --- a/extmod/vfs_posix.c +++ b/extmod/vfs_posix.c @@ -350,6 +350,7 @@ STATIC const mp_rom_map_elem_t vfs_posix_locals_dict_table[] = { STATIC MP_DEFINE_CONST_DICT(vfs_posix_locals_dict, vfs_posix_locals_dict_table); STATIC const mp_vfs_proto_t vfs_posix_proto = { + MP_PROTO_IMPLEMENT(MP_QSTR_protocol_vfs) .import_stat = mp_vfs_posix_import_stat, }; diff --git a/extmod/vfs_posix_file.c b/extmod/vfs_posix_file.c index b760b3847..be455fa28 100644 --- a/extmod/vfs_posix_file.c +++ b/extmod/vfs_posix_file.c @@ -220,6 +220,7 @@ STATIC MP_DEFINE_CONST_DICT(rawfile_locals_dict, rawfile_locals_dict_table); #if MICROPY_PY_IO_FILEIO STATIC const mp_stream_p_t fileio_stream_p = { + MP_PROTO_IMPLEMENT(MP_QSTR_protocol_stream) .read = vfs_posix_file_read, .write = vfs_posix_file_write, .ioctl = vfs_posix_file_ioctl, @@ -238,6 +239,7 @@ const mp_obj_type_t mp_type_vfs_posix_fileio = { #endif STATIC const mp_stream_p_t textio_stream_p = { + MP_PROTO_IMPLEMENT(MP_QSTR_protocol_stream) .read = vfs_posix_file_read, .write = vfs_posix_file_write, .ioctl = vfs_posix_file_ioctl, diff --git a/extmod/virtpin.c b/extmod/virtpin.c index dbfa21d66..559f99265 100644 --- a/extmod/virtpin.c +++ b/extmod/virtpin.c @@ -25,15 +25,16 @@ */ #include "extmod/virtpin.h" +#include "py/proto.h" int mp_virtual_pin_read(mp_obj_t pin) { mp_obj_base_t* s = (mp_obj_base_t*)MP_OBJ_TO_PTR(pin); - mp_pin_p_t *pin_p = (mp_pin_p_t*)s->type->protocol; + const mp_pin_p_t *pin_p = mp_proto_get(MP_QSTR_protocol_pin, s); return pin_p->ioctl(pin, MP_PIN_READ, 0, NULL); } void mp_virtual_pin_write(mp_obj_t pin, int value) { mp_obj_base_t* s = (mp_obj_base_t*)MP_OBJ_TO_PTR(pin); - mp_pin_p_t *pin_p = (mp_pin_p_t*)s->type->protocol; + const mp_pin_p_t *pin_p = mp_proto_get(MP_QSTR_protocol_pin, s); pin_p->ioctl(pin, MP_PIN_WRITE, value, NULL); } diff --git a/extmod/virtpin.h b/extmod/virtpin.h index 706affc19..591249e48 100644 --- a/extmod/virtpin.h +++ b/extmod/virtpin.h @@ -27,6 +27,7 @@ #define MICROPY_INCLUDED_EXTMOD_VIRTPIN_H #include "py/obj.h" +#include "py/proto.h" #define MP_PIN_READ (1) #define MP_PIN_WRITE (2) @@ -35,6 +36,7 @@ // Pin protocol typedef struct _mp_pin_p_t { + MP_PROTOCOL_HEAD mp_uint_t (*ioctl)(mp_obj_t obj, mp_uint_t request, uintptr_t arg, int *errcode); } mp_pin_p_t; diff --git a/lib/utils/sys_stdio_mphal.c b/lib/utils/sys_stdio_mphal.c index 266783f37..c1607dfe8 100644 --- a/lib/utils/sys_stdio_mphal.c +++ b/lib/utils/sys_stdio_mphal.c @@ -123,6 +123,7 @@ STATIC const mp_rom_map_elem_t stdio_locals_dict_table[] = { STATIC MP_DEFINE_CONST_DICT(stdio_locals_dict, stdio_locals_dict_table); STATIC const mp_stream_p_t stdio_obj_stream_p = { + MP_PROTO_IMPLEMENT(MP_QSTR_protocol_stream) .read = stdio_read, .write = stdio_write, .ioctl = stdio_ioctl, @@ -158,6 +159,7 @@ STATIC mp_uint_t stdio_buffer_write(mp_obj_t self_in, const void *buf, mp_uint_t } STATIC const mp_stream_p_t stdio_buffer_obj_stream_p = { + MP_PROTO_IMPLEMENT(MP_QSTR_protocol_stream) .read = stdio_buffer_read, .write = stdio_buffer_write, .is_text = false, diff --git a/ports/unix/coverage.c b/ports/unix/coverage.c index 841924c58..849820fff 100644 --- a/ports/unix/coverage.c +++ b/ports/unix/coverage.c @@ -96,6 +96,7 @@ STATIC const mp_rom_map_elem_t rawfile_locals_dict_table[] = { STATIC MP_DEFINE_CONST_DICT(rawfile_locals_dict, rawfile_locals_dict_table); STATIC const mp_stream_p_t fileio_stream_p = { + MP_PROTO_IMPLEMENT(MP_QSTR_protocol_stream) .read = stest_read, .write = stest_write, .ioctl = stest_ioctl, @@ -123,6 +124,7 @@ STATIC const mp_rom_map_elem_t rawfile_locals_dict_table2[] = { STATIC MP_DEFINE_CONST_DICT(rawfile_locals_dict2, rawfile_locals_dict_table2); STATIC const mp_stream_p_t textio_stream_p2 = { + MP_PROTO_IMPLEMENT(MP_QSTR_protocol_stream) .read = stest_read2, .write = NULL, .is_text = true, diff --git a/ports/unix/file.c b/ports/unix/file.c index c0cf6dcc4..e5c73d26c 100644 --- a/ports/unix/file.c +++ b/ports/unix/file.c @@ -230,6 +230,7 @@ STATIC MP_DEFINE_CONST_DICT(rawfile_locals_dict, rawfile_locals_dict_table); #if MICROPY_PY_IO_FILEIO STATIC const mp_stream_p_t fileio_stream_p = { + MP_PROTO_IMPLEMENT(MP_QSTR_protocol_stream) .read = fdfile_read, .write = fdfile_write, .ioctl = fdfile_ioctl, @@ -248,6 +249,7 @@ const mp_obj_type_t mp_type_fileio = { #endif STATIC const mp_stream_p_t textio_stream_p = { + MP_PROTO_IMPLEMENT(MP_QSTR_protocol_stream) .read = fdfile_read, .write = fdfile_write, .ioctl = fdfile_ioctl, diff --git a/ports/unix/modusocket.c b/ports/unix/modusocket.c index 84e9298fd..95da276ed 100644 --- a/ports/unix/modusocket.c +++ b/ports/unix/modusocket.c @@ -374,6 +374,7 @@ STATIC const mp_rom_map_elem_t usocket_locals_dict_table[] = { STATIC MP_DEFINE_CONST_DICT(usocket_locals_dict, usocket_locals_dict_table); STATIC const mp_stream_p_t usocket_stream_p = { + MP_PROTO_IMPLEMENT(MP_QSTR_protocol_stream) .read = socket_read, .write = socket_write, .ioctl = socket_ioctl, diff --git a/py/modio.c b/py/modio.c index d7c1a58a8..17840a6d8 100644 --- a/py/modio.c +++ b/py/modio.c @@ -90,6 +90,7 @@ STATIC mp_uint_t iobase_ioctl(mp_obj_t obj, mp_uint_t request, uintptr_t arg, in } STATIC const mp_stream_p_t iobase_p = { + MP_PROTO_IMPLEMENT(MP_QSTR_protocol_stream) .read = iobase_read, .write = iobase_write, .ioctl = iobase_ioctl, @@ -185,6 +186,7 @@ STATIC const mp_rom_map_elem_t bufwriter_locals_dict_table[] = { STATIC MP_DEFINE_CONST_DICT(bufwriter_locals_dict, bufwriter_locals_dict_table); STATIC const mp_stream_p_t bufwriter_stream_p = { + MP_PROTO_IMPLEMENT(MP_QSTR_protocol_stream) .write = bufwriter_write, }; diff --git a/py/objstringio.c b/py/objstringio.c index d2ca6decd..178e6446c 100644 --- a/py/objstringio.c +++ b/py/objstringio.c @@ -240,6 +240,7 @@ STATIC const mp_rom_map_elem_t stringio_locals_dict_table[] = { STATIC MP_DEFINE_CONST_DICT(stringio_locals_dict, stringio_locals_dict_table); STATIC const mp_stream_p_t stringio_stream_p = { + MP_PROTO_IMPLEMENT(MP_QSTR_protocol_stream) .read = stringio_read, .write = stringio_write, .ioctl = stringio_ioctl, @@ -247,6 +248,7 @@ STATIC const mp_stream_p_t stringio_stream_p = { }; STATIC const mp_stream_p_t bytesio_stream_p = { + MP_PROTO_IMPLEMENT(MP_QSTR_protocol_stream) .read = stringio_read, .write = stringio_write, .ioctl = stringio_ioctl, diff --git a/py/proto.c b/py/proto.c new file mode 100644 index 000000000..030b62674 --- /dev/null +++ b/py/proto.c @@ -0,0 +1,50 @@ +/* + * This file is part of the MicroPython project, http://micropython.org/ + * + * The MIT License (MIT) + * + * Copyright (c) 2019 Jeff Epler for Adafruit Industries + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + * THE SOFTWARE. + */ + +#include "py/obj.h" +#include "py/proto.h" +#include "py/runtime.h" + +#ifndef MICROPY_UNSAFE_PROTO +const void *mp_proto_get(uint16_t name, mp_const_obj_t obj) { + mp_obj_type_t *type = mp_obj_get_type(obj); + if (!type->protocol) return NULL; + uint16_t proto_name = *(const uint16_t*) type->protocol; + if (proto_name == name) { + return type->protocol; + } + return NULL; +} +#endif + +const void *mp_proto_get_or_throw(uint16_t name, mp_const_obj_t obj) { + const void *proto = mp_proto_get(name, obj); + if (proto) { + return proto; + } + mp_raise_TypeError_varg(translate("'%s' object does not support '%s'"), + mp_obj_get_type_str(obj), qstr_str(name)); +} diff --git a/py/proto.h b/py/proto.h new file mode 100644 index 000000000..2d4f80565 --- /dev/null +++ b/py/proto.h @@ -0,0 +1,43 @@ +/* + * This file is part of the MicroPython project, http://micropython.org/ + * + * The MIT License (MIT) + * + * Copyright (c) 2019 Jeff Epler for Adafruit Industries + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + * THE SOFTWARE. + */ + +#ifndef MICROPY_INCLUDED_PY_PROTO_H +#define MICROPY_INCLUDED_PY_PROTO_H + +#ifdef MICROPY_UNSAFE_PROTO +#define MP_PROTOCOL_HEAD /* NOTHING */ +#define MP_PROTO_IMPLEMENT(name) /* NOTHING */ +static inline void *mp_proto_get(uint16_t name, mp_const_obj_type_t obj) { return mp_obj_get_type(obj)->protocol; } +#else +#define MP_PROTOCOL_HEAD \ + uint16_t name; // The name of this protocol, a qstr +#define MP_PROTO_IMPLEMENT(n) .name = n, +const void *mp_proto_get(uint16_t name, mp_const_obj_t obj); +const void *mp_proto_get_or_throw(uint16_t name, mp_const_obj_t obj); +#endif + +#endif + diff --git a/py/py.mk b/py/py.mk index 17cb79264..ae9b005b6 100644 --- a/py/py.mk +++ b/py/py.mk @@ -214,6 +214,7 @@ PY_CORE_O_BASENAME = $(addprefix py/,\ objtype.o \ objzip.o \ opmethods.o \ + proto.o \ reload.o \ sequence.o \ stream.o \ diff --git a/py/stream.c b/py/stream.c index 1d25f6470..2ff2b76a6 100644 --- a/py/stream.c +++ b/py/stream.c @@ -86,8 +86,7 @@ mp_uint_t mp_stream_rw(mp_obj_t stream, void *buf_, mp_uint_t size, int *errcode } const mp_stream_p_t *mp_get_stream_raise(mp_obj_t self_in, int flags) { - mp_obj_type_t *type = mp_obj_get_type(self_in); - const mp_stream_p_t *stream_p = type->protocol; + const mp_stream_p_t *stream_p = mp_proto_get(MP_QSTR_protocol_stream, self_in); if (stream_p == NULL || ((flags & MP_STREAM_OP_READ) && stream_p->read == NULL) || ((flags & MP_STREAM_OP_WRITE) && stream_p->write == NULL) @@ -522,7 +521,7 @@ int mp_stream_errno; ssize_t mp_stream_posix_write(mp_obj_t stream, const void *buf, size_t len) { mp_obj_base_t* o = (mp_obj_base_t*)MP_OBJ_TO_PTR(stream); - const mp_stream_p_t *stream_p = o->type->protocol; + const mp_stream_p_t *stream_p = mp_get_stream(o); mp_uint_t out_sz = stream_p->write(stream, buf, len, &mp_stream_errno); if (out_sz == MP_STREAM_ERROR) { return -1; @@ -533,7 +532,7 @@ ssize_t mp_stream_posix_write(mp_obj_t stream, const void *buf, size_t len) { ssize_t mp_stream_posix_read(mp_obj_t stream, void *buf, size_t len) { mp_obj_base_t* o = (mp_obj_base_t*)MP_OBJ_TO_PTR(stream); - const mp_stream_p_t *stream_p = o->type->protocol; + const mp_stream_p_t *stream_p = mp_get_stream(o); mp_uint_t out_sz = stream_p->read(stream, buf, len, &mp_stream_errno); if (out_sz == MP_STREAM_ERROR) { return -1; @@ -544,7 +543,7 @@ ssize_t mp_stream_posix_read(mp_obj_t stream, void *buf, size_t len) { off_t mp_stream_posix_lseek(mp_obj_t stream, off_t offset, int whence) { const mp_obj_base_t* o = (mp_obj_base_t*)MP_OBJ_TO_PTR(stream); - const mp_stream_p_t *stream_p = o->type->protocol; + const mp_stream_p_t *stream_p = mp_get_stream(o); struct mp_stream_seek_t seek_s; seek_s.offset = offset; seek_s.whence = whence; @@ -557,7 +556,7 @@ off_t mp_stream_posix_lseek(mp_obj_t stream, off_t offset, int whence) { int mp_stream_posix_fsync(mp_obj_t stream) { mp_obj_base_t* o = (mp_obj_base_t*)MP_OBJ_TO_PTR(stream); - const mp_stream_p_t *stream_p = o->type->protocol; + const mp_stream_p_t *stream_p = mp_get_stream(o); mp_uint_t res = stream_p->ioctl(stream, MP_STREAM_FLUSH, 0, &mp_stream_errno); if (res == MP_STREAM_ERROR) { return -1; diff --git a/py/stream.h b/py/stream.h index 03e24c746..543fe8c82 100644 --- a/py/stream.h +++ b/py/stream.h @@ -27,6 +27,7 @@ #define MICROPY_INCLUDED_PY_STREAM_H #include "py/obj.h" +#include "py/proto.h" #include "py/mperrno.h" #define MP_STREAM_ERROR ((mp_uint_t)-1) @@ -64,6 +65,7 @@ struct mp_stream_seek_t { // Stream protocol typedef struct _mp_stream_p_t { + MP_PROTOCOL_HEAD // On error, functions should return MP_STREAM_ERROR and fill in *errcode (values // are implementation-dependent, but will be exposed to user, e.g. via exception). mp_uint_t (*read)(mp_obj_t obj, void *buf, mp_uint_t size, int *errcode); @@ -93,7 +95,7 @@ MP_DECLARE_CONST_FUN_OBJ_VAR_BETWEEN(mp_stream_ioctl_obj); // Object is assumed to have a non-NULL stream protocol with valid r/w/ioctl methods static inline const mp_stream_p_t *mp_get_stream(mp_const_obj_t self) { - return (const mp_stream_p_t*)((const mp_obj_base_t*)MP_OBJ_TO_PTR(self))->type->protocol; + return mp_proto_get(MP_QSTR_protocol_stream, self); } const mp_stream_p_t *mp_get_stream_raise(mp_obj_t self_in, int flags); diff --git a/shared-bindings/_bleio/CharacteristicBuffer.c b/shared-bindings/_bleio/CharacteristicBuffer.c index e7524da2d..fc95d0d50 100644 --- a/shared-bindings/_bleio/CharacteristicBuffer.c +++ b/shared-bindings/_bleio/CharacteristicBuffer.c @@ -230,6 +230,7 @@ STATIC const mp_rom_map_elem_t bleio_characteristic_buffer_locals_dict_table[] = STATIC MP_DEFINE_CONST_DICT(bleio_characteristic_buffer_locals_dict, bleio_characteristic_buffer_locals_dict_table); STATIC const mp_stream_p_t characteristic_buffer_stream_p = { + MP_PROTO_IMPLEMENT(MP_QSTR_protocol_stream) .read = bleio_characteristic_buffer_read, .write = bleio_characteristic_buffer_write, .ioctl = bleio_characteristic_buffer_ioctl, diff --git a/shared-bindings/busio/UART.c b/shared-bindings/busio/UART.c index 7a3b48e89..1fc81e78e 100644 --- a/shared-bindings/busio/UART.c +++ b/shared-bindings/busio/UART.c @@ -398,6 +398,7 @@ STATIC const mp_rom_map_elem_t busio_uart_locals_dict_table[] = { STATIC MP_DEFINE_CONST_DICT(busio_uart_locals_dict, busio_uart_locals_dict_table); STATIC const mp_stream_p_t uart_stream_p = { + MP_PROTO_IMPLEMENT(MP_QSTR_protocol_stream) .read = busio_uart_read, .write = busio_uart_write, .ioctl = busio_uart_ioctl, diff --git a/shared-bindings/socket/__init__.c b/shared-bindings/socket/__init__.c index 6d04a9893..2d6c16e90 100644 --- a/shared-bindings/socket/__init__.c +++ b/shared-bindings/socket/__init__.c @@ -500,6 +500,7 @@ mp_uint_t socket_ioctl(mp_obj_t self_in, mp_uint_t request, uintptr_t arg, int * } STATIC const mp_stream_p_t socket_stream_p = { + MP_PROTO_IMPLEMENT(MP_QSTR_protocol_stream) .ioctl = socket_ioctl, .is_text = false, }; diff --git a/shared-bindings/terminalio/Terminal.c b/shared-bindings/terminalio/Terminal.c index cdde672d3..9c01fba20 100644 --- a/shared-bindings/terminalio/Terminal.c +++ b/shared-bindings/terminalio/Terminal.c @@ -112,6 +112,7 @@ STATIC const mp_rom_map_elem_t terminalio_terminal_locals_dict_table[] = { STATIC MP_DEFINE_CONST_DICT(terminalio_terminal_locals_dict, terminalio_terminal_locals_dict_table); STATIC const mp_stream_p_t terminalio_terminal_stream_p = { + MP_PROTO_IMPLEMENT(MP_QSTR_protocol_stream) .read = NULL, .write = terminalio_terminal_write, .ioctl = terminalio_terminal_ioctl, diff --git a/shared-bindings/usb_midi/PortIn.c b/shared-bindings/usb_midi/PortIn.c index 356a81d52..e2df56e95 100644 --- a/shared-bindings/usb_midi/PortIn.c +++ b/shared-bindings/usb_midi/PortIn.c @@ -107,6 +107,7 @@ STATIC const mp_rom_map_elem_t usb_midi_portin_locals_dict_table[] = { STATIC MP_DEFINE_CONST_DICT(usb_midi_portin_locals_dict, usb_midi_portin_locals_dict_table); STATIC const mp_stream_p_t usb_midi_portin_stream_p = { + MP_PROTO_IMPLEMENT(MP_QSTR_protocol_stream) .read = usb_midi_portin_read, .write = NULL, .ioctl = usb_midi_portin_ioctl, diff --git a/shared-bindings/usb_midi/PortOut.c b/shared-bindings/usb_midi/PortOut.c index 6f4ce6716..e3eddfaf5 100644 --- a/shared-bindings/usb_midi/PortOut.c +++ b/shared-bindings/usb_midi/PortOut.c @@ -89,6 +89,7 @@ STATIC const mp_rom_map_elem_t usb_midi_portout_locals_dict_table[] = { STATIC MP_DEFINE_CONST_DICT(usb_midi_portout_locals_dict, usb_midi_portout_locals_dict_table); STATIC const mp_stream_p_t usb_midi_portout_stream_p = { + MP_PROTO_IMPLEMENT(MP_QSTR_protocol_stream) .read = NULL, .write = usb_midi_portout_write, .ioctl = usb_midi_portout_ioctl, -- cgit v1.2.3 From 603df58f971743bc36b9e391cd5fb04812262533 Mon Sep 17 00:00:00 2001 From: dherrada Date: Mon, 11 May 2020 13:40:02 -0400 Subject: Did stage, socket, storage --- shared-bindings/_stage/Layer.c | 45 +++++------ shared-bindings/_stage/Text.c | 37 ++++----- shared-bindings/_stage/__init__.c | 12 +-- shared-bindings/socket/__init__.c | 156 +++++++++++++++++++------------------ shared-bindings/storage/__init__.c | 138 ++++++++++++++++---------------- 5 files changed, 196 insertions(+), 192 deletions(-) (limited to 'shared-bindings/socket/__init__.c') diff --git a/shared-bindings/_stage/Layer.c b/shared-bindings/_stage/Layer.c index 12028b131..437114cd3 100644 --- a/shared-bindings/_stage/Layer.c +++ b/shared-bindings/_stage/Layer.c @@ -30,25 +30,26 @@ #include "Layer.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: _stage +//| class Layer: +//| """.. currentmodule:: _stage //| -//| :class:`Layer` -- Keep information about a single layer of graphics -//| =================================================================== +//| :class:`Layer` -- Keep information about a single layer of graphics +//| ===================================================================""" //| -//| .. class:: Layer(width, height, graphic, palette, [grid]) +//| def __init__(self, width: int, height: int, graphic: bytearray, palette: bytearray, grid: bytearray): +//| """Keep internal information about a layer of graphics (either a +//| ``Grid`` or a ``Sprite``) in a format suitable for fast rendering +//| with the ``render()`` function. //| -//| Keep internal information about a layer of graphics (either a -//| ``Grid`` or a ``Sprite``) in a format suitable for fast rendering -//| with the ``render()`` function. +//| :param int width: The width of the grid in tiles, or 1 for sprites. +//| :param int height: The height of the grid in tiles, or 1 for sprites. +//| :param bytearray graphic: The graphic data of the tiles. +//| :param bytearray palette: The color palette to be used. +//| :param bytearray grid: The contents of the grid map. //| -//| :param int width: The width of the grid in tiles, or 1 for sprites. -//| :param int height: The height of the grid in tiles, or 1 for sprites. -//| :param bytearray graphic: The graphic data of the tiles. -//| :param bytearray palette: The color palette to be used. -//| :param bytearray grid: The contents of the grid map. -//| -//| This class is intended for internal use in the ``stage`` library and -//| it shouldn't be used on its own. +//| This class is intended for internal use in the ``stage`` library and +//| it shouldn't be used on its own.""" +//| ... //| STATIC mp_obj_t layer_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *args, mp_map_t *kw_args) { @@ -90,9 +91,9 @@ STATIC mp_obj_t layer_make_new(const mp_obj_type_t *type, size_t n_args, return MP_OBJ_FROM_PTR(self); } -//| .. method:: move(x, y) -//| -//| Set the offset of the layer to the specified values. +//| def move(self, x: Any, y: Any) -> Any: +//| """Set the offset of the layer to the specified values.""" +//| ... //| STATIC mp_obj_t layer_move(mp_obj_t self_in, mp_obj_t x_in, mp_obj_t y_in) { layer_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -102,10 +103,10 @@ STATIC mp_obj_t layer_move(mp_obj_t self_in, mp_obj_t x_in, mp_obj_t y_in) { } STATIC MP_DEFINE_CONST_FUN_OBJ_3(layer_move_obj, layer_move); -//| .. method:: frame(frame, rotation) -//| -//| Set the animation frame of the sprite, and optionally rotation its -//| graphic. +//| def frame(self, frame: Any, rotation: Any) -> Any: +//| """Set the animation frame of the sprite, and optionally rotation its +//| graphic.""" +//| ... //| STATIC mp_obj_t layer_frame(mp_obj_t self_in, mp_obj_t frame_in, mp_obj_t rotation_in) { diff --git a/shared-bindings/_stage/Text.c b/shared-bindings/_stage/Text.c index 49c1d00ca..8797f74db 100644 --- a/shared-bindings/_stage/Text.c +++ b/shared-bindings/_stage/Text.c @@ -30,25 +30,26 @@ #include "Text.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: _stage +//| class Text: +//| """.. currentmodule:: _stage //| -//| :class:`Text` -- Keep information about a single text of text -//| ============================================================== +//| :class:`Text` -- Keep information about a single text of text +//| ==============================================================""" //| -//| .. class:: Text(width, height, font, palette, chars) +//| def __init__(self, width: int, height: int, font: bytearray, palette: bytearray, chars: bytearray): +//| """Keep internal information about a text of text +//| in a format suitable for fast rendering +//| with the ``render()`` function. //| -//| Keep internal information about a text of text -//| in a format suitable for fast rendering -//| with the ``render()`` function. +//| :param int width: The width of the grid in tiles, or 1 for sprites. +//| :param int height: The height of the grid in tiles, or 1 for sprites. +//| :param bytearray font: The font data of the characters. +//| :param bytearray palette: The color palette to be used. +//| :param bytearray chars: The contents of the character grid. //| -//| :param int width: The width of the grid in tiles, or 1 for sprites. -//| :param int height: The height of the grid in tiles, or 1 for sprites. -//| :param bytearray font: The font data of the characters. -//| :param bytearray palette: The color palette to be used. -//| :param bytearray chars: The contents of the character grid. -//| -//| This class is intended for internal use in the ``stage`` library and -//| it shouldn't be used on its own. +//| This class is intended for internal use in the ``stage`` library and +//| it shouldn't be used on its own.""" +//| ... //| STATIC mp_obj_t text_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *args, mp_map_t *kw_args) { @@ -84,9 +85,9 @@ STATIC mp_obj_t text_make_new(const mp_obj_type_t *type, size_t n_args, return MP_OBJ_FROM_PTR(self); } -//| .. method:: move(x, y) -//| -//| Set the offset of the text to the specified values. +//| def move(self, x: Any, y: Any) -> Any: +//| """Set the offset of the text to the specified values.""" +//| ... //| STATIC mp_obj_t text_move(mp_obj_t self_in, mp_obj_t x_in, mp_obj_t y_in) { text_obj_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/_stage/__init__.c b/shared-bindings/_stage/__init__.c index 4bac280bf..6b5c4fd8b 100644 --- a/shared-bindings/_stage/__init__.c +++ b/shared-bindings/_stage/__init__.c @@ -34,7 +34,7 @@ #include "Layer.h" #include "Text.h" -//| :mod:`_stage` --- C-level helpers for animation of sprites on a stage +//| """:mod:`_stage` --- C-level helpers for animation of sprites on a stage //| ===================================================================== //| //| .. module:: _stage @@ -49,11 +49,10 @@ //| :maxdepth: 3 //| //| Layer -//| Text +//| Text""" //| -//| .. function:: render(x0, y0, x1, y1, layers, buffer, display[, scale[, background]]) -//| -//| Render and send to the display a fragment of the screen. +//| def render(x0: int, y0: int, x1: int, y1: int, layers: list, buffer: bytearray, display: displayio.Display, scale: int, background: int) -> Any: +//| """Render and send to the display a fragment of the screen. //| //| :param int x0: Left edge of the fragment. //| :param int y0: Top edge of the fragment. @@ -70,7 +69,8 @@ //| valid. //| //| This function is intended for internal use in the ``stage`` library -//| and all the necessary checks are performed there. +//| and all the necessary checks are performed there.""" +//| STATIC mp_obj_t stage_render(size_t n_args, const mp_obj_t *args) { uint16_t x0 = mp_obj_get_int(args[0]); uint16_t y0 = mp_obj_get_int(args[1]); diff --git a/shared-bindings/socket/__init__.c b/shared-bindings/socket/__init__.c index 2d6c16e90..4c0811bdb 100644 --- a/shared-bindings/socket/__init__.c +++ b/shared-bindings/socket/__init__.c @@ -37,27 +37,28 @@ #include "shared-module/network/__init__.h" -//| :mod:`socket` --- TCP, UDP and RAW socket support +//| """:mod:`socket` --- TCP, UDP and RAW socket support //| ================================================= //| //| .. module:: socket //| :synopsis: TCP, UDP and RAW sockets //| :platform: SAMD21, SAMD51 //| -//| Create TCP, UDP and RAW sockets for communicating over the Internet. +//| Create TCP, UDP and RAW sockets for communicating over the Internet.""" //| STATIC const mp_obj_type_t socket_type; -//| .. currentmodule:: socket +//| class socket: +//| """.. currentmodule:: socket""" //| -//| .. class:: socket(family, type, proto) +//| def __init__(self, family: int, type: int, proto: int): +//| """Create a new socket //| -//| Create a new socket -//| -//| :param ~int family: AF_INET or AF_INET6 -//| :param ~int type: SOCK_STREAM, SOCK_DGRAM or SOCK_RAW -//| :param ~int proto: IPPROTO_TCP, IPPROTO_UDP or IPPROTO_RAW (ignored) +//| :param ~int family: AF_INET or AF_INET6 +//| :param ~int type: SOCK_STREAM, SOCK_DGRAM or SOCK_RAW +//| :param ~int proto: IPPROTO_TCP, IPPROTO_UDP or IPPROTO_RAW (ignored)""" +//| ... //| STATIC mp_obj_t socket_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *args, mp_map_t *kw_args) { @@ -98,11 +99,11 @@ STATIC void socket_select_nic(mod_network_socket_obj_t *self, const byte *ip) { } } -//| .. method:: bind(address) -//| -//| Bind a socket to an address +//| def bind(self, address: tuple) -> Any: +//| """Bind a socket to an address //| -//| :param ~tuple address: tuple of (remote_address, remote_port) +//| :param ~tuple address: tuple of (remote_address, remote_port)""" +//| ... //| STATIC mp_obj_t socket_bind(mp_obj_t self_in, mp_obj_t addr_in) { @@ -125,11 +126,11 @@ STATIC mp_obj_t socket_bind(mp_obj_t self_in, mp_obj_t addr_in) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(socket_bind_obj, socket_bind); -//| .. method:: listen(backlog) -//| -//| Set socket to listen for incoming connections +//| def listen(self, backlog: int) -> Any: +//| """Set socket to listen for incoming connections //| -//| :param ~int backlog: length of backlog queue for waiting connetions +//| :param ~int backlog: length of backlog queue for waiting connetions""" +//| ... //| STATIC mp_obj_t socket_listen(mp_obj_t self_in, mp_obj_t backlog) { @@ -150,11 +151,10 @@ STATIC mp_obj_t socket_listen(mp_obj_t self_in, mp_obj_t backlog) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(socket_listen_obj, socket_listen); -//| .. method:: accept() -//| -//| Accept a connection on a listening socket of type SOCK_STREAM, -//| creating a new socket of type SOCK_STREAM. -//| Returns a tuple of (new_socket, remote_address) +//| def accept(self, ) -> Any: +//| """Accept a connection on a listening socket of type SOCK_STREAM, +//| creating a new socket of type SOCK_STREAM. +//| Returns a tuple of (new_socket, remote_address)""" //| STATIC mp_obj_t socket_accept(mp_obj_t self_in) { @@ -188,11 +188,11 @@ STATIC mp_obj_t socket_accept(mp_obj_t self_in) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(socket_accept_obj, socket_accept); -//| .. method:: connect(address) -//| -//| Connect a socket to a remote address +//| def connect(self, address: tuple) -> Any: +//| """Connect a socket to a remote address //| -//| :param ~tuple address: tuple of (remote_address, remote_port) +//| :param ~tuple address: tuple of (remote_address, remote_port)""" +//| ... //| STATIC mp_obj_t socket_connect(mp_obj_t self_in, mp_obj_t addr_in) { @@ -215,12 +215,12 @@ STATIC mp_obj_t socket_connect(mp_obj_t self_in, mp_obj_t addr_in) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(socket_connect_obj, socket_connect); -//| .. method:: send(bytes) -//| -//| Send some bytes to the connected remote address. -//| Suits sockets of type SOCK_STREAM +//| def send(self, bytes: bytes) -> Any: +//| """Send some bytes to the connected remote address. +//| Suits sockets of type SOCK_STREAM //| -//| :param ~bytes bytes: some bytes to send +//| :param ~bytes bytes: some bytes to send""" +//| ... //| STATIC mp_obj_t socket_send(mp_obj_t self_in, mp_obj_t buf_in) { @@ -252,19 +252,20 @@ STATIC mp_int_t _socket_recv_into(mod_network_socket_obj_t *sock, byte *buf, mp_ } -//| .. method:: recv_into(buffer[, bufsize]) +//| def recv_into(self, buffer: bytearray, bufsize: int) -> Any: +//| """Reads some bytes from the connected remote address, writing +//| into the provided buffer. If bufsize <= len(buffer) is given, +//| a maximum of bufsize bytes will be read into the buffer. If no +//| valid value is given for bufsize, the default is the length of +//| the given buffer. //| -//| Reads some bytes from the connected remote address, writing -//| into the provided buffer. If bufsize <= len(buffer) is given, -//| a maximum of bufsize bytes will be read into the buffer. If no -//| valid value is given for bufsize, the default is the length of -//| the given buffer. +//| Suits sockets of type SOCK_STREAM +//| Returns an int of number of bytes read. //| -//| Suits sockets of type SOCK_STREAM -//| Returns an int of number of bytes read. +//| :param bytearray buffer: buffer to receive into +//| :param int bufsize: optionally, a maximum number of bytes to read.""" +//| ... //| -//| :param bytearray buffer: buffer to receive into -//| :param int bufsize: optionally, a maximum number of bytes to read. STATIC mp_obj_t socket_recv_into(size_t n_args, const mp_obj_t *args) { mod_network_socket_obj_t *self = MP_OBJ_TO_PTR(args[0]); @@ -287,13 +288,14 @@ STATIC mp_obj_t socket_recv_into(size_t n_args, const mp_obj_t *args) { } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(socket_recv_into_obj, 2, 3, socket_recv_into); -//| .. method:: recv(bufsize) +//| def recv(self, bufsize: int) -> Any: +//| """Reads some bytes from the connected remote address. +//| Suits sockets of type SOCK_STREAM +//| Returns a bytes() of length <= bufsize //| -//| Reads some bytes from the connected remote address. -//| Suits sockets of type SOCK_STREAM -//| Returns a bytes() of length <= bufsize +//| :param ~int bufsize: maximum number of bytes to receive""" +//| ... //| -//| :param ~int bufsize: maximum number of bytes to receive STATIC mp_obj_t socket_recv(mp_obj_t self_in, mp_obj_t len_in) { mod_network_socket_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -313,13 +315,13 @@ STATIC mp_obj_t socket_recv(mp_obj_t self_in, mp_obj_t len_in) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(socket_recv_obj, socket_recv); -//| .. method:: sendto(bytes, address) +//| def sendto(self, bytes: bytes, address: tuple) -> Any: +//| """Send some bytes to a specific address. +//| Suits sockets of type SOCK_DGRAM //| -//| Send some bytes to a specific address. -//| Suits sockets of type SOCK_DGRAM -//| -//| :param ~bytes bytes: some bytes to send -//| :param ~tuple address: tuple of (remote_address, remote_port) +//| :param ~bytes bytes: some bytes to send +//| :param ~tuple address: tuple of (remote_address, remote_port)""" +//| ... //| STATIC mp_obj_t socket_sendto(mp_obj_t self_in, mp_obj_t data_in, mp_obj_t addr_in) { @@ -347,16 +349,16 @@ STATIC mp_obj_t socket_sendto(mp_obj_t self_in, mp_obj_t data_in, mp_obj_t addr_ } STATIC MP_DEFINE_CONST_FUN_OBJ_3(socket_sendto_obj, socket_sendto); -//| .. method:: recvfrom(bufsize) -//| -//| Reads some bytes from the connected remote address. -//| Suits sockets of type SOCK_STREAM +//| def recvfrom(self, bufsize: int) -> Any: +//| """Reads some bytes from the connected remote address. +//| Suits sockets of type SOCK_STREAM //| -//| Returns a tuple containing -//| * a bytes() of length <= bufsize -//| * a remote_address, which is a tuple of ip address and port number +//| Returns a tuple containing +//| * a bytes() of length <= bufsize +//| * a remote_address, which is a tuple of ip address and port number //| -//| :param ~int bufsize: maximum number of bytes to receive +//| :param ~int bufsize: maximum number of bytes to receive""" +//| ... //| STATIC mp_obj_t socket_recvfrom(mp_obj_t self_in, mp_obj_t len_in) { @@ -386,9 +388,9 @@ STATIC mp_obj_t socket_recvfrom(mp_obj_t self_in, mp_obj_t len_in) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(socket_recvfrom_obj, socket_recvfrom); -//| .. method:: setsockopt(level, optname, value) -//| -//| Sets socket options +//| def setsockopt(self, level: Any, optname: Any, value: Any) -> Any: +//| """Sets socket options""" +//| ... //| STATIC mp_obj_t socket_setsockopt(size_t n_args, const mp_obj_t *args) { @@ -420,11 +422,11 @@ STATIC mp_obj_t socket_setsockopt(size_t n_args, const mp_obj_t *args) { } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(socket_setsockopt_obj, 4, 4, socket_setsockopt); -//| .. method:: settimeout(value) +//| def settimeout(self, value: int) -> Any: +//| """Set the timeout value for this socket. //| -//| Set the timeout value for this socket. -//| -//| :param ~int value: timeout in seconds. 0 means non-blocking. None means block indefinitely. +//| :param ~int value: timeout in seconds. 0 means non-blocking. None means block indefinitely.""" +//| ... //| STATIC mp_obj_t socket_settimeout(mp_obj_t self_in, mp_obj_t timeout_in) { @@ -451,11 +453,11 @@ STATIC mp_obj_t socket_settimeout(mp_obj_t self_in, mp_obj_t timeout_in) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(socket_settimeout_obj, socket_settimeout); -//| .. method:: setblocking(flag) -//| -//| Set the blocking behaviour of this socket. +//| def setblocking(self, flag: bool) -> Any: +//| """Set the blocking behaviour of this socket. //| -//| :param ~bool flag: False means non-blocking, True means block indefinitely. +//| :param ~bool flag: False means non-blocking, True means block indefinitely.""" +//| ... //| // method socket.setblocking(flag) @@ -513,13 +515,13 @@ STATIC const mp_obj_type_t socket_type = { .locals_dict = (mp_obj_dict_t*)&socket_locals_dict, }; -//| .. function:: getaddrinfo(host, port) -//| -//| Gets the address information for a hostname and port +//| def getaddrinfo(host: Any, port: Any) -> Any: +//| """Gets the address information for a hostname and port //| -//| Returns the appropriate family, socket type, socket protocol and -//| address information to call socket.socket() and socket.connect() with, -//| as a tuple. +//| Returns the appropriate family, socket type, socket protocol and +//| address information to call socket.socket() and socket.connect() with, +//| as a tuple.""" +//| ... //| STATIC mp_obj_t socket_getaddrinfo(mp_obj_t host_in, mp_obj_t port_in) { diff --git a/shared-bindings/storage/__init__.c b/shared-bindings/storage/__init__.c index ba439b951..feb1a9bd7 100644 --- a/shared-bindings/storage/__init__.c +++ b/shared-bindings/storage/__init__.c @@ -35,7 +35,7 @@ #include "shared-bindings/storage/__init__.h" #include "supervisor/shared/translate.h" -//| :mod:`storage` --- storage management +//| """:mod:`storage` --- storage management //| ======================================================== //| //| .. module:: storage @@ -45,16 +45,16 @@ //| The `storage` provides storage management functionality such as mounting and //| unmounting which is typically handled by the operating system hosting Python. //| CircuitPython does not have an OS, so this module provides this functionality -//| directly. +//| directly.""" //| -//| .. function:: mount(filesystem, mount_path, *, readonly=False) +//| def mount(filesystem: Any, mount_path: Any, *, readonly: bool = False) -> Any: +//| """Mounts the given filesystem object at the given path. //| -//| Mounts the given filesystem object at the given path. +//| This is the CircuitPython analog to the UNIX ``mount`` command. //| -//| This is the CircuitPython analog to the UNIX ``mount`` command. -//| -//| :param bool readonly: True when the filesystem should be readonly to CircuitPython. +//| :param bool readonly: True when the filesystem should be readonly to CircuitPython.""" +//| ... //| mp_obj_t storage_mount(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_readonly }; @@ -85,12 +85,12 @@ mp_obj_t storage_mount(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_arg } MP_DEFINE_CONST_FUN_OBJ_KW(storage_mount_obj, 2, storage_mount); -//| .. function:: umount(mount) -//| -//| Unmounts the given filesystem object or if *mount* is a path, then unmount -//| the filesystem mounted at that location. +//| def umount(mount: Any) -> Any: +//| """Unmounts the given filesystem object or if *mount* is a path, then unmount +//| the filesystem mounted at that location. //| -//| This is the CircuitPython analog to the UNIX ``umount`` command. +//| This is the CircuitPython analog to the UNIX ``umount`` command.""" +//| ... //| mp_obj_t storage_umount(mp_obj_t mnt_in) { if (MP_OBJ_IS_STR(mnt_in)) { @@ -103,15 +103,15 @@ mp_obj_t storage_umount(mp_obj_t mnt_in) { } MP_DEFINE_CONST_FUN_OBJ_1(storage_umount_obj, storage_umount); -//| .. function:: remount(mount_path, readonly=False, *, disable_concurrent_write_protection=False) +//| def remount(mount_path: Any, readonly: bool = False, *, disable_concurrent_write_protection: bool = False) -> Any: +//| """Remounts the given path with new parameters. //| -//| Remounts the given path with new parameters. -//| -//| :param bool readonly: True when the filesystem should be readonly to CircuitPython. -//| :param bool disable_concurrent_write_protection: When True, the check that makes sure the -//| underlying filesystem data is written by one computer is disabled. Disabling the protection -//| allows CircuitPython and a host to write to the same filesystem with the risk that the -//| filesystem will be corrupted. +//| :param bool readonly: True when the filesystem should be readonly to CircuitPython. +//| :param bool disable_concurrent_write_protection: When True, the check that makes sure the +//| underlying filesystem data is written by one computer is disabled. Disabling the protection +//| allows CircuitPython and a host to write to the same filesystem with the risk that the +//| filesystem will be corrupted.""" +//| ... //| mp_obj_t storage_remount(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_readonly, ARG_disable_concurrent_write_protection }; @@ -133,28 +133,29 @@ mp_obj_t storage_remount(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_a } MP_DEFINE_CONST_FUN_OBJ_KW(storage_remount_obj, 1, storage_remount); -//| .. function:: getmount(mount_path) -//| -//| Retrieves the mount object associated with the mount path +//| def getmount(mount_path: Any) -> Any: +//| """Retrieves the mount object associated with the mount path""" +//| ... //| mp_obj_t storage_getmount(const mp_obj_t mnt_in) { return common_hal_storage_getmount(mp_obj_str_get_str(mnt_in)); } MP_DEFINE_CONST_FUN_OBJ_1(storage_getmount_obj, storage_getmount); -//| .. function:: erase_filesystem() +//| def erase_filesystem() -> Any: +//| """Erase and re-create the ``CIRCUITPY`` filesystem. //| -//| Erase and re-create the ``CIRCUITPY`` filesystem. +//| On boards that present USB-visible ``CIRCUITPY`` drive (e.g., SAMD21 and SAMD51), +//| then call `microcontroller.reset()` to restart CircuitPython and have the +//| host computer remount CIRCUITPY. //| -//| On boards that present USB-visible ``CIRCUITPY`` drive (e.g., SAMD21 and SAMD51), -//| then call `microcontroller.reset()` to restart CircuitPython and have the -//| host computer remount CIRCUITPY. +//| This function can be called from the REPL when ``CIRCUITPY`` +//| has become corrupted. //| -//| This function can be called from the REPL when ``CIRCUITPY`` -//| has become corrupted. +//| .. warning:: All the data on ``CIRCUITPY`` will be lost, and +//| CircuitPython will restart on certain boards.""" +//| ... //| -//| .. warning:: All the data on ``CIRCUITPY`` will be lost, and -//| CircuitPython will restart on certain boards. mp_obj_t storage_erase_filesystem(void) { common_hal_storage_erase_filesystem(); @@ -171,54 +172,53 @@ STATIC const mp_rom_map_elem_t storage_module_globals_table[] = { { MP_ROM_QSTR(MP_QSTR_getmount), MP_ROM_PTR(&storage_getmount_obj) }, { MP_ROM_QSTR(MP_QSTR_erase_filesystem), MP_ROM_PTR(&storage_erase_filesystem_obj) }, - //| .. class:: VfsFat(block_device) - //| - //| Create a new VfsFat filesystem around the given block device. - //| - //| :param block_device: Block device the the filesystem lives on - //| - //| .. attribute:: label - //| - //| The filesystem label, up to 11 case-insensitive bytes. Note that - //| this property can only be set when the device is writable by the - //| microcontroller. - //| - //| .. method:: mkfs() - //| - //| Format the block device, deleting any data that may have been there - //| - //| .. method:: open(path, mode) - //| - //| Like builtin ``open()`` - //| - //| .. method:: ilistdir([path]) - //| - //| Return an iterator whose values describe files and folders within - //| ``path`` - //| - //| .. method:: mkdir(path) + //| class VfsFat: + //| def __init__(self, block_device: Any): ... + //| """Create a new VfsFat filesystem around the given block device. //| - //| Like `os.mkdir` + //| :param block_device: Block device the the filesystem lives on""" //| - //| .. method:: rmdir(path) + //| label: Any = ... + //| """The filesystem label, up to 11 case-insensitive bytes. Note that + //| this property can only be set when the device is writable by the + //| microcontroller.""" //| - //| Like `os.rmdir` + //| def mkfs(self, ) -> Any: + //| """Format the block device, deleting any data that may have been there""" + //| ... //| - //| .. method:: stat(path) + //| def open(self, path: Any, mode: Any) -> Any: + //| """Like builtin ``open()``""" + //| ... //| - //| Like `os.stat` + //| def ilistdir(self, path: Any) -> Any: + //| """Return an iterator whose values describe files and folders within + //| ``path``""" + //| ... //| - //| .. method:: statvfs(path) + //| def mkdir(self, path: Any) -> Any: + //| """Like `os.mkdir`""" + //| ... //| - //| Like `os.statvfs` + //| def rmdir(self, path: Any) -> Any: + //| """Like `os.rmdir`""" + //| ... //| - //| .. method:: mount(readonly, mkfs) + //| def stat(self, path: Any) -> Any: + //| """Like `os.stat`""" + //| ... //| - //| Don't call this directly, call `storage.mount`. + //| def statvfs(self, path: Any) -> Any: + //| """Like `os.statvfs`""" + //| ... //| - //| .. method:: umount() + //| def mount(self, readonly: Any, mkfs: Any) -> Any: + //| """Don't call this directly, call `storage.mount`.""" + //| ... //| - //| Don't call this directly, call `storage.umount`. + //| def umount(self, ) -> Any: + //| """Don't call this directly, call `storage.umount`.""" + //| ... //| { MP_ROM_QSTR(MP_QSTR_VfsFat), MP_ROM_PTR(&mp_fat_vfs_type) }, }; -- cgit v1.2.3 From 4e8de3c554024d3ac89e9ee77b958a6932a64bec Mon Sep 17 00:00:00 2001 From: Scott Shawcroft Date: Tue, 12 May 2020 17:15:28 -0700 Subject: Swap sphinx to autoapi and the inline stubs --- .github/workflows/build.yml | 2 +- .gitignore | 2 + Makefile | 6 +- conf.py | 14 +- docs/c2rst.py | 31 -- ports/atmel-samd/README.rst | 2 +- ports/atmel-samd/bindings/samd/Clock.c | 36 +- ports/atmel-samd/bindings/samd/__init__.c | 19 +- setup.py | 8 +- shared-bindings/_bleio/Adapter.c | 5 +- shared-bindings/_bleio/Address.c | 9 +- shared-bindings/_bleio/Attribute.c | 6 +- shared-bindings/_bleio/Characteristic.c | 9 +- shared-bindings/_bleio/CharacteristicBuffer.c | 7 +- shared-bindings/_bleio/Connection.c | 14 +- shared-bindings/_bleio/Descriptor.c | 6 +- shared-bindings/_bleio/PacketBuffer.c | 26 +- shared-bindings/_bleio/ScanEntry.c | 9 +- shared-bindings/_bleio/ScanResults.c | 7 +- shared-bindings/_bleio/Service.c | 7 +- shared-bindings/_bleio/UUID.c | 9 +- shared-bindings/_bleio/__init__.c | 26 +- shared-bindings/_eve/__init__.c | 22 +- shared-bindings/_pew/PewPew.c | 7 +- shared-bindings/_pew/__init__.c | 12 +- shared-bindings/_pixelbuf/PixelBuf.c | 7 +- shared-bindings/_pixelbuf/__init__.c | 27 +- shared-bindings/_stage/Layer.c | 5 +- shared-bindings/_stage/Text.c | 7 +- shared-bindings/_stage/__init__.c | 16 +- shared-bindings/aesio/__init__.c | 17 +- shared-bindings/aesio/aes.c | 64 ++- shared-bindings/analogio/AnalogIn.c | 5 +- shared-bindings/analogio/AnalogOut.c | 7 +- shared-bindings/analogio/__init__.c | 15 +- shared-bindings/audiobusio/I2SOut.c | 7 +- shared-bindings/audiobusio/PDMIn.c | 7 +- shared-bindings/audiobusio/__init__.c | 15 +- shared-bindings/audiocore/RawSample.c | 13 +- shared-bindings/audiocore/WaveFile.c | 5 +- shared-bindings/audiocore/__init__.c | 17 +- shared-bindings/audioio/AudioOut.c | 7 +- shared-bindings/audioio/__init__.c | 14 +- shared-bindings/audiomixer/Mixer.c | 7 +- shared-bindings/audiomixer/MixerVoice.c | 5 +- shared-bindings/audiomixer/__init__.c | 16 +- shared-bindings/audiomp3/MP3Decoder.c | 7 +- shared-bindings/audiomp3/__init__.c | 15 +- shared-bindings/audiopwmio/PWMAudioOut.c | 7 +- shared-bindings/audiopwmio/__init__.c | 14 +- shared-bindings/bitbangio/I2C.c | 5 +- shared-bindings/bitbangio/OneWire.c | 5 +- shared-bindings/bitbangio/SPI.c | 5 +- shared-bindings/bitbangio/__init__.c | 16 +- shared-bindings/board/__init__.c | 6 +- shared-bindings/busio/I2C.c | 5 +- shared-bindings/busio/OneWire.c | 5 +- shared-bindings/busio/SPI.c | 7 +- shared-bindings/busio/UART.c | 5 +- shared-bindings/busio/__init__.c | 17 +- shared-bindings/digitalio/DigitalInOut.c | 5 +- shared-bindings/digitalio/Direction.c | 5 +- shared-bindings/digitalio/DriveMode.c | 5 +- shared-bindings/digitalio/Pull.c | 5 +- shared-bindings/digitalio/__init__.c | 17 +- shared-bindings/displayio/Bitmap.c | 7 +- shared-bindings/displayio/ColorConverter.c | 7 +- shared-bindings/displayio/Display.c | 5 +- shared-bindings/displayio/EPaperDisplay.c | 5 +- shared-bindings/displayio/FourWire.c | 7 +- shared-bindings/displayio/Group.c | 7 +- shared-bindings/displayio/I2CDisplay.c | 7 +- shared-bindings/displayio/OnDiskBitmap.c | 7 +- shared-bindings/displayio/Palette.c | 7 +- shared-bindings/displayio/ParallelBus.c | 7 +- shared-bindings/displayio/Shape.c | 7 +- shared-bindings/displayio/TileGrid.c | 5 +- shared-bindings/displayio/__init__.c | 27 +- shared-bindings/fontio/BuiltinFont.c | 7 +- shared-bindings/fontio/Glyph.c | 31 +- shared-bindings/fontio/__init__.c | 17 +- shared-bindings/framebufferio/FramebufferDisplay.c | 5 +- shared-bindings/framebufferio/__init__.c | 16 +- shared-bindings/frequencyio/FrequencyIn.c | 5 +- shared-bindings/frequencyio/__init__.c | 17 +- shared-bindings/gamepad/GamePad.c | 7 +- shared-bindings/gamepad/__init__.c | 12 +- shared-bindings/gamepadshift/GamePadShift.c | 5 +- shared-bindings/gamepadshift/__init__.c | 12 +- shared-bindings/help.c | 34 -- shared-bindings/help.rst | 31 ++ shared-bindings/i2cslave/I2CSlave.c | 36 +- shared-bindings/i2cslave/__init__.c | 14 +- shared-bindings/index.rst | 10 +- shared-bindings/math/__init__.c | 7 +- shared-bindings/microcontroller/Pin.c | 7 +- shared-bindings/microcontroller/Processor.c | 11 +- shared-bindings/microcontroller/RunMode.c | 5 +- shared-bindings/microcontroller/__init__.c | 20 +- shared-bindings/multiterminal/__init__.c | 7 +- shared-bindings/neopixel_write/__init__.c | 13 +- shared-bindings/network/__init__.c | 7 +- shared-bindings/nvm/ByteArray.c | 8 +- shared-bindings/nvm/__init__.c | 17 +- shared-bindings/os/__init__.c | 7 +- shared-bindings/ps2io/Ps2.c | 5 +- shared-bindings/ps2io/__init__.c | 14 +- shared-bindings/pulseio/PWMOut.c | 7 +- shared-bindings/pulseio/PulseIn.c | 12 +- shared-bindings/pulseio/PulseOut.c | 13 +- shared-bindings/pulseio/__init__.c | 16 +- shared-bindings/random/__init__.c | 7 +- shared-bindings/rgbmatrix/RGBMatrix.c | 14 +- shared-bindings/rgbmatrix/__init__.c | 11 +- shared-bindings/rotaryio/IncrementalEncoder.c | 7 +- shared-bindings/rotaryio/__init__.c | 18 +- shared-bindings/rtc/RTC.c | 13 +- shared-bindings/rtc/__init__.c | 16 +- shared-bindings/socket/__init__.c | 8 +- shared-bindings/storage/__init__.c | 7 +- shared-bindings/struct/__init__.c | 9 +- shared-bindings/supervisor/Runtime.c | 11 +- shared-bindings/supervisor/__init__.c | 30 +- shared-bindings/terminalio/Terminal.c | 5 +- shared-bindings/terminalio/__init__.c | 16 +- shared-bindings/time/__init__.c | 7 +- shared-bindings/touchio/TouchIn.c | 5 +- shared-bindings/touchio/__init__.c | 14 +- shared-bindings/uheap/__init__.c | 6 +- shared-bindings/ulab/__init__.pyi | 523 +++++++++++++++++++++ shared-bindings/ulab/__init__.rst | 523 --------------------- shared-bindings/usb_hid/Device.c | 5 +- shared-bindings/usb_hid/__init__.c | 15 +- shared-bindings/usb_midi/PortIn.c | 7 +- shared-bindings/usb_midi/PortOut.c | 5 +- shared-bindings/usb_midi/__init__.c | 17 +- shared-bindings/ustack/__init__.c | 10 +- shared-bindings/wiznet/__init__.c | 16 +- shared-bindings/wiznet/wiznet5k.c | 5 +- tools/extract_pyi.py | 12 +- 140 files changed, 860 insertions(+), 1762 deletions(-) delete mode 100644 docs/c2rst.py delete mode 100644 shared-bindings/help.c create mode 100644 shared-bindings/help.rst create mode 100644 shared-bindings/ulab/__init__.pyi delete mode 100644 shared-bindings/ulab/__init__.rst (limited to 'shared-bindings/socket/__init__.c') diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 3dda76db4..057395eee 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -34,7 +34,7 @@ jobs: run: | sudo apt-get install -y eatmydata sudo eatmydata apt-get install -y gettext librsvg2-bin mingw-w64 - pip install requests sh click setuptools cpp-coveralls "Sphinx<4" sphinx-rtd-theme recommonmark sphinxcontrib-svg2pdfconverter polib pyyaml + pip install requests sh click setuptools cpp-coveralls "Sphinx<4" sphinx-rtd-theme recommonmark sphinx-autoapi sphinxcontrib-svg2pdfconverter polib pyyaml - name: Versions run: | gcc --version diff --git a/.gitignore b/.gitignore index 435ed73a7..403fcc299 100644 --- a/.gitignore +++ b/.gitignore @@ -14,6 +14,7 @@ ############ dist/ *.egg-info +.eggs # Logs and Databases ###################### @@ -51,6 +52,7 @@ _build # Generated rst files ###################### genrst/ +autoapi/ # ctags and similar ################### diff --git a/Makefile b/Makefile index aa8fc26d1..1971076a3 100644 --- a/Makefile +++ b/Makefile @@ -69,7 +69,7 @@ clean: rm -rf $(BUILDDIR)/* rm -rf $(STUBDIR) $(DISTDIR) *.egg-info -html: +html: stubs $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." @@ -213,8 +213,10 @@ check-translate: locale/circuitpython.pot $(wildcard locale/*.po) $(PYTHON) tools/check_translations.py $^ stubs: + mkdir -p circuitpython-stubs python tools/extract_pyi.py shared-bindings/ $(STUBDIR) - #python setup.py sdist + python tools/extract_pyi.py ports/atmel-samd/bindings $(STUBDIR) + python setup.py sdist update-frozen-libraries: @echo "Updating all frozen libraries to latest tagged version." diff --git a/conf.py b/conf.py index 2e503737c..aea84dd21 100644 --- a/conf.py +++ b/conf.py @@ -55,7 +55,6 @@ extensions = [ 'sphinx.ext.todo', 'sphinx.ext.coverage', 'rstjinja', - 'c2rst', 'recommonmark', ] @@ -66,9 +65,17 @@ templates_path = ['templates'] source_suffix = { '.rst': 'restructuredtext', '.md': 'markdown', - '.c': '' } +extensions.append('autoapi.extension') + +autoapi_type = 'python' +# Uncomment this if debugging autoapi +# autoapi_keep_files = True +autoapi_dirs = ['circuitpython-stubs'] +autoapi_add_toctree_entry = False +autoapi_options = ['members', 'undoc-members', 'private-members', 'show-inheritance', 'special-members', 'show-module-summary'] +autoapi_template_dir = 'docs/autoapi/templates' # The encoding of source files. #source_encoding = 'utf-8-sig' @@ -78,7 +85,7 @@ source_suffix = { # General information about the project. project = 'Adafruit CircuitPython' -copyright = '2014-2018, MicroPython & CircuitPython contributors (https://github.com/adafruit/circuitpython/graphs/contributors)' +copyright = '2014-2020, MicroPython & CircuitPython contributors (https://github.com/adafruit/circuitpython/graphs/contributors)' # These are overwritten on ReadTheDocs. # The version info for the project you're documenting, acts as replacement for @@ -105,6 +112,7 @@ exclude_patterns = ["**/build*", ".git", ".venv", ".direnv", + "docs/autoapi", "docs/README.md", "drivers", "examples", diff --git a/docs/c2rst.py b/docs/c2rst.py deleted file mode 100644 index 76489dca3..000000000 --- a/docs/c2rst.py +++ /dev/null @@ -1,31 +0,0 @@ -def c2rst(app, docname, source): - """ Pre-parse '.c' & '.h' files that contain rST source. - """ - # Make sure we're outputting HTML - if app.builder.format != 'html': - return - - fname = app.env.doc2path(docname) - if (not fname.endswith(".c") and - not fname.endswith(".h")): - #print("skipping:", fname) - return - - src = source[0] - - stripped = [] - for line in src.split("\n"): - line = line.strip() - if line == "//|": - stripped.append("") - elif line.startswith("//| "): - stripped.append(line[len("//| "):]) - stripped = "\r\n".join(stripped) - - rendered = app.builder.templates.render_string( - stripped, app.config.html_context - ) - source[0] = rendered - -def setup(app): - app.connect("source-read", c2rst) diff --git a/ports/atmel-samd/README.rst b/ports/atmel-samd/README.rst index 721177275..a6881902e 100644 --- a/ports/atmel-samd/README.rst +++ b/ports/atmel-samd/README.rst @@ -21,4 +21,4 @@ Port Specific modules --------------------- .. toctree:: - bindings/samd/__init__ + ../../autoapi/samd/index diff --git a/ports/atmel-samd/bindings/samd/Clock.c b/ports/atmel-samd/bindings/samd/Clock.c index b88bb82e2..24e425e8c 100644 --- a/ports/atmel-samd/bindings/samd/Clock.c +++ b/ports/atmel-samd/bindings/samd/Clock.c @@ -30,18 +30,12 @@ #include "py/objproperty.h" #include "py/runtime.h" -//| .. currentmodule:: samd +//| import typing +//| class Clock: +//| """Identifies a clock on the microcontroller. //| -//| :class:`Clock` --- Clock reference -//| ------------------------------------------ -//| -//| Identifies a clock on the microcontroller. -//| -//| .. class:: Clock -//| -//| Identifies a clock on the microcontroller. They are fixed by the -//| hardware so they cannot be constructed on demand. Instead, use -//| `samd.clock` to reference the desired clock. +//| They are fixed by the hardware so they cannot be constructed on demand. Instead, use +//| ``samd.clock`` to reference the desired clock.""" //| STATIC void samd_clock_print(const mp_print_t *print, mp_obj_t self_in, mp_print_kind_t kind) { @@ -50,9 +44,8 @@ STATIC void samd_clock_print(const mp_print_t *print, mp_obj_t self_in, mp_print mp_printf(print, "%q.%q.%q", MP_QSTR_samd, MP_QSTR_clock, self->name); } -//| .. attribute:: enabled -//| -//| Is the clock enabled? (read-only) +//| enabled: bool = ... +//| """Is the clock enabled? (read-only)""" //| STATIC mp_obj_t samd_clock_get_enabled(mp_obj_t self_in) { samd_clock_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -69,9 +62,8 @@ const mp_obj_property_t samd_clock_enabled_obj = { }, }; -//| .. attribute:: parent -//| -//| Clock parent. (read-only) +//| parent: typing.Union(Clock | None) = ... +//| """Clock parent. (read-only)""" //| STATIC mp_obj_t samd_clock_get_parent(mp_obj_t self_in) { samd_clock_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -98,9 +90,8 @@ const mp_obj_property_t samd_clock_parent_obj = { }, }; -//| .. attribute:: frequency -//| -//| Clock frequency. (read-only) +//| frequency: int = ... +//| """Clock frequency in Herz. (read-only)""" //| STATIC mp_obj_t samd_clock_get_frequency(mp_obj_t self_in) { samd_clock_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -117,9 +108,8 @@ const mp_obj_property_t samd_clock_frequency_obj = { }, }; -//| .. attribute:: calibration -//| -//| Clock calibration. Not all clocks can be calibrated. +//| calibration: int = ... +//| """Clock calibration. Not all clocks can be calibrated.""" //| STATIC mp_obj_t samd_clock_get_calibration(mp_obj_t self_in) { samd_clock_obj_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/ports/atmel-samd/bindings/samd/__init__.c b/ports/atmel-samd/bindings/samd/__init__.c index 55a10001d..6e9b68ccc 100644 --- a/ports/atmel-samd/bindings/samd/__init__.c +++ b/ports/atmel-samd/bindings/samd/__init__.c @@ -30,29 +30,16 @@ #include "bindings/samd/Clock.h" -//| :mod:`samd` --- SAMD implementation settings -//| ================================================= -//| -//| .. module:: samd -//| :synopsis: SAMD implementation settings -//| :platform: SAMD21 -//| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| Clock -//| +//| """SAMD implementation settings""" -//| :mod:`samd.clock` --- samd clock names +//| """:mod:`samd.clock` --- samd clock names //| -------------------------------------------------------- //| //| .. module:: samd.clock //| :synopsis: samd clock names //| :platform: SAMD21 //| -//| References to clocks as named by the microcontroller +//| References to clocks as named by the microcontroller""" //| const mp_obj_module_t samd_clock_module = { .base = { &mp_type_module }, diff --git a/setup.py b/setup.py index 1e0d81da3..37afb6f1b 100644 --- a/setup.py +++ b/setup.py @@ -5,18 +5,16 @@ from pathlib import Path stub_root = Path("circuitpython-stubs") stubs = [p.relative_to(stub_root).as_posix() for p in stub_root.glob("*.pyi")] -now = datetime.utcnow() -version = now.strftime("%Y.%m.%d") - setup( name="circuitpython-stubs", description="PEP 561 type stubs for CircuitPython", url="https://github.com/adafruit/circuitpython", maintainer="CircuitPythonistas", author_email="circuitpython@adafruit.com", - version=version, + use_scm_version=True, license="MIT", package_data={"circuitpython-stubs": stubs}, packages=["circuitpython-stubs"], - setup_requires=["setuptools>=38.6.0"], + setup_requires=["setuptools>=38.6.0", + "setuptools_scm"], ) diff --git a/shared-bindings/_bleio/Adapter.c b/shared-bindings/_bleio/Adapter.c index 6fb5c323d..4816294f7 100644 --- a/shared-bindings/_bleio/Adapter.c +++ b/shared-bindings/_bleio/Adapter.c @@ -48,10 +48,7 @@ #define WINDOW_DEFAULT (0.1f) //| class Adapter: -//| """.. currentmodule:: _bleio -//| -//| :class:`Adapter` --- BLE adapter -//| ---------------------------------------------------- +//| """BLE adapter //| //| The Adapter manages the discovery and connection to other nearby Bluetooth Low Energy devices. //| This part of the Bluetooth Low Energy Specification is known as Generic Access Profile (GAP). diff --git a/shared-bindings/_bleio/Address.c b/shared-bindings/_bleio/Address.c index 2071bd3b2..ccbab1b9d 100644 --- a/shared-bindings/_bleio/Address.c +++ b/shared-bindings/_bleio/Address.c @@ -35,12 +35,7 @@ #include "shared-module/_bleio/Address.h" //| class Address: -//| """.. currentmodule:: _bleio -//| -//| :class:`Address` -- BLE address -//| ========================================================= -//| -//| Encapsulates the address of a BLE device.""" +//| """Encapsulates the address of a BLE device.""" //| //| def __init__(self, address: buf, address_type: Any): @@ -97,7 +92,7 @@ STATIC mp_obj_t bleio_address_make_new(const mp_obj_type_t *type, size_t n_args, //| >>> _bleio.adapter.address //|
//| >>> _bleio.adapter.address.address_bytes -//| b'5\xa8\xed\xf5\x1d\xc8'""" +//| b'5\\xa8\\xed\\xf5\\x1d\\xc8'""" //| STATIC mp_obj_t bleio_address_get_address_bytes(mp_obj_t self_in) { bleio_address_obj_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/_bleio/Attribute.c b/shared-bindings/_bleio/Attribute.c index 72fd13d1c..6c47c87ba 100644 --- a/shared-bindings/_bleio/Attribute.c +++ b/shared-bindings/_bleio/Attribute.c @@ -30,12 +30,8 @@ #include "shared-bindings/_bleio/UUID.h" //| class Attribute: -//| """.. currentmodule:: _bleio +//| """Definitions associated with all BLE attributes: characteristics, descriptors, etc. //| -//| :class:`Attribute` -- BLE Attribute -//| ========================================================= -//| -//| Definitions associated with all BLE attributes: characteristics, descriptors, etc. //| :py:class:`~_bleio.Attribute` is, notionally, a superclass of //| :py:class:`~Characteristic` and :py:class:`~Descriptor`, //| but is not defined as a Python superclass of those classes.""" diff --git a/shared-bindings/_bleio/Characteristic.c b/shared-bindings/_bleio/Characteristic.c index f8f18d0bd..785b677d6 100644 --- a/shared-bindings/_bleio/Characteristic.c +++ b/shared-bindings/_bleio/Characteristic.c @@ -34,13 +34,8 @@ #include "shared-bindings/_bleio/UUID.h" //| class Characteristic: -//| """.. currentmodule:: _bleio -//| -//| :class:`Characteristic` -- BLE service characteristic -//| ========================================================= -//| -//| Stores information about a BLE service characteristic and allows reading -//| and writing of the characteristic's value.""" +//| """Stores information about a BLE service characteristic and allows reading +//| and writing of the characteristic's value.""" //| //| def __init__(self, ): //| """There is no regular constructor for a Characteristic. A new local Characteristic can be created diff --git a/shared-bindings/_bleio/CharacteristicBuffer.c b/shared-bindings/_bleio/CharacteristicBuffer.c index f38f650d9..6cbd587c6 100644 --- a/shared-bindings/_bleio/CharacteristicBuffer.c +++ b/shared-bindings/_bleio/CharacteristicBuffer.c @@ -42,12 +42,7 @@ STATIC void raise_error_if_not_connected(bleio_characteristic_buffer_obj_t *self } //| class CharacteristicBuffer: -//| """.. currentmodule:: _bleio -//| -//| :class:`CharacteristicBuffer` -- BLE Service incoming values buffer. -//| ===================================================================== -//| -//| Accumulates a Characteristic's incoming values in a FIFO buffer.""" +//| """Accumulates a Characteristic's incoming values in a FIFO buffer.""" //| //| def __init__(self, characteristic: Characteristic, *, timeout: int = 1, buffer_size: int = 64): //| diff --git a/shared-bindings/_bleio/Connection.c b/shared-bindings/_bleio/Connection.c index 93600e76d..0a96d8a11 100644 --- a/shared-bindings/_bleio/Connection.c +++ b/shared-bindings/_bleio/Connection.c @@ -43,12 +43,7 @@ #include "shared-bindings/_bleio/Service.h" //| class Connection: -//| """.. currentmodule:: _bleio -//| -//| :class:`Connection` -- A BLE connection -//| ========================================================= -//| -//| A BLE connection to another device. Used to discover and interact with services on the other +//| """A BLE connection to another device. Used to discover and interact with services on the other //| device. //| //| Usage:: @@ -211,15 +206,14 @@ STATIC mp_obj_t bleio_connection_get_connection_interval(mp_obj_t self_in) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(bleio_connection_get_connection_interval_obj, bleio_connection_get_connection_interval); -//| .. attribute:: max_packet_length -//| -//| The maximum number of data bytes that can be sent in a single transmission, +//| attribute: Any = ... +//| """The maximum number of data bytes that can be sent in a single transmission, //| not including overhead bytes. //| //| This is the maximum number of bytes that can be sent in a notification, //| which must be sent in a single packet. //| But for a regular characteristic read or write, may be sent in multiple packets, -//| so this limit does not apply. +//| so this limit does not apply.""" //| STATIC mp_obj_t bleio_connection_get_max_packet_length(mp_obj_t self_in) { bleio_connection_obj_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/_bleio/Descriptor.c b/shared-bindings/_bleio/Descriptor.c index 00b3bacf5..9d7020849 100644 --- a/shared-bindings/_bleio/Descriptor.c +++ b/shared-bindings/_bleio/Descriptor.c @@ -34,12 +34,8 @@ #include "shared-bindings/_bleio/UUID.h" //| class Descriptor: -//| """.. currentmodule:: _bleio +//| """Stores information about a BLE descriptor. //| -//| :class:`Descriptor` -- BLE descriptor -//| ========================================================= -//| -//| Stores information about a BLE descriptor. //| Descriptors are attached to BLE characteristics and provide contextual //| information about the characteristic.""" //| diff --git a/shared-bindings/_bleio/PacketBuffer.c b/shared-bindings/_bleio/PacketBuffer.c index 80beadb15..907bfabd2 100644 --- a/shared-bindings/_bleio/PacketBuffer.c +++ b/shared-bindings/_bleio/PacketBuffer.c @@ -36,12 +36,7 @@ #include "shared-bindings/util.h" //| class PacketBuffer: -//| """.. currentmodule:: _bleio -//| -//| :class:`PacketBuffer` -- Packet-oriented characteristic usage. -//| ===================================================================== -//| -//| Accumulates a Characteristic's incoming packets in a FIFO buffer and facilitates packet aware +//| """Accumulates a Characteristic's incoming packets in a FIFO buffer and facilitates packet aware //| outgoing writes. A packet's size is either the characteristic length or the maximum transmission //| unit (MTU) minus overhead, whichever is smaller. The MTU can change so check `incoming_packet_length` //| and `outgoing_packet_length` before creating a buffer to store data. @@ -60,7 +55,7 @@ //| It may be a local Characteristic provided by a Peripheral Service, or a remote Characteristic //| in a remote Service that a Central has connected to. //| :param int buffer_size: Size of ring buffer (in packets of the Characteristic's maximum -//| length) that stores incoming packets coming from the peer. +//| length) that stores incoming packets coming from the peer.""" //| ... //| STATIC mp_obj_t bleio_packet_buffer_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { @@ -126,11 +121,11 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_2(bleio_packet_buffer_readinto_obj, bleio_packet_ //| """Writes all bytes from data into the same outgoing packet. The bytes from header are included //| before data when the pending packet is currently empty. //| -//| This does not block until the data is sent. It only blocks until the data is pending.""" -//| ... +//| This does not block until the data is sent. It only blocks until the data is pending. //| -//| :return: number of bytes written. May include header bytes when packet is empty. -//| :rtype: int +//| :return: number of bytes written. May include header bytes when packet is empty. +//| :rtype: int""" +//| ... //| // TODO: Add a kwarg `merge=False` to dictate whether subsequent writes are merged into a pending // one. @@ -174,7 +169,7 @@ STATIC mp_obj_t bleio_packet_buffer_write(mp_uint_t n_args, const mp_obj_t *pos_ } STATIC MP_DEFINE_CONST_FUN_OBJ_KW(bleio_packet_buffer_write_obj, 1, bleio_packet_buffer_write); -//| def deinit(self, ) -> Any: +//| def deinit(self) -> Any: //| """Disable permanently.""" //| ... STATIC mp_obj_t bleio_packet_buffer_deinit(mp_obj_t self_in) { @@ -184,7 +179,7 @@ STATIC mp_obj_t bleio_packet_buffer_deinit(mp_obj_t self_in) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(bleio_packet_buffer_deinit_obj, bleio_packet_buffer_deinit); -//| packet_size: Any = ... +//| packet_size: int = ... //| """`packet_size` is the same as `incoming_packet_length`. //| The name `packet_size` is deprecated and //| will be removed in CircuitPython 6.0.0.""" @@ -210,9 +205,8 @@ const mp_obj_property_t bleio_packet_buffer_incoming_packet_length_obj = { (mp_obj_t)&mp_const_none_obj }, }; -//| .. attribute:: outgoing_packet_length -//| -//| Maximum length in bytes of a packet we are writing. +//| outgoing_packet_length: int = ... +//| """Maximum length in bytes of a packet we are writing.""" //| STATIC mp_obj_t bleio_packet_buffer_get_outgoing_packet_length(mp_obj_t self_in) { bleio_packet_buffer_obj_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/_bleio/ScanEntry.c b/shared-bindings/_bleio/ScanEntry.c index a92b247be..905bea81d 100644 --- a/shared-bindings/_bleio/ScanEntry.c +++ b/shared-bindings/_bleio/ScanEntry.c @@ -36,12 +36,7 @@ #include "shared-module/_bleio/ScanEntry.h" //| class ScanEntry: -//| """.. currentmodule:: _bleio -//| -//| :class:`ScanEntry` -- BLE scan data -//| ========================================================= -//| -//| Encapsulates information about a device that was received during scanning. It can be +//| """Encapsulates information about a device that was received during scanning. It can be //| advertisement or scan response data. This object may only be created by a `_bleio.ScanResults`: //| it has no user-visible constructor.""" //| @@ -68,7 +63,7 @@ STATIC mp_obj_t bleio_scanentry_matches(mp_uint_t n_args, const mp_obj_t *pos_ar mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)]; mp_arg_parse_all(n_args - 1, pos_args + 1, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args); - + mp_buffer_info_t bufinfo; mp_get_buffer_raise(args[ARG_prefixes].u_obj, &bufinfo, MP_BUFFER_READ); return mp_obj_new_bool(common_hal_bleio_scanentry_matches(self, bufinfo.buf, bufinfo.len, args[ARG_all].u_bool)); diff --git a/shared-bindings/_bleio/ScanResults.c b/shared-bindings/_bleio/ScanResults.c index 4b274fc68..6077dcbda 100644 --- a/shared-bindings/_bleio/ScanResults.c +++ b/shared-bindings/_bleio/ScanResults.c @@ -33,12 +33,7 @@ #include "shared-bindings/_bleio/ScanResults.h" //| class ScanResults: -//| """.. currentmodule:: _bleio -//| -//| :class:`ScanResults` -- An Iterator over BLE scanning results -//| =============================================================== -//| -//| Iterates over advertising data received while scanning. This object is always created +//| """Iterates over advertising data received while scanning. This object is always created //| by a `_bleio.Adapter`: it has no user-visible constructor.""" //| STATIC mp_obj_t scanresults_iternext(mp_obj_t self_in) { diff --git a/shared-bindings/_bleio/Service.c b/shared-bindings/_bleio/Service.c index 3526ce189..5ca7504f2 100644 --- a/shared-bindings/_bleio/Service.c +++ b/shared-bindings/_bleio/Service.c @@ -33,12 +33,7 @@ #include "shared-bindings/_bleio/UUID.h" //| class Service: -//| """.. currentmodule:: _bleio -//| -//| :class:`Service` -- BLE GATT Service -//| ========================================================= -//| -//| Stores information about a BLE service and its characteristics.""" +//| """Stores information about a BLE service and its characteristics.""" //| //| def __init__(self, uuid: UUID, *, secondary: bool = False): //| """Create a new Service identified by the specified UUID. It can be accessed by all diff --git a/shared-bindings/_bleio/UUID.c b/shared-bindings/_bleio/UUID.c index d4b0f84ca..78161b956 100644 --- a/shared-bindings/_bleio/UUID.c +++ b/shared-bindings/_bleio/UUID.c @@ -34,12 +34,7 @@ #include "shared-bindings/_bleio/UUID.h" //| class UUID: -//| """.. currentmodule:: _bleio -//| -//| :class:`UUID` -- BLE UUID -//| ========================================================= -//| -//| A 16-bit or 128-bit UUID. Can be used for services, characteristics, descriptors and more.""" +//| """A 16-bit or 128-bit UUID. Can be used for services, characteristics, descriptors and more.""" //| //| def __init__(self, value: Any): //| """Create a new UUID or UUID object encapsulating the uuid value. @@ -207,7 +202,7 @@ STATIC mp_obj_t bleio_uuid_pack_into(mp_uint_t n_args, const mp_obj_t *pos_args, mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)]; mp_arg_parse_all(n_args - 1, pos_args + 1, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args); - + mp_buffer_info_t bufinfo; mp_get_buffer_raise(args[ARG_buffer].u_obj, &bufinfo, MP_BUFFER_WRITE); diff --git a/shared-bindings/_bleio/__init__.c b/shared-bindings/_bleio/__init__.c index da7bfdd81..90b185f79 100644 --- a/shared-bindings/_bleio/__init__.c +++ b/shared-bindings/_bleio/__init__.c @@ -41,13 +41,7 @@ #include "shared-bindings/_bleio/Service.h" #include "shared-bindings/_bleio/UUID.h" -//| """:mod:`_bleio` --- Bluetooth Low Energy (BLE) communication -//| ================================================================ -//| -//| .. module:: _bleio -//| :synopsis: Bluetooth Low Energy functionality -//| :platform: nRF -//| +//| """ //| The `_bleio` module provides necessary low-level functionality for communicating //| using Bluetooth Low Energy (BLE). The '_' prefix indicates this module is meant //| for internal use by libraries but not by the end user. Its API may change incompatibly @@ -58,24 +52,6 @@ //| provides higher-level convenience functionality, including predefined beacons, clients, //| servers. //| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| Address -//| Adapter -//| Attribute -//| Characteristic -//| CharacteristicBuffer -//| Connection -//| Descriptor -//| PacketBuffer -//| ScanEntry -//| ScanResults -//| Service -//| UUID -//| //| .. attribute:: adapter //| //| BLE Adapter used to manage device discovery and connections. diff --git a/shared-bindings/_eve/__init__.c b/shared-bindings/_eve/__init__.c index 0e78cea16..4fa48f2c7 100644 --- a/shared-bindings/_eve/__init__.c +++ b/shared-bindings/_eve/__init__.c @@ -34,28 +34,10 @@ #include "shared-module/_eve/__init__.h" #include "shared-bindings/_eve/__init__.h" - - - - - - - - - - - - - -//| """:mod:`_eve` --- low-level BridgeTek EVE bindings -//| ================================================ -//| -//| .. module:: _eve -//| :synopsis: low-level BridgeTek EVE bindings -//| :platform: SAMD21/SAMD51 +//| """Low-level BridgeTek EVE bindings //| //| The `_eve` module provides a class _EVE which -//| contains methods for constructing EVE command +//| contains methods for constructing EVE command //| buffers and appending basic graphics commands.""" //| diff --git a/shared-bindings/_pew/PewPew.c b/shared-bindings/_pew/PewPew.c index 37188d2b7..82bf04a61 100644 --- a/shared-bindings/_pew/PewPew.c +++ b/shared-bindings/_pew/PewPew.c @@ -35,12 +35,7 @@ #include "supervisor/shared/translate.h" //| class PewPew: -//| """.. currentmodule:: _pew -//| -//| :class:`PewPew` -- LED matrix and button driver -//| =============================================== -//| -//| This is an internal module to be used by the ``pew.py`` library from +//| """This is an internal module to be used by the ``pew.py`` library from //| https://github.com/pewpew-game/pew-pewpew-standalone-10.x to handle the //| LED matrix display and buttons on the ``pewpew10`` board. //| diff --git a/shared-bindings/_pew/__init__.c b/shared-bindings/_pew/__init__.c index b6aab6726..6e0070d8e 100644 --- a/shared-bindings/_pew/__init__.c +++ b/shared-bindings/_pew/__init__.c @@ -41,17 +41,7 @@ STATIC mp_obj_t get_pressed(void) { STATIC MP_DEFINE_CONST_FUN_OBJ_0(get_pressed_obj, get_pressed); -//| """:mod:`_pew` --- LED matrix driver -//| ================================== -//| -//| .. module:: _pew -//| :synopsis: LED matrix driver -//| :platform: SAMD21 -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| PewPew""" +//| """LED matrix driver""" //| STATIC const mp_rom_map_elem_t pew_module_globals_table[] = { { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR__pew) }, diff --git a/shared-bindings/_pixelbuf/PixelBuf.c b/shared-bindings/_pixelbuf/PixelBuf.c index 2d1f4fff2..71a91d707 100644 --- a/shared-bindings/_pixelbuf/PixelBuf.c +++ b/shared-bindings/_pixelbuf/PixelBuf.c @@ -45,12 +45,7 @@ extern const int32_t colorwheel(float pos); static void parse_byteorder(mp_obj_t byteorder_obj, pixelbuf_byteorder_details_t* parsed); //| class PixelBuf: -//| """.. currentmodule:: _pixelbuf -//| -//| :class:`PixelBuf` -- A fast RGB[W] pixel buffer for LED and similar devices -//| =========================================================================== -//| -//| :class:`~_pixelbuf.PixelBuf` implements an RGB[W] bytearray abstraction.""" +//| """A fast RGB[W] pixel buffer for LED and similar devices.""" //| //| def __init__(self, size: int, *, byteorder: str = "BGR", brightness: float = 0, auto_write: bool = False, header: bytes = b"", trailer: bytes = b""): //| """Create a PixelBuf object of the specified size, byteorder, and bits per pixel. diff --git a/shared-bindings/_pixelbuf/__init__.c b/shared-bindings/_pixelbuf/__init__.c index 30656f1c7..bfd479fde 100644 --- a/shared-bindings/_pixelbuf/__init__.c +++ b/shared-bindings/_pixelbuf/__init__.c @@ -33,35 +33,22 @@ #include "shared-bindings/_pixelbuf/PixelBuf.h" -//| """:mod:`_pixelbuf` --- Fast RGB(W) pixel buffer and helpers -//| =========================================================== - -//| .. module:: _pixelbuf -//| :synopsis: A fast RGB(W) pixel buffer library for like NeoPixel and DotStar. +//| """A fast RGB(W) pixel buffer library for like NeoPixel and DotStar. //| //| The `_pixelbuf` module provides the :py:class:`PixelBuf` class to accelerate //| RGB(W) strip/matrix manipulation, such as DotStar and Neopixel. //| -//| Byteorders are configured with strings, such as "RGB" or "RGBD". -//| TODO: Pull in docs from pypixelbuf. +//| Byteorders are configured with strings, such as "RGB" or "RGBD".""" +// TODO: Pull in docs from pypixelbuf. -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| PixelBuf""" - -//| def colorwheel(n: Any) -> Any: ... -//| - -//| def wheel(n: Any) -> Any: +//| def colorwheel(n: int) -> Any: //| """C implementation of the common wheel() function found in many examples. //| Returns the colorwheel RGB value as an integer value for n (usable in :py:class:`PixelBuf`, neopixel, and dotstar).""" //| ... //| -//| .. function:: wheel(n) -//| Use of wheel() is deprecated. Please use colorwheel(). +//| def wheel(n: Any) -> Any: +//| """Use of wheel() is deprecated. Please use colorwheel().""" +//| STATIC mp_obj_t pixelbuf_colorwheel(mp_obj_t n) { return MP_OBJ_NEW_SMALL_INT(colorwheel(MP_OBJ_IS_SMALL_INT(n) ? MP_OBJ_SMALL_INT_VALUE(n) : mp_obj_float_get(n))); diff --git a/shared-bindings/_stage/Layer.c b/shared-bindings/_stage/Layer.c index 437114cd3..0f8260e53 100644 --- a/shared-bindings/_stage/Layer.c +++ b/shared-bindings/_stage/Layer.c @@ -31,10 +31,7 @@ #include "supervisor/shared/translate.h" //| class Layer: -//| """.. currentmodule:: _stage -//| -//| :class:`Layer` -- Keep information about a single layer of graphics -//| ===================================================================""" +//| """Keep information about a single layer of graphics""" //| //| def __init__(self, width: int, height: int, graphic: bytearray, palette: bytearray, grid: bytearray): //| """Keep internal information about a layer of graphics (either a diff --git a/shared-bindings/_stage/Text.c b/shared-bindings/_stage/Text.c index 8797f74db..b0ff1525c 100644 --- a/shared-bindings/_stage/Text.c +++ b/shared-bindings/_stage/Text.c @@ -31,13 +31,10 @@ #include "supervisor/shared/translate.h" //| class Text: -//| """.. currentmodule:: _stage -//| -//| :class:`Text` -- Keep information about a single text of text -//| ==============================================================""" +//| """Keep information about a single grid of text""" //| //| def __init__(self, width: int, height: int, font: bytearray, palette: bytearray, chars: bytearray): -//| """Keep internal information about a text of text +//| """Keep internal information about a grid of text //| in a format suitable for fast rendering //| with the ``render()`` function. //| diff --git a/shared-bindings/_stage/__init__.c b/shared-bindings/_stage/__init__.c index 6b5c4fd8b..6a5638185 100644 --- a/shared-bindings/_stage/__init__.c +++ b/shared-bindings/_stage/__init__.c @@ -34,22 +34,10 @@ #include "Layer.h" #include "Text.h" -//| """:mod:`_stage` --- C-level helpers for animation of sprites on a stage -//| ===================================================================== -//| -//| .. module:: _stage -//| :synopsis: C-level helpers for animation of sprites on a stage -//| :platform: SAMD21 +//| """C-level helpers for animation of sprites on a stage //| //| The `_stage` module contains native code to speed-up the ```stage`` Library -//| `_. -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| Layer -//| Text""" +//| `_.""" //| //| def render(x0: int, y0: int, x1: int, y1: int, layers: list, buffer: bytearray, display: displayio.Display, scale: int, background: int) -> Any: //| """Render and send to the display a fragment of the screen. diff --git a/shared-bindings/aesio/__init__.c b/shared-bindings/aesio/__init__.c index 43dc73e8b..fa2a2c426 100644 --- a/shared-bindings/aesio/__init__.c +++ b/shared-bindings/aesio/__init__.c @@ -31,23 +31,10 @@ #include "__init__.h" -//| :mod:`aesio` --- AES encryption routines -//| ======================================== -//| -//| .. module:: aesio -//| :synopsis: Embedded implementation of AES +//| """AES encryption routines //| //| The `AES` module contains classes used to implement encryption -//| and decryption. It aims to be low overhead in terms of memory. -//| -//| - -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| aes +//| and decryption. It aims to be low overhead in terms of memory.""" STATIC const mp_obj_tuple_t mp_aes_key_size_obj = { diff --git a/shared-bindings/aesio/aes.c b/shared-bindings/aesio/aes.c index 4ddcfa898..7a559b0bb 100644 --- a/shared-bindings/aesio/aes.c +++ b/shared-bindings/aesio/aes.c @@ -9,35 +9,31 @@ // Defined at the end of this file -//| .. currentmodule:: aesio +//| class AES: +//| """Encrypt and decrypt AES streams""" //| -//| :class:`aesio` -- Encrypt and decrypt AES streams -//| ===================================================== +//| def __init__(self, key, mode=0, iv=None, segment_size=8) -> Any: +//| """Create a new AES state with the given key. //| -//| An object that represents an AES stream, including the current state. +//| :param bytearray key: A 16-, 24-, or 32-byte key +//| :param int mode: AES mode to use. One of: AES.MODE_ECB, AES.MODE_CBC, or +//| AES.MODE_CTR +//| :param bytearray iv: Initialization vector to use for CBC or CTR mode //| -//| .. class:: AES(key, mode=0, iv=None, segment_size=8) +//| Additional arguments are supported for legacy reasons. //| -//| Create a new AES state with the given key. +//| Encrypting a string:: //| -//| :param bytearray key: A 16-, 24-, or 32-byte key -//| :param int mode: AES mode to use. One of: AES.MODE_ECB, AES.MODE_CBC, or -//| AES.MODE_CTR -//| :param bytearray iv: Initialization vector to use for CBC or CTR mode +//| import aesio +//| from binascii import hexlify //| -//| Additional arguments are supported for legacy reasons. -//| -//| Encrypting a string:: -//| -//| import aesio -//| from binascii import hexlify -//| -//| key = b'Sixteen byte key' -//| inp = b'Circuit Python!!' # Note: 16-bytes long -//| outp = bytearray(len(inp)) -//| cipher = aesio.AES(key, aesio.mode.MODE_ECB) -//| cipher.encrypt_into(inp, outp) -//| hexlify(outp) +//| key = b'Sixteen byte key' +//| inp = b'Circuit Python!!' # Note: 16-bytes long +//| outp = bytearray(len(inp)) +//| cipher = aesio.AES(key, aesio.mode.MODE_ECB) +//| cipher.encrypt_into(inp, outp) +//| hexlify(outp)""" +//| ... //| STATIC mp_obj_t aesio_aes_make_new(const mp_obj_type_t *type, size_t n_args, @@ -154,12 +150,13 @@ STATIC void validate_length(aesio_aes_obj_t *self, size_t src_length, } } -//| .. method:: encrypt_into(src, dest) +//| def encrypt_into(src, dest) -> None: +//| """Encrypt the buffer from ``src`` into ``dest``. //| -//| Encrypt the buffer from ``src`` into ``dest``. -//| For ECB mode, the buffers must be 16 bytes long. For CBC mode, the -//| buffers must be a multiple of 16 bytes, and must be equal length. For -//| CTX mode, there are no restrictions. +//| For ECB mode, the buffers must be 16 bytes long. For CBC mode, the +//| buffers must be a multiple of 16 bytes, and must be equal length. For +//| CTX mode, there are no restrictions.""" +//| ... //| STATIC mp_obj_t aesio_aes_encrypt_into(mp_obj_t aesio_obj, mp_obj_t src, mp_obj_t dest) { @@ -184,12 +181,13 @@ STATIC mp_obj_t aesio_aes_encrypt_into(mp_obj_t aesio_obj, mp_obj_t src, STATIC MP_DEFINE_CONST_FUN_OBJ_3(aesio_aes_encrypt_into_obj, aesio_aes_encrypt_into); -//| .. method:: decrypt_into(src, dest) +//| def decrypt_into(src, dest) -> None: //| -//| Decrypt the buffer from ``src`` into ``dest``. -//| For ECB mode, the buffers must be 16 bytes long. For CBC mode, the -//| buffers must be a multiple of 16 bytes, and must be equal length. For -//| CTX mode, there are no restrictions. +//| """Decrypt the buffer from ``src`` into ``dest``. +//| For ECB mode, the buffers must be 16 bytes long. For CBC mode, the +//| buffers must be a multiple of 16 bytes, and must be equal length. For +//| CTX mode, there are no restrictions.""" +//| ... //| STATIC mp_obj_t aesio_aes_decrypt_into(mp_obj_t aesio_obj, mp_obj_t src, mp_obj_t dest) { diff --git a/shared-bindings/analogio/AnalogIn.c b/shared-bindings/analogio/AnalogIn.c index 2fb5051eb..bafa287ff 100644 --- a/shared-bindings/analogio/AnalogIn.c +++ b/shared-bindings/analogio/AnalogIn.c @@ -37,10 +37,7 @@ #include "shared-bindings/util.h" //| class AnalogIn: -//| """.. currentmodule:: analogio -//| -//| :class:`AnalogIn` -- read analog voltage -//| ============================================ +//| """Read analog voltage levels //| //| Usage:: //| diff --git a/shared-bindings/analogio/AnalogOut.c b/shared-bindings/analogio/AnalogOut.c index 9064bb5dc..a8edcc0ae 100644 --- a/shared-bindings/analogio/AnalogOut.c +++ b/shared-bindings/analogio/AnalogOut.c @@ -37,12 +37,7 @@ #include "supervisor/shared/translate.h" //| class AnalogOut: -//| """.. currentmodule:: analogio -//| -//| :class:`AnalogOut` -- output analog voltage -//| ============================================ -//| -//| The AnalogOut is used to output analog values (a specific voltage). +//| """Output analog values (a specific voltage). //| //| Example usage:: //| diff --git a/shared-bindings/analogio/__init__.c b/shared-bindings/analogio/__init__.c index 79627f16a..1f059f340 100644 --- a/shared-bindings/analogio/__init__.c +++ b/shared-bindings/analogio/__init__.c @@ -34,25 +34,12 @@ #include "shared-bindings/analogio/AnalogIn.h" #include "shared-bindings/analogio/AnalogOut.h" -//| """:mod:`analogio` --- Analog hardware support -//| ================================================= -//| -//| .. module:: analogio -//| :synopsis: Analog hardware support -//| :platform: SAMD21, ESP8266 +//| """Analog hardware support //| //| The `analogio` module contains classes to provide access to analog IO //| typically implemented with digital-to-analog (DAC) and analog-to-digital //| (ADC) converters. //| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| AnalogIn -//| AnalogOut -//| //| All classes change hardware state and should be deinitialized when they //| are no longer needed if the program continues after use. To do so, either //| call :py:meth:`!deinit` or use a context manager. See diff --git a/shared-bindings/audiobusio/I2SOut.c b/shared-bindings/audiobusio/I2SOut.c index 724a65a34..d965aac89 100644 --- a/shared-bindings/audiobusio/I2SOut.c +++ b/shared-bindings/audiobusio/I2SOut.c @@ -36,12 +36,7 @@ #include "supervisor/shared/translate.h" //| class I2SOut: -//| """.. currentmodule:: audiobusio -//| -//| :class:`I2SOut` -- Output an I2S audio signal -//| ======================================================== -//| -//| I2S is used to output an audio signal on an I2S bus.""" +//| """Output an I2S audio signal""" //| //| def __init__(self, bit_clock: microcontroller.Pin, word_select: microcontroller.Pin, data: microcontroller.Pin, *, left_justified: bool): //| """Create a I2SOut object associated with the given pins. diff --git a/shared-bindings/audiobusio/PDMIn.c b/shared-bindings/audiobusio/PDMIn.c index 6cc834724..5b950297b 100644 --- a/shared-bindings/audiobusio/PDMIn.c +++ b/shared-bindings/audiobusio/PDMIn.c @@ -37,12 +37,7 @@ #include "supervisor/shared/translate.h" //| class PDMIn: -//| """.. currentmodule:: audiobusio -//| -//| :class:`PDMIn` -- Record an input PDM audio stream -//| ======================================================== -//| -//| PDMIn can be used to record an input audio signal on a given set of pins.""" +//| """Record an input PDM audio stream""" //| //| def __init__(self, clock_pin: microcontroller.Pin, data_pin: microcontroller.Pin, *, sample_rate: int = 16000, bit_depth: int = 8, mono: bool = True, oversample: int = 64, startup_delay: float = 0.11): //| """Create a PDMIn object associated with the given pins. This allows you to diff --git a/shared-bindings/audiobusio/__init__.c b/shared-bindings/audiobusio/__init__.c index c5c387361..89ccbb88b 100644 --- a/shared-bindings/audiobusio/__init__.c +++ b/shared-bindings/audiobusio/__init__.c @@ -34,26 +34,13 @@ #include "shared-bindings/audiobusio/I2SOut.h" #include "shared-bindings/audiobusio/PDMIn.h" -//| """:mod:`audiobusio` --- Support for audio input and output over digital bus -//| ========================================================================= -//| -//| .. module:: audiobusio -//| :synopsis: Support for audio input and output over digital bus -//| :platform: SAMD21 +//| """Support for audio input and output over digital buses //| //| The `audiobusio` module contains classes to provide access to audio IO //| over digital buses. These protocols are used to communicate audio to other //| chips in the same circuit. It doesn't include audio interconnect protocols //| such as S/PDIF. //| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| I2SOut -//| PDMIn -//| //| All libraries change hardware state and should be deinitialized when they //| are no longer needed. To do so, either call :py:meth:`!deinit` or use a //| context manager.""" diff --git a/shared-bindings/audiocore/RawSample.c b/shared-bindings/audiocore/RawSample.c index 6091fbfc0..c0f9325e6 100644 --- a/shared-bindings/audiocore/RawSample.c +++ b/shared-bindings/audiocore/RawSample.c @@ -35,19 +35,8 @@ #include "shared-bindings/audiocore/RawSample.h" #include "supervisor/shared/translate.h" - - - - - - //| class RawSample: -//| """.. currentmodule:: audiocore -//| -//| :class:`RawSample` -- A raw audio sample buffer -//| ======================================================== -//| -//| An in-memory sound sample""" +//| """A raw audio sample buffer in memory""" //| //| def __init__(self, buffer: array.array, *, channel_count: int = 1, sample_rate: int = 8000): //| """Create a RawSample based on the given buffer of signed values. If channel_count is more than diff --git a/shared-bindings/audiocore/WaveFile.c b/shared-bindings/audiocore/WaveFile.c index 65b42fb6c..a067f6cda 100644 --- a/shared-bindings/audiocore/WaveFile.c +++ b/shared-bindings/audiocore/WaveFile.c @@ -34,10 +34,7 @@ #include "supervisor/shared/translate.h" //| class WaveFile: -//| """.. currentmodule:: audiocore -//| -//| :class:`WaveFile` -- Load a wave file for audio playback -//| ======================================================== +//| """Load a wave file for audio playback //| //| A .wav file prepped for audio playback. Only mono and stereo files are supported. Samples must //| be 8 bit unsigned or 16 bit signed. If a buffer is provided, it will be used instead of allocating diff --git a/shared-bindings/audiocore/__init__.c b/shared-bindings/audiocore/__init__.c index 38f91d8ee..b400b9454 100644 --- a/shared-bindings/audiocore/__init__.c +++ b/shared-bindings/audiocore/__init__.c @@ -35,22 +35,7 @@ #include "shared-bindings/audiocore/WaveFile.h" //#include "shared-bindings/audiomixer/Mixer.h" -//| """:mod:`audiocore` --- Support for audio samples and mixer -//| ======================================================== -//| -//| .. module:: audiocore -//| :synopsis: Support for audio samples and mixer -//| :platform: SAMD21 -//| -//| The `audiocore` module contains core classes for audio IO -//| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| RawSample -//| WaveFile""" +//| """Support for audio samples""" //| STATIC const mp_rom_map_elem_t audiocore_module_globals_table[] = { diff --git a/shared-bindings/audioio/AudioOut.c b/shared-bindings/audioio/AudioOut.c index 84e5e4422..574868202 100644 --- a/shared-bindings/audioio/AudioOut.c +++ b/shared-bindings/audioio/AudioOut.c @@ -37,12 +37,7 @@ #include "supervisor/shared/translate.h" //| class AudioOut: -//| """.. currentmodule:: audioio -//| -//| :class:`AudioOut` -- Output an analog audio signal -//| ======================================================== -//| -//| AudioOut can be used to output an analog audio signal on a given pin.""" +//| """Output an analog audio signal""" //| //| def __init__(self, left_channel: microcontroller.Pin, *, right_channel: microcontroller.Pin = None, quiescent_value: int = 0x8000): //| """Create a AudioOut object associated with the given pin(s). This allows you to diff --git a/shared-bindings/audioio/__init__.c b/shared-bindings/audioio/__init__.c index bc2e26cfc..7ec927834 100644 --- a/shared-bindings/audioio/__init__.c +++ b/shared-bindings/audioio/__init__.c @@ -42,22 +42,10 @@ #include "shared-bindings/audiomixer/Mixer.h" #endif -//| """:mod:`audioio` --- Support for audio input and output -//| ====================================================== -//| -//| .. module:: audioio -//| :synopsis: Support for audio input and output -//| :platform: SAMD21 +//| """Support for audio output //| //| The `audioio` module contains classes to provide access to audio IO. //| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| AudioOut -//| //| All classes change hardware state and should be deinitialized when they //| are no longer needed if the program continues after use. To do so, either //| call :py:meth:`!deinit` or use a context manager. See diff --git a/shared-bindings/audiomixer/Mixer.c b/shared-bindings/audiomixer/Mixer.c index 966581d45..31e62cdae 100644 --- a/shared-bindings/audiomixer/Mixer.c +++ b/shared-bindings/audiomixer/Mixer.c @@ -39,12 +39,7 @@ #include "supervisor/shared/translate.h" //| class Mixer: -//| """.. currentmodule:: audiomixer -//| -//| :class:`Mixer` -- Mixes one or more audio samples together -//| =========================================================== -//| -//| Mixer mixes multiple samples into one sample.""" +//| """Mixes one or more audio samples together into one sample.""" //| //| def __init__(self, voice_count: int = 2, buffer_size: int = 1024, channel_count: int = 2, bits_per_sample: int = 16, samples_signed: bool = True, sample_rate: int = 8000): //| """Create a Mixer object that can mix multiple channels with the same sample rate. diff --git a/shared-bindings/audiomixer/MixerVoice.c b/shared-bindings/audiomixer/MixerVoice.c index 257d9507b..ec5768d2f 100644 --- a/shared-bindings/audiomixer/MixerVoice.c +++ b/shared-bindings/audiomixer/MixerVoice.c @@ -38,10 +38,7 @@ #include "supervisor/shared/translate.h" //| class MixerVoice: -//| """.. currentmodule:: audiomixer -//| -//| :class:`MixerVoice` -- Voice objects used with Mixer -//| ===================================================== +//| """Voice objects used with Mixer //| //| Used to access and control samples with `audiomixer.Mixer`.""" //| diff --git a/shared-bindings/audiomixer/__init__.c b/shared-bindings/audiomixer/__init__.c index c90a4a0e6..1146bb798 100644 --- a/shared-bindings/audiomixer/__init__.c +++ b/shared-bindings/audiomixer/__init__.c @@ -32,21 +32,7 @@ #include "shared-bindings/microcontroller/Pin.h" #include "shared-bindings/audiomixer/Mixer.h" -//| """:mod:`audiomixer` --- Support for audio mixer -//| ======================================================== -//| -//| .. module:: audiomixer -//| :synopsis: Support for audio mixer -//| -//| The `audiomixer` module contains core classes for mixing audio sources -//| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| Mixer -//| MixerVoice""" +//| """Support for audio mixing""" //| STATIC const mp_rom_map_elem_t audiomixer_module_globals_table[] = { diff --git a/shared-bindings/audiomp3/MP3Decoder.c b/shared-bindings/audiomp3/MP3Decoder.c index d9c85bbf6..e6d48e32c 100644 --- a/shared-bindings/audiomp3/MP3Decoder.c +++ b/shared-bindings/audiomp3/MP3Decoder.c @@ -35,12 +35,7 @@ #include "supervisor/shared/translate.h" //| class MP3: -//| """.. currentmodule:: audiomp3 -//| -//| :class:`MP3Decoder` -- Load a mp3 file for audio playback -//| ========================================================= -//| -//| An object that decodes MP3 files for playback on an audio device.""" +//| """Load a mp3 file for audio playback""" //| //| def __init__(self, file: typing.BinaryIO, buffer: bytearray): //| diff --git a/shared-bindings/audiomp3/__init__.c b/shared-bindings/audiomp3/__init__.c index 50b29da52..62e5f56cb 100644 --- a/shared-bindings/audiomp3/__init__.c +++ b/shared-bindings/audiomp3/__init__.c @@ -31,20 +31,7 @@ #include "shared-bindings/audiomp3/MP3Decoder.h" -//| """:mod:`audiomp3` --- Support for MP3-compressed audio files -//| ========================================================== -//| -//| .. module:: audiomp3 -//| :synopsis: Support for mp3 files -//| -//| The `audiomp3` module contains an mp3 decoder -//| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| MP3Decoder""" +//| """Support for MP3-compressed audio files""" //| STATIC const mp_rom_map_elem_t audiomp3_module_globals_table[] = { diff --git a/shared-bindings/audiopwmio/PWMAudioOut.c b/shared-bindings/audiopwmio/PWMAudioOut.c index 17f82e3f6..d6b102317 100644 --- a/shared-bindings/audiopwmio/PWMAudioOut.c +++ b/shared-bindings/audiopwmio/PWMAudioOut.c @@ -37,12 +37,7 @@ #include "supervisor/shared/translate.h" //| class PWMAudioOut: -//| """.. currentmodule:: audiopwmio -//| -//| :class:`PWMAudioOut` -- Output an analog audio signal -//| ======================================================== -//| -//| AudioOut can be used to output an analog audio signal on a given pin.""" +//| """Output an analog audio signal by varying the PWM duty cycle.""" //| //| def __init__(self, left_channel: microcontroller.Pin, *, right_channel: microcontroller.Pin = None, quiescent_value: int = 0x8000): //| """Create a PWMAudioOut object associated with the given pin(s). This allows you to diff --git a/shared-bindings/audiopwmio/__init__.c b/shared-bindings/audiopwmio/__init__.c index 74d22b45e..5caea1420 100644 --- a/shared-bindings/audiopwmio/__init__.c +++ b/shared-bindings/audiopwmio/__init__.c @@ -33,22 +33,10 @@ #include "shared-bindings/audiopwmio/__init__.h" #include "shared-bindings/audiopwmio/PWMAudioOut.h" -//| """:mod:`audiopwmio` --- Support for audio input and output -//| ======================================================== -//| -//| .. module:: audiopwmio -//| :synopsis: Support for audio output via digital PWM -//| :platform: NRF52 +//| """Audio output via digital PWM //| //| The `audiopwmio` module contains classes to provide access to audio IO. //| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| PWMAudioOut -//| //| All classes change hardware state and should be deinitialized when they //| are no longer needed if the program continues after use. To do so, either //| call :py:meth:`!deinit` or use a context manager. See diff --git a/shared-bindings/bitbangio/I2C.c b/shared-bindings/bitbangio/I2C.c index a682e050e..2043fc903 100644 --- a/shared-bindings/bitbangio/I2C.c +++ b/shared-bindings/bitbangio/I2C.c @@ -38,10 +38,7 @@ #include "supervisor/shared/translate.h" //| class I2C: -//| """.. currentmodule:: bitbangio -//| -//| :class:`I2C` --- Two wire serial protocol -//| ------------------------------------------""" +//| """Two wire serial protocol""" //| //| def __init__(self, scl: microcontroller.Pin, sda: microcontroller.Pin, *, frequency: int = 400000, timeout: int): //| """I2C is a two-wire protocol for communicating between devices. At the diff --git a/shared-bindings/bitbangio/OneWire.c b/shared-bindings/bitbangio/OneWire.c index 1c9405bd8..a236f4c2a 100644 --- a/shared-bindings/bitbangio/OneWire.c +++ b/shared-bindings/bitbangio/OneWire.c @@ -35,10 +35,7 @@ #include "shared-bindings/util.h" //| class OneWire: -//| """.. currentmodule:: bitbangio -//| -//| :class:`OneWire` -- Lowest-level of the Maxim OneWire protocol -//| =============================================================== +//| """Lowest-level of the Maxim OneWire protocol //| //| :class:`~bitbangio.OneWire` implements the timing-sensitive foundation of //| the Maxim (formerly Dallas Semi) OneWire protocol. diff --git a/shared-bindings/bitbangio/SPI.c b/shared-bindings/bitbangio/SPI.c index 38e0926e8..08bbf1257 100644 --- a/shared-bindings/bitbangio/SPI.c +++ b/shared-bindings/bitbangio/SPI.c @@ -40,10 +40,7 @@ #include "supervisor/shared/translate.h" //| class SPI: -//| """.. currentmodule:: bitbangio -//| -//| :class:`SPI` -- a 3-4 wire serial protocol -//| ----------------------------------------------- +//| """A 3-4 wire serial protocol //| //| SPI is a serial protocol that has exclusive pins for data in and out of the //| master. It is typically faster than :py:class:`~bitbangio.I2C` because a diff --git a/shared-bindings/bitbangio/__init__.c b/shared-bindings/bitbangio/__init__.c index e9600a7e6..e04bdf701 100644 --- a/shared-bindings/bitbangio/__init__.c +++ b/shared-bindings/bitbangio/__init__.c @@ -40,12 +40,7 @@ #include "py/runtime.h" -//| """:mod:`bitbangio` --- Digital protocols implemented by the CPU -//| ============================================================= -//| -//| .. module:: bitbangio -//| :synopsis: Digital protocols implemented by the CPU -//| :platform: SAMD21, ESP8266 +//| """Digital protocols implemented by the CPU //| //| The `bitbangio` module contains classes to provide digital bus protocol //| support regardless of whether the underlying hardware exists to use the @@ -55,15 +50,6 @@ //| hardware to implement the protocols. Native implementations will be faster //| than bitbanged versions and have more capabilities. //| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| I2C -//| OneWire -//| SPI -//| //| All classes change hardware state and should be deinitialized when they //| are no longer needed if the program continues after use. To do so, either //| call :py:meth:`!deinit` or use a context manager. See diff --git a/shared-bindings/board/__init__.c b/shared-bindings/board/__init__.c index 77675e093..010a9fb92 100644 --- a/shared-bindings/board/__init__.c +++ b/shared-bindings/board/__init__.c @@ -29,11 +29,7 @@ #include "shared-bindings/board/__init__.h" -//| """:mod:`board` --- Board specific pin names -//| ======================================================== -//| -//| .. module:: board -//| :synopsis: Board specific pin names +//| """Board specific pin names //| //| Common container for board base pin names. These will vary from board to //| board so don't expect portability when using this module. diff --git a/shared-bindings/busio/I2C.c b/shared-bindings/busio/I2C.c index 8ae3658ee..7e8af765f 100644 --- a/shared-bindings/busio/I2C.c +++ b/shared-bindings/busio/I2C.c @@ -37,10 +37,7 @@ #include "supervisor/shared/translate.h" //| class I2C: -//| """.. currentmodule:: busio -//| -//| :class:`I2C` --- Two wire serial protocol -//| ------------------------------------------""" +//| """Two wire serial protocol""" //| //| def __init__(self, scl: microcontroller.Pin, sda: microcontroller.Pin, *, frequency: int = 400000, timeout: int = 255): //| diff --git a/shared-bindings/busio/OneWire.c b/shared-bindings/busio/OneWire.c index 556e567ef..723cc031a 100644 --- a/shared-bindings/busio/OneWire.c +++ b/shared-bindings/busio/OneWire.c @@ -35,10 +35,7 @@ #include "shared-bindings/util.h" //| class OneWire: -//| """.. currentmodule:: busio -//| -//| :class:`OneWire` -- Lowest-level of the Maxim OneWire protocol -//| =================================================================""" +//| """Lowest-level of the Maxim OneWire protocol""" //| //| def __init__(self, pin: microcontroller.Pin): //| """(formerly Dallas Semi) OneWire protocol. diff --git a/shared-bindings/busio/SPI.c b/shared-bindings/busio/SPI.c index 5b1881702..2ba9a4c22 100644 --- a/shared-bindings/busio/SPI.c +++ b/shared-bindings/busio/SPI.c @@ -42,10 +42,7 @@ //| class SPI: -//| """.. currentmodule:: busio -//| -//| `SPI` -- a 3-4 wire serial protocol -//| ----------------------------------------------- +//| """A 3-4 wire serial protocol //| //| SPI is a serial protocol that has exclusive pins for data in and out of the //| master. It is typically faster than :py:class:`~busio.I2C` because a @@ -147,7 +144,7 @@ STATIC void check_for_deinit(busio_spi_obj_t *self) { //| def configure(self, *, baudrate: int = 100000, polarity: int = 0, phase: int = 0, bits: int = 8) -> Any: //| """Configures the SPI bus. The SPI object must be locked. //| -//| :param int baudrate: the desired clock rate in Hertz. The actual clock rate may be higher or lower +//| :param int baudrate: the desired clock rate in Hertz. The actual clock rate may be higher or lower //| due to the granularity of available clock settings. //| Check the `frequency` attribute for the actual clock rate. //| :param int polarity: the base state of the clock line (0 or 1) diff --git a/shared-bindings/busio/UART.c b/shared-bindings/busio/UART.c index 5984194a9..d4642225c 100644 --- a/shared-bindings/busio/UART.c +++ b/shared-bindings/busio/UART.c @@ -43,10 +43,7 @@ // #define STREAM_DEBUG(...) mp_printf(&mp_plat_print __VA_OPT__(,) __VA_ARGS__) //| class UART: -//| """.. currentmodule:: busio -//| -//| :class:`UART` -- a bidirectional serial protocol -//| =================================================""" +//| """A bidirectional serial protocol""" //| def __init__(self, tx: microcontroller.Pin, rx: microcontroller.Pin, *, baudrate: int = 9600, bits: int = 8, parity: Parity = None, stop: int = 1, timeout: float = 1, receiver_buffer_size: int = 64): //| """A common bidirectional serial protocol that uses an an agreed upon speed //| rather than a shared clock line. diff --git a/shared-bindings/busio/__init__.c b/shared-bindings/busio/__init__.c index 212b3218c..04632c2f4 100644 --- a/shared-bindings/busio/__init__.c +++ b/shared-bindings/busio/__init__.c @@ -38,12 +38,7 @@ #include "py/runtime.h" -//| """:mod:`busio` --- Hardware accelerated behavior -//| ================================================= -//| -//| .. module:: busio -//| :synopsis: Hardware accelerated behavior -//| :platform: SAMD21 +//| """Hardware accelerated external bus access //| //| The `busio` module contains classes to support a variety of serial //| protocols. @@ -54,16 +49,6 @@ //| then a RuntimeError will be raised. Use the `bitbangio` module to explicitly //| bitbang a serial protocol on any general purpose pins. //| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| I2C -//| OneWire -//| SPI -//| UART -//| //| All classes change hardware state and should be deinitialized when they //| are no longer needed if the program continues after use. To do so, either //| call :py:meth:`!deinit` or use a context manager. See diff --git a/shared-bindings/digitalio/DigitalInOut.c b/shared-bindings/digitalio/DigitalInOut.c index 5fffb3f65..54ced099d 100644 --- a/shared-bindings/digitalio/DigitalInOut.c +++ b/shared-bindings/digitalio/DigitalInOut.c @@ -44,10 +44,7 @@ #include "supervisor/shared/translate.h" //| class DigitalInOut: -//| """.. currentmodule:: digitalio -//| -//| :class:`DigitalInOut` -- digital input and output -//| ========================================================= +//| """Digital input and output //| //| A DigitalInOut is used to digitally control I/O pins. For analog control of //| a pin, see the :py:class:`analogio.AnalogIn` and diff --git a/shared-bindings/digitalio/Direction.c b/shared-bindings/digitalio/Direction.c index 0586e95de..dbd0e93e4 100644 --- a/shared-bindings/digitalio/Direction.c +++ b/shared-bindings/digitalio/Direction.c @@ -39,10 +39,7 @@ #include "shared-bindings/digitalio/DigitalInOut.h" //| class Direction: -//| """.. currentmodule:: digitalio -//| -//| :class:`Direction` -- defines the direction of a digital pin -//| =============================================================""" +//| """Defines the direction of a digital pin""" //| //| def __init__(self, ): //| """Enum-like class to define which direction the digital values are diff --git a/shared-bindings/digitalio/DriveMode.c b/shared-bindings/digitalio/DriveMode.c index 23745b046..31b682d38 100644 --- a/shared-bindings/digitalio/DriveMode.c +++ b/shared-bindings/digitalio/DriveMode.c @@ -27,10 +27,7 @@ #include "shared-bindings/digitalio/DriveMode.h" //| class DriveMode: -//| """.. currentmodule:: digitalio -//| -//| :class:`DriveMode` -- defines the drive mode of a digital pin -//| =============================================================""" +//| """Defines the drive mode of a digital pin""" //| //| def __init__(self, ): //| """Enum-like class to define the drive mode used when outputting diff --git a/shared-bindings/digitalio/Pull.c b/shared-bindings/digitalio/Pull.c index 1e64d0788..9aeec1f33 100644 --- a/shared-bindings/digitalio/Pull.c +++ b/shared-bindings/digitalio/Pull.c @@ -27,10 +27,7 @@ #include "shared-bindings/digitalio/Pull.h" //| class Pull: -//| """.. currentmodule:: digitalio -//| -//| :class:`Pull` -- defines the pull of a digital input pin -//| =============================================================""" +//| """Defines the pull of a digital input pin""" //| //| def __init__(self, ): //| """Enum-like class to define the pull value, if any, used while reading diff --git a/shared-bindings/digitalio/__init__.c b/shared-bindings/digitalio/__init__.c index 5a11436a2..f8f45b158 100644 --- a/shared-bindings/digitalio/__init__.c +++ b/shared-bindings/digitalio/__init__.c @@ -38,25 +38,10 @@ #include "py/runtime.h" -//| """:mod:`digitalio` --- Basic digital pin support -//| ================================================= -//| -//| .. module:: digitalio -//| :synopsis: Basic digital pin support -//| :platform: SAMD21, ESP8266 +//| """Basic digital pin support //| //| The `digitalio` module contains classes to provide access to basic digital IO. //| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| DigitalInOut -//| Direction -//| DriveMode -//| Pull -//| //| All classes change hardware state and should be deinitialized when they //| are no longer needed if the program continues after use. To do so, either //| call :py:meth:`!deinit` or use a context manager. See diff --git a/shared-bindings/displayio/Bitmap.c b/shared-bindings/displayio/Bitmap.c index d15c3b107..a52840f2e 100644 --- a/shared-bindings/displayio/Bitmap.c +++ b/shared-bindings/displayio/Bitmap.c @@ -37,12 +37,7 @@ #include "supervisor/shared/translate.h" //| class Bitmap: -//| """.. currentmodule:: displayio -//| -//| :class:`Bitmap` -- Stores values in a 2D array -//| ========================================================================== -//| -//| Stores values of a certain size in a 2D array""" +//| """Stores values of a certain size in a 2D array""" //| //| def __init__(self, width: int, height: int, value_count: int): //| """Create a Bitmap object with the given fixed size. Each pixel stores a value that is used to diff --git a/shared-bindings/displayio/ColorConverter.c b/shared-bindings/displayio/ColorConverter.c index 1d6e5a0cc..505e9f766 100644 --- a/shared-bindings/displayio/ColorConverter.c +++ b/shared-bindings/displayio/ColorConverter.c @@ -37,12 +37,7 @@ #include "supervisor/shared/translate.h" //| class ColorConverter: -//| """.. currentmodule:: displayio -//| -//| :class:`ColorConverter` -- Converts one color format to another -//| ========================================================================================= -//| -//| Converts one color format to another.""" +//| """Converts one color format to another.""" //| //| def __init__(self, *, dither: bool = False): //| """Create a ColorConverter object to convert color formats. Only supports RGB888 to RGB565 diff --git a/shared-bindings/displayio/Display.c b/shared-bindings/displayio/Display.c index 12abec1c8..62ef0f5d0 100644 --- a/shared-bindings/displayio/Display.c +++ b/shared-bindings/displayio/Display.c @@ -40,10 +40,7 @@ #include "supervisor/shared/translate.h" //| class Display: -//| """.. currentmodule:: displayio -//| -//| :class:`Display` -- Manage updating a display over a display bus -//| ========================================================================== +//| """Manage updating a display over a display bus //| //| This initializes a display and connects it into CircuitPython. Unlike other //| objects in CircuitPython, Display objects live until `displayio.release_displays()` diff --git a/shared-bindings/displayio/EPaperDisplay.c b/shared-bindings/displayio/EPaperDisplay.c index 8b03ddc06..8b77e4df3 100644 --- a/shared-bindings/displayio/EPaperDisplay.c +++ b/shared-bindings/displayio/EPaperDisplay.c @@ -40,10 +40,7 @@ #include "supervisor/shared/translate.h" //| class EPaperDisplay: -//| """.. currentmodule:: displayio -//| -//| :class:`EPaperDisplay` -- Manage updating an epaper display over a display bus -//| ============================================================================== +//| """Manage updating an epaper display over a display bus //| //| This initializes an epaper display and connects it into CircuitPython. Unlike other //| objects in CircuitPython, EPaperDisplay objects live until `displayio.release_displays()` diff --git a/shared-bindings/displayio/FourWire.c b/shared-bindings/displayio/FourWire.c index 649045039..5ee4ec5a9 100644 --- a/shared-bindings/displayio/FourWire.c +++ b/shared-bindings/displayio/FourWire.c @@ -39,12 +39,7 @@ #include "supervisor/shared/translate.h" //| class FourWire: -//| """.. currentmodule:: displayio -//| -//| :class:`FourWire` -- Manage updating a display over SPI four wire protocol -//| ========================================================================== -//| -//| Manage updating a display over SPI four wire protocol in the background while Python code runs. +//| """Manage updating a display over SPI four wire protocol in the background while Python code runs. //| It doesn't handle display initialization.""" //| //| def __init__(self, spi_bus: busio.SPI, *, command: microcontroller.Pin, chip_select: microcontroller.Pin, reset: microcontroller.Pin = None, baudrate: int = 24000000, polarity: int = 0, phase: int = 0): diff --git a/shared-bindings/displayio/Group.c b/shared-bindings/displayio/Group.c index 36e137dc9..b6f96883b 100644 --- a/shared-bindings/displayio/Group.c +++ b/shared-bindings/displayio/Group.c @@ -36,12 +36,7 @@ #include "supervisor/shared/translate.h" //| class Group: -//| """.. currentmodule:: displayio -//| -//| :class:`Group` -- Group together sprites and subgroups -//| ========================================================================== -//| -//| Manage a group of sprites and groups and how they are inter-related.""" +//| """Manage a group of sprites and groups and how they are inter-related.""" //| //| def __init__(self, *, max_size: int = 4, scale: int = 1, x: int = 0, y: int = 0): //| """Create a Group of a given size and scale. Scale is in one dimension. For example, scale=2 diff --git a/shared-bindings/displayio/I2CDisplay.c b/shared-bindings/displayio/I2CDisplay.c index e2402dc49..0cfac6672 100644 --- a/shared-bindings/displayio/I2CDisplay.c +++ b/shared-bindings/displayio/I2CDisplay.c @@ -39,12 +39,7 @@ #include "supervisor/shared/translate.h" //| class I2CDisplay: -//| """.. currentmodule:: displayio -//| -//| :class:`I2CDisplay` -- Manage updating a display over I2C -//| ========================================================================== -//| -//| Manage updating a display over I2C in the background while Python code runs. +//| """Manage updating a display over I2C in the background while Python code runs. //| It doesn't handle display initialization.""" //| //| def __init__(self, i2c_bus: busio.I2C, *, device_address: int, reset: microcontroller.Pin = None): diff --git a/shared-bindings/displayio/OnDiskBitmap.c b/shared-bindings/displayio/OnDiskBitmap.c index 95c890c3b..170873653 100644 --- a/shared-bindings/displayio/OnDiskBitmap.c +++ b/shared-bindings/displayio/OnDiskBitmap.c @@ -34,12 +34,7 @@ #include "shared-bindings/displayio/OnDiskBitmap.h" //| class OnDiskBitmap: -//| """.. currentmodule:: displayio -//| -//| :class:`OnDiskBitmap` -- Loads pixels straight from disk -//| ========================================================================== -//| -//| Loads values straight from disk. This minimizes memory use but can lead to +//| """Loads values straight from disk. This minimizes memory use but can lead to //| much slower pixel load times. These load times may result in frame tearing where only part of //| the image is visible. //| diff --git a/shared-bindings/displayio/Palette.c b/shared-bindings/displayio/Palette.c index 5df11d2b1..871b2b06a 100644 --- a/shared-bindings/displayio/Palette.c +++ b/shared-bindings/displayio/Palette.c @@ -43,12 +43,7 @@ //| class Palette: -//| """.. currentmodule:: displayio -//| -//| :class:`Palette` -- Stores a mapping from bitmap pixel palette_indexes to display colors -//| ========================================================================================= -//| -//| Map a pixel palette_index to a full color. Colors are transformed to the display's format internally to +//| """Map a pixel palette_index to a full color. Colors are transformed to the display's format internally to //| save memory.""" //| //| def __init__(self, color_count: int): diff --git a/shared-bindings/displayio/ParallelBus.c b/shared-bindings/displayio/ParallelBus.c index cedcf1de5..eb75ecc03 100644 --- a/shared-bindings/displayio/ParallelBus.c +++ b/shared-bindings/displayio/ParallelBus.c @@ -38,12 +38,7 @@ #include "supervisor/shared/translate.h" //| class ParallelBus: -//| """.. currentmodule:: displayio -//| -//| :class:`ParallelBus` -- Manage updating a display over 8-bit parallel bus -//| ============================================================================== -//| -//| Manage updating a display over 8-bit parallel bus in the background while Python code runs. This +//| """Manage updating a display over 8-bit parallel bus in the background while Python code runs. This //| protocol may be refered to as 8080-I Series Parallel Interface in datasheets. It doesn't handle //| display initialization.""" //| diff --git a/shared-bindings/displayio/Shape.c b/shared-bindings/displayio/Shape.c index 0f22bb2a3..fce89c771 100644 --- a/shared-bindings/displayio/Shape.c +++ b/shared-bindings/displayio/Shape.c @@ -35,12 +35,7 @@ #include "supervisor/shared/translate.h" //| class Shape: -//| """.. currentmodule:: displayio -//| -//| :class:`Shape` -- Represents a shape by defining its bounds on each row -//| ========================================================================== -//| -//| Represents any shape made by defining boundaries that may be mirrored.""" +//| """Represents a shape made by defining boundaries that may be mirrored.""" //| //| def __init__(self, width: int, height: int, *, mirror_x: bool = False, mirror_y: bool = False): //| """Create a Shape object with the given fixed size. Each pixel is one bit and is stored by the diff --git a/shared-bindings/displayio/TileGrid.c b/shared-bindings/displayio/TileGrid.c index e7410e4b6..01fba46a5 100644 --- a/shared-bindings/displayio/TileGrid.c +++ b/shared-bindings/displayio/TileGrid.c @@ -41,10 +41,7 @@ #include "supervisor/shared/translate.h" //| class TileGrid: -//| """.. currentmodule:: displayio -//| -//| :class:`TileGrid` -- A grid of tiles sourced out of one bitmap -//| ========================================================================== +//| """A grid of tiles sourced out of one bitmap //| //| Position a grid of tiles sourced from a bitmap and pixel_shader combination. Multiple grids //| can share bitmaps and pixel shaders. diff --git a/shared-bindings/displayio/__init__.c b/shared-bindings/displayio/__init__.c index 37c025329..b791336b5 100644 --- a/shared-bindings/displayio/__init__.c +++ b/shared-bindings/displayio/__init__.c @@ -43,33 +43,10 @@ #include "shared-bindings/displayio/Shape.h" #include "shared-bindings/displayio/TileGrid.h" -//| """:mod:`displayio` --- Native display driving -//| ========================================================================= -//| -//| .. module:: displayio -//| :synopsis: Native helpers for driving displays -//| :platform: SAMD21, SAMD51, nRF52 +//| """Native helpers for driving displays //| //| The `displayio` module contains classes to manage display output -//| including synchronizing with refresh rates and partial updating. -//| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| Bitmap -//| ColorConverter -//| Display -//| EPaperDisplay -//| FourWire -//| Group -//| I2CDisplay -//| OnDiskBitmap -//| Palette -//| ParallelBus -//| Shape -//| TileGrid""" +//| including synchronizing with refresh rates and partial updating.""" //| diff --git a/shared-bindings/fontio/BuiltinFont.c b/shared-bindings/fontio/BuiltinFont.c index f60c9e36c..bf9a65873 100644 --- a/shared-bindings/fontio/BuiltinFont.c +++ b/shared-bindings/fontio/BuiltinFont.c @@ -37,12 +37,7 @@ #include "supervisor/shared/translate.h" //| class BuiltinFont: -//| """.. currentmodule:: fontio -//| -//| :class:`BuiltinFont` -- A font built into CircuitPython -//| ========================================================================================= -//| -//| A font built into CircuitPython.""" +//| """A font built into CircuitPython""" //| //| def __init__(self, ): //| """Creation not supported. Available fonts are defined when CircuitPython is built. See the diff --git a/shared-bindings/fontio/Glyph.c b/shared-bindings/fontio/Glyph.c index 6235dbc46..6558e2e7a 100644 --- a/shared-bindings/fontio/Glyph.c +++ b/shared-bindings/fontio/Glyph.c @@ -29,22 +29,27 @@ #include //| class Glyph: -//| """.. currentmodule:: fontio +//| """Storage of glyph info""" //| -//| :class:`Glyph` -- Storage of glyph info -//| ==========================================================================""" -//| -//| def __init__(self, bitmap: displayio.Bitmap, tile_index: int, width: int, height: int, dx: int, dy: int, shift_x: int, shift_y: int): +//| def __init__(self, +//| bitmap: displayio.Bitmap, +//| tile_index: int, +//| width: int, +//| height: int, +//| dx: int, +//| dy: int, +//| shift_x: int, +//| shift_y: int): //| """Named tuple used to capture a single glyph and its attributes. //| -//| :param displayio.Bitmap bitmap: the bitmap including the glyph -//| :param int tile_index: the tile index within the bitmap -//| :param int width: the width of the glyph's bitmap -//| :param int height: the height of the glyph's bitmap -//| :param int dx: x adjustment to the bitmap's position -//| :param int dy: y adjustment to the bitmap's position -//| :param int shift_x: the x difference to the next glyph -//| :param int shift_y: the y difference to the next glyph""" +//| :param bitmap: the bitmap including the glyph +//| :param tile_index: the tile index within the bitmap +//| :param width: the width of the glyph's bitmap +//| :param height: the height of the glyph's bitmap +//| :param dx: x adjustment to the bitmap's position +//| :param dy: y adjustment to the bitmap's position +//| :param shift_x: the x difference to the next glyph +//| :param shift_y: the y difference to the next glyph""" //| ... //| const mp_obj_namedtuple_type_t fontio_glyph_type = { diff --git a/shared-bindings/fontio/__init__.c b/shared-bindings/fontio/__init__.c index 478fc1806..f376f3503 100644 --- a/shared-bindings/fontio/__init__.c +++ b/shared-bindings/fontio/__init__.c @@ -33,22 +33,7 @@ #include "shared-bindings/fontio/BuiltinFont.h" #include "shared-bindings/fontio/Glyph.h" -//| """:mod:`fontio` --- Core font related data structures -//| ========================================================================= -//| -//| .. module:: fontio -//| :synopsis: Core font related data structures -//| :platform: SAMD21, SAMD51, nRF52 -//| -//| The `fontio` module contains classes to store font related information. -//| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| BuiltinFont -//| Glyph""" +//| """Core font related data structures""" //| STATIC const mp_rom_map_elem_t fontio_module_globals_table[] = { diff --git a/shared-bindings/framebufferio/FramebufferDisplay.c b/shared-bindings/framebufferio/FramebufferDisplay.c index 5e63b988e..51ef09059 100644 --- a/shared-bindings/framebufferio/FramebufferDisplay.c +++ b/shared-bindings/framebufferio/FramebufferDisplay.c @@ -41,10 +41,7 @@ #include "supervisor/shared/translate.h" //| class FramebufferDisplay: -//| """.. currentmodule:: framebufferio -//| -//| :class:`FramebufferDisplay` -- Manage updating a display with framebuffer in RAM -//| ================================================================================ +//| """Manage updating a display with framebuffer in RAM //| //| This initializes a display and connects it into CircuitPython. Unlike other //| objects in CircuitPython, Display objects live until `displayio.release_displays()` diff --git a/shared-bindings/framebufferio/__init__.c b/shared-bindings/framebufferio/__init__.c index 50725c515..492423464 100644 --- a/shared-bindings/framebufferio/__init__.c +++ b/shared-bindings/framebufferio/__init__.c @@ -28,25 +28,13 @@ #include "shared-bindings/framebufferio/__init__.h" #include "shared-bindings/framebufferio/FramebufferDisplay.h" -//| """:mod:`framebufferio` --- Native framebuffer display driving -//| ========================================================================= -//| -//| .. module:: framebufferio -//| :synopsis: Native helpers for driving displays -//| :platform: SAMD51, nRF52 +//| """Native framebuffer display driving //| //| The `framebufferio` module contains classes to manage display output //| including synchronizing with refresh rates and partial updating. //| It is used in conjunction with classes from `displayio` to actually //| place items on the display; and classes like `RGBMatrix` to actually -//| drive the display. -//| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| FramebufferDisplay""" +//| drive the display.""" //| #if CIRCUITPY_FRAMEBUFFERIO diff --git a/shared-bindings/frequencyio/FrequencyIn.c b/shared-bindings/frequencyio/FrequencyIn.c index 270fa87c3..2d628088b 100644 --- a/shared-bindings/frequencyio/FrequencyIn.c +++ b/shared-bindings/frequencyio/FrequencyIn.c @@ -36,10 +36,7 @@ #include "supervisor/shared/translate.h" //| class FrequencyIn: -//| """.. currentmodule:: frequencyio -//| -//| :class:`FrequencyIn` -- Read a frequency signal -//| ======================================================== +//| """Read a frequency signal //| //| FrequencyIn is used to measure the frequency, in hertz, of a digital signal //| on an incoming pin. Accuracy has shown to be within 10%, if not better. It diff --git a/shared-bindings/frequencyio/__init__.c b/shared-bindings/frequencyio/__init__.c index 219d5f645..031004d4b 100644 --- a/shared-bindings/frequencyio/__init__.c +++ b/shared-bindings/frequencyio/__init__.c @@ -33,23 +33,8 @@ #include "shared-bindings/frequencyio/__init__.h" #include "shared-bindings/frequencyio/FrequencyIn.h" -//| """:mod:`frequencyio` --- Support for frequency based protocols -//| ============================================================= +//| """Support for frequency based protocols //| -//| .. module:: frequencyio -//| :synopsis: Support for frequency based protocols -//| :platform: SAMD51 -//| -//| The `frequencyio` module contains classes to provide access to basic frequency IO. -//| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| FrequencyIn -//| - //| .. warning:: This module is not available in SAMD21 builds. See the //| :ref:`module-support-matrix` for more info. //| diff --git a/shared-bindings/gamepad/GamePad.c b/shared-bindings/gamepad/GamePad.c index 946a24dbf..a750892fe 100644 --- a/shared-bindings/gamepad/GamePad.c +++ b/shared-bindings/gamepad/GamePad.c @@ -35,10 +35,7 @@ #include "supervisor/shared/translate.h" //| class GamePad: -//| """.. currentmodule:: gamepad -//| -//| :class:`GamePad` -- Scan buttons for presses -//| ============================================ +//| """Scan buttons for presses //| //| Usage:: //| @@ -90,7 +87,7 @@ //| on delays. //| //| They button presses are accumulated, until the ``get_pressed`` method -//| is called, at which point the button state is cleared, and the new +//| is called, at which point the button state is cleared, and the new //| button presses start to be recorded.""" //| ... //| diff --git a/shared-bindings/gamepad/__init__.c b/shared-bindings/gamepad/__init__.c index 0c32fd6c1..557777f50 100644 --- a/shared-bindings/gamepad/__init__.c +++ b/shared-bindings/gamepad/__init__.c @@ -29,17 +29,7 @@ #include "shared-bindings/gamepad/GamePad.h" #include "shared-bindings/util.h" -//| """:mod:`gamepad` --- Button handling -//| ================================== -//| -//| .. module:: gamepad -//| :synopsis: Button handling -//| :platform: SAMD21 -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| GamePad""" +//| """Button handling in the background""" //| STATIC const mp_rom_map_elem_t gamepad_module_globals_table[] = { { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_gamepad) }, diff --git a/shared-bindings/gamepadshift/GamePadShift.c b/shared-bindings/gamepadshift/GamePadShift.c index 37be3d957..48b579457 100644 --- a/shared-bindings/gamepadshift/GamePadShift.c +++ b/shared-bindings/gamepadshift/GamePadShift.c @@ -33,10 +33,7 @@ #include "supervisor/shared/translate.h" //| class GamePadShift: -//| """.. currentmodule:: gamepadshift -//| -//| :class:`GamePadShift` -- Scan buttons for presses through a shift register -//| ===========================================================================""" +//| """Scan buttons for presses through a shift register""" //| //| def __init__(self, clock: Any, data: Any, latch: Any): //| """Initializes button scanning routines. diff --git a/shared-bindings/gamepadshift/__init__.c b/shared-bindings/gamepadshift/__init__.c index 3763b0487..f17135893 100644 --- a/shared-bindings/gamepadshift/__init__.c +++ b/shared-bindings/gamepadshift/__init__.c @@ -30,17 +30,7 @@ #include "shared-bindings/digitalio/DigitalInOut.h" #include "shared-bindings/util.h" -//| """:mod:`gamepadshift` --- Tracks button presses read through a shift register -//| =========================================================================== -//| -//| .. module:: gamepadshift -//| :synopsis: Tracks button presses read through a shift register -//| :platform: SAMD21, SAMD51 -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| GamePadShift""" +//| """Tracks button presses read through a shift register""" //| STATIC const mp_rom_map_elem_t gamepadshift_module_globals_table[] = { { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_gamepadshift) }, diff --git a/shared-bindings/help.c b/shared-bindings/help.c deleted file mode 100644 index 4e7c3a78b..000000000 --- a/shared-bindings/help.c +++ /dev/null @@ -1,34 +0,0 @@ -/* - * This file is part of the MicroPython project, http://micropython.org/ - * - * The MIT License (MIT) - * - * Copyright (c) 2016 Scott Shawcroft for Adafruit Industries - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN - * THE SOFTWARE. - */ - -//| :func:`help` - Built-in method to provide helpful information -//| ============================================================== -//| -//| .. function:: help(object=None) -//| -//| Prints a help method about the given object. When ``object`` is none, -//| prints general port information. -//| diff --git a/shared-bindings/help.rst b/shared-bindings/help.rst new file mode 100644 index 000000000..63991bff2 --- /dev/null +++ b/shared-bindings/help.rst @@ -0,0 +1,31 @@ +# This file is part of the MicroPython project, http://micropython.org/ +# +# The MIT License (MIT) +# +# Copyright (c) 2016 Scott Shawcroft for Adafruit Industries +# +# Permission is hereby granted, free of charge, to any person obtaining a copy +# of this software and associated documentation files (the "Software"), to deal +# in the Software without restriction, including without limitation the rights +# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +# copies of the Software, and to permit persons to whom the Software is +# furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice shall be included in +# all copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +# THE SOFTWARE. + +:func:`help` - Built-in method to provide helpful information +============================================================== + +.. function:: help(object=None) + + Prints a help method about the given object. When ``object`` is none, + prints general port information. diff --git a/shared-bindings/i2cslave/I2CSlave.c b/shared-bindings/i2cslave/I2CSlave.c index 5bab2af74..80875ce75 100644 --- a/shared-bindings/i2cslave/I2CSlave.c +++ b/shared-bindings/i2cslave/I2CSlave.c @@ -50,10 +50,7 @@ STATIC mp_obj_t mp_obj_new_i2cslave_i2c_slave_request(i2cslave_i2c_slave_obj_t * } //| class I2CSlave: -//| """.. currentmodule:: i2cslave -//| -//| :class:`I2CSlave` --- Two wire serial protocol slave -//| ----------------------------------------------------""" +//| """Two wire serial protocol slave""" //| //| def __init__(self, scl: microcontroller.Pin, sda: microcontroller.Pin, addresses: tuple, smbus: bool = False): //| """I2C is a two-wire protocol for communicating between devices. @@ -229,17 +226,15 @@ const mp_obj_type_t i2cslave_i2c_slave_type = { }; //| class I2CSlaveRequest: -//| """:class:`I2CSlaveRequest` --- I2C Slave Request -//| ----------------------------------------------""" //| //| def __init__(self, slave: i2cslave.I2CSlave, address: int, is_read: bool, is_restart: bool): //| """I2C transfer request from a master. //| This cannot be instantiated directly, but is returned by :py:meth:`I2CSlave.request`. //| -//| :param ~i2cslave.I2CSlave slave: The I2C Slave receiving this request -//| :param int address: I2C address -//| :param bool is_read: I2C Master read request -//| :param bool is_restart: Repeated Start Condition""" +//| :param slave: The I2C Slave receiving this request +//| :param address: I2C address +//| :param is_read: I2C Master read request +//| :param is_restart: Repeated Start Condition""" //| STATIC mp_obj_t i2cslave_i2c_slave_request_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *args, mp_map_t *kw_args) { mp_arg_check_num(n_args, kw_args, 4, 4, false); @@ -264,7 +259,7 @@ STATIC mp_obj_t i2cslave_i2c_slave_request_obj___exit__(size_t n_args, const mp_ } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(i2cslave_i2c_slave_request___exit___obj, 4, 4, i2cslave_i2c_slave_request_obj___exit__); -//| address: Any = ... +//| address: int = ... //| """The I2C address of the request.""" //| STATIC mp_obj_t i2cslave_i2c_slave_request_get_address(mp_obj_t self_in) { @@ -274,7 +269,7 @@ STATIC mp_obj_t i2cslave_i2c_slave_request_get_address(mp_obj_t self_in) { } MP_DEFINE_CONST_PROP_GET(i2cslave_i2c_slave_request_address_obj, i2cslave_i2c_slave_request_get_address); -//| is_read: Any = ... +//| is_read: bool = ... //| """The I2C master is reading from the device.""" //| STATIC mp_obj_t i2cslave_i2c_slave_request_get_is_read(mp_obj_t self_in) { @@ -284,7 +279,7 @@ STATIC mp_obj_t i2cslave_i2c_slave_request_get_is_read(mp_obj_t self_in) { } MP_DEFINE_CONST_PROP_GET(i2cslave_i2c_slave_request_is_read_obj, i2cslave_i2c_slave_request_get_is_read); -//| is_restart: Any = ... +//| is_restart: bool = ... //| """Is Repeated Start Condition.""" //| STATIC mp_obj_t i2cslave_i2c_slave_request_get_is_restart(mp_obj_t self_in) { @@ -294,14 +289,13 @@ STATIC mp_obj_t i2cslave_i2c_slave_request_get_is_restart(mp_obj_t self_in) { } MP_DEFINE_CONST_PROP_GET(i2cslave_i2c_slave_request_is_restart_obj, i2cslave_i2c_slave_request_get_is_restart); -//| def read(self, n: int = -1, ack: bool = True) -> Any: +//| def read(self, n: int = -1, ack: bool = True) -> bytearray: //| """Read data. //| If ack=False, the caller is responsible for calling :py:meth:`I2CSlaveRequest.ack`. //| -//| :param int n: Number of bytes to read (negative means all) -//| :param bool ack: Whether or not to send an ACK after the n'th byte -//| :return: Bytes read -//| :rtype: bytearray""" +//| :param n: Number of bytes to read (negative means all) +//| :param ack: Whether or not to send an ACK after the n'th byte +//| :return: Bytes read""" //| ... //| STATIC mp_obj_t i2cslave_i2c_slave_request_read(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { @@ -355,10 +349,10 @@ STATIC mp_obj_t i2cslave_i2c_slave_request_read(size_t n_args, const mp_obj_t *p } MP_DEFINE_CONST_FUN_OBJ_KW(i2cslave_i2c_slave_request_read_obj, 1, i2cslave_i2c_slave_request_read); -//| def write(self, buffer: bytearray) -> Any: +//| def write(self, buffer: bytearray) -> int: //| """Write the data contained in buffer. //| -//| :param bytearray buffer: Write out the data in this buffer +//| :param buffer: Write out the data in this buffer //| :return: Number of bytes written""" //| ... //| @@ -393,7 +387,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_2(i2cslave_i2c_slave_request_write_obj, i2cslave_ //| """Acknowledge or Not Acknowledge last byte received. //| Use together with :py:meth:`I2CSlaveRequest.read` ack=False. //| -//| :param bool ack: Whether to send an ACK or NACK""" +//| :param ack: Whether to send an ACK or NACK""" //| ... //| STATIC mp_obj_t i2cslave_i2c_slave_request_ack(uint n_args, const mp_obj_t *args) { diff --git a/shared-bindings/i2cslave/__init__.c b/shared-bindings/i2cslave/__init__.c index ffeb216fa..41b42fef8 100644 --- a/shared-bindings/i2cslave/__init__.c +++ b/shared-bindings/i2cslave/__init__.c @@ -35,22 +35,10 @@ #include "py/runtime.h" -//| """:mod:`i2cslave` --- Two wire serial protocol slave -//| ================================================== -//| -//| .. module:: i2cslave -//| :synopsis: Two wire serial protocol slave -//| :platform: SAMD21, SAMD51 +//| """Two wire serial protocol slave //| //| The `i2cslave` module contains classes to support a I2C slave. //| -//| Classes -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| I2CSlave -//| //| Example emulating 2 devices:: //| //| import board diff --git a/shared-bindings/index.rst b/shared-bindings/index.rst index cbffdb614..d94177394 100644 --- a/shared-bindings/index.rst +++ b/shared-bindings/index.rst @@ -7,13 +7,17 @@ present or if flash space is limited. For example, a microcontroller without analog features will not have `analogio`. See the `support_matrix` page for a list of modules supported on each board. +.. toctree:: + :hidden: + + support_matrix + Modules --------- .. toctree:: :glob: - :maxdepth: 3 + :maxdepth: 2 - support_matrix - */__init__ + ../autoapi/*/index help diff --git a/shared-bindings/math/__init__.c b/shared-bindings/math/__init__.c index 755bf7589..56155306f 100644 --- a/shared-bindings/math/__init__.c +++ b/shared-bindings/math/__init__.c @@ -38,12 +38,7 @@ #define MP_PI MICROPY_FLOAT_CONST(3.14159265358979323846) -//| """:mod:`math` --- mathematical functions -//| ======================================================== -//| -//| .. module:: math -//| :synopsis: mathematical functions -//| :platform: SAMD21/SAMD51 +//| """mathematical functions //| //| The `math` module provides some basic mathematical functions for //| working with floating-point numbers.""" diff --git a/shared-bindings/microcontroller/Pin.c b/shared-bindings/microcontroller/Pin.c index cad0d67b1..765e602e5 100644 --- a/shared-bindings/microcontroller/Pin.c +++ b/shared-bindings/microcontroller/Pin.c @@ -34,12 +34,7 @@ #include "supervisor/shared/translate.h" //| class Pin: -//| """.. currentmodule:: microcontroller -//| -//| :class:`Pin` --- Pin reference -//| ------------------------------------------ -//| -//| Identifies an IO pin on the microcontroller.""" +//| """Identifies an IO pin on the microcontroller.""" //| //| def __init__(self, ): //| """Identifies an IO pin on the microcontroller. They are fixed by the diff --git a/shared-bindings/microcontroller/Processor.c b/shared-bindings/microcontroller/Processor.c index dedb5a27c..c4b249124 100644 --- a/shared-bindings/microcontroller/Processor.c +++ b/shared-bindings/microcontroller/Processor.c @@ -35,12 +35,7 @@ #include "py/runtime.h" //| class Processor: -//| """.. currentmodule:: microcontroller -//| -//| :class:`Processor` --- Microcontroller CPU information and control -//| ------------------------------------------------------------------ -//| -//| Get information about the microcontroller CPU and control it. +//| """Microcontroller CPU information and control //| //| Usage:: //| @@ -55,8 +50,8 @@ //| ... //| -//| frequency: Any = ... -//| """The CPU operating frequency as an `int`, in Hertz. (read-only)""" +//| frequency: int = ... +//| """The CPU operating frequency in Hertz. (read-only)""" //| STATIC mp_obj_t mcu_processor_get_frequency(mp_obj_t self) { return mp_obj_new_int_from_uint(common_hal_mcu_processor_get_frequency()); diff --git a/shared-bindings/microcontroller/RunMode.c b/shared-bindings/microcontroller/RunMode.c index df3ff4186..6db315d8d 100644 --- a/shared-bindings/microcontroller/RunMode.c +++ b/shared-bindings/microcontroller/RunMode.c @@ -27,10 +27,7 @@ #include "shared-bindings/microcontroller/RunMode.h" //| class RunMode: -//| """.. currentmodule:: microcontroller -//| -//| :class:`RunMode` -- run state of the microcontroller -//| =============================================================""" +//| """run state of the microcontroller""" //| //| def __init__(self, ): //| """Enum-like class to define the run mode of the microcontroller and diff --git a/shared-bindings/microcontroller/__init__.c b/shared-bindings/microcontroller/__init__.c index 75b763980..21e1c90a9 100644 --- a/shared-bindings/microcontroller/__init__.c +++ b/shared-bindings/microcontroller/__init__.c @@ -42,27 +42,13 @@ #include "py/runtime.h" #include "supervisor/shared/translate.h" -//| """:mod:`microcontroller` --- Pin references and cpu functionality -//| ================================================================ -//| -//| .. module:: microcontroller -//| :synopsis: Pin references and core functionality -//| :platform: SAMD21, ESP8266 +//| """Pin references and cpu functionality //| //| The `microcontroller` module defines the pins from the perspective of the -//| microcontroller. See `board` for board-specific pin mappings. -//| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| Pin -//| Processor -//| RunMode""" +//| microcontroller. See `board` for board-specific pin mappings.""" //| -//| cpu: Any = ... +//| cpu: Processor = ... //| """CPU information and control, such as ``cpu.temperature`` and ``cpu.frequency`` //| (clock frequency). //| This object is the sole instance of `microcontroller.Processor`.""" diff --git a/shared-bindings/multiterminal/__init__.c b/shared-bindings/multiterminal/__init__.c index 3a4065019..baf2fb674 100644 --- a/shared-bindings/multiterminal/__init__.c +++ b/shared-bindings/multiterminal/__init__.c @@ -30,12 +30,7 @@ #include "py/runtime.h" #include "supervisor/shared/translate.h" -//| """:mod:`multiterminal` --- Manage additional terminal sources -//| =========================================================== -//| -//| .. module:: multiterminal -//| :synopsis: Manage additional terminal sources -//| :platform: ESP8266 +//| """Manage additional terminal sources //| //| The `multiterminal` module allows you to configure an additional serial //| terminal source. Incoming characters are accepted from both the internal diff --git a/shared-bindings/neopixel_write/__init__.c b/shared-bindings/neopixel_write/__init__.c index f18c7fdfd..5e5bc31eb 100644 --- a/shared-bindings/neopixel_write/__init__.c +++ b/shared-bindings/neopixel_write/__init__.c @@ -31,12 +31,7 @@ #include "shared-bindings/digitalio/DigitalInOut.h" #include "supervisor/shared/translate.h" -//| """:mod:`neopixel_write` --- Low-level neopixel implementation -//| =========================================================== -//| -//| .. module:: neopixel_write -//| :synopsis: Low-level neopixel implementation -//| :platform: SAMD21 +//| """Low-level neopixel implementation //| //| The `neopixel_write` module contains a helper method to write out bytes in //| the 800khz neopixel protocol. @@ -55,11 +50,11 @@ //| pixel_off = bytearray([0, 0, 0]) //| neopixel_write.neopixel_write(pin, pixel_off)""" //| -//| def neopixel_write(digitalinout: digitalio.DigitalInOut, buf: bytearray) -> Any: +//| def neopixel_write(digitalinout: digitalio.DigitalInOut, buf: bytearray) -> None: //| """Write buf out on the given DigitalInOut. //| -//| :param ~digitalio.DigitalInOut digitalinout: the DigitalInOut to output with -//| :param bytearray buf: The bytes to clock out. No assumption is made about color order""" +//| :param digitalinout: the DigitalInOut to output with +//| :param buf: The bytes to clock out. No assumption is made about color order""" //| ... STATIC mp_obj_t neopixel_write_neopixel_write_(mp_obj_t digitalinout_obj, mp_obj_t buf) { if (!MP_OBJ_IS_TYPE(digitalinout_obj, &digitalio_digitalinout_type)) { diff --git a/shared-bindings/network/__init__.c b/shared-bindings/network/__init__.c index 4f03781cf..6af86688e 100644 --- a/shared-bindings/network/__init__.c +++ b/shared-bindings/network/__init__.c @@ -38,12 +38,7 @@ #if CIRCUITPY_NETWORK -//| """:mod:`network` --- Network Interface Management -//| =============================================== -//| -//| .. module:: network -//| :synopsis: Network Interface Management -//| :platform: SAMD +//| """Network Interface Management //| //| This module provides a registry of configured NICs. //| It is used by the 'socket' module to look up a suitable diff --git a/shared-bindings/nvm/ByteArray.c b/shared-bindings/nvm/ByteArray.c index a28c2c4f9..326f719a8 100644 --- a/shared-bindings/nvm/ByteArray.c +++ b/shared-bindings/nvm/ByteArray.c @@ -31,14 +31,8 @@ #include "shared-bindings/nvm/ByteArray.h" #include "supervisor/shared/translate.h" - - - //| class ByteArray: -//| """.. currentmodule:: nvm -//| -//| :class:`ByteArray` -- Presents a stretch of non-volatile memory as a bytearray. -//| ================================================================================ +//| """Presents a stretch of non-volatile memory as a bytearray. //| //| Non-volatile memory is available as a byte array that persists over reloads //| and power cycles. Each assignment causes an erase and write cycle so its recommended to assign diff --git a/shared-bindings/nvm/__init__.c b/shared-bindings/nvm/__init__.c index 3bd9a309b..51c5bb278 100644 --- a/shared-bindings/nvm/__init__.c +++ b/shared-bindings/nvm/__init__.c @@ -31,23 +31,10 @@ #include "shared-bindings/nvm/__init__.h" #include "shared-bindings/nvm/ByteArray.h" -//| """:mod:`nvm` --- Non-volatile memory -//| =========================================================== -//| -//| .. module:: nvm -//| :synopsis: Non-volatile memory -//| :platform: SAMD21 +//| """Non-volatile memory //| //| The `nvm` module allows you to store whatever raw bytes you wish in a -//| reserved section non-volatile memory. -//| - -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| ByteArray""" +//| reserved section non-volatile memory.""" //| STATIC const mp_rom_map_elem_t nvm_module_globals_table[] = { { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_nvm) }, diff --git a/shared-bindings/os/__init__.c b/shared-bindings/os/__init__.c index 2a6b13c9b..4e991d089 100644 --- a/shared-bindings/os/__init__.c +++ b/shared-bindings/os/__init__.c @@ -37,12 +37,7 @@ #include "py/runtime.h" #include "shared-bindings/os/__init__.h" -//| """:mod:`os` --- functions that an OS normally provides -//| ======================================================== -//| -//| .. module:: os -//| :synopsis: functions that an OS normally provides -//| :platform: SAMD21 +//| """functions that an OS normally provides //| //| The `os` module is a strict subset of the CPython `cpython:os` module. So, //| code written in CircuitPython will work in CPython but not necessarily the diff --git a/shared-bindings/ps2io/Ps2.c b/shared-bindings/ps2io/Ps2.c index d327d4180..a87b14ddd 100644 --- a/shared-bindings/ps2io/Ps2.c +++ b/shared-bindings/ps2io/Ps2.c @@ -37,10 +37,7 @@ #include "supervisor/shared/translate.h" //| class Ps2: -//| """.. currentmodule:: ps2io -//| -//| :class:`Ps2` -- Communicate with a PS/2 keyboard or mouse -//| ========================================================= +//| """Communicate with a PS/2 keyboard or mouse //| //| Ps2 implements the PS/2 keyboard/mouse serial protocol, used in //| legacy devices. It is similar to UART but there are only two diff --git a/shared-bindings/ps2io/__init__.c b/shared-bindings/ps2io/__init__.c index 081127bac..38a70b1a2 100644 --- a/shared-bindings/ps2io/__init__.c +++ b/shared-bindings/ps2io/__init__.c @@ -33,22 +33,10 @@ #include "shared-bindings/microcontroller/Pin.h" #include "shared-bindings/ps2io/Ps2.h" -//| """:mod:`ps2io` --- Support for PS/2 protocol -//| ===================================================== -//| -//| .. module:: ps2io -//| :synopsis: Support for PS/2 based devices -//| :platform: SAMD21 +//| """Support for PS/2 protocol //| //| The `ps2io` module contains classes to provide PS/2 communication. //| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| Ps2 -//| //| .. warning:: This module is not available in some SAMD21 builds. See the //| :ref:`module-support-matrix` for more info. diff --git a/shared-bindings/pulseio/PWMOut.c b/shared-bindings/pulseio/PWMOut.c index 3a25d6938..7970c02f3 100644 --- a/shared-bindings/pulseio/PWMOut.c +++ b/shared-bindings/pulseio/PWMOut.c @@ -36,12 +36,7 @@ #include "supervisor/shared/translate.h" //| class PWMOut: -//| """.. currentmodule:: pulseio -//| -//| :class:`PWMOut` -- Output a Pulse Width Modulated signal -//| ======================================================== -//| -//| PWMOut can be used to output a PWM signal on a given pin.""" +//| """Output a Pulse Width Modulated signal on a given pin.""" //| //| def __init__(self, pin: microcontroller.Pin, *, duty_cycle: int = 0, frequency: int = 500, variable_frequency: bool = False): //| """Create a PWM object associated with the given pin. This allows you to diff --git a/shared-bindings/pulseio/PulseIn.c b/shared-bindings/pulseio/PulseIn.c index 9024f53e3..5c52b2582 100644 --- a/shared-bindings/pulseio/PulseIn.c +++ b/shared-bindings/pulseio/PulseIn.c @@ -36,15 +36,9 @@ #include "supervisor/shared/translate.h" //| class PulseIn: -//| """.. currentmodule:: pulseio -//| -//| :class:`PulseIn` -- Read a series of pulse durations -//| ======================================================== -//| -//| PulseIn is used to measure a series of active and idle pulses. This is -//| commonly used in infrared receivers and low cost temperature sensors (DHT). -//| The pulsed signal consists of timed active and idle periods. Unlike PWM, -//| there is no set duration for active and idle pairs.""" +//| """Measure a series of active and idle pulses. This is commonly used in infrared receivers +//| and low cost temperature sensors (DHT). The pulsed signal consists of timed active and +//| idle periods. Unlike PWM, there is no set duration for active and idle pairs.""" //| //| def __init__(self, pin: microcontroller.Pin, maxlen: int = 2, *, idle_state: bool = False): //| """Create a PulseIn object associated with the given pin. The object acts as diff --git a/shared-bindings/pulseio/PulseOut.c b/shared-bindings/pulseio/PulseOut.c index 9c650731b..16b0a6f0c 100644 --- a/shared-bindings/pulseio/PulseOut.c +++ b/shared-bindings/pulseio/PulseOut.c @@ -37,14 +37,9 @@ #include "supervisor/shared/translate.h" //| class PulseOut: -//| """.. currentmodule:: pulseio -//| -//| :class:`PulseOut` -- Output a pulse train -//| ======================================================== -//| -//| PulseOut is used to pulse PWM "carrier" output on and off. This is commonly -//| used in infrared remotes. The pulsed signal consists of timed on and off -//| periods. Unlike PWM, there is no set duration for on and off pairs.""" +//| """Pulse PWM "carrier" output on and off. This is commonly used in infrared remotes. The +//| pulsed signal consists of timed on and off periods. Unlike PWM, there is no set duration +//| for on and off pairs.""" //| //| def __init__(self, carrier: pulseio.PWMOut): //| """Create a PulseOut object associated with the given PWMout object. @@ -115,7 +110,7 @@ STATIC mp_obj_t pulseio_pulseout_obj___exit__(size_t n_args, const mp_obj_t *arg } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(pulseio_pulseout___exit___obj, 4, 4, pulseio_pulseout_obj___exit__); -//| def send(self, pulses: array.array) -> Any: +//| def send(self, pulses: array.array) -> Any: //| """Pulse alternating on and off durations in microseconds starting with on. //| ``pulses`` must be an `array.array` with data type 'H' for unsigned //| halfword (two bytes). diff --git a/shared-bindings/pulseio/__init__.c b/shared-bindings/pulseio/__init__.c index 70cb61fc3..87946e5f0 100644 --- a/shared-bindings/pulseio/__init__.c +++ b/shared-bindings/pulseio/__init__.c @@ -35,24 +35,10 @@ #include "shared-bindings/pulseio/PulseOut.h" #include "shared-bindings/pulseio/PWMOut.h" -//| """:mod:`pulseio` --- Support for pulse based protocols -//| ===================================================== -//| -//| .. module:: pulseio -//| :synopsis: Support for pulse based protocols -//| :platform: SAMD21, ESP8266 +//| """Support for pulse based protocols //| //| The `pulseio` module contains classes to provide access to basic pulse IO. //| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| PulseIn -//| PulseOut -//| PWMOut -//| //| All classes change hardware state and should be deinitialized when they //| are no longer needed if the program continues after use. To do so, either diff --git a/shared-bindings/random/__init__.c b/shared-bindings/random/__init__.c index d8b266be0..c0124df41 100644 --- a/shared-bindings/random/__init__.c +++ b/shared-bindings/random/__init__.c @@ -33,12 +33,7 @@ #include "shared-bindings/random/__init__.h" #include "supervisor/shared/translate.h" -//| """:mod:`random` --- pseudo-random numbers and choices -//| ======================================================== -//| -//| .. module:: random -//| :synopsis: pseudo-random numbers and choices -//| :platform: SAMD21, ESP8266 +//| """pseudo-random numbers and choices //| //| The `random` module is a strict subset of the CPython `cpython:random` //| module. So, code written in CircuitPython will work in CPython but not diff --git a/shared-bindings/rgbmatrix/RGBMatrix.c b/shared-bindings/rgbmatrix/RGBMatrix.c index e2393eb61..cbf570958 100644 --- a/shared-bindings/rgbmatrix/RGBMatrix.c +++ b/shared-bindings/rgbmatrix/RGBMatrix.c @@ -39,10 +39,7 @@ #include "shared-module/framebufferio/FramebufferDisplay.h" //| class RGBMatrix: -//| """.. currentmodule:: rgbmatrix -//| -//| :class:`RGBMatrix` -- Driver for HUB75-style RGB LED matrices -//| ================================================================ +//| """Displays an in-memory framebuffer to a HUB75-style RGB LED matrix.""" //| extern Protomatter_core *_PM_protoPtr; @@ -134,9 +131,6 @@ STATIC void preflight_pins_or_throw(uint8_t clock_pin, uint8_t *rgb_pins, uint8_ } } - -//| :class:`~rgbmatrix.RGBMatrix` displays an in-memory framebuffer to an LED matrix.""" -//| //| def __init__(self, *, width: Any, bit_depth: Any, rgb_pins: Any, addr_pins: Any, clock_pin: Any, latch_pin: Any, output_enable_pin: Any, doublebuffer: Any = True, framebuffer: Any = None, height: Any = 0): //| """Create a RGBMatrix object with the given attributes. The height of //| the display is determined by the number of rgb and address pins: @@ -297,7 +291,7 @@ const mp_obj_property_t rgbmatrix_rgbmatrix_brightness_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| def refresh(self, ) -> Any: ... +//| def refresh(self) -> Any: ... //| """Transmits the color data in the buffer to the pixels so that //| they are shown.""" //| @@ -309,7 +303,7 @@ STATIC mp_obj_t rgbmatrix_rgbmatrix_refresh(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(rgbmatrix_rgbmatrix_refresh_obj, rgbmatrix_rgbmatrix_refresh); -//| width: Any = ... +//| width: int = ... //| """The width of the display, in pixels""" //| STATIC mp_obj_t rgbmatrix_rgbmatrix_get_width(mp_obj_t self_in) { @@ -325,7 +319,7 @@ const mp_obj_property_t rgbmatrix_rgbmatrix_width_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| height: Any = ... +//| height: int = ... //| """The height of the display, in pixels""" //| STATIC mp_obj_t rgbmatrix_rgbmatrix_get_height(mp_obj_t self_in) { diff --git a/shared-bindings/rgbmatrix/__init__.c b/shared-bindings/rgbmatrix/__init__.c index f61002a78..7f0576652 100644 --- a/shared-bindings/rgbmatrix/__init__.c +++ b/shared-bindings/rgbmatrix/__init__.c @@ -31,16 +31,7 @@ #include "shared-bindings/rgbmatrix/RGBMatrix.h" -//| """:mod:`rgbmatrix` --- Low-level routines for bitbanged LED matrices -//| ===================================================================== -//| -//| .. module:: rgbmatrix -//| :synopsis: Low-level routines for bitbanged LED matrices -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| RGBMatrix""" +//| """Low-level routines for bitbanged LED matrices""" //| STATIC const mp_rom_map_elem_t rgbmatrix_module_globals_table[] = { diff --git a/shared-bindings/rotaryio/IncrementalEncoder.c b/shared-bindings/rotaryio/IncrementalEncoder.c index a10fb6fd5..8b2723866 100644 --- a/shared-bindings/rotaryio/IncrementalEncoder.c +++ b/shared-bindings/rotaryio/IncrementalEncoder.c @@ -35,12 +35,7 @@ #include "shared-bindings/util.h" //| class IncrementalEncoder: -//| """.. currentmodule:: rotaryio -//| -//| :class:`IncrementalEncoder` -- Track the relative position of an incremental encoder -//| ==================================================================================== -//| -//| IncrementalEncoder determines the relative rotational position based on two series of pulses.""" +//| """IncrementalEncoder determines the relative rotational position based on two series of pulses.""" //| //| def __init__(self, pin_a: microcontroller.Pin, pin_b: microcontroller.Pin): //| """Create an IncrementalEncoder object associated with the given pins. It tracks the positional diff --git a/shared-bindings/rotaryio/__init__.c b/shared-bindings/rotaryio/__init__.c index 0cc8eb556..0fa457ca7 100644 --- a/shared-bindings/rotaryio/__init__.c +++ b/shared-bindings/rotaryio/__init__.c @@ -33,27 +33,13 @@ #include "shared-bindings/rotaryio/__init__.h" #include "shared-bindings/rotaryio/IncrementalEncoder.h" -//| """:mod:`rotaryio` --- Support for reading rotation sensors -//| ======================================================== -//| -//| .. module:: rotaryio -//| :synopsis: Support for reading rotation sensors -//| :platform: SAMD +//| """Support for reading rotation sensors //| //| The `rotaryio` module contains classes to read different rotation encoding schemes. See //| `Wikipedia's Rotary Encoder page `_ for more //| background. -//| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| IncrementalEncoder -//| -//| .. warning:: This module is not available in some SAMD21 (aka M0) builds. See the -//| :ref:`module-support-matrix` for more info. +//| .. warning:: This module is not available in some SAMD21 (aka M0) builds. See the :ref:`module-support-matrix` for more info. //| //| All classes change hardware state and should be deinitialized when they diff --git a/shared-bindings/rtc/RTC.c b/shared-bindings/rtc/RTC.c index 663f5be6c..58fe308f5 100644 --- a/shared-bindings/rtc/RTC.c +++ b/shared-bindings/rtc/RTC.c @@ -38,15 +38,8 @@ const rtc_rtc_obj_t rtc_rtc_obj = {{&rtc_rtc_type}}; - - - - //| class RTC: -//| """.. currentmodule:: rtc -//| -//| :class:`RTC` --- Real Time Clock -//| --------------------------------""" +//| """Real Time Clock""" //| //| def __init__(self, ): //| """This class represents the onboard Real Time Clock. It is a singleton and will always return the same instance.""" @@ -60,7 +53,7 @@ STATIC mp_obj_t rtc_rtc_make_new(const mp_obj_type_t *type, size_t n_args, const return (mp_obj_t)&rtc_rtc_obj; } -//| datetime: Any = ... +//| datetime: time.struct_time = ... //| """The current date and time of the RTC as a `time.struct_time`. //| //| This must be set to the current date and time whenever the board loses power:: @@ -101,7 +94,7 @@ const mp_obj_property_t rtc_rtc_datetime_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| calibration: Any = ... +//| calibration: int = ... //| """The RTC calibration value as an `int`. //| //| A positive value speeds up the clock and a negative value slows it down. diff --git a/shared-bindings/rtc/__init__.c b/shared-bindings/rtc/__init__.c index 66669ca5f..b204d511c 100644 --- a/shared-bindings/rtc/__init__.c +++ b/shared-bindings/rtc/__init__.c @@ -31,23 +31,11 @@ #include "shared-bindings/rtc/RTC.h" #include "shared-bindings/time/__init__.h" -//| """:mod:`rtc` --- Real Time Clock -//| ======================================================== -//| -//| .. module:: rtc -//| :synopsis: Real Time Clock -//| :platform: SAMD21, SAMD51, nRF52 +//| """Real Time Clock //| //| The `rtc` module provides support for a Real Time Clock. You can access and manage the //| RTC using :class:`rtc.RTC`. It also backs the :func:`time.time` and :func:`time.localtime` -//| functions using the onboard RTC if present. -//| -//| Classes -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| RTC""" +//| functions using the onboard RTC if present.""" //| void rtc_reset(void) { diff --git a/shared-bindings/socket/__init__.c b/shared-bindings/socket/__init__.c index 4c0811bdb..19c4850cd 100644 --- a/shared-bindings/socket/__init__.c +++ b/shared-bindings/socket/__init__.c @@ -37,12 +37,7 @@ #include "shared-module/network/__init__.h" -//| """:mod:`socket` --- TCP, UDP and RAW socket support -//| ================================================= -//| -//| .. module:: socket -//| :synopsis: TCP, UDP and RAW sockets -//| :platform: SAMD21, SAMD51 +//| """TCP, UDP and RAW socket support //| //| Create TCP, UDP and RAW sockets for communicating over the Internet.""" //| @@ -50,7 +45,6 @@ STATIC const mp_obj_type_t socket_type; //| class socket: -//| """.. currentmodule:: socket""" //| //| def __init__(self, family: int, type: int, proto: int): //| """Create a new socket diff --git a/shared-bindings/storage/__init__.c b/shared-bindings/storage/__init__.c index feb1a9bd7..8ac08d8c9 100644 --- a/shared-bindings/storage/__init__.c +++ b/shared-bindings/storage/__init__.c @@ -35,12 +35,7 @@ #include "shared-bindings/storage/__init__.h" #include "supervisor/shared/translate.h" -//| """:mod:`storage` --- storage management -//| ======================================================== -//| -//| .. module:: storage -//| :synopsis: storage management -//| :platform: SAMD21, SAMD51 +//| """Storage management //| //| The `storage` provides storage management functionality such as mounting and //| unmounting which is typically handled by the operating system hosting Python. diff --git a/shared-bindings/struct/__init__.c b/shared-bindings/struct/__init__.c index 3772f93a7..256b385c8 100644 --- a/shared-bindings/struct/__init__.c +++ b/shared-bindings/struct/__init__.c @@ -38,12 +38,7 @@ #include "shared-module/struct/__init__.h" #include "supervisor/shared/translate.h" -//| """:mod:`struct` --- manipulation of c-style data -//| ======================================================== -//| -//| .. module:: struct -//| :synopsis: byte data control -//| :platform: SAMD21 +//| """Manipulation of c-style data //| //| This module implements a subset of the corresponding CPython module, //| as described below. For more information, refer to the original CPython @@ -56,7 +51,7 @@ //| -//| def calcsize(fmt: Any) -> Any: +//| def calcsize(fmt: str) -> int: //| """Return the number of bytes needed to store the given fmt.""" //| ... //| diff --git a/shared-bindings/supervisor/Runtime.c b/shared-bindings/supervisor/Runtime.c index 05921899c..a420d5b80 100755 --- a/shared-bindings/supervisor/Runtime.c +++ b/shared-bindings/supervisor/Runtime.c @@ -30,12 +30,7 @@ //TODO: add USB, REPL to description once they're operational //| class Runtime: -//| """.. currentmodule:: supervisor -//| -//| :class:`Runtime` --- Supervisor Runtime information -//| ---------------------------------------------------- -//| -//| Get current status of runtime objects. +//| """Current status of runtime objects. //| //| Usage:: //| @@ -50,7 +45,7 @@ //| ... //| -//| runtime.serial_connected: Any = ... +//| serial_connected: bool = ... //| """Returns the USB serial communication status (read-only). //| //| .. note:: @@ -78,7 +73,7 @@ const mp_obj_property_t supervisor_serial_connected_obj = { }; -//| runtime.serial_bytes_available: Any = ... +//| serial_bytes_available: int = ... //| """Returns the whether any bytes are available to read //| on the USB serial input. Allows for polling to see whether //| to call the built-in input() or wait. (read-only)""" diff --git a/shared-bindings/supervisor/__init__.c b/shared-bindings/supervisor/__init__.c index 7fe6668f4..1830308b7 100644 --- a/shared-bindings/supervisor/__init__.c +++ b/shared-bindings/supervisor/__init__.c @@ -36,30 +36,16 @@ #include "shared-bindings/supervisor/__init__.h" #include "shared-bindings/supervisor/Runtime.h" -//| """:mod:`supervisor` --- Supervisor settings -//| ================================================= -//| -//| .. module:: supervisor -//| :synopsis: Supervisor settings -//| :platform: SAMD21/51 (All), nRF (Runtime only) -//| -//| The `supervisor` module. (TODO: expand description) -//| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| Runtime""" +//| """Supervisor settings""" //| -//| runtime: Any = ... -//| """Runtime information, such as `runtime.serial_connected` +//| runtime: Runtime = ... +//| """Runtime information, such as ``runtime.serial_connected`` //| (USB serial connection status). //| This object is the sole instance of `supervisor.Runtime`.""" //| -//| def enable_autoreload(self, ) -> Any: +//| def enable_autoreload(self) -> None: //| """Enable autoreload based on USB file write activity.""" //| ... //| @@ -69,7 +55,7 @@ STATIC mp_obj_t supervisor_enable_autoreload(void) { } MP_DEFINE_CONST_FUN_OBJ_0(supervisor_enable_autoreload_obj, supervisor_enable_autoreload); -//| def disable_autoreload(self, ) -> Any: +//| def disable_autoreload(self) -> None: //| """Disable autoreload based on USB file write activity until //| `enable_autoreload` is called.""" //| ... @@ -80,7 +66,7 @@ STATIC mp_obj_t supervisor_disable_autoreload(void) { } MP_DEFINE_CONST_FUN_OBJ_0(supervisor_disable_autoreload_obj, supervisor_disable_autoreload); -//| def set_rgb_status_brightness(self, ) -> Any: +//| def set_rgb_status_brightness(self, brightness: int) -> None: //| """Set brightness of status neopixel from 0-255 //| `set_rgb_status_brightness` is called.""" //| ... @@ -96,7 +82,7 @@ STATIC mp_obj_t supervisor_set_rgb_status_brightness(mp_obj_t lvl){ } MP_DEFINE_CONST_FUN_OBJ_1(supervisor_set_rgb_status_brightness_obj, supervisor_set_rgb_status_brightness); -//| def reload(self, ) -> Any: +//| def reload(self) -> None: //| """Reload the main Python code and run it (equivalent to hitting Ctrl-D at the REPL).""" //| ... //| @@ -107,7 +93,7 @@ STATIC mp_obj_t supervisor_reload(void) { } MP_DEFINE_CONST_FUN_OBJ_0(supervisor_reload_obj, supervisor_reload); -//| def set_next_stack_limit(self, size: Any) -> Any: +//| def set_next_stack_limit(self, size: int) -> None: //| """Set the size of the stack for the next vm run. If its too large, the default will be used.""" //| ... //| diff --git a/shared-bindings/terminalio/Terminal.c b/shared-bindings/terminalio/Terminal.c index 1288b7018..5c045fdee 100644 --- a/shared-bindings/terminalio/Terminal.c +++ b/shared-bindings/terminalio/Terminal.c @@ -38,10 +38,7 @@ #include "supervisor/shared/translate.h" //| class Terminal: -//| """.. currentmodule:: terminalio -//| -//| :class:`Terminal` -- display a character stream with a TileGrid -//| ================================================================""" +//| """Display a character stream with a TileGrid""" //| //| def __init__(self, tilegrid: Any, font: Any): //| """Terminal manages tile indices and cursor position based on VT100 commands. The font should be diff --git a/shared-bindings/terminalio/__init__.c b/shared-bindings/terminalio/__init__.c index 591be839a..589211139 100644 --- a/shared-bindings/terminalio/__init__.c +++ b/shared-bindings/terminalio/__init__.c @@ -35,22 +35,10 @@ #include "py/runtime.h" -//| """:mod:`terminalio` --- Displays text in a TileGrid -//| ================================================= -//| -//| .. module:: terminalio -//| :synopsis: Displays text in a TileGrid +//| """Displays text in a TileGrid //| //| The `terminalio` module contains classes to display a character stream on a display. The built -//| in font is available as ``terminalio.FONT``. -//| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| Terminal""" -//| +//| in font is available as ``terminalio.FONT``.""" //| STATIC const mp_rom_map_elem_t terminalio_module_globals_table[] = { { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_terminalio) }, diff --git a/shared-bindings/time/__init__.c b/shared-bindings/time/__init__.c index 36eaa27f6..20277d6b0 100644 --- a/shared-bindings/time/__init__.c +++ b/shared-bindings/time/__init__.c @@ -36,12 +36,7 @@ #include "shared-bindings/time/__init__.h" #include "supervisor/shared/translate.h" -//| """:mod:`time` --- time and timing related functions -//| ======================================================== -//| -//| .. module:: time -//| :synopsis: time and timing related functions -//| :platform: SAMD21 +//| """time and timing related functions //| //| The `time` module is a strict subset of the CPython `cpython:time` module. So, code //| written in MicroPython will work in CPython but not necessarily the other diff --git a/shared-bindings/touchio/TouchIn.c b/shared-bindings/touchio/TouchIn.c index 6d59a1744..4c1d534ea 100644 --- a/shared-bindings/touchio/TouchIn.c +++ b/shared-bindings/touchio/TouchIn.c @@ -39,10 +39,7 @@ #include "supervisor/shared/translate.h" //| class TouchIn: -//| """.. currentmodule:: touchio -//| -//| :class:`TouchIn` -- Read the state of a capacitive touch sensor -//| =================================================================== +//| """Read the state of a capacitive touch sensor //| //| Usage:: //| diff --git a/shared-bindings/touchio/__init__.c b/shared-bindings/touchio/__init__.c index 96367f082..92e067cf6 100644 --- a/shared-bindings/touchio/__init__.c +++ b/shared-bindings/touchio/__init__.c @@ -35,23 +35,11 @@ #include "py/runtime.h" -//| """:mod:`touchio` --- Touch related IO -//| ================================================= -//| -//| .. module:: touchio -//| :synopsis: Hardware accelerated behavior -//| :platform: SAMD21 +//| """Touch related IO //| //| The `touchio` module contains classes to provide access to touch IO typically //| accelerated by hardware on the onboard microcontroller. //| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| TouchIn -//| //| All classes change hardware state and should be deinitialized when they //| are no longer needed if the program continues after use. To do so, either //| call :py:meth:`!deinit` or use a context manager. See diff --git a/shared-bindings/uheap/__init__.c b/shared-bindings/uheap/__init__.c index f1be30424..f089f2922 100644 --- a/shared-bindings/uheap/__init__.c +++ b/shared-bindings/uheap/__init__.c @@ -31,11 +31,7 @@ #include "shared-bindings/uheap/__init__.h" -//| """:mod:`uheap` --- Heap size analysis -//| ================================================================ -//| -//| .. module:: uheap -//| :synopsis: Heap size analysis""" +//| """Heap size analysis""" //| //| def info(object: Any) -> Any: diff --git a/shared-bindings/ulab/__init__.pyi b/shared-bindings/ulab/__init__.pyi new file mode 100644 index 000000000..d2ff7eb80 --- /dev/null +++ b/shared-bindings/ulab/__init__.pyi @@ -0,0 +1,523 @@ + +:mod:`ulab` --- Manipulate numeric data similar to numpy +======================================================== + +.. module:: ulab + :synopsis: Manipulate numeric data similar to numpy + +`ulab` is a numpy-like module for micropython, meant to simplify and +speed up common mathematical operations on arrays. The primary goal was to +implement a small subset of numpy that might be useful in the context of a +microcontroller. This means low-level data processing of linear (array) and +two-dimensional (matrix) data. + +`ulab` is adapted from micropython-ulab, and the original project's +documentation can be found at +https://micropython-ulab.readthedocs.io/en/latest/ + +`ulab` is modeled after numpy, and aims to be a compatible subset where +possible. Numpy's documentation can be found at +https://docs.scipy.org/doc/numpy/index.html + +.. contents:: + +.. attribute:: __version__ + +The closest corresponding version of micropython-ulab + +ulab.array -- 1- and 2- dimensional array +----------------------------------------- + +.. class:: ulab.array(values, \*, dtype=float) + + :param sequence values: Sequence giving the initial content of the array. + :param dtype: The type of array values, ``int8``, ``uint8``, ``int16``, ``uint16``, or ``float`` + + The `values` sequence can either be another ~ulab.array, sequence of numbers + (in which case a 1-dimensional array is created), or a sequence where each + subsequence has the same length (in which case a 2-dimensional array is + created). + + Passing a ~ulab.array and a different dtype can be used to convert an array + from one dtype to another. + + In many cases, it is more convenient to create an array from a function + like `zeros` or `linspace`. + + `ulab.array` implements the buffer protocol, so it can be used in many + places an `array.array` can be used. + + .. attribute:: shape + + The size of the array, a tuple of length 1 or 2 + + .. attribute:: size + + The number of elements in the array + + .. attribute:: itemsize + + The number of elements in the array + + .. method:: flatten(\*, order='C') + + :param order: Whether to flatten by rows ('C') or columns ('F') + + Returns a new `ulab.array` object which is always 1 dimensional. + If order is 'C' (the default", then the data is ordered in rows; + If it is 'F', then the data is ordered in columns. "C" and "F" refer + to the typical storage organization of the C and Fortran languages. + + .. method:: sort(\*, axis=1) + + :param axis: Whether to sort elements within rows (0), columns (1), or elements (None) + + .. method:: transpose() + + Swap the rows and columns of a 2-dimensional array + + .. method:: __add__() + + Adds corresponding elements of the two arrays, or adds a number to all + elements of the array. If both arguments are arrays, their sizes must match. + + .. method:: __sub__() + + Subtracts corresponding elements of the two arrays, or adds a number to all + elements of the array. If both arguments are arrays, their sizes must match. + + .. method:: __mul__() + + Multiplies corresponding elements of the two arrays, or multiplies + all elements of the array by a number. If both arguments are arrays, + their sizes must match. + + .. method:: __div__() + + Multiplies corresponding elements of the two arrays, or divides + all elements of the array by a number. If both arguments are arrays, + their sizes must match. + + .. method:: __pow__() + + Computes the power (x**y) of corresponding elements of the the two arrays, + or one number and one array. If both arguments are arrays, their sizes + must match. + + .. method:: __getitem__() + + Retrieve an element of the array. + + .. method:: __setitem__() + + Set an element of the array. + +Array type codes +---------------- +.. attribute:: int8 + + Type code for signed integers in the range -128 .. 127 inclusive, like the 'b' typecode of `array.array` + +.. attribute:: int16 + + Type code for signed integers in the range -32768 .. 32767 inclusive, like the 'h' typecode of `array.array` + +.. attribute:: float + + Type code for floating point values, like the 'f' typecode of `array.array` + +.. attribute:: uint8 + + Type code for unsigned integers in the range 0 .. 255 inclusive, like the 'H' typecode of `array.array` + +.. attribute:: uint16 + + Type code for unsigned integers in the range 0 .. 65535 inclusive, like the 'h' typecode of `array.array` + + +Basic Array defining functions +------------------------------ + +.. method:: ones(shape, \*, dtype=float) + + .. param: shape + Shape of the array, either an integer (for a 1-D array) or a tuple of 2 integers (for a 2-D array) + + .. param: dtype + Type of values in the array + + Return a new array of the given shape with all elements set to 1. + +.. method:: zeros + + .. param: shape + Shape of the array, either an integer (for a 1-D array) or a tuple of 2 integers (for a 2-D array) + + .. param: dtype + Type of values in the array + + Return a new array of the given shape with all elements set to 0. + + +.. method:: eye(size, \*, dtype=float) + + Return a new square array of size, with the diagonal elements set to 1 + and the other elements set to 0. + +.. method:: linspace(start, stop, \*, dtype=float, num=50, endpoint=True) + + .. param: start + + First value in the array + + .. param: stop + + Final value in the array + + .. param int: num + + Count of values in the array + + .. param: dtype + + Type of values in the array + + .. param bool: endpoint + + Whether the ``stop`` value is included. Note that even when + endpoint=True, the exact ``stop`` value may not be included due to the + inaccuracy of floating point arithmetic. + + Return a new 1-D array with ``num`` elements ranging from ``start`` to ``stop`` linearly. + + +:mod:`ulab.compare` --- Comparison functions +============================================ + +.. module::ulab.compare + +.. method:: clip(x1, x2, x3) + + Constrain the values from ``x1`` to be between ``x2`` and ``x3``. + ``x2`` is assumed to be less than or equal to ``x3``. + + Arguments may be ulab arrays or numbers. All array arguments + must be the same size. If the inputs are all scalars, a 1-element + array is returned. + + Shorthand for ``ulab.maximum(x2, ulab.minimum(x1, x3))`` + +.. method:: maximum(x1, x2) + + Compute the element by element maximum of the arguments. + + Arguments may be ulab arrays or numbers. All array arguments + must be the same size. If the inputs are both scalars, a number is + returned + +.. method:: minimum(x1, x2) + + Compute the element by element minimum of the arguments. + + Arguments may be ulab arrays or numbers. All array arguments + must be the same size. If the inputs are both scalars, a number is + returned + + +:mod:`ulab.vector` --- Element-by-element functions +=================================================== + +.. module:: ulab.vector + +These functions can operate on numbers, 1-D arrays, or 2-D arrays by +applying the function to every element in the array. This is typically +much more efficient than expressing the same operation as a Python loop. + +.. method:: acos + + Computes the inverse cosine function + +.. method:: acosh + + Computes the inverse hyperbolic cosine function + +.. method:: asin + + Computes the inverse sine function + +.. method:: asinh + + Computes the inverse hyperbolic sine function + +.. method:: around(a, \*, decimals) + + Returns a new float array in which each element is rounded to + ``decimals`` places. + +.. method:: atan + + Computes the inverse tangent function; the return values are in the + range [-pi/2,pi/2]. + +.. method:: atan2(y,x) + + Computes the inverse tangent function of y/x; the return values are in + the range [-pi, pi]. + +.. method:: atanh + + Computes the inverse hyperbolic tangent function + +.. method:: ceil + + Rounds numbers up to the next whole number + +.. method:: cos + + Computes the cosine function + +.. method:: erf + + Computes the error function, which has applications in statistics + +.. method:: erfc + + Computes the complementary error function, which has applications in statistics + +.. method:: exp + + Computes the exponent function. + +.. method:: expm1 + + Computes $e^x-1$. In certain applications, using this function preserves numeric accuracy better than the `exp` function. + +.. method:: floor + + Rounds numbers up to the next whole number + +.. method:: gamma + + Computes the gamma function + +.. method:: lgamma + + Computes the natural log of the gamma function + +.. method:: log + + Computes the natural log + +.. method:: log10 + + Computes the log base 10 + +.. method:: log2 + + Computes the log base 2 + +.. method:: sin + + Computes the sine + +.. method:: sinh + + Computes the hyperbolic sine + +.. method:: sqrt + + Computes the square root + +.. method:: tan + + Computes the tangent + +.. method:: tanh + + Computes the hyperbolic tangent + +:mod:`ulab.linalg` - Linear algebra functions +============================================= + +.. module:: ulab.linalg + +.. method:: cholesky(A) + + :param ~ulab.array A: a positive definite, symmetric square matrix + :return ~ulab.array L: a square root matrix in the lower triangular form + :raises ValueError: If the input does not fulfill the necessary conditions + + The returned matrix satisfies the equation m=LL* + +.. method:: det + + :param: m, a square matrix + :return float: The determinant of the matrix + + Computes the eigenvalues and eigenvectors of a square matrix + +.. method:: dot(m1, m2) + + :param ~ulab.array m1: a matrix + :param ~ulab.array m2: a matrix + + Computes the matrix product of two matrices + + **WARNING:** Unlike ``numpy``, this function cannot be used to compute the dot product of two vectors + +.. method:: eig(m) + + :param m: a square matrix + :return tuple (eigenvectors, eigenvalues): + + Computes the eigenvalues and eigenvectors of a square matrix + +.. method:: inv(m) + + :param ~ulab.array m: a square matrix + :return: The inverse of the matrix, if it exists + :raises ValueError: if the matrix is not invertible + + Computes the inverse of a square matrix + +.. method:: size(array) + + Return the total number of elements in the array, as an integer. + +.. method:: trace(m) + + :param m: a square matrix + + Compute the trace of the matrix, the sum of its diagonal elements. + +:mod:`ulab.filter` --- Filtering functions +========================================== + +.. module:: ulab.filter + +.. method:: convolve(r, c=None) + + :param ulab.array a: + :param ulab.array v: + + Returns the discrete, linear convolution of two one-dimensional sequences. + The result is always an array of float. Only the ``full`` mode is supported, + and the ``mode`` named parameter of numpy is not accepted. Note that all other + modes can be had by slicing a ``full`` result. + + Convolution filters can implement high pass, low pass, band pass, etc., + filtering operations. Convolution filters are typically constructed ahead + of time. This can be done using desktop python with scipy, or on web pages + such as https://fiiir.com/ + + Convolution is most time-efficient when both inputs are of float type. + +:mod:`ulab.fft` --- Frequency-domain functions +============================================== + +.. module:: ulab.fft + +.. method:: fft(r, c=None) + + :param ulab.array r: A 1-dimension array of values whose size is a power of 2 + :param ulab.array c: An optional 1-dimension array of values whose size is a power of 2, giving the complex part of the value + :return tuple (r, c): The real and complex parts of the FFT + + Perform a Fast Fourier Transform from the time domain into the frequency domain + + See also ~ulab.extras.spectrum, which computes the magnitude of the fft, + rather than separately returning its real and imaginary parts. + +.. method:: ifft(r, c=None) + + :param ulab.array r: A 1-dimension array of values whose size is a power of 2 + :param ulab.array c: An optional 1-dimension array of values whose size is a power of 2, giving the complex part of the value + :return tuple (r, c): The real and complex parts of the inverse FFT + + Perform an Inverse Fast Fourier Transform from the frequeny domain into the time domain + +:mod:`ulab.numerical` --- Numerical and Statistical functions +============================================================= + +.. module:: ulab.numerical + +Most of these functions take an "axis" argument, which indicates whether to +operate over the flattened array (None), rows (0), or columns (1). + +.. method:: argmax(array, \*, axis=None) + + Return the index of the maximum element of the 1D array + +.. method:: argmin(array, \*, axis=None) + + Return the index of the minimum element of the 1D array + +.. method:: argsort(array, \*, axis=None) + + Returns an array which gives indices into the input array from least to greatest. + +.. method:: diff(array, \*, axis=1) + + Return the numerical derivative of successive elements of the array, as + an array. axis=None is not supported. + +.. method:: flip(array, \*, axis=None) + + Returns a new array that reverses the order of the elements along the + given axis, or along all axes if axis is None. + +.. method:: max(array, \*, axis=None) + + Return the maximum element of the 1D array + +.. method:: mean(array, \*, axis=None) + + Return the mean element of the 1D array, as a number if axis is None, otherwise as an array. + +.. method:: min(array, \*, axis=None) + + Return the minimum element of the 1D array + +.. method:: roll(array, distance, \*, axis=None) + + Shift the content of a vector by the positions given as the second + argument. If the ``axis`` keyword is supplied, the shift is applied to + the given axis. The array is modified in place. + +.. method:: std(array, \*, axis=None) + + Return the standard deviation of the array, as a number if axis is None, otherwise as an array. + +.. method:: sum(array, \*, axis=None) + + Return the sum of the array, as a number if axis is None, otherwise as an array. + +.. method:: sort(array, \*, axis=0) + + Sort the array along the given axis, or along all axes if axis is None. + The array is modified in place. + +:mod:`ulab.poly` --- Polynomial functions +========================================= + +.. module:: ulab.poly + +.. method:: polyfit([x, ] y, degree) + + Return a polynomial of given degree that approximates the function + f(x)=y. If x is not supplied, it is the range(len(y)). + +.. method:: polyval(p, x) + + Evaluate the polynomial p at the points x. x must be an array. + +:mod:`ulab.extras` --- Additional functions not in numpy +======================================================== + +.. method:: spectrum(r): + + :param ulab.array r: A 1-dimension array of values whose size is a power of 2 + + Computes the spectrum of the input signal. This is the absolute value of the (complex-valued) fft of the signal. + + This function is similar to scipy's ``scipy.signal.spectrogram``. diff --git a/shared-bindings/ulab/__init__.rst b/shared-bindings/ulab/__init__.rst deleted file mode 100644 index d2ff7eb80..000000000 --- a/shared-bindings/ulab/__init__.rst +++ /dev/null @@ -1,523 +0,0 @@ - -:mod:`ulab` --- Manipulate numeric data similar to numpy -======================================================== - -.. module:: ulab - :synopsis: Manipulate numeric data similar to numpy - -`ulab` is a numpy-like module for micropython, meant to simplify and -speed up common mathematical operations on arrays. The primary goal was to -implement a small subset of numpy that might be useful in the context of a -microcontroller. This means low-level data processing of linear (array) and -two-dimensional (matrix) data. - -`ulab` is adapted from micropython-ulab, and the original project's -documentation can be found at -https://micropython-ulab.readthedocs.io/en/latest/ - -`ulab` is modeled after numpy, and aims to be a compatible subset where -possible. Numpy's documentation can be found at -https://docs.scipy.org/doc/numpy/index.html - -.. contents:: - -.. attribute:: __version__ - -The closest corresponding version of micropython-ulab - -ulab.array -- 1- and 2- dimensional array ------------------------------------------ - -.. class:: ulab.array(values, \*, dtype=float) - - :param sequence values: Sequence giving the initial content of the array. - :param dtype: The type of array values, ``int8``, ``uint8``, ``int16``, ``uint16``, or ``float`` - - The `values` sequence can either be another ~ulab.array, sequence of numbers - (in which case a 1-dimensional array is created), or a sequence where each - subsequence has the same length (in which case a 2-dimensional array is - created). - - Passing a ~ulab.array and a different dtype can be used to convert an array - from one dtype to another. - - In many cases, it is more convenient to create an array from a function - like `zeros` or `linspace`. - - `ulab.array` implements the buffer protocol, so it can be used in many - places an `array.array` can be used. - - .. attribute:: shape - - The size of the array, a tuple of length 1 or 2 - - .. attribute:: size - - The number of elements in the array - - .. attribute:: itemsize - - The number of elements in the array - - .. method:: flatten(\*, order='C') - - :param order: Whether to flatten by rows ('C') or columns ('F') - - Returns a new `ulab.array` object which is always 1 dimensional. - If order is 'C' (the default", then the data is ordered in rows; - If it is 'F', then the data is ordered in columns. "C" and "F" refer - to the typical storage organization of the C and Fortran languages. - - .. method:: sort(\*, axis=1) - - :param axis: Whether to sort elements within rows (0), columns (1), or elements (None) - - .. method:: transpose() - - Swap the rows and columns of a 2-dimensional array - - .. method:: __add__() - - Adds corresponding elements of the two arrays, or adds a number to all - elements of the array. If both arguments are arrays, their sizes must match. - - .. method:: __sub__() - - Subtracts corresponding elements of the two arrays, or adds a number to all - elements of the array. If both arguments are arrays, their sizes must match. - - .. method:: __mul__() - - Multiplies corresponding elements of the two arrays, or multiplies - all elements of the array by a number. If both arguments are arrays, - their sizes must match. - - .. method:: __div__() - - Multiplies corresponding elements of the two arrays, or divides - all elements of the array by a number. If both arguments are arrays, - their sizes must match. - - .. method:: __pow__() - - Computes the power (x**y) of corresponding elements of the the two arrays, - or one number and one array. If both arguments are arrays, their sizes - must match. - - .. method:: __getitem__() - - Retrieve an element of the array. - - .. method:: __setitem__() - - Set an element of the array. - -Array type codes ----------------- -.. attribute:: int8 - - Type code for signed integers in the range -128 .. 127 inclusive, like the 'b' typecode of `array.array` - -.. attribute:: int16 - - Type code for signed integers in the range -32768 .. 32767 inclusive, like the 'h' typecode of `array.array` - -.. attribute:: float - - Type code for floating point values, like the 'f' typecode of `array.array` - -.. attribute:: uint8 - - Type code for unsigned integers in the range 0 .. 255 inclusive, like the 'H' typecode of `array.array` - -.. attribute:: uint16 - - Type code for unsigned integers in the range 0 .. 65535 inclusive, like the 'h' typecode of `array.array` - - -Basic Array defining functions ------------------------------- - -.. method:: ones(shape, \*, dtype=float) - - .. param: shape - Shape of the array, either an integer (for a 1-D array) or a tuple of 2 integers (for a 2-D array) - - .. param: dtype - Type of values in the array - - Return a new array of the given shape with all elements set to 1. - -.. method:: zeros - - .. param: shape - Shape of the array, either an integer (for a 1-D array) or a tuple of 2 integers (for a 2-D array) - - .. param: dtype - Type of values in the array - - Return a new array of the given shape with all elements set to 0. - - -.. method:: eye(size, \*, dtype=float) - - Return a new square array of size, with the diagonal elements set to 1 - and the other elements set to 0. - -.. method:: linspace(start, stop, \*, dtype=float, num=50, endpoint=True) - - .. param: start - - First value in the array - - .. param: stop - - Final value in the array - - .. param int: num - - Count of values in the array - - .. param: dtype - - Type of values in the array - - .. param bool: endpoint - - Whether the ``stop`` value is included. Note that even when - endpoint=True, the exact ``stop`` value may not be included due to the - inaccuracy of floating point arithmetic. - - Return a new 1-D array with ``num`` elements ranging from ``start`` to ``stop`` linearly. - - -:mod:`ulab.compare` --- Comparison functions -============================================ - -.. module::ulab.compare - -.. method:: clip(x1, x2, x3) - - Constrain the values from ``x1`` to be between ``x2`` and ``x3``. - ``x2`` is assumed to be less than or equal to ``x3``. - - Arguments may be ulab arrays or numbers. All array arguments - must be the same size. If the inputs are all scalars, a 1-element - array is returned. - - Shorthand for ``ulab.maximum(x2, ulab.minimum(x1, x3))`` - -.. method:: maximum(x1, x2) - - Compute the element by element maximum of the arguments. - - Arguments may be ulab arrays or numbers. All array arguments - must be the same size. If the inputs are both scalars, a number is - returned - -.. method:: minimum(x1, x2) - - Compute the element by element minimum of the arguments. - - Arguments may be ulab arrays or numbers. All array arguments - must be the same size. If the inputs are both scalars, a number is - returned - - -:mod:`ulab.vector` --- Element-by-element functions -=================================================== - -.. module:: ulab.vector - -These functions can operate on numbers, 1-D arrays, or 2-D arrays by -applying the function to every element in the array. This is typically -much more efficient than expressing the same operation as a Python loop. - -.. method:: acos - - Computes the inverse cosine function - -.. method:: acosh - - Computes the inverse hyperbolic cosine function - -.. method:: asin - - Computes the inverse sine function - -.. method:: asinh - - Computes the inverse hyperbolic sine function - -.. method:: around(a, \*, decimals) - - Returns a new float array in which each element is rounded to - ``decimals`` places. - -.. method:: atan - - Computes the inverse tangent function; the return values are in the - range [-pi/2,pi/2]. - -.. method:: atan2(y,x) - - Computes the inverse tangent function of y/x; the return values are in - the range [-pi, pi]. - -.. method:: atanh - - Computes the inverse hyperbolic tangent function - -.. method:: ceil - - Rounds numbers up to the next whole number - -.. method:: cos - - Computes the cosine function - -.. method:: erf - - Computes the error function, which has applications in statistics - -.. method:: erfc - - Computes the complementary error function, which has applications in statistics - -.. method:: exp - - Computes the exponent function. - -.. method:: expm1 - - Computes $e^x-1$. In certain applications, using this function preserves numeric accuracy better than the `exp` function. - -.. method:: floor - - Rounds numbers up to the next whole number - -.. method:: gamma - - Computes the gamma function - -.. method:: lgamma - - Computes the natural log of the gamma function - -.. method:: log - - Computes the natural log - -.. method:: log10 - - Computes the log base 10 - -.. method:: log2 - - Computes the log base 2 - -.. method:: sin - - Computes the sine - -.. method:: sinh - - Computes the hyperbolic sine - -.. method:: sqrt - - Computes the square root - -.. method:: tan - - Computes the tangent - -.. method:: tanh - - Computes the hyperbolic tangent - -:mod:`ulab.linalg` - Linear algebra functions -============================================= - -.. module:: ulab.linalg - -.. method:: cholesky(A) - - :param ~ulab.array A: a positive definite, symmetric square matrix - :return ~ulab.array L: a square root matrix in the lower triangular form - :raises ValueError: If the input does not fulfill the necessary conditions - - The returned matrix satisfies the equation m=LL* - -.. method:: det - - :param: m, a square matrix - :return float: The determinant of the matrix - - Computes the eigenvalues and eigenvectors of a square matrix - -.. method:: dot(m1, m2) - - :param ~ulab.array m1: a matrix - :param ~ulab.array m2: a matrix - - Computes the matrix product of two matrices - - **WARNING:** Unlike ``numpy``, this function cannot be used to compute the dot product of two vectors - -.. method:: eig(m) - - :param m: a square matrix - :return tuple (eigenvectors, eigenvalues): - - Computes the eigenvalues and eigenvectors of a square matrix - -.. method:: inv(m) - - :param ~ulab.array m: a square matrix - :return: The inverse of the matrix, if it exists - :raises ValueError: if the matrix is not invertible - - Computes the inverse of a square matrix - -.. method:: size(array) - - Return the total number of elements in the array, as an integer. - -.. method:: trace(m) - - :param m: a square matrix - - Compute the trace of the matrix, the sum of its diagonal elements. - -:mod:`ulab.filter` --- Filtering functions -========================================== - -.. module:: ulab.filter - -.. method:: convolve(r, c=None) - - :param ulab.array a: - :param ulab.array v: - - Returns the discrete, linear convolution of two one-dimensional sequences. - The result is always an array of float. Only the ``full`` mode is supported, - and the ``mode`` named parameter of numpy is not accepted. Note that all other - modes can be had by slicing a ``full`` result. - - Convolution filters can implement high pass, low pass, band pass, etc., - filtering operations. Convolution filters are typically constructed ahead - of time. This can be done using desktop python with scipy, or on web pages - such as https://fiiir.com/ - - Convolution is most time-efficient when both inputs are of float type. - -:mod:`ulab.fft` --- Frequency-domain functions -============================================== - -.. module:: ulab.fft - -.. method:: fft(r, c=None) - - :param ulab.array r: A 1-dimension array of values whose size is a power of 2 - :param ulab.array c: An optional 1-dimension array of values whose size is a power of 2, giving the complex part of the value - :return tuple (r, c): The real and complex parts of the FFT - - Perform a Fast Fourier Transform from the time domain into the frequency domain - - See also ~ulab.extras.spectrum, which computes the magnitude of the fft, - rather than separately returning its real and imaginary parts. - -.. method:: ifft(r, c=None) - - :param ulab.array r: A 1-dimension array of values whose size is a power of 2 - :param ulab.array c: An optional 1-dimension array of values whose size is a power of 2, giving the complex part of the value - :return tuple (r, c): The real and complex parts of the inverse FFT - - Perform an Inverse Fast Fourier Transform from the frequeny domain into the time domain - -:mod:`ulab.numerical` --- Numerical and Statistical functions -============================================================= - -.. module:: ulab.numerical - -Most of these functions take an "axis" argument, which indicates whether to -operate over the flattened array (None), rows (0), or columns (1). - -.. method:: argmax(array, \*, axis=None) - - Return the index of the maximum element of the 1D array - -.. method:: argmin(array, \*, axis=None) - - Return the index of the minimum element of the 1D array - -.. method:: argsort(array, \*, axis=None) - - Returns an array which gives indices into the input array from least to greatest. - -.. method:: diff(array, \*, axis=1) - - Return the numerical derivative of successive elements of the array, as - an array. axis=None is not supported. - -.. method:: flip(array, \*, axis=None) - - Returns a new array that reverses the order of the elements along the - given axis, or along all axes if axis is None. - -.. method:: max(array, \*, axis=None) - - Return the maximum element of the 1D array - -.. method:: mean(array, \*, axis=None) - - Return the mean element of the 1D array, as a number if axis is None, otherwise as an array. - -.. method:: min(array, \*, axis=None) - - Return the minimum element of the 1D array - -.. method:: roll(array, distance, \*, axis=None) - - Shift the content of a vector by the positions given as the second - argument. If the ``axis`` keyword is supplied, the shift is applied to - the given axis. The array is modified in place. - -.. method:: std(array, \*, axis=None) - - Return the standard deviation of the array, as a number if axis is None, otherwise as an array. - -.. method:: sum(array, \*, axis=None) - - Return the sum of the array, as a number if axis is None, otherwise as an array. - -.. method:: sort(array, \*, axis=0) - - Sort the array along the given axis, or along all axes if axis is None. - The array is modified in place. - -:mod:`ulab.poly` --- Polynomial functions -========================================= - -.. module:: ulab.poly - -.. method:: polyfit([x, ] y, degree) - - Return a polynomial of given degree that approximates the function - f(x)=y. If x is not supplied, it is the range(len(y)). - -.. method:: polyval(p, x) - - Evaluate the polynomial p at the points x. x must be an array. - -:mod:`ulab.extras` --- Additional functions not in numpy -======================================================== - -.. method:: spectrum(r): - - :param ulab.array r: A 1-dimension array of values whose size is a power of 2 - - Computes the spectrum of the input signal. This is the absolute value of the (complex-valued) fft of the signal. - - This function is similar to scipy's ``scipy.signal.spectrogram``. diff --git a/shared-bindings/usb_hid/Device.c b/shared-bindings/usb_hid/Device.c index bcea5b2c5..8c0c364ff 100644 --- a/shared-bindings/usb_hid/Device.c +++ b/shared-bindings/usb_hid/Device.c @@ -28,10 +28,7 @@ #include "shared-bindings/usb_hid/Device.h" //| class Device: -//| """.. currentmodule:: usb_hid -//| -//| :class:`Device` -- HID Device -//| ============================================ +//| """HID Device //| //| Usage:: //| diff --git a/shared-bindings/usb_hid/__init__.c b/shared-bindings/usb_hid/__init__.c index 3d0978d62..e12ea8da4 100644 --- a/shared-bindings/usb_hid/__init__.c +++ b/shared-bindings/usb_hid/__init__.c @@ -31,12 +31,7 @@ #include "shared-bindings/usb_hid/__init__.h" #include "shared-bindings/usb_hid/Device.h" -//| """:mod:`usb_hid` --- USB Human Interface Device -//| =========================================================== -//| -//| .. module:: usb_hid -//| :synopsis: USB Human Interface Device -//| :platform: SAMD21 +//| """USB Human Interface Device //| //| The `usb_hid` module allows you to output data as a HID device.""" //| @@ -44,14 +39,6 @@ //| usb_hid.devices: Any = ... //| """Tuple of all active HID device interfaces.""" //| - -//| """Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| Device""" -//| STATIC const mp_rom_map_elem_t usb_hid_module_globals_table[] = { { MP_ROM_QSTR(MP_QSTR___name__), MP_OBJ_NEW_QSTR(MP_QSTR_usb_hid) }, { MP_ROM_QSTR(MP_QSTR_devices), MP_ROM_PTR(&common_hal_usb_hid_devices) }, diff --git a/shared-bindings/usb_midi/PortIn.c b/shared-bindings/usb_midi/PortIn.c index 55a5865ca..9d9310b47 100644 --- a/shared-bindings/usb_midi/PortIn.c +++ b/shared-bindings/usb_midi/PortIn.c @@ -36,12 +36,9 @@ #include "supervisor/shared/translate.h" //| class PortIn: -//| """.. currentmodule:: usb_midi +//| """Receives midi commands over USB""" //| -//| :class:`PortIn` -- receives midi commands over USB -//| ===================================================""" -//| -//| def __init__(self, ): +//| def __init__(self): //| """You cannot create an instance of `usb_midi.PortIn`. //| //| PortIn objects are constructed for every corresponding entry in the USB diff --git a/shared-bindings/usb_midi/PortOut.c b/shared-bindings/usb_midi/PortOut.c index d83eb53b6..14ed0e767 100644 --- a/shared-bindings/usb_midi/PortOut.c +++ b/shared-bindings/usb_midi/PortOut.c @@ -36,10 +36,7 @@ #include "supervisor/shared/translate.h" //| class PortOut: -//| """.. currentmodule:: usb_midi -//| -//| :class:`PortOut` -- sends midi messages to a computer over USB -//| ==============================================================""" +//| """Sends midi messages to a computer over USB""" //| //| def __init__(self, ): //| """You cannot create an instance of `usb_midi.PortOut`. diff --git a/shared-bindings/usb_midi/__init__.c b/shared-bindings/usb_midi/__init__.c index 2631d8a88..5570b601c 100644 --- a/shared-bindings/usb_midi/__init__.c +++ b/shared-bindings/usb_midi/__init__.c @@ -35,22 +35,7 @@ #include "py/runtime.h" -//| """:mod:`usb_midi` --- MIDI over USB -//| ================================================= -//| -//| .. module:: usb_midi -//| :synopsis: MIDI over USB -//| -//| The `usb_midi` module contains classes to transmit and receive MIDI messages over USB -//| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| PortIn -//| PortOut""" -//| +//| """Classes to transmit and receive MIDI messages over USB""" //| mp_map_elem_t usb_midi_module_globals_table[] = { { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_usb_midi) }, diff --git a/shared-bindings/ustack/__init__.c b/shared-bindings/ustack/__init__.c index 073840aba..e5fac6941 100644 --- a/shared-bindings/ustack/__init__.c +++ b/shared-bindings/ustack/__init__.c @@ -34,15 +34,11 @@ -//| """:mod:`ustack` --- Stack information and analysis -//| ======================================================== -//| -//| .. module:: ustack -//| :synopsis: stack information functions""" +//| """Stack information and analysis""" //| #if MICROPY_MAX_STACK_USAGE -//| def max_stack_usage() -> Any: +//| def max_stack_usage() -> int: //| """Return the maximum excursion of the stack so far.""" //| ... //| @@ -53,7 +49,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_0(max_stack_usage_obj, max_stack_usage); #endif // MICROPY_MAX_STACK_USAGE -//| def stack_size() -> Any: +//| def stack_size() -> int: //| """Return the size of the entire stack. //| Same as in micropython.mem_info(), but returns a value instead //| of just printing it.""" diff --git a/shared-bindings/wiznet/__init__.c b/shared-bindings/wiznet/__init__.c index 5c8e8d3fd..0b0b7b14b 100644 --- a/shared-bindings/wiznet/__init__.c +++ b/shared-bindings/wiznet/__init__.c @@ -35,21 +35,7 @@ #include "shared-module/network/__init__.h" -//| """:mod:`wiznet` --- Support for WizNet hardware -//| ============================================= -//| -//| .. module:: wiznet -//| :synopsis: Support for WizNet hardware -//| :platform: SAMD -//| -//| Support for WizNet hardware, including the WizNet 5500 Ethernet adaptor. -//| -//| Libraries -//| -//| .. toctree:: -//| :maxdepth: 3 -//| -//| wiznet5k""" +//| """Support for WizNet hardware, including the WizNet 5500 Ethernet adaptor.""" //| extern const mod_network_nic_type_t mod_network_nic_type_wiznet5k; diff --git a/shared-bindings/wiznet/wiznet5k.c b/shared-bindings/wiznet/wiznet5k.c index 2e2ee3949..2f49dffea 100644 --- a/shared-bindings/wiznet/wiznet5k.c +++ b/shared-bindings/wiznet/wiznet5k.c @@ -47,10 +47,7 @@ #include "shared-module/wiznet/wiznet5k.h" //| class WIZNET5K: -//| """.. currentmodule:: wiznet -//| -//| :class:`WIZNET5K` -- wrapper for Wiznet 5500 Ethernet interface -//| ===============================================================""" +//| """Wrapper for Wiznet 5500 Ethernet interface""" //| //| def __init__(self, spi: busio.SPI, cs: microcontroller.Pin, rst: microcontroller.Pin, dhcp: bool = True): //| """Create a new WIZNET5500 interface using the specified pins diff --git a/tools/extract_pyi.py b/tools/extract_pyi.py index de783eb27..95370f761 100644 --- a/tools/extract_pyi.py +++ b/tools/extract_pyi.py @@ -22,7 +22,7 @@ for module in modules: pyi_lines = [] classes = os.listdir(module_path) classes = [x for x in sorted(classes) if x.endswith(".c")] - if classes[-1] == "__init__.c": + if classes and classes[-1] == "__init__.c": classes.insert(0, classes.pop()) for class_file in classes: class_path = os.path.join(module_path, class_file) @@ -37,6 +37,13 @@ for module in modules: continue pyi_lines.append(line) + raw_stubs = [x for x in sorted(classes) if x.endswith(".pyi")] + if raw_stubs and raw_stubs[-1] == "__init__.pyi": + raw_stubs.insert(0, raw_stubs.pop()) + for raw_stub in raw_stubs: + raw_stub_path = os.path.join(module_path, raw_stub) + with open(raw_stub_path, "r") as f: + pyi_lines.extend(f.readlines()) stub_filename = os.path.join(stub_directory, module + ".pyi") print(stub_filename) stub_contents = "".join(pyi_lines) @@ -54,3 +61,6 @@ for module in modules: print() print(f"{ok} ok out of {total}") + +if ok != total: + sys.exit(total - ok) -- cgit v1.2.3