PyScript

https://docs.pyscript.net/
Admin
PyScript is an open-source platform that allows users to run Python code directly in the browser...
Tokens:88,518
Snippets:1,107
Trust Score:9.8
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Development Dependencies

Source: https://docs.pyscript.net/2026.7.3/developers

Run the setup target to install required software dependencies.

```bash
make setup
```

--------------------------------

### Serve application locally

Source: https://docs.pyscript.net/2026.7.3/user-guide/offline

Command to start a local HTTP server for the public directory.

```bash
python3 -m http.server -d public/
```

--------------------------------

### Access configured resources in Python

Source: https://docs.pyscript.net/2026.7.3/user-guide/configuration

Example of using installed packages, reading mapped files, and importing JavaScript modules within a Python script.

```python
import numpy as np
from pyscript import display


# Use installed packages.
data = np.array([1, 2, 3, 4, 5])
display(f"Mean: {data.mean()}")

# Read configured files.
with open("data.csv") as f:
    display(f"Data: {f.read()[:100]}")

# Use JavaScript modules.
from pyscript.js_modules import chartjs
display("Chart.js loaded!")
```

--------------------------------

### Initialize PyScript project directory

Source: https://docs.pyscript.net/2026.7.3/user-guide/offline

Commands to create a project folder, initialize a package file, and install PyScript core via npm.

```bash
mkdir pyscript-offline
cd pyscript-offline

# Create a package.json file.
echo '{}' > package.json

# Install PyScript core.
npm i @pyscript/core

# Copy distribution files to your public directory.
mkdir -p public
cp -R node_modules/@pyscript/core/dist public/pyscript
```

--------------------------------

### Configuring editor setup scripts

Source: https://docs.pyscript.net/2026.7.3/user-guide/editor

Uses the setup attribute to run boilerplate code in an environment without displaying it in the editor.

```html
<script type="mpy-editor" env="classroom" setup>
# This code runs automatically but isn't visible.
import math
pi = math.pi
</script>

<script type="mpy-editor" env="classroom">
# This editor is visible. The setup code already ran.
print(f"Pi is approximately {pi:.2f}")
</script>
```

--------------------------------

### WebSocket Connection Initialization

Source: https://docs.pyscript.net/2026.7.3/api/websocket

Examples of initializing WebSocket connections with basic URLs, protocols, and lambda-based event handlers.

```python
# Basic connection.
ws = WebSocket(url="ws://localhost:8080/")

# With protocol.
ws = WebSocket(
    url="wss://example.com/socket",
    protocols="chat"
)

# With handlers.
ws = WebSocket(
    url="ws://localhost:8080/",
    onopen=lambda e: print("Connected"),
    onmessage=lambda e: print(e.data)
)
```

--------------------------------

### Configure HTML for local PyScript

Source: https://docs.pyscript.net/2026.7.3/user-guide/offline

Example HTML structure for loading PyScript core from a local directory.

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>PyScript Offline</title>
  <script type="module" src="/pyscript/core.js"></script>
  <link rel="stylesheet" href="/pyscript/core.css">
</head>
<body>
  <script type="mpy">
    from pyscript import document

    document.body.append("Hello from PyScript")
  </script>
</body>
</html>
```

--------------------------------

### Install and configure local Pyodide

Source: https://docs.pyscript.net/2026.7.3/user-guide/offline

Commands to install Pyodide via npm and copy the necessary files to the public directory.

```bash
# Install Pyodide.
npm i pyodide

# Create target directory.
mkdir -p public/pyodide

# Copy all necessary files.
cp node_modules/pyodide/pyodide* public/pyodide/
cp node_modules/pyodide/python_stdlib.zip public/pyodide/
```

--------------------------------

### Performing network requests with fetch

Source: https://docs.pyscript.net/2026.7.3/api/fetch

Examples of performing GET and POST requests, method chaining, and handling response status codes.

```python
# Simple GET request.
response = await fetch("https://api.example.com/data")
data = await response.json()

# Method chaining.
data = await fetch("https://api.example.com/data").json()

# POST request with JSON.
response = await fetch(
    "https://api.example.com/users",
    method="POST",
    headers={"Content-Type": "application/json"},
    body=json.dumps({"name": "Alice"})
)
result = await response.json()

# Check response status codes.
response = await fetch("https://api.example.com/data")
if response.ok:
    # Status in the range 200-299.
    data = await response.json()
elif response.status == 404:
    print("Resource not found")
else:
    print(f"Error: {response.status} {response.statusText}")
```

--------------------------------

### Install and configure local MicroPython

Source: https://docs.pyscript.net/2026.7.3/user-guide/offline

Commands to install MicroPython via npm and copy the interpreter files to the public directory.

```bash
# Install the MicroPython package.
npm i @micropython/micropython-webassembly-pyscript

# Create target directory.
mkdir -p public/micropython

# Copy interpreter files.
cp node_modules/@micropython/micropython-webassembly-pyscript/micropython.* public/micropython/
```

--------------------------------

### Implementing a full lifecycle plugin

Source: https://docs.pyscript.net/2026.7.3/user-guide/plugins

A comprehensive example showing how to register hooks for both the main thread and worker environments to log lifecycle events.

```javascript
// Import hooks from PyScript.
import { hooks } from "https://pyscript.net/releases/2026.7.3/core.js";

// Register main thread hooks.
hooks.main.onReady.add((wrap, element) => {
    console.log("main: interpreter ready");
    if (location.search === '?debug') {
        console.debug("wrap:", wrap);
        console.debug("element:", element);
    }
});

hooks.main.onBeforeRun.add(() => {
    console.log("main: about to run code");
});

hooks.main.codeBeforeRun.add('print("main: injected before")');
hooks.main.codeAfterRun.add('print("main: injected after")');

