pythonhere 0.1.4__tar.gz → 0.2.0__tar.gz

pythonhere-0.2.0/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2020 b3b
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

pythonhere-0.2.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: pythonhere
+Version: 0.2.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
+Project-URL: Homepage, https://github.com/b3b/ipython-pythonhere
+Project-URL: Changelog, https://github.com/b3b/pythonhere/blob/master/CHANGELOG.rst
+Keywords: android,ipython,jupyter,magic,kivy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+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: ipython
+Requires-Dist: ipywidgets
+Requires-Dist: Pillow
+Dynamic: license-file
+
+PythonHere
+==========
+
+.. start-badges
+.. image:: https://img.shields.io/pypi/status/pythonhere
+    :target: https://pypi.python.org/pypi/pythonhere
+    :alt: Status
+.. image:: https://img.shields.io/pypi/v/pythonhere.svg
+    :target: https://pypi.python.org/pypi/pythonhere
+    :alt: Latest version on PyPi
+.. image:: https://img.shields.io/docker/v/herethere/pythonhere?color=%23FFD43B&label=Docker%20Image
+   :target: https://hub.docker.com/r/herethere/pythonhere
+   :alt: Docker Image Version (latest by date)
+.. image:: https://img.shields.io/pypi/pyversions/pythonhere.svg
+    :target: https://pypi.python.org/pypi/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          
+.. image:: https://codecov.io/github/b3b/pythonhere/coverage.svg?branch=master
+    :target: https://codecov.io/github/b3b/pythonhere?branch=master
+    :alt: Code coverage Status
+.. end-badges
+
+*PythonHere* lets you run Python code from a local `Jupyter <https://jupyter.org/>`_
+notebook inside a remote `Kivy <https://kivy.org>`_ app.
+
+PythonHere has two parts:
+
+* *Here* is the remote/server side. It runs a Python environment with a Kivy GUI,
+  for example on Android, Raspberry Pi, or another machine.
+* *%there* is the local/client side. It is a Jupyter magic command for running
+  code interactively in the remote PythonHere environment.
+
+This makes PythonHere useful as a live Python/Kivy playground, and as a way to
+inspect or control a Python app running remotely.
+
+Project documentation: https://herethere.me/pythonhere
+
+.. image:: https://raw.githubusercontent.com/b3b/pythonhere/master/docs/description.png
+  :alt: Project description
+
+
+Install the Android app
+-----------------------
+
+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>`_.
+For a list of Python packages included in the Android build, see `buildozer.spec <https://github.com/b3b/pythonhere/blob/master/buildozer.spec>`_.
+
+Start a local Jupyter environment with Docker
+---------------------------------------------
+
+The Docker image is based on `Jupyter Docker Stacks <https://jupyter-docker-stacks.readthedocs.io/en/latest/>`_
+and includes *PythonHere* with usage examples.
+
+Example command to start the Docker container::
+
+    docker run \
+           --rm \
+           -p 8888:8888 \
+           --user root \
+           -e CHOWN_EXTRA=/home/jovyan/work \
+           -e CHOWN_EXTRA_OPTS='-R' \
+           -v "$(pwd)/work":/home/jovyan/work \
+           herethere/pythonhere:latest
+
+The command exposes the Jupyter server on host port ``8888``. Jupyter logs are
+printed in the terminal and include a URL such as
+``http://127.0.0.1:8888/?token=...``. Open this URL in a browser to use the
+local Jupyter environment.
+
+Files in ``/home/jovyan/work`` inside the container are stored in the local
+``work`` directory.
+
+
+Run a local Jupyter environment without Docker
+----------------------------------------------
+
+Commands to run locally::
+
+   pip install pythonhere jupyter
+   jupyter notebook
+
+
+Build Android app
+-----------------
+
+To build with `Buildozer <https://github.com/kivy/buildozer>`_, run in the source directory::
+
+
+  buildozer android debug
+
+
+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

pythonhere-0.2.0/README.rst

