PyScript makes available convenience objects and functions inside Python as well as custom attributes in HTML.
In Python this is done via the
In HTML this is done via
These Python objects / functions are available in both the main thread and in code running on a web worker:
This object is a proxy for the web page's global window context.
Please note that in workers, this is still the main window, not the
worker's own global context. A worker's global context is reachable instead
import js (the
js object being a proxy for the worker's
A function used to display content. The function is intelligent enough to introspect the object[s] it is passed and work out how to correctly display the object[s] in the web page.
display function takes a list of
*values as its first argument, and has
two optional named arguments:
target=None- the DOM element into which the content should be placed.
append=True- a flag to indicate if the output is going to be appended to the
There are some caveats:
- When used in the main thread, the
displayfunction automatically uses the current
<script>tag as the
targetinto which the content will be displayed.
- If the
<script>tag has the
targetattribute, the element on the page with that ID (or which matches that selector) will be used to display the content instead.
- When used in a worker, the
displayfunction needs an explicit
target="dom-id"argument to identify where the content will be displayed.
- In both the main thread and worker,
append=Trueis the default behaviour.
A Python decorator to indicate the decorated function should handle the specified events for selected elements.
The decorator takes two parameters:
event_typeshould be the name of the browser event to handle as a string (e.g.
selectorshould be a string containing a valid selector to indicate the target elements in the DOM whose events of
event_typeare of interest.
The following example has a button with an id of
my_button and a decorated
function that handles
click events dispatched by the button.
This functionality is related to the HTML py-* attributes.
Such named modules will always then be available under the
Main-thread only features
A class used to instantiate a new worker from within Python.
Currently this only works with Pyodide.
The following fragment demonstrates who to start the Python code in the file
worker.py on a new worker from within Python.
Worker only features
A function used to pass serializable data from workers to the main thread.
Imagine you have this code on the main thread:
In the code on the worker, you can pass data back to handler functions like this:
As a convenience, and to ensure backwards compatibility, PyScript allows the use of inline event handlers via custom HTML attributes.
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 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.
This is similar to how all
event handlers on elements
on in standard HTML (e.g.
onclick). The rule of thumb is to
py- and then reference the name of a Python
Under the hood, the
pyscript.when decorator is used to
enable this behaviour.
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.