postscriptum 0.1.1

Multi-interpreted-language scripting engine for Rust with Rhai and Python backends
Documentation
use std::ffi::{CStr, CString, NulError};

use crate::{EngineType, Error, Result};

use super::super::FunctionBundle;
use super::{PyCodeHandle, PythonEngine};
use pyo3::exceptions::PyValueError;
use pyo3::prelude::*;
use pyo3::types::{PyCode, PyCodeInput, PyCodeMethods, PyDict, PyDictMethods, PyModule};
use serde_json::Value;

pub(super) fn create_context() -> Py<PyDict> {
    Python::attach(|py| PyDict::new(py).unbind())
}

pub(super) fn create_with_bundle(bundle: &FunctionBundle) -> PyResult<PythonEngine> {
    Python::attach(|py| {
        let globals = create_context();

        let mut engine = PythonEngine { globals };

        // Register all functions from the bundle if it's a Python bundle
        if let FunctionBundle::Python(python_bundle) = bundle {
            python_bundle.register(py, &mut engine)?;
        }

        Ok(engine)
    })
}

pub(super) fn register_bundle(engine: &mut PythonEngine, bundle: &FunctionBundle) -> PyResult<()> {
    Python::attach(|py| {
        // Register all functions from the bundle if it's a Python bundle
        if let FunctionBundle::Python(python_bundle) = bundle {
            python_bundle.register(py, engine)?;
        }
        Ok(())
    })
}

/// The last line counts as an expression unless it opens or continues
/// a statement block. Pure function of the source — shared by string
/// eval, handle eval and compile so all three agree on the shape of
/// any snippet.
fn last_line_is_expr(last_line: &str) -> bool {
    !last_line.is_empty()
        && !last_line.ends_with(':')
        && !last_line.starts_with("def ")
        && !last_line.starts_with("class ")
        && !last_line.starts_with("if ")
        && !last_line.starts_with("elif ")
        && !last_line.starts_with("else:")
        && !last_line.starts_with("for ")
        && !last_line.starts_with("while ")
        && !last_line.starts_with("try:")
        && !last_line.starts_with("except ")
        && !last_line.starts_with("finally:")
        && !last_line.starts_with("with ")
        && !last_line.starts_with("import ")
        && !last_line.starts_with("from ")
        && !last_line.starts_with("return ")
        && !last_line.starts_with("pass")
        && !last_line.starts_with("break")
        && !last_line.starts_with("continue")
        && !last_line.starts_with("raise ")
        && !last_line.starts_with("assert ")
        && !last_line.starts_with("del ")
        && !last_line.starts_with("global ")
        && !last_line.starts_with("nonlocal ")
}

/// Split into head lines + trimmed last line.
fn split_lines(code: &str) -> (String, String) {
    let lines: Vec<&str> = code.lines().collect();
    let last_line = lines.last().unwrap_or(&"").trim().to_string();
    let head = if lines.len() > 1 {
        lines[..lines.len() - 1].join("\n")
    } else {
        String::new()
    };
    (head, last_line)
}

/// The exec source for the multi-line-with-expression-tail branch:
/// run the head, capture the tail into `__result__`.
fn rewrite_with_result(code: &str) -> String {
    let (head, last_line) = split_lines(code);
    if head.trim().is_empty() {
        format!("__result__ = {last_line}")
    } else {
        format!("{head}\n__result__ = {last_line}")
    }
}

fn nul_err(e: NulError) -> PyErr {
    PyErr::new::<PyValueError, _>(format!("code contains NUL byte: {e}"))
}

/// Run an exec step: a precompiled object when the handle has one,
/// otherwise parse the C string. Semantically identical — the handle
/// only skips re-parsing.
fn run_exec(
    py: Python<'_>,
    globals: &Bound<'_, PyDict>,
    src: &CStr,
    pre: Option<&Py<PyCode>>,
) -> PyResult<()> {
    match pre {
        Some(code) => code.bind(py).run(Some(globals), Some(globals)).map(|_| ()),
        None => py.run(src, Some(globals), Some(globals)),
    }
}

/// Fetch the REPL result slot. Missing/unreadable (never an error
/// here — mirrors today's `"Executed successfully"` fallback).
fn fetch_result(globals: &Bound<'_, PyDict>) -> Option<Py<PyAny>> {
    globals
        .get_item("__result__")
        .ok()
        .flatten()
        .map(|bound| bound.unbind())
}

/// `py.eval`, falling back to running as statements. On total failure
/// the FIRST (`eval`) error is reported — today's exact policy.
fn eval_then_run(
    py: Python<'_>,
    globals: &Bound<'_, PyDict>,
    code: &str,
    pre: Option<&Py<PyCode>>,
) -> PyResult<Option<Py<PyAny>>> {
    let src = CString::new(code).map_err(nul_err)?;
    match py.eval(&src, Some(globals), Some(globals)) {
        Ok(result) => Ok(Some(result.unbind())),
        Err(eval_err) => match run_exec(py, globals, &src, pre) {
            Ok(()) => Ok(None),
            Err(_) => Err(eval_err),
        },
    }
}

