Merge pull request #130 from pyscript/2024-6-2

ntoll · web-flow · commit 109138d71b8e · 2024-06-21T15:03:37.000+01:00
2024 6 2
diff --git a/docs/beginning-pyscript.md b/docs/beginning-pyscript.md
@@ -112,8 +112,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.6.1/core.css">
-      <script type="module" src="https://pyscript.net/releases/2024.6.1/core.js"></script>
+      <link rel="stylesheet" href="https://pyscript.net/releases/2024.6.2/core.css">
+      <script type="module" src="https://pyscript.net/releases/2024.6.2/core.js"></script>
   </head>
   <body>
 
@@ -163,8 +163,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.6.1/core.css">
-      <script type="module" src="https://pyscript.net/releases/2024.6.1/core.js"></script>
+      <link rel="stylesheet" href="https://pyscript.net/releases/2024.6.2/core.css">
+      <script type="module" src="https://pyscript.net/releases/2024.6.2/core.js"></script>
   </head>
   <body>
     <h1>Polyglot 🦜 💬 🇬🇧 ➡️ 🏴‍☠️</h1>
diff --git a/docs/user-guide/builtins.md b/docs/user-guide/builtins.md
@@ -372,6 +372,80 @@ The following code demonstrates a `pyscript.WebSocket` in action.
     ws = WebSocket(url="ws://example.com/socket", onmessage=onmessage)
     ```
 
+### `pyscript.storage`
+
+The `pyscript.storage` API wraps the browser's built-in
+[IndexDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API)
+persistent storage in a synchronous Pythonic API.
+
+!!! info 
+
+    The storage API is persistent per user tab, page, or domain, in the same
+    way IndexedDB persists.
+
+    This API **is not** saving files in the interpreter's virtual file system
+    nor onto the user's hard drive.
+
+```python
+from pyscript import storage
+
+
+# Each store must have a meaningful name.
+store = await storage("my-storage-name")
+
+# store is a dictionary and can now be used as such.
+```
+
+The returned dictionary automatically loads the current state of the referenced
+IndexDB. All changes are automatically queued in the background.
+
+```python
+# This is a write operation.
+store["key"] = value
+
+# This is also a write operation (it changes the stored data).
+del store["key"]
+```
+
+Should you wish to be certain changes have been synchronized to the underlying
+IndexDB, just `await store.sync()`.
+
+Common types of value can be stored via this API: `bool`, `float`, `int`, `str`
+and `None`. In addition, data structures like `list`, `dict` and `tuple` can
+be stored.
+
+!!! warning
+
+    Because of the way the underlying data structure are stored in IndexDB,
+    a Python `tuple` will always be returned as a Python `list`.
+
+It is even possible to store arbitrary data via a `bytearray` or
+`memoryview` object. However, there is a limitation that **such values must be
+stored as a single key/value pair, and not as part of a nested data
+structure**.
+
+Sometimes you may need to modify the behaviour of the `dict` like object
+returned by `pyscript.storage`. To do this, create a new class that inherits
+from `pyscript.Storage`, then pass in your class to `pyscript.storage` as the
+`storage_class` argument:
+
+```python
+from pyscript import window, storage, Storage
+
+
+class MyStorage(Storage):
+
+    def __setitem__(self, key, value):
+        super().__setitem__(key, value)
+        window.console.log(key, value)
+        ...
+
+
+store = await storage("my-data-store", storage_class=MyStorage)
+
+# The store object is now an instance of MyStorage.
+```
+
 ### `pyscript.ffi.to_js`
 
 A utility function to convert Python references into their JavaScript
diff --git a/docs/user-guide/editor.md b/docs/user-guide/editor.md
@@ -173,6 +173,58 @@ If a `setup` editor is present, that's the only PyEditor that needs a config.
 Any subsequent related editor will reuse the config parsed and bootstrapped for
 the `setup` editor.
 
+## Run via keyboard
+
+Depending on your operating system, a combination of either `Ctrl-Enter`,
+`Cmd-Enter` or `Shift-Enter` will execute the code in the editor (no need to
+move the mouse to click the run button).
+
+## Override run
+
+Sometimes you just need to override the way the editor runs code.
+
+The editor's `handleEvent` can be overridden to achieve this:
+
+```html title="Overriding execution via handleEvent."
+<script type="mpy-editor" id="foreign">
+print(6 * 7)
+</script>
+
+<script type="mpy">
+from pyscript import document
+
+def handle_event(event):
+    # will log `print(6 * 7)`
+    print(event.code)
+    # prevent default execution
+    return False
+
+# Grab reference to the editor
+foreign = document.getElementById("foreign")
+# Override handleEvent with your own customisation.
+foreign.handleEvent = handle_event
+</script>
+```
+
+This
+[live example](https://agiammarchi.pyscriptapps.com/pyeditor-iot-example/latest/)
+shows how the editor can be used to execute code via a USB serial connection to
+a connected MicroPython microcontroller.
+
+## Tab behavior
+
+We currently trap the `tab` key in a way that reflects what a regular code
+editor would do: the code is simply indented, rather than focus moving to
+another element.
+
+We are fully aware of the implications this might have around accessibility so
+we followed
+[this detailed advice from Codemirror's documentation](https://codemirror.net/examples/tab/)
+We have an *escape hatch* to move focus outside the editor. Press `esc` before
+`tab` to move focus to the next focusable element. Otherwise `tab` indents
+code.
+
+
 ## Still missing
 
 The PyEditor is currently under active development and refinement, so features
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.6.1/core.css">
+        <link rel="stylesheet" href="https://pyscript.net/releases/2024.6.2/core.css">
         <!-- This script tag bootstraps PyScript -->
-        <script type="module" src="https://pyscript.net/releases/2024.6.1/core.js"></script>
+        <script type="module" src="https://pyscript.net/releases/2024.6.2/core.js"></script>
     </head>
     <body>
         <!-- your code goes here... -->
diff --git a/docs/user-guide/plugins.md b/docs/user-guide/plugins.md
@@ -99,7 +99,7 @@ For example, this will work because all references are contained within the
 registered function:
 
 ```js