hooks.main.onAfterRun.add(() => {
    console.log("main: finished running code");
});

// Register worker hooks.
hooks.worker.onReady.add((wrap, xworker) => {
    console.log("worker: interpreter ready");
    if (location.search === '?debug') {
        console.debug("wrap:", wrap);
        console.debug("xworker:", xworker);
    }
});

hooks.worker.onBeforeRun.add(() => {
    console.log("worker: about to run code");
});

hooks.worker.codeBeforeRun.add('print("worker: injected before")');
hooks.worker.codeAfterRun.add('print("worker: injected after")');

hooks.worker.onAfterRun.add(() => {
    console.log("worker: finished running code");
});
```

--------------------------------

### Run standard PyScript examples locally

Source: https://docs.pyscript.net/2026.7.3/example-apps/overview

Use a standard Python HTTP server to host applications that do not require special cross-origin isolation headers.

```bash
# Navigate to the example directory.
cd example_apps/pirate-translator

# Serve with any web server.
python -m http.server 8000

# Visit http://localhost:8000 in your browser.
```

--------------------------------

### Remote Package Configuration Example

Source: https://docs.pyscript.net/2026.7.3/user-guide/configuration

Define a remote package structure including its name, dependencies, and file mapping.

```toml
name = "my_package"

# a remote config can include packages, even remote ones
packages = ["matplotlib"]

# files are resolved relatively to this config URL
[files]
"./__init__.py" = ""
"./sub/module.py" = ""
"./main.py" = ""
```

--------------------------------

### Install PyPI packages with micropip

Source: https://docs.pyscript.net/2026.7.3/faq

Use micropip to install pure Python packages from PyPI within the Pyodide environment.

```python
import micropip

await micropip.install("pillow")
```

--------------------------------

### Displaying content with the display function

Source: https://docs.pyscript.net/2026.7.3/api/display

Examples showing how to render raw HTML, target specific DOM elements, and control content replacement.

```python
from pyscript import display, HTML


# Display raw HTML.
display(HTML("<h1>Hello, World!</h1>"))

# Display in current script's output area.
display("Hello, World!")

# Display in a specific element.
display("Hello", target="my-div")

# Replace existing content (note the `#`).
display("New content", target="#my-div", append=False)

# Display multiple values in the default target.
display("First", "Second", "Third")
```

--------------------------------

### Serve with Cross-Origin Isolation headers

Source: https://docs.pyscript.net/2026.7.3/user-guide/offline

Commands to install and run mini-coi for enabling SharedArrayBuffer and worker support.

```bash
# Install mini-coi if needed.
npm i -g mini-coi

# Serve with COI headers enabled.
npx mini-coi public/
```

--------------------------------

### Synchronizing Storage

Source: https://docs.pyscript.net/2026.7.3/api/storage

Example of using the sync method to guarantee that data is persisted to IndexedDB before proceeding.

```python
store = await storage("important-data")
store["critical_value"] = data

# Ensure it's written before proceeding.
await store.sync()
```

--------------------------------

### Start an interactive REPL

Source: https://docs.pyscript.net/2026.7.3/user-guide/terminal

Use the code module to launch a full Python REPL session within the terminal.

```python
import code

code.interact()
```

--------------------------------

### Main thread deadlock example

Source: https://docs.pyscript.net/2026.7.3/faq

Demonstrates main thread code that triggers a deadlock when awaiting a worker task.

```html
<script type="mpy">
from pyscript import PyWorker


async def main_task():
    # Deadlock occurs here. 💀🔒
    await pw.sync.worker_task()


pw = PyWorker("./worker.py", {"type": "pyodide"})
pw.sync.main_task = main_task
</script>
```

--------------------------------

### Run web-worker PyScript examples locally

Source: https://docs.pyscript.net/2026.7.3/example-apps/overview

Use the mini-coi tool to serve applications requiring specific cross-origin isolation headers for web-worker functionality.

```bash
# Navigate to the worker-related project.
cd example_apps/prime-worker

# Serve the app with the correct headers.
npx mini-coi .

# Visit http://localhost:8080/ in your browser.
```

--------------------------------

### Configure editor packages

Source: https://docs.pyscript.net/2026.7.3/user-guide/editor

Pass a JSON string to the config attribute to define environment requirements like installed packages.

```html
<script type="py-editor" config='{"packages": ["numpy"]}'>
import numpy as np
print(np.array([1, 2, 3]))
</script>
```

--------------------------------

### Using PyScript Storage

Source: https://docs.pyscript.net/2026.7.3/api/storage

Demonstrates initializing a storage instance, performing dictionary-like operations, and explicitly syncing data to IndexedDB.

```python
from pyscript import storage


# Create or open a named storage.
my_data = await storage("user-preferences")

# Use like a regular dictionary.
my_data["theme"] = "dark"
my_data["font_size"] = 14
my_data["settings"] = {"notifications": True, "sound": False}

# Changes are queued automatically.
# To ensure immediate write, sync explicitly.
await my_data.sync()

# Read values (survives page reload).
theme = my_data.get("theme", "light")
```

--------------------------------

### Mounting and interacting with local files

Source: https://docs.pyscript.net/2026.7.3/api/fs

Demonstrates mounting a local directory, handling user interaction for permissions, performing file I/O, and syncing changes back to the local filesystem.

```python
from pyscript import fs, document, when


# Mount a local directory to the `/local` mount point in the browser's
# virtual filesystem (may prompt user for permission).
await fs.mount("/local")

# Alternatively, mount on a button click event. This is important because
# if the call to `fs.mount` happens after a click or other transient event,
# the confirmation dialog will not be shown.
@when("click", "#mount-button")
async def handler(event):
    await fs.mount("/another_dir")

# Work with files in the mounted directory as usual.
with open("/local/example.txt", "w") as f:
    f.write("Hello from PyScript!")

