winrt-runtime 4.0.0__cp315-cp315-win32.whl

winrt/__pyinstaller/__init__.py

@@ -0,0 +1,13 @@
+"""
+Where PyInstaller finds PyWinRT's hook.
+
+``winrt-runtime`` declares this module in the ``pyinstaller40`` entry point
+group, so PyInstaller asks it for the directory the hook is in and needs no
+configuration from the application being frozen.
+"""
+
+import os
+
+
+def get_hook_dirs() -> list[str]:
+    return [os.path.dirname(__file__)]

winrt/__pyinstaller/hook-winrt.py

@@ -0,0 +1,85 @@
+"""
+What a frozen application needs from PyWinRT that PyInstaller cannot see.
+
+Two things are invisible to an import graph.
+
+A projected namespace is a data file. ``winrt.windows.storage`` is an
+``__init__.py`` that asks the runtime to read the ``_table.pywinrt`` sitting
+beside it, so freezing the module without the table produces an executable
+that fails at import. PyInstaller collects the module and not the table.
+
+A projected type is resolved by importing the module that owns it, by name,
+while the program runs (``py::get_python_type()`` in the runtime). A call
+that hands back an ``IAsyncOperation`` imports ``winrt.windows.foundation``
+whether or not the application ever names it, and nothing in the source says
+so. So every projection package that is installed is collected rather than
+only the ones the graph reached: what an application imports says little
+about which namespaces its calls return types from.
+
+Nothing here names a Windows SDK, a Windows App SDK or any other family. What
+is collected is what the installed distributions say they ship, so a
+projection somebody else generated is collected on the same terms as the ones
+published from this repository.
+"""
+
+from importlib.metadata import distributions
+
+# the data file a projection package carries, which
+# winrt.runtime._internals.load_projection() reads from beside the module
+TABLE_NAME = "_table.pywinrt"
+
+binaries: list[tuple[str, str]] = []
+datas: list[tuple[str, str]] = []
+hiddenimports: list[str] = []
+
+
+def _installed_files() -> list[tuple[str, str, str]]:
+    """
+    Every file of every installed distribution, as (name, package, source).
+
+    ``package`` is the dotted package the file sits in and ``source`` is where
+    it is now. A distribution installed from a wheel records what it put where;
+    one that did not record it is something this can say nothing about.
+    """
+    files: list[tuple[str, str, str]] = []
+
+    for distribution in distributions():
+        for file in distribution.files or []:
+            directory = str(file).replace("\\", "/").rpartition("/")[0]
+
+            if directory:
+                files.append(
+                    (file.name, directory, str(distribution.locate_file(file)))
+                )
+
+    return files
+
+
+def _collect() -> None:
+    installed = _installed_files()
+
+    # The namespace roots PyWinRT projects into are whichever ones hold a
+    # table, rather than a list of names kept here: the runtime has no
+    # business knowing which families exist.
+    roots = {
+        package.partition("/")[0]
+        for name, package, _ in installed
+        if name == TABLE_NAME
+    }
+
+    for name, package, source in installed:
+        if package.partition("/")[0] not in roots:
+            continue
+
+        if name == TABLE_NAME:
+            datas.append((source, package))
+            hiddenimports.append(package.replace("/", "."))
+
+        # A package that redistributes a component .dll loads it by bare name
+        # after putting its own directory on the DLL search path, so no import
+        # table mentions it and nothing else would collect it.
+        if name.lower().endswith(".dll"):
+            binaries.append((source, package))
+
+
+_collect()

winrt/_winrt.pyi

