Merge pull request #2810 from dherrada/master

Pyi integration

1 files changed, 103 insertions, 110 deletions

diff --git a/shared-bindings/displayio/Display.c b/shared-bindings/displayio/Display.c
index a22b2add2..62ef0f5d0 100644
--- a/shared-bindings/displayio/Display.c
+++ b/shared-bindings/displayio/Display.c
@@ -39,73 +39,71 @@
 #include "shared-module/displayio/__init__.h"
 #include "supervisor/shared/translate.h"
 
-//| .. currentmodule:: displayio
-//|
-//| :class:`Display` -- 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()`
-//| is called. This is done so that CircuitPython can use the display itself.
-//|
-//| Most people should not use this class directly. Use a specific display driver instead that will
-//| contain the initialization sequence at minimum.
-//|
-//| .. class:: Display(display_bus, init_sequence, *, width, height, colstart=0, rowstart=0, rotation=0, color_depth=16, grayscale=False, pixels_in_byte_share_row=True, bytes_per_cell=1, reverse_pixels_in_byte=False, set_column_command=0x2a, set_row_command=0x2b, write_ram_command=0x2c, set_vertical_scroll=0, backlight_pin=None, brightness_command=None, brightness=1.0, auto_brightness=False, single_byte_bounds=False, data_as_commands=False, auto_refresh=True, native_frames_per_second=60)
-//|
-//|   Create a Display object on the given display bus (`displayio.FourWire` or `displayio.ParallelBus`).
-//|
-//|   The ``init_sequence`` is bitpacked to minimize the ram impact. Every command begins with a
-//|   command byte followed by a byte to determine the parameter count and if a delay is need after.
-//|   When the top bit of the second byte is 1, the next byte will be the delay time in milliseconds.
-//|   The remaining 7 bits are the parameter count excluding any delay byte. The third through final
-//|   bytes are the remaining command parameters. The next byte will begin a new command definition.
-//|   Here is a portion of ILI9341 init code:
-//|
-//|   .. code-block:: python
-//|
-//|     init_sequence = (b"\xe1\x0f\x00\x0E\x14\x03\x11\x07\x31\xC1\x48\x08\x0F\x0C\x31\x36\x0F" # Set Gamma
-//|                      b"\x11\x80\x78"# Exit Sleep then delay 0x78 (120ms)
-//|                      b"\x29\x80\x78"# Display on then delay 0x78 (120ms)
-//|                     )
-//|      display = displayio.Display(display_bus, init_sequence, width=320, height=240)
-//|
-//|   The first command is 0xe1 with 15 (0xf) parameters following. The second and third are 0x11 and
-//|   0x29 respectively with delays (0x80) of 120ms (0x78) and no parameters. Multiple byte literals
-//|   (b"") are merged together on load. The parens are needed to allow byte literals on subsequent
-//|   lines.
-//|
-//|   The initialization sequence should always leave the display memory access inline with the scan
-//|   of the display to minimize tearing artifacts.
-//|
-//|   :param display_bus: The bus that the display is connected to
-//|   :type display_bus: displayio.FourWire or displayio.ParallelBus
-//|   :param buffer init_sequence: Byte-packed initialization sequence.
-//|   :param int width: Width in pixels
-//|   :param int height: Height in pixels
-//|   :param int colstart: The index if the first visible column
-//|   :param int rowstart: The index if the first visible row
-//|   :param int rotation: The rotation of the display in degrees clockwise. Must be in 90 degree increments (0, 90, 180, 270)
-//|   :param int color_depth: The number of bits of color per pixel transmitted. (Some displays
-//|       support 18 bit but 16 is easier to transmit. The last bit is extrapolated.)
-//|   :param bool grayscale: True if the display only shows a single color.
-//|   :param bool pixels_in_byte_share_row: True when pixels are less than a byte and a byte includes pixels from the same row of the display. When False, pixels share a column.
-//|   :param int bytes_per_cell: Number of bytes per addressable memory location when color_depth < 8. When greater than one, bytes share a row or column according to pixels_in_byte_share_row.
-//|   :param bool reverse_pixels_in_byte: Reverses the pixel order within each byte when color_depth < 8. Does not apply across multiple bytes even if there is more than one byte per cell (bytes_per_cell.)
-//|   :param bool reverse_bytes_in_word: Reverses the order of bytes within a word when color_depth == 16
-//|   :param int set_column_command: Command used to set the start and end columns to update
-//|   :param int set_row_command: Command used so set the start and end rows to update
-//|   :param int write_ram_command: Command used to write pixels values into the update region. Ignored if data_as_commands is set.
-//|   :param int set_vertical_scroll: Command used to set the first row to show
-//|   :param microcontroller.Pin backlight_pin: Pin connected to the display's backlight
-//|   :param int brightness_command: Command to set display brightness. Usually available in OLED controllers.
-//|   :param bool brightness: Initial display brightness. This value is ignored if auto_brightness is True.
-//|   :param bool auto_brightness: If True, brightness is controlled via an ambient light sensor or other mechanism.
-//|   :param bool single_byte_bounds: Display column and row commands use single bytes
-//|   :param bool data_as_commands: Treat all init and boundary data as SPI commands. Certain displays require this.
-//|   :param bool auto_refresh: Automatically refresh the screen
-//|   :param int native_frames_per_second: Number of display refreshes per second that occur with the given init_sequence.
-//|   :param bool backlight_on_high: If True, pulling the backlight pin high turns the backlight on.
+//| class Display:
+//|     """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()`
+//|     is called. This is done so that CircuitPython can use the display itself.
+//|
+//|     Most people should not use this class directly. Use a specific display driver instead that will
+//|     contain the initialization sequence at minimum."""
+//|
+//|     def __init__(self, display_bus: Any, init_sequence: buffer, *, width: int, height: int, colstart: int = 0, rowstart: int = 0, rotation: int = 0, color_depth: int = 16, grayscale: bool = False, pixels_in_byte_share_row: bool = True, bytes_per_cell: int = 1, reverse_pixels_in_byte: bool = False, set_column_command: int = 0x2a, set_row_command: int = 0x2b, write_ram_command: int = 0x2c, set_vertical_scroll: int = 0, backlight_pin: microcontroller.Pin = None, brightness_command: int = None, brightness: bool = 1.0, auto_brightness: bool = False, single_byte_bounds: bool = False, data_as_commands: bool = False, auto_refresh: bool = True, native_frames_per_second: int = 60):
+//|         """Create a Display object on the given display bus (`displayio.FourWire` or `displayio.ParallelBus`).
+//|
+//|         The ``init_sequence`` is bitpacked to minimize the ram impact. Every command begins with a
+//|         command byte followed by a byte to determine the parameter count and if a delay is need after.
+//|         When the top bit of the second byte is 1, the next byte will be the delay time in milliseconds.
+//|         The remaining 7 bits are the parameter count excluding any delay byte. The third through final
+//|         bytes are the remaining command parameters. The next byte will begin a new command definition.
+//|         Here is a portion of ILI9341 init code:
+//|
+//|         .. code-block:: python
+//|
+//|           init_sequence = (b"\xe1\x0f\x00\x0E\x14\x03\x11\x07\x31\xC1\x48\x08\x0F\x0C\x31\x36\x0F" # Set Gamma
+//|                            b"\x11\x80\x78"# Exit Sleep then delay 0x78 (120ms)
+//|                            b"\x29\x80\x78"# Display on then delay 0x78 (120ms)
+//|                           )
+//|            display = displayio.Display(display_bus, init_sequence, width=320, height=240)
+//|
+//|         The first command is 0xe1 with 15 (0xf) parameters following. The second and third are 0x11 and
+//|         0x29 respectively with delays (0x80) of 120ms (0x78) and no parameters. Multiple byte literals
+//|         (b"") are merged together on load. The parens are needed to allow byte literals on subsequent
+//|         lines.
+//|
+//|         The initialization sequence should always leave the display memory access inline with the scan
+//|         of the display to minimize tearing artifacts.
+//|
+//|         :param display_bus: The bus that the display is connected to
+//|         :type display_bus: displayio.FourWire or displayio.ParallelBus
+//|         :param buffer init_sequence: Byte-packed initialization sequence.
+//|         :param int width: Width in pixels
+//|         :param int height: Height in pixels
+//|         :param int colstart: The index if the first visible column
+//|         :param int rowstart: The index if the first visible row
+//|         :param int rotation: The rotation of the display in degrees clockwise. Must be in 90 degree increments (0, 90, 180, 270)
+//|         :param int color_depth: The number of bits of color per pixel transmitted. (Some displays
+//|             support 18 bit but 16 is easier to transmit. The last bit is extrapolated.)
+//|         :param bool grayscale: True if the display only shows a single color.
+//|         :param bool pixels_in_byte_share_row: True when pixels are less than a byte and a byte includes pixels from the same row of the display. When False, pixels share a column.
+//|         :param int bytes_per_cell: Number of bytes per addressable memory location when color_depth < 8. When greater than one, bytes share a row or column according to pixels_in_byte_share_row.
+//|         :param bool reverse_pixels_in_byte: Reverses the pixel order within each byte when color_depth < 8. Does not apply across multiple bytes even if there is more than one byte per cell (bytes_per_cell.)
+//|         :param bool reverse_bytes_in_word: Reverses the order of bytes within a word when color_depth == 16
+//|         :param int set_column_command: Command used to set the start and end columns to update
+//|         :param int set_row_command: Command used so set the start and end rows to update
+//|         :param int write_ram_command: Command used to write pixels values into the update region. Ignored if data_as_commands is set.
+//|         :param int set_vertical_scroll: Command used to set the first row to show
+//|         :param microcontroller.Pin backlight_pin: Pin connected to the display's backlight
+//|         :param int brightness_command: Command to set display brightness. Usually available in OLED controllers.
+//|         :param bool brightness: Initial display brightness. This value is ignored if auto_brightness is True.
+//|         :param bool auto_brightness: If True, brightness is controlled via an ambient light sensor or other mechanism.
+//|         :param bool single_byte_bounds: Display column and row commands use single bytes
+//|         :param bool data_as_commands: Treat all init and boundary data as SPI commands. Certain displays require this.
+//|         :param bool auto_refresh: Automatically refresh the screen
+//|         :param int native_frames_per_second: Number of display refreshes per second that occur with the given init_sequence.
+//|         :param bool backlight_on_high: If True, pulling the backlight pin high turns the backlight on."""
+//|         ...
 //|
 STATIC mp_obj_t displayio_display_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
     enum { ARG_display_bus, ARG_init_sequence, ARG_width, ARG_height, ARG_colstart, ARG_rowstart, ARG_rotation, ARG_color_depth, ARG_grayscale, ARG_pixels_in_byte_share_row, ARG_bytes_per_cell, ARG_reverse_pixels_in_byte, ARG_reverse_bytes_in_word, ARG_set_column_command, ARG_set_row_command, ARG_write_ram_command, ARG_set_vertical_scroll, ARG_backlight_pin, ARG_brightness_command, ARG_brightness, ARG_auto_brightness, ARG_single_byte_bounds, ARG_data_as_commands, ARG_auto_refresh, ARG_native_frames_per_second, ARG_backlight_on_high };
