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:

1. 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.
2. 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.
3. 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.
4. 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 garbage collected.

A PyProxy is a JavaScript object used for accessing a Python object. When a PyProxy is created, the reference count of the underlying Python object is incremented. When the .destroy() method is called, the reference count of the underlying Python object is decremented and the proxy is disabled. Any further attempt to use it raises an error.

The base JSProxy implements property access, equality checks, __repr__, __eq__, __bool__, and a handful of other convenience methods. We also define a large number of mixins by mapping abstract Python object protocols to abstract JavaScript object protocols (and vice-versa). The mapping described in this PEP is as follows:

Base proxies (properties common to all objects):

• __getattribute__ <==> Reflect.get (proxy handler)
• __setattr__ <==> Reflect.set (proxy handler)
• __eq__ <==> === (object identity)
• __repr__ <==> toString

For the __str__ implementation, we inherit the default implementation which uses __repr__.

We implement the following mappings between protocols as mixins. When we create a proxy, we feature detect which of these abstract and concrete protocols it supports and create a class for the proxy with the appropriate mixins.

• __iter__ <==> [Symbol.iterator]
• __next__ <==> next
• __len__ <==> length, size
• __getitem__ <==> get
• __setitem__, __delitem__ <==> set, delete
• __contains__ <==> includes, has
• __call__ <==> Reflect.apply (proxy handler)
• Generator <==> Generator
• Exception <==> Error
• MutableSequence <==> Array

If a JavaScript object has a [Symbol.dispose]() method, we make the Python object into a context manager, but we do not presently use context managers to implement [Symbol.dispose]().

JavaScript also has Reflect.construct (the new keyword). Callable JSProxies have a method called new() which corresponds to Reflect.construct.

Garbage Collection and Destruction of Proxies

The most fundamental difficulty that we face is the existence of two garbage collectors, the Python garbage collector and the JavaScript garbage collector. Any reference loop from Python to JavaScript back to Python will be leaked. Furthermore, even if there is no loop, the JavaScript garbage collector has no idea how much memory a PyProxy owns nor how much memory pressure the Python garbage collector faces.

For this reason, we need to include a way to manually break references between languages. In Python, destructors are run eagerly when the reference count of an object reaches 0. Thus, if a programmer wishes to manually release a JavaScript object, they can delete all references to it and after that the JavaScript garbage collector will be able to reclaim it.

On the other hand, JavaScript finalizers are not reliable. The proposal that introduced them to the language says the following:

If an application or library depends on GC [calling a finalizer] in a timely, predictable manner, it’s likely to be disappointed: the cleanup may happen much later than expected, or not at all.

…

It’s best if [finalizers] are used as a way to avoid excess memory usage, or as a backstop against certain bugs, rather than as a normal way to clean up external resources.

https://github.com/tc39/proposal-weakrefs?tab=readme-ov-file#a-note-of-caution

A PyProxy has a destroy() method that manually detaches the PyProxy and releases the Python reference. We consider destroying a PyProxy to be the correct, normal way to clean it up. As recommended by the proposal, the finalizer is treated as a backstop. In the Pyodide test suite, we require that every PyProxy be manually destroyed in the majority of the tests. This helps to ensure that our APIs are designed in a way that keeps this ergonomic.

Calling Conventions

Defense of the Calling Convention for a JSProxy

The calling convention from JavaScript into Python is uncontroversial so we will not defend it. The calling convention from Python into JavaScript is more controversial so we will explain here why we believe it is a better design than the alternatives.

The main disadvantage of this design is that it is not as ergonomic in cases where the callee is going to persist its arguments. However, we argue that the benefits outweigh this.

The biggest advantage of this approach is that it makes it possible to use JavaScript functions that are unaware of the existence of Python without memory leaks. Another advantage is that registering a finalizer for a PyProxy is somewhat expensive and so avoiding this step can substantially decrease the overhead for certain Python to JavaScript calls.

from jstypes.code import run_js
set_x = run_js("(x) => { globalThis.x = x; }")
get_x = run_js("(x) => globalThis.x")

set_x({})
get_x()

This borrowed proxy was automatically destroyed at the end of a function call.

(x) => {
    globalThis.x?.destroy?.();
    globalThis.x = x?.copy?.() ?? x;
}

from jstypes.ffi import JSDoubleProxy
from jstypes.code import run_js

