Pydrud

Build Python UIs with a Flutter-inspired widget API.
Run host-side with the toolchain-free Pydash preview, or compile a real Android APK with Chaquopy.

Congratulations, Android users — Pydash is officially live!
Download the preview client from the Pydash releases page. iOS is coming soon.

Pydrud is a declarative UI framework for building native Android apps in Python — a Flutter-inspired, radically simpler alternative to writing Java or Kotlin, with Material Design 3 (Material You) built in. It is a Python GUI framework for Android: write the interface once as a Python widget tree, and a generated renderer turns it into native Android Views at runtime. There is no XML layout and no Java to write, and the widget, theme and styling layers stay platform-neutral, so the same screen code renders through any adapter.

Pydrud ships with a platform-neutral widget tree, a keyed diff engine, and a versioned render protocol. The same screen code drives the host preview and the native Android renderer.

It ships the Material 3 design system end to end: HCT-generated colour with all 36 semantic roles, the M3 type scale, shape and elevation systems, the component catalogue from buttons to side sheets, and the M3 motion tokens — all of it expressed once in Python and translated by the renderer.

Search terms this project answers to: Python Android UI framework · declarative Python UI · Material Design 3 in Python · Material You Python · Chaquopy app · native Android Views from Python · Flutter alternative for Python · build an Android app without Java · PSS stylesheets.

• 📦 PyPI: pypi.org/project/pydrud
• 📚 Docs: docs/ARCHITECTURE.md · docs/PSS_STYLESHEETS.md
• 🐛 Issues: github.com/MurShidM01/Pydrud/issues
• 📝 Changes: CHANGELOG.md

Quick start

pip install pydrud                       # install the framework
pydrud create my_app --org com.example   # scaffold a project (Pydash runtime)
cd my_app
pydrud dev                               # run host Python, print a preview QR/URI

For an installable Android app, add the native platform and run it:

pydrud init android        # standalone app with embedded Python (Chaquopy)
pydrud run                 # build, install and launch on a device/emulator

The generated APK boots your Python on device and runs fully offline. Pass --runtime chaquopy to pydrud create to scaffold the Android project directly.

Runtimes

An Android target can also be built with no embedded interpreter:

pydrud init android --backend host|none|chaquopy
pydrud dev --bridge            # serve the host bridge (runs `adb reverse` for you)

All three share the same widget tree, keyed diff and protocol-v2 render transactions; only the transport differs.

Platform-neutral by design

Android is the only renderer Pydrud ships — there is no iOS, Linux, Windows or web backend to configure or maintain — but the UI layer itself is renderer-agnostic, so the same screen code is portable:

• One widget vocabulary. pydrud/widgets/ imports nothing from pydrud/platforms/android/, the generated Java templates or android.*.
• One wire format. A plain JSON node dict (type, key, style, props, children, events) with no Android types in it.
• Renderer facts as data. A RendererProfile supplies platform-specific style facts to the PSS parser/resolver, so neither ever imports a platform adapter implicitly.
• Capability negotiation. A renderer advertises the widgets and services it supports, and unsupported widgets are substituted with documented fallbacks instead of being dropped.

Adding a platform later means adding one adapter under pydrud/platforms/ plus its transport — not forking the design system. See docs/ARCHITECTURE.md.

Installation

pip install pydrud                       # from PyPI

git clone https://github.com/MurShidM01/Pydrud.git
cd Pydrud && pip install -e ".[dev]"     # from source

Behind a proxy, export http_proxy / https_proxy before pydrud build; the values are forwarded to Gradle automatically.

What you get

Examples

Two complete apps live in examples/:

Run either headless with python examples/todo_app.py --tree, or drop it into a project as src/app/main.py.

PSS stylesheets

Pydrud Style Sheets (PSS) keep presentation out of Python while using the same platform-neutral vocabulary. Files named *.pss under src/ are discovered automatically and re-resolved without re-running Python modules.

