py-scriptor 0.1.4
Scriptor is a small Python library for defining and running simple rule-based scripts
License: MIT

# Py_scriptor

Scriptor is a small Python library for defining and running simple rule-based scripts. A script is a sequence of conditional rules that, when a condition is met, execute one or more actions.

> Security: Py_scriptor uses eval() and exec(). Do not run untrusted or unreviewed scripts.

## Features
- Compact rule format (condition -> actions).
- Injection of variables into the script execution environment.
- Optional importing of modules via a prefix in the script.
- Minimal IDE environment (scriptorIDE.py) for editing and running scripts.

## Installation
Install it using pip:

```bash
pip install py-scriptor
```

Note: Installation will take approximately 2 seconds at 100 kb/s of internet speed

## Script format
A script is a single string of rules separated by semicolons (`;`). Each rule uses `>>>` to separate the condition from the actions. Multiple actions are separated by commas.

Optional imports: prefix the script with module names separated by `::`, followed by the script body.

Comments: The py_scriptor supports two styles of comments:
Style 1: Starts with `#` and ends before `>>>#;`
Style 2: Starts with `#>>>#` and ends before `;`

Format:
module1::module2::...::condition >>> action1, action2; condition2 >>> action3

- condition: a Python expression evaluated with the provided variables (eval).
- action: a Python statement executed with the provided variables (exec).

Examples:
- `x > 0 >>> x -= 1`
- `math::x > 0 >>> print(math.sqrt(x)), x -= 1`

Note: newlines are deleted inside RuleScript init code
Note: `start` is a variable which is `True` only in cycle 0

## API

Class: RuleScript (in py_scriptor/__init__.py)

- RuleScript(script: str, vars: dict = {})
  - script: the script string. To import modules, use the prefix "module::...::script_body".
  - vars: a dict of variables available to conditions and actions. Imported modules are added to this dict under the module name.

- setVar(var: str, value)
  - Sets a variable in the runtime dictionary.

- getVar(var: str) -> Any
  - Retrieves a variable from the runtime dictionary.

- run(max_steps: int = 1000) -> bool
  - Executes the rules for up to max_steps iterations. Returns True on successful completion, False on import or execution errors.

- getImports() -> str
  - Returns the import line text for the imported modules (e.g., `import math`).

## Usage examples

Basic example:

```python
from py_scriptor import RuleScript

script = "x > 0 >>> print(x), x -= 1; x == 0 >>> print('done')"
vars = {"x": 3}

rs = RuleScript(script, vars)
rs.run(max_steps=10)
```

With module import:

```python
script = "math::x > 0 >>> print(math.sqrt(x)), x -= 1"
vars = {"x": 4}
rs = RuleScript(script, vars)
rs.run(max_steps=10)
```

## IDE
Runing IDE:
```python
from py_scriptor import scriptorIDE
```
Note: Scripts are saved as json files.

## Security
Scriptor executes Python code using eval/exec. Do not run scripts from unknown sources. For safer execution consider:
- Running in an isolated process/container.
- Parsing the AST and restricting allowed operations.
- Limiting available globals.

## Contributing
Contributions are welcome. Suggestions:
- Improve the parser.
- Add a safe execution mode (restricted globals/AST).
- Add unit tests and CI.

Open an issue before larger changes, then submit a pull request with tests.

## Github
Link to github: https://github.com/libmaster169/py-scriptor

## License
The LICENSE file contains the MIT license.

## Issues / Contact
Report bugs or feature requests at: https://github.com/libmaster169/py-scriptor/issues