@@ -0,0 +1,101 @@
+PythonHere
+==========
+
+.. start-badges
+.. image:: https://img.shields.io/pypi/status/pythonhere
+    :target: https://pypi.python.org/pypi/pythonhere
+    :alt: Status
+.. image:: https://img.shields.io/pypi/v/pythonhere.svg
+    :target: https://pypi.python.org/pypi/pythonhere
+    :alt: Latest version on PyPi
+.. image:: https://img.shields.io/docker/v/herethere/pythonhere?color=%23FFD43B&label=Docker%20Image
+   :target: https://hub.docker.com/r/herethere/pythonhere
+   :alt: Docker Image Version (latest by date)
+.. image:: https://img.shields.io/pypi/pyversions/pythonhere.svg
+    :target: https://pypi.python.org/pypi/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          
+.. image:: https://codecov.io/github/b3b/pythonhere/coverage.svg?branch=master
+    :target: https://codecov.io/github/b3b/pythonhere?branch=master
+    :alt: Code coverage Status
+.. end-badges
+
+*PythonHere* lets you run Python code from a local `Jupyter <https://jupyter.org/>`_
+notebook inside a remote `Kivy <https://kivy.org>`_ app.
+
+PythonHere has two parts:
+
+* *Here* is the remote/server side. It runs a Python environment with a Kivy GUI,
+  for example on Android, Raspberry Pi, or another machine.
+* *%there* is the local/client side. It is a Jupyter magic command for running
+  code interactively in the remote PythonHere environment.
+
+This makes PythonHere useful as a live Python/Kivy playground, and as a way to
+inspect or control a Python app running remotely.
+
+Project documentation: https://herethere.me/pythonhere
+
+.. image:: https://raw.githubusercontent.com/b3b/pythonhere/master/docs/description.png
+  :alt: Project description
+
+
+Install the Android app
+-----------------------
+
+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>`_.
+For a list of Python packages included in the Android build, see `buildozer.spec <https://github.com/b3b/pythonhere/blob/master/buildozer.spec>`_.
+
+Start a local Jupyter environment with Docker
+---------------------------------------------
+
+The Docker image is based on `Jupyter Docker Stacks <https://jupyter-docker-stacks.readthedocs.io/en/latest/>`_
+and includes *PythonHere* with usage examples.
+
+Example command to start the Docker container::
+
+    docker run \
+           --rm \
+           -p 8888:8888 \
+           --user root \
+           -e CHOWN_EXTRA=/home/jovyan/work \
+           -e CHOWN_EXTRA_OPTS='-R' \
+           -v "$(pwd)/work":/home/jovyan/work \
+           herethere/pythonhere:latest
+
+The command exposes the Jupyter server on host port ``8888``. Jupyter logs are
+printed in the terminal and include a URL such as
+``http://127.0.0.1:8888/?token=...``. Open this URL in a browser to use the
+local Jupyter environment.
+
+Files in ``/home/jovyan/work`` inside the container are stored in the local
+``work`` directory.
+
+
+Run a local Jupyter environment without Docker
+----------------------------------------------
+
+Commands to run locally::
+
+   pip install pythonhere jupyter
+   jupyter notebook
+
+
+Build Android app
+-----------------
+
+To build with `Buildozer <https://github.com/kivy/buildozer>`_, run in the source directory::
+
+
+  buildozer android debug
+
+
+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

pythonhere-0.2.0/pyproject.toml

