pyweft 0.2.1__tar.gz → 0.3.0__tar.gz

{pyweft-0.2.1 → pyweft-0.3.0}/.gitignore

@@ -8,3 +8,4 @@ dist-desktop/
 .venv/
 CLAUDE.md
 PROMPTS.md
+website/_build/

{pyweft-0.2.1 → pyweft-0.3.0}/CHANGELOG.md

@@ -8,6 +8,22 @@ releasing moves them under the new version (see [RELEASING.md](RELEASING.md)).
 
 ## Unreleased
 
+## 0.3.0
+
+- **`pyweft.http`**: call web APIs and load the app's data files, with the
+  same code in the browser (the page's fetch) and on the desktop (the
+  standard library). `get_json`, `get`/`post`/`put`/`patch`/`delete`,
+  `request`; JSON, form and text bodies, query parameters, timeouts. A
+  relative URL is a file the app ships (`assets/prices.json`).
+- **`pyweft.storage`**: keep data between visits: `get`, `set`, `delete`,
+  `has`, `keys`, `clear`, for any JSON value. The browser's local storage,
+  kept apart per app; on the desktop, a JSON file in the user's data
+  folder; in tests, memory.
+- The todo example remembers its list, and the tutorial has a step for it.
+- The todo and shop examples are restyled with Tailwind CSS (built with
+  its CLI), in light and dark, and work at phone width. The shop has a
+  dashboard, an orders table and a reusable status badge.
+
 ## 0.2.1
 
 - The PyPI page installs from PyPI, and its links to the guide and the

{pyweft-0.2.1 → pyweft-0.3.0}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.5
 Name: pyweft
-Version: 0.2.1
+Version: 0.3.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: Documentation, https://prassanthn.github.io/PyWeft/
 Project-URL: Issues, https://github.com/prassanthn/PyWeft/issues
 Author: Prassanth Nicholas
 License-Expression: MIT
@@ -36,6 +36,12 @@ running on your machine. No JavaScript to write, no build step.
 
 *PyWeft: the weft is the thread woven through the warp to make fabric.*
 