setXJs = run_js("(x) => { globalThis.x = x; }")
def set_x(x):
    orig_x = get_x()
    if isinstance(orig_x, JSDoubleProxy):
        orig_x.destroy()
    xpx = create_proxy(x)
    setXJs(xpx)

@create_proxy
def main_loop():
    update()
    buf = render()
    drawImageToCanvas(buffer)
    requestAnimationFrame(main_loop)

New Top Level Packages

We introduce a new top level package called jstypes.

The jstypes package three two modules: jstypes.code and jstypes.ffi. The jstypes.global_this package is the JavaScript global scope globalThis. What set of values are present on the jstypes.global_this module depends on the JavaScript runtime and whether the Python runtime is in the main thread or a worker thread. For instance from jstypes.global_this import Buffer will succeed in Node but fail in a browser.

jstypes.code exposes the run_js function.

jstypes.ffi exposes the following functions:

create_proxy

Creates a PyProxy from Python. Used to control the lifetime of the PyProxy from Python.

create_once_callable

Create a PyProxy from a Python callable which can only be called once. Decrements the reference count on the Python callable if called or garbage collected.

jsnull

Special value that converts to/from the JavaScript null value.

JSNull

The type of jsnull.

JSBigInt

Subtype of int that converts to/from JavaScript bigint.

to_js

Does a deep conversion of a Python value to JavaScript.

We also include JSProxy and its subtypes:

JSProxy

This is type(run_js("({})"))

JSArray

This is type(run_js("[]")).

JSCallable

This is type(run_js("() => {}")).

JSDoubleProxy

This is type(create_proxy({})).

JSException

This is type(run_js("new Error()")).

JSGenerator

This is type(run_js("(function*(){})()")).

JSIterable

This is type(run_js("({[Symbol.iterator](){}})")).

JSIterator

This is type(run_js("({next(){}})")).

JSMap

This is type(run_js("({get(){}})")).

JSMutableMap

This is type(run_js("new Map()")).

The Pseudocode in this Document

The pseudocode in this PEP is generally written in Python or JavaScript. We leave out most resource management and exception handling except when we think it is particularly interesting. If an error is raised, we implicitly clean up all resources and propagate the error. A large fraction of the real code consists of resource management and exception handling.

For the most part the code works as written but in a few spots we directly call a C API from Python or otherwise write code that wouldn’t run but whose intent we believe is clear.

In Python code when we want to execute a JavaScript function inline, we write it like:

jsfunc = run_js("(x, y) => doSomething")
jsfunc(x, y)

Conversely, when we want to execute Python code inline in JavaScript we write it like this:

const pyfunc = makePythonFunction(`
    def pyfunc(x, y):
        # do something
`);
pyfunc(x, y)

For the most part, this code could actually be used if performance was not a concern. In some places there may be bootstrapping issues.

Our first task is to define the Python callable run_js and the JavaScript callable makePythonFunction. run_js is a JSProxy and makePythonFunction is a PyProxy.

To make sense of this, we need to describe

1. how we convert values from JavaScript to Python and from Python to JavaScript
2. how to call a Python function from JavaScript and how to call a JavaScript function from Python

We can directly represent a PyObject* as a number in JavaScript so we can describe the process of calling a PyObject* from JavaScript. On the other hand, JavaScript objects are not directly representable in Python, we have to create a JSProxy of it. We describe first the process of calling a JSProxy, the process of creating it is described in the section on JSProxies.

Converting Values between Python and JavaScript

A few primitive types are implicitly converted between Python and JavaScript. Implicit conversions are supposed to round trip, so that when converting from Python to JavaScript back to Python or from JavaScript to Python back to JavaScript, the result is the same primitive as we started with. The one exception to this is that a JavaScript BigInt that is smaller than 2^53 round trips to a Number. We convert undefined to None and introduce the special falsey singleton jstypes.ffi.jsnull to convert null. We also introduce a subtype of int called jstypes.ffi.JSBigInt which converts to and from JavaScript bigint.

Implicit conversions are done with the C functions _Py_python2js and _Py_js2python(). These functions cannot be called directly from Python code because the JSVal type is not representable in Python.

Error handling

At the boundary between JavaScript and C, we have to translate errors.