@@ -0,0 +1,169 @@
+import abc
+import collections.abc
+from datetime import datetime, timedelta
+import types
+from typing import (
+    Any,
+    ClassVar,
+    Protocol,
+    Self,
+    SupportsIndex,
+    TypeVar,
+    final,
+    overload,
+)
+from collections.abc import Iterable, Iterator
+from uuid import UUID
+
+from typing_extensions import Buffer, TypeForm, deprecated
+
+from winrt.runtime import ApartmentType
+from winrt.runtime.interop import InterfaceCapsule
+
+MTA: int
+STA: int
+
+def init_apartment(apartment_type: ApartmentType, /) -> None: ...
+def uninit_apartment() -> None: ...
+def initialize_with_window(obj: Object, hwnd: SupportsIndex, /) -> None: ...
+def load_projection(module: types.ModuleType, table_path: str, /) -> None: ...
+@overload
+def as_interface(obj: Object, iid: UUID | type[Object], /) -> InterfaceCapsule: ...
+@overload
+def as_interface(obj: None, iid: UUID | type[Object], /) -> None: ...
+def get_activation_factory(
+    cls: type[Object], iid: UUID | type[Object], /
+) -> InterfaceCapsule: ...
+@overload
+def wrap_interface(
+    capsule: InterfaceCapsule, type: TypeForm[_TObject], /
+) -> _TObject: ...
+@overload
+def wrap_interface(capsule: InterfaceCapsule, qualified_name: str, /) -> Any: ...
+@overload
+def wrap_interface(capsule: None, type: type[Object] | str, /) -> None: ...
+def hresult_error(
+    hresult: SupportsIndex, error_info: InterfaceCapsule | None = None, /
+) -> OSError: ...
+def box_boolean(value: bool, /) -> Object: ...
+def box_int8(value: SupportsIndex, /) -> Object: ...
+def box_uint8(value: SupportsIndex, /) -> Object: ...
+def box_int16(value: SupportsIndex, /) -> Object: ...
+def box_uint16(value: SupportsIndex, /) -> Object: ...
+def box_int32(value: SupportsIndex, /) -> Object: ...
+def box_uint32(value: SupportsIndex, /) -> Object: ...
+def box_int64(value: SupportsIndex, /) -> Object: ...
+def box_uint64(value: SupportsIndex, /) -> Object: ...
+def box_single(value: float, /) -> Object: ...
+def box_double(value: float, /) -> Object: ...
+def box_char16(value: str, /) -> Object: ...
+def box_string(value: str, /) -> Object: ...
+def box_guid(value: UUID, /) -> Object: ...
+def box_date_time(value: datetime, /) -> Object: ...
+def box_time_span(value: timedelta, /) -> Object: ...
+def unbox_boolean(value: Object, /) -> bool: ...
+def unbox_int8(value: Object, /) -> int: ...
+def unbox_uint8(value: Object, /) -> int: ...
+def unbox_int16(value: Object, /) -> int: ...
+def unbox_uint16(value: Object, /) -> int: ...
+def unbox_int32(value: Object, /) -> int: ...
+def unbox_uint32(value: Object, /) -> int: ...
+def unbox_int64(value: Object, /) -> int: ...
+def unbox_uint64(value: Object, /) -> int: ...
+def unbox_single(value: Object, /) -> float: ...
+def unbox_double(value: Object, /) -> float: ...
+def unbox_char16(value: Object, /) -> str: ...
+def unbox_string(value: Object, /) -> str: ...
+def unbox_guid(value: Object, /) -> UUID: ...
+def unbox_date_time(value: Object, /) -> datetime: ...
+def unbox_time_span(value: Object, /) -> timedelta: ...
+
+# Reads a projection table and returns its contents as plain Python objects, so
+# that test/test_table.py can check that the generator's writer and this
+# module's reader agree on the format. The shape of the result follows
+# runtime/src/table-format.md rather than a type of its own.
+def read_table(data: Buffer, /) -> dict[str, Any]: ...
+
+_T = TypeVar("_T")
+_TObject = TypeVar("_TObject", bound=Object)
+
+# What as_() asks of the type it is given, a projected one or an interop
+# interface alike: as_(type) is type._query_interface_(obj).
+class _SupportsQueryInterface(Protocol):
+    @classmethod
+    def _query_interface_(cls, obj: Object, /) -> Self: ...
+
+_TQueryInterface = TypeVar("_TQueryInterface", bound=_SupportsQueryInterface)
+
+# Declared as an ABCMeta although at run time it derives from type: a type
+# checker requires an abstract member to be implemented only under ABCMeta, and
+# the members of an interface are abstract.
+class Object_Static(abc.ABCMeta):
+    def __instancecheck__(self, instance: Any) -> bool: ...
+    def __subclasscheck__(self, subclass: type) -> bool: ...
+
+# The type of everything WinRT can hold. A Python class that implements a WinRT
+# interface derives from the projected name of that interface, and therefore
+# from this, without being a wrapper around a WinRT object (at run time it does
+# not derive from Object, and isinstance() says it is one all the same): the
+# runtime gives it the three members below as it gives a wrapper. The members
+# of the interface itself are abstract, because implementing them is what
+# deriving from it means.
+class Object(metaclass=Object_Static):
+    def as_(self, type: TypeForm[_TQueryInterface], /) -> _TQueryInterface: ...
+    @property
+    def _iids_(self) -> Array[UUID]: ...
+    @property
+    def _runtime_class_name_(self) -> str: ...
+    # what as_() calls, which the runtime gives the projected name of an
+    # interface as well as the wrapper
+    @classmethod
+    def _query_interface_(cls, obj: Object, /) -> Self: ...
+
+@final
+class Array(collections.abc.Sequence[_T]):
+    _winrt_element_type_name_: str
+    def __class_getitem__(cls, key: Any) -> types.GenericAlias: ...
+    @overload
+    def __init__(self, type: TypeForm[_T], /) -> None: ...
+    @overload
+    def __init__(
+        self,
+        type: TypeForm[_T],
+        size: SupportsIndex,
+        /,
+    ) -> None: ...
+    @overload
+    def __init__(
+        self,
+        type: TypeForm[_T],
+        initializer: Buffer,
+        /,
+    ) -> None: ...
+    @overload
+    def __init__(
+        self,
+        type: TypeForm[_T],
+        initializer: Iterable[_T],
+        /,
+    ) -> None: ...
+    @overload
+    @deprecated("Passing a format string to Array is deprecated: pass the type instead")
+    def __init__(
+        self,
+        type: str,
+        initializer: SupportsIndex | Buffer | Iterable[Any],
+        /,
+    ) -> None: ...
+    def __buffer__(self, flags: int, /) -> memoryview: ...
+    def __release_buffer__(self, view: memoryview, /) -> None: ...
+    def __len__(self) -> int: ...
+    @overload
+    def __getitem__(self, index: SupportsIndex) -> _T: ...
+    @overload
+    def __getitem__(self, index: slice) -> Array[_T]: ...
+    def __setitem__(self, index: SupportsIndex, value: _T) -> None: ...
+    def __iter__(self) -> Iterator[_T]: ...
+    def __eq__(self, other: object, /) -> bool: ...
+    def __ne__(self, other: object, /) -> bool: ...
+    __hash__: ClassVar[None]  # type: ignore[assignment]