/// Evaluate to an object (`None` = bare-statement run), replicating
/// today's exact branching. `pre` swaps the RAW-source exec steps for
/// a precompiled object — never the rewritten first attempt (when the
/// rewrite is uncompilable but `py.eval` succeeds, e.g. `"[1,\n2]"`,
/// substituting raw there would return `Null` where string eval
/// returns a value). Handle eval mirrors string eval by construction:
/// same branches, same error selection.
fn eval_inner(
    py: Python<'_>,
    globals: &Bound<'_, PyDict>,
    code: &str,
    pre: Option<&Py<PyCode>>,
) -> PyResult<Option<Py<PyAny>>> {
    let (_, last_line) = split_lines(code);
    let multi_expr_tail = code.lines().count() > 1 && last_line_is_expr(&last_line);
    if multi_expr_tail {
        let rewritten = rewrite_with_result(code);
        let exec_src = CString::new(rewritten).map_err(nul_err)?;
        // Always re-parse here: `pre` (if any) is the RAW source,
        // which is not what this step runs.
        match py.run(&exec_src, Some(globals), Some(globals)) {
            Ok(()) => Ok(fetch_result(globals)),
            Err(_) => eval_then_run(py, globals, code, pre),
        }
    } else {
        eval_then_run(py, globals, code, pre)
    }
}

pub(crate) fn eval(engine: &mut PythonEngine, code: &str) -> Result<String> {
    Python::attach(|py| -> Result<String> {
        let code = code.trim();
        if code.is_empty() {
            return Ok(String::new());
        }

        // Use the single persistent globals dict for both globals and locals so
        // execution behaves like module-level scope (REPL semantics): variables
        // defined in one eval are visible to subsequently defined functions, and
        // globals() is locals() inside the script.
        let globals = engine.globals.bind(py);

        match eval_inner(py, globals, code, None) {
            Ok(Some(result)) => Ok(result.bind(py).to_string()),
            Ok(None) => Ok("Executed successfully".to_string()),
            Err(e) => Err(Error::Python(e.to_string())),
        }
    })
}

/// Convert a result object to JSON via the stdlib `json` module.
/// Anything `dumps` rejects (sets, datetimes, opaque handles, …)
/// becomes [`Error::UnconvertibleValue`] — never a panic.
fn object_to_json(py: Python<'_>, obj: &Py<PyAny>) -> Result<Value> {
    let unconvertible = || Error::UnconvertibleValue {
        backend: EngineType::Python,
    };
    let json = PyModule::import(py, "json").map_err(|e| Error::Python(e.to_string()))?;
    let text: String = json
        .getattr("dumps")
        .map_err(|e| Error::Python(e.to_string()))?
        .call1((obj,))
        .map_err(|_| unconvertible())?
        .extract()
        .map_err(|_| unconvertible())?;
    serde_json::from_str(&text).map_err(|_| unconvertible())
}

pub(super) fn eval_json(engine: &mut PythonEngine, code: &str) -> Result<Value> {
    Python::attach(|py| -> Result<Value> {
        let code = code.trim();
        if code.is_empty() {
            return Ok(Value::Null);
        }
        let globals = engine.globals.bind(py);
        match eval_inner(py, globals, code, None) {
            Ok(Some(obj)) => object_to_json(py, &obj),
            Ok(None) => Ok(Value::Null),
            Err(e) => Err(Error::Python(e.to_string())),
        }
    })
}

pub(super) fn set_var(engine: &PythonEngine, name: &str, value: &Value) -> Result<()> {
    Python::attach(|py| -> Result<()> {
        // `serde_json::Value` serializes infallibly; the error arm is
        // unreachable but keeps the failure typed.
        let text = serde_json::to_string(value).map_err(|_| Error::UnconvertibleValue {
            backend: EngineType::Python,
        })?;
        let globals = engine.globals.bind(py);
        let json = PyModule::import(py, "json").map_err(|e| Error::Python(e.to_string()))?;
        let obj: Bound<'_, PyAny> = json
            .getattr("loads")
            .map_err(|e| Error::Python(e.to_string()))?
            .call1((text,))
            .map_err(|_| Error::UnconvertibleValue {
                backend: EngineType::Python,
            })?;
        // `name` passed the shared identifier precondition; dict keys
        // never touch the parser, so no injection is possible here.
        globals
            .set_item(name, obj)
            .map_err(|e| Error::Python(e.to_string()))?;
        Ok(())
    })
}

