python-shell

  • Version 5.0.0
  • Published
  • 54.1 kB
  • No dependencies
  • MIT license

Install

npm i python-shell
yarn add python-shell
pnpm add python-shell

Overview

Run Python scripts from Node.js with simple (but efficient) inter-process communication through stdio

Index

Classes

class NewlineTransformer

class NewlineTransformer extends Transform {}
  • Takes in a string stream and emits batches seperated by newlines

class PythonShell

class PythonShell extends EventEmitter {}
  • An interactive Python shell exchanging data through stdio

    Parameter script

    The python script to execute

    Parameter options

    The launch options (also passed to child_process.spawn)

    Parameter stdoutSplitter

    Optional. Splits stdout into chunks, defaulting to splitting into newline-seperated lines

    Parameter stderrSplitter

    Optional. splits stderr into chunks, defaulting to splitting into newline-seperated lines

constructor

constructor(
scriptPath: string,
options?: Options,
stdoutSplitter?: Transform,
stderrSplitter?: Transform
);
  • spawns a python process

    Parameter scriptPath

    path to script. Relative to current directory or options.scriptFolder if specified

    Parameter options

    Parameter stdoutSplitter

    Optional. Splits stdout into chunks, defaulting to splitting into newline-seperated lines

    Parameter stderrSplitter

    Optional. splits stderr into chunks, defaulting to splitting into newline-seperated lines

property childProcess

