Add a Positron bootstrap. (#3114)

Author: freakboy3742

.github/workflows/ci.yml

@@ -63,6 +63,7 @@ jobs:
         - "gtk"
         - "iOS"
         - "toga"
+        - "positron"
         - "travertino"
         - "textual"
         - "web"
@@ -433,3 +434,54 @@ jobs:
     # - name: Setup tmate session
     #   uses: mxschmitt/action-tmate@v3
     #   if: failure()
+
+  bootstraps:
+    name: "Bootstrap"
+    needs: [ package ]
+    runs-on: "ubuntu-24.04"
+    strategy:
+      fail-fast: false
+      matrix:
+        bootstrap:
+        - "Positron (Django)"
+        - "Positron (Static)"
+        - "Positron (Site-specific)"
+        include:
+        - bootstrap: "Positron (Django)"
+          new-options: '-Q "bootstrap=Toga Positron (Django server)"'
+
+        - bootstrap: "Positron (Static)"
+          new-options: '-Q "bootstrap=Toga Positron (Static server)"'
+
+        - bootstrap: "Positron (Site-specific)"
+          new-options: '-Q "bootstrap=Toga Positron (Site-specific browser)" -Q "site_url=https://github.com/"'
+
+    steps:
+    - name: Checkout
+      uses: actions/[email protected]
+      with:
+        fetch-depth: 0
+
+    - name: Set up Python
+      uses: actions/[email protected]
+      with:
+        python-version: "3.12"
+
+    - name: Get Packages
+      uses: actions/[email protected]
+      with:
+        pattern: ${{ format('{0}-*', needs.package.outputs.artifact-basename) }}
+        merge-multiple: true
+        path: dist
+
+    - name: Test Bootstrap
+      run: |
+        mkdir bootstrap-test
+        cd bootstrap-test
+        python3 -m venv venv
+        source venv/bin/activate
+        pip install -U pip
+        pip install ../dist/toga_positron-*.whl
+        echo
+        echo "===== Create Briefcase project with ${{ matrix.bootstrap }} bootstrap ====="
+        briefcase new --no-input -Q "formal_name=Hello Bootstrap" ${{ matrix.new-options }}

.github/workflows/publish.yml

@@ -23,6 +23,7 @@ jobs:
         - "toga_demo"
         - "toga_dummy"
         - "toga_gtk"
+        - "toga_positron"
         - "toga_textual"
         - "toga_iOS"
         - "toga_web"

.github/workflows/release.yml

@@ -67,6 +67,7 @@ jobs:
         - "toga_dummy"
         - "toga_gtk"
         - "toga_iOS"
+        - "toga_positron"
         - "toga_textual"
         - "toga_web"
         - "toga_winforms"

changes/3114.feature.rst

@@ -0,0 +1 @@
+A Briefcase bootstrap for generating Positron apps (i.e., apps that are a web view in a native wrapper) was added.

examples/positron-django/README.rst

@@ -18,7 +18,7 @@ To set up a development environment::
 
 To run Django management commands::
 
-    PYTHONPATH=src python src/webapp/manage.py
+    (venv) PYTHONPATH=src python src/manage.py
 
 To run in development mode::
 
@@ -27,3 +27,21 @@ To run in development mode::
 To run as a packaged app::
 
     (venv) $ briefcase run
+
+The Django app will run on a SQLite3 database, stored in the user's data directory (the
+location of this directory is platform specific). This database file will be created if
+it doesn't exist, and migrations will be run on every app start.
+
+If you need to start the database with some initial content (e.g., an initial user
+login) you can use ``manage.py`` to create an initial database file. If there is a
+``db.sqlite3`` in the ``src/positron/resources`` folder when the app starts, and the
+user doesn't already have a ``db.sqlit3`` file in their app data folder, the initial
+database file will be copied into the user's data folder as a starting point.
+
+To create an initial database, use ``manage.py`` - e.g.,:
+
+    (venv) PYTHONPATH=src python src/manage.py migrate
+    (venv) PYTHONPATH=src python src/manage.py createsuperuser
+
+This will create an initial ``db.sqlite3`` file with a superuser account. All users of
+the app will have this superuser account in their database.

examples/positron-django/pyproject.toml

@@ -14,11 +14,11 @@ author_email = "[email protected]"
 formal_name = "Positron"
 description = "Electron, but in Python"
 icon = "src/positron/resources/positron"
