centralize backend detection

Author: timrid

CHANGELOG.rst

@@ -10,6 +10,10 @@ and this project adheres to `Semantic Versioning <https://semver.org/spec/v2.0.0
 `Unreleased`_
 =============
 
+Added
+-----
+- Added ``bleak.backends.get_backend()`` and ``BleakBackend`` enum for a centralized backend detection.
+
 `1.1.1`_ (2025-09-07)
 =====================
 

bleak/backends/__init__.py

@@ -1,5 +1,58 @@
-# -*- coding: utf-8 -*-
-# Created on 2017-11-19 by hbldh <[email protected]>
-"""
-__init__.py
-"""
+import enum
+import os
+import platform
+import sys
+
+from bleak.exc import BleakError
+
+
+class BleakBackend(enum.Enum):
+    P4Android = enum.auto()
+    """
+    Python for Android backend.
+    """
+
+    BlueZDBus = enum.auto()
+    """
+    BlueZ D-Bus backend for Linux.
+    """
+
+    PythonistaCB = enum.auto()
+    """
+    Pythonista CoreBluetooth backend for iOS and macOS.
+    """
+
+    CoreBluetooth = enum.auto()
+    """
+    CoreBluetooth backend for macOS.
+    """
+
+    WinRT = enum.auto()
+    """
+    Windows Runtime backend for Windows.
+    """
+
+
+def get_backend() -> BleakBackend:
+    """
+    Returns the preferred backend for the current platform/environment.
+    """
+    if os.environ.get("P4A_BOOTSTRAP") is not None:
+        return BleakBackend.P4Android
+
+    if platform.system() == "Linux":
+        return BleakBackend.BlueZDBus
+
+    if sys.platform == "ios" and "Pythonista3.app" in sys.executable:
+        # Must be resolved before checking for "Darwin" (macOS),
+        # as both the Pythonista app for iOS and macOS
+        # return "Darwin" from platform.system()
+        return BleakBackend.PythonistaCB
+
+    if platform.system() == "Darwin":
+        return BleakBackend.CoreBluetooth
+
+    if platform.system() == "Windows":
+        return BleakBackend.WinRT
+
+    raise BleakError(f"Unsupported platform: {platform.system()}")

bleak/backends/client.py

@@ -4,8 +4,6 @@
 Base class for backend clients.
 """
 import abc
-import os
-import platform
 import sys
 from collections.abc import Callable
 from typing import Any, Optional, Union
@@ -15,6 +13,7 @@
 else:
     from collections.abc import Buffer
 
+from bleak.backends import BleakBackend, get_backend
 from bleak.backends.characteristic import BleakGATTCharacteristic
 from bleak.backends.descriptor import BleakGATTDescriptor
 from bleak.backends.device import BLEDevice
@@ -213,20 +212,18 @@ def get_platform_client_backend_type() -> type[BaseBleakClient]:
     """
     Gets the platform-specific :class:`BaseBleakClient` type.
     """
-    if os.environ.get("P4A_BOOTSTRAP") is not None:
+    backend = get_backend()
+    if backend == BleakBackend.P4Android:
         from bleak.backends.p4android.client import BleakClientP4Android
 
         return BleakClientP4Android
 
-    if platform.system() == "Linux":
+    if backend == BleakBackend.BlueZDBus:
         from bleak.backends.bluezdbus.client import BleakClientBlueZDBus
 
         return BleakClientBlueZDBus
 
-    if sys.platform == "ios" and "Pythonista3.app" in sys.executable:
-        # Must be resolved before checking for "Darwin" (macOS),
-        # as both the Pythonista app for iOS and macOS
-        # return "Darwin" from platform.system()
+    if backend == BleakBackend.PythonistaCB:
         try:
             from bleak_pythonista import BleakClientPythonistaCB
 
@@ -236,14 +233,14 @@ def get_platform_client_backend_type() -> type[BaseBleakClient]:
                 "Ensure you have `bleak-pythonista` package installed."
             ) from e
 
-    if platform.system() == "Darwin":
+    if backend == BleakBackend.CoreBluetooth:
         from bleak.backends.corebluetooth.client import BleakClientCoreBluetooth
 
         return BleakClientCoreBluetooth
 
-    if platform.system() == "Windows":
+    if backend == BleakBackend.WinRT:
         from bleak.backends.winrt.client import BleakClientWinRT
 
         return BleakClientWinRT
 
-    raise BleakError(f"Unsupported platform: {platform.system()}")
+    raise BleakError(f"Unsupported backend: {backend}")

bleak/backends/scanner.py

@@ -1,12 +1,10 @@
 import abc
 import asyncio
 import inspect
-import os
-import platform
-import sys
 from collections.abc import Callable, Coroutine, Hashable
 from typing import Any, NamedTuple, Optional
 
+from bleak.backends import BleakBackend, get_backend
 from bleak.backends.device import BLEDevice
 from bleak.exc import BleakError
 
@@ -286,20 +284,18 @@ def get_platform_scanner_backend_type() -> type[BaseBleakScanner]:
     """
     Gets the platform-specific :class:`BaseBleakScanner` type.
     """
-    if os.environ.get("P4A_BOOTSTRAP") is not None:
+    backend = get_backend()
+    if backend == BleakBackend.P4Android:
         from bleak.backends.p4android.scanner import BleakScannerP4Android
 
         return BleakScannerP4Android
 
-    if platform.system() == "Linux":
+    if backend == BleakBackend.BlueZDBus:
         from bleak.backends.bluezdbus.scanner import BleakScannerBlueZDBus
 
         return BleakScannerBlueZDBus
 
-    if sys.platform == "ios" and "Pythonista3.app" in sys.executable:
-        # Must be resolved before checking for "Darwin" (macOS),
-        # as both the Pythonista app for iOS and macOS
-        # return "Darwin" from platform.system()
+    if backend == BleakBackend.PythonistaCB:
         try:
             from bleak_pythonista import BleakScannerPythonistaCB
 
@@ -309,14 +305,14 @@ def get_platform_scanner_backend_type() -> type[BaseBleakScanner]:
                 "Ensure you have `bleak-pythonista` package installed."
             ) from e
 
-    if platform.system() == "Darwin":
+    if backend == BleakBackend.CoreBluetooth:
         from bleak.backends.corebluetooth.scanner import BleakScannerCoreBluetooth
 
         return BleakScannerCoreBluetooth
 
-    if platform.system() == "Windows":
+    if backend == BleakBackend.WinRT:
         from bleak.backends.winrt.scanner import BleakScannerWinRT
 
         return BleakScannerWinRT
 
-    raise BleakError(f"Unsupported platform: {platform.system()}")
+    raise BleakError(f"Unsupported backend: {backend}")