pybricks.common.BLE: Update type hints and add missing documentation

jedi/tests/test_complete_city_hub.py

@@ -82,3 +82,16 @@ def test_hub_dot_system_dot():
         "shutdown",
         "storage",
     ]
+
+
+def test_hub_dot_ble_dot():
+    line = "hub.ble."
+    code = _create_snippet(line)
+    completions: list[CompletionItem] = json.loads(complete(code, 3, len(line) + 1))
+    assert [c["insertText"] for c in completions] == [
+        "broadcast",
+        "observe",
+        "observe_enable",
+        "signal_strength",
+        "version",
+    ]

jedi/tests/test_complete_essential_hub.py

@@ -114,3 +114,16 @@ def test_hub_dot_system_dot():
         "shutdown",
         "storage",
     ]
+
+
+def test_hub_dot_ble_dot():
+    line = "hub.ble."
+    code = _create_snippet(line)
+    completions: list[CompletionItem] = json.loads(complete(code, 3, len(line) + 1))
+    assert [c["insertText"] for c in completions] == [
+        "broadcast",
+        "observe",
+        "observe_enable",
+        "signal_strength",
+        "version",
+    ]

jedi/tests/test_complete_inventor_hub.py

@@ -39,4 +39,5 @@ def _create_snippet(line: str) -> str:
     test_hub_dot_light_dot,
     test_hub_dot_speaker_dot,
     test_hub_dot_system_dot,
+    test_hub_dot_ble_dot,
 )

jedi/tests/test_complete_move_hub.py

@@ -94,3 +94,16 @@ def test_hub_dot_system_dot():
         "shutdown",
         "storage",
     ]
+
+
+def test_hub_dot_ble_dot():
+    line = "hub.ble."
+    code = _create_snippet(line)
+    completions: list[CompletionItem] = json.loads(complete(code, 3, len(line) + 1))
+    assert [c["insertText"] for c in completions] == [
+        "broadcast",
+        "observe",
+        "observe_enable",
+        "signal_strength",
+        "version",
+    ]

jedi/tests/test_complete_prime_hub.py

@@ -143,3 +143,16 @@ def test_hub_dot_system_dot():
         "shutdown",
         "storage",
     ]
+
+
+def test_hub_dot_ble_dot():
+    line = "hub.ble."
+    code = _create_snippet(line)
+    completions: list[CompletionItem] = json.loads(complete(code, 3, len(line) + 1))
+    assert [c["insertText"] for c in completions] == [
+        "broadcast",
+        "observe",
+        "observe_enable",
+        "signal_strength",
+        "version",
+    ]

jedi/tests/test_complete_technic_hub.py

@@ -102,3 +102,16 @@ def test_hub_dot_system_dot():
         "shutdown",
         "storage",
     ]
+
+
+def test_hub_dot_ble_dot():
+    line = "hub.ble."
+    code = _create_snippet(line)
+    completions: list[CompletionItem] = json.loads(complete(code, 3, len(line) + 1))
+    assert [c["insertText"] for c in completions] == [
+        "broadcast",
+        "observe",
+        "observe_enable",
+        "signal_strength",
+        "version",
+    ]

jedi/tests/test_get_signature.py

@@ -86,12 +86,22 @@ def _get_constructor_signature(module: str, type: str) -> SignatureHelp:
     pytest.param(
         "pybricks.hubs",
         "MoveHub",
-        [["broadcast_channel: int=None", "observe_channels: Sequence[int]=[]"]],
+        [
+            [
+                "broadcast_channel: Optional[int]=None",
+                "observe_channels: Sequence[int]=[]",
+            ]
+        ],
     ),
     pytest.param(
         "pybricks.hubs",
         "CityHub",
-        [["broadcast_channel: int=None", "observe_channels: Sequence[int]=[]"]],
+        [
+            [
+                "broadcast_channel: Optional[int]=None",
+                "observe_channels: Sequence[int]=[]",
+            ]
+        ],
     ),
     pytest.param(
         "pybricks.hubs",
@@ -100,7 +110,7 @@ def _get_constructor_signature(module: str, type: str) -> SignatureHelp:
             [
                 "top_side: Axis=Axis.Z",
                 "front_side: Axis=Axis.X",
-                "broadcast_channel: int=None",
+                "broadcast_channel: Optional[int]=None",
                 "observe_channels: Sequence[int]=[]",
             ]
         ],
