Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
8bb3089
pybricks.common.BLE: Improve typing for hub constructor.
fkleon Jun 24, 2025
66b4245
pybricks.common.BLE: Improve typing for broadcast() and observe()
fkleon Jun 24, 2025
3850353
pybricks.common.BLE: Document bluetooth_enable() method.
fkleon Jun 24, 2025
a53f371
jedi: Add tests for methods on hub.ble.
fkleon Jun 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions jedi/tests/test_complete_city_hub.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Comment on lines +92 to +94
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A couple of these aren't in the docs, so I'm not sure they are meant to be public.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

observe_enable() was undocumented, but mentioned in the release changelog. I could extract that into a separate MR if you'd rather not add it to the public docs.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's wait and see what @laurensvalk says.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ping @laurensvalk

"signal_strength",
"version",
]
13 changes: 13 additions & 0 deletions jedi/tests/test_complete_essential_hub.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
]
1 change: 1 addition & 0 deletions jedi/tests/test_complete_inventor_hub.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
)
13 changes: 13 additions & 0 deletions jedi/tests/test_complete_move_hub.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
]
13 changes: 13 additions & 0 deletions jedi/tests/test_complete_prime_hub.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
]
13 changes: 13 additions & 0 deletions jedi/tests/test_complete_technic_hub.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
]
20 changes: 15 additions & 5 deletions jedi/tests/test_get_signature.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand All @@ -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]=[]",
]
],
Expand All @@ -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]=[]",
]
],
Expand All @@ -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]=[]",
]
],
Expand Down
33 changes: 32 additions & 1 deletion src/pybricks/_common.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand All @@ -1497,6 +1517,17 @@ def observe(
.. versionadded:: 3.3
"""

def observe_enable(self, enable: bool) -> MaybeAwaitable:
"""observe_enable(enable)

Enables or disable observing (on by default).

Args:
enable: True to enable, false to disable observing.

.. versionadded:: 3.6
"""

def signal_strength(self, channel: int) -> int:
"""signal_strength(channel) -> int: dBm

Expand Down
14 changes: 8 additions & 6 deletions src/pybricks/hubs.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@

"""LEGO® Programmable Hubs."""

from typing import Sequence
from typing import Sequence, Optional

from . import _common
from .ev3dev import _speaker
Expand Down Expand Up @@ -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=[])

Expand Down Expand Up @@ -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=[])

Expand Down Expand Up @@ -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=[])
Expand Down Expand Up @@ -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=[])
Expand Down Expand Up @@ -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=[])
Expand Down