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
```