Merge pull request #72 from pyscript/2024-3-1

WebReflection · web-flow · commit 3c28bb79b83b · 2024-03-15T12:47:26.000+01:00
Bump to 2024-3-1 and add docs for setup in editor, and new fetch in pyscript namespace.
diff --git a/docs/beginning-pyscript.md b/docs/beginning-pyscript.md
@@ -106,8 +106,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.2.1/core.css">
-      <script type="module" src="https://pyscript.net/releases/2024.2.1/core.js"></script>
+      <link rel="stylesheet" href="https://pyscript.net/releases/2024.3.1/core.css">
+      <script type="module" src="https://pyscript.net/releases/2024.3.1/core.js"></script>
   </head>
   <body>
 
@@ -157,8 +157,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.2.1/core.css">
-      <script type="module" src="https://pyscript.net/releases/2024.2.1/core.js"></script>
+      <link rel="stylesheet" href="https://pyscript.net/releases/2024.3.1/core.css">
+      <script type="module" src="https://pyscript.net/releases/2024.3.1/core.js"></script>
   </head>
   <body>
     <h1>Polyglot 🦜 💬 🇬🇧 ➡️ 🏴‍☠️</h1>
diff --git a/docs/user-guide/builtins.md b/docs/user-guide/builtins.md
@@ -116,6 +116,70 @@ Such named modules will always then be available under the
     Please see the documentation (linked above) about restrictions and gotchas
     when configuring how JavaScript modules are made available to PyScript.
 
+### `pyscript.fetch`
+
+A common task is to `fetch` data from the web via HTTP requests. The
+`pyscript.fetch` function provides a uniform way to achieve this in both
+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`.
+
+```python title="A simple HTTP GET with pyscript.fetch"
+from pyscript import fetch
+
+
+response = await fetch("https://example.com").text()
+```
+
+If the `fetch` operation _causes a response that is not deemed `OK`_ (the
+definition of which
+[can be found here](https://developer.mozilla.org/en-US/docs/Web/API/Response/ok))
+then an exception is raised.
+
+Assuming an `OK` response, the following methods are available to you to access
+the data returned from the server:
+
+* `await fetch("https://example.com").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.
+* `await fetch("https://example.com").blob()` returns a JavaScript [`blob`](https://developer.mozilla.org/en-US/docs/Web/API/Response/blob) version of the response. This is equivalent
+to the [`blob()` method](https://developer.mozilla.org/en-US/docs/Web/API/Response/blob) in the browser based `fetch` API.
+* `await fetch("https://example.com").bytearray()` returns a Python [`bytearray`](https://docs.python.org/3/library/stdtypes.html#bytearray) version of the response.
+* `await fetch("https://example.com").json()` returns a Python datastructure representing a JSON serialised payload in the response.
+* `await fetch("https://example.com").text()` returns a Python string version of the response.
+
+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)
+that you should simply pass in as keyword arguments like this:
+
+```python title="Supplying request options."
+from pyscript import fetch
+
+
+response = await fetch("https://example.com", method="POST", body="HELLO").text()
+```
+
+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()`.
+
+!!! Danger
+
+    You may encounter [CORS](https://developer.mozilla.org/en-US/docs/Glossary/CORS) errors (especially with reference to a missing
+    [Access-Control-Allow-Origin header](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS/Errors/CORSMissingAllowOrigin).
+
+    This is a security feature of modern browsers where the site to which you
+    are making a request **will not process a request from a site hosted at
+    another domain**.
+
+    For example, if your PyScript app is hosted under `example.com` and you
+    make a request to `bbc.co.uk` (who don't allow requests from other domains)
+    then you'll encounter this sort of CORS related error.
+
+    There is nothing PyScript can do about this problem (it's a feature, not a
+    bug). However, you could use a pass-through proxy service to get around
+    this limitation (i.e. the proxy service makes the call on your behalf).
+
 ## Main-thread only features
 
 ### `pyscript.PyWorker`
diff --git a/docs/user-guide/editor.md b/docs/user-guide/editor.md
@@ -54,6 +54,31 @@ The outcome of these code fragments should look something like this:
 
 <img src="../../assets/images/pyeditor1.gif" style="border: 1px solid black; border-radius: 0.2rem; box-shadow: var(--md-shadow-z1);"/>
 
+Sometimes you need to create a pre-baked Pythonic context for a shared
+environment used by an editor. This need is especially helpful in educational
+situations where boilerplate code can be run, with just the important salient
+code available in the editor.
+
+To achieve this end use the `setup` attribute within a `script` tag. The
+content of this editor will not be shown, but will bootstrap the referenced
+environment automatically before any following editor within the same
+environment is evaluated.
+
+```html title="Bootstrapping an environment with `setup`"
+<script type="mpy-editor" env="test_env" setup>
+# This code will not be visible, but will run before the next editor's code is
+# evaluated.
+a = 1
+</script>
+
+<script type="mpy-editor" env="test_env">
+# Without the "setup" attribute, this editor is visible. Because it is using
+# the same env as the previous "setup" editor, the previous editor's code is
+# always evaluated first.
+print(a)
+</script>
+```
+
 !!! info
 
     Notice that the interpreter type, and optional environment name is shown
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.2.1/core.css">
+        <link rel="stylesheet" href="https://pyscript.net/releases/2024.3.1/core.css">
         <!-- This script tag bootstraps PyScript -->
-        <script type="module" src="https://pyscript.net/releases/2024.2.1/core.js"></script>
+        <script type="module" src="https://pyscript.net/releases/2024.3.1/core.js"></script>
     </head>
     <body>
         <!-- your code goes here... -->
diff --git a/docs/user-guide/plugins.md b/docs/user-guide/plugins.md
@@ -14,7 +14,7 @@ Here's an example of how a PyScript plugin looks like:
 
 ```js
 // import the hooks from PyScript first...
-import { hooks } from "https://pyscript.net/releases/2024.2.1/core.js";
+import { hooks } from "https://pyscript.net/releases/2024.3.1/core.js";
 
 // Use the `main` attribute on hooks do define plugins that run on the main thread
 hooks.main.onReady.add((wrap, element) => {
diff --git a/version.json b/version.json
@@ -1,3 +1,3 @@
 {
-    "version": "2024.2.1"
+    "version": "2024.3.1"
 }

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,3 @@`
`1`	`1`	`{`
`2`		`- "version": "2024.2.1"`
	`2`	`+ "version": "2024.3.1"`
`3`	`3`	`}`