{"id":10354,"library":"winrt-windows-devices-bluetooth","title":"PyWinRT - Windows.Devices.Bluetooth Projection","description":"PyWinRT is a set of Python projections for Windows Runtime (WinRT) APIs, allowing Python developers to access native Windows features. This specific package, `winrt-windows-devices-bluetooth`, provides access to Bluetooth-related functionalities from the `Windows.Devices.Bluetooth` namespace. It is currently at version 3.2.1 and follows a frequent release cadence, often aligned with Windows SDK and App SDK updates.","status":"active","version":"3.2.1","language":"en","source_language":"en","source_url":"https://github.com/pywinrt/pywinrt","tags":["windows","winrt","bluetooth","api-client","asyncio","hardware"],"install":[{"cmd":"pip install winrt-windows-devices-bluetooth","lang":"bash","label":"Install specific projection"},{"cmd":"pip install winrt","lang":"bash","label":"Install core runtime (usually pulled by projection)"}],"dependencies":[{"reason":"Core runtime for all WinRT projections.","package":"winrt","optional":false}],"imports":[{"note":"WinRT projections follow the WinRT namespace structure, not the PyPI package name.","wrong":"from winrt_windows_devices_bluetooth import BluetoothAdapter","symbol":"BluetoothAdapter","correct":"from winrt.windows.devices.bluetooth import BluetoothAdapter"},{"note":"Directly importing a class from its full path without 'from ... import ...' is not idiomatic Python and may not work as expected with this projection.","wrong":"import winrt.windows.devices.bluetooth.BluetoothDevice","symbol":"BluetoothDevice","correct":"from winrt.windows.devices.bluetooth import BluetoothDevice"}],"quickstart":{"code":"import asyncio\nfrom winrt.windows.devices.bluetooth import BluetoothAdapter\n\nasync def get_bluetooth_adapter_info():\n    print(\"Attempting to get default Bluetooth adapter...\")\n    adapter = await BluetoothAdapter.GetDefaultAsync()\n\n    if adapter:\n        print(f\"\\nBluetooth Adapter Found:\")\n        print(f\"  Device ID: {adapter.DeviceId}\")\n        print(f\"  Is Low Energy Supported: {adapter.IsLowEnergySupported}\")\n        print(f\"  Is Central Role Supported: {adapter.IsCentralRoleSupported}\")\n        print(f\"  Is Peripheral Role Supported: {adapter.IsPeripheralRoleSupported}\")\n        print(f\"  Address: {adapter.BluetoothAddress:X}\")\n    else:\n        print(\"No Bluetooth adapter found or enabled on this system.\")\n        print(\"Ensure Bluetooth is turned on in Windows settings.\")\n\nif __name__ == \"__main__\":\n    # Ensure asyncio event loop is running to await WinRT async operations\n    asyncio.run(get_bluetooth_adapter_info())","lang":"python","description":"This example demonstrates how to retrieve information about the default Bluetooth adapter on a Windows system using the `BluetoothAdapter` class. It highlights the typical asynchronous pattern required for most WinRT API calls."},"warnings":[{"fix":"Consult the official migration guide (e.g., `scripts/2to3` on the PyWinRT GitHub repository) and update import paths and API usage patterns to v3.x.","message":"Significant breaking changes were introduced in v3.0.0, including a new `winrt.runtime` module, changes to `winrt.system.Object` behavior (e.g., `as_()`), and regeneration of all projections. Code written for v2.x will likely not work without modification.","severity":"breaking","affected_versions":"<3.0.0"},{"fix":"Ensure your application environment is Windows. If cross-platform compatibility is needed, implement OS checks or alternative implementations for non-Windows platforms.","message":"PyWinRT is a projection of Windows Runtime APIs, meaning it only functions on Windows operating systems. Attempting to use it on Linux, macOS, or other platforms will result in `ImportError` or runtime errors because the underlying WinRT APIs are unavailable.","severity":"gotcha","affected_versions":"all"},{"fix":"Always `await` calls to WinRT methods ending with `Async`. For synchronous execution in Python, use `.get()` or `.wait()` methods on the returned async object (available since v3.2.0): `BluetoothAdapter.GetDefaultAsync().get()`.","message":"Most WinRT APIs exposed through PyWinRT are asynchronous and return `IAsyncOperation` or `IAsyncAction` objects. Forgetting to `await` these objects will lead to `TypeError: 'coroutine' object is not awaited` or the async operation never completing.","severity":"gotcha","affected_versions":"all"},{"fix":"Ensure `pip install winrt-windows-devices-bluetooth` successfully installs `winrt>=3.0.0` (or the required version listed in PyPI metadata). If problems persist, try `pip install --upgrade winrt` before installing the projection.","message":"While `pip install winrt-windows-devices-bluetooth` will typically pull in the core `winrt` package as a dependency, issues can arise if the dependency is not correctly resolved or if an incompatible version of `winrt` is already installed. The specific projection package itself does not contain the core runtime logic.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Run `pip install winrt-windows-devices-bluetooth` to ensure both the projection and its core runtime are installed.","cause":"The `winrt-windows-devices-bluetooth` package is not installed, or its core `winrt` dependency is missing/corrupted.","error":"ImportError: cannot import name 'BluetoothAdapter' from 'winrt.windows.devices.bluetooth'"},{"fix":"Install the specific projection package: `pip install winrt-windows-devices-bluetooth`.","cause":"Only the core `winrt` package is installed, but not the specific projection package for `Windows.Devices.Bluetooth` (i.e., `winrt-windows-devices-bluetooth`). The `windows` namespace is part of the projection, not the core.","error":"AttributeError: module 'winrt' has no attribute 'windows'"},{"fix":"Prefix the call with `await` (e.g., `await BluetoothAdapter.GetDefaultAsync()`). If synchronous execution is required (from v3.2.0+), call `.get()` or `.wait()` on the returned async object: `BluetoothAdapter.GetDefaultAsync().get()`.","cause":"An asynchronous WinRT method (typically ending in `Async`) was called but not `await`ed in an `async` function, or the calling context is not asynchronous.","error":"TypeError: 'coroutine' object is not awaited"},{"fix":"PyWinRT is Windows-only. Ensure the application is running on Windows and that the necessary hardware/features (e.g., Bluetooth) are enabled and functioning correctly in Windows settings.","cause":"This low-level WinRT error often occurs when running PyWinRT on a non-Windows operating system, or when a required Windows feature (like Bluetooth) is disabled or not present.","error":"System.Exception: Element not found."}]}