From 825df5dcdcdc234edcd7b33086056d7edc198916 Mon Sep 17 00:00:00 2001
From: David Lechner <david@pybricks.com>
Date: Mon, 5 Sep 2022 09:41:37 -0500
Subject: [PATCH] deprecate discover() function

The discover() function was removed from the docs and was supposed to
be deprecated some time ago, but it didn't get a proper warning and
was still used in some examples.

This removes it from the examples and adds a warning so that it can
eventually be removed.
---
 CHANGELOG.rst                   |  1 +
 bleak/__init__.py               | 16 ++++++++++++++--
 examples/disconnect_callback.py |  4 ++--
 examples/discover.py            |  5 +++--
 4 files changed, 20 insertions(+), 6 deletions(-)

diff --git a/CHANGELOG.rst b/CHANGELOG.rst
index 1644c665..2e5e1a58 100644
--- a/CHANGELOG.rst
+++ b/CHANGELOG.rst
@@ -26,6 +26,7 @@ Changed
 * The BlueZ D-Bus backend now uses ``dbus-fast`` instead of ``dbus-next`` which significantly improves performance.
 * The BlueZ D-Bus backend will not avoid trying to connect to devices that are already connected. Fixes #992.
 * Updated logging to lazy version and replaced format by f-string for BleakClientWinRT
+* Added deprecation warning to ``discover()`` method.
 
 Fixed
 -----
diff --git a/bleak/__init__.py b/bleak/__init__.py
index 19cfba0e..9a62bac1 100644
--- a/bleak/__init__.py
+++ b/bleak/__init__.py
@@ -10,6 +10,7 @@
 import logging
 import platform
 import asyncio
+from warnings import warn
 
 from bleak.__version__ import __version__  # noqa: F401
 from bleak.exc import BleakError
@@ -80,9 +81,20 @@
 else:
     raise BleakError(f"Unsupported platform: {platform.system()}")
 
+
 # for backward compatibility
-if not _on_rtd:
-    discover = BleakScanner.discover
+def discover():
+    """
+    .. deprecated:: 0.17.0
+        This method will be removed in a future version of Bleak.
+        Use :meth:`BleakScanner.discover` instead.
+    """
+    warn(
+        "The discover function will removed in a future version, use BleakScanner.discover instead.",
+        FutureWarning,
+        stacklevel=2,
+    )
+    return BleakScanner.discover()
 
 
 def cli():
diff --git a/examples/disconnect_callback.py b/examples/disconnect_callback.py
index 00470d78..8362d878 100644
--- a/examples/disconnect_callback.py
+++ b/examples/disconnect_callback.py
@@ -10,11 +10,11 @@
 
 import asyncio
 
-from bleak import BleakClient, discover
+from bleak import BleakScanner, BleakClient
 
 
 async def main():
-    devs = await discover()
+    devs = await BleakScanner.discover()
     if not devs:
         print("No devices found, try again later.")
         return
diff --git a/examples/discover.py b/examples/discover.py
index e4867380..84c05ba7 100644
--- a/examples/discover.py
+++ b/examples/discover.py
@@ -9,11 +9,12 @@
 """
 
 import asyncio
-from bleak import discover
+
+from bleak import BleakScanner
 
 
 async def main():
-    devices = await discover()
+    devices = await BleakScanner.discover()
     for d in devices:
         print(d)