-sources = ["src/positron", "src/webapp"]
+sources = ["src/positron"]
 requires = [
     "../../travertino",
     "../../core",
-    "django~=4.1",
+    "django~=5.1",
 ]
 
 

examples/positron-django/src/webapp/manage.py examples/positron-django/src/manage.py

@@ -6,7 +6,7 @@
 
 def main():
     """Run administrative tasks."""
-    os.environ.setdefault("DJANGO_SETTINGS_MODULE", "webapp.settings")
+    os.environ.setdefault("DJANGO_SETTINGS_MODULE", "positron.settings")
     try:
         from django.core.management import execute_from_command_line
     except ImportError as exc:

examples/positron-django/src/positron/app.py

@@ -1,9 +1,12 @@
+import asyncio
 import os
+import shutil
 import socketserver
-from threading import Event, Thread
+from threading import Thread
 from wsgiref.simple_server import WSGIServer
 
 import django
+from django.core import management as django_manage
 from django.core.handlers.wsgi import WSGIHandler
 from django.core.servers.basehttp import WSGIRequestHandler
 
@@ -16,19 +19,36 @@ class ThreadedWSGIServer(socketserver.ThreadingMixIn, WSGIServer):
 
 class Positron(toga.App):
     def web_server(self):
+        print("Configuring settings...")
+        os.environ["DJANGO_SETTINGS_MODULE"] = "positron.settings"
+        django.setup(set_prefix=False)
+
+        self.paths.data.mkdir(exist_ok=True)
+        user_db = self.paths.data / "db.sqlite3"
+        if user_db.exists():
+            print("User already has a database.")
+        else:
+            template_db = self.paths.app / "resources" / "db.sqlite3"
+            if template_db.exists():
+                print("Copying initial database...")
+                shutil.copy(template_db, user_db)
+            else:
+                print("No initial database.")
+
+        print("Applying database migrations...")
+        django_manage.call_command("migrate")
+
         print("Starting server...")
         # Use port 0 to let the server select an available port.
         self._httpd = ThreadedWSGIServer(("127.0.0.1", 0), WSGIRequestHandler)
         self._httpd.daemon_threads = True
 
-        os.environ["DJANGO_SETTINGS_MODULE"] = "webapp.settings"
-        django.setup(set_prefix=False)
         wsgi_handler = WSGIHandler()
         self._httpd.set_app(wsgi_handler)
 
         # The server is now listening, but connections will block until
         # serve_forever is run.
-        self.server_exists.set()
+        self.loop.call_soon_threadsafe(self.server_exists.set_result, "ready")
         self._httpd.serve_forever()
 
     def cleanup(self, app, **kwargs):
@@ -37,7 +57,7 @@ def cleanup(self, app, **kwargs):
         return True
 
     def startup(self):
-        self.server_exists = Event()
+        self.server_exists = asyncio.Future()
 
         self.web_view = toga.WebView()
 
@@ -46,12 +66,15 @@ def startup(self):
 
         self.on_exit = self.cleanup
 
-        self.server_exists.wait()
-        host, port = self._httpd.socket.getsockname()
-        self.web_view.url = f"http://{host}:{port}/"
-
         self.main_window = toga.MainWindow()
         self.main_window.content = self.web_view
+
+    async def on_running(self):
+        await self.server_exists
+
+        host, port = self._httpd.socket.getsockname()
+        self.web_view.url = f"http://{host}:{port}/admin"
+
         self.main_window.show()
 
 

examples/positron-django/src/webapp/settings.py examples/positron-django/src/positron/settings.py

@@ -1,27 +1,25 @@
-"""Django settings for webapp project.
+"""
+Django settings for positron project.
 
-Generated by 'django-admin startproject' using Django 4.1.1.
+Generated by "django-admin startproject" using Django 5.1.5.
 
-For more information on this file, see:
-- https://docs.djangoproject.com/en/4.1/topics/settings/
+For more information on this file, see
+https://docs.djangoproject.com/en/5.1/topics/settings/
 