:root { --brand: #FF4F46E5; }

.card {
    background: var(--brand);
    border-radius: 16;
    padding: 24;                       /* all four sides */
    shadow: { color: #40000000; offsetY: 8; blur: 24 };
    font: { size: 16, weight: 600 };
}

@media (max-width: 360px) {
    .card { padding: 16; }
}

@keyframes pulse {
    from { transform: scale(1); opacity: 1; }
    to   { transform: scale(1.4); opacity: .4; }
}
.badge { animation: pulse 1.2s ease-in-out infinite; }
.badge:active { transform: scale(.92); }

Supported today: custom properties (--x / var() with fallback, inherited), the universal selector *, structural and state pseudo-classes (:first-child, :nth-child(), :not(), :active, :hover, :focus, …), @media queries, @keyframes + the animation shorthand, transition, and the CSS value language — clamp(), calc(), min()/max(), env(safe-area-inset-*) and the viewport units, resolved against the live window. CSS long-hands fold into Pydrud composites (font-size → font.size, padding-top → padding.top, background → bg, transform: scale() → scale), and web-only declarations are accepted then ignored with one warning, so a stylesheet copied from the web drops in nearly verbatim.

$token references resolve against the active palette — bg: $surface, color: $text, border-radius: $radius_card — so one stylesheet follows light/dark mode and re-tints after Theme.seed().

See docs/PSS_STYLESHEETS.md for the selector, cascade, value, diagnostics and reload contract, and docs/examples/heartbeat-css-parity.pss for a full stylesheet translated from a web prototype.

Widget catalogue

The API is Flutter-shaped. Every widget serialises to a platform-neutral node; the renderer decides how to draw it.

Layout

Controls

pydrud docs --serve generates a searchable HTML reference for every widget, prop and service.

Events, state and async

widget.on_click(callback)          # any widget — callback(data)
widget.on_change(callback)         # inputs, sliders, page views
widget.on("select", callback)      # any named event

from pydrud import State, Store, Computed
count = State(0)
Text(lambda: f"{count.value}")     # rebuilds when count changes
page.run_task(heavy_work)          # thread pool; `async def` also works
page.every(1.0, tick)              # repeating timer
page.http.get("/posts").then(render).catch(show_error)

CLI reference

Every command uses the same branded terminal UI (auto-disabled when output is redirected; override with NO_COLOR / PYDRUD_COLOR). pydrud analyze --json stays plain JSON.

Android project configuration

Applies once a project has the Android platform. pydrud.yaml is the source of truth for generated Android files — change it and run pydrud sync.

app_name: "Taskflow"
package: "com.example.taskflow"
runtime: "chaquopy"
version_code: 2
version_name: "1.1.0"
min_sdk: 24
target_sdk: 36
compile_sdk: 36
scheme: "taskflow"
permissions: ["CAMERA"]
capabilities: ["haptics", "notifications"]
camera: false
python_version: "3.11"
protocol_version: 2

Runtime dangerous permissions always require page.permissions.request(...) and explicit user consent — Pydrud never fakes or bypasses the Android prompt.

Architecture

Both runtimes share the transport-neutral widget tree, keyed diff engine and protocol-v2 transactions:

Pydash (pydrud dev)
  host Python App  ── token-authenticated preview handshake ──► renderer
        source, state and handlers stay on the host

Chaquopy (pydrud run / APK)
  embedded Python App ── local NDJSON bridge ──► generated BridgeService
                                                 └─ native Android Views

1. App(target=main) builds a widget tree; PSS rules resolve on the Python side.
2. page.update() computes keyed patches from the last renderer-confirmed tree.
3. Python sends one RenderTransaction (full snapshot or patch batch) with a strictly increasing revision.
4. The renderer applies it atomically and ACKs; a NACK triggers a full resync.
5. Events travel back through the same bridge to Python callbacks.

Source layout

No file in the repository exceeds 1,000 lines.

Native renderer (Chaquopy)

A thin ViewFactory orchestrator plus cohesive collaborators:

Requirements

Host workflow (default)

Python 3.10+ and the Pydrud package. pydrud dev needs no Java, Android SDK, NDK, Gradle or ADB.

Android APK workflow

Projects target Android API 24+ and default to arm64-v8a, armeabi-v7a and x86_64. ADB is needed for pydrud run, not for pydrud dev or the tests.

[System.Environment]::SetEnvironmentVariable('ANDROID_HOME', 'C:\Android\Sdk', 'User')
[System.Environment]::SetEnvironmentVariable('ANDROID_SDK_ROOT', 'C:\Android\Sdk', 'User')

export ANDROID_HOME=$HOME/Android/Sdk
export ANDROID_SDK_ROOT=$HOME/Android/Sdk

Development

pip install -e ".[dev]"
python -m pytest tests/ -v
ruff check .                 # the same lint CI runs

The suite covers widget/state/protocol unit tests, keyed-diff and PSS parsing/resolution, scaffold generation for both project shapes, generated Java template parsing, and end-to-end runtime tests via pydrud.testing — all without a device or emulator.

tests/test_neutrality.py additionally proves the UI layer is renderer-neutral: every module under pydrud/widgets/ is imported in a fresh interpreter and asserted to reach no Android adapter and no pyjnius, so the portability claim above cannot regress unnoticed.

Roadmap

See CHANGELOG.md for the complete itemised history.

Contributing

1. Fork the repository.
2. Create a branch: git checkout -b feature/amazing-feature.
3. Commit your changes and push the branch.
4. Open a Pull Request.

License

MIT © Pydrud Contributors. See LICENSE for details.

Pydrud — Pythonic. Portable. Simple.