Merge pull request #1081 from hbldh/release/0.19.0

Release/0.19.0

.github/ISSUE_TEMPLATE.md

@@ -20,3 +20,13 @@ reproduced with other BLE peripherals as well.
 Paste the command(s) you ran and the output.
 If there was a crash, please include the traceback here as well.
 ```
+
+### Logs
+
+Include any relevant logs here.
+
+Logs are essential to understand what is going on behind the scenes.
+
+See https://bleak.readthedocs.io/en/latest/troubleshooting.html for information on how to collect debug logs.
+
+If you receive an OS error (`WinError`, `BleakDBusError`, `NSError`, etc.), Wireshark logs of Bluetooth packets are required to understand the issue!

.github/workflows/build_and_test.yml

@@ -13,7 +13,7 @@ jobs:
         strategy:
             matrix:
                 os: [ubuntu-latest, windows-latest, macos-latest]
-                python-version: ['3.7', '3.8', '3.9', '3.10']
+                python-version: ['3.7', '3.8', '3.9', '3.10', '3.11.0-rc.2']
         steps:
             -   uses: actions/checkout@v2
             -   name: Set up Python ${{ matrix.python-version }}

CHANGELOG.rst

@@ -10,6 +10,36 @@ and this project adheres to `Semantic Versioning <https://semver.org/spec/v2.0.0
 `Unreleased`_
 =============
 
+`0.19.0`_ (2022-10-13)
+======================
+
+Added
+-----
+* Added support for Python 3.11. Merged #990.
+* Added better error message for Bluetooth not authorized on macOS. Merged #1033.
+* Added ``BleakDeviceNotFoundError`` which should is raised if a device can not
+  be found by ``connect``, ``pair`` and ``unpair``. Merged #1022.
+* Added ``rssi`` attribute to ``AdvertisementData``. Merged #1047.
+* Added ``BleakScanner.discovered_devices_and_advertisement_data`` property. Merged #1047.
+* Added ``return_adv`` argument to ``BleakScanner.discover`` method. Merged #1047.
+* Added ``BleakClient.unpair()`` implementation for BlueZ backend. Merged #1067.
+
+Changed
+-------
+* Changed ``AdvertisementData`` to a named tuple. Merged #1047.
+* A faster ``unpack_variants`` is now provided by dbus-fast. Merged #1055.
+
+Fixed
+-----
+* On BlueZ, support creating additional instances running on a different event
+  loops (i.e. multiple pytest-asyncio cases). Merged #1034.
+* Fixed unhandled exception in ``max_pdu_size_changed_handler`` in WinRT backend. Fixes #1039.
+* Fixed stale services in WinRT backend causing ``WinError -2147483629``. Fixes #1061.
+
+Removed
+-------
+Removed ``bleak.__version__``. Use ``importlib.metadata.version('bleak')`` instead.
+
 `0.18.1`_ (2022-09-25)
 ======================
 
@@ -56,7 +86,7 @@ Changed
   argument to avoid services being resolved again. Merged #923.
 * The BlueZ D-Bus backend now uses ``dbus-fast`` package instead of ``dbus-next`` which significantly improves performance. Merged #988.
 * The BlueZ D-Bus backend will not avoid trying to connect to devices that are already connected. Fixes #992.
-* Updated logging to lazy version and replaced format by f-string for BleakClientWinRT. #1000.
+* Updated logging to lazy version and replaced format by f-string for ``BleakClientWinRT``. #1000.
 * Added deprecation warning to ``discover()`` method. Merged #1005.
 * BlueZ adapter is chosen dynamically if not provided, instead of using hardcoded "hci0". Fixes #513.
 
@@ -90,7 +120,7 @@ Fixed
 Changed
 -------
 * Made BlueZ D-Bus signal callback logging lazy to improve performance. Merged #912.
-* Switch to using async_timeout instead of asyncio.wait_for for performance. Merged #916.
+* Switch to using ``async_timeout`` instead of ``asyncio.wait_for for performance``. Merged #916.
 * Improved performance of ``BlueZManager.get_services()``. Fixes #927.
 
 Removed
@@ -811,7 +841,8 @@ Fixed
 * Bleak created.
 
 
-.. _Unreleased: https://github.com/hbldh/bleak/compare/v0.18.1...develop
+.. _Unreleased: https://github.com/hbldh/bleak/compare/v0.19.0...develop
+.. _0.19.0: https://github.com/hbldh/bleak/compare/v0.18.1...v0.19.0
 .. _0.18.1: https://github.com/hbldh/bleak/compare/v0.18.0...v0.18.1
 .. _0.18.0: https://github.com/hbldh/bleak/compare/v0.17.0...v0.18.0
 .. _0.17.0: https://github.com/hbldh/bleak/compare/v0.16.0...v0.17.0