@@ -190,12 +188,13 @@ static displayio_display_obj_t* native_display(mp_obj_t display_obj) {
     return MP_OBJ_TO_PTR(native_display);
 }
 
-//|   .. method:: show(group)
+//|     def show(self, group: Group) -> Any:
+//|         """Switches to displaying the given group of layers. When group is None, the default
+//|         CircuitPython terminal will be shown.
 //|
-//|     Switches to displaying the given group of layers. When group is None, the default
-//|     CircuitPython terminal will be shown.
+//|         :param Group group: The group to show."""
+//|         ...
 //|
-//|     :param Group group: The group to show.
 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;
@@ -211,21 +210,21 @@ STATIC mp_obj_t displayio_display_obj_show(mp_obj_t self_in, mp_obj_t group_in)
 }
 MP_DEFINE_CONST_FUN_OBJ_2(displayio_display_show_obj, displayio_display_obj_show);
 
-//|   .. method:: refresh(*, target_frames_per_second=60, minimum_frames_per_second=1)
-//|
-//|     When auto refresh is off, waits for the target frame rate and then refreshes the display,
-//|     returning True. If the call has taken too long since the last refresh call for the given
-//|     target frame rate, then the refresh returns False immediately without updating the screen to
-//|     hopefully help getting caught up.
+//|     def refresh(self, *, target_frames_per_second: int = 60, minimum_frames_per_second: int = 1) -> Any:
+//|         """When auto refresh is off, waits for the target frame rate and then refreshes the display,
+//|         returning True. If the call has taken too long since the last refresh call for the given
+//|         target frame rate, then the refresh returns False immediately without updating the screen to
+//|         hopefully help getting caught up.
 //|
