⚡ Pydrud

Build native Android apps with Python.
No XML layouts. No Kotlin UI code. Just Python.

A Flutter-inspired framework that converts declarative Python widget trees
into real native Android Views at runtime — via Chaquopy + a lightweight TCP bridge.

✨ Quick Start

pip install pydrud                    # Install the framework
pydrud init my_app --org com.example  # Scaffold a new project
cd my_app
pydrud run                            # Build → install → launch

First APK in ~2 minutes. Connect your Android device via USB (or ADB over TCP), and pydrud run does the rest.

📱 What You Get

📝 Example App

from pydrud import App, Text, Container, Column, Row, Button, Center
from pydrud import State, EdgeInsets, Alignment

counter = State(0)

def main(page):
    page.title = "Pydrud Demo"
    page.bgcolor = "#FFF9FAFB"

    def on_pressed(data):
        counter.value += 1
        page.update()

    page.add(
        Column(scroll=True, children=[

            Container(
                bg="#FF6366F1", padding=EdgeInsets.symmetric(horizontal=20, vertical=16),
                child=Text("Pydrud", size=20, weight=700, color="#FFFFFFFF"),
            ),

            Spacer(expand=2),
            Center(child=Text(str(counter.value), size=72, weight=200, color="#FF6366F1")),
            Center(child=Text("Tap the button", size=14, color="#FF9CA3AF")),
            Spacer(expand=3),

            Center(
                child=Button(
                    "+", bg_color="#FF6366F1", color="#FFFFFFFF",
                    style={"borderRadius": 28, "width": 56, "height": 56},
                ).on_click(on_pressed),
            ),
            Spacer(expand=1),

        ]),
    )

app = App(target=main)
app.run()

💡 State lives outside main() so it persists across re-renders.
Update → page.update() → tree rebuilds → Android re-renders.

🔧 Installation

From PyPI (recommended)

pip install pydrud

From source

git clone https://github.com/MurShidM01/Pydrud.git
cd Pydrud
pip install -e .

Corporate / proxy networks

export http_proxy=http://proxy:port
export https_proxy=http://proxy:port
pydrud build    # proxy forwarded to Gradle automatically

🧱 Widget Reference

Layout

Basic

Events

All interactive widgets support callback chaining:

widget.on_click(callback)      # callback(data) → data is a dict
widget.on_change(callback)     # TextField, Checkbox, Switch
widget.on_submit(callback)     # TextField (IME action)
widget.on_focus(callback)      # Focus gain / loss

Styling

Use the Style builder or pass dicts inline:

Style().bg("#FFFFFF").padding(EdgeInsets.all(16)).border_radius(8).elevation(4).build()

All style properties:

📏 Responsive Scaling

Pydrud includes a built-in responsive system that auto-scales your UI to the device screen width.

from pydrud import Responsive

Responsive.text(16)      # Font size — scales proportionally
Responsive.w(48)         # Width — scales proportionally
Responsive.h(48)         # Height
Responsive.padding(24)   # Padding / margin
Responsive.spacing(12)   # Gaps between widgets
Responsive.radius(12)    # Border radius
Responsive.icon(24)      # Icon size

How it works:

1. Android sends the screen dimensions (width, height, density) to Python via the bridge "ready" event
2. Python's Responsive class computes a scale factor: screen_width_dp / 360
3. All sizes are multiplied by this factor — on a 720dp tablet, everything is 2× larger
4. Baseline 360dp matches the typical phone width

✅ No device info available? Defaults to factor 1.0 (no scaling) — safe fallback.

🏗 Architecture

┌──────────────────────────────────────────┐
│  Python Layer                             │
│  ┌────────┐  ┌──────────────────────┐    │
│  │Widgets │  │ EventDispatcher      │    │
│  │  Tree  ├──┤  (user callbacks)    │    │
│  └───┬────┘  └──────────┬───────────┘    │
│      │                  │                │
│  ┌───▼──────────────────▼────────────┐   │
│  │  TreeDiff → Patches → Bridge.encode│   │
│  └────────────────┬──────────────────┘   │
└───────────────────┼──────────────────────┘
                    │ TCP / NDJSON :8595