-import { hooks } from "https://pyscript.net/releases/2024.6.1/core.js";
+import { hooks } from "https://pyscript.net/releases/2024.6.2/core.js";
 
 hooks.worker.onReady.add(() => {
     // NOT suggested, just an example!
@@ -113,7 +113,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.6.1/core.js";
+import { hooks } from "https://pyscript.net/releases/2024.6.2/core.js";
 
 // NO NO NO NO NO! ☠️
 let i = 0;
@@ -146,7 +146,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.6.1/core.js";
+import { hooks } from "https://pyscript.net/releases/2024.6.2/core.js";
 
 // The `hooks.main` attribute defines plugins that run on the main thread.
 hooks.main.onReady.add((wrap, element) => {
@@ -196,8 +196,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.6.1/core.css">
-        <script type="module" src="https://pyscript.net/releases/2024.6.1/core.js"></script>
+        <link rel="stylesheet" href="https://pyscript.net/releases/2024.6.2/core.css">
+        <script type="module" src="https://pyscript.net/releases/2024.6.2/core.js"></script>
     </head>
     <body>
         <script type="mpy">
diff --git a/docs/user-guide/workers.md b/docs/user-guide/workers.md
@@ -164,9 +164,9 @@ 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.6.1/core.css">
+    <link rel="stylesheet" href="https://pyscript.net/releases/2024.6.2/core.css">
     <!-- This script tag bootstraps PyScript -->
-    <script type="module" src="https://pyscript.net/releases/2024.6.1/core.js"></script>
+    <script type="module" src="https://pyscript.net/releases/2024.6.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>
diff --git a/version.json b/version.json
@@ -1,3 +1,3 @@
 {
-    "version": "2024.6.1"
+    "version": "2024.6.2"
 }

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