Skip to content

Documentation for release 2024.8.2 #136

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Aug 5, 2024
Merged

Documentation for release 2024.8.2 #136

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
cf41d55
Bump version to 2024-08-2 in examples.
ntoll Aug 5, 2024
af49775
Document the new async behaviour.
ntoll Aug 5, 2024
8653cd1
Fix typo
ntoll Aug 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 6 additions & 8 deletions docs/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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"]
Expand All @@ -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]"):
Expand All @@ -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")
Expand All @@ -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")
Expand Down
8 changes: 4 additions & 4 deletions docs/beginning-pyscript.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>

Expand Down Expand Up @@ -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>
Expand Down
2 changes: 1 addition & 1 deletion docs/faq.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
27 changes: 23 additions & 4 deletions docs/user-guide/first-steps.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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... -->
Expand Down Expand Up @@ -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.
Expand Down
17 changes: 9 additions & 8 deletions docs/user-guide/plugins.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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!
Expand All @@ -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;
Expand Down Expand Up @@ -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) => {
Expand Down Expand Up @@ -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">
Expand Down
7 changes: 3 additions & 4 deletions docs/user-guide/workers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
```
Expand Down
2 changes: 1 addition & 1 deletion version.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
{
"version": "2024.8.1"
"version": "2024.8.2"
}