Finish FAQ, add web sockets, web worker examples and bumped version to 2024.5.1

ntoll · ntoll · commit a0fd3a5756cb · 2024-05-07T10:22:30.000+01:00
diff --git a/docs/beginning-pyscript.md b/docs/beginning-pyscript.md
@@ -112,8 +112,8 @@ module in the document's `<head>` tag:
       <meta charset="utf-8" />
       <meta name="viewport" content="width=device-width,initial-scale=1" />
       <title>🦜 Polyglot - Piratical PyScript</title>
-      <link rel="stylesheet" href="https://pyscript.net/releases/2024.4.2/core.css">
-      <script type="module" src="https://pyscript.net/releases/2024.4.2/core.js"></script>
+      <link rel="stylesheet" href="https://pyscript.net/releases/2024.5.1/core.css">
+      <script type="module" src="https://pyscript.net/releases/2024.5.1/core.js"></script>
   </head>
   <body>
 
@@ -163,8 +163,8 @@ In the end, our HTML should look like this:
       <meta charset="utf-8" />
       <meta name="viewport" content="width=device-width,initial-scale=1" />
       <title>🦜 Polyglot - Piratical PyScript</title>
-      <link rel="stylesheet" href="https://pyscript.net/releases/2024.4.2/core.css">
-      <script type="module" src="https://pyscript.net/releases/2024.4.2/core.js"></script>
+      <link rel="stylesheet" href="https://pyscript.net/releases/2024.5.1/core.css">
+      <script type="module" src="https://pyscript.net/releases/2024.5.1/core.js"></script>
   </head>
   <body>
     <h1>Polyglot 🦜 💬 🇬🇧 ➡️ 🏴‍☠️</h1>
diff --git a/docs/faq.md b/docs/faq.md
diff --git a/docs/user-guide/builtins.md b/docs/user-guide/builtins.md
@@ -41,7 +41,7 @@ On a worker thread, this object is a proxy for the web page's
 
 ### `pyscript.document`
 
