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
Object
ncpy.init(options) ⇒ 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 = let options = \/\* Options go in here \*\/ ncpy\/\/ available options herehttps://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 = ncpy ncpy
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 = cpython cpython
Callback
ncpy.ffi(file, functionname) ⇒ 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 = ncpy var Readable = Readable;var SomeStream = "objectMode": true SomeStreamSomeStreamSomeStreamSomeStreamSomeStreamSomeStreamncpyffi // load the python script and intitialize the python interpreter // this expects a stream (in { objectMode: true }) // Tell `ncpy` what function to excute. // add your own transform or any other stream here
ncpy.eval()
Kind: instance method of Ncpy
ncpy.initialize()
initialize python context, reserve memory.
Kind: instance method of Ncpy
Boolean
ncpy.isInitialized() ⇒ 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 |
Boolean
ncpy.isFinalized() ⇒ 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