<p align="center"> <a href="https://alibaba.github.io/pipcook/"> <img alt="boa" src="./logo.png" style="width:100%"> </a> </p>

Introduction to Boa

Boa is the Python Bridge Layer in Pipcook, it lets you call Python functions seamlessly in Node.js, it delivers any Python module for Node.js developer in lower-cost to learn or use.

Quick Start

Install Boa from npm:

$ npm install @pipcook/boa

Let's have a glance on how to call to Python's function:

const boa = require('@pipcook/boa');
const os = boa.import('os');
console.log(os.getpid()); // prints the pid from python.

// using keyword arguments namely `kwargs`
os.makedirs('..', boa.kwargs({
  mode: 0x777,
  exist_ok: false,
}));

// using bult-in functions
const { range, len } = boa.builtins();
const list = range(0, 10); // create a range array
console.log(len(list)); // 10
console.log(list[2]); // 2

Install Python Package

By default, Boa will install a conda virtual environment under the path of the Boa package. To make it easier to install python libraries, you can run:

$ ./node_modules/.bin/bip install <package-name>

bip is an alias of pip that points to the correct Python environment.

GPT Prompts to Generate boa-based JavaScript

For Python beginners, writing JavaScript code based on Boa can be quite challenging, as we may not always be familiar with Python's ecosystem. Therefore, this project has prepared a prompt powered by ChatGPT. With it, developers can simply send the corresponding Python source code to ChatGPT and receive the corresponding Boa code, along with related explanations.

Now we only have Chinese and English versions prepared:

(中文版本提示词)

你作为一个 Boa 代码转换器用于将 Python 的代码转换为依赖 Boa 的 JavaScript 代码，在输出的代码中首先会依赖 @pipcook/boa，然后将 Python import 语法转换为 boa.import(x)，x 即 Python 中的包名，接下来的转换规则如下：

1. 遇到 keyword arguments，使用 boa.kwargs(map) 包装，map 中的 key 表示 Python 函数定义的 key，map 中的 value 即参数值
2. Python 中的函数调用可以直接转换为 JavaScript 的同名函数调用
3. Python 中的内置对象通过 boa.builtins() 获取

如果明白以上规则，请回复我明白了。

(English prompt)

As a Boa code converter, you are responsible for converting Python code into JavaScript code that depends on Boa. In the output code, you will first rely on "@pipcook/boa". Then, Python's import syntax is converted to "boa.import(x)", where "x" represents the package name in Python. The following conversion rules apply:

When encountering keyword arguments, wrap them with "boa.kwargs(map)", where "map" represents the key-value pairs of the arguments.
Python function calls can be directly converted to JavaScript function calls with the same name.
Python built-in objects can be accessed through "boa.builtins()".
If you understand the above rules, please reply with "I understand".

Chat Examples

An example in Chinese:

An example in English:

API References

A Connection between 2 languages(ecosystems) has huge works to be done, even though this package is working only on the unilateral from Python to JavaScript. The most difficult part is that for developers, they need to understand the correspondence between the two languages and ecosystems. Therefore, a good design principle will make developers reduce learning costs.

boa

require('@pipcook/boa') returns the root object, which will be your entry point to all Python functions, and it provides these methods:

.builtins()

Gets the Python's built-in functions, for example:

const { len, range } = boa.builtins();
len([1, 2, 3]); // 3
len(range(0, 10)); // 10

.import(mod)

Imports a Python module in your current environment, the module includes:

• system modules like os, string and re.
• third-party modules like numpy and request via pip.

To call the function, you should pass a mod argument for the module that you want to import.

const os = boa.import('os');
const str = boa.import('string');
const numpy = boa.import('numpy');

This returns an instance of PythonObjectWrapper or a JavaScript primitive value for some special cases.

.kwargs(map)

Creates a Python's keyword arguments, Python provides a way to map arguments with names:

fs.open('./a-file-to-open', mode=0e777)

Correspondingly, this function is used to represent a keyword arguments, and the specific usage is very easy to understand:

const fs = boa.import('fs');
fs.open('./a-file-to-open', boa.kwargs({ mode: 0e777 }));

.with(ctx, fn)