-//|     If the time since the last successful refresh is below the minimum frame rate, then an
-//|     exception will be raised. Set minimum_frames_per_second to 0 to disable.
+//|         If the time since the last successful refresh is below the minimum frame rate, then an
+//|         exception will be raised. Set minimum_frames_per_second to 0 to disable.
 //|
-//|     When auto refresh is on, updates the display immediately. (The display will also update
-//|     without calls to this.)
+//|         When auto refresh is on, updates the display immediately. (The display will also update
+//|         without calls to this.)
 //|
-//|   :param int target_frames_per_second: How many times a second `refresh` should be called and the screen updated.
-//|   :param int minimum_frames_per_second: The minimum number of times the screen should be updated per second.
+//|         :param int target_frames_per_second: How many times a second `refresh` should be called and the screen updated.
+//|         :param int minimum_frames_per_second: The minimum number of times the screen should be updated per second."""
+//|         ...
 //|
 STATIC mp_obj_t displayio_display_obj_refresh(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
     enum { ARG_target_frames_per_second, ARG_minimum_frames_per_second };
@@ -246,9 +245,8 @@ STATIC mp_obj_t displayio_display_obj_refresh(size_t n_args, const mp_obj_t *pos
 }
 MP_DEFINE_CONST_FUN_OBJ_KW(displayio_display_refresh_obj, 1, displayio_display_obj_refresh);
 
-//|   .. attribute:: auto_refresh
-//|
-//|     True when the display is refreshed automatically.
+//|     auto_refresh: Any = ...
+//|     """True when the display is refreshed automatically."""
 //|
 STATIC mp_obj_t displayio_display_obj_get_auto_refresh(mp_obj_t self_in) {
     displayio_display_obj_t *self = native_display(self_in);
@@ -272,11 +270,10 @@ const mp_obj_property_t displayio_display_auto_refresh_obj = {
               (mp_obj_t)&mp_const_none_obj},
 };
 
-//|   .. attribute:: brightness
-//|
-//|     The brightness of the display as a float. 0.0 is off and 1.0 is full brightness. When
+//|     brightness: Any = ...
+//|     """The brightness of the display as a float. 0.0 is off and 1.0 is full brightness. When
 //|     `auto_brightness` is True, the value of `brightness` will change automatically.
-//|     If `brightness` is set, `auto_brightness` will be disabled and will be set to False.
+//|     If `brightness` is set, `auto_brightness` will be disabled and will be set to False."""
 //|
 STATIC mp_obj_t displayio_display_obj_get_brightness(mp_obj_t self_in) {
     displayio_display_obj_t *self = native_display(self_in);
@@ -310,12 +307,11 @@ const mp_obj_property_t displayio_display_brightness_obj = {
               (mp_obj_t)&mp_const_none_obj},
 };
 
-//|   .. attribute:: auto_brightness
-//|
-//|     True when the display brightness is adjusted automatically, based on an ambient
+//|     auto_brightness: Any = ...
+//|     """True when the display brightness is adjusted automatically, based on an ambient
 //|     light sensor or other method. Note that some displays may have this set to True by default,
 //|     but not actually implement automatic brightness adjustment. `auto_brightness` is set to False
-//|     if `brightness` is set manually.
+//|     if `brightness` is set manually."""
 //|
 STATIC mp_obj_t displayio_display_obj_get_auto_brightness(mp_obj_t self_in) {
     displayio_display_obj_t *self = native_display(self_in);
@@ -342,9 +338,8 @@ const mp_obj_property_t displayio_display_auto_brightness_obj = {
 
 
 
-//|   .. attribute:: width
-//|
-//|	Gets the width of the board
+//|     width: Any = ...
+//|	    Gets the width of the board
 //|
 //|
 STATIC mp_obj_t displayio_display_obj_get_width(mp_obj_t self_in) {
@@ -360,9 +355,8 @@ const mp_obj_property_t displayio_display_width_obj = {
               (mp_obj_t)&mp_const_none_obj},
 };
 
-//|   .. attribute:: height
-//|
-//|	Gets the height of the board
+//|     height: Any = ...
+//|	    """Gets the height of the board"""
 //|
 //|
 STATIC mp_obj_t displayio_display_obj_get_height(mp_obj_t self_in) {
@@ -378,9 +372,8 @@ const mp_obj_property_t displayio_display_height_obj = {
               (mp_obj_t)&mp_const_none_obj},
 };
 
-//|   .. attribute:: rotation
-//|
-//|     The rotation of the display as an int in degrees.
+//|     rotation: Any = ...
+//|     """The rotation of the display as an int in degrees."""
 //|
 STATIC mp_obj_t displayio_display_obj_get_rotation(mp_obj_t self_in) {
     displayio_display_obj_t *self = native_display(self_in);
@@ -402,9 +395,8 @@ const mp_obj_property_t displayio_display_rotation_obj = {
               (mp_obj_t)&mp_const_none_obj},
 };
 
-//|   .. attribute:: bus
-//|
-//|	The bus being used by the display
+//|     bus: Any = ...
+//|	    """The bus being used by the display"""
 //|
 //|
 STATIC mp_obj_t displayio_display_obj_get_bus(mp_obj_t self_in) {
@@ -421,12 +413,13 @@ const mp_obj_property_t displayio_display_bus_obj = {
 };
 
 
-//|   .. method:: fill_row(y, buffer)
+//|     def fill_row(self, y: int, buffer: bytearray) -> Any:
+//|         """Extract the pixels from a single row
 //|
-//|     Extract the pixels from a single row
+//|         :param int y: The top edge of the area
+//|         :param bytearray buffer: The buffer in which to place the pixel data"""
+//|         ...
 //|
-//|     :param int y: The top edge of the area
-//|     :param bytearray buffer: The buffer in which to place the pixel data
 STATIC mp_obj_t displayio_display_obj_fill_row(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
     enum { ARG_y, ARG_buffer };
     static const mp_arg_t allowed_args[] = {