Skip to content
Momtchil Momtchev edited this page Jan 19, 2023 · 6 revisions

API

Table of Contents

PyObject

JavaScript representation of a Python object

id

Numeric id of the object, it is generally the same as the one returned by id()

Type: number

callable

Is the property callable

Type: boolean

type

The underlying Python type, equivalent to JavaScript typeof

Type: string

length

Length of the underlying object if it is defined

Type: (number | undefined)

constr

The underlying Python type, equivalent to Python type() or JavaScript constructor

Type: PyObject

get

Get a property from the object, equivalent to Python member operator .

Type: function (name: string): PyObject

Parameters

  • name string property name

Returns PyObject

has

Check if a property exists. Equivalent to Python hasattr(o, name)

Type: function (name: (string | any)): boolean

Parameters

  • key (string | any) property name, only sets accept values that are not a string

Returns boolean

item

Retrieve an element by index, equivalent to Python subscript operator[]

Type: function (index: any): PyObject

Parameters

  • index any index

Returns boolean

with

Runs the provided function in the context of this object, equivalent to Python with

Type: function (fn: function (v: PyObject): T): T

Returns PyObject

call

Call a callable PyObject, throws if the underlying object is not callable

Type: function (...args: Array<any>): PyObject

Parameters

  • args ...Array<any> function arguments

Returns PyObject

callAsync

Asynchronously call a callable PyObject, rejects if the underlying object is not callable

Type: function (...args: Array<any>): Promise<PyObject>

Parameters

  • args ...Array<any> function arguments

Returns Promise<PyObject>

toJS

Transform the PyObject to a plain JS object. Equivalent to valueOf().

A float becomes a Number.

An int becomes a Number if it is in the safe integer number range or a BigInt otherwise.

A bool becomes a bool.

None becomes null.

An unicode string becomes a string.

A list, a tuple, a set or a frozenset becomes an array

A dictionary becomes an object.

Any object implementing the Buffer Protocol - bytes, bytearray or a memoryview - becomes a Buffer. The memory referenced by the Buffer is a copy of the Python memory. This behavior can be disabled by passing { buffer: false }.

A callable becomes a native (binary) function.

A module becomes an object.

Everything else remains a PyObject.

The maximum recursion depth can be set by passing { depth: number }. Without this parameter pymport will go down to the furthest possible level. By setting the depth to 1 it is possible to transform a Python list to a JavaScript array while keeping all elements as Python objects. Refer to the performance section of the wiki for the possible implications and especially the memory overhead.

Type: function (opts: {depth: number?, buffer: boolean?}): any

Parameters

  • opts object? options

    • opts.depth number? maximum recursion depth, undefined for unlimited
    • opts.buffer boolean? do not convert objects that implement only the Buffer protocol

Returns any

valueOf

Transform the PyObject to a plain JS object. Equivalent to toJS().

Type: function (): any

Returns any

toString

Use the Python str() built-in on the object

Type: function (): string

Returns string

iterator

Return an iterator over the object's elements. An object is iterable if it has length.

Type: function (): Iterator<PyObject>

Returns string

map

Create a new array populated with the results of calling a provided function on every element in the calling array.

Works on all iterable objects.

Type: function (callback: function (this: U, element: PyObject, index: number, iterable: PyObject): T, thisArg: U): Array<T>

Parameters

  • this unknown? optional this value to be provided to the function

int

Construct a PyObject integer from a JS number or a PyObject

Type: function (v: (number | bigint | PyObject)): PyObject

Parameters

  • number number

Returns PyObject

float

Construct a PyObject float from a JS number or a PyObject

Type: function (v: (number | PyObject)): PyObject

Parameters

  • number number

Returns PyObject

string

Construct a PyObject string from a JS string

Type: function (v: string): PyObject

Parameters

  • string string

Returns PyObject

dict

Construct a PyObject dictionary from a JS object

Type: function (object: Record<string, any>): PyObject

Parameters

  • object Record<string, any>

Returns PyObject

list

Construct a PyObject list from a JS array or an iterable PyObject

Type: function (array: (Array<any> | PyObject)): PyObject

Parameters

Returns PyObject

tuple