try {
    result = some_c_function();
} catch (e) {
    // If an error was thrown here, the C runtime state is corrupted.
    // Signal a fatal error and tear down the interpreter.
    fatal_error(e);
}
// Depending on the API, we check for -1, 0, _PyErr_Occurred(), etc to
// decide if an error occurred.
if (result === -1) {
    // This function takes the error flag and converts it to a JavaScript
    // exception. It leaves the error flag cleared.
    throw __Py_pythonexc2js();
}

Calling Conventions

function callPyObjectKwargs(pyfuncptr, jsargs, kwargs) {
    const num_pos_args = jsargs.length;
    const kwargs_names = Object.keys(kwargs);
    const kwargs_values = Object.values(kwargs);
    const num_kwargs = kwargs_names.length;
    jsargs.push(...kwargs_values);
    // apply the usual error handling logic for calling from JavaScript into C.
    return _PyProxy_apply(pyfuncptr, jsargs, num_pos_args, kwargs_names, num_kwargs);
}

run_js

The Python object jstypes.code.run_js is defined as follows:

1. Execute the JavaScript code eval and store the result into jseval.
2. Run _Py_js2python(jseval) and store the result into run_js.

makePythonFunction

Unlike run_js, the JavaScript object makePythonFunction is strictly for the sake of our pseudocode and will not be included as part of the API. We define define makePythonFunction as follows:

def make_python_function(code):
    mod = ast.parse(code)
    if isinstance(mod.body[0], ast.FunctionDef):
        d = {}
        exec(code, d)
        return d[mod.body[0].name]
    return eval(code)

1. Let make_python_function be the function above.
2. Run _Py_python2js(make_python_function) and store the result into makePythonFunction.

JSProxy

We define 14 different abstract protocols that a JavaScript object can support. These each correspond to a JSProxy type flag. There are also two additional flags IS_PY_JSON_DICT and IS_PY_JSON_SEQUENCE which are set by the JSProxy.as_py_json() method and do not reflect properties of the underlying JavaScript object.

HAS_GET

Signals whether or not the JavaScript object has a get() method. If present, used to implement __getitem__ on the JSProxy.

HAS_HAS

Signals whether or not the JavaScript object has a has() method. If present, used to implement __contains__ on the JSProxy.

HAS_INCLUDES

Signals whether or not the JavaScript object has an includes() method. If present, used to implement __contains__ on the JSProxy. We prefer to use has() to includes() if both are present.

HAS_LENGTH

Signals whether or not the JavaScript object has a length or size property. Used to implement __len__ on the JSProxy.

HAS_SET

Signals whether or not the JavaScript object has a set() method. If present, used to implement __setitem__ on the JSProxy. We also assume that there is a delete() method and use it to support __delitem__.f

HAS_DISPOSE

Signals whether or not the JavaScript object has a [Symbol.dispose]() method. If present, used to implement __enter__ and __exit__.

HAS_ASYNC_DISPOSE

Signals whether or not the JavaScript object has a [Symbol.asyncDispose]() method. If present, used to implement __aenter__ and __aexit__.

IS_ARRAY

Signals whether Array.isArray() applied to the JavaScript object returns true. If present, the JSProxy will be an instance of collections.abc.MutableSequence.

IS_ARRAY_LIKE

We set this if Array.isArray() returns false and the object has a length property and IS_ITERABLE. If present, the JSProxy will be an instance of collections.abc.Sequence. This is the case for many interfaces defined in the webidl such as NodeList

IS_CALLABLE

Signals whether the typeof the JavaScript object is "function". If present, used to implement __call__ on the JSProxy. Any keyword arguments will be put into a JavaScript object and passed as the last argument to the JavaScript function. It will also be used to implement a new method such that jscallable.new(*args, **kwargs) is shorthand for Reflect.construct(jsfunction, *args, **kwargs).

IS_ERROR

Signals whether the JavaScript object is an Error. If so, the JSProxy it will subclass Exception so it can be raised.

IS_AWAITABLE

Signals whether the JavaScript object has a then() method. If present, used to implement __await__. See Asyncio Integration for details.

IS_GENERATOR

Signals whether the JavaScript object is a generator. If so, the JSProxy will be an instance of collections.abc.Generator.

IS_ASYNC_GENERATOR

Signals whether the JavaScript object is an async generator. If so, we implement asend(), athrow() and aclose() methods.

IS_ITERABLE

Signals whether the JavaScript object has a [Symbol.iterator] method or the IS_PY_JSON_DICT flag is set. If so, we use it to implement __iter__ on the JSProxy.

