From 4337e6833a6be1701828a2b606afe4972cb30eda Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?F=C3=A1bio=20Rosado?= Date: Tue, 6 Dec 2022 13:47:08 +0000 Subject: [PATCH] Rewrite the get started tutorial using the ice cream demo (#985) * Rewrite the get started tutorial using the ice cream demo * Update docs/tutorials/getting-started.md Co-authored-by: Antonio Cuni * Address Antonio's comments Co-authored-by: Antonio Cuni --- docs/reference/elements/py-config.md | 15 +- docs/reference/elements/py-script.md | 71 +++- docs/tutorials/getting-started.md | 573 ++++++++++----------------- 3 files changed, 274 insertions(+), 385 deletions(-) diff --git a/docs/reference/elements/py-config.md b/docs/reference/elements/py-config.md index 4b759ca1..7a4a275b 100644 --- a/docs/reference/elements/py-config.md +++ b/docs/reference/elements/py-config.md @@ -2,6 +2,8 @@ Use the `` 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. +If you are unfamiliar with TOML, consider [reading about it](https://learnxinyminutes.com/docs/toml/) or if you are unfamiliar with JSON, consider reading [freecodecamp's JSON for beginners](https://www.freecodecamp.org/news/what-is-json-a-json-file-example/) guide for more information. + The `` element should be placed within the `` element. ## Attributes @@ -13,8 +15,7 @@ The `` element should be placed within the `` element. ## Examples -- `` using TOML (default) - +### `` 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=...`) ``` @@ -30,7 +31,8 @@ Reminder: when using TOML, any Arrays of Tables defined with double-brackets (li ``` -- JSON config using the `type` attribute. +### JSON config using the `type` attribute. + ```html { @@ -44,7 +46,8 @@ Reminder: when using TOML, any Arrays of Tables defined with double-brackets (li ``` -- Use of the `src` attribute: +### Use of the `src` attribute: + ```html ``` @@ -58,7 +61,7 @@ name = "pyodide-0.21.2" lang = "python" ``` -- JSON using the `type` attribute. +### JSON using the `type` and `src` attribute. ```html ``` @@ -75,6 +78,8 @@ where `custom.json` contains } ``` +### Expanding with inline configuration + One can also use both i.e pass the config from `src` attribute as well as specify it as `inline`. So the following snippet is also valid: ```html diff --git a/docs/reference/elements/py-script.md b/docs/reference/elements/py-script.md index 964df0cd..10d774b2 100644 --- a/docs/reference/elements/py-script.md +++ b/docs/reference/elements/py-script.md @@ -10,7 +10,10 @@ The `` element lets you execute multi-line Python scripts both inline ## Examples -- Inline `` element: +### Inline `` element: + +Let's execute this multi-line Python script to compute π and print it back onto the page + ```html @@ -34,19 +37,75 @@ The `` element lets you execute multi-line Python scripts both inline ``` -- `` element with `src` attribute: +### Using `` element with `src` attribute: + +we can also move our python code to its own file and reference it via the `src` attribute. + + +```python +# compute_pi.py +print("Let's compute π:") +def compute_pi(n): + pi = 2 + for i in range(1,n): + pi *= 4 * i ** 2 / (4 * i ** 2 - 1) + return pi + +pi = compute_pi(100000) +s = f"π is approximately {pi:.3f}" +print(s) +``` + +Since both compute_pi.py and index.html are in the same directory, we can reference the python file with a relative path. + ```html - - [[fetch]] - files =["compute_pi.py"] - ``` + +### Writing into labeled elements + +In the example above, we had a single `` tag printing +one or more lines onto the page in order. Within the ``, you can +use the `Element` class to create a python object for interacting with +page elements. Objects created from the `Element` class provide the `.write()` method +which enables you to send strings into the page elements referenced by those objects. + +For example, we'll add some style elements and provide placeholders for +the `` tag to write to. + +```html + + + + + + + + +

Today is

+
+
+ + import datetime as dt + Element('today').write(dt.date.today().strftime('%A %B %d, %Y')) + + def compute_pi(n): + pi = 2 + for i in range(1,n): + pi *= 4 * i ** 2 / (4 * i ** 2 - 1) + return pi + + pi = compute_pi(100000) + Element('pi').write(f'π is approximately {pi:.3f}') + + + +``` diff --git a/docs/tutorials/getting-started.md b/docs/tutorials/getting-started.md index ea16d88e..c796a179 100644 --- a/docs/tutorials/getting-started.md +++ b/docs/tutorials/getting-started.md @@ -5,46 +5,12 @@ This page will guide you through getting started with PyScript. ## Development setup PyScript does not require any development environment other -than a web browser (we recommend using [Chrome](https://www.google.com/chrome/)) and a text editor, even though using your [IDE](https://en.wikipedia.org/wiki/Integrated_development_environment) of choice might be convenient. +then a web browser (we recommend using [Chrome](https://www.google.com/chrome/)) and a text editor, even though using your [IDE](https://en.wikipedia.org/wiki/Integrated_development_environment) of choice might be convenient. If you're using [VSCode](https://code.visualstudio.com/), the [Live Server extension](https://marketplace.visualstudio.com/items?itemName=ritwickdey.LiveServer) can be used to reload the page as you edit the HTML file. -## Trying before installing - -If you're new to programming and know nothing about HTML or just want to try some of PyScript features, we recommend using the [REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop) element in the [PyScript REPL example](https://pyscript.net/examples/repl.html) instead so you can have a programming experience in a REPL that doesn't require any setup. This REPL can be used to have an interactive experience using Python directly. - - Alternatively, you can also use an online editor like W3School's [TryIt Editor](https://www.w3schools.com/html/tryit.asp?filename=tryhtml_default_default) and just plug the code below into it, as shown in the [example](https://docs.pyscript.net/latest/concepts/what-is-pyscript.html#example) page and click the run button. - -```html - - - - - - - REPL - - - - - - - - Hello world!
- This is the current date and time, as computed by Python: - -from datetime import datetime -now = datetime.now() -now.strftime("%m/%d/%Y, %H:%M:%S") - - - -``` - -You could try changing the code above to explore and play with pyscript yourself. - ## Installation There is no installation required. In this document, we'll use @@ -68,376 +34,235 @@ open an HTML by double-clicking it in your file explorer. - print('Hello, World!') + + + print('Hello, World!') + + ``` -Notice the use of the `` tag in the HTML body. This -is where you'll write your Python code. In the following sections, we'll -introduce the eight tags provided by PyScript. +## A more complex example -## The py-script tag +Now that we know how you can create a simple 'Hello, World!' example, let's see a more complex example. This example will use the Demo created by [Cheuk Ting Ho](https://github.com/Cheukting). In this example, we will use more features from PyScript. -The `` tag lets you execute multi-line Python scripts and -print back onto the page. For example, we can compute π. +### Setting up the base index file + +Let's create a new file called `index.html` and add the following content: ```html + Ice Cream Picker + - - print("Let's compute π:") - def compute_pi(n): - pi = 2 - for i in range(1,n): - pi *= 4 * i ** 2 / (4 * i ** 2 - 1) - return pi - pi = compute_pi(100000) - s = f"π is approximately {pi:.3f}" - print(s) - ``` -### Writing into labeled elements +In this first step, we have created the index file, imported `pyscript.css` and `pyscript.js`. We are ready to start adding the elements we need for our application. -In the example above, we had a single `` tag printing -one or more lines onto the page in order. Within the ``, you can -use the `Element` class to create a python object for interacting with -page elements. Objects created from the `Element` class provide the `.write()` method -which enables you to send strings into the page elements referenced by those objects. +### Importing the needed libraries -For example, we'll add some style elements and provide placeholders for -the `` tag to write to. +For this example, we will need to install `pandas` and `matplotlib`. We can install libraries using the `` tag so we can import them later. Please refer to the [``](../reference/elements/py-config.md) documentation for more information. -```html - - - - - - - - -

Today is

-
-
- - import datetime as dt - Element('today').write(dt.date.today().strftime('%A %B %d, %Y')) - - def compute_pi(n): - pi = 2 - for i in range(1,n): - pi *= 4 * i ** 2 / (4 * i ** 2 - 1) - return pi - - pi = compute_pi(100000) - Element('pi').write(f'π is approximately {pi:.3f}') - - - -``` - -## The py-config tag - -Use the `` tag to set and configure general metadata along with declaring dependencies for your PyScript application. The configuration has to be set in either TOML or JSON format. If you are unfamiliar with JSON, consider reading [freecodecamp's JSON for beginners](https://www.freecodecamp.org/news/what-is-json-a-json-file-example/) guide for more information. And for TOML, consider reading about it [here](https://learnxinyminutes.com/docs/toml/). - -The ideal place to use `` in between the `...` tags. - -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 - - autoclose_loader = true - - [[runtimes]] - src = "https://cdn.jsdelivr.net/pyodide/v0.21.3/full/pyodide.js" - name = "pyodide-0.21.3" - lang = "python" - -``` - -Alternatively, a JSON config can be passed using the `type` attribute. - -```html - - { - "autoclose_loader": true, - "runtimes": [{ - "src": "https://cdn.jsdelivr.net/pyodide/v0.21.3/full/pyodide.js", - "name": "pyodide-0.21.3", - "lang": "python" - }] - } - -``` - -Besides passing the config as inline (as shown above), one can also pass it with the `src` attribute. This is demonstrated below: - -``` - -``` - -where `custom.toml` contains - -``` -autoclose_loader = true -[[runtimes]] -src = "https://cdn.jsdelivr.net/pyodide/v0.21.3/full/pyodide.js" -name = "pyodide-0.21.3" -lang = "python" -``` - -This can also be done via JSON using the `type` attribute. By default, `type` is set to `"toml"` if not supplied. - -``` - -``` - -where `custom.json` contains - -``` -{ - "autoclose_loader": true, - "runtimes": [{ - "src": "https://cdn.jsdelivr.net/pyodide/v0.21.3/full/pyodide.js", - "name": "pyodide-0.21.3", - "lang": "python" - }] -} -``` - -One can also use both i.e pass the config from `src` attribute as well as specify it as `inline`. So the following snippet is also valid: - -``` - - [[fetch]] - files = ["./utils.py"] - -``` - -This can also be done via JSON using the `type` attribute. - -``` - - { - "fetch": [{ - "files": ["./utils.py"] - }] - } - -``` - -Note: While the `` tag supports both TOML and JSON, one cannot mix the type of config passed from 2 different sources i.e. the case when inline config is in TOML format while config from src is in JSON format is NOT allowed. Similarly for the opposite case. - ---- - -This is helpful in cases where a number of applications share a common configuration (which can be supplied via `src`), but their specific keys need to be customised and overridden. - -The keys supplied through `inline` override the values present in config supplied via `src`. - -One can also declare dependencies so as to get access to many 3rd party OSS packages that are supported by PyScript. -You can also link to `.whl` files directly on disk like in our [toga example](https://github.com/pyscript/pyscript/blob/main/examples/toga/freedom.html). - -``` - - packages = ["./static/wheels/travertino-0.1.3-py3-none-any.whl"] - -``` - -OR in JSON like - -``` - - { - "packages": ["./static/wheels/travertino-0.1.3-py3-none-any.whl"] - } - -``` - -If your `.whl` is not a pure Python wheel, then open a PR or issue with [pyodide](https://github.com/pyodide/pyodide) to get it added [here](https://github.com/pyodide/pyodide/tree/main/packages). - -If there's enough popular demand, the pyodide team will likely work on supporting your package. Regardless, things will likely move faster if you make the PR and consult with the team to get unblocked. - -For example, NumPy and Matplotlib are available. Notice here we're using `display(fig, target="plot")`, which takes the graph and displays it in the element with the id `plot`. - -```html - - - - - - - -

Let's plot random numbers

-
- - { - "packages": ["numpy", "matplotlib"] - } - - - import matplotlib.pyplot as plt - import numpy as np - x = np.random.randn(1000) - y = np.random.randn(1000) - fig, ax = plt.subplots() - ax.scatter(x, y) - display(fig, target="plot") - - - -``` - -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: - -``` - - magic = "unicorn" - -``` - -OR in JSON like - -``` - - { - "magic": "unicorn" - } - -``` - -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 - -In addition to packages, you can declare local Python modules that will -be imported in the `` tag. For example, we can place the random -number generation steps in a function in the file `data.py`. - -```python -# data.py -import numpy as np -def make_x_and_y(n): - x = np.random.randn(n) - y = np.random.randn(n) - return x, y -``` - -In the HTML tag ``, paths to local modules are provided in the -`files` key within the `fetch` section. - -```html - - - - - - - -

Let's plot random numbers

-
- - packages = ["numpy", "matplotlib"] - - [[fetch]] - files = ["./data.py"] - - - import matplotlib.pyplot as plt - from data import make_x_and_y - x, y = make_x_and_y(n=1000) - fig, ax = plt.subplots() - ax.scatter(x, y) - display(fig, target="plot") - - - -``` - -### Supported configuration values - -The following optional values are supported by ``: -| Value | Type | Description | -| ------ | ---- | ----------- | -| `name` | string | Name of the user application. This field can be any string and is to be used by the application author for their own customization purposes. | -| `description` | string | Description of the user application. This field can be any string and is to be used by the application author for their own customization purposes. | -| `version` | string | Version of the user application. This field can be any string and is to be used by the application author for their own customization purposes. It is not related to the PyScript version. | -| `schema_version` | number | The version of the config schema which determines what all keys are supported. This can be supplied by the user so PyScript knows what to expect in the config. If not supplied, the latest version for the schema is automatically used. | -| `type` | string | Type of the project. The default is an "app" i.e. a user application | -| `author_name` | string | Name of the author. | -| `author_email` | string | Email of the author. | -| `license` | string | License to be used for the user application. | -| `autoclose_loader` | boolean | If false, PyScript will not close the loading splash screen when the startup operations finish. | -| `packages` | List of Packages | Dependencies on 3rd party OSS packages are specified here. The default value is an empty list. | -| `fetch` | List of Stuff to fetch | Local Python modules OR resources from the internet are to be specified here using a Fetch Configuration, described below. 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. | - -#### Fetch - -A fetch configuration consists of the following: - -| Value | Type | Description | -| ----- | ---- | ----------- | -| `from` | string | Base URL for the resource to be fetched. | -| `to_folder` | string | Name of the folder 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. | - -```{note} -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: -| Value | Type | Description | -| ----- | ---- | ----------- | -| `src` | string (Required) | URL to the runtime source. | -| `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. | - -You may be interested in reading the [tutorial on setting a runtime](./py-config-runtime.md) to learn more about this feature. - -## The py-repl tag - -The `` tag creates a REPL component that is rendered to the page as a code editor, allowing you to write executable code inline. ```html + Ice Cream Picker + - + + + + packages = ["matplotlib", "pandas"] + + + ``` -## Visual component tags +### Importing the data and exploring -The following tags can be used to add visual attributes to your HTML page. +Now that we have installed the needed libraries, we can import and explore the data. In this step, we need to create a `` tag to import our dependencies, read the data with pandas and then use `py-repl` to explore the data. -| Tag | Description | -| --- | ----------- | -| `` | (Deprecated) Adds an input box that can be used to prompt users to enter input values. | -| `` | (Deprecated) Creates a container object that can be used to host one or more visual components that define how elements of `` should align and show on the page. | -| `` | (Deprecated) Adds a button to which authors can add labels and event handlers for actions on the button, such as `on_focus` or `on_click`. | -| `` | (Deprecated) Adds a static text title component that styles the text inside the tag as a page title. | +You may want to read the [``](../reference/elements/py-script.md) and [``](../reference/elements/py-repl.md) documentation for more information about these elements. -```{note} -These elements have been deprecated, we suggest that you use native elements and attach the respective `py-` attribute. For example for `` you can write `