# Ensure changes are written to local filesystem.
await fs.sync("/local")

# Clean up when done.
await fs.unmount("/local")
```

--------------------------------

### Initialize and use a WebSocket connection

Source: https://docs.pyscript.net/2026.7.3/api/websocket

Demonstrates establishing a connection and defining event handlers for open, message, and close events.

```python
from pyscript import WebSocket


def on_open(event):
    print("Connected!")
    ws.send("Hello server")

def on_message(event):
    print(f"Received: {event.data}")

def on_close(event):
    print("Connection closed")

ws = WebSocket(url="ws://localhost:8080/")
ws.onopen = on_open
ws.onmessage = on_message
ws.onclose = on_close
```

--------------------------------

### Basic Storage Usage

Source: https://docs.pyscript.net/2026.7.3/api/storage

Demonstrates initializing a storage instance, performing dictionary operations, and manually synchronizing data to IndexedDB.

```python
from pyscript import storage


# Open a storage.
prefs = await storage("preferences")

# Use as a dictionary.
prefs["color"] = "blue"
prefs["count"] = 42

# Iterate like a dict.
for key, value in prefs.items():
    print(f"{key}: {value}")

# Ensure writes complete immediately.
await prefs.sync()
```

--------------------------------

### web.page.title

Source: https://docs.pyscript.net/2026.7.3/api/web

Property to get or set the document title.

```APIDOC
## Property: web.page.title

### Description
Gets or sets the title of the current web page.

### Usage
```python
# Get the title
print(web.page.title)

# Set the title
web.page.title = "New Title"
```
```

--------------------------------

### Device.get_stream()

Source: https://docs.pyscript.net/2026.7.3/api/media

Get a media stream from a specific device.

```APIDOC
## async Device.get_stream()

### Description
Requests a media stream from the specific device instance. This will trigger a permission dialog if the user has not already granted permission for this device type.

### Usage
```python
# Assuming 'my_camera' is a device object from list_devices()
stream = await my_camera.get_stream()
```
```

--------------------------------

### Filesystem Operations Pattern

Source: https://docs.pyscript.net/2026.7.3/example-apps/note-taker/info

Demonstrates the sequence of mounting a directory, writing a file, and syncing changes to ensure persistence.

```python
# Mount (user selects folder).
await fs.mount("/notes")

# Write files.
with open("/notes/my-note.txt", "w") as f:
    f.write(note_text)

# Sync to persist changes.
await fs.sync("/notes")
```

--------------------------------

### Interpret Python Tracebacks

Source: https://docs.pyscript.net/2026.7.3/faq

Examples of NameError tracebacks displayed in the browser console when a variable is undefined.

```text
Traceback (most recent call last):
  File "/lib/python311.zip/_pyodide/_base.py", line 501, in eval_code
    .run(globals, locals)
     ^^^^^^^^^^^^^^^^^^^^
  File "/lib/python311.zip/_pyodide/_base.py", line 339, in run
    coroutine = eval(self.code, globals, locals)
                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "<exec>", line 1, in <module>
NameError: name 'failure' is not defined
```

```text
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
NameError: name 'failure' isn't defined
```

--------------------------------

### Load files via configuration and Python

Source: https://docs.pyscript.net/2026.7.3/faq

Define files in configuration and access them using standard Python file I/O.

```toml
[files]
"data.csv" = "./data.csv"
"config.json" = "https://example.com/config.json"
```

```python
with open("data.csv") as f:
    data = f.read()
```

--------------------------------

### Define Python module functions

Source: https://docs.pyscript.net/2026.7.3/user-guide/from_javascript

Example Python module defining functions to be imported by JavaScript.

```python
# utils.py
import json


def parse_json(text):
    """
    Parse JSON string.
    """
    return json.loads(text)


def stringify_json(obj):
    """
    Convert object to JSON string.
    """
    return json.dumps(obj)
```

--------------------------------

### Initialize and Configure WebSocket Handlers

Source: https://docs.pyscript.net/2026.7.3/api/websocket

Demonstrates creating a WebSocket connection and assigning event handlers either during initialization or by assigning them to attributes after creation.

```python
# Create WebSocket with handlers as arguments.
def handle_message(event):
    print(f"Got: {event.data}")

ws = WebSocket(
    url="ws://echo.websocket.org/",
    onmessage=handle_message
)

# Or assign handlers after creation.
def handle_open(event):
    ws.send("Hello!")

ws.onopen = handle_open
```

--------------------------------

### Define Python packages

Source: https://docs.pyscript.net/2026.7.3/user-guide/configuration

Specify packages to install via PyPI for Pyodide or the micropython-lib repository for MicroPython.

```toml
packages = ["arrr", "numberwang", "snowballstemmer>=2.2.0" ]
```

```json
{
    "packages": ["arrr", "numberwang", "snowballstemmer>=2.2.0" ]
}
```

--------------------------------

### Manage CSS Styles

Source: https://docs.pyscript.net/2026.7.3/api/web

Use a dictionary-like interface to set, get, and remove inline CSS styles.

```python
# Set styles using CSS property names (hyphenated).
element.style["color"] = "red"
element.style["background-color"] = "#f0f0f0"
element.style["font-size"] = "16px"

# Get styles.
color = element.style["color"]

# Remove styles.
del element.style["margin"]
```

--------------------------------

### Mounting and Syncing Local Directories

Source: https://docs.pyscript.net/2026.7.3/user-guide/filesystem

Basic workflow for mounting a local directory, performing file operations, and syncing changes back to the local filesystem.

```python
from pyscript import fs


# Ask for permission to mount any local folder into the virtual
# filesystem. The folder "/local" refers to the directory on the
# virtual filesystem to which the user-selected directory will be
# mounted.
await fs.mount("/local")

