0
# pymport
1
2
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.
3
4
## Package Information
5
6
- **Package Name**: pymport
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install pymport`
10
- **Python Dependencies**: Built-in Python interpreter (3.12) included
11
- **Node.js Support**: >= 16.0.0
12
- **Platforms**: Windows, Ubuntu, macOS
13
14
## Core Imports
15
16
```javascript
17
import { pymport, proxify, PyObject, pyval, version } from 'pymport';
18
```
19
20
For CommonJS:
21
22
```javascript
23
const { pymport, proxify, PyObject, pyval, version } = require('pymport');
24
```
25
26
TypeScript imports (additional types):
27
28
```typescript
29
import { pymport, proxify, PyObject, pyval, version, PyNumber, PythonError } from 'pymport';
30
```
31
32
Additional modules:
33
34
```javascript
35
import { toTypedArray, toPythonArray, getJSType, getPythonType } from 'pymport/array';
36
import { pymport as proxifiedPymport, PyObject as proxifiedPyObject, pyval as proxifiedPyval } from 'pymport/proxified';
37
```
38
39
## Basic Usage
40
41
```javascript
42
import { pymport, proxify } from 'pymport';
43
44
// Import Python numpy module
45
const np = proxify(pymport('numpy'));
46
47
// Use numpy functions naturally
48
const array = np.arange(15).reshape(3, 5);
49
const ones = np.ones([2, 3], { dtype: np.int16 });
50
51
// Convert Python objects to JavaScript
52
const jsArray = array.toJS();
53
console.log(jsArray);
54
55
// Call Python functions with JavaScript arguments
56
const sum = np.sum(array);
57
console.log(`Sum: ${sum.toJS()}`);
58
```
59
60
## Architecture
61
62
pymport is built around several key components:
63
64
- **PyObject Wrapper**: Core class that wraps Python objects and provides JavaScript interface
65
- **Proxification System**: Transparent proxy layer that makes Python objects behave like native JavaScript objects
66
- **Type Conversion**: Bidirectional conversion between Python and JavaScript data types
67
- **Module Import System**: Direct import of Python modules with full API access
68
- **Memory Management**: Proper handling between Python GC and V8 memory systems
69
- **Built-in Python Environment**: Embedded Python interpreter with package management
70
71
## Package Management
72
73
pymport includes built-in CLI tools for managing Python packages within the embedded interpreter:
74
75
```bash
76
# Install Python packages for use with pymport
77
npx pympip install numpy pandas matplotlib
78
npx pympip3 install scikit-learn tensorflow
79
80
# List installed packages
81
npx pympip list
82
83
# Uninstall packages
84
npx pympip uninstall package_name
85
86
# Show package info
87
npx pympip show package_name
88
```
89
90
The `pympip` and `pympip3` tools are equivalent and provide access to the embedded Python interpreter's pip package manager.
91
92
## Capabilities
93
94
### Python Module Import
95
96
Core functionality for importing and using Python modules with full type safety and transparent object interaction.
97
98
```typescript { .api }
99
function pymport(name: string): PyObject;
100
function proxify(v: PyObject, name?: string): any;
101
function pyval(code: string, globals?: PyObject | Record<string, any>, locals?: PyObject | Record<string, any>): PyObject;
102
declare const version: VersionInfo;
103
```
104
105
[Python Module Import](./python-modules.md)
106
107
### PyObject Manipulation
108
109
Complete PyObject class with all methods for interacting with Python objects, including conversion, property access, and method calls.
110
111
```typescript { .api }
112
class PyObject implements Iterable<PyObject> {
113
// Core properties
114
readonly id: number;
115
readonly callable: boolean;
116
readonly type: string;
117
readonly length: number | undefined;
118
readonly constr: PyObject;
119
120
// Object interaction
121
get(name: string): PyObject;
122
has(name: string | any): boolean;
123
item(index: any): PyObject;
124
call(...args: any[]): PyObject;
125
callAsync(...args: any[]): Promise<PyObject>;
126
127
// Conversion methods
128
toJS(opts?: { depth?: number; buffer?: boolean; }): any;
129
valueOf(): any;
130
toString(): string;
131
132
// Iteration support
133
[Symbol.iterator](): Iterator<PyObject>;
134
map<T, U>(callback: (this: U, element: PyObject, index: number, iterable: PyObject) => T, thisArg?: U): T[];
135
with<T>(fn: (v: PyObject) => T): T;
136
}
137
```
138
139
[PyObject Manipulation](./pyobject.md)
140
141
### Python Object Creation
142
143
Static factory methods for creating Python objects from JavaScript values, supporting all Python built-in types.
144
145
```typescript { .api }
146
// Static factory methods
147
static int(v: number | bigint | PyObject): PyObject;
148
static float(v: number | PyObject): PyObject;
149
static string(v: string): PyObject;
150
static dict(object: Record<string, any>): PyObject;
151
static list(array: any[] | PyObject): PyObject;
152
static tuple(array: any[] | PyObject): PyObject;
153
static set(v: any[] | PyObject): PyObject;
154
static frozenSet(v: any[] | PyObject): PyObject;
155
static slice(slice: [PyNumber, PyNumber, PyNumber] | { start?: PyNumber; stop?: PyNumber; step?: PyNumber; }): PyObject;
156
static bytes(buffer: Buffer): PyObject;
157
static bytearray(buffer: Buffer): PyObject;
158
static memoryview(buffer: Buffer): PyObject;
159
static func(fn: (...args: any[]) => any): PyObject;
160
static fromJS(v: any): PyObject;
161
static keys(obj: PyObject): PyObject;
162
static values(obj: PyObject): PyObject;
163
```
164
165
[Python Object Creation](./object-creation.md)
166
167
### Type Conversion & Interoperability
168
169
Advanced type conversion between Python and JavaScript, including typed arrays, buffers, and custom objects.
170
171
```typescript { .api }
172
function toTypedArray(array: PyObject): TypedArray;
173
function toPythonArray(array: TypedArray): PyObject;
174
function getJSType(array: PyObject): TypedArrayConstructor;
175
function getPythonType(array: TypedArray): string;
176
function pyval(code: string, globals?: PyObject | Record<string, any>, locals?: PyObject | Record<string, any>): PyObject;
177
```
178
179
[Type Conversion](./type-conversion.md)
180
181
### Error Handling
182
183
Python exception handling with full traceback information and error type mapping.
184
185
```typescript { .api }
186
type PythonError = (Error | TypeError | RangeError) & {
187
pythonType: PyObject;
188
pythonValue: PyObject;
189
pythonTrace: PyObject;
190
};
191
```
192
193
[Error Handling](./error-handling.md)
194
195
## Types
196
197
```typescript { .api }
198
type PyNumber = number | PyObject | null;
199
200
type TypedArray = Uint8Array | Int8Array | Uint16Array | Int16Array |
201
Uint32Array | Int32Array | BigUint64Array | BigInt64Array |
202
Float32Array | Float64Array;
203
204
type TypedArrayConstructor =
205
typeof Uint8Array | typeof Int8Array | typeof Uint16Array | typeof Int16Array |
206
typeof Uint32Array | typeof Int32Array | typeof BigUint64Array | typeof BigInt64Array |
207
typeof Float32Array | typeof Float64Array;
208
209
interface VersionInfo {
210
readonly pymport: {
211
readonly major: number;
212
readonly minor: number;
213
readonly patch: number;
214
readonly suffix: string;
215
};
216
readonly pythonLibrary: {
217
readonly builtin: boolean;
218
readonly major: number;
219
readonly minor: number;
220
readonly micro: number;
221
readonly release: number;
222
readonly serial: number;
223
/** Hex number representation of Python version */
224
readonly version: string;
225
};
226
readonly pythonHome: string;
227
/** Supported only on Python 3.10+ */
228
readonly pythonRuntime: null | string;
229
}
230
```