winrt.system module¶

Type aliases¶

Buffer¶

type Buffer

Alias of collections.abc.Buffer. The type hints of what goes into WinRT name it as ReadableBuffer or WriteableBuffer, which say whether WinRT reads the buffer or writes into it.

ReadableBuffer¶

type ReadableBuffer

Alias of collections.abc.Buffer that says WinRT only reads the buffer, as the same name says in the standard library's type hints. The type hints use it for an IBuffer that goes in, and beside Array for an array parameter that WinRT reads. A type checker sees only Buffer. An IBuffer takes the bytes of any buffer, and an array checks the layout when the method is called: a buffer whose layout is not that of the array's element type raises BufferError.

WriteableBuffer¶

type WriteableBuffer

Alias of collections.abc.Buffer that says WinRT writes into the buffer, as the same name says in the standard library's type hints. The type hints use it for an IBuffer that WinRT fills, and beside Array for an array parameter that WinRT fills. A type checker sees only Buffer, so the buffer is checked when the method is called. A read-only one, such as bytes, raises TypeError for an IBuffer and BufferError for an array, as does one whose layout is not that of the array's element type.

Annotations¶

The aliases this module gives the WinRT fundamental types that no Python type names on its own - Int8, UInt8, Int16, UInt16, Int32, UInt32, Int64, UInt64, Single, Double and Char16 - are typing.Annotated aliases of the Python type each one is projected as. The annotations say what that WinRT type is called in each of three languages, and each one is found by its own class:

from typing import get_args
from winrt.system import Int32, WinrtSignature

signature = next(
    a for a in get_args(Int32)[1:] if isinstance(a, WinrtSignature)
)

BufferFormat¶

class BufferFormat(str)

The PEP 3118 buffer format of a WinRT fundamental type, such as "i" for Int32. This is what memoryview.format reports for an Array of that type.

StructFormat¶

class StructFormat(str)

The 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 struct has no "u" format at all.

WinrtSignature¶

class WinrtSignature(str)

The WinRT type signature of a WinRT fundamental type, such as "i4" for Int32. The signature of a parameterized type is composed from the signatures of its type arguments, and its interface identifier is hashed from that.

Fundamental types¶

Object¶

class Object

A wrapper around the WinRT System.Object type.

This is the base type of all WinRT runtime objects and cannot be instantiated directly. A Python class that implements a WinRT interface is an Object too: isinstance() and issubclass() say so, although it does not derive from Object, which holds a WinRT object that a Python implementation does not have, and its instances have the members below, which answer what WinRT is told about them.

as_¶

as_(type, /)

The object as another interface it implements, or as its runtime class. Raises OSError if the object does not implement it, and TypeError if type is not a runtime class or an interface. See Query interface.

Introspection attributes

WinRT objects have the following attributes for inspecting them at runtime:

_runtime_class_name_¶

_runtime_class_name_: str

Gets the WinRT runtime class name of the object. A Python implementation of an interface is no runtime class, so it gives the name of the first interface among its class's bases: class Converter(IValueConverter) answers with the name of IValueConverter.

_iids_¶

_iids_: Array[uuid.UUID]

Gets the Interface Identifiers (IIDs) of the WinRT interfaces implemented by the object.

Object_Static¶

class Object_Static(type)

The metaclass of Object and of every projected class and interface. A class's static members are on a metaclass of its own, named after the class with _Static, such as Uri_Static, which derives from this one. The type hints name it, and code has no need to.

Array¶

class Array(type, [initializer, ] /)

A wrapper around the WinRT System.Array type.

This type implements the Python sequence protocol.

Creation examples:

from winrt.system import Array, UInt32
from winrt.windows.foundation import Point

# array of 10 32-bit unsigned integers.
a1 = Array(UInt32, 10)
# array of 3 points with initial values
a2 = Array(Point, [Point(1, 1), Point(2, 2), Point(3, 3)])

Sequence protocol examples:

# get the number of elements in the array
size = len(a1)
# get the first element of the array
item = a1[0]
# get the last element of the array
item = a1[-1]
# iterate all items of the array
for item in a1: ...
# test for element in array
if item in a1: ...

Boxing¶

Some APIs require a winrt.system.Object to be passed as a parameter. In order to pass other types like strings and numbers, they must be boxed. Likewise, when a method returns a winrt.system.Object, it may need to be unboxed to get the original value.

box_*¶

box_boolean(value: bool, /) -> Object
box_int8(value: typing.SupportsIndex, /) -> Object
box_uint8(value: typing.SupportsIndex, /) -> Object
box_int16(value: typing.SupportsIndex, /) -> Object
box_uint16(value: typing.SupportsIndex, /) -> Object
box_int32(value: typing.SupportsIndex, /) -> Object
box_uint32(value: typing.SupportsIndex, /) -> Object
box_int64(value: typing.SupportsIndex, /) -> Object
box_uint64(value: typing.SupportsIndex, /) -> Object
box_single(value: float, /) -> Object
box_double(value: float, /) -> Object
box_char16(value: str, /) -> Object
box_string(value: str, /) -> Object
box_guid(value: uuid.UUID, /) -> Object
box_date_time(value: datetime.datetime, /) -> Object
box_time_span(value: datetime.timedelta, /) -> Object

Boxes the given value into a winrt.system.Object.

Essentially, this is shorthand for calling:

from winrt.windows.foundation import PropertyValue

obj = PropertyValue.create_xyz(value)

unbox_*¶

unbox_boolean(value: Object, /) -> bool
unbox_int8(value: Object, /) -> int
unbox_uint8(value: Object, /) -> int
unbox_int16(value: Object, /) -> int
unbox_uint16(value: Object, /) -> int
unbox_int32(value: Object, /) -> int
unbox_uint32(value: Object, /) -> int
unbox_int64(value: Object, /) -> int
unbox_uint64(value: Object, /) -> int
unbox_single(value: Object, /) -> float
unbox_double(value: Object, /) -> float
unbox_char16(value: Object, /) -> str
unbox_string(value: Object, /) -> str
unbox_guid(value: Object, /) -> uuid.UUID
unbox_date_time(value: Object, /) -> datetime.datetime
unbox_time_span(value: Object, /) -> datetime.timedelta

Unboxes the given winrt.system.Object into the original value.

The value has to be boxed as that type: unbox_int32() takes what box_int32() makes, and not an Int16 or an Int64. The get_*() methods of IPropertyValue convert between numeric types where they can:

from winrt.windows.foundation import IPropertyValue

value = obj.as_(IPropertyValue).get_int32()

Raises: TypeError if the value is not boxed as that type.