Merge pull request #52 from pyscript/2023-12-1

2023.12.1 documentation changes
pyscript · Dec 8, 2023 · ca653c9 · ca653c9
2 parents 6d14e95 + e75c01b
commit ca653c9
Show file tree

Hide file tree

Showing 16 changed files with 193 additions and 30 deletions.
diff --git a/docs/assets/images/pyeditor1.gif b/docs/assets/images/pyeditor1.gif
diff --git a/docs/assets/images/pyterm2.gif b/docs/assets/images/pyterm2.gif
diff --git a/docs/assets/images/pyterm3.gif b/docs/assets/images/pyterm3.gif
diff --git a/docs/beginning-pyscript.md b/docs/beginning-pyscript.md
@@ -70,7 +70,7 @@ level.
 
 You can see this application embedded into the page below:
 
-<iframe src="https://ntoll.pyscriptapps.com/piratical/v3" style="border: 1px solid black; width:100%;min-height: 400px; border-radius: 0.2rem; box-shadow: var(--md-shadow-z1);"></iframe>
+<iframe src="https://ntoll.pyscriptapps.com/piratical/v4/" style="border: 1px solid black; width:100%;min-height: 400px; border-radius: 0.2rem; box-shadow: var(--md-shadow-z1);"></iframe>
 
 Let's explore each of the three files that make this app work.
 
@@ -106,7 +106,7 @@ 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>
-      <script type="module" src="https://pyscript.net/releases/2023.11.2/core.js"></script>
+      <script type="module" src="https://pyscript.net/releases/2023.12.1/core.js"></script>
   </head>
   <body>
 
@@ -139,7 +139,8 @@ application's output.
 
 There's something strange about the `<button>` tag: it has a `py-click`
 attribute with the value `translate_english`. This is, in fact, the name of a
-Python function we'll run whenever the button is clicked.
+Python function we'll run whenever the button is clicked. Such `py-*` style
+attributes are [built into PyScript](user-guide/builtins.md#html-attributes).
 
 We put all this together in the `script` tag at the end of the `<body>`. This
 tells the browser we're using PyScript (`type="py"`), and where PyScript
@@ -155,7 +156,7 @@ 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>
-      <script type="module" src="https://pyscript.net/releases/2023.11.2/core.js"></script>
+      <script type="module" src="https://pyscript.net/releases/2023.12.1/core.js"></script>
   </head>
   <body>
     <h1>Polyglot 🦜 💬 🇬🇧 ➡️ 🏴‍☠️</h1>

diff --git a/docs/index.md b/docs/index.md
@@ -34,10 +34,10 @@
   <dt><strong>I want to contribute...</strong></dt>
   <dd>
     <p>Welcome, friend!
-    PyScript is an <a href="/license/">open source project</a>, we expect participants to act in
-    the spirit of our <a href="/conduct/">code of conduct</a> and we have many 
-    ways in which <a href="/contributing/"><u>you</u> can contribute</a>.
-    Our <a href="/developers/">developer guide</a> explains how to set
+    PyScript is an <a href="license/">open source project</a>, we expect participants to act in
+    the spirit of our <a href="conduct/">code of conduct</a> and we have many 
+    ways in which <a href="contributing/"><u>you</u> can contribute</a>.
+    Our <a href="developers/">developer guide</a> explains how to set
     up a working development environment for PyScript.</p>
   </dd>
   <dt><strong>Just show me...</strong></dt>

diff --git a/docs/user-guide/architecture.md b/docs/user-guide/architecture.md
@@ -129,7 +129,7 @@ Here's how PyScript unfolds through time:
        attribute of a `<script>`, `<py-script>` or `<mpy-script>` tag).
     3. Given the detected configuration, download the required interpreter.
     4. Setup the interpreter's environment. This includes any
