_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
1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 | |
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. |