-On both main and worker threads, this object is a proxy for the the web page's
+On both main and worker threads, this object is a proxy for the web page's
 [document object](https://developer.mozilla.org/en-US/docs/Web/API/Document).
 The `document` is a representation of the
 [DOM](https://developer.mozilla.org/en-US/docs/Web/API/Document_object_model/Using_the_Document_Object_Model)
@@ -257,6 +257,121 @@ result = await fetch("https://example.com", method="POST", body="HELLO").text()
     bug). However, you could use a pass-through proxy service to get around
     this limitation (i.e. the proxy service makes the call on your behalf).
 
+### `pyscript.WebSocket`
+
+If a `pyscript.fetch` results in a call and response HTTP interaction with a
+web server, the `pyscript.Websocket` class provides a way to use
+[websockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API)
+for two-way sending and receiving of data via a long term connection with a
+web server.
+
+PyScript's implementation, available in both the main thread and a web worker,
+closely follows the browser's own 
+[WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) class.
+
+This class accepts the following named arguments:
+
+* A `url` pointing at the _ws_ or _wss_ address. E.g.:
+  `WebSocket(url="ws://localhost:5037/")`
+* Some `protocols`, an optional string or a list of strings as
+  [described here](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/WebSocket#parameters).
+
+The `WebSocket` class also provides these convenient static constants:
+
+* `WebSocket.CONNECTING` (`0`) - the `ws.readyState` value when a web socket
+  has just been created.
+* `WebSocket.OPEN` (`1`) - the `ws.readyState` value once the socket is open.
+* `WebSocket.CLOSING` (`2`) - the `ws.readyState` after `ws.close()` is
+  explicitly invoked to stop the connection.
+* `WebSocket.CLOSED` (`3`) - the `ws.readyState` once closed.
+
+A `WebSocket` instance has only 2 methods:
+
+* `ws.send(data)` - where `data` is either a string or a Python buffer,
+  automatically converted into a JavaScript typed array. This sends data via
+  the socket to the connected web server.
+* `ws.close(code=0, reason="because")` - which optionally accepts `code` and
+  `reason` as named arguments to signal some specific status or cause for
+  closing the web socket. Otherwise `ws.close()` works with the default
+  standard values.
+
+A `WebSocket` instance also has the fields that the JavaScript
+`WebSocket` instance will have:
+
+* [binaryType](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/binaryType) -
+  the type of binary data being received over the WebSocket connection.
+* [bufferedAmount](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/bufferedAmount) -
+  a read-only property that returns the number of bytes of data that have been
+  queued using calls to `send()` but not yet transmitted to the network.
+* [extensions](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/extensions) -
+  a read-only property that returns the extensions selected by the server.
+* [protocol](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/protocol) -
+  a read-only property that returns the name of the sub-protocol the server
+  selected.
+* [readyState](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/readyState) -
+  a read-only property that returns the current state of the WebSocket
+  connection as one of the `WebSocket` static constants (`CONNECTING`, `OPEN`,
+  etc...).
+* [url](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/url) -
+  a read-only property that returns the absolute URL of the `WebSocket`
+  instance.
+
+A `WebSocket` instance can have the following listeners. Directly attach
+handler functions to them. Such functions will always receive a single
+`event` object.
+
+* [onclose](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/close_event) -
+  fired when the `WebSocket`'s connection is closed.
+* [onerror](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/error_event) -
+  fired when the connection is closed due to an error.
+* [onmessage](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/message_event) -
+  fired when data is received via the `WebSocket`. If the `event.data` is a
+  JavaScript typed array instead of a string, the reference it will point
+  directly to a _memoryview_ of the underlying `bytearray` data.
+* [onopen](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/open_event) -
+  fired when the connection is opened.
+
+The following code demonstrates a `pyscript.WebSocket` in action.
+
+```html
+<script type="mpy" worker>
+    from pyscript import WebSocket
+
+    def onopen(event):
+        print(event.type)
+        ws.send("hello")
+
+    def onmessage(event):
+        print(event.type, event.data)
+        ws.close()
+
+    def onclose(event):
+        print(event.type)
+
+    ws = WebSocket(url="ws://localhost:5037/")
+    ws.onopen = onopen
+    ws.onmessage = onmessage
+    ws.onclose = onclose
+</script>
+```
+
+!!! info
+
+    It's also possible to pass in any handler functions as named arguments when
+    you instantiate the `pyscript.WebSocket` class:
+
+    ```python
+    from pyscript import WebSocket
+
+
+    def onmessage(event):
+        print(event.type, event.data)
+        ws.close()
+
+
+    ws = WebSocket(url="ws://example.com/socket", onmessage=onmessage)
+    ```
+
 ### `pyscript.ffi.to_js`
 
 A utility function to convert Python references into their JavaScript
@@ -343,6 +458,25 @@ an `id`, that `id` will be returned.
     Then use the standard `document.getElementById(script_id)` function to
     return a reference to it in your code.
 
+### `pyscript.config`
+
+A Python dictionary representing the configuration for the interpreter.
+
+```python title="Reading the current configuration."
+from pyscript import config
+
+
+# It's just a dict.
+print(config.get("files"))
+```
+
+!!! warning
+
+    Changing the `config` dictionary at runtime has no effect on the actual
+    configuration.
+
+    It's just a convenience to **read the configuration** at run time.
+
 ### `pyscript.HTML`
 
 A class to wrap generic content and display it as un-escaped HTML on the page.
@@ -379,8 +513,9 @@ A class used to instantiate a new worker from within Python.
     Sometimes we disambiguate between interpreters through naming conventions
     (e.g. `py` or `mpy`).
 
-    However, it is always `PyWorker` and the desired interpreter is specified
-    via a `type` option which must be either `micropython` or `pyodide`.
+    However, this class is always `PyWorker` and **the desired interpreter 
+    MUST be specified via a `type` option**. Valid values for the type of
+    interpreter are either `micropython` or `pyodide`.
 
 The following fragments demonstrate how to evaluate the file `worker.py` on a
 new worker from within Python.
@@ -400,7 +535,7 @@ print("awake")
 ```python title="main.py - starts a new worker in Python."
 from pyscript import PyWorker
 
-# type can be either `micropython` or `pyodide`
+# type MUST be either `micropython` or `pyodide`
 PyWorker("worker.py", type="micropython")
 ```
 
diff --git a/docs/user-guide/configuration.md b/docs/user-guide/configuration.md
@@ -440,6 +440,18 @@ So long as you don't cause a name collision with the built-in option names then
 you are free to use any valid data structure that works with both TOML and JSON
 to express your configuration needs.
 
-**TODO: explain how to programmatically get access to an object representing
-the config.**
+Access the current configuration via `pyscript.config`, a Python `dict`
+representing the configuration:
 
+```python title="Reading the current configuration."
+from pyscript import config
+
+
+# It's just a dict.
+print(config.get("files"))
+```
+
+!!! note
+
+    Changing the `config` dictionary at runtime doesn't change the actual
+    configuration.
diff --git a/docs/user-guide/first-steps.md b/docs/user-guide/first-steps.md
@@ -20,9 +20,9 @@ CSS:
         <meta charset="UTF-8">
         <meta name="viewport" content="width=device-width,initial-scale=1.0">
         <!-- PyScript CSS -->
-        <link rel="stylesheet" href="https://pyscript.net/releases/2024.4.2/core.css">
+        <link rel="stylesheet" href="https://pyscript.net/releases/2024.5.1/core.css">
         <!-- This script tag bootstraps PyScript -->
-        <script type="module" src="https://pyscript.net/releases/2024.4.2/core.js"></script>
+        <script type="module" src="https://pyscript.net/releases/2024.5.1/core.js"></script>
     </head>
     <body>
         <!-- your code goes here... -->
diff --git a/docs/user-guide/plugins.md b/docs/user-guide/plugins.md
@@ -1,10 +1,10 @@
 # Plugins
 
-PyScript offers a plugin API to extend its functionality. It means you can add
-new features and distribute them as plugins.
+PyScript offers a plugin API _so anyone can extend its functionality and
+share their modifications_.
 
 PyScript only supports plugins written in Javascript (although causing the
-evaluation of bespoke Python code can be a part of this process). The plugin's
+evaluation of bespoke Python code can be a part of such plugins). The plugin's
 JavaScript code should be included on the web page via a
 `<script type="module">` tag **before PyScript is included in the web page**.
 
@@ -19,7 +19,7 @@ PyScript emits events that capture the beginning or the end of specific stages
 in the application's life. No matter if code is running in the main thread or
 on a web worker, the exact same sequence of steps takes place:
 
-  * **ready** - the browser recognized the PyScript `script` or tag and the
+  * **ready** - the browser recognizes the PyScript `script` or tag, and the
     associated Python interpreter is ready to work. A JavaScript callback can
     be used to instrument the interpreter before anything else happens.
   * **before run** - some Python code is about to be evaluated. A JavaScript
@@ -53,14 +53,22 @@ lifecycle events. When such events happen, your code will be called by
 PyScript.
 
 The available hooks depend upon where your code is running: on the browser's
-(blocking) main thread or on a (non-blocking) web worker.
+(blocking) main thread or on a (non-blocking) web worker. These are defined via
+the `hooks.main` and `hooks.worker` namespaces in JavaScript.
 
 
 #### Main Hooks
 
-Callbacks registered via hooks on the main thread will receive a wrapper of
-the interpreter with its utilities, along with a reference to the element on
-the page from where the code was derived.
+Callbacks registered via hooks on the main thread will usually receive a
+wrapper of the interpreter with its unique-to-that-interpreter utilities, along
+with a reference to the element on the page from where the code was derived.
+
+Please refer to the documentation for the interpreter you're using (Pyodide or
+MicroPython) to learn about its implementation details and the potential
+capabilities made available via the wrapper.
+
+Callbacks whose purpose is simply to run raw contextual Python code, don't
+receive interpreter or element arguments. 
 
 This table lists all possible, **yet optional**, hooks a plugin can register on
 the main thread:
