JavaScript API#
Backward compatibility of the API is not guaranteed at this point.
Globals#
Functions:
async |
Load the main Pyodide wasm module and initialize it. |
- async globalThis.loadPyodide(options)#
Load the main Pyodide wasm module and initialize it.
- Arguments:
options.indexURL (
string
) – The URL from which Pyodide will load the main Pyodide runtime and packages. It is recommended that you leave this unchanged, providing an incorrect value can cause broken behavior. Default: The url that Pyodide is loaded from with the file name (pyodide.js
orpyodide.mjs
) removed.options.packageCacheDir (
string
) – The file path where packages will be cached in node. If a package exists inpackageCacheDir
it is loaded from there, otherwise it is downloaded from the JsDelivr CDN and then cached intopackageCacheDir
. Only applies when running in node; ignored in browsers. Default: same as indexURLoptions.lockFileURL (
string
) – The URL from which Pyodide will load the Pyodidepyodide-lock.json
lock file. You can produce custom lock files withmicropip.freeze()
. Default:`${indexURL}/pyodide-lock.json`
options.homedir (
string
) – The home directory which Pyodide will use inside virtual file system. This is deprecated, use{env: {HOME : some_dir}}
instead.options.fullStdLib (
boolean
) – Load the full Python standard library. Setting this to false excludes unvendored modules from the standard library. Default:false
options.stdLibURL (
string
) – The URL from which to load the standard librarypython_stdlib.zip
file. This URL includes the most of the Python standard library. Some stdlib modules were unvendored, and can be loaded separately withfullStdLib: true
option or by their package name. Default:`${indexURL}/python_stdlib.zip`
options.stdin (() =>
string
) – Override the standard input callback. Should ask the user for one line of input. Thepyodide.setStdin()
function is more flexible and should be preferred.options.stdout ((msg:
string
) =>void
) – Override the standard output callback. Thepyodide.setStdout()
function is more flexible and should be preferred in most cases, but depending on theargs
passed toloadPyodide
, Pyodide may write to stdout on startup, which can only be controlled by passing a customstdout
function.options.stderr ((msg:
string
) =>void
) – Override the standard error output callback. Thepyodide.setStderr()
function is more flexible and should be preferred in most cases, but depending on theargs
passed toloadPyodide
, Pyodide may write to stdout on startup, which can only be controlled by passing a customstdout
function.options.jsglobals (
object
) – The object that Pyodide will use for thejs
module. Default:globalThis
options.args (
string
[]) – Command line arguments to pass to Python on startup. See Python command line interface options for more details. Default:[]
options.env ({ [key:
string
]:string
; }) – Environment variables to pass to Python. This can be accessed inside of Python at runtime viaos.environ
. Certain environment variables change the way that Python loads: https://docs.python.org/3.10/using/cmdline.html#environment-variables Default:{}
. Ifenv.HOME
is undefined, it will be set to a default value of"/home/pyodide"
options.packages (
string
[]) – A list of packages to load as Pyodide is initializing. This is the same as loading the packages withpyodide.loadPackage()
after Pyodide is loaded except using thepackages
option is more efficient because the packages are downloaded while Pyodide bootstraps itself.options.pyproxyToStringRepr (
boolean
) – Opt into the old behavior where PyProxy.toString callsrepr
and not str.
- Returns:
Promise
<PyodideInterface> – The pyodide module.
Example
async function main() { const pyodide = await loadPyodide({ fullStdLib: true, homedir: "/pyodide", stdout: (msg) => console.log(`Pyodide: ${msg}`), }); console.log("Loaded Pyodide"); } main();
pyodide#
Attributes:
A map from posix error names to error codes. |
|
An alias to the Emscripten File System API. |
|
An alias to the Emscripten Path API. |
|
See pyodide.canvas. |
|
See pyodide.ffi |
|
An alias to the global Python namespace. |
|
The list of packages that Pyodide has loaded. |
|
An alias to the Python pyodide package. |
|
The Pyodide version. |
Functions:
Throws a |
|
|
Is |
async |
Load packages from the Pyodide distribution or Python wheels by URL. |
async |
Inspect a Python code chunk and use |
async |
Mounts a |
|
Imports a module and returns it. |
|
Tell Pyodide about Comlink. |
|
Registers the JavaScript object |
|
Runs a string of Python code from JavaScript, using |
async |
Run a Python code string with top level await using
|
async |
|
|
Turn on or off debug mode. |
|
Sets the interrupt buffer to be |
|
Sets the standard error handler. |
|
Set a stdin handler. |
|
Sets the standard out handler. |
|
Convert a JavaScript object to a Python object as best as possible. |
|
Unpack an archive into a target directory. |
|
Unregisters a JavaScript module with given name that has been previously
registered with |
Classes:
An alias for |
|
An alias for |
|
An alias for |
- pyodide.FS#
type:
any
An alias to the Emscripten File System API.
This provides a wide range of POSIX-like file/device operations, including mount which can be used to extend the in-memory filesystem with features like persistence.
While all the file systems implementations are enabled, only the default
MEMFS
is guaranteed to work in all runtime settings. The implementations are available as members ofFS.filesystems
:IDBFS
,NODEFS
,PROXYFS
,WORKERFS
.
- pyodide.PATH#
type:
any
An alias to the Emscripten Path API.
This provides a variety of operations for working with file system paths, such as
dirname
,normalize
, andsplitPath
.
- pyodide.canvas#
See pyodide.canvas.
- pyodide.ffi#
See pyodide.ffi
- pyodide.globals#
type:
PyProxy
An alias to the global Python namespace.
For example, to access a variable called
foo
in the Python global scope, usepyodide.globals.get("foo")
- pyodide.loadedPackages#
type: { [key:
string
]:string
; }The list of packages that Pyodide has loaded. Use
Object.keys(pyodide.loadedPackages)
to get the list of names of loaded packages, andpyodide.loadedPackages[package_name]
to access install location for a particularpackage_name
.
- pyodide.pyodide_py#
type:
PyProxy
An alias to the Python pyodide package.
You can use this to call functions defined in the Pyodide Python package from JavaScript.
- pyodide.version#
type:
string
The Pyodide version.
The version here is a Python version, following PEP 440. This is different from the version in
package.json
which follows the node package manager version convention.
- pyodide.checkInterrupt()#
Throws a
KeyboardInterrupt
error if aKeyboardInterrupt
has been requested via the interrupt buffer.This can be used to enable keyboard interrupts during execution of JavaScript code, just as
PyErr_CheckSignals()
is used to enable keyboard interrupts during execution of C code.
- pyodide.isPyProxy(jsobj)#
Note
Deprecated: Use
obj instanceof pyodide.ffi.PyProxy
instead.Is
jsobj
aPyProxy
?
- async pyodide.loadPackage(names, options)#
Load packages from the Pyodide distribution or Python wheels by URL.
This installs packages in the virtual filesystem. Packages needs to be imported from Python before it can be used.
This function can only install packages included in the Pyodide distribution, or Python wheels by URL, without dependency resolution. It is significantly more limited in terms of functionality as compared to
micropip
, however it has less overhead and can be faster.When installing binary wheels by URLs it is user’s responsibility to check that the installed binary wheel is compatible in terms of Python and Emscripten versions. Compatibility is not checked during installation time (unlike with micropip). If a wheel for the wrong Python/Emscripten version is installed it would fail at import time.
- Arguments:
names (
string
|string
[] |PyProxy
) – Either a single package name or URL or a list of them. URLs can be absolute or relative. The URLs must correspond to Python wheels: either pure Python wheels, with a file name ending withnone-any.whl
or Emscripten/WASM 32 wheels, with a file name ending withcp<pyversion>_emscripten_<em_version>_wasm32.whl
. The argument can be aPyProxy
of a list, in which case the list will be converted to JavaScript and thePyProxy
will be destroyed.options.messageCallback ((message:
string
) =>void
) – A callback, called with progress messages (optional)options.errorCallback ((message:
string
) =>void
) – A callback, called with error/warning messages (optional)options.checkIntegrity (
boolean
) – If true, check the integrity of the downloaded packages (default: true)
- Returns:
Promise
<PackageData
[]> – The loaded package data.
- async pyodide.loadPackagesFromImports(code, options)#
Inspect a Python code chunk and use
pyodide.loadPackage()
to install any known packages that the code chunk imports. Uses the Python APIpyodide.code.find_imports()
to inspect the code.For example, given the following code as input
import numpy as np x = np.array([1, 2, 3])
loadPackagesFromImports()
will callpyodide.loadPackage(['numpy'])
.- Arguments:
code (
string
) – The code to inspect.options.messageCallback ((message:
string
) =>void
) – A callback, called with progress messages (optional)options.errorCallback ((message:
string
) =>void
) – A callback, called with error/warning messages (optional)options.checkIntegrity (
boolean
) – If true, check the integrity of the downloaded packages (default: true)
- Returns:
Promise
<PackageData
[]>
- async pyodide.mountNativeFS(path, fileSystemHandle)#
Mounts a
FileSystemDirectoryHandle
into the target directory.- Arguments:
path (
string
) – The absolute path in the Emscripten file system to mount the native directory. If the directory does not exist, it will be created. If it does exist, it must be empty.fileSystemHandle (
FileSystemDirectoryHandle
) – A handle returned bynavigator.storage.getDirectory()
orwindow.showDirectoryPicker()
.
- Returns:
- pyodide.pyimport(mod_name)#
Imports a module and returns it.
Warning
This function has a completely different behavior than the old removed pyimport function!
pyimport
is roughly equivalent to:pyodide.runPython(`import ${pkgname}; ${pkgname}`);
except that the global namespace will not change.
Example:
let sysmodule = pyodide.pyimport("sys"); let recursionLimit = sysmodule.getrecursionlimit();
- pyodide.registerComlink(Comlink)#
Tell Pyodide about Comlink. Necessary to enable importing Comlink proxies into Python.
- Arguments:
Comlink (
any
) –
- pyodide.registerJsModule(name, module)#
Registers the JavaScript object
module
as a JavaScript module namedname
. This 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 fromsys.modules
. This callsregister_js_module()
.
- pyodide.runPython(code, options)#
Runs a string of Python code from JavaScript, using
eval_code()
to evaluate the code. If the last statement in the Python code is an expression (and the code doesn’t end with a semicolon), the value of the expression is returned.- Arguments:
code (
string
) – Python code to evaluateoptions.globals (
PyProxy
) – An optional Python dictionary to use as the globals. Defaults topyodide.globals
.options.locals (
PyProxy
) – An optional Python dictionary to use as the locals. Defaults to the same asglobals
.options.filename (
string
) – An optional string to use as the filename. Defaults to “<exec>”. If the filename does not start with “<” and end with “>”, the source code will be added to the Python linecache and tracebacks will show source lines.
- Returns:
any
– The result of the Python code translated to JavaScript. See the documentation foreval_code()
for more info.
Example
async function main(){ const pyodide = await loadPyodide(); console.log(pyodide.runPython("1 + 2")); // 3 const globals = pyodide.toPy({ x: 3 }); console.log(pyodide.runPython("x + 1", { globals })); // 4 const locals = pyodide.toPy({ arr: [1, 2, 3] }); console.log(pyodide.runPython("sum(arr)", { locals })); // 6 } main();
- async pyodide.runPythonAsync(code, options)#
Run a Python code string with top level await using
eval_code_async()
to evaluate the code. Returns a promise which resolves when execution completes. If the last statement in the Python code is an expression (and the code doesn’t end with a semicolon), the returned promise will resolve to the value of this expression.For example:
let result = await pyodide.runPythonAsync(` from js import fetch response = await fetch("./pyodide-lock.json") packages = await response.json() # If final statement is an expression, its value is returned to JavaScript len(packages.packages.object_keys()) `); console.log(result); // 79
Python imports
Since pyodide 0.18.0, you must call
loadPackagesFromImports()
to import any python packages referenced viaimport
statements in your code. This function will no longer do it for you.- Arguments:
code (
string
) – Python code to evaluateoptions.globals (
PyProxy
) – An optional Python dictionary to use as the globals. Defaults topyodide.globals
.options.locals (
PyProxy
) – An optional Python dictionary to use as the locals. Defaults to the same asglobals
.options.filename (
string
) – An optional string to use as the filename. Defaults to “<exec>”. If the filename does not start with “<” and end with “>”, the source code will be added to the Python linecache and tracebacks will show source lines.
- Returns:
Promise
<any
> – The result of the Python code translated to JavaScript.
- async pyodide.runPythonSyncifying(code, options)#
- pyodide.setDebug(debug)#
Turn on or off debug mode. In debug mode, some error messages are improved at a performance cost.
- pyodide.setInterruptBuffer(interrupt_buffer)#
Sets the interrupt buffer to be
interrupt_buffer
. This is only useful when Pyodide is used in a webworker. The buffer should be aSharedArrayBuffer
shared with the main browser thread (or another worker). In that case, signalsignum
may be sent by writingsignum
into the interrupt buffer. Ifsignum
does not satisfy 0 <signum
< 65 it will be silently ignored.You can disable interrupts by calling
setInterruptBuffer(undefined)
.If you wish to trigger a
KeyboardInterrupt
, writeSIGINT
(a 2) into the interrupt buffer.By default
SIGINT
raises aKeyboardInterrupt
and all other signals are ignored. You can install custom signal handlers with the signal module. Even signals that normally have special meaning and can’t be overridden likeSIGKILL
andSIGSEGV
are ignored by default and can be used for any purpose you like.- Arguments:
interrupt_buffer (
TypedArray
) –
- pyodide.setStderr(options)#
Sets the standard error handler. See the documentation for
pyodide.setStdout()
.
- pyodide.setStdin(options)#
Set a stdin handler. See redirecting standard streams for a more detailed explanation. There are two different possible interfaces to implement a handler. It’s also possible to select either the default handler or an error handler that always returns an IO error.
passing a
read
function (see below),passing a
stdin
function (see below),passing
error: true
indicates that attempting to read from stdin should always raise an IO error.passing none of these sets the default behavior. In node, the default is to read from stdin. In the browser, the default is to raise an error.
The functions on the
options
argument will be called withoptions
bound tothis
so passing an instance of a class as theoptions
object works as expected.The interfaces that the handlers implement are as follows:
The
read
function is called with aUint8Array
argument. The function should place the utf8-encoded input into this buffer and return the number of bytes written. For instance, if the buffer was completely filled with input, then returnbuffer.length
. If aread
function is passed you may optionally also pass anfsync
function which is called when stdin is flushed.The
stdin
function is called with zero arguments. It should return one of:a number
a string
an
ArrayBuffer
orTypedArray
withBYTES_PER_ELEMENT
equal to 1. The buffer should contain utf8 encoded text.
If a number is returned, it is interpreted as a single character code. The number should be between 0 and 255.
If a string is returned, it is encoded into a buffer using
TextEncoder
. By default, an EOF is appended after each string or buffer returned. If this behavior is not desired, passautoEOF: false
.
- Arguments:
options.stdin (() =>
null
|undefined
|string
|ArrayBuffer
|Uint8Array
|number
) – A stdin handleroptions.read ((buffer:
Uint8Array
) =>number
) – A read handleroptions.error (
boolean
) – If this is set totrue
, attempts to read from stdin will always set an IO error.options.isatty (
boolean
) – Shouldisatty(stdin)
betrue
orfalse
(defaultfalse
).options.autoEOF (
boolean
) – Insert an EOF automatically after each string or buffer? (defaulttrue
). This option can only be used with the stdin handler.
- pyodide.setStdout(options)#
Sets the standard out handler. A batched handler, a raw handler, or a write function can be provided. If no handler is provided, we restore the default handler.
The functions on the
options
argument will be called withoptions
bound tothis
so passing an instance of a class as theoptions
object works as expected.- Arguments:
options.batched ((output:
string
) =>void
) – A batched handler is called with a string whenever a newline character is written or stdout is flushed. In the former case, the received line will end with a newline, in the latter case it will not.options.raw ((charCode:
number
) =>void
) – A raw handler is called with the handler is called with a number for each byte of the output to stdout.options.write ((buffer:
Uint8Array
) =>number
) – A write handler is called with a buffer that contains the utf8 encoded binary dataoptions.isatty (
boolean
) – Shouldisatty(stdout)
returntrue
orfalse
. Must befalse
if a batched handler is used. (defaultfalse
).
Example
async function main(){ const pyodide = await loadPyodide(); pyodide.setStdout({ batched: (msg) => console.log(msg) }); pyodide.runPython("print('ABC')"); // 'ABC' pyodide.setStdout({ raw: (byte) => console.log(byte) }); pyodide.runPython("print('ABC')"); // 65 // 66 // 67 // 10 (the ascii values for 'ABC' including a new line character) } main();
- pyodide.toPy(obj, options)#
Convert a JavaScript object to a Python object as best as possible.
This is similar to
to_py()
but for use from JavaScript. If the object is immutable or aPyProxy
, it will be returned unchanged. If the object cannot be converted into Python, it will be returned unchanged.See JavaScript to Python for more information.
- Arguments:
obj (
any
) – The object to convert.options.depth (
number
) – Optional argument to limit the depth of the conversion.options.defaultConverter ((value:
any
, converter: (value:any
) =>any
, cacheConversion: (input:any
, output:any
) =>void
) =>any
) – Optional argument to convert objects with no default conversion. See the documentation ofto_py()
.
- Returns:
any
– The object converted to Python.
- pyodide.unpackArchive(buffer, format, options)#
Unpack an archive into a target directory.
- Arguments:
buffer (
ArrayBuffer
|TypedArray
) – The archive as anArrayBuffer
orTypedArray
.format (
string
) – The format of the archive. Should be one of the formats recognized byshutil.unpack_archive()
. By default the options are'bztar'
,'gztar'
,'tar'
,'zip'
, and'wheel'
. Several synonyms are accepted for each format, e.g., for'gztar'
any of'.gztar'
,'.tar.gz'
,'.tgz'
,'tar.gz'
or'tgz'
are considered to be synonyms.options.extractDir (
string
) – The directory to unpack the archive into. Defaults to the working directory.
- pyodide.unregisterJsModule(name)#
Unregisters a JavaScript module with given name that has been previously registered with
pyodide.registerJsModule()
orregister_js_module()
. If a JavaScript module with that name does not already exist, will throw an error. Note that if the module has already been imported, this won’t have much effect unless you also delete the imported module fromsys.modules
. This callsunregister_js_module()
.- Arguments:
name (
string
) – Name of the JavaScript module to remove
- pyodide.PyBuffer#
Note
Deprecated.
An alias for
pyodide.ffi.PyBufferView
.
- pyodide.PyProxyBuffer#
Note
Deprecated.
An alias for
pyodide.ffi.PyBuffer
.
- pyodide.PythonError#
Note
Deprecated.
An alias for
pyodide.ffi.PythonError
.
pyodide.ffi#
To import types from pyodide.ffi
you can use for example
import type { PyProxy } from "pyodide/ffi";
Classes:
A |
|
A |
|
A |
|
A |
|
A |
|
A class to allow access to Python data buffers from JavaScript. |
|
A |
|
A |
|
A |
|
A |
|
A |
|
A |
|
A |
|
A |
|
A |
|
A |
|
A |
|
A JavaScript error caused by a Python exception. |
- class pyodide.ffi.PyAsyncGenerator()#
A
PyProxy
whose proxied Python object is an asynchronous generator (i.e., it is an instance ofAsyncGenerator
)- Extends:
- async PyAsyncGenerator.return(v)#
Throws a
GeneratorExit
into the generator and if theGeneratorExit
is not caught returns the argument value{done: true, value: v}
. If the generator catches theGeneratorExit
and returns or yields another value the next value of the generator this is returned in the normal way. If it throws some error other thanGeneratorExit
orStopAsyncIteration
, that error is propagated. See the documentation forAsyncGenerator.throw()
- Arguments:
v (
any
) –
- Returns:
Promise
<IteratorResult
<any
,any
>> – An Object with two properties:done
andvalue
. When the generator yieldssome_value
,return
returns{done : false, value : some_value}
. When the generator raises aStopAsyncIteration
exception,return
returns{done : true, value : result_value}
.
- async PyAsyncGenerator.throw(exc)#
Throws an exception into the Generator.
See the documentation for
AsyncGenerator.throw()
.- Arguments:
exc (
any
) –
- Returns:
Promise
<IteratorResult
<any
,any
>> – An Object with two properties:done
andvalue
. When the generator yieldssome_value
,return
returns{done : false, value : some_value}
. When the generator raises aStopIteration(result_value)
exception,return
returns{done : true, value : result_value}
.
- class pyodide.ffi.PyAsyncIterable()#
A
PyProxy
whose proxied Python object is asynchronous iterable (i.e., has an__aiter__()
method).- Extends:
- PyAsyncIterable.[Symbol․asyncIterator]()#
This translates to the Python code
aiter(obj)
. Return an async iterator associated to the proxy. See the documentation forSymbol.asyncIterator
.This will be used implicitly by
for(await let x of proxy){}
.- Returns:
AsyncIterator
<any
,any
,any
>
- class pyodide.ffi.PyAsyncIterator()#
A
PyProxy
whose proxied Python object is an asynchronous iterator- Extends:
- async PyAsyncIterator.next(arg=undefined)#
This translates to the Python code
anext(obj)
. Returns the next value of the asynchronous iterator. The argument will be sent to the Python iterator (if it’s a generator for instance).This will be used implicitly by
for(let x of proxy){}
.- Arguments:
arg (
any
) –
- Returns:
Promise
<IteratorResult
<any
,any
>> – An Object with two properties:done
andvalue
. When the iterator yieldssome_value
,next
returns{done : false, value : some_value}
. When the giterator is done,next
returns{done : true }
.
- class pyodide.ffi.PyAwaitable()#
A
PyProxy
whose proxied Python object is awaitable (i.e., has an__await__()
method).- Extends:
- class pyodide.ffi.PyBuffer()#
A
PyProxy
whose proxied Python object supports the Python Buffer Protocol.Examples of buffers include {py:class}`bytes` objects and numpy {external+numpy:ref}`arrays`.
- Extends:
- PyBuffer.getBuffer(type)#
Get a view of the buffer data which is usable from JavaScript. No copy is ever performed.
We do not support suboffsets, if the buffer requires suboffsets we will throw an error. JavaScript nd array libraries can’t handle suboffsets anyways. In this case, you should use the
toJs()
api or copy the buffer to one that doesn’t use suboffsets (using e.g.,numpy.ascontiguousarray()
).If the buffer stores big endian data or half floats, this function will fail without an explicit type argument. For big endian data you can use
toJs()
.DataView
has support for big endian data, so you might want to pass'dataview'
as the type argument in that case.- Arguments:
type (
string
) – The type of thedata
field in the output. Should be one of:"i8"
,"u8"
,"u8clamped"
,"i16"
,"u16"
,"i32"
,"u32"
,"i32"
,"u32"
,"i64"
,"u64"
,"f32"
,"f64
, or"dataview"
. This argument is optional, if absentgetBuffer()
will try to determine the appropriate output type based on the buffer format string (see Format Strings).
- Returns:
- class pyodide.ffi.PyBufferView()#
A class to allow access to Python data buffers from JavaScript. These are produced by
getBuffer()
and cannot be constructed directly. When you are done, release it with therelease()
method. See the Python Buffer Protocol documentation for more information.To find the element
x[a_1, ..., a_n]
, you could use the following code:function multiIndexToIndex(pybuff, multiIndex){ if(multindex.length !==pybuff.ndim){ throw new Error("Wrong length index"); } let idx = pybuff.offset; for(let i = 0; i < pybuff.ndim; i++){ if(multiIndex[i] < 0){ multiIndex[i] = pybuff.shape[i] - multiIndex[i]; } if(multiIndex[i] < 0 || multiIndex[i] >= pybuff.shape[i]){ throw new Error("Index out of range"); } idx += multiIndex[i] * pybuff.stride[i]; } return idx; } console.log("entry is", pybuff.data[multiIndexToIndex(pybuff, [2, 0, -1])]);
Converting between TypedArray types
The following naive code to change the type of a typed array does not work:
// Incorrectly convert a TypedArray. // Produces a Uint16Array that points to the entire WASM memory! let myarray = new Uint16Array(buffer.data.buffer);
Instead, if you want to convert the output TypedArray, you need to say:
// Correctly convert a TypedArray. let myarray = new Uint16Array( buffer.data.buffer, buffer.data.byteOffset, buffer.data.byteLength );
- PyBufferView.c_contiguous#
type:
boolean
Is it C contiguous? See
memoryview.c_contiguous
.
- PyBufferView.data#
type:
TypedArray
The actual data. A typed array of an appropriate size backed by a segment of the WASM memory.
The
type
argument ofgetBuffer()
determines which sort ofTypedArray
orDataView
to return. By defaultgetBuffer()
will look at the format string to determine the most appropriate option. Most often the result is aUint8Array
.Contiguity
If the buffer is not contiguous, the
readonly
TypedArray will contain data that is not part of the buffer. Modifying this data leads to undefined behavior.Read only buffers
If
buffer.readonly
istrue
, you should not modify the buffer. Modifying a read only buffer leads to undefined behavior.
- PyBufferView.f_contiguous#
type:
boolean
Is it Fortran contiguous? See
memoryview.f_contiguous
.
- PyBufferView.format#
type:
string
The format string for the buffer. See Format Strings and
memoryview.format
.
- PyBufferView.itemsize#
type:
number
How large is each entry in bytes? See
memoryview.itemsize
.
- PyBufferView.nbytes#
type:
number
The total number of bytes the buffer takes up. This is equal to
buff.data.byteLength
. Seememoryview.nbytes
.
- PyBufferView.ndim#
type:
number
The number of dimensions of the buffer. If
ndim
is 0, the buffer represents a single scalar or struct. Otherwise, it represents an array. Seememoryview.ndim
.
- PyBufferView.offset#
type:
number
The offset of the first entry of the array. For instance if our array is 3d, then you will find
array[0,0,0]
atpybuf.data[pybuf.offset]
- PyBufferView.readonly#
type:
boolean
If the data is read only, you should not modify it. There is no way for us to enforce this, but it may cause very weird behavior. See
memoryview.readonly
.
- PyBufferView.shape#
type:
number
[]The shape of the buffer, that is how long it is in each dimension. The length will be equal to
ndim
. For instance, a 2x3x4 array would have shape[2, 3, 4]
. Seememoryview.shape
.
- PyBufferView.strides#
type:
number
[]An array of of length
ndim
giving the number of elements to skip to get to a new element in each dimension. See the example definition of amultiIndexToIndex
function above. Seememoryview.strides
.
- PyBufferView.release()#
Release the buffer. This allows the memory to be reclaimed.
- class pyodide.ffi.PyCallable()#
A
PyProxy
whose proxied Python object is callable (i.e., has an__call__()
method).- Extends:
- PyCallable.apply(thisArg, jsargs)#
The
apply()
method calls the specified function with a given this value, and arguments provided as an array (or an array-like object). LikeFunction.apply()
.- Arguments:
thisArg (
any
) – Thethis
argument. Has no effect unless thePyCallable
hascaptureThis()
set. IfcaptureThis()
is set, it will be passed as the first argument to the Python function.jsargs (
any
) – The array of arguments
- Returns:
any
– The result from the function call.
- PyCallable.bind(thisArg, ...jsargs)#
The
bind()
method creates a new function that, when called, has itsthis
keyword set to the provided value, with a given sequence of arguments preceding any provided when the new function is called. SeeFunction.bind()
.If the
PyCallable
does not havecaptureThis()
set, thethis
parameter will be discarded. If it does havecaptureThis()
set,thisArg
will be set to the first argument of the Python function. The returned proxy and the original proxy have the same lifetime so destroying either destroys both.
- PyCallable.call(thisArg, ...jsargs)#
Calls the function with a given this value and arguments provided individually. See
Function.call()
.- Arguments:
thisArg (
any
) – Thethis
argument. Has no effect unless thePyCallable
hascaptureThis()
set. IfcaptureThis()
is set, it will be passed as the first argument to the Python function.jsargs (
any
) – The arguments
- Returns:
any
– The result from the function call.
- PyCallable.callKwargs(...jsargs)#
Call the function with key word arguments. The last argument must be an object with the keyword arguments.
- PyCallable.captureThis()#
Returns a
PyProxy
that passesthis
as the first argument to the Python function. The returnedPyProxy
has the internalcaptureThis
property set.It can then be used as a method on a JavaScript object. The returned proxy and the original proxy have the same lifetime so destroying either destroys both.
For example:
let obj = { a : 7 }; pyodide.runPython(` def f(self): return self.a `); // Without captureThis, it doesn't work to use f as a method for obj: obj.f = pyodide.globals.get("f"); obj.f(); // raises "TypeError: f() missing 1 required positional argument: 'self'" // With captureThis, it works fine: obj.f = pyodide.globals.get("f").captureThis(); obj.f(); // returns 7
- class pyodide.ffi.PyDict()#
- class pyodide.ffi.PyGenerator()#
A
PyProxy
whose proxied Python object is a generator (i.e., it is an instance ofGenerator
).- Extends:
- PyGenerator.return(v)#
Throws a
GeneratorExit
into the generator and if theGeneratorExit
is not caught returns the argument value{done: true, value: v}
. If the generator catches theGeneratorExit
and returns or yields another value the next value of the generator this is returned in the normal way. If it throws some error other thanGeneratorExit
orStopIteration
, that error is propagated. See the documentation forGenerator.return()
.- Arguments:
v (
any
) –
- Returns:
IteratorResult
<any
,any
> – An Object with two properties:done
andvalue
. When the generator yieldssome_value
,return
returns{done : false, value : some_value}
. When the generator raises aStopIteration(result_value)
exception,return
returns{done : true, value : result_value}
.
- PyGenerator.throw(exc)#
Throws an exception into the Generator.
See the documentation for
Generator.throw()
.- Arguments:
exc (
any
) –
- Returns:
IteratorResult
<any
,any
> – An Object with two properties:done
andvalue
. When the generator yieldssome_value
,return
returns{done : false, value : some_value}
. When the generator raises aStopIteration(result_value)
exception,return
returns{done : true, value : result_value}
.
- class pyodide.ffi.PyIterable()#
A
PyProxy
whose proxied Python object is iterable (i.e., it has an__iter__()
method).- Extends:
- class pyodide.ffi.PyIterator()#
A
PyProxy
whose proxied Python object is an iterator (i.e., has asend()
or__next__()
method).- Extends:
- PyIterator.next(arg=undefined)#
This translates to the Python code
next(obj)
. Returns the next value of the generator. See the documentation forGenerator.next()
The argument will be sent to the Python generator.This will be used implicitly by
for(let x of proxy){}
.- Arguments:
arg (
any
) –
- Returns:
IteratorResult
<any
,any
> – An Object with two properties:done
andvalue
. When the generator yieldssome_value
,next
returns{done : false, value : some_value}
. When the generator raises aStopIteration
exception,next
returns{done : true, value : result_value}
.
- class pyodide.ffi.PyMutableSequence()#
A
PyProxy
whose proxied Python object is anMutableSequence
(i.e., alist
)- Extends:
- PyMutableSequence.copyWithin(target, start, end)#
The
Array.copyWithin()
method shallow copies part of aPyMutableSequence
to another location in the samePyMutableSequence
without modifying its length.- Arguments:
- Returns:
any
– The modifiedPyMutableSequence
.
- PyMutableSequence.fill(value, start, end)#
The
Array.fill()
method changes all elements in an array to a static value, from a start index to an end index.
- PyMutableSequence.pop()#
The
Array.pop()
method removes the last element from aPyMutableSequence
.- Returns:
any
– The removed element from thePyMutableSequence
; undefined if thePyMutableSequence
is empty.
- PyMutableSequence.push(...elts)#
The
Array.push()
method adds the specified elements to the end of aPyMutableSequence
.- Arguments:
elts (
any
[]) – The element(s) to add to the end of thePyMutableSequence
.
- Returns:
any
– The new length property of the object upon which the method was called.
- PyMutableSequence.reverse()#
The
Array.reverse()
method reverses aPyMutableSequence
in place.- Returns:
PyMutableSequence
– A reference to the samePyMutableSequence
- PyMutableSequence.shift()#
The
Array.shift()
method removes the first element from aPyMutableSequence
.- Returns:
any
– The removed element from thePyMutableSequence
; undefined if thePyMutableSequence
is empty.
- PyMutableSequence.sort(compareFn)#
The
Array.sort()
method sorts the elements of aPyMutableSequence
in place.- Arguments:
- Returns:
PyMutableSequence
– A reference to the samePyMutableSequence
- PyMutableSequence.splice(start, deleteCount, ...items)#
The
Array.splice()
method changes the contents of aPyMutableSequence
by removing or replacing existing elements and/or adding new elements in place.- Arguments:
start (
number
) – Zero-based index at which to start changing thePyMutableSequence
.deleteCount (
number
) – An integer indicating the number of elements in thePyMutableSequence
to remove fromstart
.items (
any
[]) – The elements to add to thePyMutableSequence
, beginning fromstart
.
- Returns:
any
[] – An array containing the deleted elements.
- PyMutableSequence.unshift(...elts)#
The
Array.unshift()
method adds the specified elements to the beginning of aPyMutableSequence
.- Arguments:
elts (
any
[]) – The elements to add to the front of thePyMutableSequence
.
- Returns:
any
– The new length of thePyMutableSequence
.
- class pyodide.ffi.PyProxy()#
A
PyProxy
is an object that allows idiomatic use of a Python object from JavaScript. See Proxying from Python into JavaScript.- PyProxy.type#
type:
string
The name of the type of the object.
Usually the value is
"module.name"
but for builtins or interpreter-defined types it is just"name"
. As pseudocode this is:ty = type(x) if ty.__module__ == 'builtins' or ty.__module__ == "__main__": return ty.__name__ else: ty.__module__ + "." + ty.__name__
- PyProxy.copy()#
Make a new
PyProxy
pointing to the same Python object. Useful if thePyProxy
is destroyed somewhere else.- Returns:
- PyProxy.destroy(options)#
Destroy the
PyProxy
. This will release the memory. Any further attempt to use the object will raise an error.In a browser supporting
FinalizationRegistry
, Pyodide will automatically destroy thePyProxy
when it is garbage collected, however there is no guarantee that the finalizer will be run in a timely manner so it is better to destroy the proxy explicitly.
- PyProxy.isAwaitable()#
Note
Deprecated: Use
obj instanceof pyodide.ffi.PyAwaitable
instead.Check whether the
PyProxy
is aPyAwaitable
- Returns:
boolean
(typeguard forPyAwaitable
)
- PyProxy.isBuffer()#
Note
Deprecated: Use
obj instanceof pyodide.ffi.PyBuffer
instead.
- PyProxy.isCallable()#
Note
Deprecated:
obj instanceof pyodide.ffi.PyCallable
instead.Check whether the
PyProxy
is aPyCallable
.- Returns:
boolean
(typeguard forPyCallable
)
- PyProxy.isIterable()#
Note
Deprecated: Use
obj instanceof pyodide.ffi.PyIterable
instead.Check whether the
PyProxy
is aPyIterable
.- Returns:
boolean
(typeguard forPyIterable
)
- PyProxy.isIterator()#
Note
Deprecated: Use
obj instanceof pyodide.ffi.PyIterator
instead.Check whether the
PyProxy
is aPyIterator
- Returns:
boolean
(typeguard forPyIterator
)
- PyProxy.supportsGet()#
Note
Deprecated: Use
obj instanceof pyodide.ffi.PyProxyWithGet
instead.Check whether the
PyProxy
is aPyProxyWithGet
.- Returns:
boolean
(typeguard forPyProxyWithGet
)
- PyProxy.supportsHas()#
Note
Deprecated: Use
obj instanceof pyodide.ffi.PyProxyWithHas
instead.Check whether the
PyProxy
is aPyProxyWithHas
.- Returns:
boolean
(typeguard forPyProxyWithHas
)
- PyProxy.supportsLength()#
Note
Deprecated: Use
obj instanceof pyodide.ffi.PyProxyWithLength
instead.Check whether the
PyProxy
is aPyProxyWithLength
.- Returns:
boolean
(typeguard forPyProxyWithLength
)
- PyProxy.supportsSet()#
Note
Deprecated: Use
obj instanceof pyodide.ffi.PyProxyWithSet
instead.Check whether the
PyProxy
is aPyProxyWithSet
.- Returns:
boolean
(typeguard forPyProxyWithSet
)
- PyProxy.toJs(options)#
Converts the
PyProxy
into a JavaScript object as best as possible. By default does a deep conversion, if a shallow conversion is desired, you can useproxy.toJs({depth : 1})
. See Explicit Conversion of PyProxy for more info.- Arguments:
options.depth (
number
) – How many layers deep to perform the conversion. Defaults to infiniteoptions.pyproxies (
PyProxy
[]) – If provided,toJs()
will store all PyProxies created in this list. This allows you to easily destroy all the PyProxies by iterating the list without having to recurse over the generated structure. The most common use case is to create a new empty list, pass the list aspyproxies
, and then later iterate overpyproxies
to destroy all of created proxies.options.create_pyproxies (
boolean
) – If false,toJs()
will throw aConversionError
rather than producing aPyProxy
.options.dict_converter ((array:
Iterable
<[key:string
, value:any
]>) =>any
) – A function to be called on an iterable of pairs[key, value]
. Convert this iterable of pairs to the desired output. For instance,Object.fromEntries()
would convert the dict to an object,Array.from()
converts it to anArray
of pairs, and(it) => new Map(it)
converts it to aMap
(which is the default behavior).options.default_converter ((obj:
PyProxy
, convert: (obj:PyProxy
) =>any
, cacheConversion: (obj:PyProxy
, result:any
) =>void
) =>any
) – Optional argument to convert objects with no default conversion. See the documentation ofto_js()
.
- Returns:
any
– The JavaScript object resulting from the conversion.
- class pyodide.ffi.PyProxyWithGet()#
A
PyProxy
whose proxied Python object has a__getitem__()
method.- Extends:
- class pyodide.ffi.PyProxyWithHas()#
A
PyProxy
whose proxied Python object has a__contains__()
method.- Extends:
- class pyodide.ffi.PyProxyWithLength()#
A
PyProxy
whose proxied Python object has a__len__()
method.- Extends:
- class pyodide.ffi.PyProxyWithSet()#
A
PyProxy
whose proxied Python object has a__setitem__()
or__delitem__()
method.- Extends:
- class pyodide.ffi.PySequence()#
A
PyProxy
whose proxied Python object is anSequence
(i.e., alist
)- Extends:
- PySequence.at(index)#
See
Array.at()
. Takes an integer value and returns the item at that index.
- PySequence.concat(...rest)#
The
Array.concat()
method is used to merge two or more arrays. This method does not change the existing arrays, but instead returns a new array.
- PySequence.entries()#
The
Array.entries()
method returns a new iterator object that contains the key/value pairs for each index in theSequence
.
- PySequence.every(predicate, thisArg)#
See
Array.every()
. Tests whether every element in theSequence
passes the test implemented by the provided function.
- PySequence.filter(predicate, thisArg)#
See
Array.filter()
. Creates a shallow copy of a portion of a givenSequence
, filtered down to just the elements from the given array that pass the test implemented by the provided function.
- PySequence.find(predicate, thisArg)#
The
Array.find()
method returns the first element in the provided array that satisfies the provided testing function.- Arguments:
- Returns:
any
– The first element in theSequence
that satisfies the provided testing function.
- PySequence.findIndex(predicate, thisArg)#
The
Array.findIndex()
method returns the index of the first element in the provided array that satisfies the provided testing function.- Arguments:
- Returns:
number
– The index of the first element in theSequence
that satisfies the provided testing function.
- PySequence.forEach(callbackfn, thisArg)#
See
Array.forEach()
. Executes a provided function once for eachSequence
element.
- PySequence.includes(elt)#
The
Array.includes()
method determines whether a Sequence includes a certain value among its entries, returning true or false as appropriate.
- PySequence.indexOf(elt, fromIndex)#
See
Array.indexOf()
. Returns the first index at which a given element can be found in the Sequence, or -1 if it is not present.
- PySequence.join(separator)#
See
Array.join()
. TheArray.join()
method creates and returns a new string by concatenating all of the elements in theSequence
.
- PySequence.keys()#
The
Array.keys()
method returns a new iterator object that contains the keys for each index in theSequence
.- Returns:
IterableIterator
<number
> – A new iterator object.
- PySequence.lastIndexOf(elt, fromIndex)#
See
Array.lastIndexOf()
. Returns the last index at which a given element can be found in the Sequence, or -1 if it is not present.
- PySequence.map(callbackfn, thisArg)#
See
Array.map()
. Creates a new array populated with the results of calling a provided function on every element in the callingSequence
.
- PySequence.reduce(callbackfn, initialValue)#
See
Array.reduce()
. Executes a user-supplied “reducer” callback function on each element of the Sequence, in order, passing in the return value from the calculation on the preceding element. The final result of running the reducer across all elements of the Sequence is a single value.
- PySequence.reduceRight(callbackfn, initialValue)#
See
Array.reduceRight()
. Applies a function against an accumulator and each value of the Sequence (from right to left) to reduce it to a single value.
- PySequence.slice(start, stop)#
See
Array.slice()
. TheArray.slice()
method returns a shallow copy of a portion of aSequence
into a new array object selected fromstart
tostop
(stop not included)- Arguments:
- Returns:
any
– A new array containing the extracted elements.
- PySequence.some(predicate, thisArg)#
See
Array.some()
. Tests whether at least one element in theSequence
passes the test implemented by the provided function.
- PySequence.values()#
The
Array.values()
method returns a new iterator object that contains the values for each index in theSequence
.- Returns:
IterableIterator
<any
> – A new iterator object.
- class pyodide.ffi.PythonError()#
A JavaScript error caused by a Python exception.
In order to reduce the risk of large memory leaks, the
PythonError
contains no reference to the Python exception that caused it. You can find the actual Python exception that caused this error assys.last_value
.See type translations of errors for more information.
Avoid leaking stack Frames
If you make a
PyProxy
ofsys.last_value
, you should be especially careful todestroy()
it when you are done. You may leak a large amount of memory including the local variables of all the stack frames in the traceback if you don’t. The easiest way is to only handle the exception in Python.- PythonError.type#
type:
string
The name of the Python error class, e.g,
RuntimeError
orKeyError
.
pyodide.canvas#
This provides APIs to set a canvas for rendering graphics.
For example, you need to set a canvas if you want to use the SDL library. See Using SDL-based packages in Pyodide for more information.
Functions:
Get the HTML5 canvas element used for 2D rendering. |
|
Get the HTML5 canvas element used for 3D rendering. |
|
|
Set the HTML5 canvas element to use for 2D rendering. |
|
Set the HTML5 canvas element to use for 3D rendering. |
- pyodide.canvas.getCanvas2D()#
Get the HTML5 canvas element used for 2D rendering. For now, Emscripten only supports one canvas element, so getCanvas2D and getCanvas3D are the same.
- Returns:
- pyodide.canvas.getCanvas3D()#
Get the HTML5 canvas element used for 3D rendering. For now, Emscripten only supports one canvas element, so getCanvas2D and getCanvas3D are the same.
- Returns:
- pyodide.canvas.setCanvas2D(canvas)#
Set the HTML5 canvas element to use for 2D rendering. For now, Emscripten only supports one canvas element, so setCanvas2D and setCanvas3D are the same.
- Arguments:
canvas (
HTMLCanvasElement
) –
- pyodide.canvas.setCanvas3D(canvas)#
Set the HTML5 canvas element to use for 3D rendering. For now, Emscripten only supports one canvas element, so setCanvas2D and setCanvas3D are the same.
- Arguments:
canvas (
HTMLCanvasElement
) –