0
# Python Module Import
1

2
Core functionality for importing and using Python modules with full access to their APIs and transparent JavaScript integration.
3

4
## Capabilities
5

6
### Module Import Function
7

8
Import any Python module by name, returning a PyObject wrapper that provides access to all module attributes and functions.
9

10
```typescript { .api }
11
/**
12
 * Import a Python module by name
13
 * @param name - Python module name (e.g., 'numpy', 'pandas', 'sys')
14
 * @returns PyObject wrapper for the imported module
15
 */
16
function pymport(name: string): PyObject;
17
```
18

19
**Usage Examples:**
20

21
```javascript
22
import { pymport } from 'pymport';
23

24
// Import standard library modules
25
const sys = pymport('sys');
26
const os = pymport('os');
27

28
// Import third-party packages (after installing via pympip)
29
const numpy = pymport('numpy');
30
const pandas = pymport('pandas');
31

32
// Access module attributes
33
console.log(sys.get('version').toString());
34
console.log(os.get('name').toString());
35

36
// Call module functions
37
const array = numpy.get('array').call([1, 2, 3, 4, 5]);
38
```
39

40
### Proxification Function
41

42
Create a proxified version of a PyObject that behaves like a native JavaScript object, enabling natural Python-like syntax.
43

44
```typescript { .api }
45
/**
46
 * Create a proxified version of a PyObject for natural JavaScript interaction
47
 * @param v - PyObject to proxify
48
 * @param name - Optional name for proxified function objects
49
 * @returns Proxified object that behaves like native JavaScript
50
 */
51
function proxify(v: PyObject, name?: string): any;
52
```
53

54
**Usage Examples:**
55

56
```javascript
57
import { pymport, proxify } from 'pymport';
58

59
// Standard PyObject usage (verbose)
60
const numpy = pymport('numpy');
61
const array = numpy.get('array').call([1, 2, 3]);
62
const reshaped = array.get('reshape').call(3, 1);
63

64
// Proxified usage (natural Python-like syntax)
65
const np = proxify(pymport('numpy'));
66
const array2 = np.array([1, 2, 3]);
67
const reshaped2 = array2.reshape(3, 1);
68

69
// Proxified functions work with method chaining
70
const result = np.arange(12).reshape(3, 4).sum();
71

72
// Access properties naturally
73
console.log(np.pi); // π constant
74
console.log(np.__version__); // numpy version
75
```
76

77
### Python Code Evaluation
78

79
Execute Python expressions with optional global and local contexts, useful for dynamic Python code execution.
80

81
```typescript { .api }
82
/**
83
 * Evaluate a Python expression and return the result
84
 * @param code - Python code string (must be an expression, not statements)
85
 * @param globals - Optional global context for execution
86
 * @param locals - Optional local context for execution
87
 * @returns PyObject result of the evaluation
88
 */
89
function pyval(
90
  code: string,
91
  globals?: PyObject | Record<string, any>,
92
  locals?: PyObject | Record<string, any>
93
): PyObject;
94
```
95

96
**Usage Examples:**
97

98
```javascript
99
import { pyval, pymport } from 'pymport';
100

101
// Simple expression evaluation
102
const result = pyval('2 + 3 * 4');
103
console.log(result.toJS()); // 14
104

105
// Using imported modules in evaluation
106
const np = pymport('numpy');
107
const array = pyval('np.array([1, 2, 3]) * 2', { np });
108
console.log(array.toJS()); // [2, 4, 6]
109

110
// Complex expressions with variables
111
const globals = { x: 10, y: 20 };
112
const result2 = pyval('x ** 2 + y ** 2', globals);
113
console.log(result2.toJS()); // 500
114
```
115

116
## Module Path Configuration
117

118
Python module search paths can be configured before importing pymport:
119

120
```javascript
121
// Set Python path to include local modules
122
process.env['PYTHONPATH'] = __dirname;
123

124
// Import pymport after setting environment
125
const { pymport } = require('pymport');
126

127
// Now can import local Python files
128
const myModule = pymport('my_local_module');
129
```
130

131
## Supported Python Modules
132

133
pymport supports all Python modules that are compatible with the built-in Python interpreter:
134

135
- **Standard Library**: `sys`, `os`, `math`, `json`, `urllib`, etc.
136
- **Scientific Computing**: `numpy`, `scipy`, `pandas` (install via `pympip`)
137
- **Data Visualization**: `matplotlib`, `seaborn` (install via `pympip`)
138
- **Machine Learning**: `scikit-learn`, `tensorflow` (install via `pympip`)
139
- **Custom Modules**: Any Python files in the PYTHONPATH
140

141
## Installation of Python Packages
142

143
Use the included `pympip` tool to install Python packages:
144

145
```bash
146
# Install packages for use with pymport
147
npx pympip install numpy pandas matplotlib
148
npx pympip3 install scikit-learn tensorflow
149

150
# List installed packages
151
npx pympip list
152
```