{"id":8783,"library":"winrt-windows-foundation","title":"WinRT Windows Foundation API","description":"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.","status":"active","version":"3.2.1","language":"en","source_language":"en","source_url":"https://github.com/pywinrt/pywinrt","tags":["windows","winrt","asyncio","interop","uwp"],"install":[{"cmd":"pip install winrt-windows-foundation","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"symbol":"Uri","correct":"from winrt.windows.foundation import Uri"},{"symbol":"IAsyncOperation","correct":"from winrt.windows.foundation import IAsyncOperation"},{"symbol":"PropertyValue","correct":"from winrt.windows.foundation import PropertyValue"},{"note":"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.","wrong":"from winrt.windows.foundation.interop import box","symbol":"box_int32","correct":"from winrt.system import box_int32"}],"quickstart":{"code":"from winrt.windows.foundation import Uri\n\ndef main():\n    # Create a WinRT Uri object\n    url = Uri(\"https://www.microsoft.com/python\")\n\n    print(f\"Original URI: {url.AbsoluteUri}\")\n    print(f\"Scheme Name: {url.SchemeName}\")\n    print(f\"Domain: {url.Domain}\")\n    print(f\"Path: {url.Path}\")\n\n    # Demonstrate a simple comparison\n    another_url = Uri(\"https://www.microsoft.com/python\")\n    if url == another_url:\n        print(\"URIs are equal.\")\n\nif __name__ == \"__main__\":\n    main()","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Uninstall `winrt-runtime` if it's installed and rely solely on `winrt-windows-foundation` (and other specific `winrt-*` packages) for runtime components.","message":"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.","severity":"deprecated","affected_versions":">=3.0.0"},{"fix":"Upgrade to `winrt-windows-foundation v3.1.0` or a later version to ensure correct iteration behavior.","message":"Before `v3.1.0`, `IIterator.__iter__()` contained critical bugs that could lead to crashes or incorrect object returns, especially when iterating over WinRT collections.","severity":"gotcha","affected_versions":"<3.1.0"},{"fix":"Update imports to `from winrt.system import box_int32` (or the appropriate type) and call the new type-specific functions.","message":"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`.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"2.0.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"ModuleNotFoundError: No module named 'winrt.runtime'"},{"fix":"Upgrade `winrt-windows-foundation` to `v3.0.0` or later, which introduced support for `==`, `!=`, and `hash()` for `winrt.system.Object`.","cause":"Attempting to use equality operators (`==`, `!=`) on `winrt.system.Object` instances before `v3.0.0`, which did not support these operations.","error":"AttributeError: 'Object' object has no attribute '__eq__'"},{"fix":"Upgrade `winrt-windows-foundation` to `v3.0.0` or later, which introduced support for `hash()` for `winrt.system.Object`.","cause":"Attempting to use `winrt.system.Object` instances as dictionary keys or in sets before `v3.0.0`, which did not implement `__hash__`.","error":"TypeError: unhashable type: 'Object'"},{"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`.","cause":"The `box` and `unbox` functions were moved and refactored into type-specific functions under `winrt.system` in `v3.0.0`.","error":"AttributeError: module 'winrt.windows.foundation.interop' has no attribute 'box'"}]}