Skip to content

Commit 1b44a05

Browse files
ntollntoll
committed
Bump to 2024-3-1 and add docs for setup in editor, and new fetch in pyscript namespace.
1 parent 86c5be9 commit 1b44a05

File tree

6 files changed

+101
-8
lines changed

6 files changed

+101
-8
lines changed

‎docs/beginning-pyscript.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -106,8 +106,8 @@ module in the document's `<head>` tag:
106106
<meta charset="utf-8" />
107107
<meta name="viewport" content="width=device-width,initial-scale=1" />
108108
<title>🦜 Polyglot - Piratical PyScript</title>
109-
<link rel="stylesheet" href="https://pyscript.net/releases/2024.2.1/core.css">
110-
<script type="module" src="https://pyscript.net/releases/2024.2.1/core.js"></script>
109+
<link rel="stylesheet" href="https://pyscript.net/releases/2024.3.1/core.css">
110+
<script type="module" src="https://pyscript.net/releases/2024.3.1/core.js"></script>
111111
</head>
112112
<body>
113113

@@ -157,8 +157,8 @@ In the end, our HTML should look like this:
157157
<meta charset="utf-8" />
158158
<meta name="viewport" content="width=device-width,initial-scale=1" />
159159
<title>🦜 Polyglot - Piratical PyScript</title>
160-
<link rel="stylesheet" href="https://pyscript.net/releases/2024.2.1/core.css">
161-
<script type="module" src="https://pyscript.net/releases/2024.2.1/core.js"></script>
160+
<link rel="stylesheet" href="https://pyscript.net/releases/2024.3.1/core.css">
161+
<script type="module" src="https://pyscript.net/releases/2024.3.1/core.js"></script>
162162
</head>
163163
<body>
164164
<h1>Polyglot 🦜 💬 🇬🇧 ➡️ 🏴‍☠️</h1>

‎docs/user-guide/builtins.md

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -116,6 +116,74 @@ Such named modules will always then be available under the
116116
Please see the documentation (linked above) about restrictions and gotchas
117117
when configuring how JavaScript modules are made available to PyScript.
118118

