Merge pull request #139 from pyscript/2024-09-01

Update to docs for the 2024.9.1 release.
pyscript · Sep 13, 2024 · 7d5fa2b · 7d5fa2b
2 parents 82e2c2d + 9a75798
commit 7d5fa2b
Show file tree

Hide file tree

Showing 8 changed files with 96 additions and 65 deletions.
diff --git a/docs/api.md b/docs/api.md
@@ -409,6 +409,12 @@ store = await storage("my-data-store", storage_class=MyStorage)
 # The store object is now an instance of MyStorage.
 ```
 
+### `@pyscript/core/dist/storage.js`
+
+The equivalent functionality based on the *JS* module can be found through our module.
+
+The goal is to be able to share the same database across different worlds (interpreters) and the functionality is nearly identical except there is no *class* to provide because the storage in *JS* is just a dictionary proxy that synchronizes behind the scene all read, write or delete operations.
+
 ### `pyscript.web`
 
 The classes and references in this namespace provide a Pythonic way to interact
@@ -766,6 +772,52 @@ The following code demonstrates a `pyscript.WebSocket` in action.
     ws = WebSocket(url="ws://example.com/socket", onmessage=onmessage)
     ```
 
+### `pyscript.js_import`
+
+If a JavaScript module is only needed under certain circumstances, we provide
+an asynchronous way to import packages that were not originally referenced in
+your configuration.
+
+```html title="A pyscript.js_import example."
+<script type="py">
+from pyscript import js_import, window
+
+escaper, = await js_import("https://esm.run/html-escaper")
+
+window.console.log(escaper)
+```
+
+The `js_import` call returns an asynchronous tuple containing the JavaScript
+modules referenced as string arguments.
+
+### `pyscript.py_import`
+
+!!! warning
+
+    **This is an experimental feature.**
+
+    Feedback and bug reports are welcome!
+
+If you have a lot of Python packages referenced in your configuration, startup
+performance may be degraded as these are downloaded.
+
+If a Python package is only needed under certain circumstances, we provide an
+asynchronous way to import packages that were not originally referenced in your
+configuration.
+
+```html title="A pyscript.py_import example."
+<script type="py">
+from pyscript import py_import
+
+matplotlib, regex, = await py_import("matplotlib", "regex")
+
+print(matplotlib, regex)
+</script>
+```
+
+The `py_import` call returns an asynchronous tuple containing the Python
+modules provided by the packages referenced as string arguments.
+
 ## Main-thread only features
 
 ### `pyscript.PyWorker`
@@ -863,52 +915,6 @@ for el in document.querySelectorAll("[type='py'][worker][name]"):
 
 ## Worker only features
 
-### `pyscript.js_import`
-
-If a JavaScript module is only needed under certain circumstances, we provide
-an asynchronous way to import packages that were not originally referenced in
-your configuration.
-
-```html title="A pyscript.js_import example."
-<script type="py">
-from pyscript import js_import, window
-
-escaper, = await js_import("https://esm.run/html-escaper")
-
-window.console.log(escaper)
-```
-
-The `js_import` call returns an asynchronous tuple containing the JavaScript
-modules referenced as string arguments.
-
-### `pyscript.py_import`
-
-!!! warning
-
-    **This is an experimental feature.**
-
-    Feedback and bug reports are welcome!
-
-If you have a lot of Python packages referenced in your configuration, startup
-performance may be degraded as these are downloaded.
-
-If a Python package is only needed under certain circumstances, we provide an
-asynchronous way to import packages that were not originally referenced in your
-configuration.
-
-```html title="A pyscript.py_import example."
-<script type="py">
-from pyscript import py_import
-
-matplotlib, regex, = await py_import("matplotlib", "regex")
-
-print(matplotlib, regex)
-</script>
-```
-
-The `py_import` call returns an asynchronous tuple containing the Python
-modules provided by the packages referenced as string arguments.
-
 ### `pyscript.sync`
 
 A function used to pass serializable data from workers to the main thread. 

diff --git a/docs/beginning-pyscript.md b/docs/beginning-pyscript.md
@@ -117,8 +117,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.8.2/core.css">
-      <script type="module" src="https://pyscript.net/releases/2024.8.2/core.js"></script>
+      <link rel="stylesheet" href="https://pyscript.net/releases/2024.9.1/core.css">
+      <script type="module" src="https://pyscript.net/releases/2024.9.1/core.js"></script>
   </head>
   <body>
 
@@ -168,8 +168,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.8.2/core.css">
-      <script type="module" src="https://pyscript.net/releases/2024.8.2/core.js"></script>
+      <link rel="stylesheet" href="https://pyscript.net/releases/2024.9.1/core.css">
+      <script type="module" src="https://pyscript.net/releases/2024.9.1/core.js"></script>
   </head>
   <body>
     <h1>Polyglot 🦜 💬 🇬🇧 ➡️ 🏴‍☠️</h1>

