Skip to content

_runner

In-engine runner for agent-submitted source.

The agent host writes an entry script that calls :func:run with the AgentScriptContext it built. The runner executes the agent source in a fresh namespace, captures everything printed, serializes result to JSON, and reports all of it back through the context.

Invariant

This module must stay parseable by IronPython 2.7, IronPython 3.4 and CPython 3, because the host picks the engine per request.

Invariant

pyrevitlib is loaded live while the host is a compiled DLL that only changes after a rebuild and a Revit restart, so this module can meet an older AgentScriptContext. Read any context member added after the first release with getattr and a default that keeps the old behavior.

Attributes

SOURCE_NAME = '<agent-script>' module-attribute

IRONPYTHON_TRACED_RECURSION_LIMIT = 500 module-attribute

Python call depth a traced IronPython run may reach.

Warning

A trace function makes every IronPython frame larger, so on Revit's 1 MB main thread a traced run with several with or try blocks per frame overflows the stack and crashes Revit between 750 and 900 calls, below the engine's limit of 1000. Untraced runs keep the engine's limit.

Classes

RunTimedOut

Bases: BaseException

Raised inside the agent script once its time limit has passed.

Derives from BaseException so a script's except Exception can't swallow it. The runner narrows every bare except and except BaseException (or except builtins.BaseException) in the script to except Exception before compiling, and records that the deadline passed so :func:run fails the run even if the script then ends normally. A handler that still catches it, such as one reached through an alias, is stopped at the next rewritten loop header, or on CPython 3.12+ by the watchdog's jump escalation.

Functions:

run(context)

Execute context.Source and report the outcome on context.

Parameters:

Name Type Description Default
context AgentScriptContext

run request and outcome sink from the host.

required
Note

Never raises. Script errors, including a failure to serialize result and a BaseException such as KeyboardInterrupt, are reported through context.SetError so the host can roll the run back. A run that passed its time limit reports no result.

Note

context.TimeoutSeconds is enforced by a watchdog thread that sets a flag every loop header of the agent source checks (see :func:_guard_loop_headers); on CPython it also raises RunTimedOut in the script thread. It stops Python code, including loops, but not a single blocking call such as a long Revit API call or time.sleep, nor, on IronPython, a long loop inside a pyrevitlib or rpw function the script calls; the run fails with timeout once that call returns. Modules imported from the workspace folder get the same loop rewrite through an import hook (:class:_WorkspaceLoopGuard) that lives only as long as the run. On IronPython, a run with no trace function (see docs/agent-runtime.md) has no check outside loop headers, so a callback passed to map, filter or sorted over an endless iterable is not stopped.

Note

While a trace function is installed, an IronPython run's recursion limit is held at :data:IRONPYTHON_TRACED_RECURSION_LIMIT, even if the script raises it, and the previous limit is restored when the script ends.

Note

Transactions the script leaves open are found by rewriting each <expr>.Start(...) call to record its object first (see :func:_record_transaction_starts), so a script that opens transactions runs as fast as one that doesn't. A line tracer is only installed when that can't see every start: a workspace run, code compiled at run time, or Start reached other than by a direct call. Reported tracebacks leave out this module's frames.

Warning

When context.Reckless is true ([agent] reckless, see docs/agent-runtime.md), none of the above applies: the source is compiled as submitted, no watchdog starts, no trace function is installed, and context.TimeoutSeconds is not enforced at all, so a runaway loop blocks Revit until the process is ended. Transactions left open are still rolled back, but only those reachable from the script's globals; one left open inside a function is not found and can crash Revit when it is finalized.

Warning

The source is compiled with every bare except and except BaseException narrowed to except Exception, so a script cannot swallow RunTimedOut there, and can no longer catch KeyboardInterrupt or SystemExit that way. A script that suppresses it some other way, such as through an alias, is stopped again at its next loop header, and on CPython 3.12+ at the end of any loop it is still in a second later (see :func:_start_watchdog).

