or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

error-handling.mdindex.mdobject-creation.mdpyobject.mdpython-modules.mdtype-conversion.md
tile.json

tessl/npm-pymport

Node.js library that enables seamless integration of Python libraries into JavaScript applications

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/pymport@1.5.x

To install, run

npx @tessl/cli install tessl/npm-pymport@1.5.0

index.mddocs/

pymport

pymport is a Node.js library that enables seamless integration of Python libraries into JavaScript applications. It allows developers to import and use standard Python libraries like NumPy, Pandas, and SciPy directly within Node.js environments without modifications, bridging the gap between Python's rich ecosystem and JavaScript applications.

Package Information

  • Package Name: pymport
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install pymport
  • Python Dependencies: Built-in Python interpreter (3.12) included
  • Node.js Support: >= 16.0.0
  • Platforms: Windows, Ubuntu, macOS

Core Imports

import { pymport, proxify, PyObject, pyval, version } from 'pymport';

For CommonJS:

const { pymport, proxify, PyObject, pyval, version } = require('pymport');

TypeScript imports (additional types):

import { pymport, proxify, PyObject, pyval, version, PyNumber, PythonError } from 'pymport';

Additional modules:

import { toTypedArray, toPythonArray, getJSType, getPythonType } from 'pymport/array';
import { pymport as proxifiedPymport, PyObject as proxifiedPyObject, pyval as proxifiedPyval } from 'pymport/proxified';

Basic Usage

import { pymport, proxify } from 'pymport';

// Import Python numpy module
const np = proxify(pymport('numpy'));

// Use numpy functions naturally
const array = np.arange(15).reshape(3, 5);
const ones = np.ones([2, 3], { dtype: np.int16 });

// Convert Python objects to JavaScript
const jsArray = array.toJS();
console.log(jsArray);

// Call Python functions with JavaScript arguments
const sum = np.sum(array);
console.log(`Sum: ${sum.toJS()}`);

Architecture

pymport is built around several key components:

  • PyObject Wrapper: Core class that wraps Python objects and provides JavaScript interface
  • Proxification System: Transparent proxy layer that makes Python objects behave like native JavaScript objects
  • Type Conversion: Bidirectional conversion between Python and JavaScript data types
  • Module Import System: Direct import of Python modules with full API access
  • Memory Management: Proper handling between Python GC and V8 memory systems
  • Built-in Python Environment: Embedded Python interpreter with package management

Package Management

pymport includes built-in CLI tools for managing Python packages within the embedded interpreter:

# Install Python packages for use with pymport
npx pympip install numpy pandas matplotlib
npx pympip3 install scikit-learn tensorflow

# List installed packages
npx pympip list

# Uninstall packages
npx pympip uninstall package_name

# Show package info
npx pympip show package_name

The pympip and pympip3 tools are equivalent and provide access to the embedded Python interpreter's pip package manager.

Capabilities

Python Module Import

Core functionality for importing and using Python modules with full type safety and transparent object interaction.

function pymport(name: string): PyObject;
function proxify(v: PyObject, name?: string): any;
function pyval(code: string, globals?: PyObject | Record<string, any>, locals?: PyObject | Record<string, any>): PyObject;
declare const version: VersionInfo;

Python Module Import

PyObject Manipulation

Complete PyObject class with all methods for interacting with Python objects, including conversion, property access, and method calls.

class PyObject implements Iterable<PyObject> {
  // Core properties
  readonly id: number;
  readonly callable: boolean;
  readonly type: string;
  readonly length: number | undefined;
  readonly constr: PyObject;

  // Object interaction
  get(name: string): PyObject;
  has(name: string | any): boolean;
  item(index: any): PyObject;
  call(...args: any[]): PyObject;
  callAsync(...args: any[]): Promise<PyObject>;
  
  // Conversion methods
  toJS(opts?: { depth?: number; buffer?: boolean; }): any;
  valueOf(): any;
  toString(): string;
  
  // Iteration support
  [Symbol.iterator](): Iterator<PyObject>;
  map<T, U>(callback: (this: U, element: PyObject, index: number, iterable: PyObject) => T, thisArg?: U): T[];
  with<T>(fn: (v: PyObject) => T): T;
}

PyObject Manipulation

Python Object Creation

Static factory methods for creating Python objects from JavaScript values, supporting all Python built-in types.

// Static factory methods
static int(v: number | bigint | PyObject): PyObject;
static float(v: number | PyObject): PyObject;
static string(v: string): PyObject;
static dict(object: Record<string, any>): PyObject;
static list(array: any[] | PyObject): PyObject;
static tuple(array: any[] | PyObject): PyObject;
static set(v: any[] | PyObject): PyObject;
static frozenSet(v: any[] | PyObject): PyObject;
static slice(slice: [PyNumber, PyNumber, PyNumber] | { start?: PyNumber; stop?: PyNumber; step?: PyNumber; }): PyObject;
static bytes(buffer: Buffer): PyObject;
static bytearray(buffer: Buffer): PyObject;
static memoryview(buffer: Buffer): PyObject;
static func(fn: (...args: any[]) => any): PyObject;
static fromJS(v: any): PyObject;
static keys(obj: PyObject): PyObject;
static values(obj: PyObject): PyObject;

Python Object Creation

Type Conversion & Interoperability

Advanced type conversion between Python and JavaScript, including typed arrays, buffers, and custom objects.

function toTypedArray(array: PyObject): TypedArray;
function toPythonArray(array: TypedArray): PyObject;
function getJSType(array: PyObject): TypedArrayConstructor;
function getPythonType(array: TypedArray): string;
function pyval(code: string, globals?: PyObject | Record<string, any>, locals?: PyObject | Record<string, any>): PyObject;

Type Conversion

Error Handling

Python exception handling with full traceback information and error type mapping.

type PythonError = (Error | TypeError | RangeError) & {
  pythonType: PyObject;
  pythonValue: PyObject;
  pythonTrace: PyObject;
};

Error Handling

Types

type PyNumber = number | PyObject | null;

type TypedArray = Uint8Array | Int8Array | Uint16Array | Int16Array | 
  Uint32Array | Int32Array | BigUint64Array | BigInt64Array | 
  Float32Array | Float64Array;

type TypedArrayConstructor = 
  typeof Uint8Array | typeof Int8Array | typeof Uint16Array | typeof Int16Array |
  typeof Uint32Array | typeof Int32Array | typeof BigUint64Array | typeof BigInt64Array |
  typeof Float32Array | typeof Float64Array;

interface VersionInfo {
  readonly pymport: {
    readonly major: number;
    readonly minor: number;
    readonly patch: number;
    readonly suffix: string;
  };
  readonly pythonLibrary: {
    readonly builtin: boolean;
    readonly major: number;
    readonly minor: number;
    readonly micro: number;
    readonly release: number;
    readonly serial: number;
    /** Hex number representation of Python version */
    readonly version: string;
  };
  readonly pythonHome: string;
  /** Supported only on Python 3.10+ */
  readonly pythonRuntime: null | string;
}