Metadata-Version: 2.4
Name: pywinui
Version: 0.1.0a1
Summary: Build native WinUI 3 (Windows App SDK) desktop apps in idiomatic Python
Project-URL: Homepage, https://github.com/israel-dryer/pywinui
Project-URL: Repository, https://github.com/israel-dryer/pywinui
Project-URL: Issues, https://github.com/israel-dryer/pywinui/issues
Author-email: Israel Dryer <israel.dryer@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Israel Dryer
        
        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.
License-File: LICENSE
Keywords: desktop,gui,windows,windows-app-sdk,winrt,winui,winui3
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Win32 (MS Windows)
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows :: Windows 10
Classifier: Operating System :: Microsoft :: Windows :: Windows 11
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: User Interfaces
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: winrt-windows-foundation<4,>=3.2; sys_platform == 'win32'
Requires-Dist: winui3-microsoft-ui-dispatching<4,>=3.2; sys_platform == 'win32'
Requires-Dist: winui3-microsoft-ui-xaml-controls<4,>=3.2; sys_platform == 'win32'
Requires-Dist: winui3-microsoft-ui-xaml<4,>=3.2; sys_platform == 'win32'
Requires-Dist: winui3-microsoft-windows-applicationmodel-dynamicdependency-bootstrap<4,>=3.2; sys_platform == 'win32'
Requires-Dist: winui3-microsoft-windows-applicationmodel-dynamicdependency<4,>=3.2; sys_platform == 'win32'
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: examples
Requires-Dist: winrt-windows-storage<4,>=3.2; (sys_platform == 'win32') and extra == 'examples'
Description-Content-Type: text/markdown

# PyWinUI

Build **native WinUI 3** (Windows App SDK) desktop applications in idiomatic Python.

Not a themed look-alike and not a reimplementation — these are real WinUI 3
controls, wrapped so that you never have to touch WinRT unless you want to.

```python
import pywinui as ui


class CounterApp(ui.App):
    def build(self):
        count = ui.TextBlock("0", font_size=32)

        def bump(sender, args):
            count.text = str(int(count.text) + 1)

        return ui.Window(
            title="PyWinUI Counter",
            content=ui.StackPanel(
                spacing=12, padding=24,
                children=[
                    ui.TextBlock("Counter", font_size=20),
                    count,
                    ui.Button("Increment", on_click=bump),
                ],
            ),
        )


CounterApp().run()
```

> **Status: early alpha.** The architecture is verified end-to-end against the
> real bindings on Windows 11, but only five controls are wrapped so far. The API
> may change. See [Current scope](#current-scope) before depending on it.

## Why now

The WinUI 3 projections for Python ([PyWinRT](https://github.com/pywinrt/pywinrt))
only landed in March 2025. Before that, a Python WinUI 3 app meant hand-rolling
raw WinRT. The bindings now exist and work; PyWinUI is the ergonomics layer on
top of them.

## Requirements

- **Windows 10/11** with the [Windows App Runtime](https://aka.ms/windowsappsdk/runtime)
- **python.org Python 3.10+** — *not* the Microsoft Store build, which is a
  packaged app and fails the runtime bootstrap with `ERROR_NOT_SUPPORTED`

## Install

```
pip install pywinui
```

The `winui3-*` dependencies are Windows-only and install automatically there.
On other platforms the package still installs and imports (the native layer is
loaded lazily), so the test suite and editor tooling work anywhere — but
anything that realizes a control needs Windows.

## Two ways to build a tree

Both are first-class and they compose.

```python
# Flutter style — the tree is a value. Best for reusable components.
ui.StackPanel(children=[ui.TextBlock("a"), ui.TextBlock("b")])

# With style — handles loops, conditionals and local references far better.
with ui.StackPanel() as panel:
    ui.TextBlock("Items")
    for name in items:
        ui.Button(name, on_click=make_handler(name))
```

## Async without the ceremony

Handlers may be `async def`. They're scheduled off the UI thread automatically,
WinRT async operations are awaited like any coroutine, and writes back to
widgets are marshalled onto the UI thread for you.

```python
async def read_file(sender, args):
    status.text = "Reading..."
    file = await StorageFile.get_file_from_path_async(path)
    text = await FileIO.read_text_async(file)      # real WinRT I/O
    status.text = f"{len(text)} chars"             # marshalled back to the UI
```

Failures arrive as ordinary Python exceptions — a missing path raises
`FileNotFoundError`.

## The escape hatch

The curated surface covers the common path with type hints, validation and value
conversions. Anything not wrapped still forwards by name, and `widget.native`
gives you the raw WinUI control:

```python
btn = ui.Button("Save")
btn.native.background = some_brush    # raw WinUI, fully supported
```

## Current scope

| Working | Not yet |
|---|---|
| `TextBlock`, `TextBox`, `Button`, `StackPanel`, `Grid`, `Window` | The other ~100 WinUI controls |
| Both tree-building styles, attach/detach | Data binding, styles, resource dictionaries |
| `async def` handlers, awaiting WinRT ops | Control templates, virtualized lists |
| Off-thread writes auto-marshalled | Off-thread *reads* (wrap in `run_on_ui`) |
| `padding`/`margin`, `visible`, content boxing | `Grid.Row`/`Grid.Column` attached properties |
| Running from a Python environment | Packaging a double-clickable app (MSIX) |

**Packaging is unproven.** Shipping an app to end users means bundling Python and
the Windows App Runtime, likely as MSIX, and that path has not been prototyped.
Today this is a library for developers who already have Python installed.

## Troubleshooting

**`DLL load failed ... The filename or extension is too long`** — your virtual
environment path is too deep. The winui3 extension modules have very long file
names (`_winui3_microsoft_windows_applicationmodel_dynamicdependency_bootstrap`),
and a nested venv can push them past Windows' 260-character `MAX_PATH`. Use a
shorter path, or [enable long paths](https://learn.microsoft.com/windows/win32/fileio/maximum-file-path-limitation).

**`ERROR_NOT_SUPPORTED` during bootstrap** — you're on the Microsoft Store build
of Python, which is itself a packaged app. Use the python.org installer.

## Examples

```
pip install -e ".[examples,dev]"
python examples/counter.py
python examples/async_file_read.py
```

## Tests

```
pytest
```

The suite runs **anywhere** — no Windows required. It swaps in a fake native
layer to lock down the tree model, both building styles, attach/detach, property
forwarding, value conversions and thread marshalling. What it deliberately
cannot cover is the binding boundary itself; that is verified by running the
examples on Windows.

## License

MIT