┌───────────────────┼──────────────────────┐
│  Android Layer    │                      │
│  ┌────────────────▼──────────────────┐   │
│  │  BridgeService  (TCP server)      │   │
│  └────────────────┬──────────────────┘   │
│  ┌────────────────▼──────────────────┐   │
│  │  ViewFactory   → native Views     │   │
│  └───────────────────────────────────┘   │
│  ┌───────────────────────────────────┐   │
│  │  EventDispatcher → Python         │   │
│  └───────────────────────────────────┘   │
└──────────────────────────────────────────┘

Data Flow

1. App(target=main) — calls your builder → produces a Widget tree
2. page.update() — rebuilds the tree → sends full render command to Android
3. BridgeService — receives the JSON tree → ViewFactory creates native Views
4. User taps a Button — Java sends {"type":"click","key":"..."} over the socket
5. Python EventDispatcher — routes the event to your callback
6. Callback mutates State — triggers page.update() → goto step 2

🔄 For V1, every state change sends a full tree re-render. Incremental patch support is planned for V2.

🛠 CLI Reference

Environment

pydrud doctor

# Expected output:
# ✔ Python ≥ 3.10       — 3.12.3
# ✔ Java 17+            — OpenJDK 17
# ✔ Android SDK         — /path/to/sdk (API 35)
# ✔ Gradle              — gradlew wrapper found
# ✔ ADB                 — Android Debug Bridge 2.x

⚙️ Requirements

Development machine

Android device

Setting up Android SDK

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

pydrud doctor

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

echo 'export ANDROID_HOME=$HOME/Android/Sdk' >> ~/.bashrc
echo 'export ANDROID_SDK_ROOT=$HOME/Android/Sdk' >> ~/.bashrc

🧪 Development

git clone https://github.com/MurShidM01/Pydrud.git
cd Pydrud
pip install -e ".[dev]"
python -m pytest tests/ -v

Current test count: 96 tests (widgets, state, diffing, events, styling, bridge, responsive).

Project Structure

pydrud/
├── pydrud/
│   ├── main.py                   # App + Page + bridge event loop
│   ├── widgets/
│   │   ├── base.py               # Widget base class
│   │   ├── layout.py             # Container, Column, Row, Center, Spacer, Divider
│   │   ├── basic.py              # Text, Button, TextField, Image, Icon, Checkbox, Switch
│   │   └── styling.py            # Style, EdgeInsets, Alignment, FontStyle
│   ├── core/
│   │   ├── state.py              # State[T], ReactiveDict
│   │   ├── diff.py               # TreeDiff → Patch list
│   │   ├── events.py             # Event dispatcher
│   │   ├── bridge.py             # Protocol encoding / decoding
│   │   └── responsive.py         # Responsive scaling
│   ├── commands/
│   │   ├── cli.py                # Click CLI
│   │   ├── project.py            # Jinja2 project scaffold
│   │   ├── builder.py            # Gradle + ADB
│   │   └── doctor.py             # Environment check
│   └── android/templates/        # Jinja2 → Android project
├── tests/                        # pytest test suite
├── pyproject.toml
└── README.md

Adding a New Widget

1. Create Python class in pydrud/widgets/ (extend Widget, set _widget_type, implement _serialise_props())
2. Export in pydrud/widgets/__init__.py and pydrud/__init__.py
3. Add a creator method in pydrud/android/templates/android/ViewFactory.java.j2
4. Add style handling in applyStyle()
5. Write tests in tests/
6. Run python -m pytest tests/ -v

📦 Publishing to PyPI

# Install build tools
pip install build twine

# Build source distribution and wheel
python -m build

# Upload to PyPI
twine upload dist/*

💡 Update the version number in pyproject.toml before publishing.

🗺 Roadmap

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -am 'Add amazing feature')
4. Push (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

MIT © Pydrud Contributors. See LICENSE for details.

Pydrud — Pythonic. Native. Simple.
Built with ❤️ for Python developers who love native mobile.