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