BleakClient: Add pairing_callbacks parameter to constructor

Author: bojanpotocnik

bleak/__init__.py

@@ -349,6 +349,13 @@ class BleakClient:
             Callback that will be scheduled in the event loop when the client is
             disconnected. The callable must take one argument, which will be
             this client object.
+        pairing_callbacks:
+            Optional callbacks used in the pairing process (e.g. displaying,
+            confirming, requesting pin). If provided here instead of to the
+            :meth:`pair` method as ``callbacks`` parameter, device will be
+            implicitly paired during connection establishment. This is useful
+            for devices sending Slave Security Request immediately after
+            connection, requiring pairing before GATT service discovery.
         timeout:
             Timeout in seconds passed to the implicit ``discover`` call when
             ``address_or_ble_device`` is not a :class:`BLEDevice`. Defaults to 10.0.
@@ -385,6 +392,7 @@ def __init__(
         self,
         address_or_ble_device: Union[BLEDevice, str],
         disconnected_callback: Optional[Callable[[BleakClient], None]] = None,
+        pairing_callbacks: Optional[BaseBleakAgentCallbacks] = None,
         *,
         timeout: float = 10.0,
         winrt: WinRTClientArgs = {},
@@ -398,6 +406,7 @@ def __init__(
         self._backend = PlatformBleakClient(
             address_or_ble_device,
             disconnected_callback=disconnected_callback,
+            pairing_callbacks=pairing_callbacks,
             timeout=timeout,
             winrt=winrt,
             **kwargs,
@@ -507,9 +516,10 @@ async def pair(
 
         Args:
             callbacks:
-                Optional callbacks for confirming or requesting pin. This is
-                only supported on Linux and Windows. If omitted, the OS will
-                handle the pairing request.
+                Optional callbacks used in the pairing process (e.g. displaying,
+                confirming, requesting pin).
+                This is only supported on Linux and Windows.
+                If omitted, the OS will handle the pairing request.
 
         Returns:
             Always returns ``True`` for backwards compatibility.

bleak/backends/bluezdbus/client.py

@@ -96,6 +96,13 @@ def __init__(self, address_or_ble_device: Union[BLEDevice, str], **kwargs):
         # used to override mtu_size property
         self._mtu_size: Optional[int] = None
 
+        if kwargs.get("pairing_callbacks"):
+            warnings.warn(
+                "Pairing on connect not yet implemented for BlueZ",
+                RuntimeWarning,
+                stacklevel=2,
+            )
+
     def close(self):
         self._bus.disconnect()
 

bleak/backends/client.py

@@ -35,6 +35,10 @@ class BaseBleakClient(abc.ABC):
         disconnected_callback (callable): Callback that will be scheduled in the
             event loop when the client is disconnected. The callable must take one
             argument, which will be this client object.
+        pairing_callbacks (BaseBleakAgentCallbacks):
+            Optional callbacks otherwise provided as ``callbacks`` parameter to the
+            :meth:`pair` method. If provided here, device will be implicitly paired
+            during connection establishment.
     """
 
     def __init__(self, address_or_ble_device: Union[BLEDevice, str], **kwargs):

bleak/backends/corebluetooth/client.py

@@ -6,6 +6,7 @@
 import asyncio
 import logging
 import uuid
+import warnings
 from typing import Optional, Union
 
 from CoreBluetooth import (
@@ -52,6 +53,13 @@ def __init__(self, address_or_ble_device: Union[BLEDevice, str], **kwargs):
         self._delegate: Optional[PeripheralDelegate] = None
         self._central_manager_delegate: Optional[CentralManagerDelegate] = None
 
+        if kwargs.get("pairing_callbacks"):
+            warnings.warn(
+                "Pairing is not available in Core Bluetooth.",
+                RuntimeWarning,
+                stacklevel=2,
+            )
+
         if isinstance(address_or_ble_device, BLEDevice):
             (
                 self._peripheral,

bleak/backends/p4android/client.py

@@ -45,6 +45,11 @@ def __init__(self, address_or_ble_device: Union[BLEDevice, str], **kwargs):
         self.__gatt = None
         self.__mtu = 23
 
+        if kwargs.get("pairing_callbacks"):
+            warnings.warn(
+                "pairing_callbacks are ignored on Android", RuntimeWarning, stacklevel=2
+            )
+
     def __del__(self):
         if self.__gatt is not None:
             self.__gatt.close()

bleak/backends/winrt/client.py

@@ -204,6 +204,13 @@ def __init__(
         self._session_status_changed_token: Optional[EventRegistrationToken] = None
         self._max_pdu_size_changed_token: Optional[EventRegistrationToken] = None
 
+        if kwargs.get("pairing_callbacks"):
+            warnings.warn(
+                "pairing_callbacks not yet implemented for Windows",
+                RuntimeWarning,
+                stacklevel=2,
+            )
+
     def __str__(self):
         return f"{type(self).__name__} ({self.address})"