-       [plugins](configuration.md/#plugins), [packages](configuration.md/#packages) or [files](configuration.md/#files) that need
+       [plugins](configuration.md/#plugins), [packages](configuration.md/#packages), [files](configuration.md/#files) or [JavaScript modules](configuration.md/#javascript-modules)that need
        to be loaded.
     5. Make available various
        [builtin helper objects and functions](builtins.md) to the

diff --git a/docs/user-guide/builtins.md b/docs/user-guide/builtins.md
@@ -1,16 +1,24 @@
 # Builtin helpers
 
 PyScript makes available convenience objects and functions inside
-Python. This is done via the `pyscript` module:
+Python as well as custom attributes in HTML.
+
+In Python this is done via the `pyscript` module:
 
 ```python title="Accessing the document object via the pyscript module"
 from pyscript import document
 ```
 
+In HTML this is done via `py-*` attributes:
+
+```html title="An example of a py-click handler"
+<button id="foo" py-click="handler_defined_in_python">Click me</button>
+```
+
 ## Common features
 
-These objects / functions are available in both the main thread and in code
-running on a web worker:
+These Python objects / functions are available in both the main thread and in
+code running on a web worker:
 
 ### `pyscript.window`
 
@@ -94,6 +102,8 @@ def click_handler(event):
     display("I've been clicked!")
 ```
 
+This functionality is related to the [HTML py-*](#html-attributes) attributes.
+
 ### `pyscript.js_modules`
 
 It is possible to [define JavaScript modules to use within your Python code](configuration.md#javascript-modules).
@@ -152,3 +162,54 @@ from pyscript import sync
 
 sync.hello("PyScript")
 ```
+
+## HTML attributes
+
+As a convenience, and to ensure backwards compatibility, PyScript allows the
+use of inline event handlers via custom HTML attributes.
+
+!!! warning
+
+    This classic pattern of coding (inline event handlers) is no longer
+    considered good practice in web development circles.
+
+    We include this behaviour for historic reasons, but the folks at
+    Mozilla [have a good explanation](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Building_blocks/Events#inline_event_handlers_%E2%80%94_dont_use_these)
+    of why this is currently considered bad practice.
+
+These attributes are expressed as `py-*` attributes of an HTML element that
+reference the name of a Python function to run when the event is fired. You
+should replace the `*` with the _actual name of an event_ (e.g. `py-click`).
+This is similar to how all
+[event handlers on elements](https://html.spec.whatwg.org/multipage/webappapis.html#event-handlers-on-elements,-document-objects,-and-window-objects)
+start with `on` in standard HTML (e.g. `onclick`). The rule of thumb is to
+simply replace `on` with `py-` and then reference the name of a Python
+function.
+
+```html title="A py-click event on an HTML button element."
+<button py-click="handle_click" id="my_button">Click me!</button>
+```
+
+```python title="The related Python function."
+from pyscript import window
+
+
+def handle_click(event):
+    """
+    Simply log the click event to the browser's console.
+    """
+    window.console.log(event)    
+```
+
+Under the hood, the [`pyscript.when`](#pyscriptwhen) decorator is used to
+enable this behaviour.
+
+!!! note
+
+    In earlier versions of PyScript, the value associated with the attribute
+    was simply evaluated by the Python interpreter. This was unsafe:
+    manipulation of the attribute's value could have resulted in the evaluation
+    of arbitrary code.
+
+    This is why we changed to the current behaviour: just supply the name
+    of the Python function to be evaluated, and PyScript will do this safely.
diff --git a/docs/user-guide/configuration.md b/docs/user-guide/configuration.md
@@ -79,8 +79,9 @@ specification of configuration information via a _single_ `<py-config>` or
 
 ## Options
 
-There are four core options ([`interpreter`](#interpreter), [`files`](#files),
-[`packages`](#packages) and [`plugins`](#plugins)). The user is free to define
+There are five core options ([`interpreter`](#interpreter), [`files`](#files),
+[`packages`](#packages), [`plugins`](#plugins) and
+[`js_modules`](#javascript-modules).) The user is free to define
 arbitrary additional configuration options that plugins or an app may require
 for their own reasons.
 
@@ -288,7 +289,7 @@ The `plugins` option lists plugins enabled by PyScript to add extra
 functionality to the platform.
 
 Each plugin should be included on the web page, as described in the
-[plugins](#plugins_1) section below. Then the plugin's name should be listed.
+[plugins](plugins.md) section. Then the plugin's name should be listed.
 
 ```TOML title="A list of plugins in TOML"
 plugins = ["custom_plugin", "!error"]

diff --git a/docs/user-guide/editor.md b/docs/user-guide/editor.md
@@ -0,0 +1,73 @@
+# Python editor 
+
+The PyEditor is a core plugin.
+
+!!! warning
+
+    Work on the Python editor is in its early stages. We have made it available
+    in this version of PyScript to give the community an opportunity to play,
+    experiment and provide feedback.
+
+    Future versions of PyScript will include a more refined, robust and perhaps
+    differently behaving version of the Python editor.
+
+If you specify the type of a `<script>` tag as either `py-editor` (for Pyodide)
+or `mpy-editor` (for MicroPython), the plugin creates a visual code editor,
+with code highlighting and a "run" button to execute the editable code
+contained therein in a non-blocking worker.
+
+The interpreter is not loaded onto the page until the run button is clicked. By
+default each editor has its own independent instance of the specified
+interpreter:
+
+```html title="Two editors, one with Pyodide, the other with MicroPython."
+<script type="py-editor">
+  import sys
+  print(sys.version)
+</script>
+<script type="mpy-editor">
+  import sys
+  print(sys.version)
+  a = 42
+  print(a)
+</script>
+```
+
+However, different editors can share the same interpreter if they share the
+same `env` attribute value.
+
+```html title="Two editors sharing the same MicroPython environment."
+<script type="mpy-editor" env="shared">
+  if not 'a' in globals():
+    a = 1
+  else:
+    a += 1
+  print(a)
+</script>
+<script type="mpy-editor" env="shared">
+  # doubled a
+  print(a * 2)
+</script>
+```
+
+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);"/>
+
+!!! info
+
+    Notice that the interpreter type, and optional environment name is shown
+    at the top right above the Python editor.
+
+    Hovering over the Python editor reveals the "run" button.
+
+Finally, the `target` attribute allows you to specify a node into which the
+editor will be rendered:
+
+```html title="Specify a target for the Python editor."
+<script type="mpy-editor" target="editor">
+  import sys
+  print(sys.version)
+</script>
+<div id="editor"></div> <!-- will eventually contain the Python editor -->
+```
diff --git a/docs/user-guide/examples.md b/docs/user-guide/examples.md
@@ -1,3 +1,22 @@
 # Example applications
 
-** TODO: fill this with references and descriptions to examples on PyScript.com **
+A curated list of example applications that demonstrate various features of
+PyScript can be found [on PyScript.com](https://pyscript.com/@examples).
+
+The examples are (links take you to the code):
+
+* [Hello world](https://pyscript.com/@examples/hello-world/latest)
+* [A simple clock](https://pyscript.com/@examples/simple-clock/latest)
+* [Simple slider panel](https://pyscript.com/@examples/simple-panel/latest)
+* [Streaming data panel](https://pyscript.com/@examples/streaming-in-panel/latest)
+* [WebGL Icosahedron](https://pyscript.com/@examples/webgl-icosahedron/latest)
+* [KMeans in a panel](https://pyscript.com/@examples/kmeans-in-panel/latest)
+* [New York Taxi panel (WebGL)](https://pyscript.com/@examples/nyc-taxi-panel-deckgl/latest)
+* [Pandas dataframe fun](https://pyscript.com/@examples/pandas/latest)
+* [Matplotlib example](https://pyscript.com/@examples/matplotlib/latest)
+* [Numpy fractals](https://pyscript.com/@examples/fractals-with-numpy-and-canvas/latest)
+* [Folium geographical data](https://pyscript.com/@examples/folium/latest)
+* [Bokeh data plotting](https://pyscript.com/@examples/bokeh/latest)
+* [Import antigravity](https://pyscript.com/@examples/antigravity/latest)
+* [Altair data plotting](https://pyscript.com/@examples/altair/latest)
+
diff --git a/docs/user-guide/features.md b/docs/user-guide/features.md
@@ -3,11 +3,11 @@
 <dl>
     <dt><em>All the web</em></dt>
     <dd>
-    <p>Pyscript gives you <a href="#the-dom">full access to the DOM</a> and all
+    <p>Pyscript gives you <a href="../dom">full access to the DOM</a> and all
     the <a href="https://developer.mozilla.org/en-US/docs/Web/API">web
     APIs implemented by your browser</a>.</p>
 
-    <p>Thanks to the <a href="#ffi">foreign
+    <p>Thanks to the <a href="../dom#ffi">foreign
     function interface</a> (FFI), Python just works with all the browser has to
     offer, including any third party JavaScript libraries that may be included
     in the page.</p>
@@ -19,10 +19,10 @@
     <dd>
     <p>PyScript brings you two Python interpreters:</p>
     <ol>
-        <li><a href="#pyodide">Pyodide</a> - the original standard
+        <li><a href="../architecture#pyodide">Pyodide</a> - the original standard
         CPython interpreter you know and love, but compiled to WebAssembly.
         </li>
-        <li><a href="#micropython">MicroPython</a> - a lean and
+        <li><a href="../architecture#micropython">MicroPython</a> - a lean and
         efficient reimplementation of Python3 that includes a comprehensive
         subset of the standard library, compiled to WebAssembly.</li>
     </ol>
@@ -38,7 +38,7 @@
     library and efficiently exposes the expressiveness of Python to the
     browser.</p>
     <p>Both Python interpreters supported by PyScript implement the
-    <a href="#ffi">same FFI</a> to bridge the gap between the worlds of Python
+    <a href="../dom#ffi">same FFI</a> to bridge the gap between the worlds of Python
     and the browser.</p>
     </dd>
 
@@ -62,15 +62,15 @@
     expensive and blocking computation can run somewhere other than the main
     application thread controlling the user interface. When such work is done
     on the main thread, the browser appears frozen; web workers ensure
-    expensive blocking computation <a href="#workers">happens elsewhere</a>.
+    expensive blocking computation <a href="../workers">happens elsewhere</a>.
     Think of workers as independent subprocesses in your web page.</dd>
 
     <dt><em>Rich and powerful plugins</em></dt>
     <dd>
     <p>PyScript has a small, efficient yet powerful core called
     <a href="https://github.com/pyscript/polyscript">PolyScript</a>. Most of
     the functionality of PyScript is actually implemented through PolyScript's
-    <a href="#plugins_1">plugin system</a>.</p>
+    <a href="../plugins">plugin system</a>.</p>
 
     <p>This approach ensures a clear separation of concerns: PolyScript
     can focus on being small, efficient and powerful, whereas the PyScript

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/2023.11.2/core.css">
+        <link rel="stylesheet" href="https://pyscript.net/releases/2023.12.1/core.css">
         <!-- This script tag bootstraps PyScript -->
-        <script type="module" src="https://pyscript.net/releases/2023.11.2/core.js"></script>
+        <script type="module" src="https://pyscript.net/releases/2023.12.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/2023.11.2/core.js";
+import { hooks } from "https://pyscript.net/releases/2023.12.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/docs/user-guide/terminal.md b/docs/user-guide/terminal.md
@@ -45,10 +45,17 @@ name = input("What is your name? ")
 print(f"Hello, {name}")
 </script>
 ```
+<img src="../../assets/images/pyterm2.gif" style="border: 1px solid black; border-radius: 0.2rem; box-shadow: var(--md-shadow-z1);"/>
 
-Once the Python code has finished you are automatically dropped into the
-Python REPL, like this:
+To use the interactive Python REPL in the terminal, use Python's
+[code](https://docs.python.org/3/library/code.html) module like this:
 
-<img src="../../assets/images/pyterm2.gif" style="border: 1px solid black; border-radius: 0.2rem; box-shadow: var(--md-shadow-z1);"/>
+```python
+import code
+
+code.interact()
+```
 
+The end result should look something like this:
 
+<img src="../../assets/images/pyterm3.gif" style="border: 1px solid black; border-radius: 0.2rem; box-shadow: var(--md-shadow-z1);"/>
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -75,5 +75,6 @@ nav:
     - Workers: user-guide/workers.md
     - Builtin helpers: user-guide/builtins.md
     - Python terminal: user-guide/terminal.md
+    - Python editor: user-guide/editor.md
     - Plugins: user-guide/plugins.md
     - Example apps: user-guide/examples.md
diff --git a/version.json b/version.json
@@ -1,3 +1,3 @@
 {
-    "version": "2023.11.2"
+    "version": "2023.12.1"
 }