Merge pull request #145 from pyscript/2024-10-1

2024 10 1
pyscript · Oct 7, 2024 · a7fe593 · a7fe593
2 parents 9943caf + 5557821
commit a7fe593
Show file tree

Hide file tree

Showing 6 changed files with 50 additions and 14 deletions.
diff --git a/docs/api.md b/docs/api.md
@@ -417,6 +417,42 @@ store = await storage("my-data-store", storage_class=MyStorage)
 # The store object is now an instance of MyStorage.
 ```
 
+### `@pyscript/core/donkey`
+
+Sometimes you need a Python worker ready and waiting to evaluate any code on
+your behalf. This is the concept behind the JavaScript "donkey". We couldn't
+think of a better way than "donkey" to describe something that is easy to
+understand and shoulders the burden without complaint. This feature
+means you're able to use PyScript without resorting to specialised
+`<script type="py">` style tags. It's just vanilla JavaScript.
+
+Simply `import { donkey } from '@pyscript/core/dist/core.js'` and automatically
+have both a *pyscript* module running on your page and a utility to bootstrap a
+terminal based worker to evaluate any Python code as and when needed in the
+future.
+
+```js title="A donkey worker"
+import { donkey } from '@pyscript/core/dist/core.js';
+
+const {
+  process,              // process(code) code (visible in the terminal)
+  execute,              // execute(statement) in Python exec way
+  evaluate,             // evaluate(expression) in Python eval way
+  clear,                // clear() the terminal
+  reset,                // reset() the terminal (including colors)
+  kill,                 // kill() the worker forever
+} = donkey({
+  type: 'py' || 'mpy',  // the Python interpreter to run
+  persistent: false,    // use `true` to track globals and locals
+  terminal: '',         // optionally set a target terminal container
+  config: {},           // the worker config (packages, files, etc.)
+});
+```
+
+By default PyScript creates a target terminal. If you don't want a terminal to
+appear on your page, use the `terminal` option to point to a CSS addressable
+container that is not visible (i.e. the target has `display: none`).
+
 ### `@pyscript/core/dist/storage.js`
 
 The equivalent functionality based on the *JS* module can be found through our module.

diff --git a/docs/beginning-pyscript.md b/docs/beginning-pyscript.md
@@ -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.9.2/core.css">
-      <script type="module" src="https://pyscript.net/releases/2024.9.2/core.js"></script>
+      <link rel="stylesheet" href="https://pyscript.net/releases/2024.10.1/core.css">
+      <script type="module" src="https://pyscript.net/releases/2024.10.1/core.js"></script>
   </head>
   <body>
 
@@ -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.9.2/core.css">
-      <script type="module" src="https://pyscript.net/releases/2024.9.2/core.js"></script>
+      <link rel="stylesheet" href="https://pyscript.net/releases/2024.10.1/core.css">
+      <script type="module" src="https://pyscript.net/releases/2024.10.1/core.js"></script>
   </head>
   <body>
     <h1>Polyglot 🦜 💬 🇬🇧 ➡️ 🏴‍☠️</h1>

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.9.2/core.css">
+        <link rel="stylesheet" href="https://pyscript.net/releases/2024.10.1/core.css">
         <!-- This script tag bootstraps PyScript -->
-        <script type="module" src="https://pyscript.net/releases/2024.9.2/core.js"></script>
+        <script type="module" src="https://pyscript.net/releases/2024.10.1/core.js"></script>
     </head>
     <body>
         <!-- your code goes here... -->

diff --git a/docs/user-guide/plugins.md b/docs/user-guide/plugins.md
@@ -100,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.9.2/core.js";
+import { hooks } from "https://pyscript.net/releases/2024.10.1/core.js";
 
 hooks.worker.onReady.add(() => {
     // NOT suggested, just an example!
@@ -114,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.9.2/core.js";
+import { hooks } from "https://pyscript.net/releases/2024.10.1/core.js";
 
 // NO NO NO NO NO! ☠️
 let i = 0;
@@ -147,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.9.2/core.js";
+import { hooks } from "https://pyscript.net/releases/2024.10.1/core.js";
 
 // The `hooks.main` attribute defines plugins that run on the main thread.
 hooks.main.onReady.add((wrap, element) => {
@@ -197,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.9.2/core.css">
-        <script type="module" src="https://pyscript.net/releases/2024.9.2/core.js"></script>
+        <link rel="stylesheet" href="https://pyscript.net/releases/2024.10.1/core.css">
+        <script type="module" src="https://pyscript.net/releases/2024.10.1/core.js"></script>
     </head>
     <body>
         <script type="mpy">

diff --git a/docs/user-guide/workers.md b/docs/user-guide/workers.md
@@ -282,9 +282,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.9.2/core.css">
+    <link rel="stylesheet" href="https://pyscript.net/releases/2024.10.1/core.css">
     <!-- This script tag bootstraps PyScript -->
-    <script type="module" src="https://pyscript.net/releases/2024.9.2/core.js"></script>
+    <script type="module" src="https://pyscript.net/releases/2024.10.1/core.js"></script>
     <title>PyWorker - mpy bootstrapping pyodide example</title>
     <script type="mpy" src="main.py"></script>
   </head>

diff --git a/version.json b/version.json
@@ -1,3 +1,3 @@
 {
-    "version": "2024.9.2"
+    "version": "2024.10.1"
 }