# Do file related operations here.
with open("/local/data.txt", "w") as f:
    f.write("Hello from PyScript!")

# Ensure changes are persisted to the local filesystem's folder.
await fs.sync("/local")

# If needed, sync and unmount to free RAM.
await fs.unmount("/local")
```

--------------------------------

### Handle crypto.randomUUID error

Source: https://docs.pyscript.net/2026.7.3/faq

Example of the error message encountered when the crypto API is unavailable in non-secure contexts.

```text
TypeError: crypto.randomUUID is not a function
```

--------------------------------

### Write and download files

Source: https://docs.pyscript.net/2026.7.3/faq

Create files in the virtual filesystem and trigger browser downloads.

```python
with open("output.txt", "w") as f:
    f.write("Hello, world!")
```

```python
from pyscript import window, ffi


def download_file(filename, content):
    """
    Trigger browser download of file content.
    """
    # Ensure you use the correct mime-type!
    blob = window.Blob.new([content], ffi.to_js({"type": "text/plain"}))
    # Create a temporary download link/URL.
    url = window.URL.createObjectURL(blob)
    link = window.document.createElement("a")
    link.href = url
    link.download = filename
    # Activate the link (pretend to click it).
    link.click()
    # Then revoke the temporary URL.
    window.URL.revokeObjectURL(url)


# Use it.
download_file("output.txt", "File contents here")
```

--------------------------------

### Create and configure a DOM element

Source: https://docs.pyscript.net/2026.7.3/user-guide/dom

Demonstrates creating a new div element, setting its content and style, and appending a child paragraph.

```python
# Create an empty div.
my_div = web.div(id="my-container")

# Add content and styling.
my_div.innerHTML = "<p>Hello!</p>"
my_div.classes.add("active")
my_div.style["background-color"] = "lightblue"

# Create a paragraph and add it.
my_p = web.p("This is a paragraph.")
my_div.append(my_p)
```

--------------------------------

### Using ContainerElement for Child Management

Source: https://docs.pyscript.net/2026.7.3/api/web

Demonstrates creating container elements with various child configurations and iterating over them.

```python
from pyscript import web


# Create with child elements as arguments.
div = web.div(
    web.h1("Title"),
    web.p("Paragraph 1"),
    web.p("Paragraph 2")
)

# Or use the children keyword argument.
div = web.div(children=[web.p("Child 1"), web.p("Child 2")])

# Mix elements and HTML strings.
div = web.div(
    web.h1("Title"),
    "<p>HTML content</p>",
    web.button("Click me")
)

# Iterate over children.
for child in div:
    print(child.innerHTML)
```

--------------------------------

### Worker thread deadlock example

Source: https://docs.pyscript.net/2026.7.3/faq

Demonstrates worker code that triggers a deadlock when awaiting a main thread task.

```python
from pyscript import sync

sync.worker_task = lambda: print('🔥 this is fine 🔥')

# Deadlock occurs here. 💀🔒
sync.main_task()
```

--------------------------------

### Build PyScript from source

Source: https://docs.pyscript.net/2026.7.3/user-guide/offline

Steps to clone the repository and copy the built distribution files to the local project directory.

```bash
# Clone the repository.
git clone https://github.com/pyscript/pyscript.git
cd pyscript

# Follow build instructions from the developer guide.
# Once built, copy the dist folder.
cp -R dist ../pyscript-offline/public/pyscript
```

--------------------------------

### Configure PyScript packages

Source: https://docs.pyscript.net/2026.7.3/user-guide/configuration

Define required Python packages to be installed from PyPI using either TOML or JSON format.

```toml
packages = ["arrr", "numberwang" ]
```

```json
{
    "packages": ["arrr", "numberwang"]
}
```

--------------------------------

### Configure file resources with templates

Source: https://docs.pyscript.net/2026.7.3/user-guide/configuration

Use curly-bracket placeholders to define reusable paths and URLs in file configurations.

```json
{
  "files": {
    "{DOMAIN}": "https://my-server.com",
    "{PATH}": "a/path",
    "{VERSION}": "1.2.3",
    "{FROM}": "{DOMAIN}/{PATH}/{VERSION}",
    "{TO}": "./my_module",
    "{FROM}/__init__.py": "{TO}/__init__.py",
    "{FROM}/foo.py": "{TO}/foo.py",
    "{FROM}/bar.py": "{TO}/bar.py",
    "{FROM}/baz.py": "{TO}/baz.py",
  }
}
```

```toml
[files]
"{DOMAIN}" = "https://my-server.com"
"{PATH}" = "a/path"
"{VERSION}" = "1.2.3"
"{FROM}" = "{DOMAIN}/{PATH}/{VERSION}"
"{TO}" = "./my_module"
"{FROM}/__init__.py" = "{TO}/__init__.py"
"{FROM}/foo.py" = "{TO}/foo.py"
"{FROM}/bar.py" = "{TO}/bar.py"
"{FROM}/baz.py" = "{TO}/baz.py"
```

--------------------------------

### Accessing media devices and streams

Source: https://docs.pyscript.net/2026.7.3/api/media

Demonstrates how to request a video stream from the default camera and list all available media devices. Note that accessing these devices triggers a browser permission prompt.

```python
from pyscript import document
from pyscript.media import Device, list_devices


# Get a video stream from the default camera.
stream = await Device.request_stream(video=True)

# Display in a video element.
video = document.getElementById("my-video")
video.srcObject = stream

# Or list all available devices.
devices = await list_devices()
for device in devices:
    print(f"{device.kind}: {device.label}")
```

--------------------------------

### get_event(name)

Source: https://docs.pyscript.net/2026.7.3/api/web

Retrieves or creates an Event instance for the specified event name. Event names must start with 'on_'.

```APIDOC
## get_event(name)