@@ -0,0 +1,151 @@
+[build-system]
+requires = ["setuptools>=70", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pythonhere"
+dynamic = ["version"]
+description = "Here is the Kivy based app to run code from the Jupyter magic %there"
+readme = { file = "README.rst", content-type = "text/x-rst" }
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    { name = "b3b", email = "ash.b3b@gmail.com" },
+]
+keywords = ["android", "ipython", "jupyter", "magic", "kivy"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+dependencies = [
+    "herethere[magic]>=0.1.0",
+    "ipython",
+    "ipywidgets",
+    "Pillow",
+]
+
+[dependency-groups]
+dev = [
+    { include-group = "docker" },
+    "build",
+    "codecov",
+    "docutils",
+    "ifaddr",
+    "kivy==2.3.1",
+    "nest-asyncio2==1.7.2",
+    "pylint",
+    "pytest",
+    "pytest-asyncio",
+    "pytest-cov",
+    "pytest-mock",
+    "ruff",
+    "twine",
+]
+docker = [
+    "jupytext==1.19.3",
+]
+
+[project.urls]
+Homepage = "https://github.com/b3b/ipython-pythonhere"
+Changelog = "https://github.com/b3b/pythonhere/blob/master/CHANGELOG.rst"
+
+[tool.uv]
+environments = [
+    "sys_platform == 'linux'",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.setuptools]
+packages = [
+    "pythonhere",
+    "pythonhere.magic_here",
+    "pythonhere.ui_here",
+]
+
+[tool.setuptools.dynamic]
+version = { attr = "pythonhere.version_here.__version__" }
+
+[tool.setuptools.package-data]
+pythonhere = [
+    "*.kv",
+    "data/logo/*.png",
+    "ui_here/*.kv",
+]
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "E",    # pycodestyle errors
+    "F",    # pyflakes
+    "W",    # pycodestyle warnings
+    "I",    # import sorting
+    "UP",   # pyupgrade
+    "B",    # flake8-bugbear
+    "TRY",  # exception handling checks
+    "PL",   # pylint-style checks supported by Ruff
+]
+ignore = [
+    "PLC0207", # keep simple last-part string splits when they are clearer
+    "PLC0415", # allow delayed Kivy/Android imports that control side effects
+    "TRY002", # keep existing broad app-facing exceptions for now
+    "TRY003", # allow direct exception messages in this small app
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = [
+    "PLR0913", # parametrized tests naturally pass several fixtures/values
+    "PLR2004", # literal expected values are readable in tests
+    "PLW0603", # tests may intentionally exercise global namespace behavior
+]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.pylint.main]
+fail-under = 10.0
+ignore = ["migrations"]
+py-version = "3.10"
+
+[tool.pylint."messages control"]
+disable = [
+  "attribute-defined-outside-init",
+  "bad-inline-option",
+  "broad-exception-caught",
+  "broad-exception-raised",
+  "deprecated-pragma",
+  "duplicate-code",
+  "file-ignored",
+  "import-outside-toplevel",
+  "import-error",
+  "inconsistent-return-statements",
+  "invalid-name",
+  "locally-disabled",
+  "logging-too-few-args",
+  "missing-function-docstring",
+  "missing-module-docstring",
+  "no-member",
+  "possibly-used-before-assignment",
+  "protected-access",
+  "raw-checker-failed",
+  "suppressed-message",
+  "too-few-public-methods",
+  "too-many-instance-attributes",
+  "unnecessary-ellipsis",
+  "unused-argument",
+  "unused-wildcard-import",
+  "use-symbolic-message-instead",
+  "useless-suppression",
+  "wildcard-import",
+  "wrong-import-order",
+]
+enable = ["c-extension-no-member"]

pythonhere-0.2.0/pythonhere/android_here.py