-For the full list of settings and their values, see:
-- https://docs.djangoproject.com/en/4.1/ref/settings/
+For the full list of settings and their values, see
+https://docs.djangoproject.com/en/5.1/ref/settings/
 """
 
 from pathlib import Path
 
-# Build paths inside the project like this: BASE_DIR / 'subdir'.
-BASE_DIR = Path(__file__).resolve().parent.parent
-
+from toga import App as TogaApp
 
-# Quick-start development settings - unsuitable for production
-# See https://docs.djangoproject.com/en/4.1/howto/deployment/checklist/
+BASE_PATH = Path(__file__).parent / "resources"
 
-# SECURITY WARNING: keep the secret key used in production secret!
-SECRET_KEY = "django-insecure-mcl=_9h9=1h)*%pbt8%*!n724ik0@v25b-=s0*v0bazgrnepyl"
-
-# SECURITY WARNING: don't run with debug turned on in production!
+# A Positron app is only ever serving to itself, so a lot of the usual advice about
+# Django best practices in production don't apply. The secret key doesn't need to be
+# *that* secret; and running in debug mode (with staticfiles) is fine.
+SECRET_KEY = "django-insecure-%vgal2@#0@feqe3jz@1d+f95c*@)2f9n^v9@#%&po5+ct7plwz"
 DEBUG = True
 
 ALLOWED_HOSTS = []
@@ -48,7 +46,7 @@
     "django.middleware.clickjacking.XFrameOptionsMiddleware",
 ]
 
-ROOT_URLCONF = "webapp.urls"
+ROOT_URLCONF = "positron.urls"
 
 TEMPLATES = [
     {
@@ -66,29 +64,25 @@
     },
 ]
 
-WSGI_APPLICATION = "webapp.wsgi.application"
+WSGI_APPLICATION = "positron.wsgi.application"
 
 
 # Database
-# https://docs.djangoproject.com/en/4.1/ref/settings/#databases
+# https://docs.djangoproject.com/en/5.1/ref/settings/#databases
 
 DATABASES = {
     "default": {
         "ENGINE": "django.db.backends.sqlite3",
-        "NAME": BASE_DIR / "db.sqlite3",
+        "NAME": (TogaApp.app.paths.data if TogaApp.app else BASE_PATH) / "db.sqlite3",
     }
 }
 
-
 # Password validation
-# https://docs.djangoproject.com/en/4.1/ref/settings/#auth-password-validators
+# https://docs.djangoproject.com/en/5.1/ref/settings/#auth-password-validators
 
 AUTH_PASSWORD_VALIDATORS = [
     {
-        "NAME": (
-            "django.contrib.auth.password_validation."
-            "UserAttributeSimilarityValidator"
-        ),
+        "NAME": "django.contrib.auth.password_validation.UserAttributeSimilarityValidator",  # noqa: E501
     },
     {
         "NAME": "django.contrib.auth.password_validation.MinimumLengthValidator",
@@ -103,7 +97,7 @@
 
 
 # Internationalization
-# https://docs.djangoproject.com/en/4.1/topics/i18n/
+# https://docs.djangoproject.com/en/5.1/topics/i18n/
 
 LANGUAGE_CODE = "en-us"
 
@@ -115,11 +109,12 @@
 
 
 # Static files (CSS, JavaScript, Images)
-# https://docs.djangoproject.com/en/4.1/howto/static-files/
+# https://docs.djangoproject.com/en/5.1/howto/static-files/
 
 STATIC_URL = "static/"
+STATIC_ROOT = BASE_PATH / "static"
 
 # Default primary key field type
-# https://docs.djangoproject.com/en/4.1/ref/settings/#default-auto-field
+# https://docs.djangoproject.com/en/5.1/ref/settings/#default-auto-field
 
 DEFAULT_AUTO_FIELD = "django.db.models.BigAutoField"

examples/positron-django/src/positron/urls.py

@@ -0,0 +1,8 @@
+from django.contrib import admin
+from django.contrib.staticfiles import views as staticfiles
+from django.urls import path, re_path
+
+urlpatterns = [
+    path("admin/", admin.site.urls),
+    re_path(r"^static/(?P<path>.*)$", staticfiles.serve),
+]

examples/positron-django/src/webapp/wsgi.py examples/positron-django/src/positron/wsgi.py

@@ -1,15 +1,16 @@
-"""WSGI config for mysite project.
+"""
+WSGI config for positron project.
 
 It exposes the WSGI callable as a module-level variable named ``application``.
 
 For more information on this file, see
-https://docs.djangoproject.com/en/4.1/howto/deployment/wsgi/
+https://docs.djangoproject.com/en/5.1/howto/deployment/wsgi/
 """
 
 import os
 
 from django.core.wsgi import get_wsgi_application
 
-os.environ.setdefault("DJANGO_SETTINGS_MODULE", "mysite.settings")
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "positron.settings")
 
 application = get_wsgi_application()