Merge pull request #1808 from hbldh/release/v1.1.0

dlech · web-flow · commit 1e6dd6f554d3 · 2025-08-10T17:51:07.000-05:00
Release/v1.1.0
diff --git a/AUTHORS.rst b/AUTHORS.rst
@@ -24,6 +24,7 @@ Contributors
 * David Johansen <davejohansen@gmail.com>
 * JP Hutchins <jphutchins@gmail.com>
 * Bram Duvigneau <bram@bramd.nl>
+* Dmytro Yaroshenko <thehelixpg@gmail.com>
 
 And many others who did not wish to be named here.
 
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -10,6 +10,19 @@ and this project adheres to `Semantic Versioning <https://semver.org/spec/v2.0.0
 `Unreleased`_
 =============
 
+`1.1.0`_ (2025-08-10)
+=====================
+
+Added
+-----
+- Added support for Pythonista iOS app backend.
+- Added ``BleakClient.name`` property for getting the peripheral's name. Fixes #1802.
+
+Fixed
+-----
+- Fixed ``BleakClient.connect()`` on Android when service characteristics have descriptors. Fixes #1803.
+- Fixed disconnect callback not called on Windows when Bleak initiates disconnection.
+
 `1.0.1`_ (2025-06-30)
 =====================
 
@@ -1098,7 +1111,8 @@ Fixed
 * Bleak created.
 
 
-.. _Unreleased: https://github.com/hbldh/bleak/compare/v1.0.1...develop
+.. _Unreleased: https://github.com/hbldh/bleak/compare/v1.1.0...develop
+.. _1.1.0: https://github.com/hbldh/bleak/compare/v1.0.1...v1.1.0
 .. _1.0.1: https://github.com/hbldh/bleak/compare/v1.0.0...v1.0.1
 .. _1.0.0: https://github.com/hbldh/bleak/compare/v0.22.3...v1.0.0
 .. _0.22.3: https://github.com/hbldh/bleak/compare/v0.22.2...v0.22.3
diff --git a/bleak/__init__.py b/bleak/__init__.py
@@ -512,6 +512,20 @@ def __init__(
 
     # device info
 
+    @property
+    def name(self) -> str:
+        """
+        Gets a human-readable name for the peripheral device.
+
+        The name can be somewhat OS-dependent. It is usually the name provided
+        by the standard Device Name characteristic, if present or the name
+        provided by the advertising data. If neither is available, it will be
+        a Bluetooth address separated with dashes (``-``) instead of colons
+        (``:``) (or a UUID on Apple devices). It may also be possible to override
+        the device name using the OS's Bluetooth settings.
+        """
+        return self._backend.name
+
     @property
     def address(self) -> str:
         """
diff --git a/bleak/backends/bluezdbus/client.py b/bleak/backends/bluezdbus/client.py
@@ -79,6 +79,8 @@ def __init__(
         # kwarg "device" is for backwards compatibility
         self._adapter: Optional[str] = kwargs.get("adapter", kwargs.get("device"))
 
+        self._device_info: Optional[dict[str, Any]]
+
         # Backend specific, D-Bus objects and data
         if isinstance(address_or_ble_device, BLEDevice):
             self._device_path = address_or_ble_device.details["path"]
@@ -666,6 +668,14 @@ async def _get_device_path(self) -> str:
         bluez_address = self.address.upper().replace(":", "_")
         return f"{adapter_path}/dev_{bluez_address}"
 
+    @property
+    @override
+    def name(self) -> str:
+        """See :meth:`bleak.BleakClient.name`."""
+        if self._device_info is None:
+            raise BleakError("Not connected")
+        return self._device_info["Alias"]
+
     @property
     @override
     def mtu_size(self) -> int:
diff --git a/bleak/backends/client.py b/bleak/backends/client.py
@@ -52,6 +52,13 @@ def __init__(self, address_or_ble_device: Union[BLEDevice, str], **kwargs: Any):
             "disconnected_callback"
         )
 
+    # NB: this is not marked as @abc.abstractmethod because that would break
+    # 3rd-party backends. We might change this in the future to make it required.
+    @property
+    def name(self) -> str:
+        """See :meth:`bleak.BleakClient.name`."""
+        raise NotImplementedError
+
     @property
     @abc.abstractmethod
     def mtu_size(self) -> int:
@@ -216,6 +223,19 @@ def get_platform_client_backend_type() -> type[BaseBleakClient]:
 
         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()
+        try:
+            from bleak_pythonista import BleakClientPythonistaCB
+
+            return BleakClientPythonistaCB
+        except ImportError as e:
+            raise ImportError(
+                "Ensure you have `bleak-pythonista` package installed."
+            ) from e
+
     if platform.system() == "Darwin":
         from bleak.backends.corebluetooth.client import BleakClientCoreBluetooth
 
diff --git a/bleak/backends/corebluetooth/client.py b/bleak/backends/corebluetooth/client.py
@@ -163,6 +163,14 @@ def is_connected(self) -> bool:
             else self._peripheral.state() == CBPeripheralStateConnected
         )
 
+    @property
+    @override
+    def name(self) -> str:
+        """Get the name of the connected peripheral"""
+        if self._peripheral is None:
+            raise BleakError("Not connected")
+        return self._peripheral.name()
+
     @property
     @override
     def mtu_size(self) -> int:
diff --git a/bleak/backends/p4android/client.py b/bleak/backends/p4android/client.py
@@ -281,7 +281,7 @@ async def _get_services(self) -> BleakGATTServiceCollection:
                     descriptor = BleakGATTDescriptor(
                         java_descriptor,
                         characteristic.handle + 1 + descriptor_index,
-                        self.obj.getUuid().toString(),
+                        java_descriptor.getUuid().toString(),
                         characteristic,
                     )
                     services.add_descriptor(descriptor)
diff --git a/bleak/backends/scanner.py b/bleak/backends/scanner.py
@@ -3,6 +3,7 @@
 import inspect
 import os
 import platform
+import sys
 from collections.abc import Callable, Coroutine, Hashable
 from typing import Any, NamedTuple, Optional
 
@@ -295,6 +296,19 @@ def get_platform_scanner_backend_type() -> type[BaseBleakScanner]:
 
         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()
+        try:
+            from bleak_pythonista import BleakScannerPythonistaCB
+
+            return BleakScannerPythonistaCB
+        except ImportError as e:
+            raise ImportError(
+                "Ensure you have `bleak-pythonista` package installed."
+            ) from e
+
     if platform.system() == "Darwin":
         from bleak.backends.corebluetooth.scanner import BleakScannerCoreBluetooth
 
diff --git a/bleak/backends/winrt/client.py b/bleak/backends/winrt/client.py
@@ -475,6 +475,17 @@ async def disconnect(self) -> None:
             gatt_char.remove_value_changed(event_handler_token)
         self._notification_callbacks.clear()
 
+        # Since we can't wait for the session close event (it may never come)
+        # we need to synthesize the disconnect event
+        if self._session and self._session_status_changed_token:
+            self._session.remove_session_status_changed(
+                self._session_status_changed_token
+            )
+            self._session_status_changed_token = None
+
+            if self._disconnected_callback:
+                self._disconnected_callback()
+
         # Dispose all service components that we have requested and created.
         if self.services:
             # HACK: sometimes GattDeviceService.Close() hangs forever, so we
@@ -509,6 +520,14 @@ def is_connected(self) -> bool:
             else self._session.session_status == GattSessionStatus.ACTIVE
         )
 
+    @property
+    @override
+    def name(self) -> str:
+        """See :meth:`bleak.BleakClient.name`."""
+        if self._requester is None:
+            raise BleakError("Not connected")
+        return self._requester.name
+
     @property
     @override
     def mtu_size(self) -> int:
diff --git a/docs/backends/index.rst b/docs/backends/index.rst
@@ -7,6 +7,7 @@ Bleak supports the following operating systems:
 * Linux distributions with BlueZ >= 5.55 (See :ref:`linux-backend` for more details)
 * OS X/macOS support via Core Bluetooth API, from at least version 10.13
 * Partial Android support mostly using Python-for-Android/Kivy.
+* Partial, optional iOS support using Pythonista iOS app.
 
 These pages document platform specific differences from the interface API.
 
@@ -19,6 +20,7 @@ Contents:
    linux
    macos
    android
+   pythonista
 
 Shared Backend API
 ------------------
diff --git a/docs/backends/pythonista.rst b/docs/backends/pythonista.rst
@@ -0,0 +1,102 @@
+Pythonista iOS app backend
+==========================
+
+Pythonista iOS app backend of Bleak is written as 3rd-party module `bleak-pythonista <https://pypi.org/project/bleak-pythonista/>`_ with
+`pythonista built-in _cb module (CoreBluetooth wrapper) <https://omz-software.com/pythonista/docs/ios/cb.html/>`_ directives for interfacing
+
+* This backend refers to `Pythonista.cb docs <https://omz-software.com/pythonista/docs/ios/cb.html>`_
+* This backend refers to existing `macOS CoreBluetooth bleak backend <https://github.com/hbldh/bleak/tree/develop/bleak/backends/corebluetooth>`_ was used as a reference
+* It also provides stub files for pythonista built-in modules as ``_cb`` and ``pythonista.cb``, and fake ``_cb.py`` implementation for testing on unsupported platforms
+* Use `Bleak docs <https://github.com/hbldh/bleak/blob/develop/README.rst>`_ to explore how to use Bleak
+
+.. note:: bleak-pythonista sources aren't included with Bleak. Explore them here: `bleak-pythonista on GitHub <https://github.com/o-murphy/bleak-pythonista>`_
+
+
+Optional installation with Bleak
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Use `StaSh <https://github.com/ywangd/stash>`_
+or `Pythonista3_pip_Configration_Tool <https://github.com/CrossDarkrix/Pythonista3_pip_Configration_Tool>`_ for pip
+
+.. code-block:: console
+
+    $ pip install bleak[pythonista]
+
+
+Specific features for the Pythonista iOS app backend
+----------------------------------------------------
+
+The most noticeable difference between the other
+backends of bleak and this backend, is that pythonista ``_cb`` (CoreBluetooth wrapper) doesn't scan for
+other devices via Bluetooth address. Instead, UUIDs are utilized that are often
+unique between the device that is scanning and the device that is being scanned.
+
+In the example files, this is handled in this fashion:
+
+.. code-block:: python
+
+    mac_addr = (
+        "24:71:89:cc:09:05"
+        if sys.platform != "darwin"
+        else "243E23AE-4A99-406C-B317-18F1BD7B4CBE"
+    )
+
+As stated above, this will however only work the Apple device that performed
+the scan and thus cached the device as ``243E23AE-4A99-406C-B317-18F1BD7B4CBE``.
+
+Pairing
+^^^^^^^
+There is no pairing functionality implemented in Pythonista iOS app right now, since it does not seem
+to be any explicit pairing methods in Pythonista ``_cb`` (CoreBluetooth wrapper).
+
+Instead, iOS will prompt the user the first time a characteristic that requires
+authorization/authentication is accessed. This means that a GATT read or write
+operation could block for a long time waiting for the user to response. So
+timeouts should be set accordingly.
+
+Calling the :meth:`bleak.BleakClient.pair` method will raise a ``NotImplementedError``
+on iOS. But setting ``pair=True`` in :class:`bleak.BleakClient` will be silently ignored.
+
+Characteristic descriptors
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+There is no functionality to get characteristic descriptors implemented in Pythonista iOS app right now.
+
+Calling the :meth:`bleak.BleakClient.read_gatt_descriptor` method will raise a ``NotImplementedError``
+on Pythonista iOS app.
+Calling the :meth:`bleak.BleakClient.write_gatt_descriptor` method will raise a ``NotImplementedError``
+on Pythonista iOS app.
+
+Notifications
+^^^^^^^^^^^^^
+Pythonista ``_cb`` (CoreBluetooth wrapper) does not differentiate between data from a notification and data from a read.
+This can cause confusion in cases where a device may send a notification message on a characteristic
+as a signal that the characteristic needs to be read again.
+
+Bleak can accept a ``notification_discriminator`` callback in the ``cb`` dict parameter that is
+passed to the :meth:`bleak.BleakClient.start_notify` method that can differentiate between these types of data.
+
+.. code-block:: python
+
+    event = asyncio.Event()
+
+    async def notification_handler(char, data):
+        event.set()
+
+    def notification_check_handler(data):
+        # We can identify notifications on this characteristic because they
+        # only contain 1 byte of data. Read responses will have more than
+        # 1 byte.
+        return len(data) == 1
+
+    await client.start_notify(
+        char,
+        notification_handler,
+        cb={"notification_discriminator": notification_check_handler},
+    )
+
+    while True:
+        await event.wait()
+        # We received a notification - prepare to receive another
+        event.clear()
+        # Then read the characteristic to get the full value
+        data = await client.read_gatt_char(char)
+        # Do stuff with data
diff --git a/docs/installation.rst b/docs/installation.rst
@@ -34,3 +34,16 @@ testing the latest changes before they reach the stable release.
     $ pip install https://github.com/hbldh/bleak/archive/refs/heads/develop.zip
 
 For checking out a copy of Bleak for developing Bleak itself, see the :doc:`contributing` page.
