pyweft 0.2.0__tar.gz

pyweft-0.2.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+*.egg-info/
+build/
+dist/
+dist-desktop/
+.venv/
+CLAUDE.md
+PROMPTS.md

pyweft-0.2.0/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+What changed in each release of `pyweft`. Newest first. The toolkit,
+`pyweft-ui`, has [its own](packages/pyweft-ui/CHANGELOG.md).
+
+Add a line under **Unreleased** with each change worth knowing about;
+releasing moves them under the new version (see [RELEASING.md](RELEASING.md)).
+
+## Unreleased
+
+## 0.2.0
+
+The first release. (It starts at 0.2.0 because an earlier, unrelated
+project named `pyweft` used 0.1.0 to 0.1.3 and deleted them, and PyPI never
+lets a deleted file name be used again.)
+
+- **Components** in `.weft` files: an XML template, a Python code block and
+  a scoped `<style>` block. `{{ }}`, `:attr`, `@event` handlers with
+  modifiers and a detailed event object, `@bind` for every form control,
+  `<If>`/`<ElseIf>`/`<Else>`, keyed `<For>`, `@property` values.
+- **Composition**: props, `emit`, slots (named, with fallbacks and slot
+  props), `@bind` on components, attributes passed to the root element,
+  components in folders, component libraries from packages, `<Dynamic>`.
+- **Pages**: `router("pages")`, `<Link>`, `navigate()`, `back()`, typed
+  values from the address and query, a not-found page.
+- **State**: `Store` for state shared across components, `@effect`,
+  lifecycle hooks, `state_has_changed()`.
+- **Async**: async handlers and `on_init`, `start_task()`, and
+  `run_in_background()` (a Web Worker in the browser, a thread elsewhere).
+- **Focus and the page**: `ref=` with `focus()`, `scroll_to()` and friends;
+  `set_title()`; `pyweft.dialogs` for opening and saving files and asking
+  for confirmation.
+- **Browser target**: Pyodide, with the first screen rendered ahead of time
+  and a loading screen that shows real progress.
+- **Desktop target**: `pyweft run --desktop` (pywebview, the `desktop` extra)
+  and `pyweft build --desktop` for a standalone program (PyInstaller, the
+  `package` extra); title, icon and window settings in `[tool.pyweft]`.
+- **CLI**: `pyweft new`, `run` (hot reload that keeps state, error overlay)
+  and `build` (a static site); PyPI dependencies installed in the browser;
+  `head.html`, `assets/` and CSS frameworks.

pyweft-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Prassanth Nicholas
+
+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.

pyweft-0.2.0/PKG-INFO

