UNPKG

8.75 kBTypeScriptView Raw
1/// <reference types="node" />
2import { EventEmitter } from 'events';
3import { ChildProcess, SpawnOptions } from 'child_process';
4import { Readable, Transform, TransformCallback, Writable } from 'stream';
5export interface Options extends SpawnOptions {
6 /**
7 * if binary is enabled message and stderr events will not be emitted
8 */
9 mode?: 'text' | 'json' | 'binary';
10 formatter?: string | ((param: string) => any);
11 parser?: string | ((param: string) => any);
12 stderrParser?: string | ((param: string) => any);
13 encoding?: string;
14 pythonPath?: string;
15 /**
16 * see https://docs.python.org/3.7/using/cmdline.html
17 */
18 pythonOptions?: string[];
19 /**
20 * overrides scriptPath passed into PythonShell constructor
21 */
22 scriptPath?: string;
23 /**
24 * arguments to your program
25 */
26 args?: string[];
27}
28export declare class PythonShellError extends Error {
29 traceback: string | Buffer;
30 exitCode?: number;
31}
32/**
33 * Takes in a string stream and emits batches seperated by newlines
34 */
35export declare class NewlineTransformer extends Transform {
36 private _lastLineData;
37 _transform(chunk: any, encoding: string, callback: TransformCallback): void;
38 _flush(done: TransformCallback): void;
39}
40/**
41 * An interactive Python shell exchanging data through stdio
42 * @param {string} script The python script to execute
43 * @param {object} [options] The launch options (also passed to child_process.spawn)
44 * @param [stdoutSplitter] Optional. Splits stdout into chunks, defaulting to splitting into newline-seperated lines
45 * @param [stderrSplitter] Optional. splits stderr into chunks, defaulting to splitting into newline-seperated lines
46 * @constructor
47 */
48export declare class PythonShell extends EventEmitter {
49 scriptPath: string;
50 command: string[];
51 mode: string;
52 formatter: (param: string | Object) => any;
53 parser: (param: string) => any;
54 stderrParser: (param: string) => any;
55 terminated: boolean;
56 childProcess: ChildProcess;
57 stdin: Writable;
58 stdout: Readable;
59 stderr: Readable;
60 exitSignal: string;
61 exitCode: number;
62 private stderrHasEnded;
63 private stdoutHasEnded;
64 private _remaining;
65 private _endCallback;
66 static defaultPythonPath: string;
67 static defaultOptions: Options;
68 /**
69 * spawns a python process
70 * @param scriptPath path to script. Relative to current directory or options.scriptFolder if specified
71 * @param options
72 * @param stdoutSplitter Optional. Splits stdout into chunks, defaulting to splitting into newline-seperated lines
73 * @param stderrSplitter Optional. splits stderr into chunks, defaulting to splitting into newline-seperated lines
74 */
75 constructor(scriptPath: string, options?: Options, stdoutSplitter?: Transform, stderrSplitter?: Transform);
76 static format: {
77 text: (data: any) => string;
78 json: (data: any) => string;
79 };
80 static parse: {
81 text: (data: any) => string;
82 json: (data: string) => any;
83 };
84 /**
85 * checks syntax without executing code
86 * @returns rejects promise w/ string error output if syntax failure
87 */
88 static checkSyntax(code: string): Promise<{
89 stdout: string;
90 stderr: string;
91 }>;
92 static getPythonPath(): string;
93 /**
94 * checks syntax without executing code
95 * @returns {Promise} rejects w/ stderr if syntax failure
96 */
97 static checkSyntaxFile(filePath: string): Promise<{
98 stdout: string;
99 stderr: string;
100 }>;
101 /**
102 * Runs a Python script and returns collected messages
103 * @param {string} scriptPath The path to the script to execute
104 * @param {Options} options The execution options
105 * @param {Function} callback The callback function to invoke with the script results
106 * @return {PythonShell} The PythonShell instance
107 */
108 static run(scriptPath: string, options?: Options, callback?: (err?: PythonShellError, output?: any[]) => any): PythonShell;
109 /**
110 * Runs the inputted string of python code and returns collected messages. DO NOT ALLOW UNTRUSTED USER INPUT HERE!
111 * @param {string} code The python code to execute
112 * @param {Options} options The execution options
113 * @param {Function} callback The callback function to invoke with the script results
114 * @return {PythonShell} The PythonShell instance
115 */
116 static runString(code: string, options?: Options, callback?: (err: PythonShellError, output?: any[]) => any): PythonShell;
117 static getVersion(pythonPath?: string): Promise<{
118 stdout: string;
119 stderr: string;
120 }>;
121 static getVersionSync(pythonPath?: string): string;
122 /**
123 * Parses an error thrown from the Python process through stderr
124 * @param {string|Buffer} data The stderr contents to parse
125 * @return {Error} The parsed error with extended stack trace when traceback is available
126 */
127 private parseError;
128 /**
129 * Sends a message to the Python shell through stdin
130 * Override this method to format data to be sent to the Python process
131 * @returns {PythonShell} The same instance for chaining calls
132 */
133 send(message: string | Object): this;
134 /**
135 * Closes the stdin stream. Unless python is listening for stdin in a loop
136 * this should cause the process to finish its work and close.
137 * @returns {PythonShell} The same instance for chaining calls
138 */
139 end(callback: (err: PythonShellError, exitCode: number, exitSignal: string) => any): this;
140 /**
141 * Sends a kill signal to the process
142 * @returns {PythonShell} The same instance for chaining calls
143 */
144 kill(signal?: NodeJS.Signals): this;
145 /**
146 * Alias for kill.
147 * @deprecated
148 */
149 terminate(signal?: NodeJS.Signals): this;
150}
151export interface PythonShell {
152 addListener(event: string, listener: (...args: any[]) => void): this;
153 emit(event: string | symbol, ...args: any[]): boolean;
154 on(event: string, listener: (...args: any[]) => void): this;
155 once(event: string, listener: (...args: any[]) => void): this;
156 prependListener(event: string, listener: (...args: any[]) => void): this;
157 prependOnceListener(event: string, listener: (...args: any[]) => void): this;
158 addListener(event: "message", listener: (parsedChunk: any) => void): this;
159 emit(event: "message", parsedChunk: any): boolean;
160 on(event: "message", listener: (parsedChunk: any) => void): this;
161 once(event: "message", listener: (parsedChunk: any) => void): this;
162 prependListener(event: "message", listener: (parsedChunk: any) => void): this;
163 prependOnceListener(event: "message", listener: (parsedChunk: any) => void): this;
164 addListener(event: "stderr", listener: (parsedChunk: any) => void): this;
165 emit(event: "stderr", parsedChunk: any): boolean;
166 on(event: "stderr", listener: (parsedChunk: any) => void): this;
167 once(event: "stderr", listener: (parsedChunk: any) => void): this;
168 prependListener(event: "stderr", listener: (parsedChunk: any) => void): this;
169 prependOnceListener(event: "stderr", listener: (parsedChunk: any) => void): this;
170 addListener(event: "close", listener: () => void): this;
171 emit(event: "close"): boolean;
172 on(event: "close", listener: () => void): this;
173 once(event: "close", listener: () => void): this;
174 prependListener(event: "close", listener: () => void): this;
175 prependOnceListener(event: "close", listener: () => void): this;
176 addListener(event: "error", listener: (error: NodeJS.ErrnoException) => void): this;
177 emit(event: "error", error: NodeJS.ErrnoException): boolean;
178 on(event: "error", listener: (error: NodeJS.ErrnoException) => void): this;
179 once(event: "error", listener: (error: NodeJS.ErrnoException) => void): this;
180 prependListener(event: "error", listener: (error: NodeJS.ErrnoException) => void): this;
181 prependOnceListener(event: "error", listener: (error: NodeJS.ErrnoException) => void): this;
182 addListener(event: "pythonError", listener: (error: PythonShellError) => void): this;
183 emit(event: "pythonError", error: PythonShellError): boolean;
184 on(event: "pythonError", listener: (error: PythonShellError) => void): this;
185 once(event: "pythonError", listener: (error: PythonShellError) => void): this;
186 prependListener(event: "pythonError", listener: (error: PythonShellError) => void): this;
187 prependOnceListener(event: "pythonError", listener: (error: PythonShellError) => void): this;
188}