+
+
+Pythonista iOS app
+^^^^^^^^^^^^^^^^^^
+Use `StaSh <https://github.com/ywangd/stash>`_
+or `Pythonista3_pip_Configration_Tool <https://github.com/CrossDarkrix/Pythonista3_pip_Configration_Tool>`_ for pip
+
+.. code-block:: console
+
+    $ pip install bleak[pythonista]
+
+It should install ``bleak`` and ``bleak-pythonista``
+Then use bleak as common :doc:`usage` or refer to `bleak-pythonista docs <https://github.com/o-murphy/bleak-pythonista/blob/master/docs/pythonista.rst>`_
diff --git a/examples/service_explorer.py b/examples/service_explorer.py
@@ -57,15 +57,15 @@ async def main(args: Args):
         # Give the user plenty of time to enter a PIN code if paring is required.
         timeout=90 if args.pair else 10,
     ) as client:
-        logger.info("connected")
+        logger.info("connected to %s (%s)", client.name, client.address)
 
         for service in client.services:
             logger.info("[Service] %s", service)
 
             for char in service.characteristics:
                 if "read" in char.properties:
                     try:
-                        value = await client.read_gatt_char(char.uuid)
+                        value = await client.read_gatt_char(char)
                         extra = f", Value: {value}"
                     except Exception as e:
                         extra = f", Error: {e}"
