cpython

0.10.1 • Public • Published

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

Build Status Build status js-standard-style Join the chat at https://gitter.im/eljefedelrodeodeljefe/node-cpython

NPM

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

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

Dependents (0)

Package Sidebar

Install

npm i cpython

Weekly Downloads

11

Version

0.10.1

License

MIT

Last publish

Collaborators

  • eljefederodeodeljefe