node-cpython

Native bindings to run python in its native interpreter.

This Library is in rc status. Do only use if you know what you do

TL;DR

Sometimes you want to use Python scripts or even whole libraries, but you don't want to rely on child_process.exec() or child_process.spawn(). This module initializes the standard Python interpreter and passes Py code to it.

Implementation Status

Method	implemented
Core
.ffi(py_file, fn_name, args, [options], [cb])	yes
.repl()	yes
.run()	-
.runSync()	-
.runString(string	yes
.simpleString(string, [cb])	yes
.eval()	-
-	-
Infrastructure
init()	yes
initialize()	yes
finalize()	yes
isInitialized()	yes
isFinalized()	yes
setProgramName()	-
setArgv()	-
-	-
Stream API
ffi.require(py_file, [options])	yes
ffi.init(stream)	yes
ffi.run(fn_name)	yes
ffi.pipe(stream)	yes
ffi.on(event)	yes

Introduction

The following shall give background information and explain why you want to use this.

Motivation

In order to compile C code with Emscripten you'd have to run the Python script, which utilizes LLVM. However working with child_process.exec() or chold_process.spawn() seems odd, since it neither safe nor does it handle errors nor is it platform independent. So in order to run scripts programmatically it seemed a good idea to use the the perfect legit Python.h C-header in the standard implementation of Python.

Overview

Technical Overview

Rquirements:

• Node 4.0.0+

Platform

This module is currently tested on:

Platform	0.12	3.0	4.0	5.0
Mac OS X	-	-	yes	yes
Linux	-	-	yes	yes
Windows	-	-	-	-

Roadmap

Please see list of the implemented methods for now.

API

Ncpy

Kind: global class

• Ncpy
  • new Ncpy()
  • .init(options) ⇒ Object
  • .repl()
  • .run(glob, Argv, [cb])
  • .runSync(glob, Argv, [cb])
  • .runString(string)
  • .simpleString(str, [flags], [cb])
  • .ffi(file, functionname) ⇒ Callback
  • .eval()
  • .initialize()
  • .isInitialized() ⇒ Boolean
  • .finalize(callback)
  • .isFinalized() ⇒ Boolean
  • .setProgramName(Program)
  • .setArgv(string)

new Ncpy()

Implements the Ncpy Python interpreter

ncpy.init(options) ⇒ Object

intitialze this module from init function rather than over constructor

Kind: instance method of Ncpy
Returns: Object - returns itself is chainable

Param	Type	Description
options	Object	object where keys represent toggles of individual features or point to files

Example

const ncpy = require('node-cpython')

let options = {
	\/\* Options go in here \*\/
}

ncpy.init(options)
\/\/ available options [here](https://github.com/eljefedelrodeodeljefe/node-cpython#options)

ncpy.repl()

Starts a Python contexts, runs a newline delimited string of python from Node's stdin, listens for SIGINT and finalizes the Python context.

Kind: instance method of Ncpy

ncpy.run(glob, Argv, [cb])

Executes any number of Python source code files. This is JS userland API and automates and abstracts many choices of the below C-API. If you want to have more control, please use the below methods.

Kind: instance method of Ncpy

Param	Type	Description
glob	String | Array.<String>	a glob of valid .py files
Argv	Array	global arguments array
[cb]	Callback	Optional callback

Example

'use strict'
const ncpy = require('node-cpython')

ncpy.on('error', function(err) {console.log(err)})

ncpy.run('[example/**\/*.py',[2, 10, 'someOtherArg'], function(err) {
	console.log(err)
})

ncpy.runSync(glob, Argv, [cb])

Kind: instance method of Ncpy

Param	Type	Description
glob	String | Array.<String>	a glob of valid .py files
Argv	Array	global arguments array
[cb]	Callback	Optional callback

ncpy.runString(string)

Exuute a line of Python script

Kind: instance method of Ncpy

Param	Type	Description
string	String	a valid string of Python script

ncpy.simpleString(str, [flags], [cb])

Executes the Python source code from command. See also Python docs for Reference

Kind: instance method of Ncpy

Param	Type	Default	Description
str	string		String of python denoted code
[flags]	string | Array.<string>	null	Compiler flag or array of flags for CPython
[cb]	callback		Optional callback

Example

'use strict'
const ncpy = require('node-cpython')

cpython.on('error', function(err) {console.log(err)})

cpython.simpleString('from time import time,ctime\nprint 'Today is',ctime(time())\n')

ncpy.ffi(file, functionname) ⇒ Callback

The ffi method serves as entry point for generally executing Python functions from .py-files. Important to note is, that is branching in two modes, depending how many arguments get passed. If there are arguments it makes a singular call to the script, you open and close a whole Python memory contexts for it.

Second, when called in a chain with the stream API (see below). The context get's created and only closed on stream end.

Use it accourdingly:

Kind: instance method of Ncpy
Returns: Callback - Tailcall with err and res

Param	Type	Description
file	String	.py file with function definition
functionname	String	name of function definition

Example

const ncpy = require('node-cpython')

ncpy.ffi('multiplication.py', 'multiply', [ 20, 5], function (err, res) {
  console.log('ncpy -> easy call to multiply, here');
  console.log('ncpy -> ' + res + '\n');
})
	var Readable = require('stream').Readable;
var SomeStream = new Readable({ "objectMode": true })

SomeStream.push([1,2])
SomeStream.push([20,3])
SomeStream.push([3,40])
SomeStream.push([4,50])
SomeStream.push([55,66])
SomeStream.push(null)
ncpy.ffi
  // load the python script and intitialize the python interpreter
  .require('multiplication.py', { path: './examples' })
  // this expects a stream (in { objectMode: true })
  .init(SomeStream)
  // Tell `ncpy` what function to excute.
  .run('multiply')
  // add your own transform or any other stream here
  .pipe()
  .on('end', function() {
    console.log('ncpy -> Ending python context here.');
  })

ncpy.eval()

Kind: instance method of Ncpy

ncpy.initialize()

initialize python context, reserve memory.

Kind: instance method of Ncpy

ncpy.isInitialized() ⇒ Boolean

is-check for the interpreter not running

Kind: instance method of Ncpy
Returns: Boolean - returns true if Py_isInitialized is ecplictely not 0

ncpy.finalize(callback)

Finalize python context, clear memory.

Kind: instance method of Ncpy

Param	Type	Description
callback	callback	for completion of py context

ncpy.isFinalized() ⇒ Boolean

is-check for the interpreter not running

Kind: instance method of Ncpy
Returns: Boolean - return true if Py_isInitialized explictely is 0

ncpy.setProgramName(Program)

set low level python program name (optional)

Kind: instance method of Ncpy

Param	Type	Description
Program	string	name.

ncpy.setArgv(string)

set low level python argv

Kind: instance method of Ncpy

Param	Type	Description
string	string | Array.<string>	or an array of strings as argv argc is auto computed by the arrays length

License

MIT