winrt/runtime/__init__.py

@@ -0,0 +1,28 @@
+from enum import IntEnum
+
+# winrt._winrt imports uuid when it loads, from compiled code, where a freezer
+# that follows a program's imports cannot see it. Everything that loads the
+# runtime imports this package, so saying it here puts uuid in the bundle.
+import uuid
+
+del uuid
+
+from winrt._winrt import init_apartment, uninit_apartment, STA, MTA
+
+
+__all__ = ["ApartmentType", "init_apartment", "uninit_apartment"]
+
+
+class ApartmentType(IntEnum):
+    """
+    Enumeration of COM apartment types.
+    """
+
+    SINGLE_THREADED = STA
+    """
+    Single-threaded apartment.
+    """
+    MULTI_THREADED = MTA
+    """
+    Multi-threaded apartment.
+    """

winrt/runtime/_internals.py

@@ -0,0 +1,488 @@
+from abc import ABCMeta
+import asyncio
+from importlib.machinery import ModuleSpec
+import os
+from collections.abc import (
+    Callable,
+    Mapping,
+    MutableMapping,
+    MutableSequence,
+    Sequence,
+)
+from enum import IntEnum
+from pathlib import Path
+import sys
+from typing import Any, Self, TypeVar, Protocol, TYPE_CHECKING, cast
+import warnings
+
+# NB: have to import Object from here instead of winrt.system to avoid circular import issues.
+from winrt._winrt import (
+    load_projection as _load_projection,
+    Object,
+)
+
+# Unfortunately, we can't import at runtime because of circular imports.
+if TYPE_CHECKING:
+    from winrt.windows.foundation import AsyncStatus
+
+
+#: The file a projection package keeps its namespace's table in, beside the
+#: ``__init__.py`` that loads it. It is part of the table format, which
+#: ``runtime/src/table-format.md`` is the contract for; winrt-table-compiler
+#: spells it for itself, as the two ends of the format spell the magic and the
+#: record sizes for themselves.
+TABLE_NAME = "_table.pywinrt"
+
+
+def load_projection(spec: ModuleSpec) -> None:
+    """
+    Creates the Python types of one WinRT namespace from its projection table.
+
+    A projection package ships a table rather than an extension module, so this
+    is what its ``__init__.py`` calls before anything else: the runtime reads
+    the table beside it and builds the classes, interfaces and structs straight
+    into the module. Everything after that line - the enums, the delegate
+    aliases, the protocol mixins - is ordinary Python that expects them to be
+    there.
+
+    Args:
+        spec: The module's own ``__spec__``, which says where it was loaded
+            from and therefore where its table is.
+    """
+    if not spec.origin:
+        raise ImportError(f"{spec.name} was not loaded from a file")
+
+    table = os.fspath(Path(spec.origin).parent / TABLE_NAME)
+
+    try:
+        _load_projection(sys.modules[spec.name], table)
+    except OSError as error:
+        # The table is opened and mapped, so a missing or unreadable one
+        # arrives here as an OSError that says only what the operating system
+        # said - no file name, no module. That is nearly always a package
+        # whose module was copied without the data file beside it, which is
+        # what a freezer does when nothing tells it about the table, so the
+        # message has to name both and say what kind of thing is missing.
+        raise ImportError(
+            f"{spec.name} could not read its projection table, which a"
+            " projection package carries beside the module that loads it."
+            f" Reading {table} failed: {error}",
+            name=spec.name,
+            path=table,
+        ) from error
+
+
+class WinrtIntEnum(IntEnum):
+    """
+    The base of every projected WinRT enum that is not a set of flags.
+
+    A newer version of Windows can hand back a value that the projection was
+    generated without, so a value with no member of its own makes a member
+    of its own, rather than a ``ValueError`` that fails the call it came from,
+    as ``IntFlag`` keeps a bit it has no member for. Such a member equals its
+    number, is named with it, as in ``"99"``, which no member name can be, and
+    does not appear when the enum is iterated.
+    """
+
+    @classmethod
+    def _missing_(cls, value: object) -> Self | None:
+        # A WinRT enum that is not a set of flags is a signed 32-bit integer,
+        # so a value WinRT could not hold is still refused.
+        if not isinstance(value, int) or not -(2**31) <= value < 2**31:
+            return None
+
+        # A bool, or a member of another enum, is made the plain number that
+        # every member holds.
+        number = int(value)
+
+        member = int.__new__(cls, number)
+        member._name_ = str(number)
+        member._value_ = number
+        return member
+
+    def __repr__(self) -> str:
+        if self._name_ not in type(self)._member_map_:
+            return f"<{type(self).__name__}: {self._value_!r}>"
+
+        return super().__repr__()
+
+
+# Staged deprecation of the method names that pywinrt v3.x used for overloaded
+# methods. DeprecationWarning is aimed at developers of code that uses pywinrt.
+# In a future release, this will become FutureWarning, which is shown to end
+# users as well, and after that the aliases will be removed.
+# https://docs.python.org/3/library/exceptions.html#DeprecationWarning
+#
+# NB: The calls to the functions below are generated. See the note on the
+# aliases in PyWinRT/Projection/ProjectedType.cs for everything that has to be
+# removed when the aliases go away.
+_LEGACY_METHOD_WARNING: type[Warning] = DeprecationWarning
+
+
+def _add_alias(target: type, owner: type, alias: str, name: str) -> None:
+    # a real attribute of the type always wins over an alias
+    if alias in vars(target):
+        return
+
+    def method(self: Any, *args: Any) -> Any:
+        warnings.warn(
+            f"{owner.__name__}.{alias}() is deprecated, use {name}() instead",
+            _LEGACY_METHOD_WARNING,
+            stacklevel=2,
+        )
+        return getattr(self, name)(*args)
+
+    method.__name__ = alias
+    method.__qualname__ = f"{owner.__name__}.{alias}"
+    method.__doc__ = f"Deprecated alias of ``{name}()``."
+
+    setattr(target, alias, method)
+
+
+def alias_method(typ: type, alias: str, name: str) -> None:
+    """
+    Adds a deprecated alias of a method to a projected type.
+
+    Args:
+        typ: The projected type.
+        alias: The name the method had in pywinrt v3.x.
+        name: The name of the method now.
+    """
+    _add_alias(typ, typ, alias, name)
+
+
+def alias_static_method(typ: type, alias: str, name: str) -> None:
+    """
+    Adds a deprecated alias of a static method to a projected type.
+
+    Args:
+        typ: The projected type.
+        alias: The name the method had in pywinrt v3.x.
+        name: The name of the method now.
+    """
+    # static methods are implemented by the metaclass of the projected type
+    _add_alias(type(typ), typ, alias, name)
+
+
+def alias_field(typ: type, name: str) -> None:
+    """
+    Adds a deprecated property for the one field a projected type used to have.
+
+    A WinRT struct that holds a single integer - an HRESULT, an event token -
+    is projected as a subclass of ``int`` rather than as a wrapper, so the
+    value is the object itself. Reading the field by the name it had in
+    pywinrt v3.x still works and warns.
+
+    Args:
+        typ: The projected type.
+        name: The name the field had.
+    """
+
+    def field(self: Any) -> Any:
+        warnings.warn(
+            f"{typ.__name__}.{name} is deprecated, "
+            f"the value is the {typ.__name__} itself",
+            _LEGACY_METHOD_WARNING,
+            stacklevel=2,
+        )
+        return int(self)
+
+    field.__name__ = name
+    field.__qualname__ = f"{typ.__name__}.{name}"
+    field.__doc__ = f"Deprecated: the value is the {typ.__name__} itself."
+
+    setattr(typ, name, property(field))
+
+
+# NB: The types implemented in C cannot inherit from abc.ABC since Python 3.12
+# so we have to implement the protocols like this instead.
+# https://github.com/python/cpython/issues/103968#issuecomment-1589928055
+
+
+def _register(abc_type: type, typ: type) -> None:
+    """
+    Registers typ as a virtual subclass of abc_type.
+
+    The collections.abc types are ABCMeta instances at run time, but typeshed
+    derives most of them from typing.Protocol without saying so, which leaves
+    pyright without their register() method.
+    """
+    cast(ABCMeta, abc_type).register(typ)
+
+
+def _sequence_index(
+    self: Sequence[Any], value: Any, start: int = 0, stop: int = sys.maxsize
+) -> int:
+    """
+    Sequence.index(), with a message like the one list.index() gives rather
+    than none at all. It names a vector rather than the type, which may be a
+    wrapper such as _IVector[String] that the user never sees.
+    """
+    try:
+        return Sequence[Any].index(self, value, start, stop)
+    except ValueError:
+        raise ValueError("index(x): x not in vector") from None
+
+
+def _mutable_sequence_remove(self: MutableSequence[Any], value: Any) -> None:
+    """
+    MutableSequence.remove(), with a message like the one list.remove() gives.
+    """
+    try:
+        index = Sequence[Any].index(self, value)
+    except ValueError:
+        raise ValueError("remove(x): x not in vector") from None
+
+    del self[index]
+
+
+def _mutable_mapping_popitem(self: MutableMapping[Any, Any]) -> tuple[Any, Any]:
+    """
+    MutableMapping.popitem(), with a message like the one dict.popitem() gives.
+    """
+    try:
+        key = next(iter(self))
+    except StopIteration:
+        raise KeyError("popitem(): map is empty") from None
+
+    value = self[key]
+    del self[key]
+    return key, value
+
+
+def mixin_sequence(typ: type) -> None:
+    """
+    Adds missing Python mapping methods to types that implement IVectorView and
+    registers the type as a Sequence.
+    """
+    # mixin methods
+    if not hasattr(typ, "index"):
+        setattr(typ, "index", _sequence_index)
+
+    if not hasattr(typ, "count"):
+        setattr(typ, "count", Sequence[Any].count)
+
+    if not hasattr(typ, "__contains__"):
+        setattr(typ, "__contains__", Sequence[Any].__contains__)
+
+    if not hasattr(typ, "__iter__"):
+        setattr(typ, "__iter__", Sequence[Any].__iter__)
+
+    if not hasattr(typ, "__reversed__"):
+        setattr(typ, "__reversed__", Sequence[Any].__reversed__)
+
+    _register(Sequence, typ)
+
+
+def mixin_mutable_sequence(typ: type) -> None:
+    """
+    Adds missing Python mapping methods to types that implement IVector and
+    registers the type as a MutableSequence.
+    """
+    mixin_sequence(typ)
+
+    # mixin methods
+    if not hasattr(typ, "append"):
+        setattr(typ, "append", MutableSequence[Any].append)
+
+    if not hasattr(typ, "clear"):
+        setattr(typ, "clear", MutableSequence[Any].clear)
+
+    if not hasattr(typ, "extend"):
+        setattr(typ, "extend", MutableSequence[Any].extend)
+
+    if not hasattr(typ, "reverse"):
+        setattr(typ, "reverse", MutableSequence[Any].reverse)
+
+    if not hasattr(typ, "pop"):
+        setattr(typ, "pop", MutableSequence[Any].pop)
+
+    if not hasattr(typ, "remove"):
+        setattr(typ, "remove", _mutable_sequence_remove)
+
+    if not hasattr(typ, "__iadd__"):
+        setattr(typ, "__iadd__", MutableSequence[Any].__iadd__)
+
+    _register(MutableSequence, typ)
+
+
+def mixin_mapping(typ: type) -> None:
+    """
+    Adds missing Python mapping methods to types that implement IMapView and
+    registers the type as a Mapping.
+    """
+    # mixin methods
+    if not hasattr(typ, "keys"):
+        setattr(typ, "keys", Mapping[Any, Any].keys)
+
+    if not hasattr(typ, "items"):
+        setattr(typ, "items", Mapping[Any, Any].items)
+
+    if not hasattr(typ, "values"):
+        setattr(typ, "values", Mapping[Any, Any].values)
+
+    if not hasattr(typ, "get"):
+        setattr(typ, "get", Mapping[Any, Any].get)
+
+    if not hasattr(typ, "__contains__"):
+        setattr(typ, "__contains__", Mapping[Any, Any].__contains__)
+
+    # HACK: Version check works around inheritance anomaly caused by hacky
+    # metaclass inheritance implementation in runtime.cpp. This works as long
+    # as we don't change the projection to implement rich comparison methods
+    # on mapping types.
+
+    if (
+        typ.__eq__ == object.__eq__
+        or typ.__eq__ == Object.__eq__
+        or sys.version_info < (3, 12)
+    ):
+        setattr(typ, "__eq__", Mapping[Any, Any].__eq__)
+        # Equal maps are different objects, so an identity hash would break
+        # hash(a) == hash(b) for a == b. A class derived from Mapping is
+        # unhashable for the same reason.
+        setattr(typ, "__hash__", None)
+
+    if (
+        typ.__ne__ == object.__ne__
+        or typ.__ne__ == Object.__ne__
+        or sys.version_info < (3, 12)
+    ):
+        setattr(typ, "__ne__", Mapping[Any, Any].__ne__)
+
+    _register(Mapping, typ)
+
+
+def mixin_mutable_mapping(typ: type) -> None:
+    """
+    Adds missing Python mapping methods to types that implement IMap and
+    registers the type as a MutableMapping.
+    """
+    mixin_mapping(typ)
+
+    # mixin methods
+    if not hasattr(typ, "clear"):
+        setattr(typ, "clear", MutableMapping[Any, Any].clear)
+
+    if not hasattr(typ, "pop"):
+        setattr(typ, "pop", MutableMapping[Any, Any].pop)
+        # private-name-mangled attribute :-(
+        setattr(
+            typ,
+            "_MutableMapping__marker",
+            getattr(MutableMapping, "_MutableMapping__marker"),
+        )
+
+    if not hasattr(typ, "popitem"):
+        setattr(typ, "popitem", _mutable_mapping_popitem)
+
+    if not hasattr(typ, "setdefault"):
+        setattr(typ, "setdefault", MutableMapping[Any, Any].setdefault)
+
+    if not hasattr(typ, "update"):
+        setattr(typ, "update", MutableMapping[Any, Any].update)
+
+    _register(MutableMapping, typ)
+
+
+T = TypeVar("T")
+
+
+# MyPy wants covariant T but Pylance wants invariant. Invariant seems correct.
+class AsyncOp(Protocol[T]):  # type: ignore [misc]
+    """
+    Protocol that matches the four async interfaces.
+    """
+
+    def cancel(self) -> None: ...
+    @property
+    def status(self) -> "AsyncStatus": ...
+    def get_results(self) -> T: ...
+    @property
+    def completed(self) -> Callable[[Self, "AsyncStatus"], None]: ...
+    @completed.setter
+    def completed(self, value: Callable[[Self, "AsyncStatus"], None]) -> None: ...
+
+
+async def wrap_async(op: AsyncOp[T]) -> T:
+    """
+    What ``await`` of an async operation runs.
+
+    An operation that has finished already is answered from
+    ``get_results()``. Otherwise the completed handler wakes the coroutine,
+    and the status, which can read ``COMPLETED`` before the handler has run,
+    is not asked again.
+
+    Cancelling the task asks WinRT to cancel the operation and goes on
+    waiting, so that nothing is left running behind a task that has moved on,
+    and the cancellation is raised once the operation has finished. Cancelling
+    the task again while it waits for that gives up waiting, and if the
+    operation then fails, the error goes to the loop's exception handler, as
+    an error that nothing retrieved from a future does.
+    """
+    from winrt.windows.foundation import AsyncStatus
+
+    if op.status != AsyncStatus.STARTED:
+        return op.get_results()
+
+    loop = asyncio.get_running_loop()
+    event = asyncio.Event()
+    abandoned = False
+
+    def report(finished: AsyncOp[T]) -> None:
+        try:
+            finished.get_results()
+        except Exception as error:
+            loop.call_exception_handler(
+                {
+                    "message": "async operation failed after the task "
+                    "awaiting it gave up waiting for it",
+                    "exception": error,
+                    "operation": finished,
+                }
+            )
+
+    def deliver(finished: AsyncOp[T], status: "AsyncStatus") -> None:
+        if not abandoned:
+            event.set()
+        elif status == AsyncStatus.ERROR:
+            report(finished)
+
+    # WinRT keeps the handler for as long as the operation exists, and the
+    # event reaches this coroutine and so the operation, through the task
+    # waiting for it. The handler lets go of what it delivers to when it runs,
+    # which breaks that cycle even when there is no loop left to deliver on.
+    pending: Callable[[AsyncOp[T], AsyncStatus], None] | None = deliver
+
+    def completed(finished: AsyncOp[T], status: "AsyncStatus") -> None:
+        nonlocal pending
+        delivery, pending = pending, None
+
+        if delivery is None:
+            return
+
+        try:
+            loop.call_soon_threadsafe(delivery, finished, status)
+        except RuntimeError:
+            # The loop is closed. A task left waiting is reported by asyncio
+            # when it is freed, so only an error that nothing will wait for
+            # is reported here, which a closed loop can still be asked to do.
+            if abandoned and status == AsyncStatus.ERROR:
+                report(finished)
+
+    op.completed = completed
+
+    try:
+        await event.wait()
+    except asyncio.CancelledError:
+        op.cancel()
+
+        try:
+            await event.wait()
+        except asyncio.CancelledError:
+            abandoned = True
+            raise
+
+        raise
+
+    return op.get_results()

