Updates around latest changes and docs

Author: WebReflection

README.md

@@ -32,6 +32,7 @@ of this repository).
 # example of a simple virtual environment
 # creation from the root of this project
 python -m venv .
+./bin/pip install --upgrade setuptools
 ./bin/pip install -r requirements.txt
 ```
 

docs/faq.md

@@ -705,7 +705,7 @@ done"` message is written to the browser's console.
 
 Applications need third party packages and [PyScript can be configured to
 automatically install packages for you](user-guide/configuration/#packages).
-Yet [packaging can be a complicated beast](#python-packages), so here are some
+Yet packaging can be a complicated beast, so here are some
 hints for a painless packaging experience with PyScript.
 
 There are essentially four ways in which a third party package can become
@@ -724,9 +724,10 @@ available in PyScript.
 3. Reference hosted Python source files, to be included on the file
    system, via the [`files` setting](../user-guide/configuration/#files).
 4. Create a folder containing the package's files and sub folders, and create
-   a hosted `.zip` or `.tgz`/`.tar.gz` archive to be decompressed into the file
+   a hosted `.zip` or `.tgz`/`.tar.gz`/`.whl` archive to be decompressed into the file
    system (again, via the
    [`files` setting](../user-guide/configuration/#files)).
+5. provide your own `.whl` package as part of the `packages = [...]` list to see it available within your project
 
 #### Host a package
 
@@ -768,7 +769,7 @@ packages onto the Python path:
 </script>
 ```
 
-#### Code archive (`zip`/`tgz`) 
+#### Code archive (`zip`/`tgz`/`whl`) 
 
 Compress all the code you want into an archive (using either either `zip` or
 `tgz`/`tar.gz`). Host the resulting archive and use the
@@ -1207,6 +1208,8 @@ js.callback(
 )
 ```
 
+Ultimately though, Pyodide maps can be consumed out of the box as literals, so that *some* required conversion might not be needed anymore and `to_js` might be enough, without specifying the `dict_converter` as that's inferred, once consumed, behind the scene.
+
 In addition, MicroPython's version of `to_js` takes the opposite approach (for
 many of the reasons stated above) and converts Python dictionaries to object
 literals instead of `Map` objects.
@@ -1215,6 +1218,8 @@ As a result, **the PyScript `pyscript.ffi.to_js` ALWAYS returns a JavaScript
 object literal by default when converting a Python dictionary** no matter if
 you're using Pyodide or MicroPython as your interpreter.
 
+That being said, in MicroPython things work closely to JS users' expectations, memory friendly too, so using the `to_js` is more a cross-interpreter guard than a necessity these days.
+
 #### Caveat
 
 !!! warning

docs/user-guide/builtins.md

@@ -571,6 +571,27 @@ from pyscript import sync
 sync.hello("PyScript")
 ```
 
+### `pyscript.py_modules`
+
+Bootstrapping *Pyodide* or *MicroPython* with a lot of packages might degrade the time to readyness.
+
+When some dependency is needed only under certain conditions or after some specific user action, we are offering an asynchronuos way to lazily import packages that were not present already in the *config*.
+
+A bare minimal example of how this feature works can be summarized as such:
+
+```html title="pyscript.py_modules example"
+<script type="py" async>
+from pyscript import py_modules
+
+matplotlib, regex, = await py_modules("matplotlib", "regex")
+
+print(matplotlib, regex)
+</script>
+```
+
+The `py_modules` then returns an asynchronous tuple with one or more modules passed as string and it's compatible with `.whl` packages too.
+
+
 ## HTML attributes
 
 As a convenience, and to ensure backwards compatibility, PyScript allows the

docs/user-guide/editor.md

@@ -16,6 +16,11 @@ or `mpy-editor` (for MicroPython), the plugin creates a visual code editor,
 with code highlighting and a "run" button to execute the editable code
 contained therein in a non-blocking worker.
 
+!!! info
+
+    Once clicked, the *Run* button will show a spinner until the code is executed. This might not be visible if the code took nothing to execute, but if the code took any measurable time longer, one will notice such spinner before results will be shown.
+
+
 The interpreter is not loaded onto the page until the run button is clicked. By
 default each editor has its own independent instance of the specified
 interpreter:
@@ -61,6 +66,8 @@ The outcome of these code fragments should look something like this:
 
     Hovering over the Python editor reveals the "run" button.
 
+### Setup
+
 Sometimes you need to create a pre-baked Pythonic context for a shared
 environment used by an editor. This need is especially helpful in educational
 situations where boilerplate code can be run, with just the important salient
@@ -128,6 +135,46 @@ not expect the same behavior regular *PyScript* elements follow, most notably:
   * There is no special reference to the underlying editor instance, while
     there is both `script.terminal` or `__terminal__` in the terminal.
 
+## Read / Write / Execute
+
+Behind the scene, we bootstrap an editor that provides:
+
+  * highlights around the Python code in it
+  * a Run button to execute the code
+  * a `target` reference where the code output lands, once printed
+
+This is all great and sound, but there is also a way to read the *editor* code, and update it with ease, that's the `code` accessor any editor gets, once bootstrapped:
+
+```python
+from pyscript import document
+
+# grab the editor script reference
+editor = document.querySelector('#editor')
+
+# output its content
+print(editor.code)
+
+# or update its content
+editor.code = """
+a = 1
+b = 2
+print(a + b)
+"""
+```
+
+To execute that new editor content a user might click the *Run* button one more time, or the driver of such editor can use `editor.process(editor.code)`, or any other arbitrary code, to actually bypass the need to click *Run* and execute the code passed along the `.process(...)` invoke.
+
+These utilities are helpful to let consumers of the editor change its view state and/or execute it out the box.
+
+## Config
+
+Differently from `<script type="py">` or `<py-script>`, and the `mpy` counterpart, a *PyEditor* is not affected by the presence of `<py-config>` elements in the page: it requires an explicit `config="..."` attribute to specify its dependencies, behavior and whatnot.
+
+If a `setup` editor is present though, that's the only *PyEditor* that needs a config, so that any further related editor will have already such config parsed and bootstrapped.
+
+That is: do not expect `<py-config>` to dictate the behavior of a `py-editor`, these are *two different kind of custom script* so that an editor, when needed, must use a `config` attribute.
+
+
 ## Still missing
 
 The PyEditor is currently under active development and refinement, so features

docs/user-guide/terminal.md

@@ -150,3 +150,23 @@ terminal automatically become links). Behind the scenes is the example code
 shown above, and this approach will work for
 [any other addon](https://github.com/xtermjs/xterm.js/tree/master/addons/) you
 may wish to use.
+
+### MicroPython
+
+When it comes to *MicroPython*, we recently enabled a proper *REPL* mode that offers an easier way to have a fully functional terminal, including:
+
+  * all *Ctrl+X* strokes are handled, including *paste mode* and kill switches
+  * **history** works out of the box, *arrow up* and see what you pasted or typed before
+  * **tab completion** works too, *tab* away to see your previously referenced variables or available globals
+  * **copy and paste** improved, out of a singe terminal entry or a *paste mode* enabled variant
+
+In few words, the *MicroPython* terminal is somehow superior and broadly aligned with a regular *MicroPython terminal / REPL* experience, and strawberry on top, it works on both *main* thread and *worker* related one, and these are the differences:
+
+  * **main thread terminal**
+    * the `input` is, as blocking requirement, delegated to the native Web [prompt](https://developer.mozilla.org/en-US/docs/Web/API/Window/prompt) utility
+    * there is no guard against blocking executing code, such as `while True:` loops and friends
+  * **worker thread terminal**
+    * full support for `input` directives without ever blocking the main thread or showing *prompt* blocking relates UI around
+    * `while True:` loops, or any other loop based, or blocking, directive, is handled out of the box without blocking the main thread UI
+
+In short, we still encourage the usage of `worker` attribute to bootstrap a *MicroPython* terminal, but fear not, the script without such attribute will not throw anymore on *input* calls and it will just work almost as fine out of the main thread as long as nothing is really blocking such thread execution.

docs/user-guide/workers.md

@@ -146,3 +146,82 @@ into the DOM and access some `window` based APIs.
       and produce unforeseen problematic results**. Remember, with great power
       comes great responsibility... and we've given you a bazooka (so please
       remember not to shoot yourself in the foot with it).
+
+## PyWorker
+
+It is possible to bootstrap either a *micropython* or a *pyodide* worker from either *micropython* or *pyodide* and within *Python* code.
+
+Due different bootstrap time, the most common use case that is going to be tackled in here is *MicroPython* bootstrapping *Pyodide* out of *Python* code, underlying each step within the process.
+
+#### Structure
+
+For highlight goodness and simplicity sake, we are going to use an `mpy` script on the main page, which points at a `main.py` file that bootstraps a `worker.py` file.
+
+**html**
+```HTML title="Pyodide worker via MicroPython"
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+    <!-- PyScript CSS -->
+    <link rel="stylesheet" href="https://pyscript.net/releases/2024.5.2/core.css">
+    <!-- This script tag bootstraps PyScript -->
+    <script type="module" src="https://pyscript.net/releases/2024.5.2/core.js"></script>
+    <title>PyWorker - mpy bootstrapping pyodide example</title>
+    <!-- the async attribute is useful but not mandatory -->
+    <script type="mpy" src="main.py" async></script>
+  </head>
+</html>
+```
+
+**main.py**
+```Python title="MicroPython bootstrapping a Pyodide worker"
+from pyscript import PyWorker, document
+
+# bootstrap the pyodide worker with optional config too
+# the worker here is:
+#   * owned by this script, no JS or Pyodide code in the same page can access it
+#   * it allows pre-sync methods exposure
+#   * it exposes a ready Promise to await pyodide on the worker side
+#   * it then allows using post-sync (utilities exposed by pyodide)
+worker = PyWorker("worker.py", type="pyodide")
+
+# expose an utility that can be invoke *out of the box* in worker.py
+worker.sync.greetings = lambda: print("Pyodide bootstrapped")
+
+print("before ready")
+# await for Pyodide to complete its bootstrap
+await worker.ready
+print("after ready")
+
+# await any exposed utility exposed via Pyodide
+result = await worker.sync.heavy_computation()
+print(result)
+
+# show the result at the end of the body
+document.body.append(result)
+
+# here we free memory and get rid of everything
+worker.terminate()
+```
+
+**worker.py**
+```Python title="A Pyodide worker"
+from pyscript import sync
+
+# use any already exposed utility from main.py
+sync.greetings()
+
+# expose any method meant to be used from main
+sync.heavy_computation = lambda: 6 * 7
+```
+
+Save these files in a *tmp* folder and use `npx mini-coi ./tmp` to reach out that `index.html` and see the following outcome in *devtools*:
+
+```
+before ready
+Pyodide bootstrapped
+after ready
+42
+```