Merge pull request #1568 from hbldh/release/v0.22.1

Release/v0.22.1

CHANGELOG.rst

@@ -10,7 +10,15 @@ and this project adheres to `Semantic Versioning <https://semver.org/spec/v2.0.0
 `Unreleased`_
 =============
 
-`0.22.0`_ (2024-04-04)
+`0.22.1`_ (2024-05-07)
+======================
+
+Added
+-----
+* Added ``bleak.backends.winrt.util.allow_sta()`` method to allow integration
+  with graphical user interfaces on Windows. Fixes #1565.
+
+`0.22.0`_ (2024-05-04)
 ======================
 
 Added
@@ -1014,7 +1022,8 @@ Fixed
 * Bleak created.
 
 
-.. _Unreleased: https://github.com/hbldh/bleak/compare/v0.22.0...develop
+.. _Unreleased: https://github.com/hbldh/bleak/compare/v0.22.1...develop
+.. _0.22.1: https://github.com/hbldh/bleak/compare/v0.22.0...v0.22.1
 .. _0.22.0: https://github.com/hbldh/bleak/compare/v0.21.1...v0.22.0
 .. _0.21.1: https://github.com/hbldh/bleak/compare/v0.21.0...v0.21.1
 .. _0.21.0: https://github.com/hbldh/bleak/compare/v0.20.2...v0.21.0

bleak/backends/winrt/util.py

@@ -69,6 +69,9 @@ def assert_mta() -> None:
 
     .. versionadded:: 0.22
     """
+    if hasattr(allow_sta, "_allowed"):
+        return
+
     try:
         apt_type, _ = _get_apartment_type()
         if apt_type != _AptType.MTA:
@@ -81,6 +84,24 @@ def assert_mta() -> None:
             raise
 
 
+def allow_sta():
+    """
+    Suppress check for MTA thread type and allow STA.
+
+    Bleak will hang forever if the current thread is not MTA - unless there is
+    a Windows event loop running that is properly integrated with asyncio in
+    Python.
+
+    If your program meets that condition, you must call this function do disable
+    the check for MTA. If your program doesn't have a graphical user interface
+    you probably shouldn't call this function. and use ``uninitialize_sta()``
+    instead.
+
+    .. versionadded:: 0.22.1
+    """
+    allow_sta._allowed = True
+
+
 def uninitialize_sta():
     """
     Uninitialize the COM library on the current thread if it was not initialized

docs/troubleshooting.rst

@@ -82,11 +82,28 @@ Bleak should detect this and raise an exception with a message similar to::
 
     The current thread apartment type is not MTA: STA.
 
-To work around this, you can use a utility function provided by Bleak to
-uninitialize the threading model after importing an offending package::
+To work around this, you can use one of the utility functions provided by Bleak.
+
+If your program has a graphical user interface and the UI framework *and* it is
+properly integrated with asyncio *and* Bleak is not running on a background
+thread then call ``allow_sta()`` before calling any other Bleak APis::
+
+    try:
+        from bleak.backends.winrt.util import allow_sta
+        # tell Bleak we are using a graphical user interface that has been properly
+        # configured to work with asyncio
+        allow_sta()
+    except ImportError:
+        # other OSes and older versions of Bleak will raise ImportError which we
+        # can safely ignore
+        pass
+
+The more typical case, though, is that some library has imported something like
+``pywin32`` which breaks Bleak. In this case, you can uninitialize the threading
+model like this::
 
     import win32com  # this sets current thread to STA :-(
-    from bleak.backends.winrt.utils import uninitialize_sta
+    from bleak.backends.winrt.util import uninitialize_sta
 
     uninitialize_sta()  # undo the unwanted side effect
 

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "bleak"
-version = "0.22.0"
+version = "0.22.1"
 description = "Bluetooth Low Energy platform Agnostic Klient"
 authors = ["Henrik Blidh <henrik.blidh@nedomkull.com>"]
 license = "MIT"