Metadata-Version: 2.4
Name: gpyui
Version: 0.4.0
License-File: LICENSE
Summary: Native Python UI controls powered by GPUI and GPUI Kit
Author-email: Polina Gregor <polyxeni.gregor@gmail.com>
License-Expression: MIT
Requires-Python: >=3.12
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Changelog, https://github.com/gtrefalt/gpyui/blob/main/CHANGELOG.md
Project-URL: Documentation, https://gtrefalt.github.io/gpyui/
Project-URL: Homepage, https://gtrefalt.github.io/gpyui/
Project-URL: Issues, https://github.com/gtrefalt/gpyui/issues
Project-URL: Releases, https://github.com/gtrefalt/gpyui/releases
Project-URL: Repository, https://github.com/gtrefalt/gpyui

# gpyui

[![PyPI](https://img.shields.io/pypi/v/gpyui.svg)](https://pypi.org/project/gpyui/)
[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://pypi.org/project/gpyui/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/gtrefalt/gpyui/blob/main/LICENSE)
[![Documentation](https://img.shields.io/badge/docs-gpyui-teal.svg)](https://gtrefalt.github.io/gpyui/)

**Build native desktop applications in Python with GPUI Kit.**

gpyui is a Python UI toolkit for apps, tools and dashboards. Compose layouts,
bind state and handle events in Python, using Longbridge's
[GPUI Kit](https://github.com/longbridge/gpui-kit) components. The Rust backend,
powered by [GPUI](https://github.com/zed-industries/zed/tree/main/crates/gpui),
handles native windows, rendering and text editing.

[Documentation](https://gtrefalt.github.io/gpyui/) ·
[Component catalog](https://gtrefalt.github.io/gpyui/components/) ·
[Examples](https://github.com/gtrefalt/gpyui/tree/main/examples) ·
[Releases](https://github.com/gtrefalt/gpyui/releases)

![A native gpyui dashboard in light appearance, with a watchlist, price chart and paper-order controls](https://raw.githubusercontent.com/gtrefalt/gpyui/main/docs/screenshots/workspace-light.png)

A real native window built entirely through the Python API. The
[trading dashboard example](https://gtrefalt.github.io/gpyui/examples/trading/)
includes simulated quotes, streaming charts and async paper orders. See the
documentation for the animated walkthrough.

## Why gpyui?

- **Native components:** 72 Python controls spanning inputs, tables, charts,
  navigation, dialogs and feedback, backed by GPUI Kit.
- **Python composition:** build layouts with `Column`, `Row`, containers and
  context managers, or pass an explicit tree of controls.
- **State binding:** connect application state to text, inputs and selection
  controls with `State` and bindings.
- **Async events:** use regular functions or `async def` callbacks; property
  changes are queued and batched for native updates.
- **Shared commands:** use the same Python action from buttons, nested menus and
  platform-aware keyboard shortcuts.
- **Native themes:** macOS, Windows/Fluent and shadcn-inspired light/dark presets,
  custom palettes and live switching that preserves editor state.

## Installation

Requires **CPython 3.12+**. On macOS 12+ and Windows, install from PyPI:

```bash
uv init my-app
cd my-app
uv add gpyui
```

In an existing uv project, just run `uv add gpyui`. Alternatively, use
`pip install gpyui` in a virtual environment. Native wheels are available for
Intel/x64 and ARM64; Windows ARM64 is tested with Python 3.13+.

On **Linux**, install the matching prebuilt wheel from
[GitHub Releases](https://github.com/gtrefalt/gpyui/releases). Linux wheels use
system X11, font and Vulkan libraries and are currently distributed separately
from PyPI. See the [installation guide](https://gtrefalt.github.io/gpyui/guide/install/)
for runtime dependencies and source builds. Installing a wheel requires no Rust
compiler.

## Your first app

Save this as `hello.py`:

```python
from gpyui import Application, Button, Column, Label, TextInput

app = Application(title="Hello, gpyui", width=480, height=300, theme="light")

with app, Column().style(gap=12, padding=24):
    name = TextInput(placeholder="Your name")
    greeting = Label("Enter a name and choose Greet")

    def greet():
        greeting.text = f"Hello, {name.value or 'world'}!"

    Button("Greet", variant="primary", on_click=greet)

app.run()
```

Run `uv run python hello.py` (or `python hello.py` with pip). Clicking the native
button runs your Python callback and updates the label. Explore
[layouts](https://gtrefalt.github.io/gpyui/guide/layout/),
[state binding](https://gtrefalt.github.io/gpyui/guide/state/) and
[async events](https://gtrefalt.github.io/gpyui/guide/events/) for larger apps.

## Documentation and examples

Choose a native preset with `Application(theme=Theme("macos"))` or
`Theme("windows", mode="dark")`. Customize colors, corner radii and typography;
switch a running app by assigning `app.theme`. These are styles for Kit controls,
with platform-owned window decorations. See [themes and native previews](https://gtrefalt.github.io/gpyui/guide/themes/)
and the [appearance example](https://github.com/gtrefalt/gpyui/blob/main/examples/appearance.py).

The [documentation](https://gtrefalt.github.io/gpyui/) includes a visual catalog
with real native previews, properties, events and runnable examples for every
control, plus guides for styling, application lifecycle and release builds.

Try the [trading dashboard](https://gtrefalt.github.io/gpyui/examples/trading/),
[notes editor](https://gtrefalt.github.io/gpyui/examples/notes/),
[component gallery](https://gtrefalt.github.io/gpyui/examples/gallery/) or
[async binding example](https://github.com/gtrefalt/gpyui/blob/main/examples/async_binding.py).

## Agent skills

Give your coding agent the Python API, component contracts, async recipes and
native desktop design guidance:

```bash
npx skills add gtrefalt/gpyui --skill gpyui --skill gpyui-design-guides
```

Inspired by [GPUI Kit's skills](https://github.com/longbridge/gpui-kit/tree/main/skills),
these skills cover the Python bindings and their current limits. See
[installation and usage](https://gtrefalt.github.io/gpyui/agent-skills/), including
manual installation for Codex. Python dependencies use uv; the command above
installs agent instructions.

## Project status

gpyui is in early development. The component catalog has initial Python wrappers;
specialized Kit APIs are still being exposed. Applications currently use one
window with dynamic children and visibility. Existing controls retain their native
identity and editing state when moved or hidden. See the
[coverage and roadmap](https://gtrefalt.github.io/gpyui/component-coverage/) for
supported features and planned work.

Release wheels are tested on Linux, macOS and Windows across x64 and ARM64.
Linux/X11 has native interaction tests; macOS and Windows have native window,
state and lifecycle smoke tests. See [release support](https://gtrefalt.github.io/gpyui/releases/)
for the platform and Python matrix.

## Contributing

Issues and pull requests are welcome. Start with the
[contributor guide](https://github.com/gtrefalt/gpyui/blob/main/CONTRIBUTING.md)
for source setup, Ruff, ty, Just and Lefthook, and the
[architecture](https://gtrefalt.github.io/gpyui/architecture/) for design decisions
and pinned upstream dependencies.

## License and acknowledgements

gpyui is available under the
[MIT License](https://github.com/gtrefalt/gpyui/blob/main/LICENSE).
[GPUI](https://www.gpui.rs/) and [GPUI Kit](https://gpui-kit.com/) make its native
backend possible. The Python API also draws on composition and event patterns
from [NiceGUI](https://github.com/zauberzeug/nicegui) and
[Flet](https://github.com/flet-dev/flet).

Dependencies retain their own licenses. Distributions include
[third-party notices](https://github.com/gtrefalt/gpyui/blob/main/src/gpyui/THIRD_PARTY_NOTICES.txt).

