BleakScanner: Add async iterator scanning capability (hbldh#1361)

Add `advertisement_data()` async iterator method to the `BleakScanner`
which yields results of the ongoing scan.

CHANGELOG.rst

@@ -22,6 +22,8 @@ Changed
 * Scanner backends modified to allow multiple advertisement callbacks. Merged #1367.
 * Changed default handling of the ``response`` argument in ``BleakClient.write_gatt_char``.
   Fixes #909.
+* Added ``advertisement_data()`` async iterator method to ``BleakScanner``. Merged #1361.
+* Added ``scan_iterator.py`` example.
 
 Fixed
 -----

bleak/__init__.py

@@ -16,6 +16,7 @@
 import uuid
 from typing import (
     TYPE_CHECKING,
+    AsyncGenerator,
     Awaitable,
     Callable,
     Dict,
@@ -214,6 +215,31 @@ def set_scanning_filter(self, **kwargs):
         )
         self._backend.set_scanning_filter(**kwargs)
 
+    async def advertisement_data(
+        self,
+    ) -> AsyncGenerator[Tuple[BLEDevice, AdvertisementData], None]:
+        """
+        Yields devices and associated advertising data packets as they are discovered.
+
+        .. note::
+            Ensure that scanning is started before calling this method.
+
+        Returns:
+            An async iterator that yields tuples (:class:`BLEDevice`, :class:`AdvertisementData`).
+
+        .. versionadded:: 0.21
+        """
+        devices = asyncio.Queue()
+
+        unregister_callback = self._backend.register_detection_callback(
+            lambda bd, ad: devices.put_nowait((bd, ad))
+        )
+        try:
+            while True:
+                yield await devices.get()
+        finally:
+            unregister_callback()
+
     @overload
     @classmethod
     async def discover(
@@ -370,16 +396,12 @@ async def find_device_by_filter(
             the timeout.
 
         """
-        found_device_queue: asyncio.Queue[BLEDevice] = asyncio.Queue()
-
-        def apply_filter(d: BLEDevice, ad: AdvertisementData):
-            if filterfunc(d, ad):
-                found_device_queue.put_nowait(d)
-
-        async with cls(detection_callback=apply_filter, **kwargs):
+        async with cls(**kwargs) as scanner:
             try:
                 async with async_timeout(timeout):
-                    return await found_device_queue.get()
+                    async for bd, ad in scanner.advertisement_data():
+                        if filterfunc(bd, ad):
+                            return bd
             except asyncio.TimeoutError:
                 return None
 

docs/api/scanner.rst

@@ -62,13 +62,19 @@ following methods:
 Getting discovered devices and advertisement data
 -------------------------------------------------
 
-If you aren't using the "easy" class methods, there are two ways to get the
+If you aren't using the "easy" class methods, there are three ways to get the
 discovered devices and advertisement data.
 
 For event-driven programming, you can provide a ``detection_callback`` callback
 to the :class:`BleakScanner` constructor. This will be called back each time
 and advertisement is received.
 
+Alternatively, you can utilize the asynchronous iterator to iterate over
+advertisements as they are received. The method below returns an async iterator
+that yields the same tuples as otherwise provided to ``detection_callback``.
+
+.. automethod:: bleak.BleakScanner.advertisement_data
+
 Otherwise, you can use one of the properties below after scanning has stopped.
 
 .. autoproperty:: bleak.BleakScanner.discovered_devices

examples/scan_iterator.py

@@ -0,0 +1,37 @@
+"""
+Scan/Discovery Async Iterator
+--------------
+
+Example showing how to scan for BLE devices using async iterator instead of callback function
+
+Created on 2023-07-07 by bojanpotocnik <[email protected]>
+
+"""
+import asyncio
+
+from bleak import BleakScanner
+
+
+async def main():
+    async with BleakScanner() as scanner:
+        print("Scanning...")
+
+        n = 5
+        print(f"\n{n} advertisement packets:")
+        async for bd, ad in scanner.advertisement_data():
+            print(f" {n}. {bd!r} with {ad!r}")
+            n -= 1
+            if n == 0:
+                break
+
+        n = 10
+        print(f"\nFind device with name longer than {n} characters...")
+        async for bd, ad in scanner.advertisement_data():
+            found = len(bd.name or "") > n or len(ad.local_name or "") > n
+            print(f" Found{' it' if found else ''} {bd!r} with {ad!r}")
+            if found:
+                break
+
+
+if __name__ == "__main__":
+    asyncio.run(main())