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

pythonhere/magic_here/prompts/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 generated cell 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/prompts.py

@@ -0,0 +1,37 @@
+"""PythonHere prompt sections for ``%%there ai``."""
+
+from importlib.resources import files
+
+from herethere.there.ai import register_ai_prompt, set_ai_prompts
+
+PYTHONHERE_AI_ACTIVE_PROMPTS = (
+    "kivy-runtime",
+    "kivy-kv",
+    "android-runtime",
+    "jnius",
+    "android-permissions",
+    "android-packages",
+    "android-media",
+    "plyer",
+)
+
+PYTHONHERE_AI_PROMPTS = (
+    *PYTHONHERE_AI_ACTIVE_PROMPTS,
+    "able",
+    "midi",
+)
+
+
+def _read_prompt(name: str) -> str:
+    return (
+        files("pythonhere.magic_here")
+        .joinpath("prompts", f"{name}.md")
+        .read_text(encoding="utf-8")
+    )
+
+
+def register_pythonhere_ai_prompts() -> None:
+    """Register PythonHere Android/Kivy prompt sections as the active AI stack."""
+    for name in PYTHONHERE_AI_PROMPTS:
+        register_ai_prompt(name, _read_prompt(name))
+    set_ai_prompts("default", *PYTHONHERE_AI_ACTIVE_PROMPTS)

pythonhere/main.py

@@ -12,12 +12,14 @@ else:
     startup_script_exception = None  # pylint: disable=invalid-name
 
 import asyncio
+import logging
 import os
 import sys
 import threading
 from pathlib import Path
 from typing import Any
 
+import asyncssh
 from enum_here import ScreenName, ServerState
 from exception_manager_here import install_exception_handler, show_exception_popup
 from kivy.app import App
@@ -31,6 +33,12 @@ from window_here import reset_window_environment
 monkeypatch_kivy()
 
 
+def configure_logging():
+    """Configure logging for the app runtime."""
+    logging.getLogger().setLevel(logging.INFO)
+    asyncssh.set_log_level("WARNING")
+
+
 class PythonHereApp(App):
     """PythonHere main app."""
 
@@ -217,6 +225,7 @@ class PythonHereApp(App):
 
 async def main():
     """Run PythonHere."""
+    configure_logging()
     app = PythonHereApp()
     await app.run_app()
 

pythonhere/server_here.py

@@ -30,7 +30,7 @@ async def run_ssh_server(app):
         try:
             config = ServerConfig(
                 host="",
-                chroot=app.upload_dir,
+                sftp_root=app.upload_dir,
                 key_path=Path("./key.rsa").resolve(),
                 **app.get_pythonhere_config(),
             )

pythonhere/version_here.py

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythonhere
-Version: 0.2.0
+Version: 0.2.2
 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.1.0
+Requires-Dist: herethere[magic]>=0.2.3
 Requires-Dist: ipython
 Requires-Dist: ipywidgets
 Requires-Dist: Pillow
@@ -40,7 +40,7 @@ PythonHere
     :alt: Supported Python versions
 .. image:: https://github.com/b3b/pythonhere/actions/workflows/tests.yml/badge.svg?branch=master
    :target: https://github.com/b3b/pythonhere/actions/workflows/tests.yml?query=branch%3Amaster
-   :alt: CI Status          
+   :alt: CI Status
 .. image:: https://codecov.io/github/b3b/pythonhere/coverage.svg?branch=master
     :target: https://codecov.io/github/b3b/pythonhere?branch=master
     :alt: Code coverage Status
@@ -68,6 +68,9 @@ Project documentation: https://herethere.me/pythonhere
 Install the Android app
 -----------------------
 
+Install *PythonHere* with `Obtainium <https://apps.obtainium.imranr.dev/redirect?r=obtainium://add/https://github.com/b3b/pythonhere>`_
+to receive updates from GitHub Releases.
+
 Ready-to-use *PythonHere* APKs are available from the `GitHub Releases <https://github.com/b3b/pythonhere/releases>`_ page.
 
 For APK provenance and signing checks, see `Android APK verification <https://github.com/b3b/pythonhere/blob/master/docs/android-apk-verification.rst>`_.
@@ -120,6 +123,7 @@ To build with `Buildozer <https://github.com/kivy/buildozer>`_, run in the sourc
 Related resources
 -----------------
 
