pythonhere 0.2.2__py3-none-any.whl → 0.3.0__py3-none-any.whl

pythonhere/.agents/skills/pythonhere/references/plyer.md

@@ -0,0 +1,202 @@
+## Plyer helpers
+
+Use this addon for Plyer-backed Android/device features:
+notification, Android toast-style messages, vibration, audio recording, camera capture,
+file chooser, GPS/location, battery, accelerometer, compass, text-to-speech,
+and similar Plyer facades.
+
+`plyer` is installed; do not need to check for import errors before normal use.
+
+Rules:
+- `plyer` is installed; do not need to check for import errors before normal use.
+- Prefer the `plyer` package for the supported device facades listed here.
+- Plyer does not have a separate `toast` facade. Do not write
+  `from plyer import toast`.
+- For Android toast-style messages, use
+  `from plyer import notification` and call
+  `notification.notify(..., toast=True)`.
+- Do not request permissions here unless the user explicitly asks; use the separate Android permissions prompt.
+- Do not access camera, microphone, GPS/location, sensors, contacts, SMS, call logs, or private files unless the user requested that specific capability.
+- Do not delete, overwrite, upload, or make network requests with selected files unless explicitly requested.
+- For asynchronous Plyer callbacks, store results in globals. If a Kivy UI is
+  involved, update visible UI through the Kivy runtime pattern.
+- For microphone recording, Android normally needs
+  `android.permission.RECORD_AUDIO` declared in the app manifest and granted at
+  runtime. Use the Android permissions prompt when the user asks to request or
+  check microphone permission.
+
+Text-to-speech rules:
+- For simple text-to-speech, use exactly this API shape:
+
+    from plyer import tts
+    tts.speak(message=text_to_read)
+
+- Do not use low-level Android framework speech APIs through Pyjnius for
+  ordinary read-aloud, speech, voice output, poem reading, or narration
+  requests. Use Pyjnius speech only when the user explicitly asks for lower-level
+  Android speech controls that Plyer does not expose.
+- Do not use legacy SL4A-style Android helper speech APIs.
+- Do not use desktop speech packages or platform shell commands for
+  Android/PythonHere TTS snippets.
+- Do not generate `TTS_AVAILABLE` fallback scaffolding or probe multiple TTS
+  backends unless the user explicitly asks for cross-platform desktop code.
+- Do not run `tts.speak(...)` inside a background Python thread. Use the Plyer
+  call directly from the `there run` program or from a short Kivy callback.
+- For a Kivy UI button or delayed speech start, the callback should call
+  `tts.speak(message=text)` directly and update UI state through the Kivy
+  runtime pattern.
+
+Plyer audio recording rules:
+- Use `plyer.audio` for audio recording workflows.
+- Do not use `plyer.audio` as a general local-file playback API.
+- Never call `audio.play(path)` or `audio.play("file.wav")`.
+- For Android Plyer recording, prefer `.3gp` output paths unless this runtime has
+  verified another format.
+- Do not name Plyer Android recordings `.wav` unless the backend is known to
+  write real WAV PCM data.
+- Replay audio recorded through Plyer with `audio.play()` and no arguments after
+  `audio.stop()`.
+- Stop recording or Plyer-managed playback with `audio.stop()`.
+- Do not use Kivy SoundLoader to replay audio just recorded through Plyer on
+  Android. Kivy SoundLoader is for normal existing local audio files and is
+  covered by the Kivy Runtime prompt.
+
+Toast example:
+    from plyer import notification
+
+    notification.notify(
+        title="",
+        message="Hello",
+        app_name="PythonHere",
+        toast=True,
+    )
+
+Notification example:
+    from plyer import notification
+
+    notification.notify(
+        title="PythonHere",
+        message="Done",
+        app_name="PythonHere",
+        timeout=5,
+    )
+
+Toast plus notification example:
+    from plyer import notification
+
+    notification.notify(
+        title="",
+        message="Done",
+        app_name="PythonHere",
+        toast=True,
+    )
+    notification.notify(
+        title="PythonHere",
+        message="Done",
+        app_name="PythonHere",
+        timeout=5,
+    )
+
+Vibration example:
+    from plyer import vibrator
+
+    vibrator.vibrate(0.2)
+
+Text-to-speech example:
+    from plyer import tts
+
+    tts.speak(message="Hello from PythonHere.")
+
+File chooser example:
+    from plyer import filechooser
+
+    def on_selection(paths):
+        plyer_filechooser_result = {
+            "paths": list(paths or []),
+            "cancelled_or_empty": not bool(paths),
+        }
+        globals()["plyer_filechooser_result"] = plyer_filechooser_result
+
+    filechooser.open_file(on_selection=on_selection)
+
+Audio recording start example:
+    from pathlib import Path
+    from datetime import datetime
+
+    from plyer import audio
+
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    plyer_audio_recording_path = str(Path.cwd() / f"pythonhere-recording-{timestamp}.3gp")
+    audio.file_path = plyer_audio_recording_path
+    audio.start()
+    plyer_audio_recording_status = {
+        "recording": True,
+        "path": plyer_audio_recording_path,
+    }
+
+Audio recording stop example:
+    from plyer import audio
+
+    audio.stop()
+    plyer_audio_recording_status = {
+        "recording": False,
+        "path": plyer_audio_recording_path,
+    }
+
+Audio recording replay example:
+    from plyer import audio
+
+    audio.play()
+
+Camera example:
+    from plyer import camera
+
+    camera.take_picture(
+        filename="photo.jpg",
+        on_complete=lambda path: globals().__setitem__(
+            "plyer_camera_result",
+            {"path": path, "cancelled_or_empty": not bool(path)},
+        ),
+    )
+
+GPS example:
+    from plyer import gps
+
+    def on_location(**kwargs):
+        globals()["plyer_gps_last_location"] = dict(kwargs)
+
+    gps.configure(on_location=on_location)
+    gps.start()
+
+GPS stop example:
+    from plyer import gps
+
+    gps.stop()
+
+Battery example:
+    from plyer import battery
+
+    status = battery.status
+
+Accelerometer example:
+    from plyer import accelerometer
+
+    accelerometer.enable()
+    acceleration = accelerometer.acceleration
+
+Compass example:
+    from plyer import compass
+
+    compass.enable()
+    heading = compass.orientation
+
+Plyer callback state pattern:
+- For every asynchronous Plyer facade, store callback results in a named global
+  such as `plyer_filechooser_result`, `plyer_camera_result`, or
+  `plyer_gps_last_location`.
+- If a Kivy UI is involved, update a visible status widget from the callback
+  using `Clock.schedule_once(...)` when needed.
+- Do not treat a callback returning an empty selection or `None` as an
+  exception; report it as a cancelled/empty result.
+- Keep file chooser behavior read-only unless the user explicitly asks to open,
+  process, copy, upload, delete, or overwrite selected files.