### Description
Retrieves or creates an Event instance for the specified event name. Event names must start with 'on_'.

### Parameters
- **name** (str) - Required - The name of the event (e.g., 'on_click').
```

--------------------------------

### Create and trigger a custom event

Source: https://docs.pyscript.net/2026.7.3/api/events

Demonstrates initializing an Event instance, registering a listener function, and triggering the event with data.

```python
from pyscript.events import Event

# Create a custom event.
data_loaded = Event()

# Add a listener.
def on_data_loaded(result):
    print(f"Data loaded: {result}")

data_loaded.add_listener(on_data_loaded)

# Time passes.... trigger the event.
data_loaded.trigger({"data": 123})
```

--------------------------------

### HTML Canvas Setup

Source: https://docs.pyscript.net/2026.7.3/user-guide/pygame-ce

The HTML structure required to host the PyGame-CE application, including the canvas element and PyScript script tag.

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <title>PyScript PyGame-CE Example</title>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width,initial-scale=1.0">
  <link rel="stylesheet" 
    href="https://pyscript.net/releases/2026.7.3/core.css">
  <script type="module" 
    src="https://pyscript.net/releases/2026.7.3/core.js"></script>
</head>
<body>
  <canvas id="canvas" style="image-rendering: pixelated"></canvas>
  <script type="py-game" src="quickstart.py" 
    config="pyscript.toml"></script>
</body>
</html>
```

--------------------------------

### List Devices Import

Source: https://docs.pyscript.net/2026.7.3/api/media

Import statement for listing available media devices.

```python
from pyscript.media import list_devices
```

--------------------------------

### Implement get_event for event handling

Source: https://docs.pyscript.net/2026.7.3/api/web

Retrieves or creates an Event instance for a given event name, ensuring the name starts with 'on_'.

```python
def get_event(self, name):
    """
    Get an `Event` instance for the specified event name.

    Event names must start with `on_` (e.g. `on_click`). Creates and
    caches `Event` instances that are triggered when the DOM event fires.
    """
    if not name.startswith("on_"):
        raise ValueError("Event names must start with 'on_'.")
    event_name = name[3:]  # Remove 'on_' prefix.
    if not hasattr(self._dom_element, event_name):
        raise ValueError(f"Element has no '{event_name}' event.")
    if name in self._on_events:
        return self._on_events[name]
    # Create Event instance and wire it to the DOM event.
    ev = Event()
    self._on_events[name] = ev
    self._dom_element.addEventListener(event_name, create_proxy(ev.trigger))
    return ev
```

--------------------------------

### Initialize Classes

Source: https://docs.pyscript.net/2026.7.3/api/web

Constructor for the Classes class.

```python
def __init__(self, element):
    """
    Initialise the CSS Classes set for the given element.
    """
    self._class_list = element._dom_element.classList
    super().__init__(self._class_list)
```

--------------------------------

### Download PyScript core via npm

Source: https://docs.pyscript.net/2026.7.3/user-guide/offline

Use npm to fetch the PyScript distribution files for local hosting.

```bash
npm install @pyscript/core
```

--------------------------------

### Implement __getattr__ for element attributes

Source: https://docs.pyscript.net/2026.7.3/api/web

Retrieves attributes from the underlying DOM element, with special handling for event attributes starting with 'on_'.

```python
def __getattr__(self, name):
    """
    Get an attribute from the element.

    Attributes starting with `on_` return `Event` instances. Other
    attributes are retrieved from the underlying DOM element.
    """
    if name.startswith("on_"):
        return self.get_event(name)
    dom_name = self._normalize_attribute_name(name)
    return getattr(self._dom_element, dom_name)
```

--------------------------------

### __init__(dom_element=None, classes=None, style=None, **kwargs)

Source: https://docs.pyscript.net/2026.7.3/api/web

Initializes a new Element instance, either by creating a new DOM element or wrapping an existing one.

```APIDOC
## __init__(dom_element=None, classes=None, style=None, **kwargs)

### Description
Create or wrap a DOM element. If `dom_element` is `None`, this creates a new element. Otherwise wraps the provided DOM element.

### Parameters
- **dom_element** (object) - Optional - The DOM element to wrap.
- **classes** (list/str) - Optional - CSS classes to apply.
- **style** (dict/str) - Optional - Style attributes to apply.
- **kwargs** (dict) - Optional - HTML attributes and event handlers (names starting with `on_`).
```

--------------------------------

### List and access media devices

Source: https://docs.pyscript.net/2026.7.3/api/media

Demonstrates how to retrieve a list of available media devices and filter them by type.

```python
from pyscript.media import list_devices


# Get all available devices.
devices = await list_devices()

# Find video input devices (cameras).
cameras = [d for d in devices if d.kind == "videoinput"]

# Get a stream from a specific camera.
if cameras:
    stream = await cameras[0].get_stream()
```

--------------------------------

### Get HTML tag name

Source: https://docs.pyscript.net/2026.7.3/api/web

The get_tag_name class method returns the HTML tag name associated with the class, stripping trailing underscores.

```python
@classmethod
def get_tag_name(cls):
    """
    Get the HTML tag name for this class.

    Classes ending with underscore (e.g. `input_`) have it removed to get
    the actual HTML tag name.
    """
    return cls.__name__.replace("_", "")
```

--------------------------------

### WebSocket.__init__(url, protocols=None, **handlers)

Source: https://docs.pyscript.net/2026.7.3/api/websocket

Initializes a new WebSocket connection to the specified URL. Supports optional protocols and event handlers.

```APIDOC
## WebSocket.__init__(url, protocols=None, **handlers)

### Description
Creates a new WebSocket connection from the given `url` (`ws://` or `wss://`). Optionally specify `protocols` and event handlers as keyword arguments.

