PyWinRT - Windows.Devices.Bluetooth Projection

Common errors

• ImportError: cannot import name 'BluetoothAdapter' from 'winrt.windows.devices.bluetooth'

  cause The `winrt-windows-devices-bluetooth` package is not installed, or its core `winrt` dependency is missing/corrupted.
  fix Run `pip install winrt-windows-devices-bluetooth` to ensure both the projection and its core runtime are installed.

• AttributeError: module 'winrt' has no attribute 'windows'

  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.
  fix Install the specific projection package: `pip install winrt-windows-devices-bluetooth`.

• TypeError: 'coroutine' object is not awaited

  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.
  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()`.

• System.Exception: Element not found.

  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.
  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.

Warnings

• breaking 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.
  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.
• gotcha 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.
  Fix: Ensure your application environment is Windows. If cross-platform compatibility is needed, implement OS checks or alternative implementations for non-Windows platforms.
• gotcha 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.
  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()`.
• gotcha 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.
  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.

Install

• pip install winrt-windows-devices-bluetooth Install specific projection
• pip install winrt Install core runtime (usually pulled by projection)

Imports

• BluetoothAdapter
  wrong:

  from winrt_windows_devices_bluetooth import BluetoothAdapter

  correct:

  from winrt.windows.devices.bluetooth import BluetoothAdapter

  WinRT projections follow the WinRT namespace structure, not the PyPI package name.
• BluetoothDevice
  wrong:

  import winrt.windows.devices.bluetooth.BluetoothDevice

  correct:

  from winrt.windows.devices.bluetooth import BluetoothDevice

  Directly importing a class from its full path without 'from ... import ...' is not idiomatic Python and may not work as expected with this projection.

Quickstart

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.

import asyncio
from winrt.windows.devices.bluetooth import BluetoothAdapter

async def get_bluetooth_adapter_info():
    print("Attempting to get default Bluetooth adapter...")
    adapter = await BluetoothAdapter.GetDefaultAsync()

    if adapter:
        print(f"\nBluetooth Adapter Found:")
        print(f"  Device ID: {adapter.DeviceId}")
        print(f"  Is Low Energy Supported: {adapter.IsLowEnergySupported}")
        print(f"  Is Central Role Supported: {adapter.IsCentralRoleSupported}")
        print(f"  Is Peripheral Role Supported: {adapter.IsPeripheralRoleSupported}")
        print(f"  Address: {adapter.BluetoothAddress:X}")
    else:
        print("No Bluetooth adapter found or enabled on this system.")
        print("Ensure Bluetooth is turned on in Windows settings.")

if __name__ == "__main__":
    # Ensure asyncio event loop is running to await WinRT async operations
    asyncio.run(get_bluetooth_adapter_info())