IS_ASYNC_ITERABLE

Signals whether the JavaScript object has a [Symbol.asyncIterator]() method. If present, is used to implement __aiter__.

IS_ITERATOR

Signals whether the JavaScript object has a next() method and no [Symbol.asyncIterator] method. If so, we use it to implement __next__ on the JSProxy. (If there is a [Symbol.asyncIterator] method, we assume that the next() method should be used to implement __anext__.)

IS_ASYNC_ITERATOR

Signals whether the JavaScript object has a next() method and a [Symbol.asyncIterator]() method. (If it only has a next() method, we assume it’s a synchronous iterator.) If present, is used to implement __anext__.

IS_PY_JSON_DICT

This is set on a JSProxy by the as_py_json() method if it is not an Array. When this is set, __getitem__ on the JSProxy will turn into attribute access on the JavaScript object. Also, the return values from iterating over the proxy or indexing it will also have IS_PY_JSON_DICT or IS_PY_JSON_SEQUENCE set as appropriate.

IS_PY_JSON_SEQUENCE

This is set on a JSProxy by the as_py_json() method if it is an Array. When this is set, when indexing or iterating the JSProxy we’ll call as_py_json() on the result.

IS_MAPPING

We set this if the flags HAS_GET, HAS_LENGTH, and IS_ITERABLE are set, or if IS_PY_JSON_DICT is set. In this case, the JSProxy will be an instance of collections.abc.Mapping.

IS_MUTABLE_MAPPING

We set this if the flags IS_MAPPING and HAS_SET are set or if IS_PY_JSON_DICT is set. In this case, the JSProxy will be an instance of collections.abc.MutableMapping.

IS_BUFFER

Signals whether the JavaScript object is a TypedArray or ArrayBuffer. If set, we add methods jsbuffer.assign(py_buffer) which copies data from the Python buffer into the JavaScipt buffer, jsbuffer.assign_to(py_buffer) which copies data from the JavaScript buffer into the Python buffer, jsbuffer.from_file(file) which reads len(jsbuffer) bytes from file into jsbuffer, jsbuffer.to_file(file) which writes len(jsbuffer) bytes from jsbuffer into file and conversion methods to_bytes(), to_memoryview(), and to_string() which convert the buffer to various Python types.

d = {}
d.update(run_js("[['a', 'b'], [1, 2]]"))
assert d == {"a" : "b", 1 : 2}
# The result if we didn't filter out Array.keys would be as follows:
assert d != {1 : ['a', 'b'], 2: [1, 2]}

def normalize_python_keywords(attr):
    stripped = attr.strip("_")
    if not keyword.iskeyword(stripped):
        return attr
    if stripped != attr:
        return attr[:-1]
    return attr

function js_bool(val) {
    // if it's a falsey JS object, return false
    if (!val) {
        return false;
    }
    // We also want to return false on container types with size 0.
    if (val.size === 0) {
        // Return true for HTML elements even if they have a size of zero.
        if (val instanceof HTMLElement) {
            return true;
        }
        return false;
    }
    // A function with zero arguments has a length property equal to
    // zero. Make sure we return true for this.
    if (val.length === 0 && Array.isArray(val)) {
        return false;
    }
    // An empty buffer
    if (val.byteLength === 0) {
        return false;
    }
    return true;

}

class JSProxy(metaclass=_JSProxyMetaClass):
    def __eq__(self, other: JSProxy) -> bool:
        ...

    def __bool__(self):
        return js_bool(self)

    @property
    def js_id(self) -> int:
        """
        This returns an integer with the property that jsproxy1 == jsproxy2
        if and only if jsproxy1.js_id == jsproxy2.js_id.

        JSProxy is not hashable, so this allows making dictionaries or sets
        that key on JavaScript object identity.
        """
        ...

    def as_py_json(self) -> JSProxy:
        """
        Return a proxy that adapts from JavaScript JSON to Python JSON.

        This is intended so that JSON.parse(s).as_py_json() has an identical
        interface to json.loads(s).
        """

    def to_py(self, *, depth: int = -1, default_converter: Callable[[JSProxy], Any] | None = None) -> Any:
        """
        Deep convert from JavaScript to Python. See section on deep conversions.
        """
        ...

    def object_entries(self) -> JSProxy:
        """Call Object.entries on the JavaScript object."""

    def object_keys(self) -> JSProxy:
        """Call Object.keys on the JavaScript object."""

    def object_values(self) -> JSProxy:
        """Call Object.values on the JavaScript object."""

    def to_weakref(self) -> JSProxy:
        """Wrap the JavaScript object in a WeakRef."""

