tessl/npm-python-shell

Run Python scripts from Node.js with efficient inter-process communication through stdio

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Configuration

Name: tessl/npm-python-shell
Author: tessl

Comprehensive configuration interface for customizing Python execution environment, data handling, and process options. The Options interface extends Node.js SpawnOptions to provide Python-specific configuration.

Capabilities

Options Interface

Main configuration interface for PythonShell execution options.

/**
 * Configuration options for PythonShell
 * Extends Node.js SpawnOptions for child process configuration
 */
interface Options extends SpawnOptions {
  /** Data exchange mode for stdin/stdout communication */
  mode?: 'text' | 'json' | 'binary';
  /** Custom message formatter function or built-in formatter name */
  formatter?: string | ((param: string) => any);
  /** Custom data parser function or built-in parser name */
  parser?: string | ((param: string) => any);
  /** Custom stderr parser function or built-in parser name */
  stderrParser?: string | ((param: string) => any);
  /** Text encoding for streams */
  encoding?: BufferEncoding;
  /** Path to Python executable */
  pythonPath?: string;
  /** Command line options for Python */
  pythonOptions?: string[];
  /** Override for script directory path */
  scriptPath?: string;
  /** Arguments to pass to Python script */
  args?: string[];
}

Data Exchange Modes

Control how data flows between Node.js and Python processes.

Text Mode (default):

const options: Options = {
  mode: 'text'  // Each line becomes a string message
};

// Python output: print("Hello\nWorld")
// Node.js receives: ['Hello', 'World']

JSON Mode:

const options: Options = {
  mode: 'json'  // Each line parsed as JSON
};

// Python output: print(json.dumps({"key": "value"}))
// Node.js receives: [{ key: 'value' }]

Binary Mode:

const options: Options = {
  mode: 'binary'  // Raw data, no parsing, no message events
};
// Use for binary data transfer, direct stream access

Custom Formatters and Parsers

Define custom data processing functions or use built-in ones.

// Built-in formatters
static format = {
  text: (data: any) => string;    // Converts to string
  json: (data: any) => string;    // JSON.stringify()
};

// Built-in parsers  
static parse = {
  text: (data: string) => string;  // Returns as-is
  json: (data: string) => any;     // JSON.parse()
};

Usage Examples:

import { PythonShell } from "python-shell";

// Using built-in formatters/parsers by name
const options: Options = {
  formatter: 'json',    // Use built-in JSON formatter
  parser: 'text',       // Use built-in text parser
  stderrParser: 'text'  // stderr always uses text parsing
};

// Custom formatter function
const options: Options = {
  formatter: (data) => {
    if (typeof data === 'object') {
      return JSON.stringify(data) + '\n';
    }
    return String(data) + '\n';
  }
};

// Custom parser function
const options: Options = {
  parser: (line) => {
    // Parse CSV-like format
    return line.split(',').map(s => s.trim());
  }
};

// Custom stderr parser
const options: Options = {
  stderrParser: (line) => {
    // Parse log levels from stderr
    const match = line.match(/\[(DEBUG|INFO|WARN|ERROR)\] (.+)/);
    return match ? { level: match[1], message: match[2] } : line;
  }
};

Python Environment Configuration

Configure Python executable and execution environment.

Python Path:

const options: Options = {
  pythonPath: '/usr/bin/python3.9',  // Specific Python version
  // or
  pythonPath: 'python',              // Use system default
  // or
  pythonPath: './venv/bin/python'    // Virtual environment
};

Python Options:

const options: Options = {
  pythonOptions: [
    '-u',           // Unbuffered stdout/stderr
    '-O',           // Optimize bytecode
    '-W', 'ignore', // Ignore warnings
    '-c'            // Execute command (when using runString)
  ]
};

Script Path:

const options: Options = {
  scriptPath: './python_scripts',  // Base directory for scripts
  // Script path combines with scriptPath:
  // new PythonShell('script.py', { scriptPath: './scripts' })
  // Executes: './scripts/script.py'
};

Script Arguments:

const options: Options = {
  args: [
    'input.txt',      // Positional arguments
    '--verbose',      // Flags
    '--output=result.json'  // Key-value arguments
  ]
};

// Python script receives: sys.argv[1:] = ['input.txt', '--verbose', '--output=result.json']

Stream Configuration

Configure text encoding and stream handling.

const options: Options = {
  encoding: 'utf8',     // Default encoding
  // or
  encoding: 'ascii',    // ASCII encoding  
  // or
  encoding: 'base64'    // Base64 encoding
};

Node.js SpawnOptions

All Node.js child_process.spawn options are available:

const options: Options = {
  // Working directory for Python process
  cwd: './python_workspace',
  
  // Environment variables
  env: {
    ...process.env,
    PYTHONPATH: './my_modules',
    DEBUG: '1'
  },
  
  // Stdio configuration (advanced)
  stdio: ['pipe', 'pipe', 'pipe'],
  
  // Detached process
  detached: false,
  
  // Shell execution
  shell: false,
  
  // User/group (Unix only)
  uid: 1000,
  gid: 1000,
  
  // Timeout (not recommended, use kill() instead)
  timeout: 30000
};

Default Options

Set global defaults for all PythonShell instances:

static defaultOptions: Options;

Usage Examples:

import { PythonShell } from "python-shell";

// Set global defaults
PythonShell.defaultOptions = {
  mode: 'text',
  pythonPath: '/usr/bin/python3',
  scriptPath: './python_scripts',
  pythonOptions: ['-u'],
  encoding: 'utf8'
};

// All instances inherit these defaults
const shell1 = new PythonShell('script1.py');  // Uses defaults
const shell2 = new PythonShell('script2.py', { 
  mode: 'json'  // Override just the mode
});

// Reset defaults
PythonShell.defaultOptions = {};

Complete Configuration Example

import { PythonShell, Options } from "python-shell";

const comprehensiveOptions: Options = {
  // Data handling
  mode: 'json',
  formatter: 'json',
  parser: 'json',
  stderrParser: 'text',
  encoding: 'utf8',
  
  // Python environment
  pythonPath: './venv/bin/python',
  pythonOptions: ['-u', '-O'],
  scriptPath: './src/python',
  args: ['--config', 'production.json', '--verbose'],
  
  // Node.js process options
  cwd: './workspace',
  env: {
    ...process.env,
    PYTHONPATH: './modules',
    LOG_LEVEL: 'DEBUG'
  },
  
  // Advanced stdio
  stdio: ['pipe', 'pipe', 'pipe']
};

const pyshell = new PythonShell('data_processor.py', comprehensiveOptions);

// Process will execute:
// ./venv/bin/python -u -O ./src/python/data_processor.py --config production.json --verbose
// In working directory: ./workspace
// With PYTHONPATH=./modules and LOG_LEVEL=DEBUG environment variables

Install with Tessl CLI