winrt/runtime/interop.py

@@ -0,0 +1,25 @@
+from typing import NewType
+
+from typing_extensions import CapsuleType
+
+from winrt._winrt import (
+    as_interface,
+    get_activation_factory,
+    hresult_error,
+    initialize_with_window,
+    wrap_interface,
+)
+
+__all__ = [
+    "InterfaceCapsule",
+    "as_interface",
+    "get_activation_factory",
+    "hresult_error",
+    "initialize_with_window",
+    "wrap_interface",
+]
+
+# A capsule named "winrt.interface" that holds one reference to a COM interface,
+# which its destructor releases. It is how a WinRT object crosses between the
+# runtime and a compiled interop module, which share no C ABI.
+InterfaceCapsule = NewType("InterfaceCapsule", CapsuleType)

winrt/system/__init__.py

@@ -0,0 +1,191 @@
+from typing import TYPE_CHECKING, Annotated, Any, Protocol, TypeAlias, runtime_checkable
+import warnings
+
+from typing_extensions import Buffer as _Buffer, deprecated
+
+from winrt._winrt import (
+    Array,
+    Object,
+    Object_Static,
+    box_boolean,
+    box_char16,
+    box_date_time,
+    box_double,
+    box_guid,
+    box_int8,
+    box_int16,
+    box_int32,
+    box_int64,
+    box_single,
+    box_string,
+    box_time_span,
+    box_uint8,
+    box_uint16,
+    box_uint32,
+    box_uint64,
+    unbox_boolean,
+    unbox_char16,
+    unbox_date_time,
+    unbox_double,
+    unbox_guid,
+    unbox_int8,
+    unbox_int16,
+    unbox_int32,
+    unbox_int64,
+    unbox_single,
+    unbox_string,
+    unbox_time_span,
+    unbox_uint8,
+    unbox_uint16,
+    unbox_uint32,
+    unbox_uint64,
+)
+import winrt.runtime._internals
+
+
+class BufferFormat(str):
+    """
+    The `PEP 3118`_ buffer format of a WinRT fundamental type.
+
+    This is what :attr:`memoryview.format` reports for an :class:`Array` of
+    that type and what :class:`Array` accepts in place of the type.
+
+    .. _PEP 3118: https://peps.python.org/pep-3118/
+    """
+
+    __slots__ = ()
+
+    _annotation_kind_ = "buffer_format"
+
+
+class StructFormat(str):
+    """
+    The :mod:`struct` module format of a WinRT fundamental type.
+
+    It is the same character as the buffer format for every type but
+    ``Char16``, where it is ``"H"``, because :mod:`struct` has no ``"u"``
+    format at all.
+    """
+
+    __slots__ = ()
+
+    _annotation_kind_ = "struct_format"
+
+
+class WinrtSignature(str):
+    """
+    The WinRT type signature of a WinRT fundamental type.
+
+    The signature of a parameterized type is composed from the signatures of
+    its type arguments, and its interface identifier is hashed from that.
+    """
+
+    __slots__ = ()
+
+    _annotation_kind_ = "winrt_signature"
+
+
+# The fundamental types that no Python type names on its own, each annotated
+# with one spelling of what it is per kind of format. A consumer finds the one
+# it wants by isinstance over typing.get_args(), never by position.
+Int8 = Annotated[int, BufferFormat("b"), StructFormat("b"), WinrtSignature("i1")]
+UInt8 = Annotated[int, BufferFormat("B"), StructFormat("B"), WinrtSignature("u1")]
+Int16 = Annotated[int, BufferFormat("h"), StructFormat("h"), WinrtSignature("i2")]
+UInt16 = Annotated[int, BufferFormat("H"), StructFormat("H"), WinrtSignature("u2")]
+Int32 = Annotated[int, BufferFormat("i"), StructFormat("i"), WinrtSignature("i4")]
+UInt32 = Annotated[int, BufferFormat("I"), StructFormat("I"), WinrtSignature("u4")]
+Int64 = Annotated[int, BufferFormat("q"), StructFormat("q"), WinrtSignature("i8")]
+UInt64 = Annotated[int, BufferFormat("Q"), StructFormat("Q"), WinrtSignature("u8")]
+Single = Annotated[float, BufferFormat("f"), StructFormat("f"), WinrtSignature("f4")]
+Double = Annotated[float, BufferFormat("d"), StructFormat("d"), WinrtSignature("f8")]
+Char16 = Annotated[str, BufferFormat("u"), StructFormat("H"), WinrtSignature("c2")]
+
+winrt.runtime._internals.mixin_sequence(Array)
+
+# What an IBuffer or an array parameter takes besides an Array: any buffer,
+# named for whether WinRT reads it or writes into it, as typeshed's aliases of
+# the same names are.
+ReadableBuffer: TypeAlias = _Buffer
+WriteableBuffer: TypeAlias = _Buffer
+
+# PEP 702 deprecates a class or a function, not an alias, so the type checkers
+# see a deprecated copy of typeshed's collections.abc.Buffer, and the real one
+# is what __getattr__() hands out at run time.
+if TYPE_CHECKING:
+
+    @deprecated(
+        "Use collections.abc.Buffer instead, "
+        "or typing_extensions.Buffer before Python 3.12"
+    )
+    @runtime_checkable
+    class Buffer(Protocol):
+        def __buffer__(self, flags: int, /) -> memoryview: ...
+
+else:
+
+    def __getattr__(name: str) -> Any:
+        if name == "Buffer":
+            warnings.warn(
+                "winrt.system.Buffer is deprecated: use collections.abc.Buffer, "
+                "or typing_extensions.Buffer before Python 3.12",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            return _Buffer
+
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    "BufferFormat",
+    "StructFormat",
+    "WinrtSignature",
+    "Int8",
+    "UInt8",
+    "Int16",
+    "UInt16",
+    "Int32",
+    "UInt32",
+    "Int64",
+    "UInt64",
+    "Single",
+    "Double",
+    "Char16",
+    "Object",
+    "Object_Static",
+    "Array",
+    "ReadableBuffer",
+    "WriteableBuffer",
+    "box_boolean",
+    "box_int8",
+    "box_uint8",
+    "box_int16",
+    "box_uint16",
+    "box_int32",
+    "box_uint32",
+    "box_int64",
+    "box_uint64",
+    "box_single",
+    "box_double",
+    "box_char16",
+    "box_string",
+    "box_guid",
+    "box_date_time",
+    "box_time_span",
+    "unbox_boolean",
+    "unbox_int8",
+    "unbox_uint8",
+    "unbox_int16",
+    "unbox_uint16",
+    "unbox_int32",
+    "unbox_uint32",
+    "unbox_int64",
+    "unbox_uint64",
+    "unbox_single",
+    "unbox_double",
+    "unbox_char16",
+    "unbox_string",
+    "unbox_guid",
+    "unbox_date_time",
+    "unbox_time_span",
+]

