Merge remote-tracking branch 'origin/main' into refine-stubs

Author: jepler

.git-blame-ignore-revs

@@ -1,3 +1,6 @@
+# tools/gen-cpydiff.py: Fix formatting of doc strings for new Black.
+0f78c36c5aa458a954eed39a46942209107a553e
+
 # tests/run-tests.py: Reformat with Black.
 2a38d7103672580882fb621a5b76e8d26805d593
 

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,63 @@
+name: 🐞 Bug Report
+description: Create a bug report to help us improve
+labels:
+  - bug
+body:
+  - type: markdown
+    attributes:
+      value: >-
+        Thanks! for testing out CircuitPython. Now that you have encountered a
+        bug... you can file a report for it.
+  - type: textarea
+    id: firmware
+    attributes:
+      label: CircuitPython version
+      description: >-
+        Include the version of CircuitPython you're running. You can see it in
+        the `boot_out.txt` file, as well as in the `REPL`.
+      placeholder: Adafruit CircuitPython 6.2.0 on 2021-03-01; Raspberry Pi Pico with rp2040
+      render: python
+    validations:
+      required: true
+  - type: textarea
+    id: code
+    attributes:
+      label: Code/REPL
+      description: This is automatically rendered as Python, so no need for backticks.
+      placeholder: |
+        import busio, bitbangio
+        i2c = bitbangio.I2C(board.GP1, board.GP0)
+      render: python
+    validations:
+      required: true
+  - type: textarea
+    id: behavior
+    attributes:
+      label: Behavior
+      description: What happens when you run the code above? Include error messages (if any).
+      placeholder: |
+        ```python
+        Traceback (most recent call last):
+          File "<stdin>", line 1, in <module>
+          TimeoutError: Clock stretch too long
+        ```
+        On-board led pulses red.
+    validations:
+      required: true
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: Optionally, describe the bug in more detail.
+      placeholder: |
+        - Error while using i2c...
+        - Only happens when...
+        - might be related to #4291...
+  - type: textarea
+    id: more-info
+    attributes:
+      label: Additional information
+      description: >-
+        Optionally, add any other information like hardware connection, scope
+        output etc. If you have already done some debugging, mention it here.
+      placeholder: Removing [this](url) line resolves the issue.

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -1,7 +1,7 @@
 contact_links:
-  - name: Adafruit Forum
+  - name: 🔗 Adafruit Forum
     url: https://forums.adafruit.com/
     about: Official Adafruit technical support forum. Good for getting help on getting a project working.
-  - name: Adafruit Discord
+  - name: 🔗 Adafruit Discord
     url: https://adafru.it/discord
     about: Unofficial chat with many helpful folks and normally prompt replies.

.github/ISSUE_TEMPLATE/config.yml

@@ -1,11 +1,11 @@
 ---
-name: Feature request
+name: 🚀 Feature Request
 about: Suggest an idea for this project
 title: ''
 labels: 'enhancement'
 assignees: ''
 
 ---
 
-<!-- We are always adding new features and enhancements to CircuitPython 🚀
+<!-- We keep adding new features and enhancements to CircuitPython 🚀
 and would love ❤ to see what new challenge you have got for us... 🙂 -->

.github/ISSUE_TEMPLATE/feature_request.md

@@ -132,8 +132,9 @@ jobs:
         TWINE_USERNAME: ${{ secrets.pypi_username }}
         TWINE_PASSWORD: ${{ secrets.pypi_password }}
       run: |