PyProxy

We define 12 mixins that a Python object may support that affect the type of the PyProxy we make from it.

HAS_GET

We set this flag if the Python object has a __getitem__ method. If present, we use it to implement a get() method on the PyProxy.

HAS_SET

We set this flag if the Python object has a __setitem__ method. If present, we use it to implement a set() method on the PyProxy. We also assume that the Python object has a __delitem__ method and use it to implement a delete() method on the PyProxy.

HAS_CONTAINS

We set this flag if the Python object has a __contains__ method. If present, we use it to implement a has() method on the PyProxy.

HAS_LENGTH

We set this flag if the Python object has a __len__ method. If present, we use it to implement a length getter on the PyProxy.

IS_CALLABLE

We set this flag if the Python object has a __call__ method. If present, we make the PyProxy an instance of Function. We also add functions captureThis and callKwargs. captureThis returns a PyProxy that when called will pass thisArg as the first argument. This returned PyProxy shares its lifetime with the original PyProxy. callKwargs takes as its last argument a kwargs argument which should be a JavaScript object.

IS_DICT

We set this flag if the Python object is of exact type dict. If present, we will make property pyproxy.some_property fall back to pyobj.__getitem__("some_property") if getattr(pyobj, "some_property") raises an AttributeError.

IS_AWAITABLE

We set this flag if the Python object has a __await__ method. If this flag is set, we use it to implement then(), catch(), and finally() methods on the PyProxy. See Asyncio Integration for more details.

IS_GENERATOR

We set this flag if the Python object is an instance of collections.abc.Generator. If present, we make the PyProxy implement the methods of a JavaScript generator.

IS_ASYNC_GENERATOR

We set this flag if the Python object is an instance of collections.abc.AsyncGenerator. If present, we make the PyProxy implement the methods of a JavaScript async generator.

IS_ITERABLE

We set this flag if the Python object has a __iter__ method. If present, we use it to implement a [Symbol.iterator]() method on the PyProxy.

IS_ASYNC_ITERABLE

We set this flag if the Python object has an __aiter__ method. If present, we use it to implement a [Symbol.asyncIterator]() method on the PyProxy.

IS_ITERATOR

We set this flag if the Python object has a __next__ method. If present, we use it to implement a next() method on the PyProxy. We also include a [Symbol.iterator]() implementation that returns the PyProxy itself.

IS_ASYNC_ITERATOR

We set this flag if the Python object has an __anext__ method. If present we use it to implement a next() method. We also include [Symbol.asyncIterator]() that returns the PyProxy itself.

IS_SEQUENCE

We set this flag if the Python object is an instance of collections.abc.Sequence. If it is present, we use it to implement all of the Array.prototype methods that don’t mutate on the PyProxy.

IS_MUTABLE_SEQUENCE

We set this flag if the Python object is an instance of collections.abc.MutableSequence. If it is present, we use it to implement all Array.prototype methods on the PyProxy.

IS_JS_JSON_DICT

We set this flag when the asJsJson() method is used on a dictionary. If this flag is set, property access on the PyProxy will _only_ look at values from __getitem__ and not at attributes on the Python object, with exceptions for “copy”, “constructor”, “destroy”, and “toString”. We also will call asJsJson() on the result of indexing or iterating the PyProxy.

IS_JS_JSON_SEQUENCE

We set this flag when the asJsJson() is used on a Sequence. If this flag is set, we will call asJsJson() on the result of indexing or iterating the PyProxy.

IS_BUFFER

We set this flag if the Python object has a __buffer__ method. If this flag is set, we use it to implement the getBuffer() method which returns a JavaScript view on the Python buffer. We increment the reference count on the Python buffer and returned object has a [Symbol.dispose]() method that decrements the reference count. The returned object has a data field with an appropriate TypedArray containing the data, and also fields readonly, format, offset, itemsize, shape, strides, c_contiguous, and f_contiguous, which have the same meaning as the corresponding fields on a memoryview.

A PyProxy is made up of a mixture of a JavaScript class and a collection of ES6 Proxy handlers. Depending on which flags are present, we construct our class out of an appropriate collection of mixins and an appropriate choice of handlers.

When a PyProxy is created, we increment the reference count of the wrapped Python object. When a PyProxy is destroyed, we decrement the reference count and mark it as destroyed. As a result, if we attempt to do anything with the PyProxy, we will call _Py_js2python() on it and an error will be thrown.

Deep Conversions

We define JSProxy.to_py() to make deep conversions from JavaScript to Python and jstypes.ffi.to_js() to make deep conversions from Python to JavaScript. Note that it is not intended that these are inverse functions to each other.

def pair_converter(jsobj, convert, cache_conversion):
    if jsobj.constructor.name != "Pair":
        return jsobj
    result = []
    cache_conversion(jsobj, result)
    result.append(convert(jsobj.first))
    result.append(convert(jsobj.second))
    return result

Asyncio Integration

To make asyncio work, we need an implementation of an event loop and a way to adapt between JavaScript awaitables and Python awaitables.

JavaScript runtimes contain a single global JavaScript event loop which is always running and has no lifecycle that can be accessed from user code. All IO in JavaScript runtimes goes through JavaScript and so any asynchronous Python code that actually waits on IO is ultimately waiting on some JavaScript promise. Thus, there is essentially only one useful design for an event loop.

JavaScript awaitables and Python awaitables have similar APIs. The key subtleties that come up are around lifetimes and around the fact that Python coroutines are lazy (they need to be scheduled before they will do any real work). It is easy to make a lazy JavaScript awaitable, and Pyodide once produced them but we found in real world testing that it broke compatibility with a lot of JavaScript code. For this reason, if we ever convert a Python coroutine into a PyProxy we always schedule it at the same time.

def call_later(self, delay, callback, *args, context) -> asyncio.Handle:
    if delay < 0:
        raise ValueError("Can't schedule in the past")
    h = asyncio.Handle(callback, args, self, context=context)
    def run_handle():
        if h.cancelled():
            return
        h._run()

    from jstypes.global_this import setTimeout
    setTimeout(
        create_once_callable(run_handle),
        min(delay * 1000, _MAX_TIMEOUT_MS),
    )

    return h

def pyawaitable_to_promise(pyawaitable):
    # Make sure pyawaitable is scheduled.
    pyawaitable = ensure_future(pyawaitable)
    jspromise = run_js("Promise.withResolvers()")
    def callback(fut):
        try:
            jspromise.resolve(fut.result())
        except BaseException as e:
            jspromise.reject(e)
    pyawaitable.add_done_callback(callback)
    return jspromise.promise

def __await__(self):
    return jsawaitable_to_pyawaitable(self).__await__()

def jsawaitable_to_pyawaitable(jsawaitable, done_callback=None):
    from jstypes.global_this import Promise

    future = asyncio.get_event_loop().create_future()
    jsawaitable_to_pyawaitable_js(jsawaitable, future.set_result, future.set_exception, done_callback)
    return future

function jsawaitable_to_pyawaitable_js(jsawaitable, set_result, set_exception, done_callback) {
    // normalize any exotic awaitable into a Promise
    jsawaitable = Promise.resolve(jsawaitable);

    // Take ownership of both handle_result and handle_exception
    _Py_IncRef(handle_result);
    _Py_IncRef(handle_exception);
    let used = false;
    function checkUsed() {
        if (used) {
            throw new Error("One of the promise handles has already been called.");
        }
    }
    // We release both handle_result and handle_exception when either is called.
    function destroy() {
        checkUsed();
        used = true;
        _Py_DecRef(handle_result);
        _Py_DecRef(handle_exception);
        if (done_callback) {
            done_callback();
        }
    }
    function onFulfilled(res) {
        checkUsed();
        try {
            return handle_result(res);
        } finally {
            destroy();
        }
    }
    function onRejected(err) {
        checkUsed();
        try {
            return handle_exception(err);
        } finally {
            destroy();
        }
    }
    jsawaitable.then(set_result, set_exception);
}

The jstypes.global_this Module

The jstypes.global_this module is a reference to the JavaScript globalThis object. globalThis is the JavaScript equivalent of the Python builtins module. The exact set of properties defined on it depends on the JavaScript runtime and any additional properties that have been added by user code.

The jstypes package

This has an empty __init__.py and two submodules.

def destroy_proxies(proxies):
    for proxy in proxies:
        proxy.destroy()

Changes to the json Module

The json module will be updated to serialize jsnull to null.