bleak/__init__.py

@@ -14,7 +14,18 @@
 import os
 import sys
 import uuid
-from typing import TYPE_CHECKING, Awaitable, Callable, List, Optional, Type, Union
+from typing import (
+    TYPE_CHECKING,
+    Awaitable,
+    Callable,
+    Dict,
+    List,
+    Optional,
+    Tuple,
+    Type,
+    Union,
+    overload,
+)
 from warnings import warn
 
 import async_timeout
@@ -24,7 +35,6 @@
 else:
     from typing import Literal
 
-from .__version__ import __version__  # noqa: F401
 from .backends.characteristic import BleakGATTCharacteristic
 from .backends.client import BaseBleakClient, get_platform_client_backend_type
 from .backends.device import BLEDevice
@@ -58,6 +68,13 @@ class BleakScanner:
     """
     Interface for Bleak Bluetooth LE Scanners.
 
+    The scanner will listen for BLE advertisements, optionally filtering on advertised services or
+    other conditions, and collect a list of :class:`BLEDevice` objects. These can subsequently be used to
+    connect to the corresponding BLE server.
+
+    A :class:`BleakScanner` can be used as an asynchronous context manager in which case it automatically
+    starts and stops scanning.
+
     Args:
         detection_callback:
             Optional function that will be called each time a device is
@@ -77,6 +94,14 @@ class BleakScanner:
             custom backend).
         **kwargs:
             Additional args for backwards compatibility.
+
+    .. versionchanged:: 0.15.0
+        ``detection_callback``, ``service_uuids`` and ``scanning_mode`` are no longer keyword-only.
+        Added ``bluez`` parameter.
+
+    .. versionchanged:: 0.18.0
+        No longer is alias for backend type and no longer inherits from :class:`BaseBleakScanner`.
+        Added ``backend`` parameter.
     """
 
     def __init__(
@@ -153,34 +178,74 @@ def set_scanning_filter(self, **kwargs):
         )
         self._backend.set_scanning_filter(**kwargs)
 
+    @overload
+    @classmethod
+    async def discover(
+        cls, timeout: float = 5.0, *, return_adv: Literal[False] = False, **kwargs
+    ) -> List[BLEDevice]:
+        ...
+
+    @overload
+    @classmethod
+    async def discover(
+        cls, timeout: float = 5.0, *, return_adv: Literal[True], **kwargs
+    ) -> Dict[str, Tuple[BLEDevice, AdvertisementData]]:
+        ...
+
     @classmethod
-    async def discover(cls, timeout=5.0, **kwargs) -> List[BLEDevice]:
+    async def discover(cls, timeout=5.0, *, return_adv=False, **kwargs):
         """
         Scan continuously for ``timeout`` seconds and return discovered devices.
 
         Args:
             timeout:
                 Time, in seconds, to scan for.
+            return_adv:
+                If ``True``, the return value will include advertising data.
             **kwargs:
                 Additional arguments will be passed to the :class:`BleakScanner`
                 constructor.
 
         Returns:
+            The value of :attr:`discovered_devices_and_advertisement_data` if
+            ``return_adv`` is ``True``, otherwise the value of :attr:`discovered_devices`.
 
+        .. versionchanged:: 0.19.0
+            Added ``return_adv`` parameter.
         """
         async with cls(**kwargs) as scanner:
             await asyncio.sleep(timeout)
-            devices = scanner.discovered_devices
-        return devices
+
+        if return_adv:
+            return scanner.discovered_devices_and_advertisement_data
+
+        return scanner.discovered_devices
 
     @property
     def discovered_devices(self) -> List[BLEDevice]:
-        """Gets the devices registered by the BleakScanner.
+        """
+        Gets list of the devices that the scanner has discovered during the scanning.
 
-        Returns:
-            A list of the devices that the scanner has discovered during the scanning.
+        If you also need advertisement data, use :attr:`discovered_devices_and_advertisement_data` instead.
+        """
+        return [d for d, _ in self._backend.seen_devices.values()]
+
+    @property
+    def discovered_devices_and_advertisement_data(
+        self,
+    ) -> Dict[str, Tuple[BLEDevice, AdvertisementData]]:
+        """
+        Gets a map of device address to tuples of devices and the most recently
+        received advertisement data for that device.
+
+        The address keys are useful to compare the discovered devices to a set
+        of known devices. If you don't need to do that, consider using
+        ``discovered_devices_and_advertisement_data.values()`` to just get the
+        values instead.
+
+        .. versionadded:: 0.19.0
         """
-        return self._backend.discovered_devices
+        return self._backend.seen_devices
 
     async def get_discovered_devices(self) -> List[BLEDevice]:
         """Gets the devices registered by the BleakScanner.