winrt/system/hresult.py

@@ -0,0 +1,47 @@
+"""Common HRESULT error codes."""
+
+from winrt.windows.foundation import HResult
+
+# https://learn.microsoft.com/en-us/windows/win32/debug/system-error-codes--0-499-
+_ERROR_FILE_NOT_FOUND = 2
+
+# https://learn.microsoft.com/en-us/windows/win32/debug/system-error-codes--1000-1299-
+_ERROR_CANCELLED = 1223
+
+
+# https://learn.microsoft.com/en-us/windows/win32/api/winerror/nf-winerror-hresult_facility
+_FACILITY_WIN32 = 7
+
+
+# https://learn.microsoft.com/en-us/windows/win32/api/winerror/nf-winerror-hresult_from_win32
+def _HRESULT_FROM_WIN32(error_code: int) -> HResult:
+    x = HResult(error_code)
+    return (
+        x
+        if x <= 0
+        else HResult((x & 0x0000FFFF) | (_FACILITY_WIN32 << 16) | 0x80000000)
+    )
+
+
+# common errors from CppWinRT
+S_OK = HResult(0)
+E_FAIL = HResult(0x80004005)
+E_ACCESSDENIED = HResult(0x80070005)
+E_NOTIMPL = HResult(0x80004001)
+E_INVALIDARG = HResult(0x80070057)
+E_BOUNDS = HResult(0x8000000B)
+E_NOINTERFACE = HResult(0x80004002)
+E_CHANGED_STATE = HResult(0x8000000C)
+E_ILLEGAL_METHOD_CALL = HResult(0x8000000E)
+E_ILLEGAL_STATE_CHANGE = HResult(0x8000000D)
+E_ILLEGAL_DELEGATE_ASSIGNMENT = HResult(0x80000018)
+E_OUTOFMEMORY = HResult(0x8007000E)
+CLASS_E_CLASSNOTAVAILABLE = HResult(0x80040111)
+CO_E_NOTINITIALIZED = HResult(0x800401F0)
+REGDB_E_CLASSNOTREG = HResult(0x80040154)
+RPC_E_WRONG_THREAD = HResult(0x8001010E)
+WIN32_ERROR_FILE_NOT_FOUND = _HRESULT_FROM_WIN32(_ERROR_FILE_NOT_FOUND)
+WIN32_ERROR_CANCELLED = _HRESULT_FROM_WIN32(_ERROR_CANCELLED)
+
+# Errors defined by PyWinRT
+PYWINRT_E_UNRAISABLE_PYTHON_EXCEPTION = HResult(0xA0EE4005)

