Managing Python Dependencies and JS Interop in PyScript

The Challenge of Browser-Based Python

Executing Python in a browser via PyScript requires a shift in how you handle dependencies and environment interaction. Because the code runs inside a WebAssembly (Wasm) sandbox, you cannot use pip install at runtime or access the local OS file system. The primary takeaway is that dependency management must be declared in the HTML configuration and DOM interaction must occur through the Pyodide Foreign Function Interface (FFI).

Configuring the Runtime Environment

PyScript uses the <py-config> tag to define the environment before the Python interpreter initializes. This is where you specify required packages and configuration files. PyScript primarily relies on Pyodide, a port of CPython to WebAssembly, which means only pure-Python packages or those specifically compiled for Wasm are compatible.

Worked Example: DOM Manipulation and External Packages

The following example demonstrates how to import a package (micropip is used internally by PyScript for package loading) and interact with an HTML element.

<!-- Load PyScript assets in the head -->
<link rel="stylesheet" href="https://pyscript.net/releases/2024.1.1/core.css">
<script type="module" src="https://pyscript.net/releases/2024.1.1/core.js"></script>

<!-- Define dependencies and configuration -->
<py-config>
    packages = ["pandas"]
</py-config>

<div id="output">Waiting for Python...</div>

<py-script>
import pandas as pd
from pyscript import display

# Create a simple DataFrame
data = {"Name": ["PyScript", "Pyodide"], "Type": ["Framework", "Runtime"]}
df = pd.DataFrame(data)

# Use the 'display' function to inject content into the DOM
# This replaces the content of the target element or appends to it
display(df, target="output")
</py-script>

Execution and Permissions

• Where to run: This code runs entirely in the client's browser. No backend server is required other than a basic HTTP server to serve the HTML file.
• Permissions: The code operates under browser security policies (Same-Origin Policy). It cannot access C:\ or /home/user.
• Expected Result: The <div id="output"> will be updated with a rendered HTML table representing the pandas DataFrame.

Understanding the Pyodide FFI

When you need to move beyond the display() helper, you use the Foreign Function Interface (FFI). This allows Python to call JavaScript functions and vice versa. In PyScript, JavaScript objects are wrapped in a Python proxy.

To call a JavaScript function like alert(), you can use the js module:

from js import alert

# This triggers a native browser alert dialog
alert("Hello from Python!")

Limitations and Engineering Trade-offs

The Cold Start Problem

The most significant limitation is the initial load time. The browser must download the Pyodide Wasm runtime and the Python standard library before the first line of code executes. For a basic page, this can be several megabytes. To mitigate this, use a loading indicator in your HTML to prevent the user from seeing a blank screen during initialization.

The Virtual File System (VFS)

Since the browser cannot access the hard drive, Pyodide implements a Virtual File System. If your Python code uses open('data.txt', 'r'), it is looking at a memory-mapped file system. To use actual data, you must either fetch the data via an HTTP request or define the files in your <py-config> under a files key.

Performance Overhead

While Wasm is fast, it is not native. Computationally intensive loops in Python will run slower than they would on a local machine. For heavy data processing, leverage libraries like pandas or numpy that are pre-compiled in Wasm to utilize optimized C-extensions.

Common Implementation Mistakes

Mistake	Consequence	Correction
Using pip install in <py-script>	Runtime Error	List packages in <py-config>.
Attempting os.listdir('/')	Empty or restricted list	Use the Pyodide VFS or fetch files via URL.
Importing C-extensions not in Pyodide	ImportError	Verify package compatibility on the Pyodide official list.

Verification and Diagnostics

To verify the runtime is functioning correctly, open the Browser Developer Tools (F12) and check the Console. If the runtime fails to initialize, you will see Wasm compilation errors or 404s for the core.js assets. You can also type window.pyodide in the console to verify the underlying runtime object is instantiated.