# Python Scripting (`opencad.python`) ## Sandboxing (Phase 1.5) **Audited, not assumed — and the assumption was wrong.** Earlier phases claimed "no stdlib is loaded, so `import os`/`socket`/`subprocess` is already impossible." True for those three names, but incomplete: RustPython 0.5.0's `host_env` Cargo feature — **on by default**, and `rustpython-vm = "0.5"` in this crate's `Cargo.toml` used to pull in the full default set — bakes `posix`/`_ctypes` (and `os`/`nt` on other platforms) into every interpreter's *core* module registry, entirely independent of ever adding the separate `rustpython-stdlib` crate. Confirmed by actually running it, not by reading feature flags: with `host_env` on, `PY_EVAL __import__('posix').getcwd()` and `PY_EVAL open('/etc/passwd').read()` both worked — full filesystem read (and write) access from any script. **Fixed**: `Cargo.toml` now depends on `rustpython-vm` with `default-features = false, features = ["compiler", "gc"]` — no `host_env`. Re-verified the full matrix after the fix, all blocked (`ModuleNotFoundError` or, for `open()`, `UnsupportedOperation`): `os`, `posix`, `nt`, `subprocess`, `socket`, `ctypes`, `_ctypes`, `_socket`, `_subprocess`, `_signal`, `pwd`, and both read and write through the built-in `open()` — its `FileIO` backing turned out to depend on `host_env`-gated code internally too, even though the `_io` module itself is always registered. Confirmed no functional regression: `ocs.add_line` and the full `examples/example.py` (including both real constraints) still run correctly with `host_env` off. What's left in `sys.modules` after that fix, for a fresh interpreter — audited exhaustively, not just "fewer than before": `_ast`, `_codecs`, `_frozen_importlib`, `_imp`, `_io`, `_thread`, `_typing`, `_warnings`, `_weakref`, `builtins`, `codecs`, `encodings_ascii`, `encodings_utf_8`, `ocs`, `sys` — core language/import/codec plumbing needed to run Python at all, plus `ocs`. None of it reaches the filesystem, network, or another process. **One known, accepted residual gap, not silently ignored: `_thread` is real and functional** (`_thread.start_new_thread` exists and is callable, verified — not a stub). It's registered unconditionally in `rustpython-vm` 0.5.0's `stdlib/mod.rs` with no feature guard at all — not `host_env`, not even its own `threading` Cargo feature — so there is no dependency-level way to remove it short of patching RustPython itself, which is out of scope here. It grants no filesystem/network/process access (everything that would matter for *that* is confirmed blocked above); the realistic risk is a script spawning a thread that busy-loops or otherwise misbehaves inside the plugin's own process — a resource/stability concern local to the already crash-isolated plugin process (per `plugin-architecture.md`'s out-of-process design), not a host compromise or data exfiltration path. Deleting `_thread` from `sys.modules` after interpreter setup was considered and rejected as a fix: the module stays *registered* at the VM level regardless, so a script could just re-import it — the deletion would be security theater, not a real control. ## Commands | Command | Description | |---------|-------------| | `PY_EVAL ` | Evaluate one Python expression and print the result (or error) to the command line. Example: `PY_EVAL 1 + 1`. | | `PY_RUN ` | Run a `.py` file as a script (statements, not just one expression). Reports an error the same way as `PY_EVAL` (missing file, syntax error, exception) — never a silent no-op. | ## The `ocs` module Pre-bound as `ocs` in both commands — no `import` needed (and for `PY_EVAL`, none is possible: it compiles in `Mode::Eval`, which only accepts a single expression, not statements). Phases 1.2 (read), 1.3 (2D write) and part of 1.4 (`Run Script…`) of this plugin's `ROADMAP.md`. | Function | Returns | |----------|---------| | `ocs.selection()` | List of the selected entities' handles (`int`), as of the last selection change — see note below. | | `ocs.get(handle)` | Dict of `{handle, kind, layer, point}` for that entity, or `None` if it doesn't exist. `point` is `{x, y, z}` or `None` for non-point entities. | | `ocs.get_text(handle)` | For single-line TEXT, returns its active alignment point, OCS normal, rotation, direction, and height; otherwise `None`. Reads the host's full document snapshot. | | `ocs.text_entities()` | Lists top-level TEXT/MTEXT entities as `{handle, kind, value}` dictionaries from the active document. | | `ocs.block_references()` | Lists top-level INSERT entities as `{handle, name, effective_name, count, is_xref, is_dynamic, visibility}` dictionaries; `count` includes MINSERT row × column multiplicity and unresolved visibility is `None`. | | `ocs.layers()` | Lists active-document layer names, off/frozen/locked flags, and top-level entity counts. | | `ocs.set_entity_layer(handle, layer_name)` | Moves an existing top-level entity to an existing layer, preserving its handle and layout ownership. | | `ocs.export_layer_dwg(layer_name, output_path)` | Writes a new DWG containing one layer's top-level entities plus needed block definitions; requires an existing directory and refuses overwrite. | | `ocs.current_layer()` | Returns the active document's current layer name (`CLAYER`). | | `ocs.layout_for_entity(handle)` | Returns an entity's owning layout name, tab order, and paperspace sheet count; `None` when unresolved. | | `ocs.viewport_model_outline(handle)` | Returns four XY modelspace corners and elevation for a rectangular, unclipped +Z paperspace viewport; otherwise `None`. | | `ocs.add_closed_polyline(vertices, elevation)` | Adds a closed lightweight polyline from at least three finite `[x, y]` vertices. | | `ocs.text_box_vertices(handle, padding)` | Returns an approximate rotated XY box for left/baseline +Z TEXT; otherwise `None`. | | `ocs.update_closed_polyline(handle, vertices, elevation)` | Replaces a closed lightweight polyline's vertices/elevation, preserving its handle and common properties. | | `ocs.copy_model_to_paper(handles, viewport_handle)` | Copies planar modelspace LINE/ARC/CIRCLE/LWPolyline geometry through a rectangular +Z viewport to its paperspace layout. | | `ocs.mirror_xy_entities(handles, axis_handle, erase_source)` | Mirrors planar LINE/ARC/CIRCLE/LWPolyline entities across an existing XY LINE; optionally removes sources in the same undo group. | | `ocs.mirror_xy_about_line(handles, point, tangent, erase_source)` | Mirrors planar curves across the XY line through a point in a tangent direction; supports curved-axis midpoint workflows. | | `ocs.break_xy_line(handle, first, second)` | Removes the span between two interior XY points on a LINE, preserving its first fragment's handle and properties. | | `ocs.break_xy_arc(handle, first, second)` | Removes the angular span between two interior XY ARC points, retaining the first fragment's handle. | | `ocs.break_xy_circle(handle, first, second)` | Replaces an XY CIRCLE with the complementary ARC after removing the counterclockwise span from first to second. | | `ocs.break_xy_polyline(handle, first, second)` | Removes a path interval from an open, straight, zero-width XY LWPolyline, keeping the first fragment's handle. | | `ocs.align_xy_entities(handles, source, destination, source_direction, target_direction, copy_mode)` | Rigidly moves and rotates planar LINE/ARC/CIRCLE/LWPolyline entities in XY; `copy_mode=True` adds transformed copies instead of changing originals. | | `ocs.block_insert_point(handle)` | Returns `[x, y, z]` for an INSERT, or `None`. | | `ocs.block_bounds_xy(handle)` | Returns `[xmin, ymin, xmax, ymax]` for a simple unrotated single INSERT whose definition contains only LINE/ARC/CIRCLE/LWPolyline geometry; otherwise `None`. | | `ocs.block_attributes(handle)` | Lists `{tag, value}` pairs for one INSERT, or `None` for another entity. | | `ocs.set_block_attribute(handle, tag, value)` | Updates one INSERT attribute by case-insensitive tag, preserving the block's other data. | | `ocs.set_text_value(handle, value)` | Replaces one TEXT/MTEXT entity's content, preserving other properties. Raises if the entity cannot be updated. | | `ocs.set_mtext_mask(handle, mode, scale)` | Sets one MTEXT background mode (`off`, `mask`, or `fill`) and border scale; raises if invalid or not MTEXT. | | `ocs.move_text(handle, x, y, z)` | Moves only a TEXT entity's active alignment point, preserving its other properties. Raises if it cannot update the entity. | | `ocs.set_text_pose(handle, x, y, z, rotation)` | Moves and rotates one XY TEXT entity while preserving its other properties. | | `ocs.get_area(handle)` | Returns `{area, point}` for a circle or straight, closed lightweight polyline in the world XY plane; otherwise `None`. `point` is suitable for an area-number label. | | `ocs.get_curve_measure(handle)` | Returns `{length, point, rotation, tangent}` at half length for an XY line, circle, arc, or straight lightweight polyline; `tangent` is an XY unit vector. Otherwise `None`. | | `ocs.line_endpoints(handle)` | Returns two `[x, y, z]` points for a nonzero XY LINE; otherwise `None`. | | `ocs.polyline_segments(handle)` | Returns segment endpoint, width, length, and optional bulge-arc centre/radius dictionaries for an XY lightweight polyline; otherwise `None`. | | `ocs.write_new_text_file(path, content)` | Writes a new UTF-8 report file at an explicit path during a `PY_` command. Refuses to overwrite or create parent directories. | | `ocs.curve_samples(handle, segments)` | Returns equally spaced XY sample vertices, elevation, and closure for a line, arc, or circle; otherwise `None`. | | `ocs.replace_with_polyline(handle, vertices, elevation, closed)` | Replaces a line, arc, or circle in place with a lightweight polyline, preserving the handle and common drawing properties. | | `ocs.add_line(x1, y1, x2, y2)` | Adds a 2D line (z=0, layer `"0"`); returns its handle. | | `ocs.add_circle(x, y, radius)` | Adds a 2D circle (z=0, layer `"0"`); returns its handle. | | `ocs.add_arc(x, y, radius, start_deg, end_deg)` | Adds a 2D arc (z=0, layer `"0"`), angles in degrees; returns its handle. | | `ocs.add_polyline(vertices, elevation)` | Adds an open 2D lightweight polyline. Each vertex is `[x, y, start_width, end_width]`; returns its handle. | | `ocs.add_text_centered(value, x, y, z, height, rotation_radians)` | Adds middle-center aligned single-line text; returns its handle. | | `ocs.add_text_left(value, x, y, z, height, rotation_radians)` | Adds left/baseline single-line text at its insertion point; returns its handle. | | `ocs.add_mtext(value, point, height, width, rotation_radians)` | Adds top-left anchored MTEXT at `[x, y, z]` using Standard style; returns its handle. | | `ocs.add_points(points)` | Adds many 3D points (each `[x, y, z]`) in one `HostApi::add_entities` batch call; returns the new handles in order. | | `ocs.remove_entity(handle)` | Deletes one entity in the script's undo group; raises if the handle cannot be removed. | | `ocs.add_table(rows, x, y, z, row_height, column_width)` | Adds a native table from a rectangular list of string rows; returns its handle. | | `ocs.read_record(handle, app_name)` | Returns `{app_name, values}` for the XDATA record `app_name` on `handle`, or `None` if the entity or the record doesn't exist. See "XDATA" below for the `values` shape. | | `ocs.write_record(handle, app_name, values)` | Attaches an XDATA record to `handle` for `app_name`, replacing any existing record for that application. Raises if `handle` doesn't exist. | | `ocs.remove_record(handle, app_name)` | Removes the XDATA record for `app_name` from `handle`, if any. Returns `True` if a record was actually removed. | | `ocs.command(cmd)` | Experimental only; absent from the portable default build. Requires unreleased host API support and can hang on OCS 2026.37. See historical notes below. | | `ocs.select(handles)` | Experimental only; absent from the portable default build. Requires unreleased host API support. | | `ocs.system_variable(name)` / `ocs.set_system_variable(name, value)` | Development-only `experimental-host-settings` feature. Reads or sets host-managed CLAYER (text) and SNAPANG (degrees) without nested command dispatch. Requires the Felix OCS fork's `plugin/host-model-api` branch; absent from the portable default build. | `add_line`/`add_circle`/`add_arc` take plain Python numbers — `ocs.add_line(0, 0, 10, 10)` works with ints, not just floats. (Needed an explicit fix: a bare `f64` `#[pyfunction]` parameter in RustPython, unlike CPython's C-function argument parsing, does *not* implicitly coerce an `int` — it raises `TypeError`. Using `rustpython_vm::function::ArgIntoFloat` instead accepts anything with `__float__`/`__index__`, matching how a script author actually writes coordinates.) ### Layers: `ocs.active_document.layers` The layer table, with every change validated by the host, recorded as one undo step, and refused (a `RuntimeError`, nothing changed) when it cannot be honoured. ```python L = ocs.active_document.layers L.create("Walls", color=1, lineweight=50, description="load bearing") L.create("Grid", color=(10, 200, 30), linetype="Continuous", off=True) L.modify("Walls", color=5, locked=True) # only the properties given L.rename("Walls", "Structure") # entities on it follow L.set_current("Grid") L.delete("Structure", erase_objects=True) # refused if it holds objects otherwise "Grid" in L, L["Grid"]["color"], L.current, L.names() ``` Properties: `color` (ACI 1-255, an `(r, g, b)` tuple or a Color dict), `linetype` (must exist in the drawing), `lineweight` (1/100 mm, 0-211; -1 ByLayer, -2 ByBlock, -3 Default), `off`, `frozen`, `locked`, `plottable`, `transparency` (percent 0-90), `description`. Records also carry `handle`, `entity_count` and `current`. Refused: an existing or invalid name (empty, over 255 characters, or containing `<>/\":;?*|=` or a backquote), a color of ByLayer/ByBlock/0, an unknown property, renaming or deleting layer `0` or `Defpoints`, deleting or freezing the current layer, deleting an externally referenced layer, and modifying with no properties. Making a layer current is a setting, not an undo step. ### Text and dimension styles: `doc.text_styles`, `doc.dim_styles` ```python S, D = ocs.active_document.text_styles, ocs.active_document.dim_styles S.create("Title", height=5, width_factor=0.8, oblique=15, font="romans", annotative=True) S.modify("Title", height=6) D.create("Metric", dimscale=2, dimtxt=3.5, dimtxsty="Title") # DimStyle field names D.create("Metric2", copy_from="Metric", dimtxt=4) S.rename("Title", "Heading") # entities, dimension styles and tables follow S.set_current("Heading"); D.set_current("Metric") D.delete("Metric2"); S["Heading"]["height"]; D.current["name"]; S.names() ``` Same guarantees as layers: host-validated, one undo step, a refusal raises `RuntimeError` and changes nothing (making a style current is a setting). Text properties: `height` (0 = each text chooses), `width_factor` (0-100), `oblique` (degrees, within 85), `font`, `big_font`, `backward`, `upside_down`, `vertical`, `annotative`; use `font="arial.ttf"` for a TrueType face, because the codec does not persist a separate family name. Dimension styles use the `DimStyle` field names (`dimscale`, `dimtxt`, `dimasz`, ...); records list all of them. Handles, `xref_*` fields and `name` are host-managed and refused, unknown fields and wrongly typed values are refused, `dimscale` and `dimtxt` must be positive, and `dimtxsty` must name an existing text style. `Standard` is never renamed or deleted; a style that is current or still referenced is never deleted; a case-only rename is refused. Style operations act on the active document. Known persistence limits (cadcodec, see `docs/cadcodec-reader-gaps.md`): a DXF save drops the backward/upside-down flags of a text style and does not restore a dimension style's `dimtxsty` name (the handle link survives); DWG keeps both. ### Blocks: `ocs.active_document.blocks` ```python doc = ocs.active_document line = doc.create_entity("Line", start=..., end=...) circle = doc.create_entity("Circle", center=..., radius=1) B = doc.blocks B.create("Widget", [line, circle], base_point=(1, 1, 0), description="a widget") doc.create_entity("Insert", block_name="Widget", insert_point={"x": 10, "y": 0, "z": 0}) B.modify("Widget", explodable=False) B.rename("Widget", "Gadget") # every insert follows B["Gadget"]["entities"], B["Gadget"]["insert_count"], B.names() B.delete("Gadget") # refused while an insert, style or leader uses it ``` `create` copies model or paper space entities (descriptors or handles) into a new definition shifted by `-base_point`, so an insert at `p` puts the base point at `p`. `erase_originals=True` removes the sources, as the BLOCK command does; the default keeps them. No insert is placed. Refused: an empty, duplicate, invalid or `*`-prefixed name, no entities, a missing or repeated entity, an entity inside a block, a viewport, a non-finite base point, renaming or deleting layout, anonymous or externally referenced blocks, and a case-only rename. Deleting also removes the definition's contents. Records list user blocks only (`handle`, `name`, `description`, `explodable`, `scale_uniformly`, `base_point`, `insert_count`, `entities` as `{handle, kind}`). A DXF save drops the block description (cadcodec); DWG keeps it. **Block contents.** Add to a definition with `create_entity(kind, block="Part", ...)`. It is validated exactly like a model-space entity and the host sets the owner (so attribute definitions work: `create_entity("AttributeDefinition", block="Part", tag=..., prompt=..., default_value=..., insertion_point=..., height=...)`). Members are read, edited (`entity.end = (8, 0, 0)` inside `doc.transaction(...)`) and deleted (`doc.delete_entity`) with the ordinary entity API, using the handles in `blocks["Part"]["entities"]`. Refused: an unknown, layout, anonymous or external block, an invalid entity, a viewport, raster image, block marker or nested attribute, an entity on a locked layer, and an insert that would nest a block inside itself directly or through other blocks. Adding while the block editor is open is refused. Each add or delete is one undo step. ### Linetypes and layouts: `doc.linetypes`, `doc.layouts` ```python doc = ocs.active_document LT, LY = doc.linetypes, doc.layouts LT.create("Bracket", [12, -3, 2, -3], "bracket line") # dash 12, gap 3, dash 2, gap 3 LT.modify("Bracket", description="renamed"); LT.rename("Bracket", "Cut") doc.layers.create("Cuts", linetype="Cut") LT.delete("Cut") # refused while a layer uses it LY.create("Sheet1") LY.set_page("Sheet1", paper_size=(420, 297), rotation=0, scale=(1, 50)) LY.current = "Sheet1" # create_entity now draws on the sheet doc.create_entity("Circle", center={"x": 50, "y": 50, "z": 0}, radius=5) LY.current = "Model" LY.rename("Sheet1", "Plan"); LY.delete("Plan") # deletes the sheet's entities too LY.names(), LY.current["name"], LY["Plan"]["paper_size"] ``` Both follow the same rules as the other tables: host-validated, one undo step (switching layout is not one), a refusal raises `RuntimeError` and changes nothing. A linetype pattern is signed lengths (positive dash, negative gap, zero dot; 2-12 elements with a gap and a dash or dot); text and shape linetypes can be read (`complex`) but not created or edited. `Continuous`, `ByLayer` and `ByBlock` are never changed, names of standard linetypes are taken, renaming updates the layers and entities that use it, and a linetype used by a layer, entity, dimension style or the current setting is never deleted. Layouts: `Model` cannot be created, renamed or deleted; deleting the current layout falls back to `Model`; a case-only rename is refused. `set_page` takes the sheet in millimetres, a rotation of 0/90/180/270 and a custom scale `(numerator, denominator)`, and updates the layout limits. Layout operations act on the active document. Records list `current`, `tab_order`, `entity_count`, `viewport_count`, `paper_size`, `rotation` and `scale`. Reordering layouts and plot devices or styles are not available yet. ### Running OCS commands: `doc.command`, `doc.start_command`, `doc.modify` Scripts can drive OCS's own tools. The host runs the real command, so it behaves exactly as at the command line (same prompts, same geometry, same undo), and does it synchronously on the editor thread, so a step never waits on outside input. ```python doc = ocs.active_document doc.command("CIRCLE 5,5 3") # a whole line: tokens answer the prompts, then Enter with doc.start_command("OFFSET") as c: # or answer prompt by prompt c.text(2) # a typed value c.entity(line, at=(5, 0, 0)) # an object pick c.point((5, 4, 0)) # a point c.enter() print(c.outcome["status"], c.outcome["prompt"], c.outcome["added"]) M = doc.modify # the common tools as plain calls M.offset(line, 2, side=(5, 5)) # returns the new entity M.trim(target, at=(108, 0)); M.extend(target, at=(208, 0)) M.fillet(first, second, radius=2) # radius 0 squares the corner M.move([a, b], (0, 0, 0), (5, 5, 0)); M.copy([a], base, target) M.rotate([a], base, 90); M.scale([a], base, 2) M.mirror([a], p1, p2, erase_source=False); M.erase([a]) M.chamfer(first, second, 2, 3) # distance 2 along first, 3 along second M.array_rect([a], rows=2, columns=3, row_spacing=10, column_spacing=20) M.array_polar([a], center, count=4, angle=360) # counts include the original M.explode([polyline]); M.join([line1, line2]) M.break_entity(line, first_point, second_point) M.stretch(corner1, corner2, base, target) # crossing window, then the displacement M.lengthen(line, 5, at=near_the_end) # delta; negative shortens ``` Each step returns an outcome dict: `status` (`completed` or `waiting_input`), `blocked_by`, `command`, `prompt`, `accepts` (`point`, `entity`, `selection`, `text`, `token`, `enter`), `options` (keyword tokens), `entities`, `added`, `unconsumed` and `error`. `c.point`, `c.text`, `c.token`, `c.entity`, `c.selection`, `c.enter` and `c.cancel` map to those prompts; an `error` raises `RuntimeError`, and leaving the `with` block cancels a command that is still waiting, also closing any editor or dialog it opened. `doc.command` cancels and raises when the line leaves a prompt open. Selection-based tools (`move`, `copy`, `rotate`, `scale`, `mirror`, `erase`, the arrays, `explode` and `join`) select the entities you pass first, so the command skips its own selection prompt. Pick points default to the middle of a line, arc or circle; give `at=` for anything else. `trim` and `extend` cut or extend against every entity in the drawing. Each command is undone as the editor would undo it. Guards: a command is refused while another is active (cancel it first) or when the line names a command that could end the session or re-enter Python: `QUIT`, `EXIT`, `CLOSE`, `CLOSEALL`, `NEW`, `QNEW`, `OPEN`, `SAVE`, `QSAVE`, `SAVEAS`, `SAVEALL`, `RECOVER`, `SCRIPT`, `RUNSCRIPT` and any `PY_*`. Commands run on the active document only. Commands that need an interactive surface a script cannot fill (the rich-text editor, a file dialog) report it in `blocked_by` and are cancelled. Hatching has no wrapper: create it with `create_entity("Hatch", ...)`, because the HATCH command needs an interactive boundary pick. `ocs.command_step(kind, options)` is the raw single step behind all of this. ### Historical command-replay experiment (not in the default build) The following records an earlier experiment. The bundled build does **not** expose `ocs.command()` or `ocs.select()`. An OCS 2026.37 diagnostic found nested `ocs.command("CLAYER ...")` could hang, so these examples are not instructions to run against the released host. **`ocs.command()` + `ocs.select()` together can apply a real, persistent constraint, entirely from a script** — this required two host changes (`HostApi::run_command` and `HostApi::set_selection`, `ocs_plugin_api` v0.2.1+ built from a worktree that isn't upstream yet — see the note at the bottom of this file), not something achievable from the plugin alone. Verified end-to-end against a real running host, not just "it compiles": ```python ocs.select([line1_handle, line2_handle]) ocs.command("PCONSTRAINT") ``` run as a plain `.py` file via `PY_RUN` — no automation-API help, no manual pre-selection — ran the actual geometric solver and visibly adjusted both lines' coordinates to be genuinely parallel (checked numerically: direction-vector cross product ≈ 0 after, nonzero before). A real, persistent `PCONSTRAINT` object. Same result verified for `TCONSTRAINT` (circle-to-line tangency): center-to-line distance equals the radius exactly after. `examples/example.py` does both — its "parallel" lines and "tangent" circle are real constraint objects, not geometry computed once. Why two calls, not one: constraint commands read a prior *selection* (a `"Select objects:"` prompt), not picks fed as command-line tokens the way `LINE`'s points are — feeding `ocs.command("PCONSTRAINT {h1} {h2}")` with handles as trailing tokens starts the command but ends in "Command cancelled", not a constraint. `ocs.select()` sets that selection state first; `ocs.command()` then reads it. **Not every command completes cleanly this way — `ALIGN` is the found counterexample.** `ocs.command()`'s point-feeding sends exactly *one* trailing Enter after the fed tokens, to finish the command. `ALIGN` needs two after its point pairs (skip the optional 3rd source/destination pair, then answer a "Scale objects? [Yes/No]" question) — so `ocs.command("ALIGN 0,0 20,20 2,0 22,22")` **does** apply the actual move/rotate transform correctly (verified: the entities land at the right transformed coordinates), but leaves that Scale prompt open instead of cleanly finishing the command. Not attempted in `examples/example.py` — shipping something that half-completes seemed worse than leaving it out. A general fix would need `ocs.command()` to accept a trailing-Enter *count* (or an explicit terminator convention) instead of always exactly one; not implemented. **`ocs.command()` cannot invoke itself or any other plugin's command** — only built-ins. This call is a nested plugin→host request arriving while the plugin's own `dispatch()` is still running (its one runner thread is blocked waiting for this exact call to return); routing it back through normal plugin dispatch would hand that same plugin (or any plugin) a second `Dispatch` request it has no free thread to answer, deadlocking both sides. Found this the hard way — `ocs.command("LINE 0,0 10,10")` hung completely before the host-side fix. `run_command` skips plugin dispatch entirely, by design, not as an oversight. ### Which built-in commands `ocs.command()` can reach `ocs.command()` goes through the exact same dispatcher as the interactive command line — `HostApi::run_command` → the host's `run_command_line_no_plugin_reentry` → `dispatch_command_inner(cmd, allow_suggest=false, try_plugins=false)` — so almost everything typeable in OCS also works from a script, minus one deliberate carve-out. **Reachable: the full built-in command set**, spread across ten dispatch families in the host's `src/app/commands/` (`fileops`, `layers`, `blocks`, `draw`, `dim`, `inquiry`, `view`, `layerprops`, `styleprops`, `display`). That covers everything AutoCAD-compatible the host implements natively — drawing entities and constraints (`LINE`, `CIRCLE`, `ARC`, `POLYLINE`, `MOVE`, `ROTATE`, `ALIGN`, `PCONSTRAINT`, `TCONSTRAINT`, in `dispatch_draw`), dimensions (`DIMLINEAR`, `DIMALIGNED`, `DIMSTYLE`, ...), blocks (`BLOCK`, `INSERT`, `WBLOCK`, `ATTSYNC`, ...), layers/properties (`LAYER`, `LAYISO`, `LAYDEL`, `CHPROP`, `PROPERTIES`, ...), file ops (`NEW`, `OPEN`, `SAVE`, `SAVEAS`, `EXPORT...`, `PLOT`, ...), inquiry (`LIST`, `DIST`, `AREA`, `DBLIST`, ...), view (`ZOOM`, `PAN`, `VIEW`, `REGEN`, ...), and directly-settable system variables typed as commands (`PICKBOX 5`, `MIRRTEXT 1`, `LUPREC 4`, ...). Aliases still resolve too (`ocs.command("L 0,0 10,10")` works the same as `LINE`), since alias expansion happens before the plugin-skip. **Not reachable: any plugin-provided command, including this plugin's own** (`PYTHONSHELL`, `PY_EVAL`, `PY_RUN`) — see the paragraph above for why. This is the *only* restriction versus the interactive command line; there is no narrower allow-list beyond it. `allow_suggest=false` also means no autocomplete/fuzzy-matching of partial verbs (unlike typing `BAC` and pressing Enter for `BACKGROUND`) — a script must spell out the exact command name or a real alias. Usage notes already verified end-to-end (see the constraint example above and `examples/example.py`): - Multi-point/interactive commands take their args inline on one string, exactly as if typed then Enter: `ocs.command("LINE 0,0 10,10")`. - A command that reads a *prior selection* rather than inline picks (constraint commands are the concrete case) needs `ocs.select(handles)` called first — `ocs.command()` alone can't feed a "Select objects:" prompt. - `ALIGN` needs two trailing Enters (skip the optional 3rd point pair, then answer the Scale prompt); `ocs.command()` only ever sends one, so it applies the transform but leaves that prompt dangling — see above. For the exhaustive, exact list rather than this summary, the source of truth is the `inventory::submit!(CommandRegistration { names: &[...] })` blocks scattered across the host's `src/app/commands/*.rs` (105 files register at least one command as of this writing); the largest single block — everything without its own interactive command module — is `src/app/commands/mod.rs`'s command-line autocomplete registry. Since it's the same dispatcher, OCS's own command-line autocomplete is also a live index of what `ocs.command()` can run. **One `push_undo` group per script, not per `ocs.add_*` call.** A `PY_RUN` script that calls `ocs.add_line` ten times undoes as one step. Verified end-to-end: a two-line script undoes both lines in a single `undo`. Implemented via `host_ctx::ensure_undo_started`, called lazily by the first write in a given `PY_EVAL`/`PY_RUN` — a read-only script never touches the undo stack. Note: `ocs.command()` does *not* go through this — a built-in command manages its own undo the same way it would if typed, so `ocs.command` calls are not folded into the script's shared undo group. **`ocs.selection()` is a cache, not a live query.** `HostApi` has no synchronous "give me the current selection" call — only a best-effort `SelectionChanged` / `SelectionChangedV4` notification. It reflects the selection as of the last time it changed, not necessarily the instant the script calls it. That cache is populated via `BuiltinPlugin::on_notification`, **not** by calling `HostApi::try_recv_notification()` from `dispatch()`. Found the hard way: `ocs_plugin_api::runner`'s own V4 event loop (`run_v4` in `runner.rs`) drains that queue itself on every iteration and forwards each notification to `on_notification` *before* a `Dispatch` request ever reaches `dispatch()` — so polling it from inside `dispatch` always finds it empty. This plugin overrides `on_notification` and stashes the latest selection in a process-wide cache (`selection_cache.rs`); `ocs.selection()` reads that. Verified end-to-end against a real host build: select an entity, then `PY_EVAL ocs.selection()` returns its handle. Each `PY_EVAL`/`PY_RUN` runs in a fresh interpreter (no stdlib, no session state across calls) — REPL/session persistence is an open question for a later phase. **Typing or pasting `PY_EVAL`/`PY_RUN` directly into the interactive command line is broken for anything beyond trivial arithmetic — a host issue, not this plugin.** `Message::CommandInput` in `src/app/update/mod.rs` (this repo) uppercases the *entire* input line on every keystroke *and* on paste, and auto-submits the instant it contains a space (both deliberate, for classic single-line CAD commands like `LINE 0,0 10,10`). That mangles case (`ocs.add_line` → `OCS.ADD_LINE`, a `NameError`) and truncates arguments (`PY_EVAL ` submits before you finish typing the expression) for *any* multi-word, case-sensitive plugin argument — automation (`ocs_execute`/`--mcp`) bypasses this UI path entirely, which is why it never surfaced in this session's own testing until a live user tried typing it by hand. **`Run Script…` (below) sidesteps this correctly** — the host authors already solved the identical problem for file paths via `ModuleEvent::PluginFileDialog`, which dispatches with original case intact. There is no equivalent bypass for `PY_EVAL` today; typed/pasted `PY_EVAL` only survives if it has no spaces and no case-sensitive identifiers. ## Ribbon Two tools in the "Tools" group: | Tool | Behavior | |------|----------| | Eval 1+1 | Dispatches `PY_EVAL 1 + 1` directly — a smoke test. | | Run Script… | `ModuleEvent::PluginFileDialog` opens a native "pick a `.py` file" dialog; on selection the host dispatches `PY_RUN ` back to the plugin. Cancel does nothing. | **A real script manager UI (list/run/save scripts, or a dockable REPL console) is not possible with today's `ocs_plugin_api`.** This was an open question in `ROADMAP.md` — now answered by reading `ribbon.rs`: `CadModule` exposes exactly one hook, `ribbon_groups()`, which returns a **static** set of ribbon buttons/dropdowns (`RibbonItem`). There is no API for a plugin to host a persistent custom panel, list dynamic content, or render arbitrary UI — the ribbon vocabulary is deliberately "plain data the host renders," not a widget toolkit. Getting a script list or REPL panel would need a new `HostApi`/`CadModule` capability, i.e. an `ocs_plugin_api` version bump — a host-side feature, out of scope for a plugin repo. `Run Script…` (above) is the most a plugin can do today: reuse the host's own native file picker via the existing `PluginFileDialog` event, which was already there for other plugins to import files. ## lisp2py — AutoLISP macro transpiler `../lisp2py/` (an independent sibling workspace — zero dependency on this crate or `ocs_plugin_api`) is a **best-effort, offline, source-to-source** translator from AutoLISP (`.lsp`) to the `ocs.*` Python dialect documented above. Not an interpreter: it never executes AutoLISP, and its output is a draft a human reviews and finishes, then runs through `PY_RUN` like any other script. This is Phase 2.2/2.3 of `ROADMAP.md` — see [`../lisp2py/README.md`](../lisp2py/README.md) for the full pipeline, the corpus-measured builtin coverage, and every known limitation; this is just the quick-start. ```sh cargo run --manifest-path ../lisp2py/Cargo.toml --bin ocs-lisp2py -- macro.lsp > macro.py # then, inside OCS: PY_RUN macro.py ``` (Or pipe source on stdin: `cat macro.lsp | cargo run --manifest-path ../lisp2py/Cargo.toml --bin ocs-lisp2py -- > macro.py`.) Anything the translator can't confidently map — an unrecognized builtin, a construct with no Python equivalent — becomes a `_todo_manual_port(...)` call in the generated file (raises `NotImplementedError` if actually run) plus a warning printed to stderr, never a silent guess. `vla-*`/`vlax-*` (ActiveX/COM) and `vlr-*` (reactors) are explicitly out of scope, for the same reason as everywhere else in this plugin's design: COM doesn't run under AutoCAD for Mac either. Builtin coverage was widened using measured call-frequency data from a real AutoLISP corpus sample rather than guesswork, biased toward 2D geometry (`angle`/`distance`/`polar`) over 3D/solid-modeling per current project priority. ## XDATA `ocs.read_record`/`ocs.write_record`/`ocs.remove_record` wrap `HostApi::read_record`/`write_record`/`remove_record` — already implemented by the host (unlike `run_command`/`set_selection`, these needed no host change or `[patch]` entry). A record is `{"app_name": str, "values": [...]}`; each value is `{"kind": str, "value": ...}`. Supported kinds and their Python `value` shape: | `kind` | Python `value` | |---|---| | `String`, `ControlString`, `LayerName` | `str` | | `BinaryData` | `bytes` | | `Handle` | `int` | | `Point3D`, `Position3D`, `Displacement3D`, `Direction3D` | `[x, y, z]` (`float`) | | `Real`, `Distance`, `ScaleFactor` | `float` | | `Integer16`, `Integer32` | `int` | ```python ocs.write_record(handle, "MYAPP", [ {"kind": "String", "value": "part-042"}, {"kind": "Integer32", "value": 7}, ]) record = ocs.read_record(handle, "MYAPP") # {"app_name": "MYAPP", "values": [...]} ocs.remove_record(handle, "MYAPP") ``` This `{app_name, values}`/`{kind, value}` shape is deliberately the same one `schoeller/ocs_python_repl` (a separate, out-of-process PyO3-based Python plugin for OCS) uses in its `ocs.doc.read_record`/`write_record`, so a script's XDATA handling ports between the two plugins unchanged. `write_record` starts the script's shared undo group the same way `ocs.add_*` does (see below); `remove_record` only starts it when a record actually existed to remove. ## Build note: bundled host API `Cargo.toml` uses the repository-relative `ocs_plugin_api` crate. Packaging builds the plugin with the same compiler and CAD codec as the host and stages matching metadata beside the library. The `experimental-command-replay` Cargo feature keeps the old bridge code available, but the tested nested-command path can hang. Do not enable it for production.