From 1b44a05823aa7d005f1e22ef6684c319b89ad420 Mon Sep 17 00:00:00 2001 From: "Nicholas H.Tollervey" Date: Fri, 15 Mar 2024 11:11:36 +0000 Subject: [PATCH 1/2] Bump to 2024-3-1 and add docs for setup in editor, and new fetch in pyscript namespace. --- docs/beginning-pyscript.md | 8 ++-- docs/user-guide/builtins.md | 68 ++++++++++++++++++++++++++++++++++ docs/user-guide/editor.md | 25 +++++++++++++ docs/user-guide/first-steps.md | 4 +- docs/user-guide/plugins.md | 2 +- version.json | 2 +- 6 files changed, 101 insertions(+), 8 deletions(-) diff --git a/docs/beginning-pyscript.md b/docs/beginning-pyscript.md index 67dcc1c..2cde017 100644 --- a/docs/beginning-pyscript.md +++ b/docs/beginning-pyscript.md @@ -106,8 +106,8 @@ module in the document's `` tag: 🦜 Polyglot - Piratical PyScript - - + + @@ -157,8 +157,8 @@ In the end, our HTML should look like this: 🦜 Polyglot - Piratical PyScript - - + +

Polyglot 🦜 💬 🇬🇧 ➡️ 🏴‍☠️

diff --git a/docs/user-guide/builtins.md b/docs/user-guide/builtins.md index 85851fd..3257930 100644 --- a/docs/user-guide/builtins.md +++ b/docs/user-guide/builtins.md @@ -116,6 +116,74 @@ 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. + +```python title="A simple HTTP GET with pyscript.fetch" +from pyscript import fetch + + +response = await fetch("https://example.com") +``` + +If the `fetch` operation _returns 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: + +* `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. +* `response.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. +* `response.bytearray()` returns a Python [`bytearray`](https://docs.python.org/3/library/stdtypes.html#bytearray) version of the response. +* `response.json()` returns a Python datastructure representing a JSON serialised payload in the response. +* `response.text()` returns a Python string version of the response. + +!!! warning + + Unlike the browser based `fetch` API, you **do not need to await** the + methods listed above, in order to get the data from 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") +``` + +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 index 8313cb2..77931fa 100644 --- 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: +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`" + + + +``` + !!! 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 index b63ec76..6256d1e 100644 --- a/docs/user-guide/first-steps.md +++ b/docs/user-guide/first-steps.md @@ -20,9 +20,9 @@ CSS: - + - + diff --git a/docs/user-guide/plugins.md b/docs/user-guide/plugins.md index 2381016..5921e6c 100644 --- 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 index 8b8721f..0ca80dc 100644 --- a/version.json +++ b/version.json @@ -1,3 +1,3 @@ { - "version": "2024.2.1" + "version": "2024.3.1" } From 8378989effeb23b01b3ede4bb9673ce2e2b49c4f Mon Sep 17 00:00:00 2001 From: "Nicholas H.Tollervey" Date: Fri, 15 Mar 2024 11:22:47 +0000 Subject: [PATCH 2/2] Update docs on fetch. --- docs/user-guide/builtins.md | 24 ++++++++++-------------- 1 file changed, 10 insertions(+), 14 deletions(-) diff --git a/docs/user-guide/builtins.md b/docs/user-guide/builtins.md index 3257930..b827686 100644 --- a/docs/user-guide/builtins.md +++ b/docs/user-guide/builtins.md @@ -126,16 +126,17 @@ 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. +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") +response = await fetch("https://example.com").text() ``` -If the `fetch` operation _returns a response that is not deemed `OK`_ (the +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. @@ -143,17 +144,12 @@ then an exception is raised. Assuming an `OK` response, the following methods are available to you to access the data returned from the server: -* `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. -* `response.blob()` returns a JavaScript [`blob`](https://developer.mozilla.org/en-US/docs/Web/API/Response/blob) version of the response. This is equivalent +* `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. -* `response.bytearray()` returns a Python [`bytearray`](https://docs.python.org/3/library/stdtypes.html#bytearray) version of the response. -* `response.json()` returns a Python datastructure representing a JSON serialised payload in the response. -* `response.text()` returns a Python string version of the response. - -!!! warning - - Unlike the browser based `fetch` API, you **do not need to await** the - methods listed above, in order to get the data from the response. +* `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: @@ -162,7 +158,7 @@ that you should simply pass in as keyword arguments like this: from pyscript import fetch -response = await fetch("https://example.com", method="POST", body="HELLO") +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()`.