Merge pull request #136 from pyscript/2024-8-2

Documentation for release 2024.8.2
pyscript · Aug 5, 2024 · 82e2c2d · 82e2c2d
2 parents ea0c9a0 + 8653cd1
commit 82e2c2d
Show file tree

Hide file tree

Showing 7 changed files with 47 additions and 30 deletions.
diff --git a/docs/api.md b/docs/api.md
@@ -197,10 +197,8 @@ Pyodide and MicroPython. It is closely modelled on the
 [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) found
 in browsers with some important Pythonic differences.
 
-The simple use case is to pass in a URL and `await` the response. Remember, in
-order to use `await` you must have the `async` attribute in the `script` tag
-that references your code. If this request is in a function, that function
-should also be defined as `async`.
+The simple use case is to pass in a URL and `await` the response. If this
+request is in a function, that function should also be defined as `async`.
 
 ```python title="A simple HTTP GET with pyscript.fetch"
 from pyscript import fetch
@@ -834,7 +832,7 @@ While over on the main thread, this fragment of MicroPython will be able to
 access the worker's `version` function via the `workers` reference:
 
 ```html
-<script type="mpy" async>
+<script type="mpy">
 from pyscript import workers
 
 pyworker = await workers["py-version"]
@@ -853,7 +851,7 @@ Should you wish to await for all workers on the page at load time, it's
 possible to loop over matching elements in the document like this:
 
 ```html
-<script type="mpy" async>
+<script type="mpy">
 from pyscript import document, workers
 
 for el in document.querySelectorAll("[type='py'][worker][name]"):
@@ -872,7 +870,7 @@ an asynchronous way to import packages that were not originally referenced in
 your configuration.
 
 ```html title="A pyscript.js_import example."
-<script type="py" async>
+<script type="py">
 from pyscript import js_import, window
 
 escaper, = await js_import("https://esm.run/html-escaper")
@@ -899,7 +897,7 @@ asynchronous way to import packages that were not originally referenced in your
 configuration.
 
 ```html title="A pyscript.py_import example."
-<script type="py" async>
+<script type="py">
 from pyscript import py_import
 
 matplotlib, regex, = await py_import("matplotlib", "regex")

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.1/core.css">
-      <script type="module" src="https://pyscript.net/releases/2024.8.1/core.js"></script>
+      <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>
   </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.1/core.css">
-      <script type="module" src="https://pyscript.net/releases/2024.8.1/core.js"></script>
+      <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>
   </head>
   <body>
     <h1>Polyglot 🦜 💬 🇬🇧 ➡️ 🏴‍☠️</h1>

diff --git a/docs/faq.md b/docs/faq.md
@@ -819,7 +819,7 @@ Combined with our `pyscript.fetch` utility, it's also possible to store more
 complex data from the web.
 
 ```python title="Writing a binary file."
-# Assume an `async` attribute / execution.
+# Assume async execution.
 from pyscript import fetch, window
 
 href = window.location.href

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.1/core.css">
+        <link rel="stylesheet" href="https://pyscript.net/releases/2024.8.2/core.css">
         <!-- This script tag bootstraps PyScript -->
-        <script type="module" src="https://pyscript.net/releases/2024.8.1/core.js"></script>
+        <script type="module" src="https://pyscript.net/releases/2024.8.2/core.js"></script>
     </head>
     <body>
         <!-- your code goes here... -->
@@ -75,8 +75,27 @@ attributes:
   JSON or a TOML file,
   `config='{"packages":["numpy"]}'` and `config="./config.json"` or
   `config="./config.toml"` are all valid.
-* `async` - your Python code can contain a
-  [top level await](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await#top_level_await).
+* `async` - set this flag to `"false"` so your code won't run within a
+  [top level await](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await#top_level_await)
+  (the default behaviour).
+
+
+!!! warning
+
+    **This behaviour changed in version 2024.8.2.**
+
+    PyScript now uses a 
+    [top level await](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await#top_level_await)
+    by default.
+
+    You used to have to include the `async` flag to enable this. Now, instead,
+    use `async="false"` to revert the behaviour back to the old default
+    behaviour of synchronous evaluation.
+
+    We made this change because many folks were `await`-ing functions and
+    missing or not realising the need for the (old) `async` attribute. Hence
+    the flip in behaviour.
+
 * `worker` - a flag to indicate your Python code is to be run on a
   [web worker](workers.md) instead of the "main thread" that looks after the user
   interface.

diff --git a/docs/user-guide/plugins.md b/docs/user-guide/plugins.md
@@ -42,9 +42,10 @@ on a web worker, the exact same sequence of steps takes place:
     callback found in test frameworks.
 
 PyScript's interpreters can run their code either *synchronously* or
-*asynchronously*. No matter, the very same sequence is guaranteed to run in
-order in both cases, the only difference being the naming convention used to
-reference synchronous or asynchronous lifecycle hooks.
+*asynchronously* (**note**, the default is asynchronously). No matter, the very
+same sequence is guaranteed to run in order in both cases, the only difference
+being the naming convention used to reference synchronous or asynchronous
+lifecycle hooks.
 
 ### Hooks
 
@@ -99,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.1/core.js";
+import { hooks } from "https://pyscript.net/releases/2024.8.2/core.js";
 
 hooks.worker.onReady.add(() => {
     // NOT suggested, just an example!
@@ -113,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.1/core.js";
+import { hooks } from "https://pyscript.net/releases/2024.8.2/core.js";
 
 // NO NO NO NO NO! ☠️
 let i = 0;
@@ -146,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.1/core.js";
+import { hooks } from "https://pyscript.net/releases/2024.8.2/core.js";
 
 // The `hooks.main` attribute defines plugins that run on the main thread.
 hooks.main.onReady.add((wrap, element) => {
@@ -196,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.1/core.css">
-        <script type="module" src="https://pyscript.net/releases/2024.8.1/core.js"></script>
+        <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>
     </head>
     <body>
         <script type="mpy">

diff --git a/docs/user-guide/workers.md b/docs/user-guide/workers.md
@@ -282,12 +282,11 @@ 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.1/core.css">
+    <link rel="stylesheet" href="https://pyscript.net/releases/2024.8.2/core.css">
     <!-- This script tag bootstraps PyScript -->
-    <script type="module" src="https://pyscript.net/releases/2024.8.1/core.js"></script>
+    <script type="module" src="https://pyscript.net/releases/2024.8.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>
+    <script type="mpy" src="main.py"></script>
   </head>
 </html>
 ```

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