119+
### `pyscript.fetch`
120+
121+
A common task is to `fetch` data from the web via HTTP requests. The
122+
`pyscript.fetch` function provides a uniform way to achieve this in both
123+
Pyodide and MicroPython. It is closely modelled on the
124+
[Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) found
125+
in browsers with some important Pythonic differences.
126+
127+
The simple use case is to pass in a URL and `await` the response. Remember, in
128+
order to use `await` you must have the `async` attribute in the `script` tag
129+
that references your code.
130+
131+
```python title="A simple HTTP GET with pyscript.fetch"
132+
from pyscript import fetch
133+
134+
135+
response = await fetch("https://example.com")
136+
```
137+
138+
If the `fetch` operation _returns a response that is not deemed `OK`_ (the
139+
definition of which
140+
[can be found here](https://developer.mozilla.org/en-US/docs/Web/API/Response/ok))
141+
then an exception is raised.
142+
143+
Assuming an `OK` response, the following methods are available to you to access
144+
the data returned from the server:
145+
146+
* `response.arrayBuffer()` returns a Python [memoryview](https://docs.python.org/3/library/stdtypes.html#memoryview) of the response. This is equivalent to the [`arrayBuffer()` method](https://developer.mozilla.org/en-US/docs/Web/API/Response/arrayBuffer) in the browser based `fetch` API.
147+
* `response.blob()` returns a JavaScript [`blob`](https://developer.mozilla.org/en-US/docs/Web/API/Response/blob) version of the response. This is equivalent
148+
to the [`blob()` method](https://developer.mozilla.org/en-US/docs/Web/API/Response/blob) in the browser based `fetch` API.
149+
* `response.bytearray()` returns a Python [`bytearray`](https://docs.python.org/3/library/stdtypes.html#bytearray) version of the response.
150+
* `response.json()` returns a Python datastructure representing a JSON serialised payload in the response.
151+
* `response.text()` returns a Python string version of the response.
152+
153+
!!! warning
154+
155+
Unlike the browser based `fetch` API, you **do not need to await** the
156+
methods listed above, in order to get the data from the response.
157+
158+
The underlying browser `fetch` API has [many request options](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch#supplying_request_options)
159+
that you should simply pass in as keyword arguments like this:
160+
161+
```python title="Supplying request options."
162+
from pyscript import fetch
163+
164+
165+
response = await fetch("https://example.com", method="POST", body="HELLO")
166+
```
167+
168+
Should you need access to the underlying [JavaScript response object](https://developer.mozilla.org/en-US/docs/Web/API/Response), you can find it as `response._response()`.
169+
170+
!!! Danger
171+
172+
You may encounter [CORS](https://developer.mozilla.org/en-US/docs/Glossary/CORS) errors (especially with reference to a missing
173+
[Access-Control-Allow-Origin header](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS/Errors/CORSMissingAllowOrigin).
174+
175+
This is a security feature of modern browsers where the site to which you
176+
are making a request **will not process a request from a site hosted at
177+
another domain**.
178+
179+
For example, if your PyScript app is hosted under `example.com` and you
180+
make a request to `bbc.co.uk` (who don't allow requests from other domains)
181+
then you'll encounter this sort of CORS related error.
182+
183+
There is nothing PyScript can do about this problem (it's a feature, not a
184+
bug). However, you could use a pass-through proxy service to get around
185+
this limitation (i.e. the proxy service makes the call on your behalf).
186+
119187
## Main-thread only features
120188

121189
### `pyscript.PyWorker`

‎docs/user-guide/editor.md

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,31 @@ The outcome of these code fragments should look something like this:
5454

5555
<img src="../../assets/images/pyeditor1.gif" style="border: 1px solid black; border-radius: 0.2rem; box-shadow: var(--md-shadow-z1);"/>
5656

57+
Sometimes you need to create a pre-baked Pythonic context for a shared
58+
environment used by an editor. This need is especially helpful in educational
59+
situations where boilerplate code can be run, with just the important salient
60+
code available in the editor.
61+
62+
To achieve this end use the `setup` attribute within a `script` tag. The
63+
content of this editor will not be shown, but will bootstrap the referenced
64+
environment automatically before any following editor within the same
65+
environment is evaluated.
66+
67+
```html title="Bootstrapping an environment with `setup`"
68+
<script type="mpy-editor" env="test_env" setup>
69+
# This code will not be visible, but will run before the next editor's code is
70+
# evaluated.
71+
a = 1
72+
</script>
73+
74+
<script type="mpy-editor" env="test_env">
75+
# Without the "setup" attribute, this editor is visible. Because it is using
76+
# the same env as the previous "setup" editor, the previous editor's code is
77+
# always evaluated first.
78+
print(a)
79+
</script>
80+
```
81+
5782
!!! info
5883
5984
Notice that the interpreter type, and optional environment name is shown

‎docs/user-guide/first-steps.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,9 +20,9 @@ CSS:
2020
<meta charset="UTF-8">
2121
<meta name="viewport" content="width=device-width,initial-scale=1.0">
2222
<!-- PyScript CSS -->
23-
<link rel="stylesheet" href="https://pyscript.net/releases/2024.2.1/core.css">
23+
<link rel="stylesheet" href="https://pyscript.net/releases/2024.3.1/core.css">
2424
<!-- This script tag bootstraps PyScript -->
25-
<script type="module" src="https://pyscript.net/releases/2024.2.1/core.js"></script>
25+
<script type="module" src="https://pyscript.net/releases/2024.3.1/core.js"></script>
2626
</head>
2727
<body>
2828
<!-- your code goes here... -->

‎docs/user-guide/plugins.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ Here's an example of how a PyScript plugin looks like:
1414

1515
```js
1616
// import the hooks from PyScript first...
17-
import { hooks } from "https://pyscript.net/releases/2024.2.1/core.js";
17+
import { hooks } from "https://pyscript.net/releases/2024.3.1/core.js";
1818

1919
// Use the `main` attribute on hooks do define plugins that run on the main thread
2020
hooks.main.onReady.add((wrap, element) => {

‎version.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
{
2-
"version": "2024.2.1"
2+
"version": "2024.3.1"
33
}

0 commit comments

Comments
 (0)