childProcess: ChildProcess;

    property command

    command: string[];

      property defaultOptions

      static defaultOptions: Options;

        property defaultPythonPath

        static defaultPythonPath: string;

          property exitCode

          exitCode: number;

            property exitSignal

            exitSignal: string;

              property format

              static format: { text: (data: any) => string; json: (data: any) => string };

                property formatter

                formatter: (param: string | Object) => any;

                  property mode

                  mode: string;

                    property parse

                    static parse: { text: (data: any) => string; json: (data: string) => any };

                      property parser

                      parser: (param: string) => any;

                        property scriptPath

                        scriptPath: string;

                          property stderr

                          stderr: Readable;

                            property stderrParser

                            stderrParser: (param: string) => any;

                              property stdin

                              stdin: Writable;

                                property stdout

                                stdout: Readable;

                                  property terminated

                                  terminated: boolean;

                                    method checkSyntax

                                    static checkSyntax: (
                                    code: string
                                    ) => Promise<{ stdout: string; stderr: string }>;
                                    • checks syntax without executing code

                                      Returns

                                      rejects promise w/ string error output if syntax failure

                                    method checkSyntaxFile

                                    static checkSyntaxFile: (
                                    filePath: string
                                    ) => Promise<{ stdout: string; stderr: string }>;
                                    • checks syntax without executing code

                                      Returns

                                      {Promise} rejects w/ stderr if syntax failure

                                    method end

                                    end: (
                                    callback: (
                                    err: PythonShellError,
                                    exitCode: number,
                                    exitSignal: string
                                    ) => any
                                    ) => this;
                                    • Closes the stdin stream. Unless python is listening for stdin in a loop this should cause the process to finish its work and close.

                                      Returns

                                      {PythonShell} The same instance for chaining calls

                                    method getPythonPath

                                    static getPythonPath: () => string;

                                      method getVersion

                                      static getVersion: (pythonPath?: string) => any;

                                        method getVersionSync

                                        static getVersionSync: (pythonPath?: string) => string;

                                          method kill

                                          kill: (signal?: NodeJS.Signals) => this;
                                          • Sends a kill signal to the process

                                            Returns

                                            {PythonShell} The same instance for chaining calls

                                          method run

                                          static run: (scriptPath: string, options?: Options) => Promise<any[]>;
                                          • Runs a Python script and returns collected messages as a promise. If the promise is rejected, the err will probably be of type PythonShellErrorWithLogs

                                            Parameter scriptPath

                                            The path to the script to execute

                                            Parameter options

                                            The execution options

                                          method runString

                                          static runString: (code: string, options?: Options) => Promise<any[]>;
                                          • Runs the inputted string of python code and returns collected messages as a promise. DO NOT ALLOW UNTRUSTED USER INPUT HERE!

                                            Parameter code

                                            The python code to execute

                                            Parameter options

                                            The execution options a promise with the output from the python script

                                          method send

                                          send: (message: string | Object) => this;
                                          • Sends a message to the Python shell through stdin Override this method to format data to be sent to the Python process

                                            Returns

                                            {PythonShell} The same instance for chaining calls

                                          method terminate

                                          terminate: (signal?: NodeJS.Signals) => this;
                                          • Alias for kill.

                                            Deprecated

                                          class PythonShellError

                                          class PythonShellError extends Error {}

                                            property exitCode

                                            exitCode?: number;

                                              property traceback

                                              traceback: any;

                                                class PythonShellErrorWithLogs

                                                class PythonShellErrorWithLogs extends PythonShellError {}

                                                  property logs

                                                  logs: any[];

                                                    Interfaces

                                                    interface Options

                                                    interface Options extends SpawnOptions {}

                                                      property args

                                                      args?: string[];
                                                      • arguments to your program

                                                      property encoding

                                                      encoding?: BufferEncoding;

                                                        property formatter

                                                        formatter?: string | ((param: string) => any);

                                                          property mode

                                                          mode?: 'text' | 'json' | 'binary';
                                                          • if binary is enabled message and stderr events will not be emitted

                                                          property parser

                                                          parser?: string | ((param: string) => any);

                                                            property pythonOptions

                                                            pythonOptions?: string[];
                                                            • see https://docs.python.org/3.7/using/cmdline.html

                                                            property pythonPath

                                                            pythonPath?: string;

                                                              property scriptPath

                                                              scriptPath?: string;
                                                              • overrides scriptPath passed into PythonShell constructor

                                                              property stderrParser

                                                              stderrParser?: string | ((param: string) => any);

                                                                interface PythonShell

                                                                interface PythonShell {}

                                                                  method addListener

                                                                  addListener: {
                                                                  (event: string, listener: (...args: any[]) => void): this;
                                                                  (event: 'message', listener: (parsedChunk: any) => void): this;
                                                                  (event: 'stderr', listener: (parsedChunk: any) => void): this;
                                                                  (event: 'close', listener: () => void): this;
                                                                  (event: 'error', listener: (error: NodeJS.ErrnoException) => void): this;
                                                                  (event: 'pythonError', listener: (error: PythonShellError) => void): this;
                                                                  };

                                                                    method emit

                                                                    emit: {
                                                                    (event: string | symbol, ...args: any[]): boolean;
                                                                    (event: 'message', parsedChunk: any): boolean;
                                                                    (event: 'stderr', parsedChunk: any): boolean;
                                                                    (event: 'close'): boolean;
                                                                    (event: 'error', error: NodeJS.ErrnoException): boolean;
                                                                    (event: 'pythonError', error: PythonShellError): boolean;
                                                                    };

                                                                      method on

                                                                      on: {
                                                                      (event: string, listener: (...args: any[]) => void): this;
                                                                      (event: 'message', listener: (parsedChunk: any) => void): this;
                                                                      (event: 'stderr', listener: (parsedChunk: any) => void): this;
                                                                      (event: 'close', listener: () => void): this;
                                                                      (event: 'error', listener: (error: NodeJS.ErrnoException) => void): this;
                                                                      (event: 'pythonError', listener: (error: PythonShellError) => void): this;
                                                                      };

                                                                        method once

                                                                        once: {
                                                                        (event: string, listener: (...args: any[]) => void): this;
                                                                        (event: 'message', listener: (parsedChunk: any) => void): this;
                                                                        (event: 'stderr', listener: (parsedChunk: any) => void): this;
                                                                        (event: 'close', listener: () => void): this;
                                                                        (event: 'error', listener: (error: NodeJS.ErrnoException) => void): this;
                                                                        (event: 'pythonError', listener: (error: PythonShellError) => void): this;
                                                                        };

                                                                          method prependListener

                                                                          prependListener: {
                                                                          (event: string, listener: (...args: any[]) => void): this;
                                                                          (event: 'message', listener: (parsedChunk: any) => void): this;
                                                                          (event: 'stderr', listener: (parsedChunk: any) => void): this;
                                                                          (event: 'close', listener: () => void): this;
                                                                          (event: 'error', listener: (error: NodeJS.ErrnoException) => void): this;
                                                                          (event: 'pythonError', listener: (error: PythonShellError) => void): this;
                                                                          };

                                                                            method prependOnceListener

                                                                            prependOnceListener: {
                                                                            (event: string, listener: (...args: any[]) => void): this;
                                                                            (event: 'message', listener: (parsedChunk: any) => void): this;
                                                                            (event: 'stderr', listener: (parsedChunk: any) => void): this;
                                                                            (event: 'close', listener: () => void): this;
                                                                            (event: 'error', listener: (error: NodeJS.ErrnoException) => void): this;
                                                                            (event: 'pythonError', listener: (error: PythonShellError) => void): this;
                                                                            };

                                                                              Package Files (1)

                                                                              Dependencies (0)

                                                                              No dependencies.

                                                                              Dev Dependencies (8)

                                                                              Peer Dependencies (0)

                                                                              No peer dependencies.

                                                                              Badge

                                                                              To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

                                                                              You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/python-shell.

                                                                              • Markdown
                                                                                [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/python-shell)
                                                                              • HTML
                                                                                <a href="https://www.jsdocs.io/package/python-shell"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>