Refactor the pyscript python package. (#1713)

pyscript.core/README.md

@@ -27,9 +27,9 @@ Accordingly, whenever a file contains this warning at its first line, please do
 // ⚠️ This file is an artifact: DO NOT MODIFY
 ```
 
-## Python stdlib
+## `pyscript` python package
 
-The `pyscript` module available in _Python_ defines its exported utilities via `src/stdlib/pyscript.py`. Any file that would like to provide an export should be placed into `src/stdlib/_pyscript` folder (see the `display.py` as example) and its public functionalities should be explicit in the `src/stdlib/pyscript.py` file.
+The `pyscript` package available in _Python_ lives in the folder `src/stdlib/pyscript/`.
 
 All _Python_ files will be embedded automatically whenever `npm run build` happens and reflected into the `src/stdlib/pyscript.js` file.
 

pyscript.core/docs/README.md

@@ -111,7 +111,7 @@ import { hooks } from "https://cdn.jsdelivr.net/npm/@pyscript/core";
 
 // example
 hooks.onInterpreterReady.add((utils, element) => {
-  console.lot(element, 'found', 'pyscript is ready');
+  console.log(element, 'found', 'pyscript is ready');
 });
 
 // the hooks namespace
@@ -148,9 +148,9 @@ Please note that a *worker* is a completely different environment and it's not p
 
 However, each worker string can use `from pyscript import x, y, z` as that will be available out of the box.
 
-## PyScript Module API
+## PyScript Python API
 
-The python module offers various utilities in either the main thread or the worker.
+The `pyscript` python package offers various utilities in either the main thread or the worker.
 
 The commonly shared utilities are:
 
@@ -257,15 +257,6 @@ We might decide to allow TOML too in the future, but the direct config as attrib
   </div>
 </details>
 
-<details>
-  <summary><strong>why worker attribute needs an external file?</strong></summary>
-  <div markdown=1>
-
-It would create confusion to have worker code embedded directly in the page and let *PyScript* forward the content to be executed as worker, but the separation of concerns felt more aligned with the meaning of bootstrapping a worker: it inevitably happens elsewhere and with little caveats or features here and there, so it's OK for now to keep that separation explicit.
-
-  </div>
-</details>
-
 <details>
   <summary><strong>what are the worker's caveats?</strong></summary>
   <div markdown=1>

pyscript.core/src/core.js

@@ -82,7 +82,7 @@ const registerModule = ({ XWorker: $XWorker, interpreter, io }) => {
     }
 
     // enrich the Python env with some JS utility for main
-    interpreter.registerJsModule("_pyscript_js", {
+    interpreter.registerJsModule("_pyscript", {
         PyWorker,
         get target() {
             return isScript(currentElement)

pyscript.core/src/stdlib/_pyscript/__init__.py

@@ -1,12 +0,0 @@
-import js as window
-
-IS_WORKER = not hasattr(window, "document")
-
-if IS_WORKER:
-    from polyscript import xworker as _xworker
-
-    window = _xworker.window
-    document = window.document
-    sync = _xworker.sync
-else:
-    document = window.document

pyscript.core/src/stdlib/pyscript.py

@@ -1,34 +0,0 @@
-# export only what we want to expose as `pyscript` module
-# but not what is WORKER/MAIN dependent
-from _pyscript import window, document, IS_WORKER
-from _pyscript.display import HTML, display as _display
-from _pyscript.event_handling import when
-
-# this part is needed to disambiguate between MAIN and WORKER
-if IS_WORKER:
-    # in workers the display does not have a default ID
-    # but there is a sync utility from xworker
-    import polyscript as _polyscript
-    from _pyscript import sync
-
-    def current_target():
-        return _polyscript.target
-
-else:
-    # in MAIN both PyWorker and current element target exist
-    # so these are both exposed and the display will use,
-    # if not specified otherwise, such current element target
-    import _pyscript_js
-
-    PyWorker = _pyscript_js.PyWorker
-
-    def current_target():
-        return _pyscript_js.target
-
-
-# the display provides a handy default target either in MAIN or WORKER
-def display(*values, target=None, append=True):
-    if target is None:
-        target = current_target()
-
-    return _display(*values, target=target, append=append)

pyscript.core/src/stdlib/pyscript/display.py

@@ -3,7 +3,7 @@ import html
 import io
 import re
 
-from . import document, window
+from pyscript.magic_js import document, window, current_target
 
 _MIME_METHODS = {
     "__repr__": "text/plain",
@@ -146,6 +146,9 @@ def _write(element, value, append=False):
 
 
 def display(*values, target=None, append=True):
+    if target is None:
+        target = current_target()
+
     element = document.getElementById(target)
     for v in values:
         _write(element, v, append=append)

pyscript.core/src/stdlib/pyscript/event_handling.py

@@ -1,7 +1,7 @@
 import inspect
 
 from pyodide.ffi.wrappers import add_event_listener
-from pyscript import document
+from pyscript.magic_js import document
 
 
 def when(event_type=None, selector=None):

pyscript.core/src/stdlib/pyscript/magic_js.py

@@ -0,0 +1,33 @@
+import js as globalThis
+
+RUNNING_IN_WORKER = not hasattr(globalThis, "document")
+
+if RUNNING_IN_WORKER:
+    import polyscript
+
+    # XXX we should use a "smarter" object which emits a clearer error message
+    # if you try to access it
+    PyWorker = None
+
+    window = polyscript.xworker.window
+    document = window.document
+    sync = polyscript.xworker.sync
+
+    # in workers the display does not have a default ID
+    # but there is a sync utility from xworker
+    def current_target():
+        return polyscript.target
+
+else:
+    import _pyscript
+    from _pyscript import PyWorker
+
+    window = globalThis
+    document = globalThis.document
+    # XXX we should use a "smarter" object which emits a clearer error message
+    # if you try to access it
+    sync = None
+
+    # in MAIN the current element target exist, just use it
+    def current_target():
+        return _pyscript.target

pyscript.core/types/stdlib/pyscript.d.ts

@@ -1,12 +1,12 @@
-declare const _default: {
-    _pyscript: {
+declare namespace _default {
+    let pyscript: {
         "__init__.py": string;
         "display.py": string;
         "event_handling.py": string;
+        "magic_js.py": string;
     };
-    "pyscript.py": string;
-    pyweb: {
+    let pyweb: {
         "pydom.py": string;
     };
-};
+}
 export default _default;