WinRT Windows Foundation Collections

3.2.1 · active · verified Thu Apr 16

This package provides Python projections for the Windows Runtime (WinRT) APIs specifically within the `Windows.Foundation.Collections` namespace. It enables Python developers to interact with WinRT collection types like maps, vectors, and property sets. The current version is 3.2.1, with releases occurring frequently, often tied to Windows SDK updates and bug fixes.

Common errors

```
ModuleNotFoundError: No module named 'winrt.foundation.collections'
```
cause Incorrect import path. WinRT namespaces are mapped directly to Python packages, including the 'windows' component.

fix Change your import statement to `from winrt.windows.foundation.collections import ...`.
```
TypeError: 'dict' object cannot be converted to WinRT type 'Windows.Foundation.Collections.IMap`2<K,V>'
```
cause WinRT APIs often expect specific WinRT types or iterables of `IKeyValuePair` rather than raw Python dictionaries, especially when creating or manipulating collections.

fix For APIs expecting `Iterable[IKeyValuePair[K, V]]` (supported since v3.2.0), you can pass a Python mapping. For other scenarios, you may need to manually convert Python dicts to a `PropertySet` or similar concrete WinRT collection type, or use projection-specific helper functions if available.
```
AttributeError: 'IIterator' object has no attribute '__iter__'
```
cause This error typically occurs in versions prior to 3.1.0 where the Pythonic iteration interface for `IIterator` was broken or missing, preventing direct use in `for` loops.

fix Upgrade your `winrt-windows-foundation-collections` package to version 3.1.0 or newer to resolve issues with `IIterator` and enable proper Pythonic iteration.
```
ERROR: Could not find a version that satisfies the requirement winrt-windows-foundation-collections==2.0.0 (from versions: ...)
```
cause Version 2.0.0 of this package was tagged on GitHub but was never published to PyPI due to internal compilation issues.

fix Use `pip install winrt-windows-foundation-collections==2.0.1` or a newer version. Version 2.0.1 and all subsequent versions were successfully published.

Warnings

breaking Version 3.0.0 introduced significant breaking changes, including a new `winrt.runtime` module, changes to object identity (`==`, `hash()`), and interface casting (`as_()`).
Fix: Consult the official migration guide for `pywinrt` version 2 to 3 (often found in the project's GitHub repository under `scripts/2to3/README.md`) to adapt your code.
breaking The `winrt-windows-foundation-collections==2.0.0` package was never published to PyPI due to compilation issues, despite being tagged in GitHub. Attempts to install this specific version will fail.
Fix: Do not target version `2.0.0`. Use `2.0.1` or later, as `2.0.1` contains fixes and was successfully published.
breaking Prior to version 3.1.0, `IIterator.__iter__()` returned an invalid object or did not take a reference, leading to crashes or broken Pythonic iteration (e.g., `for item in my_collection:`).
Fix: Upgrade to `winrt-windows-foundation-collections` version 3.1.0 or newer to ensure correct iteration behavior for WinRT collections.
gotcha As of version 3.2.0, `asyncio` cancellation is propagated to WinRT async actions/operations. If your code relies on WinRT operations continuing after an `asyncio` task is cancelled, this behavior change might affect you.
Fix: Review `asyncio` task cancellation logic when awaiting WinRT async operations. If previous cancellation behavior was implicitly relied upon, you might need to adjust task handling or error recovery.

Install

pip install winrt-windows-foundation-collections Install core collections package

Imports

IVector
wrong:
```
from winrt.foundation.collections import IVector
```
correct:
```
from winrt.windows.foundation.collections import IVector
```
The full namespace path `winrt.windows.foundation.collections` must be used, not `winrt.foundation.collections`.
IMap
wrong:
```
from winrt.runtime.collections import IMap
```
correct:
```
from winrt.windows.foundation.collections import IMap
```
WinRT types are organized by their full WinRT namespace within the `winrt` Python package hierarchy.

PropertySet

from winrt.windows.foundation.collections import PropertySet

Quickstart

This quickstart demonstrates creating and interacting with a `PropertySet`, a common mutable WinRT map-like collection. It shows how to insert items, retrieve them, and iterate over the collection using both WinRT-specific methods and Python's dictionary-like interface.

from winrt.windows.foundation.collections import PropertySet
from winrt.windows.foundation import Uri

# PropertySet is a concrete WinRT collection type (IMap<str, object>)
properties = PropertySet()
properties.Insert("myString", "Hello WinRT")
properties.Insert("myNumber", 123)
properties.Insert("myUri", Uri("http://example.com/test"))

print(f"PropertySet size: {properties.Size}")
print(f"Value for 'myString': {properties.Lookup('myString')}")
print(f"Value for 'myUri': {properties.Lookup('myUri')}")

# PropertySet also supports Python dictionary-like access and iteration
properties["anotherKey"] = "anotherValue"

print("\nIterating through PropertySet:")
for key, value in properties:
    print(f"  {key}: {value}")

# Check if a key exists
if properties.HasKey("myNumber"):
    print(f"'myNumber' exists with value: {properties['myNumber']}")

view raw JSON →