@@ -112,7 +122,7 @@ def _get_constructor_signature(module: str, type: str) -> SignatureHelp:
             [
                 "top_side: Axis=Axis.Z",
                 "front_side: Axis=Axis.X",
-                "broadcast_channel: int=None",
+                "broadcast_channel: Optional[int]=None",
                 "observe_channels: Sequence[int]=[]",
             ]
         ],
@@ -124,7 +134,7 @@ def _get_constructor_signature(module: str, type: str) -> SignatureHelp:
             [
                 "top_side: Axis=Axis.Z",
                 "front_side: Axis=Axis.X",
-                "broadcast_channel: int=None",
+                "broadcast_channel: Optional[int]=None",
                 "observe_channels: Sequence[int]=[]",
             ]
         ],

src/pybricks/_common.py

@@ -1448,7 +1448,22 @@ class BLE:
     .. versionadded:: 3.3
     """
 
+    @overload
+    def broadcast(
+        self, data: Iterable[Union[bool, int, float, str, bytes]]
+    ) -> MaybeAwaitable:
+        ...
+
+    @overload
     def broadcast(self, data: Union[bool, int, float, str, bytes]) -> MaybeAwaitable:
+        ...
+
+    def broadcast(
+        self,
+        data: Union[
+            Iterable[Union[bool, int, float, str, bytes]], bool, int, float, str, bytes
+        ],
+    ) -> MaybeAwaitable:
         """broadcast(data)
 
         Starts broadcasting the given data on
@@ -1479,7 +1494,12 @@ def broadcast(self, data: Union[bool, int, float, str, bytes]) -> MaybeAwaitable
 
     def observe(
         self, channel: int
-    ) -> Optional[Tuple[Union[bool, int, float, str, bytes], ...]]:
+    ) -> Optional[
+        Union[
+            Tuple[Union[bool, int, float, str, bytes], ...],
+            Union[bool, int, float, str, bytes],
+        ]
+    ]:
         """observe(channel) -> bool | int | float | str | bytes | tuple | None
 
         Retrieves the last observed data for a given channel.

src/pybricks/hubs.py

@@ -3,7 +3,7 @@
 
 """LEGO® Programmable Hubs."""
 
-from typing import Sequence
+from typing import Sequence, Optional
 
 from . import _common
 from .ev3dev import _speaker
@@ -44,7 +44,9 @@ class MoveHub:
     ble = _common.BLE()
 
     def __init__(
-        self, broadcast_channel: int = None, observe_channels: Sequence[int] = []
+        self,
+        broadcast_channel: Optional[int] = None,
+        observe_channels: Sequence[int] = [],
     ):
         """MoveHub(top_side=Axis.Z, front_side=Axis.X, broadcast_channel=None, observe_channels=[])
 
@@ -78,7 +80,7 @@ class CityHub:
     ble = _common.BLE()
 
     def __init__(
-        self, broadcast_channel: int = None, observe_channels: Sequence[int] = []
+        self, broadcast_channel: Optional[int] = None, observe_channels: Sequence[int] = []
     ):
         """CityHub(broadcast_channel=None, observe_channels=[])
 
@@ -112,7 +114,7 @@ def __init__(
         self,
         top_side: Axis = Axis.Z,
         front_side: Axis = Axis.X,
-        broadcast_channel: int = None,
+        broadcast_channel: Optional[int] = None,
         observe_channels: Sequence[int] = [],
     ):
         """TechnicHub(top_side=Axis.Z, front_side=Axis.X, broadcast_channel=None, observe_channels=[])
@@ -157,7 +159,7 @@ def __init__(
         self,
         top_side: Axis = Axis.Z,
         front_side: Axis = Axis.X,
-        broadcast_channel: int = None,
+        broadcast_channel: Optional[int] = None,
         observe_channels: Sequence[int] = [],
     ):
         """EssentialHub(top_side=Axis.Z, front_side=Axis.X, broadcast_channel=None, observe_channels=[])
@@ -212,7 +214,7 @@ def __init__(
         self,
         top_side: Axis = Axis.Z,
         front_side: Axis = Axis.X,
-        broadcast_channel: int = None,
+        broadcast_channel: Optional[int] = None,
         observe_channels: Sequence[int] = [],
     ):
         """PrimeHub(top_side=Axis.Z, front_side=Axis.X, broadcast_channel=None, observe_channels=[])