Source code in pyrevitlib/pyrevit/agent/_runner.py
def run(context):
    """Execute ``context.Source`` and report the outcome on ``context``.

    Args:
        context (AgentScriptContext): run request and outcome sink from the host.

    Note:
        Never raises. Script errors, including a failure to serialize
        ``result`` and a ``BaseException`` such as ``KeyboardInterrupt``, are
        reported through ``context.SetError`` so the host can roll the run
        back. A run that passed its time limit reports no ``result``.

    Note:
        ``context.TimeoutSeconds`` is enforced by a watchdog thread that sets
        a flag every loop header of the agent source checks (see
        :func:`_guard_loop_headers`); on CPython it also raises
        ``RunTimedOut`` in the script thread. It stops Python code, including
        loops, but not a single blocking call such as a long Revit API call or
        ``time.sleep``, nor, on IronPython, a long loop inside a
        pyrevitlib or rpw function the script calls; the run fails with
        ``timeout`` once that call returns. Modules imported from the
        ``workspace`` folder get the same loop rewrite through an import hook
        (:class:`_WorkspaceLoopGuard`) that lives only as long as the run.
        On IronPython, a run with no trace function
        (see ``docs/agent-runtime.md``) has no check outside loop headers, so
        a callback passed to ``map``, ``filter`` or ``sorted`` over an endless
        iterable is not stopped.

    Note:
        While a trace function is installed, an IronPython run's recursion
        limit is held at :data:`IRONPYTHON_TRACED_RECURSION_LIMIT`, even if
        the script raises it, and the previous limit is restored when the
        script ends.

    Note:
        Transactions the script leaves open are found by rewriting each
        ``<expr>.Start(...)`` call to record its object first (see
        :func:`_record_transaction_starts`), so a script that opens
        transactions runs as fast as one that doesn't. A line tracer is only
        installed when that can't see every start: a ``workspace`` run, code
        compiled at run time, or ``Start`` reached other than by a direct
        call. Reported tracebacks leave out this module's frames.

    Warning:
        When ``context.Reckless`` is true (``[agent] reckless``, see
        ``docs/agent-runtime.md``), none of the above applies: the source is
        compiled as submitted, no watchdog starts, no trace function is
        installed, and ``context.TimeoutSeconds`` is not enforced at all, so a
        runaway loop blocks Revit until the process is ended. Transactions
        left open are still rolled back, but only those reachable from the
        script's globals; one left open inside a function is not found and
        can crash Revit when it is finalized.

    Warning:
        The source is compiled with every bare ``except`` and ``except
        BaseException`` narrowed to ``except Exception``, so a script cannot
        swallow ``RunTimedOut`` there, and can no longer catch
        ``KeyboardInterrupt`` or ``SystemExit`` that way. A script that
        suppresses it some other way, such as through an alias, is stopped
        again at its next loop header, and on CPython 3.12+ at the end of
        any loop it is still in a second later (see :func:`_start_watchdog`).
    """
    phases = _PhaseClock(context)
    context.SetEngine(_implementation(), sys.version.split()[0], sys.version)
    source = context.Source
    linecache.cache[SOURCE_NAME] = (
        len(source),
        None,
        _source_lines(source),
        SOURCE_NAME,
    )
    captured = _CappedOutput(_MAX_OUTPUT_CHARS + 1)
    saved_stdout = sys.stdout
    saved_stderr = sys.stderr
    sys.stdout = captured
    sys.stderr = captured
    failed = False
    workspace = None
    workspace_guard = None
    workspace_folder = context.Workspace
    namespace = None
    left_open = 0
    reckless = bool(getattr(context, "Reckless", False))
    timeout_s = None if reckless else getattr(context, "TimeoutSeconds", None)
    state = {
        "timed_out": False,
        "interrupted": False,
        "script_ended": False,
        "finished": False,
        "check_lines": False,
    }
    script_finished = False
    tracked_transactions = {}
    try:
        workspace = _enter_workspace(context.Workspace)
        namespace = _build_namespace(context)
        guard_loops = bool(timeout_s)
        if guard_loops:
            (
                namespace["__agent_tick__"],
                namespace["__agent_loop__"],
            ) = _loop_guards(timeout_s, state, tracked_transactions)
            if workspace_folder:
                workspace_guard = _WorkspaceLoopGuard(
                    workspace_folder,
                    {
                        name: namespace[name]
                        for name in ("__agent_tick__", "__agent_loop__")
                    },
                    lambda: state.update(check_lines=True),
                )
                sys.meta_path.insert(0, workspace_guard)
        phases.lap("setup")
        if reckless:
            code = compile(source, SOURCE_NAME, "exec")
            rewrite_problem, track, unguarded_code = None, False, False
        else:
            namespace[_START_RECORDER] = _start_recorder(tracked_transactions)
            recorded_source, starts_recorded = _record_transaction_starts(source)
            code, rewrite_problem, loops_guarded = _compile_source(
                recorded_source, guard_loops
            )
            dynamic_code = _runs_dynamic_code(source)
            track = _needs_transaction_tracking(
                context.Workspace, starts_recorded, dynamic_code
            )
            unguarded_code = (
                not loops_guarded or dynamic_code or _hides_loops_in_fstrings(source)
            )
        phases.lap("compile")
        if rewrite_problem:
            print(
                "[pyRevit agent] Could not rewrite the script's headers ({}).".format(
                    rewrite_problem
                )
            )
        check_lines = (
            guard_loops and unguarded_code and _set_async_exc_function() is None
        )
        started = time.time()
        saved_recursion_limit = sys.getrecursionlimit()
        saved_trace = getattr(sys, "gettrace", lambda: None)()
        try:
            if timeout_s:
                _start_watchdog(timeout_s, state)
            if check_lines or track:
                sys.settrace(
                    _execution_tracer(
                        timeout_s,
                        state,
                        tracked_transactions,
                        check_lines,
                        track,
                        _limit_traced_recursion(),
                    )
                )
            script_exit = None
            try:
                exec(code, namespace)
            except SystemExit as ex:
                script_exit = ex
            finally:
                state["script_ended"] = True
                phases.lap("exec")

            script_finished = True
            if script_exit is not None:
                if not _is_successful_exit(script_exit):
                    failed = True
                    context.SetError(
                        "SystemExit", _system_exit_message(script_exit), ""
                    )
            _raise_if_past_deadline(timeout_s, started, state)
            serialized = None
            if not failed and "result" in namespace:
                try:
                    serialized = json.dumps(
                        namespace["result"],
                        default=_to_jsonable,
                        ensure_ascii=False,
                    )
                except Exception as ex:
                    failed = True
                    context.SetError(
                        "ResultSerializationError",
                        _safe_text(ex),
                        _format_script_traceback(),
                    )
                phases.lap("result")

            state["finished"] = True
            _raise_if_past_deadline(timeout_s, started, state)
            if serialized is not None:
                context.SetResult(serialized)
        finally:
            _finish_and_stop_watchdog(state)
            sys.settrace(saved_trace)
            sys.setrecursionlimit(saved_recursion_limit)
    except BaseException as ex:
        failed = True
        if isinstance(ex, RunTimedOut) and state["timed_out"]:
            if script_finished and not state["interrupted"]:
                context.SetError("timeout", _late_timeout_message(timeout_s), "")
            else:
                context.SetError(
                    "timeout",
                    "The script ran longer than its {} second limit and was "
                    "stopped; its changes were rolled back. Pass a larger timeout_s "
                    "if the work needs more time.".format(_format_limit(timeout_s)),
                    "" if script_finished else _format_script_traceback(),
                )
        else:
            error_type, message = _describe_error(ex)
            context.SetError(error_type, message, _format_script_traceback())
    finally:
        if workspace_guard is not None:
            sys.meta_path[:] = [
                finder for finder in sys.meta_path if finder is not workspace_guard
            ]
        if namespace is not None:
            left_open = _roll_back_open_transactions(namespace, tracked_transactions)
        _TRANSACTION_RANKS.clear()
        _UNTRACKED_TYPES.clear()
        _TRACKED_TYPES.clear()
        _ATTRIBUTE_HOLDERS.clear()
        linecache.cache.pop(SOURCE_NAME, None)
        phases.lap("rollback")
        sys.stdout = saved_stdout
        sys.stderr = saved_stderr
        _leave_workspace(context.Workspace, workspace)
        context.SetOutput(captured.getvalue())
        phases.lap("cleanup")

    if left_open and not failed:
        context.SetError(
            "transaction_left_open",
            "The script left {} transaction(s) open; they were rolled back. Commit or "
            "roll back every transaction it starts.".format(left_open),
            None,
        )
        return
    if failed or "result" not in namespace:
        return

warm_up()

Run a small script through :func:run so the first agent run finds the runner ready.

The agent host calls this once per session load, after the first request an agent sends (see docs/agent-runtime.md). The script goes through source rewriting, compilation, loop guards, transaction recording, the watchdog, result serialization and the rollback scan, against a context with no Revit application: it reads no document, starts no transaction and leaves no run record.

Raises:

Type Description
RuntimeError

the warm-up script reported an error. The host only logs it.

Source code in pyrevitlib/pyrevit/agent/_runner.py
def warm_up():
    """Run a small script through :func:`run` so the first agent run finds the runner ready.

    The agent host calls this once per session load, after the first request
    an agent sends (see ``docs/agent-runtime.md``). The script goes through
    source rewriting, compilation, loop guards, transaction recording, the
    watchdog, result serialization and the rollback scan, against a context
    with no Revit application: it reads no document, starts no transaction
    and leaves no run record.

    Raises:
        RuntimeError: the warm-up script reported an error. The host only
            logs it.
    """
    context = _WarmUpContext()
    run(context)
    if context.error is not None:
        raise RuntimeError("Agent warm-up failed: {}: {}".format(*context.error))