winrt-runtime

3.2.1 · active · verified Thu Apr 16

winrt-runtime is the foundational Python package providing the runtime support and the `winrt.system` module for interacting with Windows Runtime (WinRT) APIs. It is part of a community-supported fork of the original pywinrt project, which provides modular bindings for individual Windows SDK namespaces (e.g., `winrt-Windows.Foundation`). The library, currently at version 3.2.1, is actively maintained with frequent updates, enabling Python developers to access a wide range of Windows OS features, hardware, and to build WinUI applications.

Common errors

```
ERROR: Could not find a version that satisfies the requirement winrt (from versions: none)
```
cause This error typically indicates that you are attempting to install the old, monolithic `winrt` package which may not be available for your Python version (e.g., Python 3.10+) or has been superseded by the modular `winrt-runtime` approach.

fix Install `winrt-runtime` for the core functionality and then install specific namespace packages like `winrt-Windows.Foundation` for the APIs you need: `pip install winrt-runtime winrt-Windows.MyNamespace`.
```
ModuleNotFoundError: No module named 'winrt.windows.devices.geolocation'
```
cause You have likely installed `winrt-runtime` but have not installed the specific PyPI package for the `Windows.Devices.Geolocation` namespace.

fix Install the required namespace package: `pip install winrt-Windows.Devices.Geolocation`.
```
RuntimeError: The object has been shut down.
```
cause This generic `RuntimeError` can occur when a WinRT object is accessed after its underlying COM object has been released or shut down, often due to improper lifecycle management, especially with objects tied to UI threads or background tasks. In some cases, it can also stem from an unhandled `asyncio` issue in older versions of `winrt` when trying to access hardware-related APIs like geolocation.

fix Ensure WinRT objects are kept alive for the duration of their use. For `asyncio` operations, ensure the event loop is running and that operations are properly awaited. For specific problematic APIs, check for newer versions of `winrt-runtime` or the relevant `winrt-Windows.*` package, as bug fixes are ongoing (e.g., `asyncio` cancellation propagation in v3.2.0).

Warnings

breaking Starting with v3.0.0, the Python WinRT bindings transitioned from monolithic `winrt` or `winsdk` packages to a modular distribution. Each WinRT namespace (e.g., `Windows.Foundation`, `Windows.Media.SpeechSynthesis`) now requires its own `winrt-Windows.Namespace` package installation.
Fix: Instead of `pip install winrt` or `pip install winsdk`, install `winrt-runtime` for the base runtime and then `pip install winrt-Windows.MyNamespace` for each specific WinRT namespace you need. Update imports from `winsdk.windows.some_module` or `winrt.windows.some_module` to `from winrt.windows.some_module import SomeClass`.
deprecated The `winsdk` package, which was a community-maintained fork after the original `winrt` package, is now deprecated in favor of the modular `winrt-runtime` and `winrt-Windows.*` package structure.
Fix: Migrate to `winrt-runtime` and the specific `winrt-Windows.*` namespace packages. This involves adjusting both installation commands and import statements.
gotcha WinRT APIs often involve asynchronous operations, which require proper integration with Python's `asyncio` event loop. Incorrect handling can lead to blocking or unexpected behavior.
Fix: Always `await` WinRT asynchronous methods (those ending with `_async`). For events that signal completion (like `MediaEnded`), use `asyncio.Event` and ensure callbacks are scheduled on the event loop with `loop.call_soon_threadsafe`.

Install

pip install winrt-runtime Base Runtime
pip install winrt-Windows.Foundation winrt-Windows.Media.SpeechSynthesis Example Namespace Packages

Imports

Object
```
from winrt.system import Object
```

SpeechSynthesizer

from winrt.windows.media.speechsynthesis import SpeechSynthesizer

Uri
wrong:
```
import winrt.windows.foundation as wf; wf.Uri
```
correct:
```
from winrt.windows.foundation import Uri
```
While aliasing works, direct import of specific classes is often preferred for clarity.

Quickstart

This quickstart demonstrates how to use `winrt-runtime` along with specific WinRT namespace packages to synthesize and play speech. It utilizes asynchronous WinRT APIs with Python's `asyncio`. Make sure to install `winrt-Windows.Media.SpeechSynthesis` and `winrt-Windows.Media.Playback` for this example to run.

import asyncio
from winrt.system import Object
from winrt.windows.media.speechsynthesis import SpeechSynthesizer
from winrt.windows.media.playback import MediaPlayer, MediaPlayerAudioCategory

async def speak_hello_world():
    synth = SpeechSynthesizer()
    # Asynchronous operation, must be awaited
    stream = await synth.synthesize_text_to_stream_async("Hello, World from WinRT!")

    media_ended_event = asyncio.Event()
    loop = asyncio.get_running_loop()

    def on_media_ended(sender: MediaPlayer, args: Object):
        loop.call_soon_threadsafe(media_ended_event.set)

    player = MediaPlayer()
    player.audio_category = MediaPlayerAudioCategory.SPEECH
    player.set_stream_source(stream)
    player.add_media_ended(on_media_ended)

    player.play()
    await media_ended_event.wait()
    print("Speech finished.")

if __name__ == "__main__":
    # Ensure required namespace packages are installed: 
    # pip install winrt-Windows.Media.SpeechSynthesis winrt-Windows.Media.Playback
    asyncio.run(speak_hello_world())

view raw JSON →