pythonhere 0.4.0__py3-none-any.whl → 0.4.1__py3-none-any.whl

pythonhere/.agents/skills/pythonhere/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pythonhere
-description: "Build, inspect, and debug PythonHere applications by executing Python through the `there` CLI in an already-running Kivy/Python-for-Android process. Use when a task targets a PythonHere device or `there.env` connection and involves live Kivy UI, KV language, Android APIs, Pyjnius, permissions, installed Android packages, media/files, Plyer device features, BLE with able, MIDI with midistream, or on-device AI with LiteRT-LM and `.litertlm` models."
+description: "Build, inspect, and debug PythonHere applications by executing Python through the `there` CLI in an already-running Kivy/Python-for-Android process. Use when a task targets a PythonHere device or `there.env` connection and involves live Kivy UI, KV language, Android APIs, Pyjnius, permissions, installed Android packages, media/files, Plyer device features, BLE with able, MIDI with midistream, durable on-device task runs, or on-device AI with LiteRT-LM and `.litertlm` models."
 ---
 
 # Operate PythonHere with `there`
@@ -42,6 +42,8 @@ when the task depends on it broadly or requires its exact current contents.
 - Consult [midi.md](references/midi.md) for MIDI or synthesizer work.
 - Consult [litert.md](references/litert.md) for PythonHere's ML model helpers
   and LiteRT-LM usage.
+- Consult [tasks.md](references/tasks.md) for durable sequential work that must
+  continue after a client disconnect or recover after PythonHere restarts.
 
 Combine references when a feature genuinely needs details from several
 concerns; for example, an Android gallery may need permission, MediaStore, and

pythonhere/.agents/skills/pythonhere/references/tasks.md

@@ -0,0 +1,58 @@
+# Durable task runs
+
+Use `TaskRunner` for sequential work that must continue after the client
+disconnects, retain progress across a PythonHere restart, or retry individual
+items.
+
+## Start a run
+
+```python
+from tasks_here import TaskRunner
+
+runner = TaskRunner.create("data-import", max_attempts=3)
+runner.add([
+    {"id": "part-1", "path": "one.json"},
+    {"id": "part-2", "path": "two.json"},
+])
+runner.start(execute_task)
+```
+
+Tasks and results must contain plain JSON-compatible values. Every task needs a
+unique nonempty string `id`. `start()` returns promptly and processes one task
+at a time. Preserve the runner in a named global when later commands need it.
+
+Inspect `runner.status()`, `runner.results()`, `runner.get(id)`, or
+`runner.failed()` through normal `there get` calls. `pause()` finishes the
+current item and stops before claiming another.
+
+## Wait and inspect the outcome
+
+After starting the runner, wait in bounded intervals through the CLI:
+
+```bash
+there --json --timeout 60 get --worker \
+  "{'stopped': runner.wait(timeout=50), 'status': runner.status()}"
+```
+
+Here, `--worker` keeps the wait off the app's event loop.
+Keep the CLI timeout longer than the wait timeout to allow time for connection
+and response. If `stopped` is `false`, tasks continue running; repeat the command
+to wait again. A `true` value only means the worker is no longer running (or was
+never started), not that every task succeeded. Inspect `status.state`,
+`status.failed`, and `status.worker_error`. A `completed` state includes tasks
+that exhausted their retries; inspect `runner.failed()` for their errors.
+
+## Resume after restart
+
+After PythonHere restarts, reopen the named run, recreate resources and the
+executor callable, then restart execution:
+
+```python
+runner = TaskRunner.open("data-import")
+runner.start(execute_task)
+```
+
+Execution is at least once: an item interrupted by process death can run again.
+Make irreversible executor side effects idempotent or check their durable state
+before applying them. The executor runs in a background thread; marshal Kivy UI
+access to the main thread according to `kivy-runtime.md`.

pythonhere/main.py

@@ -26,6 +26,7 @@ from kivy.app import App
 from kivy.clock import Clock
 from kivy.config import Config, ConfigParser
 from kivy.logger import Logger
+from kivy.properties import StringProperty  # pylint: disable=no-name-in-module
 from patches_here import monkeypatch_kivy
 from server_here import run_ssh_server
 from window_here import reset_window_environment
@@ -42,6 +43,8 @@ def configure_logging():
 class PythonHereApp(App):
     """PythonHere main app."""
 
+    ssh_host_key_sha256 = StringProperty("")
+
     def __init__(self):
         super().__init__()
         self.server_task: asyncio.Task | None = None

pythonhere/server_here.py

@@ -39,6 +39,7 @@ async def run_ssh_server(app):
                 namespace=app.ssh_server_namespace,
                 server_factory=PythonHereServer,
             )
+            app.ssh_host_key_sha256 = server.host_key_sha256
         except Exception as exc:
             Logger.error("PythonHere: SSH server start error")
             Logger.exception(exc)