arepl-backend/README.md

JS interface to python evaluator for AREPL

# AREPL-backend [![npm version](https://badge.fury.io/js/arepl-backend.svg)](https://badge.fury.io/js/arepl-backend) ![example workflow](https://github.com/almenon/AREPL-backend/actions/workflows/tests.yml/badge.svg)

JS interface to python evaluator for AREPL.

Evaluates python code and sends back the user variables and/or any errors.

Although it is meant for AREPL, it is not dependent upon AREPL and can be used by any project.

**Important Note**: this should ONLY be used to execute trusted code.  It does not have any security features whatsoever.

## Installation

> npm install [arepl-backend](https://www.npmjs.com/package/arepl-backend)

Must have python 3.8 or greater

## Usage

see <https://github.com/Almenon/AREPL-vscode> for example useage.

## For developers:

Semantic release cheatsheet:

    | Commit message       | Release type |
    |----------------------|--------------|
    | fix: msg             | patch        |
    | feat: msg            | feature      |
    | perf: msg            |              |
    | BREAKING CHANGE: msg | breaking     |

## API

<!-- Generated by documentation.js. Update this documentation by updating the source code. -->

#### Table of Contents

*   [PythonState](#pythonstate)
*   [constructor](#constructor)
    *   [Parameters](#parameters)
*   [execCode](#execcode)
    *   [Parameters](#parameters-1)
*   [sendStdin](#sendstdin)
    *   [Parameters](#parameters-2)
*   [restart](#restart)
    *   [Parameters](#parameters-3)
*   [stop](#stop)
    *   [Parameters](#parameters-4)
*   [start](#start)
    *   [Parameters](#parameters-5)
*   [onResult](#onresult)
    *   [Parameters](#parameters-6)
*   [onPrint](#onprint)
    *   [Parameters](#parameters-7)
*   [onStderr](#onstderr)
    *   [Parameters](#parameters-8)
*   [handleResult](#handleresult)
    *   [Parameters](#parameters-9)
*   [checkSyntax](#checksyntax)
    *   [Parameters](#parameters-10)
*   [formatPythonException](#formatpythonexception)
    *   [Parameters](#parameters-11)
    *   [Examples](#examples)

### PythonState

Starting = Starting or restarting.
Ending = Process is exiting.
Executing = Executing inputted code.
DirtyFree = evaluator may have been polluted by side-effects from previous code, but is free for more code.
FreshFree = evaluator is ready for the first run of code

### constructor

starts python\_evaluator.py

#### Parameters

*   `options`  Process / Python options. If not specified sensible defaults are inferred. (optional, default `{}`)

### execCode

does not do anything if program is currently executing code

#### Parameters

*   `code` &#x20;

### sendStdin

#### Parameters

*   `message` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**&#x20;

### restart

kills python process and restarts.  Force-kills if necessary after 50ms.
After process restarts the callback passed in is invoked

#### Parameters

*   `callback`   (optional, default `()=>{}`)

### stop

Kills python process.  Force-kills if necessary after 50ms.
You can check python\_evaluator.running to see if process is dead yet

#### Parameters

*   `kill_immediately`   (optional, default `false`)

### start

starts python\_evaluator.py. Will NOT WORK with python 2

#### Parameters

*   `finishedStartingCallback` &#x20;

### onResult

Overwrite this with your own handler.
is called when program fails or completes

#### Parameters

*   `foo` &#x20;

### onPrint

Overwrite this with your own handler.
Is called when program prints

#### Parameters

*   `foo` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**&#x20;

### onStderr

Overwrite this with your own handler.
Is called when program logs stderr

#### Parameters

*   `foo` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**&#x20;

### handleResult

handles pyshell results and calls onResult / onPrint

#### Parameters

*   `results` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**&#x20;

### checkSyntax

checks syntax without executing code

#### Parameters

*   `code` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**&#x20;

Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)** rejects w/ stderr if syntax failure

### formatPythonException

gets rid of unnecessary File "<string>" message in exception

#### Parameters

*   `err` &#x20;

#### Examples

```javascript
err:
Traceback (most recent call last):\n  File "<string>", line 1, in <module>\nNameError: name \'x\' is not defined\n
```