@@ -84,7 +84,7 @@ async def main(args: Args):
 
                 for descriptor in char.descriptors:
                     try:
-                        value = await client.read_gatt_descriptor(descriptor.handle)
+                        value = await client.read_gatt_descriptor(descriptor)
                         logger.info("    [Descriptor] %s, Value: %r", descriptor, value)
                     except Exception as e:
                         logger.error("    [Descriptor] %s, Error: %s", descriptor, e)
diff --git a/poetry.lock b/poetry.lock
diff --git a/pyproject.toml b/pyproject.toml

-Original file line number
+Diff line change
 * David Johansen <[email protected]>
 * JP Hutchins <[email protected]>
 * Bram Duvigneau <[email protected]>
 +* Dmytro Yaroshenko <[email protected]>
 And many others who did not wish to be named here.
Original file line number	Diff line number	Diff line change
`@@ -281,7 +281,7 @@ async def _get_services(self) -> BleakGATTServiceCollection:`
`281`	`281`	`descriptor = BleakGATTDescriptor(`
`282`	`282`	`java_descriptor,`
`283`	`283`	`characteristic.handle + 1 + descriptor_index,`
`284`		`- self.obj.getUuid().toString(),`
	`284`	`+ java_descriptor.getUuid().toString(),`
`285`	`285`	`characteristic,`
`286`	`286`	`)`
`287`	`287`	`services.add_descriptor(descriptor)`