winrt_runtime-4.0.0.dist-info/METADATA

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: winrt-runtime
+Version: 4.0.0
+Summary: The runtime that every PyWinRT projection package runs on
+License-Expression: MIT
+Project-URL: Documentation, https://pywinrt.readthedocs.io
+Project-URL: Repository, https://github.com/pywinrt/pywinrt
+Project-URL: Changelog, https://github.com/pywinrt/pywinrt/blob/main/runtime/CHANGELOG.md
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: Free Threading :: 2 - Beta
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typing_extensions>=4.12.2
+Dynamic: license-file
+
+# winrt-runtime
+
+This package provides the PyWinRT runtime including the `winrt.system` module.
+
+Every PyWinRT package requires it, so pip installs it with any of them. Each
+WinRT namespace is a package of its own, so install the package of each
+namespace your code imports from, such as `winrt-Windows.Foundation`.
+
+## For interop modules
+
+Compiled code outside the runtime, such as the interop packages, exchanges
+WinRT objects with it through the Python functions of `winrt.runtime.interop`
+rather than a C ABI: `as_interface()` gives an interface of a projected object
+as an interface pointer capsule, `wrap_interface()` makes a projected object of
+one, and `hresult_error()` builds the exception that a failed call raises. An interface pointer capsule is named `"winrt.interface"`
+and holds one reference, which its destructor releases.