### Parameters
- **url** (str) - Required - The WebSocket URL to connect to.
- **protocols** (str or list) - Optional - A string or list of protocol strings.
- **handlers** (dict) - Optional - Event handlers such as `onopen`, `onmessage`, etc.
```

--------------------------------

### __getattr__(name)

Source: https://docs.pyscript.net/2026.7.3/api/web

Retrieves an attribute from the element. Attributes starting with 'on_' return Event instances, while others are retrieved from the underlying DOM element.

```APIDOC
## __getattr__(name)

### Description
Retrieves an attribute from the element. Attributes starting with 'on_' return Event instances, while others are retrieved from the underlying DOM element.

### Parameters
- **name** (str) - Required - The name of the attribute to retrieve.
```

--------------------------------

### Initialize a Device wrapper

Source: https://docs.pyscript.net/2026.7.3/api/media

Wraps a MediaDeviceInfo object to provide a Pythonic interface.

```python
def __init__(self, device):
    """
    Create a Device wrapper around a MediaDeviceInfo `device`.
    """
    self._device_info = device
```

--------------------------------

### Create and Manage Python Virtual Environments

Source: https://docs.pyscript.net/2026.7.3/developers

Commands for creating, activating, and deactivating a standard Python virtual environment.

```bash
python3 -m venv my_pyscript_dev_venv
```

```bash
source my_pyscript_dev_venv/bin/activate
```

```bash
deactivate
```

--------------------------------

### Element Creation and Attribute Management

Source: https://docs.pyscript.net/2026.7.3/api/web

Demonstrates how to instantiate HTML elements using tag-specific classes and manage their attributes, classes, and styles.

```APIDOC
## Element Creation

### Description
Create new HTML elements using tag-specific classes provided by the `web` namespace.

### Usage
```python
from pyscript import web

# Create a simple div
div = web.div("Hello, World!")

# Create with attributes
link = web.a("Click me", href="https://example.com", target="_blank")

# Create with classes and styles
button = web.button(
    "Submit",
    classes=["primary", "large"],
    style={"background-color": "blue", "color": "white"},
    id="submit-btn"
)
```

## Attribute Access

### Description
Access and modify HTML attributes directly as Python properties.

### Usage
```python
# Get attributes
val = element.id

# Set attributes
element.id = "new-id"

# HTML content
element.innerHTML = "<b>Bold text</b>"
```

## CSS Class Management

### Description
Manage CSS classes using a set-like interface.

### Usage
```python
# Add classes
element.classes.add("active")

# Remove classes
element.classes.remove("inactive")

# Check membership
if "active" in element.classes:
    print("Element is active")
```
```

--------------------------------

### Bouncing Ball Game Logic

Source: https://docs.pyscript.net/2026.7.3/user-guide/pygame-ce

The core game loop for the bouncing ball example. Requires an async context to use await asyncio.sleep(1/60) for browser canvas updates.

```python
import asyncio
import sys
import pygame

pygame.init()

size = width, height = 320, 240
speed = [2, 2]
black = 0, 0, 0

screen = pygame.display.set_mode(size)
ball = pygame.image.load("intro_ball.gif")
ballrect = ball.get_rect()

while True:
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            sys.exit()

    ballrect = ballrect.move(speed)
    if ballrect.left < 0 or ballrect.right > width:
        speed[0] = -speed[0]
    if ballrect.top < 0 or ballrect.bottom > height:
        speed[1] = -speed[1]

    screen.fill(black)
    screen.blit(ball, ballrect)
    pygame.display.flip()
    await asyncio.sleep(1/60)
```

--------------------------------

### Create a basic Python editor

Source: https://docs.pyscript.net/2026.7.3/user-guide/editor

Initialize a code editor by setting the script type to py-editor for Pyodide or mpy-editor for MicroPython.

```html
<script type="py-editor">
import sys
print(sys.version)
</script>
```

--------------------------------

### Configure PyScript for offline use

Source: https://docs.pyscript.net/2026.7.3/user-guide/offline

HTML template demonstrating local package loading and Pyodide interpreter configuration for offline execution.

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>PyScript Offline</title>
  <script type="module" src="/pyscript/core.js"></script>
  <link rel="stylesheet" href="/pyscript/core.css">
</head>
<body>
  <py-config>
    interpreter = "/pyodide/pyodide.mjs"
    packages = ["pandas"]
  </py-config>
  <script type="py">
    import pandas as pd

    x = pd.Series([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
    result = [i**2 for i in x]

    from pyscript import document
    document.body.append(str(result))
  </script>
</body>
</html>
```

--------------------------------

### Creating DOM Elements

Source: https://docs.pyscript.net/2026.7.3/example-apps/task-board-ffi/info

Comparison between declarative element creation in PyScript web and imperative creation using FFI.

```python
task_div = web.div(
    checkbox,
    task_text,
    delete_btn,
    classes=["task", priority]
)
```

```python
task_div = document.createElement("div")
task_div.className = f"task {priority}"
task_div.appendChild(checkbox)
task_div.appendChild(task_text)
task_div.appendChild(delete_btn)
```

--------------------------------

### list_devices()

Source: https://docs.pyscript.net/2026.7.3/api/media

Asynchronously retrieves a list of all available media input and output devices.

```APIDOC
## list_devices()

### Description
Retrieves a list of available media devices (cameras, microphones, speakers) accessible by the browser.

### Returns
- **List[Device]** - A list of Device objects representing the available hardware.
```

--------------------------------

### Format code with make

Source: https://docs.pyscript.net/2026.7.3/developers

Reformat the codebase to ensure consistent layout.

```makefile
make fmt
```

--------------------------------

### Request a media stream from a specific device

Source: https://docs.pyscript.net/2026.7.3/api/media

Demonstrates how to list available devices, filter for a specific camera, and request a stream from it.

