WinRT Windows Foundation API

3.2.1 · active · verified Thu Apr 16

winrt-windows-foundation is a Python package that provides a projection of the core Windows Runtime (WinRT) Foundation APIs, enabling Python developers to interact with fundamental Windows features and UWP application components. As of version 3.2.1, it offers enhanced asyncio integration, support for the Python buffer protocol, and streamlined API access. Releases are frequent, often coinciding with updates to the Windows SDK and Windows App SDK.

Common errors

```
ModuleNotFoundError: No module named 'winrt.runtime'
```
cause The `winrt.runtime` module, previously provided by the separate `winrt-runtime` PyPI package (or a different internal structure), has been integrated into the main `winrt-windows-foundation` and other `winrt-*` packages since v3.0.0.

fix Ensure `winrt-windows-foundation` is updated to v3.0.0 or later. Remove any explicit `pip uninstall winrt-runtime` if it was installed separately. The `winrt.runtime` module is now part of the standard `winrt` package hierarchy.
```
AttributeError: 'Object' object has no attribute '__eq__'
```
cause Attempting to use equality operators (`==`, `!=`) on `winrt.system.Object` instances before `v3.0.0`, which did not support these operations.

fix Upgrade `winrt-windows-foundation` to `v3.0.0` or later, which introduced support for `==`, `!=`, and `hash()` for `winrt.system.Object`.
```
TypeError: unhashable type: 'Object'
```
cause Attempting to use `winrt.system.Object` instances as dictionary keys or in sets before `v3.0.0`, which did not implement `__hash__`.

fix Upgrade `winrt-windows-foundation` to `v3.0.0` or later, which introduced support for `hash()` for `winrt.system.Object`.
```
AttributeError: module 'winrt.windows.foundation.interop' has no attribute 'box'
```
cause The `box` and `unbox` functions were moved and refactored into type-specific functions under `winrt.system` in `v3.0.0`.

fix Update import statements and function calls to use type-specific functions directly from `winrt.system`, e.g., `from winrt.system import box_int32` instead of `from winrt.windows.foundation.interop import box`.

Warnings

breaking Version 3.0.0 introduced significant breaking changes, including major changes to module structure, `winrt.system.Object` behavior (e.g., for equality), and the relocation/refactoring of `box`/`unbox` functions. Consult the migration guide for details.
Fix: Review the 'scripts/2to3/README.md' in the pywinrt GitHub repository for migration steps. Update import paths and code relying on `Object` comparisons or `box/unbox` functions.
deprecated The separate `winrt-runtime` PyPI package is no longer needed nor compatible with `winrt-windows-foundation` versions 3.0.0 and above. Its functionality is now integrated directly into `winrt-*` packages.
Fix: Uninstall `winrt-runtime` if it's installed and rely solely on `winrt-windows-foundation` (and other specific `winrt-*` packages) for runtime components.
gotcha Before `v3.1.0`, `IIterator.__iter__()` contained critical bugs that could lead to crashes or incorrect object returns, especially when iterating over WinRT collections.
Fix: Upgrade to `winrt-windows-foundation v3.1.0` or a later version to ensure correct iteration behavior.
breaking The `box` and `unbox` helper functions, previously found in `winrt.windows.foundation.interop`, were moved to `winrt.system` and split into type-specific functions (e.g., `box_int32`, `unbox_string`) in `v3.0.0`.
Fix: Update imports to `from winrt.system import box_int32` (or the appropriate type) and call the new type-specific functions.
gotcha The `v2.0.0` release was never published to PyPI due to compilation issues. If you intend to use a `v2` release, `v2.0.1` was the first stable and published version.
Fix: Do not attempt to install `winrt-windows-foundation==2.0.0`. Use `winrt-windows-foundation==2.0.1` or a later compatible version instead.

Install

pip install winrt-windows-foundation Install latest version

Imports

Uri

from winrt.windows.foundation import Uri

IAsyncOperation

from winrt.windows.foundation import IAsyncOperation

PropertyValue

from winrt.windows.foundation import PropertyValue

box_int32
wrong:
```
from winrt.windows.foundation.interop import box
```
correct:
```
from winrt.system import box_int32
```
The `box` and `unbox` functions were moved from `winrt.windows.foundation.interop` to `winrt.system` in v3.0.0, and split into type-specific functions like `box_int32`, `box_string`, etc.

Quickstart

This quickstart demonstrates how to create and interact with a basic WinRT Uri object from the Windows.Foundation namespace, showcasing property access and object comparison.

from winrt.windows.foundation import Uri

def main():
    # Create a WinRT Uri object
    url = Uri("https://www.microsoft.com/python")

    print(f"Original URI: {url.AbsoluteUri}")
    print(f"Scheme Name: {url.SchemeName}")
    print(f"Domain: {url.Domain}")
    print(f"Path: {url.Path}")

    # Demonstrate a simple comparison
    another_url = Uri("https://www.microsoft.com/python")
    if url == another_url:
        print("URIs are equal.")

if __name__ == "__main__":
    main()

view raw JSON →