Noisy Pneumatic Mnemonic

    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

    Install

    npm i cpython

    DownloadsWeekly Downloads

    2

    Version

    0.10.1

    License

    MIT

    Last publish

    Collaborators

    • eljefederodeodeljefe