openscad-cpp-evaluator 0.2.0__tar.gz → 0.3.0__tar.gz

{openscad_cpp_evaluator-0.2.0 → openscad_cpp_evaluator-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openscad_cpp_evaluator
-Version: 0.2.0
+Version: 0.3.0
 Summary: C++ OpenSCAD evaluator with Python bindings
 Author: NeuSCAD Contributors
 License-Expression: MIT

{openscad_cpp_evaluator-0.2.0 → openscad_cpp_evaluator-0.3.0}/bindings/module.cpp

@@ -292,13 +292,34 @@ nb::list callStackToPy(const std::vector<oscadeval::CallStackFrame>& cs) {
     return out;
 }
 
+// Called from within a debug_hook/error_break callback (never after it
+// returns) to best-effort generate a live render of whatever's been
+// resolved so far -- see Evaluator::generatePartialTree()'s own doc
+// comment for why this is safe to call mid-resolve.
+using GeneratePartialFn = std::function<std::vector<oscadeval::ColoredBody>()>;
+
+// Wraps a GeneratePartialFn as a Python callable returning a plain list of
+// body-dicts (bodiesToList's own shape) -- the facade's _generate_partial_render
+// converts these to ColoredBody and catches whatever exception a GenerateFn
+// raises, the same try/except shape it already had calling generate_tree()
+// directly. No error handling needed here: a C++ exception crossing into
+// Python via this cpp_function is nanobind's normal std::exception ->
+// RuntimeError mapping, which that Python try/except already catches.
+nb::object generatePartialTrampoline(const GeneratePartialFn& generatePartial) {
+    return nb::cpp_function([&generatePartial]() -> nb::list {
+        std::vector<oscadeval::ColoredBody> bodies = generatePartial();
+        return bodiesToList(bodies);
+    });
+}
+
 // Trampoline: C++ debug hook -> the Python DebugSession hook. Runs with the
-// GIL held (reacquired by the caller). `getFrame`/`callStack` are valid only
-// for this synchronous call, so the get_frames closure is only ever invoked
-// from within the Python hook, before it returns.
+// GIL held (reacquired by the caller). `getFrame`/`callStack`/`generatePartial`
+// are valid only for this synchronous call, so the get_frames/generate_partial
+// closures are only ever invoked from within the Python hook, before it returns.
 oscadeval::DebugAction callPyDebugHook(nb::handle hook, int line, int depth, bool forced, const std::string& origin,
                                         const std::vector<oscadeval::CallStackFrame>& callStack,
-                                        const oscadeval::DebugFramesFn& getFrame) {
+                                        const oscadeval::DebugFramesFn& getFrame,
+                                        const GeneratePartialFn& generatePartial) {
     auto getFramesPy = nb::cpp_function([&callStack, &getFrame]() -> nb::object {
         std::vector<oscadeval::DebugFrame> frames = getFrame();
         nb::list allFrameLocals;
@@ -313,9 +334,11 @@ oscadeval::DebugAction callPyDebugHook(nb::handle hook, int line, int depth, boo
         }
         return nb::make_tuple(nb::make_tuple(lastLocals, allFrameLocals), callStackToPy(callStack));
     });
+    nb::object generatePartialPy = generatePartialTrampoline(generatePartial);
 
     nb::object ret = hook(line, depth, nb::arg("forced") = forced, nb::arg("expr_level") = false,
-                          nb::arg("expr_depth") = 0, nb::arg("origin") = origin, nb::arg("get_frames") = getFramesPy);
+                          nb::arg("expr_depth") = 0, nb::arg("origin") = origin, nb::arg("get_frames") = getFramesPy,
+                          nb::arg("generate_partial") = generatePartialPy);
     nb::tuple t = nb::cast<nb::tuple>(ret);
     oscadeval::DebugAction action;
     action.stop = (nb::cast<std::string>(t[0]) == "stop");
@@ -327,11 +350,13 @@ oscadeval::DebugAction callPyDebugHook(nb::handle hook, int line, int depth, boo
 // Trampoline: C++ errorBreak -> the Python DebugSession error hook.
 void callPyErrorBreak(nb::handle errorBreak, int line, const std::string& header, const std::string& origin,
                        const std::vector<oscadeval::CallStackFrame>& callStack,
-                       const oscadeval::DebugFramesFn& getFrame) {
+                       const oscadeval::DebugFramesFn& getFrame, const GeneratePartialFn& generatePartial) {
     std::vector<oscadeval::DebugFrame> frames = getFrame();
     nb::list allFrameLocals;
     for (const oscadeval::DebugFrame& f : frames) allFrameLocals.append(frameToDict(f));
-    errorBreak(line, header, allFrameLocals, callStackToPy(callStack), nb::arg("origin") = origin);
+    nb::object generatePartialPy = generatePartialTrampoline(generatePartial);
+    errorBreak(line, header, allFrameLocals, callStackToPy(callStack), nb::arg("origin") = origin,
+               nb::arg("generate_partial") = generatePartialPy);
 }
 
 // Trampoline: C++ returnHook -> the Python DebugSession return hook. Only
@@ -362,17 +387,29 @@ nb::object debugEvaluate(const std::string& path, nb::dict viewportParams, nb::c
             nb::gil_scoped_acquire g;
             echoFn(m);
         };
+        // Set right after `ev` is constructed below, before evaluate() runs
+        // -- every hook fires only from within that call, by which point
+        // this is always valid. Needed because `hooks` (captured by the
+        // lambdas below) must be fully built and passed into Evaluator's
+        // constructor before `ev` exists, so the lambdas can't capture `ev`
+        // itself; they capture this pointer's address instead, which DOES
+        // already exist (see generatePartial's own doc comment on why
+        // GeneratePartialFn needs a live Evaluator& at all).
+        oscadeval::Evaluator* evPtr = nullptr;
+        GeneratePartialFn generatePartial = [&evPtr]() -> std::vector<oscadeval::ColoredBody> {
+            return evPtr->generatePartialTree();
+        };
         oscadeval::DebugHooks hooks;
         hooks.debugHook = [&](int line, int depth, bool forced, const std::string& origin,
                               const std::vector<oscadeval::CallStackFrame>& cs,
                               const oscadeval::DebugFramesFn& gf) -> oscadeval::DebugAction {
             nb::gil_scoped_acquire g;
-            return callPyDebugHook(debugHook, line, depth, forced, origin, cs, gf);
+            return callPyDebugHook(debugHook, line, depth, forced, origin, cs, gf, generatePartial);
         };
         hooks.errorBreak = [&](int line, const std::string& header, const std::string& origin,
                                const std::vector<oscadeval::CallStackFrame>& cs, const oscadeval::DebugFramesFn& gf) {
             nb::gil_scoped_acquire g;
-            callPyErrorBreak(errorBreak, line, header, origin, cs, gf);
+            callPyErrorBreak(errorBreak, line, header, origin, cs, gf, generatePartial);
         };
         if (!returnHook.is_none()) {
             hooks.returnHook = [&](const std::string& name, const oscadeval::Value& result, int depth) {
@@ -384,6 +421,7 @@ nb::object debugEvaluate(const std::string& path, nb::dict viewportParams, nb::c
             std::vector<std::unique_ptr<oscad::ASTNode>> ast = oscad::getASTFromFile(path);
             oscadeval::ResolvedUseScopes used = oscadeval::resolveUseScopes(ast, path, echoCpp);
             oscadeval::Evaluator ev(echoCpp, nullptr, manifoldCache, hooks, false);
+            evPtr = &ev;
             oscadeval::EvalContext ctx = oscadeval::EvalContext::makeRoot(used.rootScope.get());
             bodies = oscadeval::toRenderableBodies(ev.evaluate(used.processedNodes, ctx, vp));
             collectIdSpans(ev, idSpans);

{openscad_cpp_evaluator-0.2.0 → openscad_cpp_evaluator-0.3.0}/include/openscad_cpp_evaluator/evaluator.hpp

@@ -174,6 +174,26 @@ public:
     // top-level show_only filter -- see evaluate().
     std::vector<ColoredBody> generateTree(const std::vector<std::unique_ptr<CSGNode>>& tree);
 
+    // Best-effort generate over whatever's been resolved SO FAR, for a live
+    // partial render while genuinely paused inside a debug hook mid-
+    // evaluation (resolveTree()/evaluate() haven't returned yet) -- flattens
+    // treeStack_ across every nesting level and runs the same bottom-up
+    // generate walk generateTree() uses, via generateTreeImpl(), over
+    // non-owning pointers into nodes treeStack_ (not this call) still owns.
+    // Safe to call mid-resolve: the resolve pass never reads CSGNode::bodies,
+    // only ever writes kind/params/children, so populating .bodies early
+    // here cannot corrupt or race the resolve that's paused around this
+    // call -- and if a ManifoldCache is set, the real generateTree() call at
+    // the end of evaluate() gets a cache hit for any subtree this already
+    // generated, so a debug session pays no repeated Manifold work session-
+    // wide (see manifold_cache.hpp's own doc comment on this exact use
+    // case). Only meaningful to call synchronously from within a
+    // DebugHookFn/ErrorBreakFn callback; the caller must not retain a
+    // reference into anything treeStack_ owns past that callback's return.
+    // Mirrors the reference's `ev.generate_tree(partial_nodes)` called from
+    // `_generate_partial_render`.
+    std::vector<ColoredBody> generatePartialTree();
+
     // Provenance tables populated by tagGenerated() during generate --
     // originalID -> the AST node that produced it / that node's own
     // resolved color. Public, read by a caller (CLI, WYSIWYG picking) after
@@ -357,6 +377,12 @@ private:
     std::vector<ColoredBody> evaluateImpl(const NodeList& nodes, EvalContext& ctx,
                                            const std::unordered_map<std::string, Value>& viewportParams);
 
+    // Shared bottom-up generate walk behind generateTree()/generatePartialTree()
+    // -- see generatePartialTree()'s own doc comment and this function's
+    // definition (csg_generate.cpp) for why non-owning pointers, not
+    // unique_ptr, let both callers share one implementation.
+    std::vector<ColoredBody> generateTreeImpl(const std::vector<CSGNode*>& tree);
+
     // Evaluates one top-level element of a `[...]` list literal (a plain
     // expression, or one of the 6 list-comprehension clause kinds --
     // for/c-for/let/if/if-else/each), appending whatever it contributes to

{openscad_cpp_evaluator-0.2.0 → openscad_cpp_evaluator-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "scikit_build_core.build"
 
 [project]
 name = "openscad_cpp_evaluator"
-version = "0.2.0"
+version = "0.3.0"
 description = "C++ OpenSCAD evaluator with Python bindings"
 readme = "README.md"
 requires-python = ">=3.12"

{openscad_cpp_evaluator-0.2.0 → openscad_cpp_evaluator-0.3.0}/python/openscad_cpp_evaluator/__init__.py

@@ -17,7 +17,7 @@ from ._openscad_cpp_evaluator import ManifoldCache
 
 __all__ = [
     "Evaluator", "ColoredBody", "EvalError", "ParseError", "OscObject", "parse", "to_renderable_bodies",
-    "ManifoldCache", "CallSiteProfile", "ProfileResult", "format_csg_tree",
+    "ManifoldCache", "CallSiteProfile", "ProfileResult", "format_csg_tree", "bodies_from_dicts",
 ]
 
 
@@ -132,7 +132,7 @@ class _CSGNode:
     def __init__(self, kind, params, bodies, is_builtin, children):
         self.kind = kind
         self.params = params
-        self.bodies = [ColoredBody(_BodyShim(d), d["color"], None, d["flat_preview"]) for d in bodies]
+        self.bodies = bodies_from_dicts(bodies)
         self.is_builtin = is_builtin
         self.children = children
 
@@ -289,6 +289,15 @@ class ColoredBody:
     flat_preview: bool = False
 
 
+def bodies_from_dicts(body_dicts) -> list:
+    """Convert raw body-dicts (the shape both evaluate()/debug_evaluate() and
+    a debug hook's `generate_partial()` callable return) to ColoredBody
+    instances. Shared by Evaluator.evaluate() and a debug session's own live
+    partial-render (see debug_evaluate()'s `generate_partial` hook kwarg,
+    module.cpp) so both paths convert identically."""
+    return [ColoredBody(_BodyShim(d), d["color"], None, d["flat_preview"]) for d in body_dicts]
+
+
 class Evaluator:
     """Drop-in for belfryscad.engine.evaluator.Evaluator, backed by C++.
 
@@ -355,7 +364,7 @@ class Evaluator:
             raise
         except Exception as e:  # ParseError/EvalError from C++ arrive as RuntimeError
             raise EvalError(str(e)) from e
-        bodies = [ColoredBody(_BodyShim(d), d["color"], None, d["flat_preview"]) for d in body_dicts]
+        bodies = bodies_from_dicts(body_dicts)
         # originalID -> a node with `.position` (start/end offsets) for WYSIWYG
         # picking and gizmo write-back.
         id_to_node = {

{openscad_cpp_evaluator-0.2.0 → openscad_cpp_evaluator-0.3.0}/src/csg_generate.cpp

@@ -22,10 +22,18 @@ std::vector<ColoredBody> flattenCsgTree(const std::vector<std::unique_ptr<CSGNod
     return result;
 }
 
-std::vector<ColoredBody> Evaluator::generateTree(const std::vector<std::unique_ptr<CSGNode>>& tree) {
+// Shared bottom-up walk behind generateTree() (owning unique_ptr tree) and
+// generatePartialTree() (a live, still-being-resolved treeStack_ level,
+// which the resolve pass -- not this function -- continues to own): takes
+// non-owning CSGNode* so both callers share one implementation without
+// either transferring ownership. unique_ptr's constness doesn't propagate
+// to the pointee, so mutating node.bodies here is legal even from a const
+// vector<unique_ptr<CSGNode>>& (see csg_node.hpp) -- this overload just
+// makes that non-owning access explicit for the treeStack_ caller too.
+std::vector<ColoredBody> Evaluator::generateTreeImpl(const std::vector<CSGNode*>& tree) {
     std::vector<ColoredBody> topLevelBodies;
     const auto& dispatch = generateDispatch();
-    for (const auto& nodePtr : tree) {
+    for (CSGNode* nodePtr : tree) {
         CSGNode& node = *nodePtr;
 
         // ManifoldCache lookup: node.uncacheable (rands() taint, set
@@ -43,10 +51,11 @@ std::vector<ColoredBody> Evaluator::generateTree(const std::vector<std::unique_p
         } else {
             // Recurse into children first (bottom-up) -- populates each
             // child's own .bodies in place so flattenCsgTree/a GenerateFn
-            // can read them back. unique_ptr's constness doesn't propagate
-            // to the pointee, so this mutation is legal even though `tree`
-            // is a const& (see csg_node.hpp).
-            generateTree(node.children);
+            // can read them back.
+            std::vector<CSGNode*> childPtrs;
+            childPtrs.reserve(node.children.size());
+            for (const std::unique_ptr<CSGNode>& c : node.children) childPtrs.push_back(c.get());
+            generateTreeImpl(childPtrs);
 
             auto it = dispatch.find(node.kind);
             if (node.isBuiltin && it != dispatch.end()) {
@@ -66,6 +75,28 @@ std::vector<ColoredBody> Evaluator::generateTree(const std::vector<std::unique_p
     return topLevelBodies;
 }
 
+std::vector<ColoredBody> Evaluator::generateTree(const std::vector<std::unique_ptr<CSGNode>>& tree) {
+    std::vector<CSGNode*> ptrs;
+    ptrs.reserve(tree.size());
+    for (const std::unique_ptr<CSGNode>& n : tree) ptrs.push_back(n.get());
+    return generateTreeImpl(ptrs);
+}
+
+std::vector<ColoredBody> Evaluator::generatePartialTree() {
+    // Flatten treeStack_ across every nesting level (mirrors the reference's
+    // `[node for level in ev._tree_stack for node in level]`): a CSGNode
+    // only lands in its parent's own accumulator once the parent's resolve
+    // finishes, so for a script whose whole geometry is one deeply-nested
+    // top-level statement, the *top* of the tree stays empty for the entire
+    // time spent stepping through its innermost leaves -- flattening every
+    // level picks up already-resolved leaves (e.g. a finished cube() sitting
+    // in a still-in-progress union()'s accumulator) regardless of how deep.
+    std::vector<CSGNode*> flat;
+    for (const std::vector<std::unique_ptr<CSGNode>>& level : treeStack_)
+        for (const std::unique_ptr<CSGNode>& node : level) flat.push_back(node.get());
+    return generateTreeImpl(flat);
+}
+
 ColoredBody Evaluator::tagGenerated(manifold::Manifold body, const oscad::ASTNode& node, const Value& colorValue) {
     manifold::MeshGL mesh = body.GetMeshGL();
     std::optional<std::array<float, 4>> color = valueToColor(colorValue);

{openscad_cpp_evaluator-0.2.0 → openscad_cpp_evaluator-0.3.0}/tests/test_python_bindings.py

@@ -96,7 +96,8 @@ def test_return_hook_fires_for_user_function():
     path = _write("function double(x) = x * 2; y = double(21); cube(y);")
     returns = []
 
-    def debug_hook(line, depth, forced=False, expr_level=False, expr_depth=0, origin=None, get_frames=None):
+    def debug_hook(line, depth, forced=False, expr_level=False, expr_depth=0, origin=None, get_frames=None,
+                   generate_partial=None):
         return ("continue", {})
 
     def return_hook(name, value, depth):
@@ -107,6 +108,52 @@ def test_return_hook_fires_for_user_function():
     assert returns == [("double", 42.0, 1)]
 
 
+def test_generate_partial_during_a_live_pause():
+    # Two statements: by the time the hook fires on line 2 (forced=True,
+    # the breakpoint() call), cube(1) has already fully resolved and
+    # generated once via the normal resolve pass -- but sphere(5) on the
+    # next line hasn't been reached yet. generate_partial() should return
+    # geometry from whatever's ALREADY been resolved at that exact moment
+    # (just the cube), proving it reads live in-progress state, not a
+    # snapshot from a completed evaluate().
+    path = _write("cube(1);\nbreakpoint();\nsphere(5);")
+    seen_partial_counts = []
+
+    def debug_hook(line, depth, forced=False, expr_level=False, expr_depth=0, origin=None, get_frames=None,
+                   generate_partial=None):
+        if forced:
+            bodies = generate_partial()
+            seen_partial_counts.append(len(bodies))
+        return ("continue", {})
+
+    ev = Evaluator(debug_hook=debug_hook)
+    bodies, _ = ev.evaluate(path)
+    assert seen_partial_counts == [1]  # only the cube, at the moment breakpoint() paused
+    assert len(bodies) == 2  # both cube and sphere in the final, complete result
+
+
+def test_generate_partial_on_an_empty_tree_returns_empty_not_an_error():
+    # At the very first statement's forced pause, nothing has resolved yet --
+    # generate_partial() must handle an empty tree gracefully (empty list),
+    # not raise. (A genuine GenerateFn exception mid-partial-render is real
+    # error-propagation behavior too -- see generatePartialTrampoline's own
+    # doc comment in module.cpp -- but isn't exercised here: this backend's
+    # builtins are permissive about invalid dimensions, same as real OpenSCAD,
+    # so there's no reliable way to force one from a script.)
+    path = _write("breakpoint();\ncube(1);")
+    seen = []
+
+    def debug_hook(line, depth, forced=False, expr_level=False, expr_depth=0, origin=None, get_frames=None,
+                   generate_partial=None):
+        if forced:
+            seen.append(generate_partial())
+        return ("continue", {})
+
+    ev = Evaluator(debug_hook=debug_hook)
+    ev.evaluate(path)
+    assert seen == [[]]
+
+
 def test_dyn_explicit_distinguishes_seeded_from_script_assigned():
     path = _write("$fn = 72; cube(1);")
     ev = Evaluator()