@@ -0,0 +1,100 @@
+"""Android specific functions."""
+
+# pylint: disable=invalid-name,import-error,import-outside-toplevel
+import uuid
+from pathlib import Path
+
+from android import activity as android_activity
+from jnius import autoclass, cast
+from kivy.logger import Logger
+
+Context = autoclass("android.content.Context")
+Icon = autoclass("android.graphics.drawable.Icon")
+Intent = autoclass("android.content.Intent")
+PythonActivity = autoclass("org.kivy.android.PythonActivity")
+ShortcutInfoBuilder = autoclass("android.content.pm.ShortcutInfo$Builder")
+System = autoclass("java.lang.System")
+Uri = autoclass("android.net.Uri")
+
+
+def get_current_intent() -> Intent:
+    """Return the intent that started Python activity."""
+    return PythonActivity.mActivity.getIntent()
+
+
+def get_startup_script(intent: None = None) -> str | None:
+    """Return script entrypoint that was passed to a given, or current, intent."""
+    if not intent:
+        intent = get_current_intent()
+    data = intent.getData()
+    return data and data.toString()
+
+
+def restart_app(script: str = None):
+    """Restart app, with a script as a starting point if provided."""
+    Logger.info("PythonHere: restart requested with a script: %s", script)
+    activity = PythonActivity.mActivity
+    intent = Intent(activity.getApplicationContext(), PythonActivity)
+    intent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
+    intent.setFlags(Intent.FLAG_ACTIVITY_CLEAR_TASK)
+
+    if script:
+        intent.setData(Uri.parse(script))
+
+    activity.startActivity(intent)
+    System.exit(0)
+
+
+def bind_run_script_on_new_intent():
+    """Add handler for new intent event:
+    restart app with entrypoint of a new intent.
+    """
+
+    def on_new_intent(intent):
+        Logger.info("PythonHere: on_new_intent")
+        restart_app(get_startup_script(intent))
+        Logger.error("PythonHere: app was not restarted")
+
+    android_activity.bind(on_new_intent=on_new_intent)
+
+
+def create_shortcut_icon() -> Icon:
+    """Create icon to use for a shurtcut."""
+    activity = PythonActivity.mActivity
+    Drawable = autoclass(f"{activity.getPackageName()}.R$drawable")
+    context = cast("android.content.Context", activity.getApplicationContext())
+    return Icon.createWithResource(context, Drawable.icon)
+
+
+def resolve_script_path(script: str) -> str:
+    """Resolve path against upload directory."""
+    from kivy.app import App
+
+    if script.startswith("/"):
+        path = Path(script)
+    else:
+        app = App.get_running_app()
+        path = Path(app.upload_dir) / script
+    return str(path.resolve(strict=True))
+
+
+def pin_shortcut(script: str, label: str):
+    """Request a pinned shortcut creation to run a Python script."""
+    activity = PythonActivity.mActivity
+    context = cast("android.content.Context", activity.getApplicationContext())
+
+    intent = Intent(activity.getApplicationContext(), PythonActivity)
+    intent.setAction(Intent.ACTION_MAIN)
+    intent.setData(Uri.parse(resolve_script_path(script)))
+
+    shortcut = (
+        ShortcutInfoBuilder(context, f"pythonhere-{uuid.uuid4().hex}")
+        .setShortLabel(label)
+        .setLongLabel(label)
+        .setIntent(intent)
+        .setIcon(create_shortcut_icon())
+        .build()
+    )
+
+    manager = activity.getSystemService(Context.SHORTCUT_SERVICE)
+    manager.requestPinShortcut(shortcut, None)

{pythonhere-0.1.4 → pythonhere-0.2.0}/pythonhere/enum_here.py

@@ -1,4 +1,5 @@
 """Enums."""
+
 from enum import Enum
 
 

pythonhere-0.2.0/pythonhere/exception_manager_here.kv

@@ -0,0 +1,22 @@
+<-UnhandledExceptionPopupHere>:
+    title: "Unhandled Exception catched"
+    BoxLayout:
+        orientation: 'vertical'
+        padding: 10
+        spacing: 20
+        Label:
+            size_hint_y: None
+            font_size: '18sp'
+            height: '24sp'
+            text: 'Exception details: '
+        ScrollView:
+            CodeInput:
+                id: catched_exception_code_input_here
+                text: root.message
+                size_hint: 1, None
+                height: self.minimum_height
+        Button:
+            size_hint_y: None
+            height: '40sp'
+            text: 'OK, continue'
+            on_press: root.dismiss()

{pythonhere-0.1.4 → pythonhere-0.2.0}/pythonhere/exception_manager_here.py

@@ -1,46 +1,26 @@
 """App exceptions manager."""
+
 import asyncio
 import traceback
