jprdonnelly/pyscript
1
0
Fork 0
mirror of https://github.com/pyscript/pyscript.git synced 2025-12-19 18:27:29 -05:00
Code Issues Projects Releases Wiki Activity

Add three new tutorials and small tweaks to docs (#972)

Browse Source
This commit is contained in:
Fábio Rosado
2022-11-24 10:53:22 +00:00
committed by GitHub
parent cafebd68f2
commit 06df21e8e3
9 changed files with 562 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
docs/error.md Normal file
View File

@@ -0,0 +1,3 @@
# Not found!
The page that you looked for could not be found. If you think this is a mistake, please [open an issue](https://github.com/pyscript/pyscript/issues/new/)

14
docs/reference/elements/py-config.md
View File

@@ -1,6 +1,6 @@
# <py-config> # <py-config>
Use the `<py-config>` tag to set and configure general metadata along with declaring dependencies for your PyScript application. The configuration has to be set in either [TOML](https://toml.io/) or [JSON](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Objects/JSON) format. Use the `<py-config>` tag to set and configure general metadata along with declaring dependencies for your PyScript application. The configuration has to be set in either [TOML](https://toml.io/)(default) or [JSON](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Objects/JSON) format.
The `<py-config>` element should be placed within the `<body>` element. The `<py-config>` element should be placed within the `<body>` element.
@@ -14,6 +14,11 @@ The `<py-config>` element should be placed within the `<body>` element.
## Examples ## Examples
- `<py-config>` using TOML (default) - `<py-config>` using TOML (default)
```{note}
Reminder: when using TOML, any Arrays of Tables defined with double-brackets (like `[[runtimes]]` and `[[fetch]]` must come after individual keys (like `paths = ...` and `packages=...`)
```
```html ```html
<py-config> <py-config>
autoclose_loader = true autoclose_loader = true
@@ -24,7 +29,6 @@ The `<py-config>` element should be placed within the `<body>` element.
lang = "python" lang = "python"
</py-config> </py-config>
``` ```
Note: `[[runtimes]]` is a TOML table. Make sure this is the last item within a py-config, as the properties created after it go into the runtimes object.
- JSON config using the `type` attribute. - JSON config using the `type` attribute.
```html ```html
@@ -204,6 +208,8 @@ In the HTML tag `<py-config>`, paths to local modules are provided in the
</html> </html>
``` ```
## Supported configuration values
The following optional values are supported by `<py-config>`: The following optional values are supported by `<py-config>`:
| Value | Type | Description | | Value | Type | Description |
| ------ | ---- | ----------- | | ------ | ---- | ----------- |
@@ -221,6 +227,8 @@ The following optional values are supported by `<py-config>`:
| `plugins` | List of Plugins | List of Plugins are to be specified here. The default value is an empty list. | | `plugins` | List of Plugins | List of Plugins are to be specified here. The default value is an empty list. |
| `runtimes` | List of Runtimes | List of runtime configurations, described below. The default value contains a single Pyodide based runtime. | | `runtimes` | List of Runtimes | List of runtime configurations, described below. The default value contains a single Pyodide based runtime. |
### Fetch
A fetch configuration consists of the following: A fetch configuration consists of the following:
| Value | Type | Description | | Value | Type | Description |
| ----- | ---- | ----------- | | ----- | ---- | ----------- |
@@ -231,6 +239,8 @@ A fetch configuration consists of the following:
The parameters `to_file` and `files` shouldn't be supplied together. The parameters `to_file` and `files` shouldn't be supplied together.
### Runtime
A runtime configuration consists of the following: A runtime configuration consists of the following:
| Value | Type | Description | | Value | Type | Description |
| ----- | ---- | ----------- | | ----- | ---- | ----------- |

3
docs/tutorials/deployment.md
View File

@@ -1,3 +0,0 @@
# Deployment
**Coming soon!**

62
docs/tutorials/getting-started.md
View File

@@ -150,7 +150,11 @@ Use the `<py-config>` tag to set and configure general metadata along with decla
The ideal place to use `<py-config>` in between the `<body>...</body>` tags. The ideal place to use `<py-config>` in between the `<body>...</body>` tags.
The `<py-config>` tag can be used as follows: By default the `py-config` tag is set to TOML and can be used as follows:
```{note}
Reminder: when using TOML, any Arrays of Tables defined with double-brackets (like `[[runtimes]]` and `[[fetch]]` must come after individual keys (like `paths=...` and `packages=...`)
```
```html ```html
<py-config> <py-config>
@@ -162,7 +166,6 @@ The `<py-config>` tag can be used as follows:
lang = "python" lang = "python"
</py-config> </py-config>
``` ```
Note: `[[runtimes]]` is a TOML table. Make sure this is the last item within a py-config, as the properties created after it go into the runtimes object.
Alternatively, a JSON config can be passed using the `type` attribute. Alternatively, a JSON config can be passed using the `type` attribute.
@@ -297,6 +300,28 @@ as a shortcut, which takes the expression on the last line of the script and run
</html> </html>
``` ```
Besides the above format, a user can also supply any extra keys and values that are relevant as metadata information or perhaps are being used within the application.
For example, a valid config could also be with the snippet below:
```
<py-config type="toml">
magic = "unicorn"
</py-config>
```
OR in JSON like
```
<py-config type="json">
{
"magic": "unicorn"
}
</py-config>
```
If this `"magic"` key is present in config supplied via `src` and also present in config supplied via `inline`, then the value in the inline config is given priority i.e. the overriding process also works for custom keys.
### Local modules ### Local modules
In addition to packages, you can declare local Python modules that will In addition to packages, you can declare local Python modules that will
@@ -343,6 +368,8 @@ In the HTML tag `<py-config>`, paths to local modules are provided in the
</html> </html>
``` ```
### Supported configuration values
The following optional values are supported by `<py-config>`: The following optional values are supported by `<py-config>`:
| Value | Type | Description | | Value | Type | Description |
| ------ | ---- | ----------- | | ------ | ---- | ----------- |
@@ -360,7 +387,10 @@ The following optional values are supported by `<py-config>`:
| `plugins` | List of Plugins | List of Plugins are to be specified here. The default value is an empty list. | | `plugins` | List of Plugins | List of Plugins are to be specified here. The default value is an empty list. |
| `runtimes` | List of Runtimes | List of runtime configurations, described below. The default value contains a single Pyodide based runtime. | | `runtimes` | List of Runtimes | List of runtime configurations, described below. The default value contains a single Pyodide based runtime. |
#### Fetch
A fetch configuration consists of the following: A fetch configuration consists of the following:
| Value | Type | Description | | Value | Type | Description |
| ----- | ---- | ----------- | | ----- | ---- | ----------- |
| `from` | string | Base URL for the resource to be fetched. | | `from` | string | Base URL for the resource to be fetched. |
@@ -368,7 +398,13 @@ A fetch configuration consists of the following:
| `to_file` | string | Name of the target to create in the filesystem. | | `to_file` | string | Name of the target to create in the filesystem. |
| `files` | List of string | List of files to be downloaded. | | `files` | List of string | List of files to be downloaded. |
```{note}
The parameters `to_file` and `files` shouldn't be supplied together. The parameters `to_file` and `files` shouldn't be supplied together.
```
You may be interested in reading the [tutorial on fetching resources](./py-config-fetch.md) to learn more about this feature.
#### Runtime
A runtime configuration consists of the following: A runtime configuration consists of the following:
| Value | Type | Description | | Value | Type | Description |
@@ -377,27 +413,7 @@ A runtime configuration consists of the following:
| `name` | string | Name of the runtime. This field can be any string and is to be used by the application author for their own customization purposes | | `name` | string | Name of the runtime. This field can be any string and is to be used by the application author for their own customization purposes |
| `lang` | string | Programming language supported by the runtime. This field can be used by the application author to provide clarification. It currently has no implications on how PyScript behaves. | | `lang` | string | Programming language supported by the runtime. This field can be used by the application author to provide clarification. It currently has no implications on how PyScript behaves. |
Besides the above format, a user can also supply any extra keys and values that are relevant as metadata information or perhaps are being used within the application. You may be interested in reading the [tutorial on setting a runtime](./py-config-runtime.md) to learn more about this feature.
For example, a valid config could also be with the snippet below:
```
<py-config type="toml">
magic = "unicorn"
</py-config>
```
OR in JSON like
```
<py-config type="json">
{
"magic": "unicorn"
}
</py-config>
```
If this `"magic"` key is present in config supplied via `src` and also present in config supplied via `inline`, then the value in the inline config is given priority i.e. the overriding process also works for custom keys.
## The py-repl tag ## The py-repl tag

5
docs/tutorials/index.md
View File

@@ -7,6 +7,7 @@ This is the tutorials section for beginners.
maxdepth: 2 maxdepth: 2
--- ---
getting-started getting-started
deployment py-config-fetch
setup py-config-runtime
writing-to-page
``` ```

205
docs/tutorials/py-config-fetch.md Normal file
View File

@@ -0,0 +1,205 @@
# Using the fetch from py-config
This tutorial shows how to use the fetch configuration from `py-config` to fetch two files from a remote server, store them in a local directory, and verify their contents.
## Development setup
We will create a todo list application similar to the one in the [examples](https://pyscript.net/examples/todo.html). To do this, we need three things:
* An `index.html` file containing the HTML for the application.
* A `todo.py` file containing the Python code for the application.
* A `utils.py` file containing some utility functions for the application.
We will use the `fetch` configuration from `py-config` to fetch these files from a remote server and store them in a local directory.
### Creating the html file
In this first step, we will create the `index.html` file and import both `pyscript.css` and `pyscript.js`. These are needed to run our Python code in the browser and style the application.
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width,initial-scale=1" />
<title>My Todo</title>
<link rel="stylesheet" href="https://pyscript.net/latest/pyscript.css" />
<script defer src="https://pyscript.net/latest/pyscript.js"></script>
</head>
<body>
</body>
</html>
```
## Fetching the files
### Using `fetch` to get the python files
Now we will use the `fetch` configuration from `py-config` to fetch the `todo.py` and `utils.py` files from a remote server and store them in a local directory called `todo`. Here we will fetch files from different URLs, using a `fetch` per item.
Also, remember when we said that we needed three things? We actually need four things. We also need
to fetch `pyscript.py` because we will use the `Element` class to interact with the DOM.
```{note}
We are not going into in-depth as to why we need to fetch `pyscript.py` here. The short version is that PyScript isn't installed in the filesystem when we fetch the files.
```
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width,initial-scale=1" />
<title>My Todo</title>
<link rel="stylesheet" href="https://pyscript.net/latest/pyscript.css" />
<script defer src="https://pyscript.net/latest/pyscript.js"></script>
</head>
<body>
<py-config>
[[fetch]]
from = "https://raw.githubusercontent.com/pyscript/pyscript/main/pyscriptjs/src/python/"
files = ["pyscript.py"]
[[fetch]]
from = "https://pyscript.net/examples/"
files = ["utils.py"]
[[fetch]]
from = "https://gist.githubusercontent.com/FabioRosado/faba0b7f6ad4438b07c9ac567c73b864/raw/37603b76dc7ef7997bf36781ea0116150f727f44/"
files = ["todo.py"]
</py-config>
</body>
</html>
```
## Creating a todo application
### Creating the todo elements
Now we will create the todo elements in the `body` of the `index.html` file.
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width,initial-scale=1" />
<title>My Todo</title>
<link rel="stylesheet" href="https://pyscript.net/latest/pyscript.css" />
<script defer src="https://pyscript.net/latest/pyscript.js"></script>
</head>
<body>
<py-config>
[[fetch]]
from = "https://raw.githubusercontent.com/pyscript/pyscript/main/pyscriptjs/src/python/"
files = ["pyscript.py"]
[[fetch]]
from = "https://pyscript.net/examples/"
files = ["utils.py"]
[[fetch]]
from = "https://gist.githubusercontent.com/FabioRosado/faba0b7f6ad4438b07c9ac567c73b864/raw/37603b76dc7ef7997bf36781ea0116150f727f44/"
files = ["todo.py"]
</py-config>
<section>
<div class="text-center w-full mb-8">
<h1 class="text-3xl font-bold text-gray-800 uppercase tracking-tight">To Do List</h1>
</div>
<div>
<input id="new-task-content" class="py-input" type="text">
<button id="new-task-btn" class="py-button" type="submit" py-click="add_task()">
Add task
</button>
</div>
<div id="list-tasks-container" class="flex flex-col-reverse mt-4"></div>
<template id="task-template">
<section class="task py-li-element">
<label for="flex items-center p-2 ">
<input class="mr-2" type="checkbox">
<p class="m-0 inline"></p>
</label>
</section>
</template>
</section>
</body>
</html>
```
Our todo application is starting to shape up, although if you try to add any tasks, you will notice that nothing happens. This is because we have not yet imported the `todo.py` file.
### Importing the needed functions from `todo.py`
This is where the magic happens. We can import the `todo.py` file by adding it as a source to the `py-script` tag. By specifying the file, pyscript will automatically import the file and run the code in it.
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width,initial-scale=1" />
<title>My Todo</title>
<link rel="stylesheet" href="https://pyscript.net/latest/pyscript.css" />
<script defer src="https://pyscript.net/latest/pyscript.js"></script>
</head>
<body>
<py-config>
[[fetch]]
from = "https://raw.githubusercontent.com/pyscript/pyscript/main/pyscriptjs/src/python/"
files = ["pyscript.py"]
[[fetch]]
from = "https://pyscript.net/examples/"
files = ["utils.py"]
[[fetch]]
from = "https://gist.githubusercontent.com/FabioRosado/faba0b7f6ad4438b07c9ac567c73b864/raw/37603b76dc7ef7997bf36781ea0116150f727f44/"
files = ["todo.py"]
</py-config>
<py-script>
from todo import add_task, add_task_event
</py-script>
<section>
<div class="text-center w-full mb-8">
<h1 class="text-3xl font-bold text-gray-800 uppercase tracking-tight">To Do List</h1>
</div>
<div>
<input id="new-task-content" class="py-input" type="text">
<button id="new-task-btn" class="py-button" type="submit" py-click="add_task()">
Add task
</button>
</div>
<div id="list-tasks-container" class="flex flex-col-reverse mt-4"></div>
<template id="task-template">
<section class="task py-li-element">
<label for="flex items-center p-2 ">
<input class="mr-2" type="checkbox">
<p class="m-0 inline"></p>
</label>
</section>
</template>
</section>
</body>
</html>
```
You can now save the file and refresh the page. You should now be able to add tasks to your todo list.
## That's it!
You have now created a todo application using pyscript. You can add tasks and mark them as done. Let's take a recap of what we have achieved:
* We have imported three separate files into our `index.html` file using the `py-config` tag.
* We have created the necessary HTML code to create our todo's
* We have imported functions from the `todo.py` file, using the `py-script` tag.
For reference, the code from [the gist](https://gist.githubusercontent.com/FabioRosado/faba0b7f6ad4438b07c9ac567c73b864/raw/37603b76dc7ef7997bf36781ea0116150f727f44/todo.py) is the same code that our [todo example](https://pyscript.net/examples/todo.html) uses with a slight change of importing `Element` from `pyscript`.

88
docs/tutorials/py-config-runtime.md Normal file
View File

@@ -0,0 +1,88 @@
# Setting a pyodide runtime
Pyscript will automatically set the runtime for you, but you can also set it manually. This is useful if you want to use a different version than the one set by default.
## Development setup
To get started, let's create a new `index.html` file and import `pyscript.js`.
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width,initial-scale=1" />
<title>Runtime</title>
<link rel="stylesheet" href="https://pyscript.net/latest/pyscript.css" />
<script defer src="https://pyscript.net/latest/pyscript.js"></script>
</head>
<body>
</body>
</html>
```
We are using the pyodide CDN to setup our runtime, but you can also download the files from [the pyodide GitHub release](https://github.com/pyodide/pyodide/releases/tag/0.22.0a3), unzip them and use the `pyodide.js` file as your runtime.
## Setting the runtime
To set the runtime, you can use the `runtime` configuration in the `py-config` element. In this tutorial, we will use the default `TOML` format, but know that you can also use `json` if you prefer by changing the `type` attribute of the `py-config` element.
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width,initial-scale=1" />
<title>Runtime</title>
<link rel="stylesheet" href="https://pyscript.net/latest/pyscript.css" />
<script defer src="https://pyscript.net/latest/pyscript.js"></script>
</head>
<body>
<py-config>
[[runtimes]]
src = "https://cdn.jsdelivr.net/pyodide/v0.22.0a3/full/pyodide.js"
name = "pyodide-0.22.0a3"
lang = "python"
</py-config>
</body>
</html>
```
## Confirming the runtime version
To confirm that the runtime is set correctly, you can open the DevTools and check the version from the console. But for the sake of this tutorial, let's create a `py-script` tag and print pyodide's version.
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width,initial-scale=1" />
<title>Runtime</title>
<link rel="stylesheet" href="https://pyscript.net/latest/pyscript.css" />
<script defer src="https://pyscript.net/latest/pyscript.js"></script>
</head>
<body>
<py-config>
[[runtimes]]
src = "https://cdn.jsdelivr.net/pyodide/v0.22.0a3/full/pyodide.js"
name = "pyodide-0.22.0a3"
lang = "python"
</py-config>
<py-script>
import pyodide
print(pyodide.__version__)
</py-script>
</body>
</html>
```

3
docs/tutorials/setup.md
View File

@@ -1,3 +0,0 @@
# Setup
**Coming soon!**

212
docs/tutorials/writing-to-page.md Normal file
View File

@@ -0,0 +1,212 @@
# How to write content to the page
When creating your PyScript application, you will want to write content to the page. This tutorial will explore the different methods you can use to write content to the page and their differences.
## Development setup
To get started, we will create an `index.html` file, import PyScript and start building on top of it.
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width,initial-scale=1" />
<title>Writing to the page</title>
<link rel="stylesheet" href="https://pyscript.net/latest/pyscript.css" />
<script defer src="https://pyscript.net/latest/pyscript.js"></script>
</head>
<body>
</body>
</html>
```
## Writing content to an element
Let's first see how we can write content to an element on the page. We will start by creating a `div` element with an `id` of `manual-write`, then create a `py-script` tag that, upon a click of a button, will write 'Hello World' to the `div` element.
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width,initial-scale=1" />
<title>Writing to the page</title>
<link rel="stylesheet" href="https://pyscript.net/latest/pyscript.css" />
<script defer src="https://pyscript.net/latest/pyscript.js"></script>
</head>
<body>
<div id="manual-write"></div>
<button py-click="write_to_page()" id="manual">Say Hello</button>
<py-script>
def write_to_page():
manual_div = Element("manual-write")
manual_div.element.innerText = "Hello World"
</py-script>
</body>
</html>
```
```{note}
When using `py-click` you must supply an `id` to the element you want to use as the trigger.
```
We can now open our `index.html` file and click the button. You will see that "Hello World" will appear in the `div` element. You could also write HTML using `manual_div.element.innerHTML` instead of `innerText`. For example:
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width,initial-scale=1" />
<title>Writing to the page</title>
<link rel="stylesheet" href="https://pyscript.net/latest/pyscript.css" />
<script defer src="https://pyscript.net/latest/pyscript.js"></script>
</head>
<body>
<div id="manual-write"></div>
<button py-click="write_to_page()" id="manual">Say Hello</button>
<py-script>
def write_to_page():
manual_div = Element("manual-write")
manual_div.element.innerHTML = "<p><b>Hello World</b></p>"
</py-script>
</body>
</html>
```
## Writing content with the `display` API
The `display` API is a simple way to write content to the page. Not only does it allow you to write content to the page, but it also allows you to display a range of different content types such as images, markdown, svgs, json, etc.
Using the' display' API, let's reuse our previous example and write "Hello World" to the page.
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width,initial-scale=1" />
<title>Writing to the page</title>
<link rel="stylesheet" href="https://pyscript.net/latest/pyscript.css" />
<script defer src="https://pyscript.net/latest/pyscript.js"></script>
</head>
<body>
<div id="manual-write"></div>
<button py-click="write_to_page()" id="manual">Say Hello</button>
<div id="display-write"></div>
<button py-click="display_to_div()" id="display">Say Things!</button>
<py-script>
def write_to_page():
manual_div = Element("manual-write")
manual_div.element.innerHTML = "<p><b>Hello World</b></p>"
def display_to_div():
display("I display things!", target="display-write")
</py-script>
</body>
</html>
```
```{note}
When using the `display` API, you must specify the `target` parameter to tell PyScript where to write the content. If you do not use this parameter, an error will be thrown.
```
You may be interested in reading more about the `display` API in the [Display API](../reference/api/display) section of the documentation.
## Printing to the page
We couldn't have a tutorial on writing to the page without mentioning the `print` function. The `print` function is a simple way to write content to the page, that any Python developer will be familiar with. When you use the `print` function, the content will be written to the page in a `py-terminal` element.
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width,initial-scale=1" />
<title>Writing to the page</title>
<link rel="stylesheet" href="https://pyscript.net/latest/pyscript.css" />
<script defer src="https://pyscript.net/latest/pyscript.js"></script>
</head>
<body>
<div id="manual-write"></div>
<button py-click="write_to_page()" id="manual">Say Hello</button>
<div id="display-write"></div>
<button py-click="display_to_div()" id="display">Say Things!</button>
<button py-click="print_to_page()" id="print">Print Things!</button>
<py-script>
def write_to_page():
manual_div = Element("manual-write")
manual_div.element.innerHTML = "<p><b>Hello World</b></p>"
def display_to_div():
display("I display things!", target="display-write")
def print_to_page():
print("I print things!")
</py-script>
</body>
</html>
```
You may be surprised to see that when you click the "Print Things!" button, the content is written below the rest of the elements on the page in a black canvas. This is because the `print` function writes content to the page in a `py-terminal` element. You can read more about the `py-terminal` element in the [Terminal Element](../reference/plugins/py-terminal) section of the documentation.
PyScript comes with the `py-terminal` plugin by default and any `stdout` or `stderr` content will be shown in this element. We can be explicit about where we want the terminal to be shown by adding the `<py-terminal>` tag to our HTML.
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width,initial-scale=1" />
<title>Writing to the page</title>
<link rel="stylesheet" href="https://pyscript.net/latest/pyscript.css" />
<script defer src="https://pyscript.net/latest/pyscript.js"></script>
</head>
<body>
<div id="manual-write"></div>
<button py-click="write_to_page()" id="manual">Say Hello</button>
<div id="display-write"></div>
<button py-click="display_to_div()" id="display">Say Things!</button>
<div>
<py-terminal>
</div>
<button py-click="print_to_page()" id="print">Print Things!</button>
<py-script>
def write_to_page():
manual_div = Element("manual-write")
manual_div.element.innerHTML = "<p><b>Hello World</b></p>"
def display_to_div():
display("I display things!", target="display-write")
def print_to_page():
print("I print things!")
</py-script>
</body>
</html>
```