pythonhere/magic_here/shortcuts.py

@@ -16,12 +16,12 @@ load_kv_string(r'''{code} ''', clear_style={clear_style})
 
 SCREENSHOT_COMMAND_TEMPLATE = """
 import sys
-from window_here import encoded_screenshot
+from tools_here import encoded_screenshot
 sys.stderr.write(encoded_screenshot())
 """
 
 PIN_COMMAND_TEMPLATE = """
-from android_here import pin_shortcut
+from tools_here import pin_shortcut
 pin_shortcut(script="{script}", label="{label}")
 """
 

pythonhere/server_here.py

@@ -31,7 +31,7 @@ async def run_ssh_server(app):
             config = ServerConfig(
                 host="",
                 sftp_root=app.upload_dir,
-                key_path=Path("./key.rsa").resolve(),
+                key_path=Path("./ssh_host_key").resolve(),
                 **app.get_pythonhere_config(),
             )
             server = await start_server(

pythonhere/tools_here.py

@@ -0,0 +1,359 @@
+"""Reusable tools for the live PythonHere runtime."""
+
+import copy
+import json
+import math
+import threading
+from concurrent.futures import Future
+from concurrent.futures import TimeoutError as FutureTimeoutError
+from pathlib import Path
+from typing import Any
+
+MAIN_THREAD_BRIDGE_TIMEOUT = 10.0
+DEFAULT_UI_SNAPSHOT_DEPTH = 6
+DEFAULT_UI_SNAPSHOT_WIDGETS = 200
+MAX_UI_SNAPSHOT_CLASS = 120
+MAX_UI_SNAPSHOT_DEPTH = 48
+MAX_UI_SNAPSHOT_ERROR = 240
+MAX_UI_SNAPSHOT_WIDGETS = 500
+MAX_UI_SNAPSHOT_TEXT = 240
+
+
+class MainThreadBridgeError(RuntimeError):
+    """Kivy could not execute a requested main-thread operation."""
+
+
+class MainThreadTimeoutError(MainThreadBridgeError):
+    """Kivy did not execute a requested operation before its deadline."""
+
+
+def _clock_boundary():
+    """Return the Kivy Clock objects used by the worker-thread bridge."""
+    from kivy.clock import Clock, ClockNotRunningError
+
+    return Clock, ClockNotRunningError
+
+
+def _run_on_main_thread(function, /, *args, _timeout=None, **kwargs):
+    """Run ``function`` on Kivy's thread and synchronously return its result."""
+    if threading.current_thread() is threading.main_thread():
+        return function(*args, **kwargs)
+
+    timeout = MAIN_THREAD_BRIDGE_TIMEOUT if _timeout is None else _timeout
+    completion = Future()
+
+    def execute(_delta_time):
+        if not completion.set_running_or_notify_cancel():
+            return
+        try:
+            result = function(*args, **kwargs)
+        except BaseException as exc:  # Ensure every invocation releases its waiter.
+            completion.set_exception(exc)
+        else:
+            completion.set_result(result)
+
+    def clock_ended(_event):
+        if completion.set_running_or_notify_cancel():
+            completion.set_exception(
+                MainThreadBridgeError(
+                    "Kivy's Clock stopped before PythonHere could run the "
+                    "requested main-thread operation"
+                )
+            )
+
+    clock, clock_not_running_error = _clock_boundary()
+    try:
+        event = clock.create_lifecycle_aware_trigger(
+            execute,
+            clock_ended,
+            timeout=0,
+            release_ref=False,
+        )
+        event()
+    except clock_not_running_error as exc:
+        raise MainThreadBridgeError(
+            "Kivy's Clock is not running; PythonHere cannot run the requested "
+            "main-thread operation"
+        ) from exc
+
+    try:
+        return completion.result(timeout=timeout)
+    except FutureTimeoutError:
+        # An implementation may itself raise TimeoutError. Preserve it when it
+        # completed before the bridge deadline instead of mislabelling it.
+        if completion.done():
+            return completion.result()
+
+        cancelled_before_start = completion.cancel()
+        event.cancel()
+        if cancelled_before_start:
+            detail = "The operation was cancelled before it started."
+        elif completion.done():
+            return completion.result()
+        else:
+            detail = "The operation had started and may still complete."
+        raise MainThreadTimeoutError(
+            f"Kivy did not complete the requested main-thread operation within "
+            f"{timeout:g} seconds. {detail} Do not blindly retry mutations."
+        ) from None
+
+
+def _current_root(widget=None):
+    if widget is not None:
+        return widget
+
+    from kivy.app import App
+    from kivy.core.window import Window
+
+    app = App.get_running_app()
+    if app is not None and app.root is not None:
+        return app.root
+    if Window.children:
+        return Window.children[0]
+    raise RuntimeError("PythonHere has no visible root widget")
+
+
+def _json_number(value):
+    number = float(value)
+    if not math.isfinite(number):
+        return None
+    return round(number, 2)
+
+
+def _snapshot_limit(name: str, value: int, minimum: int, maximum: int) -> int:
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise TypeError(f"{name} must be an integer")
+    if not minimum <= value <= maximum:
+        raise ValueError(f"{name} must be between {minimum} and {maximum}")
+    return value
+
+
+def _optional_text(widget):
+    try:
+        value = widget.text
+        return (str(value) if value is not None else None), False
+    except AttributeError:
+        return None, False
+    except Exception:  # A custom diagnostic property must not abort the snapshot.
+        return None, True
+
+
+def _snapshot_widget(current, path):
+    children = list(reversed(getattr(current, "children", ())))
+    text, text_unavailable = _optional_text(current)
+    text_length = len(text) if text is not None else None
+    text_truncated = bool(text is not None and len(text) > MAX_UI_SNAPSHOT_TEXT)
+    if text_truncated:
+        text = text[: MAX_UI_SNAPSHOT_TEXT - 3] + "..."
+
+    class_name = type(current).__name__
+    class_truncated = len(class_name) > MAX_UI_SNAPSHOT_CLASS
+    if class_truncated:
+        class_name = class_name[: MAX_UI_SNAPSHOT_CLASS - 3] + "..."
+
+    item = {
+        "path": path,
+        "class": class_name,
+        "text": text,
+        "disabled": bool(getattr(current, "disabled", False)),
+        "pos": [_json_number(value) for value in current.pos],
+        "size": [_json_number(value) for value in current.size],
+        "child_count": len(children),
+    }
+    if class_truncated:
+        item["class_truncated"] = True
+    if text_unavailable:
+        item["text_unavailable"] = True
+    if text_length is not None:
+        item["text_length"] = text_length
+    if text_truncated:
+        item["text_truncated"] = True
+    return item, children
+
+
+def _compact_inspection_error(exc):
+    error_type = type(exc).__name__
+    if len(error_type) > MAX_UI_SNAPSHOT_CLASS:
+        error_type = error_type[: MAX_UI_SNAPSHOT_CLASS - 3] + "..."
+    try:
+        message = str(exc)
+    except Exception:
+        message = "<error message unavailable>"
+    if len(message) > MAX_UI_SNAPSHOT_ERROR:
+        message = message[: MAX_UI_SNAPSHOT_ERROR - 3] + "..."
+    return {"type": error_type, "message": message}
+
+
+def _customize_snapshot_widget(current, default_item, callback):
+    if callback is None:
+        return default_item
+
+    callback_item = copy.deepcopy(default_item)
+    try:
+        item = callback(current, callback_item)
+    except Exception as exc:
+        default_item["inspection_error"] = _compact_inspection_error(exc)
+        return default_item
+
+    if item is None:
+        return None
+    if not isinstance(item, dict):
+        exc = TypeError("widget_record_callback must return a dictionary or None")
+        default_item["inspection_error"] = _compact_inspection_error(exc)
+        return default_item
+
+    try:
+        json.dumps(item, allow_nan=False)
+    except Exception as exc:
+        default_item["inspection_error"] = _compact_inspection_error(exc)
+        return default_item
+    return item
+
+
+def _snapshot_ui(
+    widget=None,
+    *,
+    max_depth: int = DEFAULT_UI_SNAPSHOT_DEPTH,
+    max_widgets: int = DEFAULT_UI_SNAPSHOT_WIDGETS,
+    widget_record_callback=None,
+) -> dict[str, Any]:
+    """Return observable widget facts from Kivy's main thread."""
+    max_depth = _snapshot_limit(
+        "max_depth",
+        max_depth,
+        0,
+        MAX_UI_SNAPSHOT_DEPTH,
+    )
+    max_widgets = _snapshot_limit(
+        "max_widgets",
+        max_widgets,
+        1,
+        MAX_UI_SNAPSHOT_WIDGETS,
+    )
+    if widget_record_callback is not None and not callable(widget_record_callback):
+        raise TypeError("widget_record_callback must be callable or None")
+    widgets = []
+    pending = [("0", _current_root(widget), 0)]
+    omitted_descendants = False
+    visited_widgets = 0
+
+    while pending and visited_widgets < max_widgets:
+        path, current, depth = pending.pop()
+        visited_widgets += 1
+        default_item, children = _snapshot_widget(current, path)
+        item = _customize_snapshot_widget(
+            current,
+            default_item,
+            widget_record_callback,
+        )
+        if item is not None:
+            widgets.append(item)
+
+        if depth >= max_depth:
+            omitted_descendants = omitted_descendants or bool(children)
+        else:
+            for index in range(len(children) - 1, -1, -1):
+                pending.append((f"{path}/{index}", children[index], depth + 1))
+
+    return {
+        "widgets": widgets,
+        "widget_count": len(widgets),
+        "truncated": omitted_descendants or bool(pending),
+    }
+
+
+def snapshot_ui(
+    widget=None,
+    *,
+    max_depth: int = DEFAULT_UI_SNAPSHOT_DEPTH,
+    max_widgets: int = DEFAULT_UI_SNAPSHOT_WIDGETS,
+    widget_record_callback=None,
+) -> dict[str, Any]:
+    """Return observable widget facts, marshaling worker calls to Kivy."""
+    return _run_on_main_thread(
+        _snapshot_ui,
+        widget,
+        max_depth=max_depth,
+        max_widgets=max_widgets,
+        widget_record_callback=widget_record_callback,
+    )
+
+
+def _runtime_info(app=None, root=None) -> dict[str, Any]:
+    import kivy
+    from kivy.app import App
+    from kivy.core.window import Window
+    from kivy.utils import platform
+
+    if app is None:
+        app = App.get_running_app()
+    root = _current_root(root)
+    return {
+        "app_class": type(app).__name__ if app is not None else None,
+        "root_class": type(root).__name__,
+        "kivy_version": kivy.__version__,
+        "platform": platform,
+        "window_size": [_json_number(value) for value in Window.size],
+    }
+
+
+def runtime_info(app=None, root=None) -> dict[str, Any]:
+    """Return live Kivy runtime information, marshaling worker calls."""
+    return _run_on_main_thread(_runtime_info, app, root)
+
+
+def _save_screenshot(
+    path: str | Path = "pythonhere-screenshot.png",
+    widget=None,
+) -> str:
+    from kivy.app import App
+    from window_here import save_screenshot as save_window_screenshot
+
+    destination = Path(path)
+    if not destination.is_absolute():
+        app = App.get_running_app()
+        upload_dir = getattr(app, "upload_dir", None) if app is not None else None
+        destination = Path(upload_dir or Path.cwd()) / destination
+    return save_window_screenshot(destination, widget=widget)
+
+
+def save_screenshot(
+    path: str | Path = "pythonhere-screenshot.png",
+    widget=None,
+) -> str:
+    """Save visible content as PNG, marshaling worker calls to Kivy."""
+    return _run_on_main_thread(_save_screenshot, path, widget)
+
+
+def _encoded_screenshot(widget=None) -> str:
+    from window_here import encoded_screenshot as encode_window_screenshot
+
+    return encode_window_screenshot(widget=widget)
+
+
+def encoded_screenshot(widget=None) -> str:
+    """Encode visible content as PNG, marshaling worker calls to Kivy."""
+    return _run_on_main_thread(_encoded_screenshot, widget)
+
+
+def _pin_shortcut(script: str, label: str | None = None) -> None:
+    from android_here import pin_shortcut as pin_android_shortcut
+
+    shortcut_label = label or script.rstrip("/").rsplit("/", 1)[-1]
+    pin_android_shortcut(script=script, label=shortcut_label)
+
+
+def pin_shortcut(script: str, label: str | None = None) -> None:
+    """Request an Android shortcut, marshaling worker calls to Kivy."""
+    return _run_on_main_thread(_pin_shortcut, script, label)
+
+
+__all__ = (
+    "encoded_screenshot",
+    "MainThreadBridgeError",
+    "MainThreadTimeoutError",
+    "pin_shortcut",
+    "runtime_info",
+    "save_screenshot",
+    "snapshot_ui",
+)

pythonhere/version_here.py

@@ -1 +1 @@
-__version__ = "0.2.2"
+__version__ = "0.3.0"

pythonhere/window_here.py

@@ -1,6 +1,5 @@
 """Utilities for working with Kivy window."""
 
-import os
 import time
 from base64 import b64encode
 from pathlib import Path
@@ -53,13 +52,29 @@ def load_kv_string(code: str, clear_style: bool):
         app.update_ssh_server_namespace({"root": root})
 
 
-def encoded_screenshot() -> str:
-    """Return base64 encoded displayed image."""
+def save_screenshot(path: str | Path, widget=None) -> str:
+    """Save a widget, or the visible window content, as a PNG."""
     from kivy.core.window import Window  # pylint: disable=import-outside-toplevel
 
-    path = str(Path(f"screenshot_{time.time()}.png").resolve())
-    Window.children[0].export_to_png(path)
-    with open(path, "rb") as png_file:
-        data = b64encode(png_file.read()).decode()
-    os.remove(path)
-    return data
+    if widget is None:
+        if not Window.children:
+            raise RuntimeError("PythonHere has no visible content to capture")
+        widget = Window.children[0]
+
+    destination = Path(path).expanduser().resolve()
+    if not destination.parent.is_dir():
+        raise FileNotFoundError(
+            f"Screenshot directory does not exist: {destination.parent}"
+        )
+    widget.export_to_png(str(destination))
+    return str(destination)
+
+
+def encoded_screenshot(widget=None) -> str:
+    """Return base64 encoded displayed image."""
+    path = Path(f"screenshot_{time.time()}.png").resolve()
+    try:
+        save_screenshot(path, widget=widget)
+        return b64encode(path.read_bytes()).decode()
+    finally:
+        path.unlink(missing_ok=True)

{pythonhere-0.2.2.dist-info → pythonhere-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythonhere
-Version: 0.2.2
+Version: 0.3.0
 Summary: Here is the Kivy based app to run code from the Jupyter magic %there
 Author-email: b3b <ash.b3b@gmail.com>
 License-Expression: MIT
@@ -16,7 +16,7 @@ Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.10
 Description-Content-Type: text/x-rst
 License-File: LICENSE
-Requires-Dist: herethere[magic]>=0.2.3
+Requires-Dist: herethere[magic]>=0.3.1
 Requires-Dist: ipython
 Requires-Dist: ipywidgets
 Requires-Dist: Pillow
@@ -111,6 +111,15 @@ Commands to run locally::
    jupyter notebook
 
 
+Coding agents
+-------------
+
+PythonHere includes agent skills for working with the live app through the
+``there`` command-line interface. See `Coding agent skills
+<https://herethere.me/pythonhere/examples/coding-agents.html>`_ for skill setup
+and practical examples.
+
+
 Build Android app
 -----------------