{"id":9409,"library":"winrt-windows-foundation-collections","title":"WinRT Windows Foundation Collections","description":"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.","status":"active","version":"3.2.1","language":"en","source_language":"en","source_url":"https://github.com/pywinrt/pywinrt","tags":["windows","winrt","collections","interop","gui"],"install":[{"cmd":"pip install winrt-windows-foundation-collections","lang":"bash","label":"Install core collections package"}],"dependencies":[{"reason":"Provides the core WinRT projection engine and base types.","package":"winrt-runtime","optional":false},{"reason":"Provides types from the Windows.Foundation namespace, which collections often rely on.","package":"winrt-windows-foundation","optional":false}],"imports":[{"note":"The full namespace path `winrt.windows.foundation.collections` must be used, not `winrt.foundation.collections`.","wrong":"from winrt.foundation.collections import IVector","symbol":"IVector","correct":"from winrt.windows.foundation.collections import IVector"},{"note":"WinRT types are organized by their full WinRT namespace within the `winrt` Python package hierarchy.","wrong":"from winrt.runtime.collections import IMap","symbol":"IMap","correct":"from winrt.windows.foundation.collections import IMap"},{"symbol":"PropertySet","correct":"from winrt.windows.foundation.collections import PropertySet"}],"quickstart":{"code":"from winrt.windows.foundation.collections import PropertySet\nfrom winrt.windows.foundation import Uri\n\n# PropertySet is a concrete WinRT collection type (IMap<str, object>)\nproperties = PropertySet()\nproperties.Insert(\"myString\", \"Hello WinRT\")\nproperties.Insert(\"myNumber\", 123)\nproperties.Insert(\"myUri\", Uri(\"http://example.com/test\"))\n\nprint(f\"PropertySet size: {properties.Size}\")\nprint(f\"Value for 'myString': {properties.Lookup('myString')}\")\nprint(f\"Value for 'myUri': {properties.Lookup('myUri')}\")\n\n# PropertySet also supports Python dictionary-like access and iteration\nproperties[\"anotherKey\"] = \"anotherValue\"\n\nprint(\"\\nIterating through PropertySet:\")\nfor key, value in properties:\n    print(f\"  {key}: {value}\")\n\n# Check if a key exists\nif properties.HasKey(\"myNumber\"):\n    print(f\"'myNumber' exists with value: {properties['myNumber']}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"Version 3.0.0 introduced significant breaking changes, including a new `winrt.runtime` module, changes to object identity (`==`, `hash()`), and interface casting (`as_()`).","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Do not target version `2.0.0`. Use `2.0.1` or later, as `2.0.1` contains fixes and was successfully published.","message":"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.","severity":"breaking","affected_versions":"2.0.0"},{"fix":"Upgrade to `winrt-windows-foundation-collections` version 3.1.0 or newer to ensure correct iteration behavior for WinRT collections.","message":"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:`).","severity":"breaking","affected_versions":"<3.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.2.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Change your import statement to `from winrt.windows.foundation.collections import ...`.","cause":"Incorrect import path. WinRT namespaces are mapped directly to Python packages, including the 'windows' component.","error":"ModuleNotFoundError: No module named 'winrt.foundation.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.","cause":"WinRT APIs often expect specific WinRT types or iterables of `IKeyValuePair` rather than raw Python dictionaries, especially when creating or manipulating collections.","error":"TypeError: 'dict' object cannot be converted to WinRT type 'Windows.Foundation.Collections.IMap`2<K,V>'"},{"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.","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.","error":"AttributeError: 'IIterator' object has no attribute '__iter__'"},{"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.","cause":"Version 2.0.0 of this package was tagged on GitHub but was never published to PyPI due to internal compilation issues.","error":"ERROR: Could not find a version that satisfies the requirement winrt-windows-foundation-collections==2.0.0 (from versions: ...)"}]}