Construct a PyObject tuple from a JS array or a PyObject list

Type: function (array: (Array<any> | PyObject)): PyObject

Parameters

Returns PyObject

set

Construct a PyObject set from a JS array or an iterable PyObject

Type: function (v: (Array<any> | PyObject)): PyObject

Parameters

  • array Array<any>

Returns PyObject

frozenSet

Construct a PyObject frozenset from a JS array or an iterable PyObject

Type: function (v: (Array<any> | PyObject)): PyObject

Parameters

  • array Array<any>

Returns PyObject

slice

Construct a PyObject slice from three elements (start, stop, step). In Python, a slice and a range are two different object types: https://til.hashrocket.com/posts/5zuzolqlcb-range-v-slice

Type: function (slice: ([PyNumber, PyNumber, PyNumber] | {start: PyNumber?, stop: PyNumber?, step: PyNumber?})): PyObject

Returns PyObject

bytes

Construct a PyObject bytes from a Buffer. The resulting object is a copy.

Type: function (buffer: Buffer): PyObject

Parameters

  • buffer Buffer

Returns PyObject

bytearray

Construct a PyObject bytearray from a Buffer. The resulting object is a copy.

Type: function (buffer: Buffer): PyObject

Parameters

  • buffer Buffer

Returns PyObject

memoryview

Construct a PyObject memoryview from a Buffer. The resulting object references directly the Buffer. The Buffer is guaranteed to stay in memory for as long as the memoryview exists. This is the only case in which V8 objects can be held by the Python GC.

Type: function (buffer: Buffer): PyObject

Parameters

  • buffer Buffer

Returns PyObject

func

Construct a PyObject pymport.js_function from a JS function. The resulting object is a Python callable.

Type: function (fn: function (...args: Array<any>): any): PyObject

Returns PyObject

fromJS

Construct an automatically typed PyObject from a plain JS value. The PyObject is a copy by value unless explicitly mentioned.

A number becomes an int when it has no decimal part or a float when it has one.

A BigInt becomes an int.

A bool becomes a bool.

Undefined and null become None.

A string becomes an unicode string.

An array becomes a list.

An object becomes a dictionary.

A PyObject or a proxified PyObject is always passed by reference and reverts to its Python type.

A Buffer becomes a bytearray.

A JS function (including a native function) becomes a callable pymport.js_function

Type: function (v: any): PyObject

Parameters

  • value any

Returns PyObject

keys

Retrieve a list with the keys of the dictionary, equivalent to JS Object.keys()

Type: function (obj: PyObject): PyObject

Returns PyObject

values

Retrieve a list with the values of the dictionary, equivalent to JS Object.values()

Type: function (obj: PyObject): PyObject

Returns PyObject

pymport

Import a Python module.

Default search location is determined by the Python interpreter library. It can be overridden by setting the PYTHONPATH environment variable.

If you want to load a Python file in the same directory as the calling JS you can use

process.env['PYTHONPATH'] = __dirname

before importing pymport - once Python has been initialized further modifications will have no effect.

Parameters

  • name string Python module name

Returns PyObject

proxify

Create a proxified version of a PyObject that works like a native Python object. All values returned by its methods will also be proxified.

Parameters

  • v PyObject
  • name string? optional name to be assigned to a proxified function
  • object PyObject object to proxify

Returns any

pyval

Eval a Python fragment. Uses Python eval which is a special language context. The Python code must be an expression that evaluates to a value and not a statement. Refer to the Python documentation for more information on what is allowed in this context. If you need to execute statements, you should place them in a file and load it as a module.

Parameters

  • code string Python code
  • globals (PyObject | Record<string, any>)? Optional global context
  • locals (PyObject | Record<string, any>)? Optional local context

Returns PyObject

version

Hex number

Type: string

version

Version information

Type: {pymport: {major: number, minor: number, patch: number, suffix: string}, pythonLibrary: {builtin: boolean, major: number, minor: number, micro: number, release: number, serial: number, version: string}, pythonHome: string, pythonRuntime: (null | string)}

pythonRuntime

Supported only on Python 3.10+

Type: (null | string)

PythonError

Errors thrown from Python have a pythonTrace property that contains the Python traceback

Type: any