Skip to content

The pyscript API

Important

These API docs are auto-generated from our source code. To suggest changes or report errors, please do so via our GitHub repository. The source code for these APIs is found here in our repository.

This is the main pyscript namespace. It provides the primary Pythonic API for users to interact with the browser's own API. It includes utilities for common activities such as displaying content, handling events, fetching resources, managing local storage, and coordinating with web workers.

The most important names provided by this namespace can be directly imported from pyscript, for example:

from pyscript import display, HTML, fetch, when, storage, WebSocket

The following names are available in the pyscript namespace:

  • RUNNING_IN_WORKER: Boolean indicating if the code is running in a Web Worker.
  • PyWorker: Class for creating Web Workers running Python code.
  • config: Configuration object for pyscript settings.
  • current_target: The element in the DOM that is the current target for output.
  • document: The standard document object, proxied in workers.
  • window: The standard window object, proxied in workers.
  • js_import: Function to dynamically import JS modules.
  • js_modules: Object containing JS modules available to Python.
  • sync: Utility for synchronizing between worker and main thread.
  • display: Function to render Python objects in the web page.
  • HTML: Helper class to create HTML content for display.
  • fetch: Function to perform HTTP requests.
  • Storage: Class representing browser storage (local/session).
  • storage: Object to interact with browser's local storage.
  • WebSocket: Class to create and manage WebSocket connections.
  • when: Function to register event handlers on DOM elements.
  • Event: Class representing user defined or DOM events.
  • py_import: Function to lazily import Pyodide related Python modules.

If running in the main thread, the following additional names are available:

  • create_named_worker: Function to create a named Web Worker.
  • workers: Object to manage and interact with existing Web Workers.

All of these names are defined in the various submodules of pyscript and are imported and re-exported here for convenience. Please refer to the respective submodule documentation for more details on each component.

Note

Some notes about the naming conventions and the relationship between various similar-but-different names found within this code base.

import pyscript

The pyscript package contains the main user-facing API offered by PyScript. All the names which are supposed be used by end users should be made available in pyscript/__init__.py (i.e., this source file).

import _pyscript

The _pyscript module is an internal API implemented in JS. End users should not use it directly. For its implementation, grep for interpreter.registerJsModule("_pyscript",...) in core.js.

import js

The js object is the JS globalThis, as exported by Pyodide and/or Micropython's foreign function interface (FFI). As such, it contains different things in the main thread or in a worker, as defined by web standards.

import pyscript.context

The context submodule abstracts away some of the differences between the main thread and a worker. Its most important features are made available in the root pyscript namespace. All other functionality is mostly for internal PyScript use or advanced users. In particular, it defines window and document in such a way that these names work in both cases: in the main thread, they are the "real" objects, in a worker they are proxies which work thanks to coincident.

from pyscript import window, document

These are just the window and document objects as defined by pyscript.context. This is the blessed way to access them from pyscript, as it works transparently in both the main thread and worker cases.