-* `Kivy Remote Shell <https://github.com/kivy/kivy-remote-shell>`_ : Remote SSH+Python interactive shell application
 * `herethere <https://github.com/b3b/herethere>`_ : Library for interactive code execution, based on AsyncSSH
 * `AsyncSSH <https://github.com/ronf/asyncssh>`_ : Asynchronous SSH for Python
+* `Buildozer <https://github.com/kivy/buildozer>`_ : Tool used to build the Android APK.
+* `python-for-android <https://github.com/kivy/python-for-android>`_ : Build toolchain used by Buildozer to package Python applications for Android.

{pythonhere-0.2.0.dist-info → pythonhere-0.2.2.dist-info}/RECORD

@@ -1,21 +1,33 @@
-pythonhere/__init__.py,sha256=gkVrYFkF3klE1fripHpmTuZx8_BaVHWRRvvr6PK6XWE,212
-pythonhere/android_here.py,sha256=imQCNkhAJYgT3gMeX25kd9cQzH5ZbeF5PlgP8e9sbl0,3316
+pythonhere/__init__.py,sha256=1GEGd8Y4FOPQOH1Mh6JC0GQDwV-0w83qV1KYCvGOxH0,466
+pythonhere/android_here.py,sha256=wBZNDgglichTFDpGuKFwdNbPXS2kVw8XvssnGd_4Y9Q,3546
 pythonhere/enum_here.py,sha256=FPj3pBeXfpPwl4-LDdC-wmbaoiv4QdbKHkGoBfTXnTE,449
 pythonhere/exception_manager_here.kv,sha256=FZNhQgVojSLcVxZ0vjAxAF915xCBP-3nldPXVczRzCE,656
 pythonhere/exception_manager_here.py,sha256=-UYqGRbzkoyfF0-pLWbxaFGEAvAdaw6b8hkm_bMIKx8,1943
 pythonhere/launcher_here.py,sha256=I5zBpN0P3hmhsZFOJemxQ9Q2k2am5zkfS6Vg0Svnl98,1274
-pythonhere/main.py,sha256=7vAF6mznCr2JFxeXjm3-a6PN1abPt-loI8ZHncAAPp0,7237
+pythonhere/main.py,sha256=lV4Wz_54khwQ9FE1u9YXkNay0x-3yc_-WmP3Loh7Z2o,7453
 pythonhere/network_here.py,sha256=e3FDlBcXPaTFlWaqW2_bcWctht-ifpFIvtOj0lO4S9w,1558
 pythonhere/patches_here.py,sha256=zB7Ohbk5PIXt0imnnrV5Mtl-Y7jpD_p5IBPlijQcCCQ,1727
 pythonhere/pythonhere.kv,sha256=x1xwiKvJAevqBhtXGLb_axIf-VRos4V_jM9Q2i44f2U,1453
-pythonhere/server_here.py,sha256=ss4Alg4ySkI0aG58l8D2SQMXiGHJeK-hGUIIBrbQ6nE,1854
-pythonhere/version_here.py,sha256=Zn1KFblwuFHiDRdRAiRnDBRkbPttWh44jKa5zG2ov0E,22
+pythonhere/server_here.py,sha256=Y3tOIQo0JBp50AUXOKQhxKMokvedV7QV_JSYPh4t99U,1857
+pythonhere/version_here.py,sha256=m6kyaNpwBcP1XYcqrelX2oS3PJuOnElOcRdBa9pEb8c,22
 pythonhere/window_here.py,sha256=na47v7bgomAjb6VC_g35RwhzEtm5RCInQIuQK27zY8U,2023
 pythonhere/data/logo/logo-128.png,sha256=4sitDJcVBHOU5UPxicmrzc6YqFY7_xtYrc_ULyrw9ks,4161
 pythonhere/data/logo/logo-32.png,sha256=qanrIAt6vK_2BsCjCxth2B4vxBa0ONnpDlils7syUWE,1247
 pythonhere/data/logo/logo-splash.png,sha256=-edmwKnkkpGP4RZ0AJYto5_BOy8NoISt5ftOEI8BQOY,4663
 pythonhere/magic_here/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pythonhere/magic_here/prompts.py,sha256=kiNSuHPEIgJdDYl84pLt_kBHtjdzWF_7sA9WS5wZCPU,899
 pythonhere/magic_here/shortcuts.py,sha256=pdB_ET6Snl4DxusbyZPI1_G8jGzA8d35er60qQb_2cY,2499