It's equivalent to the with-statement in Python, this would be called with an object ctx that supports the context management protocol (that is, has __enter__() and __exit__() methods). And 2nd fn is corresponding to the execution block, A simple example is as follows:

boa.with(localcontext(), (ctx) => {
  // execution
  // the ctx is localcontext().__enter().
});

.eval(str)

Execute Python expression in the context specified, here is a simple call:

boa.eval('len([10, 20])');
// 2

Alternatively, developers can use [tagged template literal][] to pass variables that have been defined in JavaScript:

const elem = np.array([[1, 2, 3], [4, 5, 6]], np.int32);
boa.eval`${elem} + 100`;  // do matrix + operation
boa.eval`len(${elem})`;   // equivalent to `len(elem)`

For multi-line code, Python 3 does not provide a mechanism to return a value, so the eval function can only handle single-line Python expressions.

.bytes(str)

A shortcut to create a Python's bytes literal from JavaScript string, it's equivalent to b'foobar' in Python.

const { bytes } = boa;
bytes('foobar'); // "b'foobar'"

The bytes(str) function simply creates a plain object that is used to pass a string to a Python function as a bytes literal, but does not correspond to any Python object itself. Alternatively, you could use Python's builtin class bytes for creating a real object:

const { bytes } = boa.builtins();
const foobar = Buffer.from('foobar');
bytes.fromhex(foobar.toString('hex'));
// "b'foobar'"

Class PythonObjectWrapper

This class represents a wrapper for the corresponding object in Python runtime, it must be returned only from boa methods like boa.builtins and boa.import.

creation of instance

In order for developers to use Python objects seamlessly, creating a PythonObjectWrapper requires some necessary steps.

First, check the type of the Python object under instance. If it is one of the following types, it will be converted to the corresponding primitive type.

| python type | primitive | |---------------|--------------| | int,float | number | | int64 | bigint | | float64 | bigdecimal | | bool | boolean | | str | string | | NoneType | null |

If the type of the object that needs to be wrapped is not in the above primitive, a temporary object will be created, and methods and properties will be defined through Object.defineProperties.

On an instance of PythonObjectWrapper, developers can directly obtain values through the property way, just like using those in Python. This is because we use [ES6 Proxy][], so the last step, we created a Proxy Object, configured with 3 trap handlers, get, set, apply, and finally returns this proxy object.

property accessor

At [Python][] language, an object has attr and item accessors, and they use different expressions:

• x.y is for attr accessor
• m[n] is for item accessor

Unfortunately, [ES6 Proxy][] does not distinguish the above things. Therefore, it's needed to define an algorithm to confirm their priority in a time of operation.

• given a name variable which is passed by [ES6 Proxy][]'s get handler.
• check the name property is owned by the JavaScript object via .hasOwnProperty().
  • return the property if it's truthy.
• check the name property is owned by the object's class via .constructor.prototype.hasOwnProperty().
  • return the property if it's truthy.
• check if name is a numeric representation.
  • if it's truthy, call the internal method .__getitem__(i) for item accessor.
  • otherwise
    • try to access the attr via the internal method .__getattr__().
      • if no exceptions, create the new instance from the value and return.
    • try to access the item via the internal method .__getitem__().
      • if no exceptions, create the new instance from the value and return.
    • otherwise, return undefined.

To better understand the algorithm above, let's look at some examples:

const boa = require('@pipcook/boa');
const { abs, tuple } = boa.builtins();

{
  console.log(abs(-100));  // 100
  console.log(abs(100));   // 100
}
{
  const re = boa.import('re');
  const m = re.search('(?<=abc)def', 'abcdef');
  console.log(m.group(0)); // 'def'
}
{
  // make sure the `numpy` is in your current python env.
  const np = boa.import('numpy');
  const x0 = np.array([[1, 2, 3], [4, 5, 6]], np.int32);
  const x1 = np.arange(15).reshape(3, 5);
  const x2 = np.zeros(tuple([3, 4]));
}

As mentioned above, in addition to dynamically obtaining objects from the [Python][] runtime, the class PythonObjectWrapper also defines the following public methods built into JavaScript.

.prototype.toString()

Returns a string for representing the object, internally it calls the CPython's [PyObject_Str