@@ -0,0 +1,324 @@
+Metadata-Version: 2.5
+Name: pyweft
+Version: 0.2.0
+Summary: A UI framework for Python: XML templates, Python code-behind, one render core for web, desktop and mobile.
+Project-URL: Homepage, https://github.com/prassanthn/PyWeft
+Project-URL: Documentation, https://github.com/prassanthn/PyWeft/blob/main/docs/getting-started.md
+Project-URL: Issues, https://github.com/prassanthn/PyWeft/issues
+Author: Prassanth Nicholas
+License-Expression: MIT
+License-File: LICENSE
+Keywords: components,framework,pyodide,ui,webassembly,webview
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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
+Requires-Python: >=3.10
+Provides-Extra: desktop
+Requires-Dist: pywebview>=5; extra == 'desktop'
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Provides-Extra: package
+Requires-Dist: pyinstaller>=6; extra == 'package'
+Requires-Dist: pywebview>=5; extra == 'package'
+Description-Content-Type: text/markdown
+
+# PyWeft
+
+**Build web and desktop apps in Python.** Write components as `.weft` files,
+an XML template plus a Python code block, and PyWeft runs them in the browser
+with real CPython compiled to WebAssembly, or in a native window with Python
+running on your machine. No JavaScript to write, no build step.
+
+*PyWeft: the weft is the thread woven through the warp to make fabric.*
+
+```xml
+<template>
+  <div>
+    <h1>Hello, {{ name or "stranger" }}!</h1>
+    <input @bind="name" placeholder="your name" />
+    <button @click="count += 1">Clicked {{ count }} times</button>
+  </div>
+</template>
+
+<code>
+name: str = ""
+count: int = 0
+</code>
+```
+
+Type in the box and the heading follows; click and the count goes up. State
+is plain Python fields, and the page updates itself after every event.
+
+> **Status:** a working proof of concept. Web apps and desktop apps (run
+> locally or built into a program to hand out) work today. APIs may still
+> change. Not on PyPI yet, so you install from GitHub (below).
+
+## Quick start
+
+You need Python 3.10 or newer. With [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv init myproject && cd myproject
+uv add git+https://github.com/prassanthn/PyWeft.git
+uv run pyweft new myapp
+uv run pyweft run myapp
+```
+
+Open <http://127.0.0.1:8642/>. Your page shows straight away, dimmed, while
+the browser downloads Python in the background (a few seconds the first
+time, cached after that); then it comes alive.
+
+With pip instead:
+
+```bash
+pip install git+https://github.com/prassanthn/PyWeft.git
+pyweft new myapp
+pyweft run myapp
+```
+
+Now open `myapp/app.weft` in your editor, change something and save: the page
+updates in place and keeps what you'd typed. Make a mistake and an overlay
+shows the file and line; fix it and save again.
+
+`myapp/` is your whole app:
+
+```
+myapp/
+  app.weft         the root component
+  styles.css       page-wide CSS (optional)
+  pyproject.toml   your app's dependencies, installed in the browser
+  head.html        extra <head> tags: fonts, CDN stylesheets (optional)
+  loading.html     what visitors see while Python starts (optional)
+```
+
+When you're ready to publish, `uv run pyweft build myapp` writes a static site
+to `myapp/dist/` that any web host can serve, such as GitHub Pages or Netlify.
+
+The same app also runs as a desktop app, in a native window with Python on
+your machine:
+
+```bash
+uv add "pyweft[desktop]"
+uv run pyweft run myapp --desktop
+```
+
+To hand it to people without Python, build it into one program (an `.exe`
+on Windows, a `.app` on macOS) in `myapp/dist-desktop/`:
+
+```bash
+uv add --dev "pyweft[package]"
+uv run pyweft build myapp --desktop
+```
+
+Name the app and give it an icon in `myapp/pyproject.toml`, for the browser
+tab and the window alike, and size the window there too:
+
+```toml
+[tool.pyweft]
+title = "Acme Orders"
+icon = "assets/icon.ico"
+
+[tool.pyweft.desktop]
+width = 1200
+height = 800
+```
+
+## Ready-made controls (no HTML or CSS needed)
+
+[`pyweft-ui`](packages/pyweft-ui/README.md) gives you styled, accessible
+controls as components: buttons, text fields, selects, checkboxes, switches,
+cards, tabs, sortable tables, dialogs, alerts, toasts, layout and light/dark
+themes.
+
+```bash
+uv add "pyweft-ui @ git+https://github.com/prassanthn/PyWeft.git#subdirectory=packages/pyweft-ui"
+```
+
+Add `"pyweft-ui"` to the `dependencies` list in `myapp/pyproject.toml`, then
+use the controls:
+
+```xml
+<template>
+  <ui.Theme mode="auto">
+    <ui.AppShell title="Orders">
+      <ui.Card title="New order">
+        <ui.TextField label="Customer" @bind="customer" required="true" />
+        <ui.Select label="Size" options="Small, Medium, Large" @bind="size" />
+        <ui.Switch label="Express delivery" @bind="express" />
+        <Fill name="footer">
+          <ui.Button variant="primary" icon="send" @click="place_order">Place order</ui.Button>
+        </Fill>
+      </ui.Card>
+    </ui.AppShell>
+  </ui.Theme>
+</template>
+
+<code>
+from pyweft_ui import ui
+
+customer: str = ""
+size: str = "Medium"
+express: bool = False
+
+def place_order(self):
+    ...
+</code>
+```
+
+PyWeft notices the toolkit is installed and sends it to the browser for you.
+To see every control live, clone this repository and run
+`uv run pyweft run packages/pyweft-ui/gallery`.
+
+## What you get
+
+- **Components in one file:** template, Python code and a `<style>` block
+  that only applies to that component.
+- **Template syntax:**
+  - **Values:** `{{ expression }}` shows a value, `:attr="expression"` sets an
+    attribute from Python, `@bind="field"` keeps a form control and a field
+    in sync.
+  - **Events:** `@click="method"` handles an event, with modifiers like
+    `@submit.prevent` and `@keydown.enter`.
+  - **Focus:** `ref="name"` marks an element; `self.focus("name")` and
+    `self.scroll_to("name")` move the keyboard focus or the page to it.
+  - **Control flow:** `<If>`, `<ElseIf>`, `<Else>` and `<For>`.
+- **Composition:** components inside components, with props, events, slots
+  for passing content, and `@bind` on your own components. Organise them in
+  folders, or install them as packages.
+- **Shared state:** a `Store` holds what many components use, like a cart
+  or the signed-in user; change it from anywhere and every page showing it
+  updates.
+- **Pages:** a `pages/` folder becomes your app's screens, with links, Back
+  and Forward, typed values from the address (`/orders/{id}`), and a
+  not-found page.
+- **Lifecycle and effects:** `on_init`, `on_after_render` and `on_dispose`
+  run as a component appears, updates and goes away; `@effect` methods
+  re-run when the state they read changes.
+- **Async:** `async def` handlers, plus `run_in_background()` to run heavy
+  Python in a Web Worker so the page never freezes.
+- **Styling your way:** scoped styles, plain CSS files, or frameworks such as
+  Tailwind and Bootstrap through `head.html`.
+- **Packages:** any pure-Python package from PyPI, declared in
+  `pyproject.toml`, works in the browser.
+- **Files and dialogs:** `pyweft.dialogs` opens and saves files and asks for
+  confirmation with the same code on both targets: the browser's picker and
+  downloads on the web, the system's own dialogs on the desktop.
+- **A fast dev loop:** hot reload that keeps your app's state, and readable
+  errors that point to your `.weft` file and line.
+- **Fast first load:** your app's first screen is rendered ahead of time and
+  shows at once, while Python starts in the background.
+
+## Learn more
+
+| You want to | Read |
+|---|---|
+| Learn the basics: state, templates, events | [Getting started](docs/getting-started.md), sections 1–3 |
+| Run code when a component appears, updates or goes away | [Lifecycle](docs/getting-started.md#lifecycle-when-your-code-runs) |
+| Split an app into components, use slots | [Composing components](docs/getting-started.md#4-composing-components) |
+| Build an app with several pages | [Pages and navigation](docs/getting-started.md#pages-and-navigation) |
+| Handle forms and keyboard input | [Binding form controls](docs/getting-started.md#binding-form-controls), [event modifiers](docs/getting-started.md#event-modifiers) |
+| Load data, run async code, do heavy work | [Async handlers](docs/getting-started.md#async-handlers-and-background-work), [`run_in_background`](docs/getting-started.md#heavy-work-run_in_background) |
+| Style with Tailwind or Bootstrap | [Using CSS frameworks](docs/getting-started.md#using-css-frameworks) |
+| Build screens with the ready-made controls | [pyweft-ui guide](packages/pyweft-ui/docs/guide.md), then the [reference](packages/pyweft-ui/README.md) |
+| Deploy your app | [Building for deployment](docs/getting-started.md#building-for-deployment) |
+| Run it as a desktop app | [A desktop app](docs/getting-started.md#a-desktop-app-pyweft-run---desktop) |
+| Hand out a desktop app (`.exe`, `.app`) | [Handing out a desktop app](docs/getting-started.md#handing-out-a-desktop-app-pyweft-build---desktop) |
+| Open and save files, ask for confirmation | [Files and dialogs](docs/getting-started.md#files-and-dialogs) |
+| Name the app, give it an icon | [The app's title and icon](docs/getting-started.md#the-apps-title-and-icon) |
+| Test components without a browser | [Using the engine from plain Python](docs/getting-started.md#6-using-the-engine-from-plain-python) |
+
+`examples/todo/` is a small complete app, and `examples/shop/` one with
+pages; run them from a clone with `uv run pyweft run examples/todo`.
+
+## Good to know
+
+- **Templates must be well-formed XML:** close every tag (`<br/>`, `<input />`)
+  and quote every attribute.
+- **No threads in the browser.** Use `async`/`await` for waiting and
+  `run_in_background` for heavy computation.
+- **Code runs in the visitor's browser.** Your `.weft` files are visible to
+  them, as with any website's JavaScript, so keep secrets on a server.
+- **Not every package works in a browser:** pure-Python packages do, and so
+  do the ~250 that Pyodide ships prebuilt (NumPy, pandas, …). Anything that
+  needs raw sockets or subprocesses doesn't.
+
+## How it works
+
+PyWeft renders HTML rather than native widgets. A component renders to a
+lightweight tree of elements; after every event PyWeft renders again, compares
+the new tree with the old one and sends only the differences to the page as
+small JSON instructions. The core never touches the page itself. That is what
+makes other targets cheap: a desktop app is a webview showing the same page,
+with Python running natively and the same instructions crossing a bridge.
+
+| Target | Where Python runs | What draws the page |
+|---|---|---|
+| Web | Pyodide, in the browser | the browser |
+| Desktop (`pyweft run --desktop`) | CPython on the machine | a webview (WebView2, WKWebView, WebKitGTK) |
+| Mobile (later) | CPython via Briefcase | a webview |
+
+There is no reactive state system to learn: a handler runs, the component
+renders again, and the comparison finds what changed. `@effect` is the one
+place where PyWeft tracks which fields you read.
+
+## Working on PyWeft
+
+```bash
+git clone https://github.com/prassanthn/PyWeft.git && cd PyWeft
+uv sync --extra dev          # also installs packages/pyweft-ui, editable
+uv run pytest                # 920 tests, including pyweft-ui's
+uv run python examples/demo.py              # render -> event -> diff -> apply, no browser
+uv run pyweft run examples/todo             # the todo app
+uv run pyweft run packages/pyweft-ui/gallery  # every control
+```
+
+With pip: `pip install -e ".[dev]"` and `pip install -e packages/pyweft-ui`.
+
+Releases go to PyPI by pushing a version tag; [RELEASING.md](RELEASING.md)
+has the steps, and [CHANGELOG.md](CHANGELOG.md) what each release changed.
+
+```
+src/pyweft/           the framework (zero runtime dependencies)
+  static/             the browser side: runtime.js, the page shell, the worker
+packages/pyweft-ui/   the control toolkit, released as its own package
+docs/                 the guide
+examples/             a headless demo, the todo app and the shop (pages)
+tests/                the framework's tests
+```
+
+Under the hood:
+- **Patches:** each patch instruction says where to insert, remove, move or
+  change something. They're ordered so the page can apply them front to back
+  with no bookkeeping.
+- **Testing the differ:** tests apply the patches to the old tree and check
+  the result equals the new one, rather than checking the exact instructions.
+  400 of the tests do this on randomly generated trees.
+- **Handler ids** are built from list keys where available, so a row keeps
+  its handlers when a list is reordered.
+
+## Roadmap
+
+**Done:** the render core and differ; the browser target; the desktop target
+(pywebview), and standalone desktop programs (PyInstaller); components with props, events, slots and component libraries;
+pages and navigation; shared state with stores; events with modifiers and
+`@bind` for every form control; moving focus from Python; effects; async
+handlers and Web Worker background work; file and confirmation dialogs on
+both targets; the app's title and icon, and window settings; scoped styles
+and CSS framework support; the `pyweft` CLI with hot reload, static builds
+and pre-rendered first screens; `pyweft-ui` with 22 keyboard-accessible
+controls and a gallery.
+
+**Next:** publishing `pyweft` and `pyweft-ui` to PyPI; more controls (menus,
+a date picker, form validation); installers (`.msi`, `.dmg`) and code
+signing for desktop apps.
+
+**Later:** mobile packaging with Briefcase, developer tools.
+
+## License
+
+MIT. See [LICENSE](LICENSE).