From 807bc31eafa0fcfffff32c4959325e9939242f99 Mon Sep 17 00:00:00 2001
From: David Lechner <david@pybricks.com>
Date: Mon, 3 Oct 2022 17:42:41 -0500
Subject: [PATCH] backends/device: deprecate BLEDevice.rssi and .metadata

This make a clean separation between the BLEDevice which is the OS
handle for a "known" BLE device and the advertising data for that
device. There are now alternatives in place for getting advertising
data paired with the BLEDevice so we can deprecate these attributes.

Fixes #1025.
---
 CHANGELOG.rst             |  1 +
 bleak/backends/device.py  | 64 ++++++++++++++++++++++++++++-----------
 bleak/backends/scanner.py |  3 +-
 examples/kivy/main.py     |  2 --
 4 files changed, 50 insertions(+), 20 deletions(-)

diff --git a/CHANGELOG.rst b/CHANGELOG.rst
index 0ff6c4fd3..621e15d10 100644
--- a/CHANGELOG.rst
+++ b/CHANGELOG.rst
@@ -23,6 +23,7 @@ Changed
 -------
 * Changed ``AdvertisementData`` to a named tuple.
 * A faster ``unpack_variants`` is now provided by dbus-fast
+* Deprecated ``BLEDevice.rssi`` and ``BLEDevice.metadata``. Fixes #1025.
 
 Fixed
 -----
diff --git a/bleak/backends/device.py b/bleak/backends/device.py
index 6ef93f0b6..dfd522497 100644
--- a/bleak/backends/device.py
+++ b/bleak/backends/device.py
@@ -8,31 +8,61 @@
 """
 
 
+from typing import Any, Optional
+from warnings import warn
+
+
 class BLEDevice:
-    """A simple wrapper class representing a BLE server detected during
-    a `discover` call.
-
-    - When using Windows backend, `details` attribute is a
-      ``Windows.Devices.Bluetooth.Advertisement.BluetoothLEAdvertisement`` object, unless
-      it is created with the Windows.Devices.Enumeration discovery method, then is is a
-      ``Windows.Devices.Enumeration.DeviceInformation``.
-    - When using Linux backend, ``details`` attribute is a
-      dict with keys ``path`` which has the string path to the DBus device object and ``props``
-      which houses the properties dictionary of the D-Bus Device.
-    - When using macOS backend, ``details`` attribute will be a CBPeripheral object.
+    """
+    A simple wrapper class representing a BLE server detected during scanning.
     """
 
-    def __init__(self, address, name=None, details=None, rssi=0, **kwargs):
+    def __init__(
+        self, address: str, name: Optional[str], details: Any, rssi: int, **kwargs
+    ):
         #: The Bluetooth address of the device on this machine.
         self.address = address
-        #: The advertised name of the device.
+        #: The operating system name of the device (not necessarily the local name
+        # from the advertising data), suitable for display to the user.
         self.name = name
         #: The OS native details required for connecting to the device.
         self.details = details
-        #: RSSI, if available
-        self.rssi = rssi
-        #: Device specific details. Contains a ``uuids`` key which is a list of service UUIDs and a ``manufacturer_data`` field with a bytes-object from the advertised data.
-        self.metadata = kwargs
+
+        # for backwards compatibility
+        self._rssi = rssi
+        self._metadata = kwargs
+
+    @property
+    def rssi(self) -> int:
+        """
+        Gets the RSSI of the last received advertisement.
+
+        .. deprecated:: 0.19.0
+            Use :class:`AdvertisementData` from detection callback or
+            :attr:`BleakScanner.discovered_devices_and_advertisement_data` instead.
+        """
+        warn(
+            "BLEDevice.rssi is deprecated and will be removed in a future version of Bleak, use AdvertisementData.rssi instead",
+            FutureWarning,
+            stacklevel=2,
+        )
+        return self._rssi
+
+    @property
+    def metadata(self) -> dict:
+        """
+        Gets additional advertisement data for the device.
+
+        .. deprecated:: 0.19.0
+            Use :class:`AdvertisementData` from detection callback or
+            :attr:`BleakScanner.discovered_devices_and_advertisement_data` instead.
+        """
+        warn(
+            "BLEDevice.metadata is deprecated and will be removed in a future version of Bleak, use AdvertisementData instead",
+            FutureWarning,
+            stacklevel=2,
+        )
+        return self._metadata
 
     def __str__(self):
         return f"{self.address}: {self.name}"
diff --git a/bleak/backends/scanner.py b/bleak/backends/scanner.py
index 664b4f67a..359c6ce57 100644
--- a/bleak/backends/scanner.py
+++ b/bleak/backends/scanner.py
@@ -197,7 +197,8 @@ def create_or_update_device(
         try:
             device, _ = self.seen_devices[address]
 
-            device.metadata = metadata
+            device._rssi = adv.rssi
+            device._metadata = metadata
         except KeyError:
             device = BLEDevice(
                 address,
diff --git a/examples/kivy/main.py b/examples/kivy/main.py
index 2be33704f..c90e340ab 100644
--- a/examples/kivy/main.py
+++ b/examples/kivy/main.py
@@ -49,8 +49,6 @@ async def example(self):
                 if len(scanned_devices) == 0:
                     raise bleak.exc.BleakError("no devices found")
 
-                scanned_devices.sort(key=lambda device: -device.rssi)
-
                 for device in scanned_devices:
                     self.line(f"{device.name} ({device.address})")