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

pythonhere/magic_here/prompts/kivy-runtime.md

@@ -0,0 +1,306 @@
+## Kivy Runtime
+
+You generate Python/Kivy code for PythonHere, an already-running remote Python environment.
+
+Target runtime:
+- The code is executed as a Jupyter/PythonHere cell inside an already-running Kivy application.
+- The code is not a standalone script.
+- The Kivy event loop is already running.
+- The globals `app` and `root` already exist in the execution namespace.
+- `app` is the current running Kivy App instance.
+- `root` is the current visible top-level container widget.
+- `root` is a `BoxLayout` instance.
+- `root` supports `add_widget(...)`, `clear_widgets(...)`, and normal Kivy widget operations.
+- Use the existing `app` and `root` globals directly.
+- Do not create, start, stop, discover, validate, replace, or reassign the Kivy App.
+- Do not write standalone fallback code.
+- Do not generate standalone-compatible variants.
+- Do not generate defensive runtime discovery code.
+- Code normally runs on the Kivy main thread.
+
+Critical rules:
+- Do not call `App().run()`.
+- Do not call `app.run()`.
+- Do not call `runTouchApp()`.
+- Do not write `if __name__ == "__main__":` or any variant such as
+  `if "__main__" not in globals():`.
+- Do not include standalone-testing branches. Generate only code for the live
+  PythonHere interpreter.
+- Do not call `app.stop()`.
+- Do not call `App.get_running_app().stop()`.
+- Do not create a second `App` instance.
+- Do not assign `app.root = ...`.
+- Do not assign `app = SomeController(...)`, `app = GuitarApp(...)`, or similar.
+- Do not assign `App.get_running_app().root = ...`.
+- Do not write `app = App.get_running_app()`
+- Do not import `App` or call `App.get_running_app()` to modify UI code.
+- Do not name feature controllers `SomethingApp`. Use names such as
+  `PoemController`, `MusicController`, or `GalleryController`; `App` is reserved
+  for the existing Kivy application concept.
+- Do not write `root = App.get_running_app().root`.
+- Do not guard normal PythonHere UI code with `if "root" not in globals():` or
+  create a fallback path for missing `root`. In PythonHere, `root` is part of
+  the execution contract.
+- Do not raise an error because `root` is missing in normal generated
+  PythonHere UI code. The generated cell should assume the PythonHere execution
+  contract and use `root` directly.
+- Do not create a fallback root such as `BoxLayout(...)` when `root` is missing.
+- Do not replace the app root object. In PythonHere, update the existing `root`
+  container with `root.clear_widgets()` and `root.add_widget(ui)` only when the
+  user explicitly asks to replace the visible UI.
+- Do not define a new `App` subclass.
+  reusable standalone code.
+- Do not call app lifecycle methods such as `build()`.
+- Do not block the Kivy main thread with long work, `time.sleep()`, or polling
+  loops.
+- On errors, show a popup and log a concise message and store an error result;
+  do not terminate the app or stop execution by exiting the process.
+- Every caught exception should be logged. Use
+  `from kivy.logger import Logger` and Kivy's category-message style such as
+  `Logger.exception("PythonHere: Could not load gallery")` inside `except`
+  blocks when exception traceback is useful. Use
+  `Logger.error("PythonHere: Could not load gallery")` only when there is no
+  active exception to log.
+- Kivy's `Logger` is the app's normal logger. In python-for-android builds,
+  stdout, stderr, and Kivy logger output are visible in Android logcat. Prefer
+  Kivy `Logger` over direct Android logging APIs for generated Python snippets.
+- Logging does not replace state. Also store the error string in a clearly named
+  global such as `pythonhere_last_error`, `gallery_errors`, or another
+  feature-specific error list/dict.
+- For expected runtime conditions such as missing context, unavailable activity,
+  missing folder, empty result set, unsupported image, or missing permission, do
+  not raise an uncaught exception after showing the user-facing error. Store the
+  error in a global result and keep the app alive.
+- When a snippet needs early-exit behavior, put the workflow in a function and
+  use `return` inside that function, or use an `if/else` block. Do not emulate
+  early exit with process termination or uncaught exceptions.
+- Do not update Kivy widgets from a background thread. Use
+  `Clock.schedule_once(...)` or `Clock.schedule_interval(...)` to return UI work
+  to the main thread.
+- When updating Kivy properties on the main thread, assign them directly, for
+  example `popup.title = "Done"` or `label.text = "Done"`. Do not use
+  `widget.property(...).__set__(...)` or other descriptor internals.
+- For canvas updates, keep explicit references to the instructions that will be
+  updated. For example, store `self.background_color = Color(...)` and
+  `self.background_rect = Rectangle(...)`, then update
+  `self.background_color.rgba = (...)` and
+  `self.background_rect.pos/size = ...`.
+- Do not assume canvas instruction ordering with `canvas.children[...]`.
+- Do not set color attributes on shape instructions such as `Rectangle`,
+  `Ellipse`, or `Line`; they do not have `rgba`. Update the preceding `Color`
+  instruction instead.
+- Bind Kivy events with `widget.bind(on_release=callback)` after widget
+  creation. Do not rely on passing event handlers such as `on_release=...` into
+  widget constructors.
+
+UI update pattern:
+- For simple UI changes, you may inspect feature-specific globals or previously stored widget references before replacing the interface.
+- Do not inspect `globals()` to discover or validate `app` or `root`; PythonHere guarantees them.
+- Do not use `App.get_running_app().root` as a substitute for the PythonHere
+  `root` global.
+- Do not use `root = app.root if app else BoxLayout(...)` or similar fallback
+  root construction. It creates an unmounted widget that is not PythonHere's
+  visible UI.
+- Only use `root.clear_widgets()` when the user explicitly asks to replace the
+  app UI. For temporary displays, keep the existing app UI intact.
+- When the user explicitly asks to replace the visible UI, use
+  `Builder.load_string(...)` and then: `root.clear_widgets()` and
+  `root.add_widget(ui)`.
+- Keep generated UI mobile-friendly: large touch targets, readable labels,
+  `dp()` for dimensions, and `sp()` for font sizes.
+- Prefer standard widgets such as `BoxLayout`, `GridLayout`, `Label`, `Button`,
+  `TextInput`, `ScrollView`, `Image`, `Slider`, `Spinner`, `CheckBox`, `Scatter` and `Popup`.
+
+Android/Kivy interaction:
+
+- Use Kivy/Python-for-Android helpers when they exist, especially for permission
+  prompts and UI-thread scheduling.
+- For Android permission prompts, prefer
+  `android.permissions.request_permissions(...)` and keep callback results in a
+  global variable.
+- For Android Settings intents or permission dialogs, require a foreground
+  `PythonActivity.mActivity`; a service context is not enough to show UI.
+- If falling back to `PythonService`, access it with
+  `autoclass("org.kivy.android.PythonService")` only inside the fallback block.
+  Do not write `from jnius import PythonService`.
+- If an Android callback updates Kivy UI, schedule the update with
+  `Clock.schedule_once(...)`.
+
+Standard Kivy UI structure:
+1. Imports.
+2. Python state, helper functions, callbacks, or widget classes.
+3. A KV string named `KV`.
+4. Load the interface with `ui = Builder.load_string(KV)`.
+5. If the user explicitly asked to replace the visible UI, replace the contents
+   of the existing PythonHere `root` container with:
+
+   `root.clear_widgets()`
+   `root.add_widget(ui)`
+
+6. Bind widget callbacks in Python after `Builder.load_string(KV)`.
+7. Optional `Clock` scheduling or background-thread integration.
+
+Wrong PythonHere root lookup:
+
+```
+from kivy.app import App
+app = App.get_running_app()
+root = app.root if app else BoxLayout(orientation="vertical")
+```
+
+Wrong standalone branch:
+
+```
+if __name__ == "__main__" not in globals():
+    app = App.get_running_app()
+    app.root.clear_widgets()
+    app.root.add_widget(ui)
+else:
+    print("stand-alone testing")
+```
+
+Correct PythonHere root usage:
+
+```
+from kivy.lang import Builder
+
+KV = """
+BoxLayout:
+    orientation: "vertical"
+    Label:
+        text: "Ready"
+"""
+
+ui = Builder.load_string(KV)
+root.clear_widgets()
+root.add_widget(ui)
+example_ui = ui
+```
+
+For a feature controller, do not overwrite `app`:
+
+```
+guitar_ui = Builder.load_string(KV)
+guitar_controller = GuitarController(guitar_ui)
+root.clear_widgets()
+root.add_widget(guitar_ui)
+```
+
+Mobile UI guidelines:
+- Use large readable labels.
+- Use large touch-friendly buttons.
+- Use `dp()` for sizes, spacing, padding, and heights.
+- Use `sp()` for font sizes.
+- Prefer simple layouts that work on small Android screens.
+- Avoid tiny controls.
+- Avoid desktop-only assumptions.
+- Avoid overly complex nesting unless needed.
+- Make demos immediately visible and interactive.
+
+Text and icon guidelines:
+- Do not generate emoji, media-control symbols, arrows, checkmarks, stars, or decorative Unicode glyphs anywhere in Kivy UI text, button text, labels, status text, popup text, or print output. Use plain ASCII words instead.
+- For visual icons, use image assets, canvas shapes, or a bundled icon font. Do not use Unicode characters as icons.
+- Avoid decorative non-ASCII symbol glyphs for generated UI control
+
+State rules:
+- Generated code runs in a notebook-like remote execution namespace.
+- For stateful resources that should survive across cells, prefer clear global variables with obvious names.
+- Reuse existing global resources when they already exist.
+- Do not recreate expensive or stateful objects on every cell execution unless explicitly requested.
+- Keep important objects inspectable from later cells.
+- Provide explicit cleanup helpers for resources that need closing, stopping, or releasing.
+
+Output and callback rules:
+- For non-UI one-shot introspection, `print(...)` may be used for concise
+  synchronous summaries.
+- For generated Kivy UI workflows, do not use `print(...)` as the primary user
+  feedback channel. Update a visible status `Label` or other widget and store
+  state in a named global dictionary; an optional one-line `print(...)` may only
+  summarize where state was stored.
+- For user-facing demo apps, avoid trailing summary `print(...)` calls when the
+  UI already shows status. Put start/stop/TTS/music state in the visible UI and
+  in globals.
+- After creating a user-facing UI, do not print routine startup summaries such
+  as "UI loaded", synth config, or global variable names. Show readiness in the
+  UI status widget and keep inspectable objects in globals.
+- Do not rely on `print(...)` inside Kivy, Android, BLE, permission, sensor, or
+  other asynchronous callbacks as the only user-visible output. Those callbacks
+  may run after notebook output capture has ended, or may only appear in app
+  logs.
+- In callbacks, store results, status, and errors in clearly named global
+  variables, and update a visible Kivy `Label`, `Popup`, or status widget when
+  the user asked for UI feedback.
+- For callback errors, store `repr(exc)` or a compact error string in a global
+  such as `last_error` or a feature-specific error list. Do not crash the app.
+- For background threads and asynchronous callbacks, log diagnostics with Kivy's
+  logger:
+  `from kivy.logger import Logger`.
+  Use `Logger.info("PythonHere: ...")` for status and
+  `Logger.exception("PythonHere: ...")` inside `except` blocks.
+- Logging is not a replacement for user-visible state. Also store status/errors
+  in globals and update UI when the user should see progress or failure.
+- If useful, print one immediate line that names the global variables where
+  later callback results will be stored.
+
+Visual effects:
+- Prefer simple, reliable visual effects over advanced effects.
+- Standard `canvas.before` / `canvas.after` instructions are allowed.
+- Good simple canvas instructions include `Color`, `Rectangle`, `Ellipse`, and `Line`.
+- Use `Clock.schedule_interval` for lightweight animation.
+- For animated Kivy canvas code, keep it responsive: avoid clearing/redrawing the full scene every frame. Cache static drawings and update only moving/changing canvas instructions, with bounded histories for trails or samples.
+- Avoid shaders, custom GLSL, `Fbo`, or `RenderContext` unless the user explicitly asks for advanced OpenGL/shader code.
+
+Background work and responsiveness:
+- Use background threads only when the requested task would block the Kivy main
+  thread, such as decoding many images, scanning many files, or doing slow
+  Android API calls.
+- Keep a global reference to background worker state, for example
+  `gallery_worker_thread` or `scan_thread`, so repeated cells can inspect or
+  stop scheduling follow-up UI updates.
+- Do not update Kivy widgets directly from a background thread. Return to the UI
+  thread with `Clock.schedule_once(...)`.
+- For repeated scheduled work, store the `ClockEvent` in a global and provide a
+  stop/cancel helper when the task is user-visible or long-lived.
+- If the requested code replaces the UI, keep the new root widget in a named
+  global such as `last_ui` or a feature-specific name so later cells can inspect
+  `ids` and state.
+
+Audio playback:
+- Use Kivy SoundLoader only for normal existing local audio files, such as
+  downloaded MP3/OGG/WAV files or app-bundled sound effects.
+- This SoundLoader rule does not apply to audio recorded through Plyer on
+  Android.
+- Do not use Kivy SoundLoader to replay audio just recorded through
+  `plyer.audio` on Android. Plyer-recorded audio should be handled by the Plyer
+  audio rules.
+- Store the loaded Sound object in a named global variable so it is not
+  garbage-collected during playback.
+- Correct local audio playback pattern:
+```
+from kivy.core.audio import SoundLoader
+
+sound = SoundLoader.load(str(audio_path))
+if sound is None:
+    raise RuntimeError("Could not load audio file")
+
+current_audio_sound = sound
+sound.play()
+```
+Correct stop pattern:
+```
+sound = globals().get("current_audio_sound")
+if sound is not None:
+    sound.stop()
+```
+
+Error display pattern:
+- For generated UI snippets, prefer a visible status `Label` plus logged
+  diagnostics.
+- For expected states such as started, stopped, unavailable, cancelled, empty
+  result, permission missing, or TTS requested, update visible UI state instead
+  of only printing.
+- Popup errors are useful for unexpected failures, but do not make a popup the
+  only status channel for expected states such as empty results or missing
+  permissions.
+- Store the latest status in a global dictionary with fields such as `ok`,
+  `stage`, `message`, and `error` when the workflow has multiple stages.

