diff --git a/docs/api.md b/docs/api.md
index 664145f..b12953d 100644
--- 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
-
+
+
@@ -168,8 +168,8 @@ In the end, our HTML should look like this:
🦜 Polyglot - Piratical PyScript
-
-
+
+
Polyglot 🦜 💬 🇬🇧 ➡️ 🏴☠️
diff --git a/docs/faq.md b/docs/faq.md
index f249f23..23c25af 100644
--- 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
index d0fcffe..b13ba18 100644
--- a/docs/user-guide/first-steps.md
+++ b/docs/user-guide/first-steps.md
@@ -20,9 +20,9 @@ CSS:
-
+
-
+
@@ -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
index 8d2d696..9c43cb1 100644
--- 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(() => {
-
-
+
+
+
PyWorker - mpy bootstrapping pyodide example
-
-
+