```python
from pyscript.media import list_devices


# List all devices.
devices = await list_devices()

# Find a specific camera.
my_camera = None
for device in devices:
    if device.kind == "videoinput" and "USB" in device.label:
        my_camera = device
        break

# Get a stream from that specific camera.
if my_camera:
    stream = await my_camera.get_stream()
```

--------------------------------

### Define the HTML Body

Source: https://docs.pyscript.net/2026.7.3/beginning-pyscript

Sets up the user interface elements and links the Python source file and configuration.

```html
<body>
  <h1>Polyglot 🦜 💬 🇬🇧 ➡️ 🏴‍☠️</h1>
  <p>Translate English into Pirate speak...</p>
  <input type="text" id="english" placeholder="Type English here..." />
  <button id="translate-button">Translate</button>
  <div id="output"></div>
  <script type="py" src="./main.py" config="./pyscript.json"></script>
</body>
```

--------------------------------

### Clone and Configure PyScript Repository

Source: https://docs.pyscript.net/2026.7.3/developers

Commands for cloning a fork, navigating to the directory, and setting up the upstream remote.

```bash
git clone https://github.com/<YOUR USERNAME>/pyscript
```

```bash
cd pyscript
```

```bash
git remote add upstream https://github.com/pyscript/pyscript.git
```

```bash
git remote remove upstream
git remote add upstream git@github.com:pyscript/pyscript.git
```

```bash
git pull upstream main
```

--------------------------------

### Select and Use Specific Media Devices

Source: https://docs.pyscript.net/2026.7.3/user-guide/media

List available devices and use get_stream() on a specific device instance to bypass default selection.

```python
from pyscript.media import list_devices


# Find all cameras.
devices = await list_devices()
cameras = [d for d in devices if d.kind == "videoinput"]

# Use the second camera if available.
if len(cameras) > 1:
    stream = await cameras[1].get_stream()
    video = page["#my-video"]
    video.srcObject = stream
```

--------------------------------

### Initialize PyScript in HTML Body

Source: https://docs.pyscript.net/2026.7.3

Use the py script tag to link a configuration file and a main Python script within the document body.

```html
<script type="py" config="./conf.json" src="./main.py"></script>
```

--------------------------------

### Request media streams with constraints

Source: https://docs.pyscript.net/2026.7.3/api/media

Shows how to request media streams using simple boolean flags or complex dictionary constraints, and how to assign the resulting stream to a DOM element.

```python
from pyscript import document
from pyscript.media import Device


# Get default video stream.
stream = await Device.request_stream()

# Get stream with specific constraints.
stream = await Device.request_stream(
    video={"width": 1920, "height": 1080}
)

# Get audio and video.
stream = await Device.request_stream(audio=True, video=True)

# Use the stream.
video_el = document.getElementById("camera")
video_el.srcObject = stream
```

--------------------------------

### Loading a plugin in HTML

Source: https://docs.pyscript.net/2026.7.3/user-guide/plugins

Shows the correct order for loading a plugin module before the PyScript core files.

```html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">

    <!-- Plugin loads first. -->
    <script type="module" src="./log.js"></script>

    <!-- PyScript loads after. -->
    <link rel="stylesheet" 
      href="https://pyscript.net/releases/2026.7.3/core.css">
    <script type="module" 
      src="https://pyscript.net/releases/2026.7.3/core.js"></script>
</head>
<body>
    <script type="mpy">
        print("ACTUAL CODE")
    </script>
</body>
</html>
```

--------------------------------

### fs.mount(path, mode='readwrite', root='', id='pyscript')

Source: https://docs.pyscript.net/2026.7.3/api/fs

Mounts a local directory to the virtual filesystem. This triggers a browser prompt for directory selection and permission granting.

```APIDOC
## fs.mount(path, mode='readwrite', root='', id='pyscript')

### Description
Mounts a directory from the local filesystem to the virtual filesystem at the specified path. On first use, the browser will prompt the user to select a directory and grant permission.

### Parameters
- **path** (string) - Required - The mount point in the virtual filesystem.
- **mode** (string) - Optional - Access level, either 'readwrite' or 'read'. Defaults to 'readwrite'.
- **root** (string) - Optional - A hint for the file picker starting location.
- **id** (string) - Optional - An identifier to allow multiple distinct mounts at the same path. Defaults to 'pyscript'.

### Example
```python
from pyscript import fs

# Basic mount
await fs.mount("/local")

# Mount with read-only access
await fs.mount("/readonly", mode="read")
```
```

--------------------------------

### Mounting Local Directories

Source: https://docs.pyscript.net/2026.7.3/api/fs

Mounts a local directory to the virtual filesystem. Requires user interaction to grant permission on the first attempt.

```python
from pyscript import fs


# Basic mount with default settings.
await fs.mount("/local")

# Mount with read-only access.
await fs.mount("/readonly", mode="read")

# Mount with a hint to start in Downloads folder.
await fs.mount("/downloads", root="downloads")

# Mount with a custom ID to track different directories.
await fs.mount("/project", id="my-project")
```