winrt_runtime-4.0.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+winrt/_winrt.cp315-win32.pyd,sha256=qPb_-b7rZYMByWIHCUayYzoLWGoklUBcv1gbBYpB998,489984
+winrt/_winrt.pyi,sha256=3lFW6xIHTrSPUjYp7CLIJx7vvCuNeHiN6RJa8gkqS20,6444
+winrt/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+winrt/__pyinstaller/__init__.py,sha256=rmXUl7CBERuK6iPwf_hIrpM67iJMGKds-ugl9XB5xb8,336
+winrt/__pyinstaller/hook-winrt.py,sha256=wIsqk5iXLgIO3ktYqmoEhd3tatD0ODY_wcM3RbDrLj0,3201
+winrt/runtime/__init__.py,sha256=XDwoFBCKJWVWHYDEQh6t5EhOkd776ThHllH93bUWuKo,648
+winrt/runtime/_internals.py,sha256=f0lbSO6sBk5XHf80m8YknjMjHmCRz6PWJn1siLOdziQ,16328
+winrt/runtime/interop.py,sha256=91zDKvOCPJzSWg8FtBYcdXMTBq16kOTvZqZEYFemtYA,658
+winrt/runtime/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+winrt/system/__init__.py,sha256=szmgICmY0yBtzUYc_vYWnMKKvQvDXYqQUdm1uf_O8Ss,5103
+winrt/system/hresult.py,sha256=J_CKmHtqTL4JFv-JTpdSTAMeHHAm_UjFPNJ5ulgZXxE,1579
+winrt/system/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+winrt_runtime-4.0.0.dist-info/licenses/LICENSE,sha256=dyVKOMqPV0fimbzMhqN3zpg6K6Y2OlekwrdfiZTBm8M,1225
+winrt_runtime-4.0.0.dist-info/METADATA,sha256=ZL6UORpX-KV0eesu2fHTRmhw2y6XG76dZwM_UldFizo,1963
+winrt_runtime-4.0.0.dist-info/WHEEL,sha256=hw69xxiYuOcOqid9WoScsymTbZ3eDs5HQ4gUZZtdDhs,97
+winrt_runtime-4.0.0.dist-info/entry_points.txt,sha256=9q8Xbd5-xvYTUwc1m7ddw7ln0lBVYxnGjmB8ot_uCWc,62
+winrt_runtime-4.0.0.dist-info/top_level.txt,sha256=BzwQb4dZRt0NxCXi10ARjWsox7Asmtf_lXrw_KR-D_E,6
+winrt_runtime-4.0.0.dist-info/RECORD,,

winrt_runtime-4.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: false
+Tag: cp315-cp315-win32
+

winrt_runtime-4.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[pyinstaller40]
+hook-dirs = winrt.__pyinstaller:get_hook_dirs

winrt_runtime-4.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+    MIT License
+
+    Copyright (c) Microsoft Corporation. All rights reserved.
+    Copyright (c) 2021-2026 David Lechner <david@pybricks.com>
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE

winrt_runtime-4.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+winrt