Text of peps.python.org › pep-0818 as Styx crawled it on Oct 13, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

PEP 818 – Adding the Core of the Pyodide Foreign Function Interface to Python | peps.python.org

PEP 818 – Adding the Core of the Pyodide Foreign Function Interface to Python PEP 818 – Adding the Core of the Pyodide Foreign Function Interface to Python Author : Hood Chatham <roberthoodchatham at gmail.com> Sponsor : Łukasz Langa <lukasz at python.org> Discussions-To : Discourse thread Status : Draft Type : Standards Track Created : 10-Dec-2025 Python-Version : 3.16 Post-History : 05-Jan-2026 , 01-Oct-2026 Table of Contents Abstract Motivation Rationale Translating Objects Proxies Garbage Collection and Destruction of Proxies Calling Conventions Calling a Python Function from JavaScript Calling a JavaScript Function from Python Defense of the Calling Convention for a JSProxy An Example of a Disadvantage of the Calling Convention A Use Case That Is Made Simpler By This Calling Convention New Top Level Packages Specification The Pseudocode in this Document Converting Values between Python and JavaScript Implicit conversion from Python to JavaScript Implicit conversion from JavaScript to Python Error handling Executing JavaScript Code from C Executing C Code from JavaScript Calling Conventions Calling a Python Function from JavaScript Calling a JavaScript Function from Python run_js makePythonFunction JSProxy Creating a JSProxy The JSProxy Metaclass The JSProxy Base Class PyProxy Creating a PyProxy The PyProxy Base Class Deep Conversions From JavaScript to Python From Python to JavaScript Asyncio Integration The WebLoop Adapting from a Python awaitable to a JavaScript awaitable Adapting from a JavaScript awaitable to a Python awaitable The jstypes.global_this Module The jstypes package The jstypes.ffi Module The jstypes.code Module Changes to the json Module Backwards Compatibility Security Implications How to Teach This Change History Reference Implementation Acknowledgments Copyright Abstract Pyodide is a distribution of Python for JavaScript runtimes, including browsers.

Browsers are a universal computing platform. As with C for Unix family operating systems, in the browser platform all fundamental capabilities are exposed through the JavaScript language. For years, Pyodide has included a comprehensive JavaScript foreign function interface. This provides the equivalent of the os module for the JavaScript world. This PEP proposes adding the core of the Pyodide foreign function interface to Python.

Motivation The Pyodide project is a Python distribution for JavaScript runtimes. Pyodide is a very popular project. In 2025, Pyodide received over a billion requests on JsDelivr. The popularity is rapidly growing: usage has more than doubled in each of the last two years. Pyodide includes several components: A port of CPython to the Emscripten compiler toolchain (a toolchain to compile linux C/C++ programs to JavaScript and WebAssembly).

A foreign function interface for calling Python from JavaScript and JavaScript from Python. A JavaScript programmatic interface for managing the Python runtime and package installation. An ABI for native extensions. A toolchain to cross-compile Python packages compatible with that ABI for use with Pyodide. In the long run, we would like to upstream the runtime components (1)–(4) of the Pyodide project into CPython. In 2022, Christian Heimes upstreamed (1) the Emscripten port of CPython, and Emscripten is currently a tier 3 supported platform (see PEP 776 ).

PEP 783 proposes to allow Pyodide-compatible wheels to be uploaded to PyPI. What is needed for these to be Emscripten-CPython-compatible wheels is to upstream (2) the Python/JavaScript foreign function interface and (4) the ABI for native extensions. This PEP concerns partially upstreaming (2) the Python/JavaScript foreign function interface. This interface is similar to the os module for Python on linux: all IO requires going through libc and the os module provides access to libc calls to Python code.

Similarly, in a JavaScript runtime, to do any actual work requires making calls into JavaScript: for example, it is required to display content to the screen, to receive user input, to handle events, to access databases, etc. For instance, once Python has a JavaScript foreign function interface, it will be possible to support urllib on Emscripten. Downstream, supporting urllib3 , aiohttp , and httpx requires the foreign function interface.

The fact that the Pyodide foreign function interface is coupled to Pyodide creates problems for other Emscripten-CPython distributions. For instance, Emscripten-forge is a project that provides conda recipes for the Emscripten platform. They have to reimplement the Pyodide foreign function interface in order to support downstream packages that use it. Their reimplementation is slower and has various minor incompatibilities.

For this reason, the Emscripten-force maintainers strongly support adding Pyodide’s interface to CPython. In order to keep the length of this PEP reasonable, we focus on the “core” of the foreign function interface. The JavaScript interface for managing the Python runtime is left to a future PEP. Rationale Our goal here is to upstream Pyodide’s foreign function interface, without breaking backwards compatibility more than necessary for Pyodide’s large collection of existing users.

On the other hand, the best time to making breaking changes is now. With that in mind, we wish here to justify not that our design is perfect but that the costs of any changes outweigh the benefits. Translating Objects The most fundamental decision is how we translate objects from one language to the other. When translating an object, we can either choose to convert the value into a similar object in the target language, or to make a proxy that “wraps” the original object.

A few considerations apply here: Mutability: If we call a function that expects to mutate its argument, then it is important that we proxy the argument and not convert it. Otherwise, the function mutates a copy that we then throw away. So implicit conversion is only a reasonable option for immutable objects. Round trip behavior: It is strongly desirable that passing an object from Python to JavaScript back to Python results in the original Python object and vice-versa.

If the object is immutable, it is okay if the result is only equal to the original object and not the same object. If the object is mutable, it should be the same object. Performance characteristics: Converting a complex object entails a lot of up front work. If the object is only minimally used, then it may be less performant. On the other hand, each access to an object via a proxy is slower than to a native object so if the object is used a lot, converting up front is more efficient than proxying.

Proxying by default and allowing the user to explicitly convert when they want to gives the user maximum control over performance. Ergonomics: A native object is in many cases easier to work with. JavaScript has the following immutable types: string , undefined , boolean , number and bigint . It also has the special value null . Of these, string and boolean directly correspond to str and bool . We convert a number to an int if Number.isSafeInteger() returns true and otherwise we convert it to a float .

Conversely we convert float to number and we convert int to number unless it exceeds 2**53 in which case we convert it to a bigint . We make a new subclass of int called JSBigInt to act as the conversion for bigint .``undefined`` is the default value for a missing argument so it corresponds to None . We invent a new falsey singleton Python value jsnull of type JSNull to act as the conversion of null . All other types are proxied.

In particular, even though tuples are immutable, they have no equivalent in JavaScript so we proxy them. They can be manually converted to an Array with the toJs() method if desired. Proxies A JSProxy is a Python object used for accessing a JavaScript object. While the JSProxy exists, the underlying JavaScript object is kept in a table which keeps it from being ga

The rest of this page is on the live site.