@@ -204,7 +269,7 @@ async def get_discovered_devices(self) -> List[BLEDevice]:
     async def find_device_by_address(
         cls, device_identifier: str, timeout: float = 10.0, **kwargs
     ) -> Optional[BLEDevice]:
-        """A convenience method for obtaining a ``BLEDevice`` object specified by Bluetooth address or (macOS) UUID address.
+        """Obtain a ``BLEDevice`` for a BLE server specified by Bluetooth address or (macOS) UUID address.
 
         Args:
             device_identifier (str): The Bluetooth/UUID address of the Bluetooth peripheral sought.
@@ -228,9 +293,10 @@ async def find_device_by_address(
     async def find_device_by_filter(
         cls, filterfunc: AdvertisementDataFilter, timeout: float = 10.0, **kwargs
     ) -> Optional[BLEDevice]:
-        """
-        A convenience method for obtaining a ``BLEDevice`` object specified by
-        a filter function.
+        """Obtain a ``BLEDevice`` for a BLE server that matches a given filter function.
+
+        This can be used to find a BLE server by other identifying information than its address,
+        for example its name.
 
         Args:
             filterfunc:
@@ -263,7 +329,13 @@ def apply_filter(d: BLEDevice, ad: AdvertisementData):
 
 
 class BleakClient:
-    """The Client Interface for Bleak Backend implementations to implement.
+    """The Client interface for connecting to a specific BLE GATT server and communicating with it.
+
+    A BleakClient can be used as an asynchronous context manager in which case it automatically
+    connects and disconnects.
+
+    How many BLE connections can be active simultaneously, and whether connections can be active while
+    scanning depends on the Bluetooth adapter hardware.
 
     Args:
         address_or_ble_device:
@@ -296,6 +368,13 @@ class BleakClient:
             the :meth:`connect` method to implicitly call :meth:`BleakScanner.discover`.
             This is known to cause problems when trying to connect to multiple
             devices at the same time.
+
+    .. versionchanged:: 0.15.0
+        ``disconnected_callback`` is no longer keyword-only. Added ``winrt`` parameter.
+
+    .. versionchanged:: 0.18.0
+        No longer is alias for backend type and no longer inherits from :class:`BaseBleakClient`.
+        Added ``backend`` parameter.
     """
 
     def __init__(
@@ -402,7 +481,12 @@ async def disconnect(self) -> bool:
 
     async def pair(self, *args, **kwargs) -> bool:
         """
-        Pair with the peripheral.
+        Pair with the specified GATT server.
+
+        This method is not available on macOS. Instead of manually initiating
+        paring, the user will be prompted to pair the device the first time
+        that a characteristic that requires authentication is read or written.
+        This method may have backend-specific additional keyword arguments.
 
         Returns:
             Always returns ``True`` for backwards compatibility.
@@ -412,7 +496,12 @@ async def pair(self, *args, **kwargs) -> bool:
 
     async def unpair(self) -> bool:
         """
-        Unpair with the peripheral.
+        Unpair from the specified GATT server.
+
+        Unpairing will also disconnect the device.
+
+        This method is only available on Windows and Linux and will raise an
+        exception on other platforms.
 
         Returns:
             Always returns ``True`` for backwards compatibility.
@@ -422,7 +511,7 @@ async def unpair(self) -> bool:
     @property
     def is_connected(self) -> bool:
         """
-        Check connection status between this client and the server.
+        Check connection status between this client and the GATT server.
 
         Returns:
             Boolean representing connection status.
@@ -533,6 +622,10 @@ def callback(sender: int, data: bytearray):
                 The function to be called on notification. Can be regular
                 function or async function.
 
+
+        .. versionchanged:: 0.18.0
+            The first argument of the callback is now a :class:`BleakGATTCharacteristic`
+            instead of an ``int``.
         """
         if not self.is_connected:
             raise BleakError("Not connected")
@@ -603,7 +696,7 @@ async def write_gatt_descriptor(
 
 
 # for backward compatibility
-def discover():
+def discover(*args, **kwargs):
     """
     .. deprecated:: 0.17.0
         This method will be removed in a future version of Bleak.
@@ -614,7 +707,7 @@ def discover():
         FutureWarning,
         stacklevel=2,
     )
-    return BleakScanner.discover()
+    return BleakScanner.discover(*args, **kwargs)
 
 
 def cli():

bleak/assigned_numbers.py

@@ -16,6 +16,8 @@ class AdvertisementDataType(IntEnum):
     Generic Access Profile advertisement data types.
 
     `Source <https://btprodspecificationrefs.blob.core.windows.net/assigned-numbers/Assigned%20Number%20Types/Generic%20Access%20Profile.pdf>`.
+
+    .. versionadded:: 0.15.0
     """
 
     FLAGS = 0x01