-        echo "Uploading dev release to PyPi"
-        twine upload circuitpython-stubs/dist/*
+        # setup.py sdist was run by 'make stubs'
+        if [ -z "$TWINE_USERNAME" ] || echo "Uploading dev release to PyPi"
+        if [ -z "$TWINE_USERNAME" ] || twine upload circuitpython-stubs/dist/*
 
   mpy-cross-mac:
     runs-on: macos-10.15

.github/workflows/build.yml

@@ -153,6 +153,7 @@
 [submodule "ports/esp32s2/esp-idf"]
 	path = ports/esp32s2/esp-idf
 	url = https://github.com/adafruit/esp-idf.git
+	branch = circuitpython-v4.3
 [submodule "ports/esp32s2/certificates/nina-fw"]
 	path = ports/esp32s2/certificates/nina-fw
 	url = https://github.com/adafruit/nina-fw.git

.gitmodules

@@ -417,7 +417,6 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {"cpython": ('https://docs.python.org/3/', None),
-                       "bus_device": ('https://circuitpython.readthedocs.io/projects/busdevice/en/latest/', None),
                        "register": ('https://circuitpython.readthedocs.io/projects/register/en/latest/', None)}
 
 # Adapted from sphinxcontrib-redirects

conf.py

@@ -118,7 +118,8 @@ STATIC void add_generic_services(bleio_adapter_obj_t *adapter) {
         SECURITY_MODE_NO_ACCESS,
         248,                    // max length, from Bluetooth spec
         false,                  // not fixed length
-        &generic_name_bufinfo
+        &generic_name_bufinfo,
+        NULL
         );
 
     uint16_t zero_16 = 0;
@@ -140,7 +141,8 @@ STATIC void add_generic_services(bleio_adapter_obj_t *adapter) {
         SECURITY_MODE_NO_ACCESS,
         2,                      // max length, from Bluetooth spec
         true,                  // fixed length
-        &zero_16_value
+        &zero_16_value,
+        NULL
         );
 
     // Generic Attribute Service setup.
@@ -176,7 +178,8 @@ STATIC void add_generic_services(bleio_adapter_obj_t *adapter) {
         SECURITY_MODE_NO_ACCESS,
         4,                     // max length, from Bluetooth spec
         true,                  // fixed length
-        &zero_32_value
+        &zero_32_value,
+        NULL
         );
 }
 
@@ -645,7 +648,11 @@ STATIC void check_data_fit(size_t data_len, bool connectable) {
 //     return true;
 // }
 
-uint32_t _common_hal_bleio_adapter_start_advertising(bleio_adapter_obj_t *self, bool connectable, bool anonymous, uint32_t timeout, float interval, uint8_t *advertising_data, uint16_t advertising_data_len, uint8_t *scan_response_data, uint16_t scan_response_data_len, mp_int_t tx_power) {
+uint32_t _common_hal_bleio_adapter_start_advertising(bleio_adapter_obj_t *self,
+    bool connectable, bool anonymous, uint32_t timeout, float interval,
+    const uint8_t *advertising_data, uint16_t advertising_data_len,
+    const uint8_t *scan_response_data, uint16_t scan_response_data_len,
+    mp_int_t tx_power, const bleio_address_obj_t *directed_to) {
     check_enabled(self);
 
     if (self->now_advertising) {
@@ -769,7 +776,11 @@ uint32_t _common_hal_bleio_adapter_start_advertising(bleio_adapter_obj_t *self,
     return 0;
 }
 
-void common_hal_bleio_adapter_start_advertising(bleio_adapter_obj_t *self, bool connectable, bool anonymous, uint32_t timeout, mp_float_t interval, mp_buffer_info_t *advertising_data_bufinfo, mp_buffer_info_t *scan_response_data_bufinfo, mp_int_t tx_power) {
+void common_hal_bleio_adapter_start_advertising(bleio_adapter_obj_t *self,
+    bool connectable, bool anonymous, uint32_t timeout, mp_float_t interval,
+    mp_buffer_info_t *advertising_data_bufinfo,
+    mp_buffer_info_t *scan_response_data_bufinfo,
+    mp_int_t tx_power, const bleio_address_obj_t *directed_to) {
     check_enabled(self);
 
     // interval value has already been validated.
@@ -803,7 +814,7 @@ void common_hal_bleio_adapter_start_advertising(bleio_adapter_obj_t *self, bool
         advertising_data_bufinfo->len,
         scan_response_data_bufinfo->buf,
         scan_response_data_bufinfo->len,
-        tx_power);
+        tx_power, directed_to);
 
     if (result) {
         mp_raise_bleio_BluetoothError(translate("Already advertising"));

devices/ble_hci/common-hal/_bleio/Adapter.c

@@ -41,7 +41,7 @@
 #define CCCD_INDICATE 0x2
 
 
-void common_hal_bleio_characteristic_construct(bleio_characteristic_obj_t *self, bleio_service_obj_t *service, uint16_t handle, bleio_uuid_obj_t *uuid, bleio_characteristic_properties_t props, bleio_attribute_security_mode_t read_perm, bleio_attribute_security_mode_t write_perm, mp_int_t max_length, bool fixed_length, mp_buffer_info_t *initial_value_bufinfo) {
+void common_hal_bleio_characteristic_construct(bleio_characteristic_obj_t *self, bleio_service_obj_t *service, uint16_t handle, bleio_uuid_obj_t *uuid, bleio_characteristic_properties_t props, bleio_attribute_security_mode_t read_perm, bleio_attribute_security_mode_t write_perm, mp_int_t max_length, bool fixed_length, mp_buffer_info_t *initial_value_bufinfo, const char *user_description) {
     self->service = service;
     self->uuid = uuid;
     self->decl_handle = BLE_GATT_HANDLE_INVALID;
@@ -66,7 +66,7 @@ void common_hal_bleio_characteristic_construct(bleio_characteristic_obj_t *self,
     if (service->is_remote) {
         self->handle = handle;
     } else {
-        common_hal_bleio_service_add_characteristic(self->service, self, initial_value_bufinfo);
+        common_hal_bleio_service_add_characteristic(self->service, self, initial_value_bufinfo, user_description);
     }
 }
 

devices/ble_hci/common-hal/_bleio/Characteristic.c

@@ -148,7 +148,8 @@ mp_int_t common_hal_bleio_packet_buffer_readinto(bleio_packet_buffer_obj_t *self
     return ret;
 }
 
-mp_int_t common_hal_bleio_packet_buffer_write(bleio_packet_buffer_obj_t *self, uint8_t *data, size_t len, uint8_t *header, size_t header_len) {
+mp_int_t common_hal_bleio_packet_buffer_write(bleio_packet_buffer_obj_t *self,
+    const uint8_t *data, size_t len, uint8_t *header, size_t header_len) {
     if (self->outgoing[0] == NULL) {
         mp_raise_bleio_BluetoothError(translate("Writes not supported on Characteristic"));
     }

devices/ble_hci/common-hal/_bleio/PacketBuffer.c

@@ -84,7 +84,8 @@ bool common_hal_bleio_service_get_is_secondary(bleio_service_obj_t *self) {
 
 void common_hal_bleio_service_add_characteristic(bleio_service_obj_t *self,
     bleio_characteristic_obj_t *characteristic,
-    mp_buffer_info_t *initial_value_bufinfo) {
+    mp_buffer_info_t *initial_value_bufinfo,
+    const char *user_description) {
 
     if (self->handle != common_hal_bleio_adapter_obj.last_added_service_handle) {
         mp_raise_bleio_BluetoothError(

devices/ble_hci/common-hal/_bleio/Service.c

@@ -36,7 +36,7 @@
 #include "shared-bindings/_bleio/Descriptor.h"
 #include "shared-bindings/_bleio/Service.h"
 #include "shared-bindings/_bleio/UUID.h"
-#include "supervisor/shared/bluetooth.h"
+#include "supervisor/shared/bluetooth/bluetooth.h"
 
 // UUID shared by all cccd's.
 bleio_uuid_obj_t cccd_uuid;

devices/ble_hci/common-hal/_bleio/__init__.c

@@ -182,10 +182,6 @@ Exceptions
 
 .. exception:: OSError
 
-    |see_cpython| :py:class:`cpython:OSError`. CircuitPython doesn't implement the ``errno``
-    attribute, instead use the standard way to access exception arguments:
-    ``exc.args[0]``.
-
 .. exception:: RuntimeError
 
 .. exception:: ReloadException

docs/library/builtins.rst

@@ -214,6 +214,14 @@ TCP stream connections
 
     This is a coroutine.
 
+.. method:: Stream.readinto(buf)
+
+    Read up to n bytes into *buf* with n being equal to the length of *buf*.
+
+    Return the number of bytes read into *buf*.
+
+    This is a coroutine, and a MicroPython extension.
+
 .. method:: Stream.readline()
 
     Read a line and return it.

docs/library/uasyncio.rst

@@ -247,7 +247,7 @@ Module contents
 
 .. data:: VOID
 
-   ``VOID`` is an alias for ``UINT8``, and is provided to conviniently define
+   ``VOID`` is an alias for ``UINT8``, and is provided to conveniently define
    C's void pointers: ``(uctypes.PTR, uctypes.VOID)``.
 
 .. data:: PTR

docs/library/uctypes.rst

@@ -8,9 +8,11 @@
 
 |see_cpython_module| :mod:`cpython:heapq`.
 
-This module implements the heap queue algorithm.
+This module implements the
+`min heap queue algorithm <https://en.wikipedia.org/wiki/Heap_%28data_structure%29>`_.
 
-A heap queue is simply a list that has its elements stored in a certain way.
+A heap queue is essentially a list that has its elements stored in such a way
+that the first item of the list is always the smallest.
 
 Functions
 ---------
@@ -21,8 +23,10 @@ Functions
 
 .. function:: heappop(heap)
 
-   Pop the first item from the ``heap``, and return it.  Raises IndexError if
-   heap is empty.
+   Pop the first item from the ``heap``, and return it.  Raise ``IndexError`` if
+   ``heap`` is empty.
+
+   The returned item will be the smallest item in the ``heap``.
 
 .. function:: heapify(x)
 

docs/library/uheapq.rst

@@ -89,11 +89,11 @@ Methods
    ``callee-owned tuples``. This function provides efficient, allocation-free
    way to poll on streams.
 
-   If *flags* is 1, one-shot behavior for events is employed: streams for
+   If *flags* is 1, one-shot behaviour for events is employed: streams for
    which events happened will have their event masks automatically reset
    (equivalent to ``poll.modify(obj, 0)``), so new events for such a stream
    won't be processed until new mask is set with `poll.modify()`. This
-   behavior is useful for asynchronous I/O schedulers.
+   behaviour is useful for asynchronous I/O schedulers.
 
    .. admonition:: Difference to CPython
       :class: attention