+pythonhere/magic_here/prompts/README.md,sha256=5r56B8NOieyYPu9xzHarpRR9oU9KqYWM2Ds0wfjuWYQ,1604
+pythonhere/magic_here/prompts/able.md,sha256=rh8f3muFdl2d50oOloWTc-mv9U7nuGBZtdsFXuiwzxQ,22836
+pythonhere/magic_here/prompts/android-media.md,sha256=vM55sxJmvkLQmKAjHZYL_z0F0SR__PjOHSXtGIgP1BI,6631
+pythonhere/magic_here/prompts/android-packages.md,sha256=naBfg68N7lXCd_d2fILgqTrcwLWK5NsGD_KDqlLs3S0,3834
+pythonhere/magic_here/prompts/android-permissions.md,sha256=g85CsmQvMU6CTbpD82BH7NEByFhqpHs6OW613hxZtdQ,10903
+pythonhere/magic_here/prompts/android-runtime.md,sha256=VCZkyw7nW5T-GtlF6R8vzYaQZ9BlMHWiTY4_X4DFwng,1674
+pythonhere/magic_here/prompts/jnius.md,sha256=lyjdGUsZXw2lS-0eppS2-JNTVgEED30z1DglzT6H0D8,14999
+pythonhere/magic_here/prompts/kivy-kv.md,sha256=ajIDSo6PG1_7gHcgfNrOARQOUlUEPUaeySQIxb6XjnM,8509
+pythonhere/magic_here/prompts/kivy-runtime.md,sha256=cAgOF0uE3RKYdKQus7h4lklKtANaLPcOYilGShjNtgM,14621
+pythonhere/magic_here/prompts/midi.md,sha256=2rKvgrwlmeA4MfdnRH9xnTSN0OFOm4mTxtgdYdMAd3Q,10611
+pythonhere/magic_here/prompts/plyer.md,sha256=wplCHPXkN1vU_thGIxvALuYPB6QDdjCHFhoc93ppvAE,6708
 pythonhere/ui_here/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pythonhere/ui_here/actionbar_here.kv,sha256=cOjY4ByOyBDUbeS9kbI3JAhi_X3kJ3Pb5h4RL58urwU,214
 pythonhere/ui_here/common_here.kv,sha256=vnNyDwAKKNbRKvh0QKMbTvR0jNDKiY8DdGRnoEEexSc,324
@@ -26,8 +38,8 @@ pythonhere/ui_here/server_screen_here.kv,sha256=x0Se8hmgjS57gFIPa1r2lf6yJchs3lXO
 pythonhere/ui_here/server_screen_here.py,sha256=2zQv1YFmiKNxa__7UZDYbAAAwYFLoZPSZPhr7vjCAkU,925
 pythonhere/ui_here/settings_here.kv,sha256=stMcDq8dCYjay4idK30_7EUu5edkMDAQVPv0H0GuAcM,710
 pythonhere/ui_here/settings_here.py,sha256=7NflZBUqY2ANZaSEuubaX9wIKniqbekcNQkUbqhhmto,4093
-pythonhere-0.2.0.dist-info/licenses/LICENSE,sha256=nW9_eVi3dSMOkr6xghsobAovBEJiffjl_5WjujJTa74,1071
-pythonhere-0.2.0.dist-info/METADATA,sha256=s6EVWNzwY9n6PDwLpNX6kVrd55fGxGpba3j26LYz7cQ,4790
-pythonhere-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-pythonhere-0.2.0.dist-info/top_level.txt,sha256=dvkfRGF1tFbkjXzD9vwqXTge1Znkv7ga5fRJy5yhJsE,11
-pythonhere-0.2.0.dist-info/RECORD,,
+pythonhere-0.2.2.dist-info/licenses/LICENSE,sha256=nW9_eVi3dSMOkr6xghsobAovBEJiffjl_5WjujJTa74,1071
+pythonhere-0.2.2.dist-info/METADATA,sha256=tSi1b9FPaAZhPx6wdMJA7TTjhoxFqsUynO-UgCTFtS4,5079
+pythonhere-0.2.2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+pythonhere-0.2.2.dist-info/top_level.txt,sha256=dvkfRGF1tFbkjXzD9vwqXTge1Znkv7ga5fRJy5yhJsE,11
+pythonhere-0.2.2.dist-info/RECORD,,