py-scriptor 0.1.3

Scriptor is a small Python library for defining and running simple rule-based scripts

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:

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

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:

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:

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:

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