-from typing import Optional
+from pathlib import Path
 
 from kivy.base import (
     ExceptionHandler,
     ExceptionManager,
 )
 from kivy.clock import Clock
-from kivy.properties import StringProperty  # pylint: disable=no-name-in-module
 from kivy.lang import Builder
 from kivy.logger import Logger
+from kivy.properties import StringProperty  # pylint: disable=no-name-in-module
 from kivy.uix.popup import Popup
 
 
 def load_exception_popup_style():
     """Load KV rules for `UnhandledExceptionPopupHere`."""
-    Builder.load_string(
-        """<-UnhandledExceptionPopupHere>:
-    title: "Unhandled Exception catched"
-    BoxLayout:
-        orientation: 'vertical'
-        padding: 10
-        spacing: 20
-        Label:
-            size_hint_y: None
-            font_size: '18sp'
-            height: '24sp'
-            text: 'Exception details: '
-        ScrollView:
-            CodeInput:
-                id: catched_exception_code_input_here
-                text: root.message
-                size_hint: 1, None
-                height: self.minimum_height
-        Button:
-            size_hint_y: None
-            height: '40sp'
-            text: 'OK, continue'
-            on_press: root.dismiss()
-    """
-    )
+    kv_path = str(Path(__file__).with_suffix(".kv"))
+
+    if kv_path not in Builder.files:
+        Builder.load_file(kv_path)
 
 
 class ErrorMessageOnException(ExceptionHandler):
@@ -48,9 +28,9 @@ class ErrorMessageOnException(ExceptionHandler):
 
     def handle_exception(self, exception) -> int:
         """Handle a exception."""
-        Logger.exception("Unhandled Exception catched")
         if isinstance(exception, (asyncio.CancelledError, KeyboardInterrupt)):
             return ExceptionManager.RAISE
+        Logger.exception("Unhandled Exception catched")
         show_exception_popup()
         return ExceptionManager.PASS
 
@@ -63,10 +43,14 @@ class UnhandledExceptionPopupHere(Popup):
 
 def install_exception_handler():
     """Install `ErrorMessageOnException` exception handler."""
-    ExceptionManager.add_handler(ErrorMessageOnException())
+    if not any(
+        isinstance(handler, ErrorMessageOnException)
+        for handler in ExceptionManager.handlers
+    ):
+        ExceptionManager.add_handler(ErrorMessageOnException())
 
 
-def show_exception_popup(exc: Optional[Exception] = None):
+def show_exception_popup(exc: Exception | None = None):
     """Show exception popup."""
     load_exception_popup_style()
     if exc:

pythonhere-0.2.0/pythonhere/launcher_here.py

@@ -0,0 +1,46 @@
+"""Utilities for launching scripts."""
+
+import os
+import runpy
+import sys
+from pathlib import Path
+
+from kivy import platform
+from kivy.logger import Logger
+
+
+def run_script(script: str):
+    """Execute given script."""
+    Logger.info("PythonHere: Run script %s", script)
+    try:
+        path = Path(script).resolve(strict=True)
+    except FileNotFoundError:
+        Logger.error("Script not found: %s", script)
+        raise Exception(f"Script not found: {script}") from None
+
+    original_cwd = str(Path.cwd())
+    original_sys_path = sys.path[:]
+    try:
+        script_dir = path.parent
+        os.chdir(str(script_dir))
+        sys.path.insert(0, str(script_dir))
+        runpy.run_path(str(path), run_name="__main__")
+    finally:
+        os.chdir(original_cwd)
+        sys.path = original_sys_path
+
+
+def try_startup_script():
+    """Execute startup script, if it was passed to app."""
+    if platform != "android":
+        return
+    import android_here  # pylint: disable=import-outside-toplevel
+
+    try:
+        android_here.bind_run_script_on_new_intent()
+        script = android_here.get_startup_script()
+        if script:
+            run_script(script)
+    except Exception:
+        Logger.exception("PythonHere: Error while starting script")
+        raise