Metadata-Version: 2.4
Name: guile
Version: 0.4.0
Summary: A lightweight Python framework for building native desktop apps.
Author-email: Andres Patrignani <andrespatrignani@ksu.edu>
License: MIT
Project-URL: Homepage, https://andpatrig.github.io/guile
Project-URL: Repository, https://github.com/andpatrig/guile
Project-URL: Bug Tracker, https://github.com/andpatrig/guile/issues
Project-URL: Changelog, https://github.com/andpatrig/guile/releases
Keywords: gui,desktop,app,pywebview,reactive
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: User Interfaces
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: pywebview>=5.0
Requires-Dist: matplotlib>=3.5
Provides-Extra: science
Requires-Dist: numpy>=1.21; extra == "science"
Requires-Dist: pandas>=1.3; extra == "science"
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"

# gui**le**

A lightweight Python framework for building desktop apps.

---

## Philosophy

Guile started as a personal tool for building lab and research apps — the kind of quick internal dashboards, data explorers, and parameter tools that are too specific to justify a full web stack, but too interactive for a script. The goal was always to stay out of the way: write Python top to bottom, get a native window with a clean interface, nothing more.

Inspired by the early design of the Julia language — which set out to take the best of Python, R, and MATLAB rather than compromise between them — guile tries to do the same for Python GUIs. In that spirit: guile has the syntax of Streamlit, the single-process simplicity of Tkinter, and the visual polish of a modern web app, without requiring you to write HTML, CSS, or JavaScript.

It is not trying to compete with NiceGUI, PyQt, or Dash. It is the right tool for a simple lab, company, or personal project — and deliberately nothing more.

**A few specific choices that shape how guile feels:**

- **No full-page refresh.** When state changes, only the parts of the UI that actually changed are updated. Text stays in inputs, sliders don't jump, focus is never lost. This is different from Streamlit, which re-executes the whole script and redraws the page on every interaction.

- **No nesting hell.** Layout is written top to bottom using `with` blocks, not by nesting constructors inside constructors. `with gui.card():` followed by indented widget calls reads the same way the finished UI looks — no inside-out tree building, no closing parentheses to track.

- **No server.** The app runs as a single Python process and opens a native OS window. There is no local HTTP server, no port to bind, no browser tab to manage. This also means packaging with PyInstaller produces a self-contained executable with no runtime dependencies for the end user.

---

## Install

```bash
pip install pywebview
```

Copy the `guile/` folder into your project. No further setup.

---

## Quick start

```python
import guile as gui

count = gui.state(0)

@gui.app("Counter", width=400, height=300)
def ui():
    with gui.col(align="center", justify="center", style="height:100vh"):
        with gui.card(gap=14):
            gui.title("Counter")
            with gui.row(gap=16, align="center", justify="center"):
                gui.button("−", variant="secondary",
                           on_click=lambda: count.update(lambda x: x - 1))
                gui.text(count, size="2xl", bold=True,
                         style="min-width:64px;text-align:center")
                gui.button("+",
                           on_click=lambda: count.update(lambda x: x + 1))
```

---

## How it works

- `gui.state(value)` — a reactive value; setting it re-renders the UI automatically
- `with gui.card():` / `with gui.col():` / `with gui.row():` — layout containers; everything indented goes inside
- `gui.button()`, `gui.slider()`, `gui.input()`, `gui.table()` — widgets that take `on_click=` or return their current value
- `gui.figure(fig)` — embed a matplotlib figure inline
- `gui.leaflet(center, markers=...)` — embed an interactive map

---

## Examples

| File | What it shows |
|------|--------------|
| `01_counter.py` | State, buttons, badges |
| `02_todo.py` | Lists, dynamic rendering, checkboxes |
| `03_settings.py` | Sliders, selects, form layout |
| `04_geo_data.py` | Matplotlib figure + Leaflet map |
| `05_data_tools.py` | Table, date picker, file picker |
| `06_soil_water.py` | Sliders driving a live chart |

---

## Dependencies

| Package | Purpose |
|---------|---------|
| `pywebview` | Native window |
| `matplotlib` | Only if you use `gui.figure()` |
| `numpy` | Only if your app uses it |

Everything else is Python standard library.

---

## Files

| File | Role |
|------|------|
| `state.py` | Reactive value class |
| `ui.py` | Render engine + all widgets |
| `_app.py` | Window lifecycle, pywebview bridge |
| `_template.py` | Embedded HTML/CSS/JS |
| `__init__.py` | Public API (`gui.*`) |

See `ARCHITECTURE.md` for a deeper explanation of how the files connect.

---


## Versions

v0.1.0
First release including docs, reference, and 27 widgets. AP on 22 May 2026

v0.2.0
Added max_height argument to gui.scroll() widget
Replaced onchange for onblur in gui.multiselect() widget

v0.3.0
Added notify and modal widgets
Created new examples and improved existing examples

v0.4.0
Added tabs
Fixed the datetime-local input to display in 24-hour format by setting lang="en-GB"

MIT License