diff --git a/docs/faq.md b/docs/faq.md
@@ -682,6 +682,31 @@ done"` message is written to the browser's console.
 </script>
 ```
 
+#### m/py:progress
+
+The `py:progress` or `mpy:progress` event triggers on the main thread *during*
+interpreter bootstrap (no matter if your code is running on main or in a
+worker).
+
+The received `event.detail` is a string that indicates operations between
+`Loading {what}` and `Loaded {what}`. So, the first event would be, for
+example, `Loading Pyodide` and the last one per each bootstrap would be
+`Loaded Pyodide`.
+
+In between all operations are `event.detail`s, such as:
+
+  * `Loading files` and `Loaded files`, when `[files]` is found in the optional
+    config
+  * `Loading fetch` and `Loaded fetch`, when `[fetch]` is found in the optional
+     config
+  * `Loading JS modules` and `Loaded JS modules`, when `[js_modules.main]` or
+    `[js_modules.worker]` is found in the optional config
+  * finally, all optional packages handled via *micropip* or *mip* will also
+    trigger various `Loading ...` and `Loaded ...` events so that users can see
+    what is going on while PyScript is bootstrapping
+
+An example of this listener applied to a dialog can be [found in here](https://agiammarchi.pyscriptapps.com/kmeans-in-panel-copy/v1/).
+
 ### Packaging pointers
 
 Applications need third party packages and [PyScript can be configured to

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.8.2/core.css">
+        <link rel="stylesheet" href="https://pyscript.net/releases/2024.9.1/core.css">
         <!-- This script tag bootstraps PyScript -->
-        <script type="module" src="https://pyscript.net/releases/2024.8.2/core.js"></script>
+        <script type="module" src="https://pyscript.net/releases/2024.9.1/core.js"></script>
     </head>
     <body>
         <!-- your code goes here... -->

diff --git a/docs/user-guide/offline.md b/docs/user-guide/offline.md
@@ -40,7 +40,7 @@ cd pyscript-offline
 Build PyScript core by cloning the project repository and follow the
 instructions in our [developer guide](../developers.md)
 
-Once completed, copy the `build` folder, that was been created by the build
+Once completed, copy the `dist` folder, that has been created by the build
 step, into your `pyscript-offline` folder.
 
 ### PyScript core from `npm`
@@ -114,7 +114,7 @@ python3 -m http.server -d ./public/
 If you would like to test `worker` features, try instead:
 
 ```sh
-npx static-handler --coi ./public/
+npx mini-coi ./public/
 ```
 
 ## Download a local interpreter
@@ -231,7 +231,7 @@ Finally, we need the ability to install Python packages from a local source
 when using Pyodide.
 
 Put simply, we use the packages bundle from
-[pyodide releases](https://github.com/pyodide/pyodide/releases/tag/0.24.1).
+[pyodide releases](https://github.com/pyodide/pyodide/releases/tag/0.26.2).
 
 !!! warning
 
@@ -240,8 +240,8 @@ Put simply, we use the packages bundle from
     It contains each package that is required by Pyodide, and Pyodide will only
     load packages when needed.
 
-Once downloaded and extracted (we're using version `0.24.1` in this example),
-we can simply copy the files and folders inside the `pyodide-0.24.1/pyodide/*`
+Once downloaded and extracted (we're using version `0.26.2` in this example),
+we can simply copy the files and folders inside the `pyodide-0.26.2/pyodide/*`
 directory into our `./public/pyodide/*` folder.
 
 Feel free to either skip or replace the content, or even directly move the

diff --git a/docs/user-guide/plugins.md b/docs/user-guide/plugins.md
@@ -100,7 +100,7 @@ For example, this will work because all references are contained within the
 registered function:
 
 ```js
-import { hooks } from "https://pyscript.net/releases/2024.8.2/core.js";
+import { hooks } from "https://pyscript.net/releases/2024.9.1/core.js";
 
 hooks.worker.onReady.add(() => {
     // NOT suggested, just an example!
@@ -114,7 +114,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.8.2/core.js";
+import { hooks } from "https://pyscript.net/releases/2024.9.1/core.js";
 
 // NO NO NO NO NO! ☠️
 let i = 0;
@@ -147,7 +147,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.8.2/core.js";
+import { hooks } from "https://pyscript.net/releases/2024.9.1/core.js";
 
 // The `hooks.main` attribute defines plugins that run on the main thread.
 hooks.main.onReady.add((wrap, element) => {
@@ -197,8 +197,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.8.2/core.css">
-        <script type="module" src="https://pyscript.net/releases/2024.8.2/core.js"></script>
+        <link rel="stylesheet" href="https://pyscript.net/releases/2024.9.1/core.css">
+        <script type="module" src="https://pyscript.net/releases/2024.9.1/core.js"></script>
     </head>
     <body>
         <script type="mpy">

diff --git a/docs/user-guide/workers.md b/docs/user-guide/workers.md
@@ -282,9 +282,9 @@ Here's how:
     <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.8.2/core.css">
+    <link rel="stylesheet" href="https://pyscript.net/releases/2024.9.1/core.css">
     <!-- This script tag bootstraps PyScript -->
-    <script type="module" src="https://pyscript.net/releases/2024.8.2/core.js"></script>
+    <script type="module" src="https://pyscript.net/releases/2024.9.1/core.js"></script>
     <title>PyWorker - mpy bootstrapping pyodide example</title>
     <script type="mpy" src="main.py"></script>
   </head>

diff --git a/version.json b/version.json
@@ -1,3 +1,3 @@
 {
-    "version": "2024.8.2"
+    "version": "2024.9.1"
 }