@@ -91,7 +99,7 @@ For example, this will work because all references are contained within the
 registered function:
 
 ```js
-import { hooks } from "https://pyscript.net/releases/2024.4.2/core.js";
+import { hooks } from "https://pyscript.net/releases/2024.5.1/core.js";
 
 hooks.worker.onReady.add(() => {
     // NOT suggested, just an example!
@@ -105,7 +113,7 @@ hooks.worker.onReady.add(() => {
 However, due to the outer reference to the variable `i`, this will fail:
 
 ```js
-import { hooks } from "https://pyscript.net/releases/2024.4.2/core.js";
+import { hooks } from "https://pyscript.net/releases/2024.5.1/core.js";
 
 // NO NO NO NO NO! ☠️
 let i = 0;
@@ -138,7 +146,7 @@ the page.
 
 ```js title="log.js - a plugin that simply logs to the console."
 // import the hooks from PyScript first...
-import { hooks } from "https://pyscript.net/releases/2024.4.2/core.js";
+import { hooks } from "https://pyscript.net/releases/2024.5.1/core.js";
 
 // The `hooks.main` attribute defines plugins that run on the main thread.
 hooks.main.onReady.add((wrap, element) => {
@@ -188,8 +196,8 @@ hooks.worker.onAfterRun.add(() => {
         <!-- JS plugins should be available before PyScript bootstraps -->
         <script type="module" src="./log.js"></script>
         <!-- PyScript -->
-        <link rel="stylesheet" href="https://pyscript.net/releases/2024.4.2/core.css">
-        <script type="module" src="https://pyscript.net/releases/2024.4.2/core.js"></script>
+        <link rel="stylesheet" href="https://pyscript.net/releases/2024.5.1/core.css">
+        <script type="module" src="https://pyscript.net/releases/2024.5.1/core.js"></script>
     </head>
     <body>
         <script type="mpy">
diff --git a/docs/user-guide/workers.md b/docs/user-guide/workers.md
@@ -54,8 +54,22 @@ attribute flag:
 <script type="py" src="./my-worker-code.py" worker></script>
 ```
 