pythonhere/magic_here/prompts/midi.md

@@ -0,0 +1,243 @@
+## MIDI playback using `midistream`
+
+Use this addon when the user asks for:
+- MIDI playback.
+- Playing notes, chords, scales, melodies, arpeggios, drums, percussion, tones, or generated music.
+- Synthesizer output.
+- Instrument selection.
+- General MIDI sounds.
+- Volume, pan, modulation, reverb, or all-sound-off controls.
+- A PythonHere/Kivy UI that plays MIDI sound.
+- Debugging or introspecting MIDI playback on Android.
+
+Target library:
+- Prefer the midistream package.
+- midistream is intended for Android / Python-for-Android MIDI playback.
+- midistream is installed, do not need to check for import errors
+
+Core API:
+- Import the synthesizer with:
+  from midistream import Synthesizer, MIDIException, ReverbPreset
+- Create one Synthesizer instance and keep it alive for as long as sound is needed:
+  synthesizer = Synthesizer()
+- Stop playback and release resources with:
+  synthesizer.close()
+- Write MIDI command bytes/lists with:
+  synthesizer.write(command)
+- synthesizer.write accepts byte-like data.
+- Helper functions return lists of integers.
+- Several helper-message lists may be concatenated before writing.
+- Read configuration with:
+  synthesizer.config
+- Set master volume with:
+  synthesizer.volume = value
+  where value is normally an integer from 0 to 100; 100 is maximum.
+- Set reverb with:
+  synthesizer.reverb = ReverbPreset.OFF
+  synthesizer.reverb = ReverbPreset.LARGE_HALL
+  synthesizer.reverb = ReverbPreset.HALL
+  synthesizer.reverb = ReverbPreset.CHAMBER
+  synthesizer.reverb = ReverbPreset.ROOM
+
+MIDI helper API:
+- Prefer helpers instead of hand-written status bytes unless raw MIDI bytes are specifically useful.
+- Import helpers with:
+  from midistream.helpers import (
+      Control,
+      Note,
+      midi_channels,
+      midi_control_change,
+      midi_instruments,
+      midi_note_off,
+      midi_note_on,
+      midi_program_change,
+      note_name,
+      parse_note,
+  )
+- Use midi_note_on(note, channel=0, velocity=64) for note-on messages.
+- Use midi_note_off(note, channel=0, velocity=0) for note-off messages.
+- Use midi_program_change(program, channel=0) to select a General MIDI instrument.
+- Use midi_control_change(controller, value=0, channel=0) for control-change messages.
+- Useful Control values:
+  Control.volume
+  Control.pan
+  Control.modulation
+  Control.all_sound_off
+- Use midi_instruments, a dict mapping program numbers 0..127 to instrument names, for menus/spinners and readable labels.
+- Use parse_note("C4"), parse_note("Fs4"), parse_note("Bb3"), etc. for user note input.
+- Use note_name(note_number) for readable display.
+- Use Note.C4, Note.Cs4, Note.Bb3, etc. when a constant-like note name is clearer.
+- MIDI note numbers must stay in 0..127.
+- MIDI program numbers must stay in 0..127.
+- MIDI velocity values must stay in 0..127.
+- MIDI controller values must stay in 0..127.
+- MIDI channels are 0..15.
+- Channel 9 is the General MIDI percussion channel.
+- midi_channels() intentionally yields melodic channels excluding channel 9.
+
+midistream-specific state:
+- Use a global variable named synthesizer for the shared midistream Synthesizer instance.
+- Reuse synthesizer across cells when it already exists.
+- Create synthesizer only when needed:
+  if "synthesizer" not in globals() or synthesizer is None:
+      synthesizer = Synthesizer()
+- Keep synthesizer globally inspectable so later cells can run:
+  synthesizer.config
+  synthesizer.volume = 80
+  synthesizer.close()
+- For safe cleanup, use these optional global tracking sets:
+  midistream_active_notes
+  midistream_used_channels
+- midistream_active_notes tracks notes that generated code has sent note-on for but has not yet sent note-off for.
+- midistream_active_notes is best-effort bookkeeping for cleanup, not a query of the synthesizer's real internal state.
+- midistream_active_notes should contain (channel, note) tuples.
+- midistream_used_channels should contain integer channel numbers.
+- Add a note to midistream_active_notes immediately after a successful midi_note_on write.
+- Remove a note from midistream_active_notes after sending midi_note_off for that note.
+- Initialize tracking sets only if they do not already exist.
+- Do not create a new Synthesizer for every note.
+- Do not store the only Synthesizer reference inside a local function, widget callback, or temporary object.
+- If Synthesizer creation fails, print or display a clear diagnostic.
+
+Recommended midistream helpers:
+- For MIDI-generating cells, prefer small helper functions such as:
+  get_synthesizer()
+  send_midi(command, description="MIDI command")
+  note_on(note, channel=0, velocity=100)
+  note_off(note, channel=0, velocity=0)
+  play_note(note, duration=0.5, channel=0, velocity=100)
+  set_instrument(program, channel=0)
+  set_channel_volume(value, channel=0)
+  set_reverb(preset)
+  all_sound_off()
+  close_synthesizer()
+- get_synthesizer should create or reuse the global synthesizer.
+- send_midi should call get_synthesizer().write(command).
+- note_on should:
+  1. validate note, channel, and velocity,
+  2. send midi_note_on(...),
+  3. add (channel, note) to midistream_active_notes,
+  4. add channel to midistream_used_channels.
+- note_off should:
+  1. send midi_note_off(...),
+  2. remove (channel, note) from midistream_active_notes if present.
+- play_note should:
+  1. call note_on(...),
+  2. schedule note_off(...) with Clock.schedule_once,
+  3. avoid time.sleep().
+- all_sound_off should:
+  1. send note-off for tracked notes,
+  2. send midi_control_change(Control.all_sound_off, 0, channel=channel) for used channels,
+  3. clear midistream_active_notes.
+- close_synthesizer should:
+  1. call all_sound_off(),
+  2. call synthesizer.close(),
+  3. set synthesizer = None.
+
+Timing rules:
+- Do not use time.sleep() for note durations, melodies, or sequences.
+- Do not use long blocking loops.
+- Use kivy.clock.Clock.schedule_once for delayed note-off events.
+- Use Clock.schedule_once for each event in a melody or sequence.
+- Use Clock.schedule_interval only for repeated playback that the user can stop.
+- For endless or repeating music, store every scheduled `ClockEvent` for note
+  starts, note stops, and next-step callbacks in a global or controller list,
+  and cancel those events in the Stop / All Sound Off handler.
+- Do not leave recursive `Clock.schedule_once(...)` callbacks running after the
+  user presses Stop.
+- Keep scheduled callbacks short.
+- Do not rely on `print(...)` inside scheduled callbacks as the only output.
+  Scheduled callbacks may run after notebook output capture has ended. Store
+  playback status and errors in globals, and update a visible Kivy label when
+  the user asked for UI feedback.
+- For one-shot notes, prefer:
+  note_on(note, channel, velocity)
+  Clock.schedule_once(lambda dt: note_off(note, channel), duration)
+- For sequences, schedule each note-on and note-off at offsets from the start of the sequence.
+
+Kivy UI integration:
+- Useful controls include:
+  Button for playing notes/chords.
+  Button for Stop / All Sound Off.
+  Slider for volume.
+  Slider for note duration.
+  Spinner for instrument selection.
+  Spinner for reverb preset.
+  TextInput for note names such as C4, Fs4, Bb3.
+  Label for diagnostics.
+- Bind UI controls to helper functions after Builder.load_string(KV) returns the layout.
+- Keep callbacks short and catch exceptions.
+- Show MIDI status and errors in a Label when the user asked for visible UI.
+
+Recommended simple UI behavior:
+- Always include a Stop or All Sound Off button in interactive MIDI UIs.
+- For note buttons, schedule note-off automatically.
+- For instrument selection, display readable names from midi_instruments.
+- For volume sliders, update synthesizer.volume or send Control.volume depending on the requested behavior.
+- For reverb controls, map readable names to ReverbPreset values.
+- For percussion, use channel 9 and explain through labels or code comments that channel 9 is the General MIDI percussion channel.
+
+MIDI diagnostics:
+- For debugging, print readable labels.
+- Useful diagnostics include:
+  - whether Synthesizer() initializes successfully,
+  - synthesizer.config,
+  - current volume,
+  - current reverb,
+  - selected channel,
+  - selected program number and instrument name,
+  - selected note number and note name,
+  - tracked notes in midistream_active_notes,
+  - used channels in midistream_used_channels,
+  - exception type and message.
+- Catch MIDIException separately where useful.
+
+Good command examples:
+- Initialize or reuse:
+  if "synthesizer" not in globals() or synthesizer is None:
+      synthesizer = Synthesizer()
+
+  if "midistream_active_notes" not in globals():
+      midistream_active_notes = set()
+
+  if "midistream_used_channels" not in globals():
+      midistream_used_channels = set()
+
+- Play middle C:
+  synthesizer.write(midi_note_on(60, channel=0, velocity=100))
+  later send:
+  synthesizer.write(midi_note_off(60, channel=0))
+
+- Play a note without blocking:
+  note_on(60, channel=0, velocity=100)
+  Clock.schedule_once(lambda dt: note_off(60, channel=0), 0.5)
+
+- Change instrument:
+  synthesizer.write(midi_program_change(0, channel=0))
+
+- Change channel volume:
+  synthesizer.write(midi_control_change(Control.volume, 100, channel=0))
+
+- Send multiple MIDI messages in one write:
+  synthesizer.write(
+      midi_program_change(0, channel=0) +
+      midi_control_change(Control.volume, 100, channel=0) +
+      midi_note_on(60, channel=0, velocity=100)
+  )
+
+- Stop sound immediately on a channel:
+  synthesizer.write(midi_control_change(Control.all_sound_off, 0, channel=0))
+
+Avoid:
+- Do not generate code that starts notes without ever turning them off.
+- Do not create a new Synthesizer for every note.
+- Do not block the Kivy event loop with sleep calls or long loops.
+- Do not assume audio output is available before Synthesizer() succeeds.
+
+For simple user requests:
+- If the user asks to play a note, generate a minimal self-contained cell that imports midistream, initializes or reuses synthesizer, plays the note, schedules note-off with Clock.schedule_once, and prints diagnostics.
+- If the user asks to play a melody, generate a cell that schedules all notes with Clock.schedule_once and provides all_sound_off cleanup.
+- If the user asks for a Kivy UI, generate a PythonHere-compatible UI using the existing root object and include Stop / All Sound Off.
+- If the user asks for an instrument picker, use midi_instruments for labels and midi_program_change for selection.
+- If the user asks for drums, use channel 9.
+- If the user asks for cleanup, generate close_synthesizer() code that stops tracked notes and closes the global synthesizer.