0
# Python Shell
1

2
Python Shell is a Node.js TypeScript library that provides efficient inter-process communication between Node.js and Python through child processes. It offers promise-based APIs, multiple data exchange modes, error handling with Python tracebacks, and both interactive and one-time execution patterns.
3

4
## Package Information
5

6
- **Package Name**: python-shell
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install python-shell`
10

11
## Core Imports
12

13
```typescript
14
import { PythonShell } from "python-shell";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { PythonShell } = require("python-shell");
21
```
22

23
Additional imports for interfaces and utilities:
24

25
```typescript
26
import { PythonShell, Options, PythonShellError, NewlineTransformer } from "python-shell";
27
import { Transform } from "stream"; // For custom splitters
28
```
29

30
## Basic Usage
31

32
```typescript
33
import { PythonShell } from "python-shell";
34

35
// Run a Python script and get results
36
const results = await PythonShell.run('my_script.py', {
37
  mode: 'text',
38
  pythonPath: 'python3',
39
  scriptPath: './scripts',
40
  args: ['arg1', 'arg2']
41
});
42

43
// Execute Python code directly
44
const output = await PythonShell.runString('print("Hello from Python")');
45
console.log(output); // ['Hello from Python']
46

47
// Interactive communication
48
const pyshell = new PythonShell('interactive_script.py');
49
pyshell.send('input data');
50
pyshell.on('message', (message) => {
51
  console.log('Received:', message);
52
});
53
pyshell.end((err, code, signal) => {
54
  if (err) throw err;
55
  console.log('Process finished with code:', code);
56
});
57
```
58

59
## Architecture
60

61
Python Shell is built around several key components:
62

63
- **PythonShell Class**: Main interactive shell for persistent Python processes with event-driven communication
64
- **Static Execution Methods**: Utility functions (`run`, `runString`) for one-time Python script execution
65
- **Stream Processing**: Built-in parsers/formatters for text, JSON, and binary data modes
66
- **Error Handling**: Extended error reporting with Python traceback integration
67
- **Configuration System**: Comprehensive options for Python path, arguments, and execution environment
68

69
## Capabilities
70

71
### Script Execution
72

73
Static methods for executing Python scripts and code strings with promise-based results collection.
74

75
```typescript { .api }
76
static run(scriptPath: string, options?: Options): Promise<any[]>;
77
static runString(code: string, options?: Options): Promise<any[]>;
78
```
79

80
[Script Execution](./script-execution.md)
81

82
### Interactive Shell
83

84
Interactive Python shell class for persistent processes with real-time data exchange through events and streams.
85

86
```typescript { .api }
87
class PythonShell extends EventEmitter {
88
  constructor(scriptPath: string, options?: Options, stdoutSplitter: Transform = null, stderrSplitter: Transform = null);
89
  send(message: string | Object): PythonShell;
90
  end(callback: (err: PythonShellError, exitCode: number, exitSignal: string) => any): PythonShell;
91
  kill(signal?: NodeJS.Signals): PythonShell;
92
}
93
```
94

95
[Interactive Shell](./interactive-shell.md)
96

97
### Configuration Options
98

99
Comprehensive configuration interface for customizing Python execution environment, data handling, and process options.
100

101
```typescript { .api }
102
interface Options extends SpawnOptions {
103
  mode?: 'text' | 'json' | 'binary';
104
  formatter?: string | ((param: string) => any);
105
  parser?: string | ((param: string) => any);
106
  stderrParser?: string | ((param: string) => any);
107
  encoding?: BufferEncoding;
108
  pythonPath?: string;
109
  pythonOptions?: string[];
110
  scriptPath?: string;
111
  args?: string[];
112
}
113
```
114

115
[Configuration](./configuration.md)
116

117
### Utilities
118

119
Utility functions for Python environment management, syntax checking, and stream processing.
120

121
```typescript { .api }
122
static checkSyntax(code: string): Promise<void>;
123
static checkSyntaxFile(filePath: string): Promise<void>;
124
static getVersion(pythonPath?: string): Promise<{stdout: string, stderr: string}>;
125
static getVersionSync(pythonPath?: string): string;
126
static getPythonPath(): string;
127
```
128

129
[Utilities](./utilities.md)
130

131
## Static Properties
132

133
```typescript { .api }
134
static defaultPythonPath: string;    // Default Python executable path
135
static defaultOptions: Options;      // Global default options for all instances
136
static format: {                     // Built-in formatters
137
  text: (data: any) => string;
138
  json: (data: any) => string;
139
};
140
static parse: {                      // Built-in parsers
141
  text: (data: string) => string;
142
  json: (data: string) => any;
143
};
144
```
145

146
## Core Types
147

148
```typescript { .api }
149
class PythonShellError extends Error {
150
  traceback: string | Buffer;
151
  exitCode?: number;
152
}
153

154
class PythonShellErrorWithLogs extends PythonShellError {
155
  logs: any[];
156
}
157

158
class NewlineTransformer extends Transform {
159
  _transform(chunk: any, encoding: string, callback: TransformCallback): void;
160
  _flush(done: TransformCallback): void;
161
}
162
```