-Code running in the worker needs to be able to access the web page running in
-the main thread. This is achieved via [builtin helper utilities](../builtins).
+Alternatively, to launch a worker from within Python running on the main thread
+use the [pyscript.PyWorker](../builtins/#pyscriptpyworker) class and must
+reference both the target Python script and interpreter type:
+
+```python title="Launch a worker from within Python"
+from pyscript import PyWorker
+
+# The type MUST be given and can be either `micropython` or `pyodide`
+PyWorker("my-worker-code.py", type="micropython")
+```
+
+## Worker interactions
+
+Code running in the worker needs to be able to interact with code running in
+the main thread and perhaps have access to the web page. This is achieved via
+some helpful [builtin utilities](../builtins).
 
 !!! note
 
@@ -67,3 +81,53 @@ the main thread. This is achieved via [builtin helper utilities](../builtins).
     [consult the XWorker](https://pyscript.github.io/polyscript/#xworker)
     related documentation from the PolyScript project for how to make use of
     these features.
+
+To synchronise serializable data between the worker and the main thread use
+[the `sync` function](../builtins/#pyscriptsync) in the worker to reference a
+function registered on the main thread:
+
+```python title="Python code running on the main thread."
+from pyscript import PyWorker
+
+def hello(name="world"):
+    return(f"Hello, {name}")
+
+# Create the worker.
+worker = PyWorker("./worker.py", type="micropython")
+
+# Register the hello function as callable from the worker.
+worker.sync.hello = hello
+```
+
+```python title="Python code in the resulting worker."
+from pyscript import sync, window
+
+greeting = sync.hello("PyScript")
+window.console.log(greeting)
+```
+
+The values passed between the main thread and the worker **must be
+serializable**. Try the example given above via
+[this project on PyScript.com](https://pyscript.com/@ntoll/tiny-silence/latest).
+
+No matter if your code is running on the main thread or in a web worker,
+both the [`pyscript.window`](../builtins/#pyscriptwindow) (representing the main
+thread's global window context) and
+[`pyscript.document`](../builtins/#pyscriptdocument) (representing the web
+page's
+[document object](https://developer.mozilla.org/en-US/docs/Web/API/Document))
+will be available and work in the same way. As a result, a worker can reach
+into the DOM and access some `window` based APIs.
+
+!!! warning
+
+    Access to the `window` and `document` objects is a powerful feature. Please
+    remember that:
+
+    * Arguments to and the results from such calls, when used in a worker,
+      **must be serializable**, otherwise they won't work.
+    * If you manipulate the DOM via the `document` object, and other workers or
+      code on the main thread does so too, **they may interfere with each other
+      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).
diff --git a/mkdocs.yml b/mkdocs.yml
diff --git a/version.json b/version.json