```python
async def mount(path, mode="readwrite", root="", id="pyscript"):
    """
    Mount a directory from the local filesystem to the virtual filesystem
    at the specified `path` mount point. The `mode` can be "readwrite" or
    "read" to specify access level. The `root` parameter provides a hint
    for the file picker starting location. The `id` parameter allows multiple
    distinct mounts at the same path.

    On first use, the browser will prompt the user to select a directory
    and grant permission.

    ```python
    from pyscript import fs


    # Basic mount with default settings.
    await fs.mount("/local")

    # Mount with read-only access.
    await fs.mount("/readonly", mode="read")

    # Mount with a hint to start in Downloads folder.
    await fs.mount("/downloads", root="downloads")

    # Mount with a custom ID to track different directories.
    await fs.mount("/project", id="my-project")
    ```

    If called during a user interaction (like a button click), the
    permission dialog may be skipped if permission was previously granted.
    """
    js.console.warn("experimental pyscript.fs ⚠️")

    # Check if path is already mounted with a different ID.
    mount_key = f"{path}@{id}"
    if path in mounted:
        # Path already mounted - check if it's the same ID.
        for existing_key in mounted.keys():
            if existing_key.startswith(f"{path}@") and existing_key != mount_key:
                raise ValueError(
                    f"Path '{path}' is already mounted with a different ID. "
                    f"Unmount it first or use a different path."
                )

    details = None
    handler = None

    options = {"id": id, "mode": mode}
    if root != "":
        options["startIn"] = root

    if RUNNING_IN_WORKER:
        fs_handler = sync_with_worker.storeFSHandler(mount_key, to_js(options))

        # Handle both async and SharedArrayBuffer use cases.
        if isinstance(fs_handler, bool):
            success = fs_handler
        else:
            success = await fs_handler

        if success:
            idbm = IDBMap.new(_fs.NAMESPACE)
            details = await idbm.get(mount_key)
            handler = await _check_permission(details)
            if handler is None:
                # Force await in either async or sync scenario.
                await js.Promise.resolve(sync_with_worker.getFSHandler(details.options))
                handler = details.handler
        else:
            raise RuntimeError(_fs.ERROR)

    else:
        success = await _fs.idb.has(mount_key)

        if success:
            details = await _fs.idb.get(mount_key)
            handler = await _check_permission(details)
            if handler is None:
                handler = await _fs.getFileSystemDirectoryHandle(details.options)
        else:
            js_options = to_js(options)
            handler = await _fs.getFileSystemDirectoryHandle(js_options)
            details = {"handler": handler, "options": js_options}
            await _fs.idb.set(mount_key, to_js(details))

    mounted[path] = await interpreter.mountNativeFS(path, handler)
```

--------------------------------

### Handle Media Permissions

Source: https://docs.pyscript.net/2026.7.3/user-guide/media

Wrap stream requests in try-except blocks to gracefully handle cases where users deny access or hardware is unavailable.

```python
from pyscript.media import Device


try:
    stream = await Device.request_stream(video=True)
    # Use the stream.
    video = page["#camera"]
    video.srcObject = stream
except Exception as e:
    # Permission denied or device not available.
    print(f"Could not access camera: {e}")
    # Show a message to the user explaining what happened.
```

--------------------------------

### list_devices()

Source: https://docs.pyscript.net/2026.7.3/api/media

Returns a list of all media devices currently available to the browser, such as microphones, cameras, and speakers.

```APIDOC
## async list_devices()

### Description
Returns a list of all media devices currently available to the browser. The returned list omits devices blocked by the document Permission Policy or for which the user has not granted explicit permission.

### Usage
```python
from pyscript.media import list_devices

devices = await list_devices()
for device in devices:
    print(f"{device.kind}: {device.label} (ID: {device.id})")
```
```

--------------------------------

### Initialize and use persistent storage

Source: https://docs.pyscript.net/2026.7.3/api/storage

Open or create storage instances using a unique name. Custom storage classes can be provided to extend default dictionary behavior.

```python
from pyscript import storage


# Basic usage.
user_data = await storage("user-profile")
user_data["name"] = "Alice"
user_data["age"] = 30

# Multiple independent storages.
settings = await storage("app-settings")
cache = await storage("api-cache")

# With custom Storage class.
class ValidatingStorage(Storage):
    def __setitem__(self, key, value):
        if not isinstance(key, str):
            raise TypeError("Keys must be strings")
        super().__setitem__(key, value)

validated = await storage("validated-data", ValidatingStorage)
```

--------------------------------

### List available media devices

Source: https://docs.pyscript.net/2026.7.3/api/media

Retrieves all available media devices and demonstrates how to filter them by type. Device labels may be empty until permissions are granted.

```python
from pyscript.media import list_devices


# Get all devices.
devices = await list_devices()

# Print device information.
for device in devices:
    print(f"{device.kind}: {device.label} (ID: {device.id})")

# Filter for specific device types.
cameras = [d for d in devices if d.kind == "videoinput"]
microphones = [d for d in devices if d.kind == "audioinput"]
speakers = [d for d in devices if d.kind == "audiooutput"]
```

--------------------------------

### fetch(url, **options)

Source: https://docs.pyscript.net/2026.7.3/api/fetch

Fetches a resource from the network. The function accepts a URL and optional keyword arguments corresponding to the JavaScript RequestInit dictionary, such as method, headers, and body.

```APIDOC
## fetch(url, **options)

### Description
Fetch a resource from the network using a Pythonic interface. This function wraps the JavaScript fetch API and returns a promise that resolves to a response object.

### Parameters
- **url** (string) - Required - The URL to fetch.
- **options** (dict) - Optional - Keyword arguments corresponding to the JavaScript RequestInit dictionary (e.g., method, headers, body).

### Response Methods
- **await response.json()** - Returns JSON as Python objects.
- **await response.text()** - Returns text data.
- **await response.bytearray()** - Returns raw data as a bytearray.
- **await response.arrayBuffer()** - Returns raw data as a memoryview or bytes.
- **await response.blob()** - Returns the raw JS Blob object.

### Response Properties
- **ok** (boolean) - True if the status is in the range 200-299.
- **status** (integer) - The HTTP status code.
- **statusText** (string) - The status message.

### Usage Example
```python
# Simple GET request
response = await fetch("https://api.example.com/data")
data = await response.json()

# POST request with JSON
response = await fetch(
    "https://api.example.com/users",
    method="POST",
    headers={"Content-Type": "application/json"},
    body=json.dumps({"name": "Alice"})
)
```
```
Tokens:
Raw