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.args (
string
[]) – Command line arguments to pass to Python on startup. See Python command line interface options for more details. Default:[]
options.fullStdLib (
boolean
) – Load the full Python standard library. Setting this to false excludes unvendored modules from the standard library. Default:false
options.homedir (
string
) – The home directory which Pyodide will use inside virtual file system. Default:"/home/pyodide"
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.jsglobals (
object
) – The object that Pyodide will use for thejs
module. Default:globalThis
options.lockFileURL (
string
) – The URL from which Pyodide will load the Pyodiderepodata.json
lock file. You can produce custom lock files withmicropip.freeze
. Default:`${indexURL}/repodata.json`
options.stderr ((msg:
string
) =>void
) – Override the standard error output callback.options.stdin (() =>
string
) – Override the standard input callback. Should ask the user for one line of input.options.stdout ((msg:
string
) =>void
) – Override the standard output callback.
- Returns
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. |
|
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 the argument a |
async |
Load a package or a list of packages over the network. |
async |
Inspect a Python code chunk and use |
async |
Mounts FileSystemDirectoryHandle in to the target directory. |
|
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
|
|
Sets the interrupt buffer to be |
|
Sets the standard error handler. |
|
Set a stdin handler. The stdin handler is called with zero arguments whenever stdin is read and
the current input buffer is exhausted. It should return one of:
- |
|
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:
A class to allow access to a Python data buffers from JavaScript. |
|
A JavaScript error caused by a Python exception. |
- 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.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#
-
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 follows PEP440 which is different from the one in package.json, as we want to compare this with the version of Pyodide Python package without conversion.
- 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.
- async pyodide.loadPackage(names, options)#
Load a package or a list of packages over the network. This installs the package in the virtual filesystem. The package needs to be imported from Python before it can be used.
- 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 have file name<package-name>.js
and there must be a file called<package-name>.data
in the same directory. The argument can be aPyProxy
of a list, in which case the list will be converted to JavaScript and thePyProxy
will be destroyed.options.checkIntegrity (
boolean
) – If true, check the integrity of the downloaded packages (default: true)options.errorCallback ((message:
string
) =>void
) – A callback, called with error/warning messages (optional)options.messageCallback ((message:
string
) =>void
) – A callback, called with progress messages (optional)
- Returns
- 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.checkIntegrity (
boolean
) – If true, check the integrity of the downloaded packages (default: true)options.errorCallback ((message:
string
) =>void
) – A callback, called with error/warning messages (optional)options.messageCallback ((message:
string
) =>void
) – A callback, called with progress messages (optional)
- Returns
- async pyodide.mountNativeFS(path, fileSystemHandle)#
Mounts FileSystemDirectoryHandle in to 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 by navigator.storage.getDirectory() or window.showDirectoryPicker().
- Returns
Promise
<NativeFS
> –
- 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 calls thepyodide_py
APIregister_js_module()
.
- pyodide.runPython(code, options)#
Runs a string of Python code from JavaScript, using
pyodide.code.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
.
- Returns
any
– The result of the Python code translated to JavaScript. See the documentation forpyodide.code.eval_code
for more info.
- async pyodide.runPythonAsync(code, options)#
Run a Python code string with top level await using
pyodide.code.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("./repodata.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
.
- Returns
Promise
<any
> – The result of the Python code translated to JavaScript.
- 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. A batched handler or a raw handler can be provided (both not both). If neither is provided, we restore the default handler.
- Arguments
options.isatty (
boolean
) – Shouldisatty(stderr)
returntrue
orfalse
. Can only be set totrue
if a raw handler is provided (defaultfalse
).options.batched ((a:
string
) =>void
) – A batched handler is called with a string whenever a newline character is written is written or stderr is flushed. In the former case, the received line will end with a newline, in the latter case it will not. isatty(stderr) is set to false (when using a batched handler, stderr is buffered so it is impossible to make a tty with it).options.raw ((a:
number
) =>void
) – A raw handler is called with the handler is called with a number for each byte of the output to stderr.
- pyodide.setStdin(options)#
Set a stdin handler.
The stdin handler is called with zero arguments whenever stdin is read and the current input buffer is exhausted. It should return one of:
null
orundefined
: these are interpreted as end of file.a number
a string
an
ArrayBuffer
orTypedArray
withBYTES_PER_ELEMENT
equal to 1.
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, a new line is appended if one is not present and the resulting string is turned into a
Uint8Array
usingTextEncoder
.Returning a buffer is more efficient and allows returning partial lines of text.
- Arguments
options.autoEOF (
boolean
) – Insert an EOF automatically after each string or buffer? (defaulttrue
).options.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.stdin (
InFuncType
) – The stdin handler.
- pyodide.setStdout(options)#
Sets the standard out handler. A batched handler or a raw handler can be provided (both not both). If neither is provided, we restore the default handler.
- Arguments
options.isatty (
boolean
) – Shouldisatty(stdout)
returntrue
orfalse
. Can only be set totrue
if a raw handler is provided (defaultfalse
).options.batched ((a:
string
) =>void
) – A batched handler is called with a string whenever a newline character is written 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 ((a:
number
) =>void
) – A raw handler is called with the handler is called with a number for each byte of the output to stdout.
- pyodide.toPy(obj, options)#
Convert a JavaScript object to a Python object as best as possible.
This is similar to
JsProxy.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 ofJsProxy.to_py
.
- Returns
any
– The object converted to Python.
- pyodide.unpackArchive(buffer, format, options)#
Unpack an archive into a target directory.
- Arguments
buffer (
TypedArray
|ArrayBuffer
) – 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 calls thepyodide_py
APIunregister_js_module()
.- Arguments
name (
string
) – Name of the JavaScript module to remove
- class pyodide.PyBuffer()#
A class to allow access to a Python data buffers from JavaScript. These are produced by
PyProxy.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 );
- PyBuffer.c_contiguous#
type:
boolean
Is it C contiguous? See
memoryview.c_contiguous
.
- PyBuffer.data#
type:
TypedArray
The actual data. A typed array of an appropriate size backed by a segment of the WASM memory.
The
type
argument ofPyProxy.getBuffer
determines which sort ofTypedArray
orDataView
to return. By defaultPyProxy.getBuffer
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
data
TypedArray will contain data that is not part of the buffer. Modifying this data leads to undefined behavior.Readonly buffers
If
buffer.readonly
istrue
, you should not modify the buffer. Modifying a readonly buffer leads to undefined behavior.
- PyBuffer.f_contiguous#
type:
boolean
Is it Fortran contiguous? See
memoryview.f_contiguous
.
- PyBuffer.format#
type:
string
The format string for the buffer. See Format Strings and
memoryview.format
.
- PyBuffer.itemsize#
type:
number
How large is each entry (in bytes)? See
memoryview.itemsize
.
- PyBuffer.nbytes#
type:
number
The total number of bytes the buffer takes up. This is equal to
buff.data.byteLength
. Seememoryview.nbytes
.
- PyBuffer.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
.
- PyBuffer.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]
- PyBuffer.readonly#
type:
boolean
If the data is readonly, you should not modify it. There is no way for us to enforce this, but it may cause very weird behavior. See
memoryview.readonly
.
- PyBuffer.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
.
- PyBuffer.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
.
- PyBuffer.release()#
Release the buffer. This allows the memory to be reclaimed.
- class pyodide.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
.
PyProxy#
A PyProxy is an object that allows idiomatic use of a Python object from JavaScript. See Proxying from Python into JavaScript.
Attributes:
Functions:
This translates to the Python code |
|
This translates to the Python code |
|
|
The |
|
The |
|
Calls the function with a given this value and arguments provided individually. |
|
Call the function with key word arguments. |
Returns a |
|
async |
Calls |
|
Make a new PyProxy pointing to the same Python object. |
|
This translates to the Python code |
|
Destroy the |
async |
Calls |
|
This translates to the Python code |
|
Get a view of the buffer data which is usable from JavaScript. |
|
This translates to the Python code |
Check whether the PyProxy is awaitable. |
|
|
Check whether the PyProxy implements the Buffer Protocol. |
Check whether the PyProxy is callable. |
|
Check whether the PyProxy is iterable. |
|
Check whether the PyProxy is iterable. |
|
|
This translates to the Python code |
|
Throws a |
async |
Throws a |
|
This translates to the Python code |
Check whether the |
|
Check whether the |
|
Check whether the |
|
Check whether the |
|
async |
Calls |
|
Throws an exception into the Generator. |
async |
Throws an exception into the Generator. |
|
Converts the |
|
- PyProxy.[asyncIterator]()#
This translates to the Python code
aiter(obj)
. Return an async iterator associated to the proxy. See the documentation forSymbol.asyncIterator
.Present only if the proxied Python object is asynchronous iterable (i.e., has an
__aiter__()
method).This will be used implicitly by
for(let x of proxy){}
.- Returns
AsyncIterator
<any
,any
,any
> –
- PyProxy.[iterator]()#
This translates to the Python code
iter(obj)
. Return an iterator associated to the proxy. See the documentation forSymbol.iterator
Present only if the proxied Python object is iterable (i.e., has an
__iter__()
method).This will be used implicitly by
for(let x of proxy){}
.
- PyProxy.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()
.Present only if the proxied Python object is callable (i.e., has a
__call__()
method).- Arguments
thisArg (
any
) – Thethis
argument. Has no effect unless thePyProxy
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.
- PyProxy.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 PyProxy does not have
captureThis
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.Present only if the proxied Python object is callable (i.e., has a
__call__()
method)
- PyProxy.call(thisArg, ...jsargs)#
Calls the function with a given this value and arguments provided individually. See
Function.call()
.Present only if the proxied Python object is callable (i.e., has a
__call__()
method).- Arguments
thisArg (
any
) – Thethis
argument. Has no effect unless thePyProxy
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.
- PyProxy.callKwargs(...jsargs)#
Call the function with key word arguments. The last argument must be an object with the keyword arguments. Present only if the proxied Python object is callable (i.e., has a
__call__()
method).
- PyProxy.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
- Returns
PyProxy
– The resultingPyProxy
. It has the same lifetime as the originalPyProxy
but passesthis
to the wrapped function.
- async PyProxy.catch(onRejected)#
Calls
asyncio.ensure_future()
on the awaitable and executesonRejected(error)
if theFuture
fails.See the documentation for
Promise.catch()
.Present only if the proxied Python object is awaitable (i.e., has an
__await__()
method)
- PyProxy.copy()#
Make a new PyProxy pointing to the same Python object. Useful if the PyProxy is destroyed somewhere else.
- Returns
PyProxy
–
- PyProxy.delete(key)#
This translates to the Python code
del obj[key]
.Present only if the proxied Python object has a
__delitem__()
method.- Arguments
key (
any
) – The key to delete.
- 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.
- async PyProxy.finally(onFinally)#
Calls
asyncio.ensure_future()
on the awaitable and executesonFinally(error)
when theFuture
resolves.See the documentation for
Promise.finally()
.Present only if the proxied Python object is awaitable (i.e., has an
__await__()
method).
- PyProxy.get(key)#
This translates to the Python code
obj[key]
.Present only if the proxied Python object has a
__getitem__()
method.
- PyProxy.getBuffer(type)#
Get a view of the buffer data which is usable from JavaScript. No copy is ever performed.
Present only if the proxied Python object supports the Python Buffer Protocol.
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 suboffets (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
PyBuffer
–PyBuffer
- PyProxy.has(key)#
This translates to the Python code
key in obj
.Present only if the proxied Python object has a
__contains__()
method.
- PyProxy.isAwaitable()#
Check whether the PyProxy is awaitable. A Typescript type guard, if this function returns true Typescript considers the PyProxy to be a
Promise
.- Returns
boolean
(typeguard forPyProxyAwaitable
) –
- PyProxy.isBuffer()#
Check whether the PyProxy implements the Buffer Protocol. A Typescript type guard for
PyProxy.getBuffer
.- Returns
boolean
(typeguard forPyProxyBuffer
) –
- PyProxy.isCallable()#
Check whether the PyProxy is callable. A Typescript type guard, if this returns true then Typescript considers the Proxy to be callable of signature
(args... : any[]) => PyProxy | number | bigint | string | boolean | undefined
.- Returns
boolean
(typeguard forPyProxyCallable
) –
- PyProxy.isIterable()#
Check whether the PyProxy is iterable. A Typescript type guard for
PyProxy.[iterator]
.- Returns
boolean
(typeguard forPyProxyIterable
) –
- PyProxy.isIterator()#
Check whether the PyProxy is iterable. A Typescript type guard for
PyProxy.next
.- Returns
boolean
(typeguard forPyProxyIterator
) –
- PyProxy.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){}
.Present only if the proxied Python object is an iterator (i.e., has a
send()
or__next__()
method).- 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}
.
- PyProxy.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()
.Present only if the proxied Python object is a generator.
- 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}
.
- async PyProxy.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()
Present only if the proxied Python object is an asynchronous generator.
- 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}
.
- PyProxy.set(key, value)#
This translates to the Python code
obj[key] = value
.Present only if the proxied Python object has a
__setitem__()
method.
- PyProxy.supportsGet()#
Check whether the
PyProxy.get
method is available on this PyProxy. A Typescript type guard.- Returns
boolean
(typeguard forPyProxyWithGet
) –
- PyProxy.supportsHas()#
Check whether the
PyProxy.has
method is available on this PyProxy. A Typescript type guard.- Returns
boolean
(typeguard forPyProxyWithHas
) –
- PyProxy.supportsLength()#
Check whether the
PyProxy.length
getter is available on this PyProxy. A Typescript type guard.- Returns
boolean
(typeguard forPyProxyWithLength
) –
- PyProxy.supportsSet()#
Check whether the
PyProxy.set
method is available on this PyProxy. A Typescript type guard.- Returns
boolean
(typeguard forPyProxyWithSet
) –
- async PyProxy.then(onFulfilled, onRejected)#
Calls
asyncio.ensure_future()
on the awaitable, executesonFulfilled(result)
when theFuture
resolves successfully, executesonRejected(error)
when theFuture
fails. Will be used implicitly byawait obj
.See the documentation for
Promise.then()
.Present only if the proxied Python object is awaitable (i.e., has an
__await__()
method).
- PyProxy.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}
.
- async PyProxy.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}
.
- 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.create_pyproxies (
boolean
) – If false,toJs
will throw aConversionError
rather than producing aPyProxy
.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 as pyproxies, and then later iterate over pyproxies to destroy all of created proxies.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()
.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).
- Returns
any
– The JavaScript object resulting from the conversion.