implement PEP 692 type hints for BleakScanner kwargs

Most of the class methods for BleakScanner allow passing **kwargs to
the BleakScanner() constructor. PEP 692 now gives us a way to have
proper type hints for this.

CHANGELOG.rst

@@ -15,6 +15,7 @@ Added
 * Added ``bleak.uuids.normalize_uuid_16()`` function.
 * Added ``bleak.uuids.normalize_uuid_32()`` function.
 * Added ``advertisement_data()`` async iterator method to ``BleakScanner``. Merged #1361.
+* Added type hints for kwargs on ``BleakScanner`` class methods.
 
 Changed
 -------

bleak/__init__.py

@@ -26,6 +26,7 @@
     Set,
     Tuple,
     Type,
+    TypedDict,
     Union,
     overload,
 )
@@ -39,8 +40,10 @@
 
 if sys.version_info < (3, 11):
     from async_timeout import timeout as async_timeout
+    from typing_extensions import Unpack
 else:
     from asyncio import timeout as async_timeout
+    from typing import Unpack
 
 
 from .backends.characteristic import BleakGATTCharacteristic
@@ -242,6 +245,38 @@ async def advertisement_data(
         finally:
             unregister_callback()
 
+    class ExtraArgs(TypedDict):
+        """
+        Keyword args from :class:`~bleak.BleakScanner` that can be passed to
+        other convenience methods.
+        """
+
+        service_uuids: List[str]
+        """
+        Optional list of service UUIDs to filter on. Only advertisements
+        containing this advertising data will be received. Required on
+        macOS >= 12.0, < 12.3 (unless you create an app with ``py2app``).
+        """
+        scanning_mode: Literal["active", "passive"]
+        """
+        Set to ``"passive"`` to avoid the ``"active"`` scanning mode.
+        Passive scanning is not supported on macOS! Will raise
+        :class:`BleakError` if set to ``"passive"`` on macOS.
+        """
+        bluez: BlueZScannerArgs
+        """
+        Dictionary of arguments specific to the BlueZ backend.
+        """
+        cb: CBScannerArgs
+        """
+        Dictionary of arguments specific to the CoreBluetooth backend.
+        """
+        backend: Type[BaseBleakScanner]
+        """
+        Used to override the automatically selected backend (i.e. for a
+            custom backend).
+        """
+
     @overload
     @classmethod
     async def discover(
@@ -257,7 +292,9 @@ async def discover(
         ...
 
     @classmethod
-    async def discover(cls, timeout=5.0, *, return_adv=False, **kwargs):
+    async def discover(
+        cls, timeout=5.0, *, return_adv=False, **kwargs: Unpack[ExtraArgs]
+    ):
         """
         Scan continuously for ``timeout`` seconds and return discovered devices.
 
@@ -331,7 +368,7 @@ async def get_discovered_devices(self) -> List[BLEDevice]:
 
     @classmethod
     async def find_device_by_address(
-        cls, device_identifier: str, timeout: float = 10.0, **kwargs
+        cls, device_identifier: str, timeout: float = 10.0, **kwargs: Unpack[ExtraArgs]
     ) -> Optional[BLEDevice]:
         """Obtain a ``BLEDevice`` for a BLE server specified by Bluetooth address or (macOS) UUID address.
 
@@ -353,7 +390,7 @@ async def find_device_by_address(
 
     @classmethod
     async def find_device_by_name(
-        cls, name: str, timeout: float = 10.0, **kwargs
+        cls, name: str, timeout: float = 10.0, **kwargs: Unpack[ExtraArgs]
     ) -> Optional[BLEDevice]:
         """Obtain a ``BLEDevice`` for a BLE server specified by the local name in the advertising data.
 
@@ -375,7 +412,10 @@ async def find_device_by_name(
 
     @classmethod
     async def find_device_by_filter(
-        cls, filterfunc: AdvertisementDataFilter, timeout: float = 10.0, **kwargs
+        cls,
+        filterfunc: AdvertisementDataFilter,
+        timeout: float = 10.0,
+        **kwargs: Unpack[ExtraArgs],
     ) -> Optional[BLEDevice]:
         """Obtain a ``BLEDevice`` for a BLE server that matches a given filter function.
 

docs/api/scanner.rst

@@ -19,6 +19,8 @@ multiple devices.
 .. automethod:: bleak.BleakScanner.find_device_by_name
 .. automethod:: bleak.BleakScanner.find_device_by_address
 .. automethod:: bleak.BleakScanner.find_device_by_filter
+.. autoclass:: bleak.BleakScanner.ExtraArgs
+    :members:
 
 
 ---------------------