/// Compile helper: `compile()` builtin in `exec` mode. Syntax errors
/// surface WITHOUT executing anything (validate-without-run).
fn compile_exec(py: Python<'_>, src: &str) -> PyResult<Py<PyCode>> {
    let code = CString::new(src).map_err(nul_err)?;
    PyCode::compile(py, &code, c"<postscriptum>", PyCodeInput::File).map(|bound| bound.unbind())
}

pub(super) fn compile_py(src: &str) -> Result<PyCodeHandle> {
    // Source cap enforced by the shared wrapper in `mod.rs`.
    Python::attach(|py| -> Result<PyCodeHandle> {
        let src = src.trim().to_string();
        let (_, last_line) = split_lines(&src);
        let single_expr = src.lines().count() == 1 && last_line_is_expr(&last_line);

        if single_expr {
            // Same object `py.eval` would produce (pyo3 compiles
            // `eval`-mode internally) — try it first. NUL bytes are
            // pathological; reported as a plain Python error.
            let eval_src = CString::new(src.as_str())
                .map_err(|e| Error::Python(format!("code contains NUL byte: {e}")))?;
            if let Ok(code) = PyCode::compile(py, &eval_src, c"<postscriptum>", PyCodeInput::Eval) {
                return Ok(PyCodeHandle {
                    code: code.unbind(),
                    eval_mode: true,
                    has_result: true,
                    src,
                });
            }
            // Falls through to exec handling below (mirrors string
            // eval, where a failed `py.eval` runs as statements).
        }

        let multi_expr_tail = src.lines().count() > 1 && last_line_is_expr(&last_line);
        if multi_expr_tail {
            // Prefer the rewritten form (captures `__result__`);
            // the raw form is the fallback — and the fallback's
            // error is what the user sees (it's THEIR code).
            let rewritten = rewrite_with_result(&src);
            if let Ok(code) = compile_exec(py, &rewritten) {
                return Ok(PyCodeHandle {
                    code,
                    eval_mode: false,
                    has_result: true,
                    src,
                });
            }
        }
        compile_exec(py, &src)
            .map(|code| PyCodeHandle {
                code,
                eval_mode: false,
                has_result: false,
                src,
            })
            .map_err(|e| Error::Python(e.to_string()))
    })
}

pub(super) fn eval_compiled(engine: &mut PythonEngine, handle: &PyCodeHandle) -> Result<Value> {
    Python::attach(|py| -> Result<Value> {
        let globals = engine.globals.bind(py);
        // Every path below mirrors `eval_json` exactly (same
        // branches, same error selection) — the handle only skips
        // re-parsing the first exec attempt.
        if handle.eval_mode {
            if let Ok(obj) = handle.code.bind(py).run(Some(globals), Some(globals)) {
                return object_to_json(py, &obj.unbind());
            }
            // Fall through to the src fallback on runtime failure.
        } else if handle.has_result {
            if let Ok(()) = handle
                .code
                .bind(py)
                .run(Some(globals), Some(globals))
                .map(|_| ())
            {
                return Ok(match fetch_result(globals) {
                    Some(obj) => object_to_json(py, &obj)?,
                    None => Value::Null,
                });
            }
            // Fall through to the src fallback on runtime failure.
        }
        // Fallback (or `has_result == false`): the string-eval chain
        // verbatim. `pre` is used for the run step ONLY when it is
        // the raw-source exec object — an eval-mode object would
        // diverge (see devlog 004).
        let pre = if !handle.eval_mode && !handle.has_result {
            Some(&handle.code)
        } else {
            None
        };
        match eval_inner(py, globals, &handle.src, pre) {
            Ok(Some(obj)) => object_to_json(py, &obj),
            Ok(None) => Ok(Value::Null),
            Err(e) => Err(Error::Python(e.to_string())),
        }
    })
}

/// Fork into an independent engine (G6): a fresh globals dict holding
/// a SHALLOW copy (`dict.copy()` semantics) — mutating the fork never
/// rebinds the original and vice versa, but MUTABLE values are
/// aliased (pushing to a bound list in the fork affects the parent;
/// documented, no `deepcopy` per fork for cost reasons). Registered
/// bundle functions copy as references. Never an `Arc` clone onto
/// shared state.
pub(super) fn fork(engine: &PythonEngine) -> Result<PythonEngine> {
    Python::attach(|py| -> Result<PythonEngine> {
        let copied = engine
            .globals
            .bind(py)
            .copy()
            .map_err(|e| Error::Python(e.to_string()))?;
        Ok(PythonEngine {
            globals: copied.unbind(),
        })
    })
}

/// Empty the shared globals (G6): every binding is gone, the next
/// eval referencing one fails. Total (unlike the WASM tracked clear
/// — documented on the public method).
pub(super) fn clear(engine: &PythonEngine) -> Result<()> {
    Python::attach(|py| -> Result<()> {
        engine.globals.bind(py).clear();
        Ok(())
    })
}