Document the new async behaviour.

Author: ntoll

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")

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

docs/user-guide/first-steps.md

@@ -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 not 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.

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
 

docs/user-guide/workers.md

@@ -286,8 +286,7 @@ Here's how:
     <!-- This script tag bootstraps PyScript -->
     <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>
 ```