2021-04-06 22:11:00 +00:00
|
|
|
|
(quickstart)=
|
2020-10-30 20:09:25 +00:00
|
|
|
|
|
2021-04-06 22:11:00 +00:00
|
|
|
|
# Getting started
|
2018-06-21 15:19:34 +00:00
|
|
|
|
|
2021-04-20 16:09:24 +00:00
|
|
|
|
## Try it online
|
|
|
|
|
|
|
2023-03-07 17:10:27 +00:00
|
|
|
|
Try Pyodide in a [REPL](../console.html){.external} directly in your browser
|
|
|
|
|
|
(no installation needed).
|
2021-04-20 16:09:24 +00:00
|
|
|
|
|
2021-04-06 22:11:00 +00:00
|
|
|
|
## Setup
|
2018-06-21 15:19:34 +00:00
|
|
|
|
|
2023-08-29 08:53:44 +00:00
|
|
|
|
There is a [complete example](complete-example) that you can copy & paste
|
|
|
|
|
|
into an html file below. To include Pyodide in your project you can use the
|
|
|
|
|
|
following CDN URL:
|
2021-07-26 23:00:27 +00:00
|
|
|
|
|
2021-08-11 10:00:44 +00:00
|
|
|
|
```text
|
2022-05-30 01:26:40 +00:00
|
|
|
|
{{PYODIDE_CDN_URL}}pyodide.js
|
2021-03-31 22:43:46 +00:00
|
|
|
|
```
|
2019-05-31 20:02:51 +00:00
|
|
|
|
|
2021-11-14 20:47:49 +00:00
|
|
|
|
You can also download a release from [GitHub
|
2021-03-31 22:43:46 +00:00
|
|
|
|
releases](https://github.com/pyodide/pyodide/releases) or build Pyodide
|
2021-08-11 10:00:44 +00:00
|
|
|
|
yourself. See {ref}`downloading_deploying` for more details.
|
2019-05-31 20:02:51 +00:00
|
|
|
|
|
2021-07-27 04:31:59 +00:00
|
|
|
|
The `pyodide.js` file defines a single async function called
|
2023-02-01 19:00:58 +00:00
|
|
|
|
{js:func}`~globalThis.loadPyodide` which sets up the Python environment
|
2021-07-27 04:31:59 +00:00
|
|
|
|
and returns {js:mod}`the Pyodide top level namespace <pyodide>`.
|
2018-06-21 15:19:34 +00:00
|
|
|
|
|
2021-02-15 08:38:49 +00:00
|
|
|
|
```pyodide
|
2021-03-31 22:43:46 +00:00
|
|
|
|
async function main() {
|
2022-03-21 05:44:54 +00:00
|
|
|
|
let pyodide = await loadPyodide();
|
2021-03-03 08:11:50 +00:00
|
|
|
|
// Pyodide is now ready to use...
|
2021-03-31 22:43:46 +00:00
|
|
|
|
console.log(pyodide.runPython(`
|
|
|
|
|
|
import sys
|
|
|
|
|
|
sys.version
|
|
|
|
|
|
`));
|
2021-05-17 17:08:25 +00:00
|
|
|
|
};
|
2021-03-31 22:43:46 +00:00
|
|
|
|
main();
|
2018-06-21 15:19:34 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## Running Python code
|
|
|
|
|
|
|
2023-02-01 19:00:58 +00:00
|
|
|
|
Python code is run using the {js:func}`pyodide.runPython` function. It takes as
|
2021-03-31 22:43:46 +00:00
|
|
|
|
input a string of Python code. If the code ends in an expression, it returns the
|
2021-09-29 08:01:53 +00:00
|
|
|
|
result of the expression, translated to JavaScript objects (see
|
2021-03-31 22:43:46 +00:00
|
|
|
|
{ref}`type-translations`). For example the following code will return the
|
2021-09-29 08:01:53 +00:00
|
|
|
|
version string as a JavaScript string:
|
2021-07-26 23:00:27 +00:00
|
|
|
|
|
2021-02-15 08:38:49 +00:00
|
|
|
|
```pyodide
|
2020-07-13 19:46:20 +00:00
|
|
|
|
pyodide.runPython(`
|
2021-03-31 22:43:46 +00:00
|
|
|
|
import sys
|
|
|
|
|
|
sys.version
|
2020-07-13 19:46:20 +00:00
|
|
|
|
`);
|
2018-06-21 15:19:34 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
2021-03-03 08:11:50 +00:00
|
|
|
|
After importing Pyodide, only packages from the standard library are available.
|
2021-03-31 22:43:46 +00:00
|
|
|
|
See {ref}`loading_packages` for information about loading additional packages.
|
2020-10-31 09:02:23 +00:00
|
|
|
|
|
2023-08-29 08:53:44 +00:00
|
|
|
|
(complete-example)=
|
|
|
|
|
|
|
2020-05-20 16:58:43 +00:00
|
|
|
|
## Complete example
|
|
|
|
|
|
|
|
|
|
|
|
Create and save a test `index.html` page with the following contents:
|
2021-07-26 23:00:27 +00:00
|
|
|
|
|
2021-02-15 08:38:49 +00:00
|
|
|
|
```html-pyodide
|
2022-09-13 22:12:40 +00:00
|
|
|
|
<!doctype html>
|
2020-05-20 16:58:43 +00:00
|
|
|
|
<html>
|
2020-07-13 19:46:20 +00:00
|
|
|
|
<head>
|
2022-05-30 01:26:40 +00:00
|
|
|
|
<script src="{{PYODIDE_CDN_URL}}pyodide.js"></script>
|
2020-07-13 19:46:20 +00:00
|
|
|
|
</head>
|
|
|
|
|
|
<body>
|
|
|
|
|
|
Pyodide test page <br>
|
2021-03-03 08:11:50 +00:00
|
|
|
|
Open your browser console to see Pyodide output
|
2020-05-20 16:58:43 +00:00
|
|
|
|
<script type="text/javascript">
|
2021-03-31 22:43:46 +00:00
|
|
|
|
async function main(){
|
2022-03-21 05:44:54 +00:00
|
|
|
|
let pyodide = await loadPyodide();
|
2021-03-31 22:43:46 +00:00
|
|
|
|
console.log(pyodide.runPython(`
|
|
|
|
|
|
import sys
|
|
|
|
|
|
sys.version
|
|
|
|
|
|
`));
|
2022-06-22 03:15:37 +00:00
|
|
|
|
pyodide.runPython("print(1 + 2)");
|
2021-03-31 22:43:46 +00:00
|
|
|
|
}
|
|
|
|
|
|
main();
|
2020-05-20 16:58:43 +00:00
|
|
|
|
</script>
|
2020-07-13 19:46:20 +00:00
|
|
|
|
</body>
|
|
|
|
|
|
</html>
|
2020-05-20 16:58:43 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
2020-10-13 09:58:59 +00:00
|
|
|
|
## Alternative Example
|
|
|
|
|
|
|
|
|
|
|
|
```html
|
2022-09-13 22:12:40 +00:00
|
|
|
|
<!doctype html>
|
2020-10-30 20:09:25 +00:00
|
|
|
|
<html>
|
2021-07-26 23:00:27 +00:00
|
|
|
|
<head>
|
2022-05-30 01:26:40 +00:00
|
|
|
|
<script src="{{PYODIDE_CDN_URL}}pyodide.js"></script>
|
2021-07-26 23:00:27 +00:00
|
|
|
|
</head>
|
|
|
|
|
|
|
|
|
|
|
|
<body>
|
|
|
|
|
|
<p>
|
|
|
|
|
|
You can execute any Python code. Just enter something in the box below and
|
|
|
|
|
|
click the button.
|
|
|
|
|
|
</p>
|
|
|
|
|
|
<input id="code" value="sum([1, 2, 3, 4, 5])" />
|
|
|
|
|
|
<button onclick="evaluatePython()">Run</button>
|
|
|
|
|
|
<br />
|
|
|
|
|
|
<br />
|
|
|
|
|
|
<div>Output:</div>
|
|
|
|
|
|
<textarea id="output" style="width: 100%;" rows="6" disabled></textarea>
|
|
|
|
|
|
|
|
|
|
|
|
<script>
|
|
|
|
|
|
const output = document.getElementById("output");
|
|
|
|
|
|
const code = document.getElementById("code");
|
|
|
|
|
|
|
|
|
|
|
|
function addToOutput(s) {
|
|
|
|
|
|
output.value += ">>>" + code.value + "\n" + s + "\n";
|
2021-03-31 22:43:46 +00:00
|
|
|
|
}
|
2020-10-13 09:58:59 +00:00
|
|
|
|
|
2021-07-26 23:00:27 +00:00
|
|
|
|
output.value = "Initializing...\n";
|
|
|
|
|
|
// init Pyodide
|
|
|
|
|
|
async function main() {
|
2022-03-21 05:44:54 +00:00
|
|
|
|
let pyodide = await loadPyodide();
|
2021-07-26 23:00:27 +00:00
|
|
|
|
output.value += "Ready!\n";
|
|
|
|
|
|
return pyodide;
|
|
|
|
|
|
}
|
|
|
|
|
|
let pyodideReadyPromise = main();
|
|
|
|
|
|
|
|
|
|
|
|
async function evaluatePython() {
|
|
|
|
|
|
let pyodide = await pyodideReadyPromise;
|
|
|
|
|
|
try {
|
|
|
|
|
|
let output = pyodide.runPython(code.value);
|
|
|
|
|
|
addToOutput(output);
|
|
|
|
|
|
} catch (err) {
|
|
|
|
|
|
addToOutput(err);
|
|
|
|
|
|
}
|
|
|
|
|
|
}
|
|
|
|
|
|
</script>
|
|
|
|
|
|
</body>
|
2020-10-13 09:58:59 +00:00
|
|
|
|
</html>
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2021-09-29 08:01:53 +00:00
|
|
|
|
## Accessing Python scope from JavaScript
|
2020-10-13 09:58:59 +00:00
|
|
|
|
|
2022-06-22 03:15:37 +00:00
|
|
|
|
All functions and variables defined in the Python global scope are accessible
|
2023-02-01 19:00:58 +00:00
|
|
|
|
via the {js:attr}`pyodide.globals` object.
|
2020-10-13 09:58:59 +00:00
|
|
|
|
|
2023-08-29 08:53:44 +00:00
|
|
|
|
For example, if you run the code `x = [3, 4]` in Python global scope,
|
2022-06-22 03:15:37 +00:00
|
|
|
|
you can access the global variable `x` from JavaScript in your browser's
|
|
|
|
|
|
developer console with `pyodide.globals.get("x")`. The same goes for functions
|
|
|
|
|
|
and imports. See {ref}`type-translations` for more details.
|
2020-10-13 09:58:59 +00:00
|
|
|
|
|
2023-03-07 17:10:27 +00:00
|
|
|
|
You can try it yourself in the browser console. Go to the [Pyodide REPL
|
|
|
|
|
|
URL](../console.html){.external} and type the following into the browser
|
|
|
|
|
|
console:
|
2022-06-22 03:15:37 +00:00
|
|
|
|
|
2021-03-31 22:43:46 +00:00
|
|
|
|
```pyodide
|
|
|
|
|
|
pyodide.runPython(`
|
2023-08-29 08:53:44 +00:00
|
|
|
|
x = [3, 4]
|
2021-03-31 22:43:46 +00:00
|
|
|
|
`);
|
2021-03-24 11:05:00 +00:00
|
|
|
|
pyodide.globals.get('x').toJs();
|
2023-08-29 08:53:44 +00:00
|
|
|
|
// >>> [ 3, 4 ]
|
2020-10-13 09:58:59 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
2022-06-22 03:15:37 +00:00
|
|
|
|
You can assign new values to Python global variables or create new ones from
|
|
|
|
|
|
Javascript.
|
2020-10-13 09:58:59 +00:00
|
|
|
|
|
2021-03-31 22:43:46 +00:00
|
|
|
|
```pyodide
|
2020-10-13 09:58:59 +00:00
|
|
|
|
// re-assign a new value to an existing variable
|
2021-02-23 19:25:10 +00:00
|
|
|
|
pyodide.globals.set("x", 'x will be now string');
|
2020-10-13 09:58:59 +00:00
|
|
|
|
|
2022-06-22 03:15:37 +00:00
|
|
|
|
// add the js "alert" function to the Python global scope
|
|
|
|
|
|
// this will show a browser alert if called from Python
|
2021-02-23 19:25:10 +00:00
|
|
|
|
pyodide.globals.set("alert", alert);
|
2020-10-13 09:58:59 +00:00
|
|
|
|
|
2022-06-22 03:15:37 +00:00
|
|
|
|
// add a "square" function to Python global scope
|
2021-02-23 19:25:10 +00:00
|
|
|
|
pyodide.globals.set("square", x => x*x);
|
2021-03-23 21:48:50 +00:00
|
|
|
|
|
2022-06-22 03:15:37 +00:00
|
|
|
|
// Test the new "square" Python function
|
2021-04-06 08:14:07 +00:00
|
|
|
|
pyodide.runPython("square(3)");
|
2020-10-13 09:58:59 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
2021-09-29 08:01:53 +00:00
|
|
|
|
## Accessing JavaScript scope from Python
|
2020-10-13 09:58:59 +00:00
|
|
|
|
|
2021-09-29 08:01:53 +00:00
|
|
|
|
The JavaScript scope can be accessed from Python using the `js` module (see
|
2022-06-22 03:15:37 +00:00
|
|
|
|
{ref}`type-translations_using-js-obj-from-py`). We can use it to access global
|
|
|
|
|
|
variables and functions from Python. For instance, we can directly manipulate the DOM:
|
2020-10-13 09:58:59 +00:00
|
|
|
|
|
|
|
|
|
|
```python
|
|
|
|
|
|
import js
|
|
|
|
|
|
|
|
|
|
|
|
div = js.document.createElement("div")
|
|
|
|
|
|
div.innerHTML = "<h1>This element was created from Python</h1>"
|
|
|
|
|
|
js.document.body.prepend(div)
|
|
|
|
|
|
```
|
