PyScript Python ↔ JavaScript bridge: default global reachability of imported modules

Default Visibility and Scoping

By default, Python modules imported within a PyScript environment are not automatically exposed to the JavaScript global window object. They remain scoped to the Pyodide runtime instance. While JavaScript can invoke the Python interpreter to execute code, it cannot directly reference a Python module as a native JavaScript object unless that module has been explicitly proxied or assigned to the global namespace.

The Visibility Model

The intended visibility model is one of isolation by default. PyScript acts as a wrapper around Pyodide, which maintains a distinct memory boundary between the WebAssembly-based Python environment and the browser's JavaScript engine. This ensures that internal Python names, imported libraries, and user-defined functions do not pollute the JavaScript global namespace.

How to Isolate or Expose Code

Because isolation is the default state, you do not need a configuration to "hide" internal names. However, if you need to control exactly what is reachable, follow these patterns:

• To keep code private: Simply define your functions and imports within your <py-script> or .py files. They will be accessible to other Python code in the same runtime but invisible to window.my_function().
• To explicitly expose a function: Use the Pyodide proxy system or assign the object to the JavaScript window object from within Python:

  import js
  
  def my_exposed_function():
      return "Hello from Python!"
  
  js.window.my_exposed_function = my_exposed_function
  

• To access Python objects without global pollution: Use pyodide.globals.get("variable_name") from JavaScript to retrieve a specific object from the Python global scope without attaching it to window.

Verification Steps

To verify the current scoping behavior in your environment, you can run the following test:

1. Import a module (e.g., import math) inside your PyScript tag.
2. Open the browser developer console.
3. Type window.math. It should return undefined.
4. Type pyodide.globals.get("math"). This should return the Python module proxy, confirming the module is present in the runtime but isolated from the JS global scope.

Note: This behavior assumes a standard PyScript/Pyodide implementation. If you are using a custom Pyodide build or a specific legacy version of PyScript, please specify the version number, as proxying behavior has evolved.