bleak: raise BleakBluetoothNotAvailableError from BleakAdapter.get() on Linux and Windows

CoreBluetooth already raises BleakBluetoothNotAvailableError from
BleakAdapter.get() via wait_until_ready() when Bluetooth is not powered
on. This makes the BlueZ and WinRT backends do the same, so callers can
rely on the exception across all platforms.

- BlueZ: checks for adapter presence in the manager's cached properties
  and the Powered property; raises NO_BLUETOOTH or POWERED_OFF.
- WinRT: fetches the Bluetooth radio via Radio.get_radios_async() and
  checks RadioState; raises NO_BLUETOOTH or POWERED_OFF.

Author: Kirill Rudovski

CHANGELOG.rst

@@ -14,6 +14,10 @@ Added
 -----
 * Added ``BleakAdapter`` class with ``get_connected_devices()`` to retrieve BLE devices that are already connected to the system without scanning.
 
+Changed
+-------
+* Changed ``BleakAdapter.get()`` to raise ``BleakBluetoothNotAvailableError`` on Linux and Windows when the local Bluetooth adapter is not powered on, matching the existing CoreBluetooth behaviour.
+
 Fixed
 -----
 * Fixed handling empty notification payloads in BlueZ backend when using "AcquireNotify". Fixes #1982.

bleak/backends/bluezdbus/adapter.py

@@ -10,8 +10,10 @@
 from bleak._compat import Self, override
 from bleak.args.bluez import BlueZAdapterArgs
 from bleak.backends.adapter import BaseBleakAdapter
+from bleak.backends.bluezdbus import defs
 from bleak.backends.bluezdbus.manager import get_global_bluez_manager
 from bleak.backends.device import BLEDevice
+from bleak.exc import BleakBluetoothNotAvailableError, BleakBluetoothNotAvailableReason
 
 
 class BleakAdapterBlueZDBus(BaseBleakAdapter):
@@ -28,6 +30,21 @@ async def get(cls, *, bluez: BlueZAdapterArgs = {}, **kwargs: Any) -> Self:
         adapter_path = (
             f"/org/bluez/{adapter}" if adapter else manager.get_default_adapter()
         )
+
+        adapter_props = manager._properties.get(  # pyright: ignore[reportPrivateUsage]
+            adapter_path, {}
+        ).get(defs.ADAPTER_INTERFACE)
+        if adapter_props is None:
+            raise BleakBluetoothNotAvailableError(
+                f"Bluetooth adapter '{adapter_path}' is unavailable",
+                BleakBluetoothNotAvailableReason.NO_BLUETOOTH,
+            )
+        if not adapter_props.get("Powered"):
+            raise BleakBluetoothNotAvailableError(
+                "Bluetooth adapter is not powered on",
+                BleakBluetoothNotAvailableReason.POWERED_OFF,
+            )
+
         return cls(adapter_path)
 
     @override

bleak/backends/winrt/adapter.py

@@ -16,11 +16,13 @@
 )
 from winrt.windows.devices.bluetooth.genericattributeprofile import GattDeviceService
 from winrt.windows.devices.enumeration import DeviceInformation
+from winrt.windows.devices.radios import Radio, RadioKind, RadioState
 
 from bleak._compat import Self, override
 from bleak.backends.adapter import BaseBleakAdapter
 from bleak.backends.device import BLEDevice
 from bleak.backends.winrt.util import assert_mta
+from bleak.exc import BleakBluetoothNotAvailableError, BleakBluetoothNotAvailableReason
 from bleak.uuids import normalize_uuid_16
 
 
@@ -31,6 +33,23 @@ class BleakAdapterWinRT(BaseBleakAdapter):
     @override
     async def get(cls, **kwargs: Any) -> Self:
         await assert_mta()
+
+        radio = None
+        for candidate in await Radio.get_radios_async():
+            if candidate.kind == RadioKind.BLUETOOTH:
+                radio = candidate
+                break
+        if radio is None:
+            raise BleakBluetoothNotAvailableError(
+                "No Bluetooth radio available",
+                BleakBluetoothNotAvailableReason.NO_BLUETOOTH,
+            )
+        if radio.state != RadioState.ON:
+            raise BleakBluetoothNotAvailableError(
+                "Bluetooth adapter is not powered on",
+                BleakBluetoothNotAvailableReason.POWERED_OFF,
+            )
+
         return cls()
 
     @override

docs/api/adapter.rst

@@ -26,6 +26,10 @@ On Linux, a specific adapter can be selected via the ``bluez`` argument::
 
     adapter = await BleakAdapter.get(bluez={"adapter": "hci1"})
 
+:meth:`BleakAdapter.get` raises :class:`~bleak.exc.BleakBluetoothNotAvailableError`
+if the local Bluetooth adapter is not currently powered on or is otherwise
+unavailable.
+
 .. automethod:: bleak.BleakAdapter.get
 
 -----------------------------

tests/integration/test_adapter.py

@@ -1,3 +1,4 @@
+import asyncio
 import dataclasses
 from collections.abc import AsyncGenerator
 
@@ -11,6 +12,7 @@
 
 from bleak import BleakAdapter, BleakClient
 from bleak.backends.device import BLEDevice
+from bleak.exc import BleakBluetoothNotAvailableError, BleakBluetoothNotAvailableReason
 from tests.integration.conftest import (
     configure_and_power_on_bumble_peripheral,
     create_bumble_peripheral,
@@ -99,3 +101,29 @@ async def test_get_connected_devices_filters_by_service_uuid(
 
     not_connected = await adapter.get_connected_devices([OTHER_SERVICE_UUID])
     assert not_connected == []
+
+
+@pytest.mark.asyncio(loop_scope="module")
+@pytest.mark.usefixtures("hci_transport")
+async def test_get_raises_when_powered_off() -> None:
+    """``BleakAdapter.get()`` raises ``BleakBluetoothNotAvailableError`` with
+    reason ``POWERED_OFF`` when the local Bluetooth adapter is not powered on.
+
+    This test power-cycles the BlueZ adapter via ``bluetoothctl``, so it must
+    be the last test in the module - it leaves the adapter back in
+    ``POWERED_ON`` but subsequent tests would race the recovery.
+    """
+    proc = await asyncio.create_subprocess_exec("bluetoothctl", "power", "off")
+    await proc.wait()
+    # Allow the BlueZ PropertiesChanged signal to propagate to the manager's
+    # cached properties before calling get().
+    await asyncio.sleep(1.0)
+
+    try:
+        with pytest.raises(BleakBluetoothNotAvailableError) as exc_info:
+            await BleakAdapter.get()
+        assert exc_info.value.reason == BleakBluetoothNotAvailableReason.POWERED_OFF
+    finally:
+        proc = await asyncio.create_subprocess_exec("bluetoothctl", "power", "on")
+        await proc.wait()
+        await asyncio.sleep(1.0)