+**[Website](https://prassanthn.github.io/PyWeft/)**: a step-by-step
+[tutorial](https://prassanthn.github.io/PyWeft/tutorial/), the
+[guide](https://prassanthn.github.io/PyWeft/guide/), and the
+[controls](https://prassanthn.github.io/PyWeft/live/gallery/) and
+[examples](https://prassanthn.github.io/PyWeft/examples/) running live.
+
 ```xml
 <template>
   <div>
@@ -208,6 +214,9 @@ To see every control live, clone this repository and run
 - **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.
+- **Data in and out:** `pyweft.http` calls web APIs and loads your app's
+  data files, and `pyweft.storage` keeps settings and lists between visits,
+  with the same code in the browser and 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
@@ -229,6 +238,7 @@ To see every control live, clone this repository and run
 | Run it as a desktop app | [A desktop app](https://github.com/prassanthn/PyWeft/blob/main/docs/getting-started.md#a-desktop-app-pyweft-run---desktop) |
 | Hand out a desktop app (`.exe`, `.app`) | [Handing out a desktop app](https://github.com/prassanthn/PyWeft/blob/main/docs/getting-started.md#handing-out-a-desktop-app-pyweft-build---desktop) |
 | Open and save files, ask for confirmation | [Files and dialogs](https://github.com/prassanthn/PyWeft/blob/main/docs/getting-started.md#files-and-dialogs) |
+| Call web APIs, save data between visits | [Loading data](https://github.com/prassanthn/PyWeft/blob/main/docs/getting-started.md#loading-data-pywefthttp), [saving data](https://github.com/prassanthn/PyWeft/blob/main/docs/getting-started.md#saving-data-between-visits-pyweftstorage) |
 | Name the app, give it an icon | [The app's title and icon](https://github.com/prassanthn/PyWeft/blob/main/docs/getting-started.md#the-apps-title-and-icon) |
 | Test components without a browser | [Using the engine from plain Python](https://github.com/prassanthn/PyWeft/blob/main/docs/getting-started.md#6-using-the-engine-from-plain-python) |
 
@@ -282,12 +292,22 @@ With pip: `pip install -e ".[dev]"` and `pip install -e packages/pyweft-ui`.
 Releases go to PyPI by pushing a version tag; [RELEASING.md](https://github.com/prassanthn/PyWeft/blob/main/RELEASING.md)
 has the steps, and [CHANGELOG.md](https://github.com/prassanthn/PyWeft/blob/main/CHANGELOG.md) what each release changed.
 
+The website is rebuilt and published on every push to `main`. To build it
+locally:
+
+```bash
+uv sync --group website
+uv run python website/build.py
+uv run python -m http.server -d website/_build/site    # http://127.0.0.1:8000/
+```
+
 ```
 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
+docs/                 the guide (the website splits it into pages)
 examples/             a headless demo, the todo app and the shop (pages)
+website/              the website: home page, tutorial, build script
 tests/                the framework's tests
 ```
 

{pyweft-0.2.1 → pyweft-0.3.0}/README.md

@@ -7,6 +7,12 @@ running on your machine. No JavaScript to write, no build step.
 
 *PyWeft: the weft is the thread woven through the warp to make fabric.*
 
+**[Website](https://prassanthn.github.io/PyWeft/)**: a step-by-step
+[tutorial](https://prassanthn.github.io/PyWeft/tutorial/), the
+[guide](https://prassanthn.github.io/PyWeft/guide/), and the
+[controls](https://prassanthn.github.io/PyWeft/live/gallery/) and
+[examples](https://prassanthn.github.io/PyWeft/examples/) running live.
+
 ```xml
 <template>
   <div>
@@ -179,6 +185,9 @@ To see every control live, clone this repository and run
 - **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.
+- **Data in and out:** `pyweft.http` calls web APIs and loads your app's
+  data files, and `pyweft.storage` keeps settings and lists between visits,
+  with the same code in the browser and 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
@@ -200,6 +209,7 @@ To see every control live, clone this repository and run
 | Run it as a desktop app | [A desktop app](https://github.com/prassanthn/PyWeft/blob/main/docs/getting-started.md#a-desktop-app-pyweft-run---desktop) |
 | Hand out a desktop app (`.exe`, `.app`) | [Handing out a desktop app](https://github.com/prassanthn/PyWeft/blob/main/docs/getting-started.md#handing-out-a-desktop-app-pyweft-build---desktop) |
 | Open and save files, ask for confirmation | [Files and dialogs](https://github.com/prassanthn/PyWeft/blob/main/docs/getting-started.md#files-and-dialogs) |
+| Call web APIs, save data between visits | [Loading data](https://github.com/prassanthn/PyWeft/blob/main/docs/getting-started.md#loading-data-pywefthttp), [saving data](https://github.com/prassanthn/PyWeft/blob/main/docs/getting-started.md#saving-data-between-visits-pyweftstorage) |
 | Name the app, give it an icon | [The app's title and icon](https://github.com/prassanthn/PyWeft/blob/main/docs/getting-started.md#the-apps-title-and-icon) |
 | Test components without a browser | [Using the engine from plain Python](https://github.com/prassanthn/PyWeft/blob/main/docs/getting-started.md#6-using-the-engine-from-plain-python) |
 
@@ -253,12 +263,22 @@ With pip: `pip install -e ".[dev]"` and `pip install -e packages/pyweft-ui`.
 Releases go to PyPI by pushing a version tag; [RELEASING.md](https://github.com/prassanthn/PyWeft/blob/main/RELEASING.md)
 has the steps, and [CHANGELOG.md](https://github.com/prassanthn/PyWeft/blob/main/CHANGELOG.md) what each release changed.
 
+The website is rebuilt and published on every push to `main`. To build it
+locally:
+
+```bash
+uv sync --group website
+uv run python website/build.py
+uv run python -m http.server -d website/_build/site    # http://127.0.0.1:8000/
+```
+
 ```
 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
+docs/                 the guide (the website splits it into pages)
 examples/             a headless demo, the todo app and the shop (pages)
+website/              the website: home page, tutorial, build script
 tests/                the framework's tests
 ```
 

{pyweft-0.2.1 → pyweft-0.3.0}/docs/getting-started.md

@@ -51,6 +51,8 @@ later mobile: only the transport differs.
    [PyPI packages](#using-pypi-packages),
    [calling JavaScript](#calling-javascript),
    [files and dialogs](#files-and-dialogs),
+   [loading data (http)](#loading-data-pywefthttp),
+   [saving data between visits (storage)](#saving-data-between-visits-pyweftstorage),
    [building for deployment](#building-for-deployment),
    [a desktop app](#a-desktop-app-pyweft-run---desktop),
    [handing it out](#handing-out-a-desktop-app-pyweft-build---desktop)
@@ -1694,6 +1696,21 @@ page:
 `@apply` works in `_tailwind/input.css`, but not in a component's `<style>`
 block, which Tailwind never reads.
 
+**Classes that depend on state.** A `:class` sets the whole attribute, so
+an element with both `class` and `:class` gets only the `:class` one. Put
+the fixed classes in the expression too:
+
+```xml
+<button @click="show = name"
+        :class="'rounded-lg px-3 py-1.5 ' + ('bg-slate-900 text-white' if name == show else 'text-slate-500')">
+  {{ name }}
+</button>
+```
+
+The todo and shop examples (`examples/todo`, `examples/shop`) are styled
+with Tailwind's CLI exactly as above: see each one's `_tailwind/input.css`
+for the setup and the command that rebuilds its `tailwind.css`.
+
 ### Ready-made controls: pyweft-ui
 
 If you'd rather not write HTML and CSS at all, `pyweft-ui` gives you styled,
@@ -1869,6 +1886,101 @@ async def clear(self):
 - **In tests**, `dialogs.set_host()` installs a stand-in that answers
   instead of the user; without one, the calls raise an error saying so.
 
+### Loading data: pyweft.http
+
+`pyweft.http` calls web APIs and loads files, the same way in the browser
+and in a [desktop app](#a-desktop-app-pyweft-run---desktop). Requests are
+`async`, so make them in `async` handlers or an `async def on_init`:
+
+```python
+from pyweft import http
+
+orders: list = []
+error: str = ""
+
+async def on_init(self):
+    self.orders = await http.get_json("https://api.example.com/orders")
+
+async def save(self, order):
+    response = await http.post("https://api.example.com/orders", json=order)
+    if not response.ok:
+        self.error = f"Couldn't save the order ({response.status})"
+```
+
+| Call | Returns |
+|---|---|
+| `get_json(url)` | the body parsed as JSON; `http.HTTPError` unless the status is 2xx |
+| `get(url)`, `post(url)`, `put(url)`, `patch(url)`, `delete(url)` | a `Response`, whatever its status |
+| `request(method, url)` | the same, for any method |
+
+Each takes `params=` (added to the URL's query), `headers=`, `timeout=`
+(seconds, 30 by default) and a body: `json=` (any JSON value) or `data=`
+(bytes, text, or a dict sent as a form).
+
+- **A `Response`** has `status`, `ok` (a 2xx status), `headers` (names in
+  lower case), `data` (the bytes), `text` and `json()`.
+  `raise_for_status()` raises `http.HTTPError` unless it's 2xx.
+- **A relative URL is a file your app ships.** Put data files in
+  `assets/`, and `await http.get_json("assets/prices.json")` reads them in
+  the browser and in a desktop window alike.
+- **Failures:** no answer at all (offline, a mistyped address) raises
+  `http.NetworkError`; a slow server raises `TimeoutError`.
+- **In the browser, the browser's rules apply.** A request to another site
+  only works if that server allows it (it must send CORS headers; public
+  APIs usually do). There is no such rule in a desktop app.
+- **Everyone can see the requests a web app makes**, as with any web page,
+  so an API key in your code isn't secret. Keep secrets on a server of
+  your own and call that.
+- **In tests**, requests go out for real through the standard library.
+  `http.set_host()` installs a stand-in instead: an object with `async
+  request(method, url, headers, body, timeout)` returning `(status,
+  headers, data, url)`.
+
+### Saving data between visits: pyweft.storage
+
+`pyweft.storage` keeps small amounts of data, such as settings, a draft or
+a list, until the next visit:
+
+```python
+from pyweft import effect, storage
+
+items: list = []
+
+def on_init(self):
+    self.items = storage.get("todos", [])   # [] the first time
+
+@effect
+def keep(self):
+    storage.set("todos", self.items)        # runs again whenever items changes
+```
+
+| Call | Does |
+|---|---|
+| `get(key, default=None)` | the stored value, or `default` |
+| `set(key, value)` | stores `value`, replacing what was there |
+| `delete(key)`, `clear()` | removes one key, or everything this app stored |
+| `has(key)`, `keys()` | whether a key has a value; every key, sorted |
+
+- **Values are anything JSON can hold:** numbers, text, `True`/`False`/
+  `None`, and lists and dicts of those. Anything else raises `TypeError`;
+  turn dates into text first, for example.
+- **`get` returns a copy.** Changing a list you got back doesn't change
+  what's stored until you `set` it again, which is what the effect above
+  does.
+- **The calls aren't `async`**, so they work anywhere: in `on_init`, an
+  effect, a property, or a module of your app.
+- **Where it lives:** in the browser, the browser's local storage for your
+  site (about 5 MB in all, cleared if the visitor clears site data), kept
+  apart per app by the `[project]` name in its `pyproject.toml`. In a
+  desktop app, a JSON file in the user's data folder:
+  `%APPDATA%\<name>\storage.json` on Windows,
+  `~/Library/Application Support/<name>/` on macOS,
+  `~/.local/share/<name>/` on Linux.
+- **Not in `run_in_background`:** the worker can't reach the page's
+  storage, so read what the function needs first and pass it in.
+- **In tests** it lives in memory. `storage.set_host(storage.MemoryStorage())`
+  starts a test empty; `storage.FileStorage(path)` keeps it in a file.
+
 ### Building for deployment
 
 ```bash

{pyweft-0.2.1 → pyweft-0.3.0}/pyproject.toml

@@ -35,7 +35,7 @@ package = ["pywebview>=5", "pyinstaller>=6"]
 
 [project.urls]
 Homepage = "https://github.com/prassanthn/PyWeft"
-Documentation = "https://github.com/prassanthn/PyWeft/blob/main/docs/getting-started.md"
+Documentation = "https://prassanthn.github.io/PyWeft/"
 Issues = "https://github.com/prassanthn/PyWeft/issues"
 
 [project.scripts]
@@ -70,3 +70,11 @@ pyweft-ui = { workspace = true }
 
 [dependency-groups]
 dev = ["pyweft-ui"]
+# The website (website/build.py): uv sync --group website
+# and the examples' Tailwind stylesheets (examples/*/_tailwind/input.css)
+website = [
+    "mkdocs-material>=9.8,<10; python_version >= '3.11'",
+    "pytailwindcss>=0.4; python_version >= '3.11'",
+    # the todo example's own dependency, so its first screen can be pre-rendered
+    "humanize",
+]

{pyweft-0.2.1 → pyweft-0.3.0}/src/pyweft/__init__.py

@@ -4,7 +4,7 @@ Markup in XML, logic in Python, one render core that emits transport-agnostic
 patches so desktop (webview), web (Pyodide) and mobile can share a codebase.
 """
 
-from . import dialogs
+from . import dialogs, http, storage
 from .background import BackgroundError, run_in_background
 from .component import (
     Component,
@@ -24,7 +24,7 @@ from .store import Store
 from .styles import collect_styles, scope_css
 from .vdom import Element, Node, Text, to_dicts
 
-__version__ = "0.2.1"
+__version__ = "0.3.0"
 
 __all__ = [
     "Component",
@@ -43,6 +43,8 @@ __all__ = [
     "Store",
     "set_title",
     "dialogs",
+    "http",
+    "storage",
     "collect_styles",
     "scope_css",
     "diff",

{pyweft-0.2.1 → pyweft-0.3.0}/src/pyweft/cli.py

@@ -234,6 +234,26 @@ def app_identity(app_dir: Path) -> AppIdentity:
     return AppIdentity(title=title.strip(), icon=icon)
 
 
+def app_id(app_dir: Path) -> str:
+    """A stable name for keeping the app's data apart (pyweft.storage): the
+    ``[project]`` name from its pyproject.toml, else the folder's name.
+    Renaming the project starts its saved data afresh."""
+    name = ""
+    pyproject = app_dir / "pyproject.toml"
+    if pyproject.exists():
+        text = pyproject.read_text(encoding="utf-8")
+        if tomllib is not None:
+            try:
+                name = tomllib.loads(text).get("project", {}).get("name", "")
+            except tomllib.TOMLDecodeError as exc:
+                raise CliError(f"{pyproject}: {exc}") from None
+        else:
+            name = _flat_table(text, "project").get("name", "")
+    if not isinstance(name, str) or not name.strip():
+        name = app_dir.resolve().name
+    return re.sub(r"[^a-z0-9._-]+", "-", name.strip().lower()).strip("-.") or "app"
+
+
 # mimetypes reads the Windows registry, which can be wrong or missing these.
 _CONTENT_TYPES = {
     ".css": "text/css",
@@ -515,6 +535,7 @@ def render_shell(
             "__PYWEFT_LIBRARIES__",
             json.dumps([{"name": lib.name, "files": lib.files} for lib in app_libraries(app_dir)]),
         )
+        .replace("__PYWEFT_APP_ID__", json.dumps(app_id(app_dir)))
         .replace("__PYWEFT_DEV__", "true" if dev else "false")
         .replace("__PYWEFT_SINCE__", str(since))
         .replace("__PYWEFT_CSS__", css)

{pyweft-0.2.1 → pyweft-0.3.0}/src/pyweft/desktop.py

@@ -22,6 +22,7 @@ from __future__ import annotations
 import asyncio
 import concurrent.futures
 import json
+import os
 import re
 import sys
 import threading
@@ -32,7 +33,7 @@ from pathlib import Path
 from typing import Any, Callable
 from urllib.parse import unquote
 
-from . import dialogs, routing
+from . import dialogs, http, routing, storage
 from .component import load_component
 from .differ import diff
 from .hotreload import format_error, hot_swap
@@ -225,9 +226,20 @@ class DesktopApp:
     """One app, one window. ``window`` is anything with ``evaluate_js``:
     a pywebview window, or a stand-in in tests."""
 
-    def __init__(self, app_dir: Path, window: Any = None):
+    def __init__(
+        self,
+        app_dir: Path,
+        window: Any = None,
+        base_url: str | None = None,
+        storage_file: Path | None = None,
+    ):
         self.app_dir = Path(app_dir).resolve()
         self.window = window
+        # Where the window's page is served, so relative pyweft.http URLs
+        # (assets/data.json) work as they do in the browser.
+        self.base_url = base_url
+        # pyweft.storage's file; in memory without one (tests).
+        self.storage_file = storage_file
         self.here = "/"
         self.tree: list = []
         self.renderer: Renderer | None = None
@@ -281,6 +293,10 @@ class DesktopApp:
         sys.path.insert(0, str(self.app_dir))  # the app's own modules
         routing.set_host(_Location(self))
         dialogs.set_host(_Dialogs(self))
+        http.set_host(http.Urllib(base_url=self.base_url))
+        storage.set_host(
+            storage.FileStorage(self.storage_file) if self.storage_file else storage.MemoryStorage()
+        )
         self.cls = load_component(self.app_dir / "app.weft")
         self.renderer = Renderer(self.cls())
         # Already on the loop thread whenever app code changes state, except
@@ -539,10 +555,22 @@ def watch(app: DesktopApp, stop: threading.Event, interval: float = 0.3) -> None
             app.js("location.reload()")  # head.html, assets: the page remounts
 
 
+def data_dir(app_id: str) -> Path:
+    """Where a desktop app keeps its data (pyweft.storage): the user's
+    application data folder, in a folder named after the app."""
+    if sys.platform == "win32":
+        base = os.environ.get("APPDATA") or Path.home() / "AppData" / "Roaming"
+    elif sys.platform == "darwin":
+        base = Path.home() / "Library" / "Application Support"
+    else:
+        base = os.environ.get("XDG_DATA_HOME") or Path.home() / ".local" / "share"
+    return Path(base) / app_id
+
+
 def run_desktop(app_dir: Path, dev: bool = True) -> None:
     """The app in a window until it closes. ``dev`` (``pyweft run``) adds
     hot reload and terminal messages; a packaged app runs without them."""
-    from .cli import CliError, app_identity, app_pyweft_files
+    from .cli import CliError, app_id, app_identity, app_pyweft_files
 
     app_pyweft_files(app_dir)  # fails fast without an app.weft
     identity = app_identity(app_dir)  # and on a mistake in the settings
@@ -555,15 +583,16 @@ def run_desktop(app_dir: Path, dev: bool = True) -> None:
             'uv add "pyweft[desktop]"  (or: pip install "pyweft[desktop]")'
         ) from None
 
-    app = DesktopApp(app_dir)
+    server = make_server(app_dir)
+    threading.Thread(target=server.serve_forever, daemon=True).start()
+    url = f"http://127.0.0.1:{server.server_address[1]}/"
+    app = DesktopApp(app_dir, base_url=url, storage_file=data_dir(app_id(app_dir)) / "storage.json")
     try:
         app.start()
     except Exception as exc:  # noqa: BLE001 - shown as a CLI error
         app.stop()
+        server.shutdown()
         raise CliError(format_error(exc, root=str(Path(app_dir).resolve()))) from None
-    server = make_server(app_dir)
-    threading.Thread(target=server.serve_forever, daemon=True).start()
-    url = f"http://127.0.0.1:{server.server_address[1]}/"
     app.window = webview.create_window(identity.title, url, js_api=app.api, **options)
     stop = threading.Event()
     if dev: