pyodide.ffi#

Exceptions:

`ConversionError`	An error thrown when conversion between JavaScript and Python fails.
`JsException`	A wrapper around a JavaScript Error to allow it to be thrown in Python.

Classes:

JsProxy()

A proxy to make a JavaScript object behave like a Python object

Functions:

`create_once_callable`(obj, /)	Wrap a Python callable in a JavaScript function that can be called once.
`create_proxy`(obj, /, *[, capture_this, ...])	Create a `JsProxy` of a `PyProxy`.
`destroy_proxies`(pyproxies, /)	Destroy all PyProxies in a JavaScript array.
`register_js_module`(name, jsproxy)	Registers `jsproxy` as a JavaScript module named `name`.
`to_js`(obj, /, *[, depth, pyproxies, ...])	Convert the object to JavaScript.
`unregister_js_module`(name)	Unregisters a JavaScript module with given name that has been previously registered with `pyodide.registerJsModule` or `pyodide.ffi.register_js_module`.

exception pyodide.ffi.ConversionError#: An error thrown when conversion between JavaScript and Python fails.

exception pyodide.ffi.JsException#

A wrapper around a JavaScript Error to allow it to be thrown in Python. See Errors.

property js_error: pyodide.JsProxy#: The original JavaScript error

class pyodide.ffi.JsProxy#

A proxy to make a JavaScript object behave like a Python object

For more information see the Type translations documentation. In particular, see the list of __dunder__ methods that are (conditionally) implemented on JsProxy.

append(object: Any) → None#

Append object to the end of the list.

Present only if the wrapped Javascript object is an array.

assign(rhs: Any, /) → None#

Assign from a Python buffer into the JavaScript buffer.

Present only if the wrapped JavaScript object is an ArrayBuffer or an ArrayBuffer view.

assign_to(to: Any, /) → None#

Assign to a Python buffer from the JavaScript buffer.

Present only if the wrapped JavaScript object is an ArrayBuffer or an ArrayBuffer view.

catch(onrejected: collections.abc.Callable[[Any], Any], /) → pyodide.Promise#

The Promise.catch API, wrapped to manage the lifetimes of the handler.

Present only if the wrapped JavaScript object has a “then” method. Pyodide will automatically release the references to the handler when the promise resolves.

count(x: Any) → int#

Return the number of times x appears in the list.

Present only if the wrapped Javascript object is an array.

extend(other: collections.abc.Iterable[Any]) → None#

Extend array by appending elements from the iterable.

Present only if the wrapped Javascript object is an array.

finally_(onfinally: collections.abc.Callable[[Any], Any], /) → pyodide.Promise#

The Promise.finally API, wrapped to manage the lifetimes of the handler.

Present only if the wrapped JavaScript object has a “then” method. Pyodide will automatically release the references to the handler when the promise resolves. Note the trailing underscore in the name; this is needed because finally is a reserved keyword in Python.

from_file(file: io.IOBase, /) → None#

Reads from a file into a buffer.

Will try to read a chunk of data the same size as the buffer from the current position of the file.

Present only if the wrapped Javascript object is an ArrayBuffer or an ArrayBuffer view.

Example

>>> import pytest; pytest.skip()
>>> from js import Uint8Array
>>> # the JsProxy need to be pre-allocated
>>> x = Uint8Array.new(range(10))
>>> with open('file.bin', 'rb') as fh:
...    x.read_file(fh)
which is equivalent to
>>> x = Uint8Array.new(range(10))
>>> with open('file.bin', 'rb') as fh:
...    chunk = fh.read(size=x.byteLength)
...    x.assign(chunk)
but the latter copies the data twice whereas the former only copies the
data once.

index(value: Any, start: int = 0, stop: int = 9223372036854775807) → int#

Return first index of value.

Present only if the wrapped Javascript object is an array. Raises ValueError if the value is not present.

property js_id: int#

An id number which can be used as a dictionary/set key if you want to key on JavaScript object identity.

If two JsProxy are made with the same backing JavaScript object, they will have the same js_id. The reault is a “pseudorandom” 32 bit integer.

new(*args: Any, **kwargs: Any) → pyodide.JsProxy#: Construct a new instance of the JavaScript object

object_entries() → pyodide.JsProxy#: The JavaScript API Object.entries(object)

object_keys() → pyodide.JsProxy#: The JavaScript API Object.keys(object)

object_values() → pyodide.JsProxy#: The JavaScript API Object.values(object)

pop(index: int = - 1) → Any#

Remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range. Present only if the wrapped Javascript object is an array.

reverse() → None#

Reverse the array in place.

Present only if the wrapped Javascript object is an array.

then(onfulfilled: collections.abc.Callable[[Any], Any], onrejected: collections.abc.Callable[[Any], Any]) → pyodide.Promise#

The Promise.then API, wrapped to manage the lifetimes of the handlers.

Present only if the wrapped JavaScript object has a “then” method. Pyodide will automatically release the references to the handlers when the promise resolves.

to_bytes() → bytes#

Convert a buffer to a bytes object.

Copies the data once. Present only if the wrapped Javascript object is an ArrayBuffer or an ArrayBuffer view.

to_file(file: io.IOBase, /) → None#

Writes a buffer to a file.

Will write the entire contents of the buffer to the current position of the file.

Present only if the wrapped Javascript object is an ArrayBuffer or an ArrayBuffer view.

Example

>>> import pytest; pytest.skip()
>>> from js import Uint8Array
>>> x = Uint8Array.new(range(10))
>>> with open('file.bin', 'wb') as fh:
...    x.to_file(fh)
which is equivalent to,
>>> with open('file.bin', 'wb') as fh:
...    data = x.to_bytes()
...    fh.write(data)
but the latter copies the data twice whereas the former only copies the
data once.

to_memoryview() → memoryview#

Convert a buffer to a memoryview.

Copies the data once. This currently has the same effect as to_py. Present only if the wrapped Javascript object is an ArrayBuffer or an ArrayBuffer view.

to_py(*, depth: int = - 1, default_converter: Optional[collections.abc.Callable[[JsProxy, collections.abc.Callable[[JsProxy], Any], collections.abc.Callable[[JsProxy, Any], None]], Any]] = None) → Any#

Convert the JsProxy to a native Python object as best as possible.

By default, does a deep conversion, if a shallow conversion is desired, you can use proxy.to_py(depth=1). See JavaScript to Python for more information.

default_converter if present will be invoked whenever Pyodide does not have some built in conversion for the object. If default_converter raises an error, the error will be allowed to propagate. Otherwise, the object returned will be used as the conversion. default_converter takes three arguments. The first argument is the value to be converted.

Here are a couple examples of converter functions. In addition to the normal conversions, convert Date to datetime:

from datetime import datetime
def default_converter(value, _ignored1, _ignored2):
    if value.constructor.name == "Date":
        return datetime.fromtimestamp(d.valueOf()/1000)
    return value

Don’t create any JsProxies, require a complete conversion or raise an error:

def default_converter(_value, _ignored1, _ignored2):
    raise Exception("Failed to completely convert object")

The second and third arguments are only needed for converting containers. The second argument is a conversion function which is used to convert the elements of the container with the same settings. The third argument is a “cache” function which is needed to handle self referential containers. Consider the following example. Suppose we have a Javascript Pair class:

class Pair {
    constructor(first, second){
        this.first = first;
        this.second = second;
    }
}

We can use the following default_converter to convert Pair to list:

def default_converter(value, convert, cache):
    if value.constructor.name != "Pair":
        return value
    result = []
    cache(value, result);
    result.append(convert(value.first))
    result.append(convert(value.second))
    return result

Note that we have to cache the conversion of value before converting value.first and value.second. To see why, consider a self referential pair:

let p = new Pair(0, 0);
p.first = p;

Without cache(value, result);, converting p would lead to an infinite recurse. With it, we can successfully convert p to a list such that l[0] is l.

to_string(encoding: Optional[str] = None) → str#

Convert a buffer to a string object.

Copies the data twice.

The encoding argument will be passed to the Javascript [TextDecoder](https://developer.mozilla.org/en-US/docs/Web/API/TextDecoder) constructor. It should be one of the encodings listed in the table here: https://encoding.spec.whatwg.org/#names-and-labels. The default encoding is utf8.

Present only if the wrapped Javascript object is an ArrayBuffer or an ArrayBuffer view.

property typeof: str#

Returns the JavaScript type of the JsProxy.

Corresponds to typeof obj; in JavaScript. You may also be interested in the constuctor attribute which returns the type as an object.

unwrap() → Any#

Unwrap a double proxy created with create_proxy into the wrapped Python object.

Only present on double proxies.

pyodide.ffi.create_once_callable(obj: collections.abc.Callable[[...], Any], /) → pyodide.JsProxy#

Wrap a Python callable in a JavaScript function that can be called once.

After being called the proxy will decrement the reference count of the Callable. The JavaScript function also has a destroy API that can be used to release the proxy without calling it.

pyodide.ffi.create_proxy(obj: Any, /, *, capture_this: bool = False, roundtrip: bool = True) → pyodide.JsProxy#

Create a JsProxy of a PyProxy.

This allows explicit control over the lifetime of the PyProxy from Python: call the destroy API when done.

Parameters

obj (any) – The object to wrap.
capture_this (bool, default=False) – If the object is callable, should this be passed as the first argument when calling it from JavaScript.
roundtrip (bool, default=True) –
When the proxy is converted back from JavaScript to Python, if this is True it is converted into a double proxy. If False, it is unwrapped into a Python object. In the case that roundtrip is True it is possible to unwrap a double proxy with the unwrap method. This is useful to allow easier control of lifetimes from Python:
```
from js import o
d = {}
o.d = create_proxy(d, roundtrip=True)
o.d.destroy() # Destroys the proxy created with create_proxy
```
With roundtrip=False this would be an error.

pyodide.ffi.destroy_proxies(pyproxies: pyodide.JsProxy, /) → None#

Destroy all PyProxies in a JavaScript array.

pyproxies must be a JsProxy of type PyProxy[]. Intended for use with the arrays created from the “pyproxies” argument of PyProxy.toJs and to_js. This method is necessary because indexing the Array from Python automatically unwraps the PyProxy into the wrapped Python object.

pyodide.ffi.register_js_module(name: str, jsproxy: Any) → None#

Registers jsproxy as a JavaScript module named name. The module can then be imported from Python using the standard Python import system. If another module by the same name has already been imported, this won’t have much effect unless you also delete the imported module from sys.modules. This is called by the JavaScript API pyodide.registerJsModule.

Parameters

name (str) – Name of js module
jsproxy (JsProxy) – JavaScript object backing the module

pyodide.ffi.to_js(obj: Any, /, *, depth: int = - 1, pyproxies: Optional[pyodide.JsProxy] = None, create_pyproxies: bool = True, dict_converter: Optional[collections.abc.Callable[[collections.abc.Iterable[pyodide.JsProxy]], pyodide.JsProxy]] = None, default_converter: Optional[collections.abc.Callable[[Any, collections.abc.Callable[[Any], pyodide.JsProxy], collections.abc.Callable[[Any, pyodide.JsProxy], None]], pyodide.JsProxy]] = None) → pyodide.JsProxy#

Convert the object to JavaScript.

This is similar to PyProxy.toJs, but for use from Python. If the object can be implicitly translated to JavaScript, it will be returned unchanged. If the object cannot be converted into JavaScript, this method will return a JsProxy of a PyProxy, as if you had used pyodide.ffi.create_proxy.

See Python to JavaScript for more information.

Parameters

obj (Any) – The Python object to convert
depth (int, default=-1) – The maximum depth to do the conversion. Negative numbers are treated as infinite. Set this to 1 to do a shallow conversion.
pyproxies (JsProxy, default = None) – Should be a JavaScript Array. If provided, any PyProxies generated will be stored here. You can later use destroy_proxies if you want to destroy the proxies from Python (or from JavaScript you can just iterate over the Array and destroy the proxies).
create_pyproxies (bool, default=True) – If you set this to False, to_js will raise an error
dict_converter (Callable[[Iterable[JsProxy]], JsProxy], default = None) –
This converter if provided receives a (JavaScript) iterable of (JavaScript) pairs [key, value]. It is expected to return the desired result of the dict conversion. Some suggested values for this argument:

js.Map.new – similar to the default behavior js.Array.from – convert to an array of entries js.Object.fromEntries – convert to a JavaScript object
default_converter (Callable[[Any, Callable[[Any], JsProxy], Callable[[Any, JsProxy], None]], JsProxy], default=None) –
If present will be invoked whenever Pyodide does not have some built in conversion for the object. If default_converter raises an error, the error will be allowed to propagate. Otherwise, the object returned will be used as the conversion. default_converter takes three arguments. The first argument is the value to be converted.

Here are a couple examples of converter functions. In addition to the normal conversions, convert Date to datetime:
```
from datetime import datetime
from js import Date
def default_converter(value, _ignored1, _ignored2):
    if isinstance(value, datetime):
        return Date.new(value.timestamp() * 1000)
    return value
```
Don’t create any PyProxies, require a complete conversion or raise an error:
```
def default_converter(_value, _ignored1, _ignored2):
    raise Exception("Failed to completely convert object")
```
The second and third arguments are only needed for converting containers. The second argument is a conversion function which is used to convert the elements of the container with the same settings. The third argument is a “cache” function which is needed to handle self referential containers. Consider the following example. Suppose we have a Python Pair class:
```
class Pair:
    def __init__(self, first, second):
        self.first = first
        self.second = second
```
We can use the following default_converter to convert Pair to Array:
```
from js import Array
def default_converter(value, convert, cache):
    if not isinstance(value, Pair):
        return value
    result = Array.new()
    cache(value, result);
    result.push(convert(value.first))
    result.push(convert(value.second))
    return result
```
Note that we have to cache the conversion of value before converting value.first and value.second. To see why, consider a self referential pair:
```
p = Pair(0, 0);
p.first = p;
```
Without cache(value, result);, converting p would lead to an infinite recurse. With it, we can successfully convert p to an Array such that l[0] === l.

pyodide.ffi.unregister_js_module(name: str) → None#

Unregisters a JavaScript module with given name that has been previously registered with pyodide.registerJsModule or pyodide.ffi.register_js_module. If a JavaScript module with that name does not already exist, will raise an error. If the module has already been imported, this won’t have much effect unless you also delete the imported module from sys.modules. This is called by the JavaScript API pyodide.unregisterJsModule.

Parameters: name (str) – Name of js module

Functions:

`add_event_listener`(elt, event, listener)	Wrapper for JavaScript's addEventListener() which automatically manages the lifetime of a JsProxy corresponding to the listener param.
`clear_interval`(interval_retval)	Wrapper for JavaScript's clearInterval() which automatically manages the lifetime of a JsProxy corresponding to the callback param.
`clear_timeout`(timeout_retval)	Wrapper for JavaScript's clearTimeout() which automatically manages the lifetime of a JsProxy corresponding to the callback param.
`remove_event_listener`(elt, event, listener)	Wrapper for JavaScript's removeEventListener() which automatically manages the lifetime of a JsProxy corresponding to the listener param.
`set_interval`(callback, interval)	Wrapper for JavaScript's setInterval() which automatically manages the lifetime of a JsProxy corresponding to the callback param.
`set_timeout`(callback, timeout)	Wrapper for JavaScript's setTimeout() which automatically manages the lifetime of a JsProxy corresponding to the callback param.

pyodide.ffi.wrappers.add_event_listener(elt: pyodide.JsProxy, event: str, listener: collections.abc.Callable[[Any], None]) → None#: Wrapper for JavaScript’s addEventListener() which automatically manages the lifetime of a JsProxy corresponding to the listener param.

pyodide.ffi.wrappers.clear_interval(interval_retval: int | pyodide.JsProxy) → None#: Wrapper for JavaScript’s clearInterval() which automatically manages the lifetime of a JsProxy corresponding to the callback param.

pyodide.ffi.wrappers.clear_timeout(timeout_retval: int | pyodide.JsProxy) → None#: Wrapper for JavaScript’s clearTimeout() which automatically manages the lifetime of a JsProxy corresponding to the callback param.

pyodide.ffi.wrappers.remove_event_listener(elt: pyodide.JsProxy, event: str, listener: collections.abc.Callable[[Any], None]) → None#: Wrapper for JavaScript’s removeEventListener() which automatically manages the lifetime of a JsProxy corresponding to the listener param.

pyodide.ffi.wrappers.set_interval(callback: collections.abc.Callable[[], None], interval: int) → int | pyodide.JsProxy#: Wrapper for JavaScript’s setInterval() which automatically manages the lifetime of a JsProxy corresponding to the callback param.

pyodide.ffi.wrappers.set_timeout(callback: collections.abc.Callable[[], None], timeout: int) → int | pyodide.JsProxy#: Wrapper for JavaScript’s setTimeout() which automatically manages the lifetime of a JsProxy corresponding to the callback param.

Version 0.22.0a2

pyodide.ffi

pyodide.ffi#