Skip to content

_operations

Run a marked automation operation for the agent's run_automation tool.

The CLI picks the operation from its library index and sends a fixed script that calls :func:invoke; the module, function and id arrive as data in the run's inputs, never as code. :func:invoke re-checks everything the CLI checked against the live marker, so a stale index or a hand-built request cannot call anything that is not a marked, invocable operation.

The run itself is a query run, so the host still rolls back any model change and blocks saves and exports.

Attributes

ALLOWED_PACKAGES = ('pyrevit.', 'rpw.') module-attribute

Packages an operation can be imported from.

INVOCABLE_MODES = ('query', 'pure') module-attribute

Modes run_automation may call; every other mode needs run_modify.

MAX_ITEMS = 200 module-attribute

Items returned from a list result; total and truncated say the rest.

Classes

OperationError

Bases: Exception

Raised when an operation cannot be run through run_automation.

Functions:

invoke(operation, inputs, doc)

Validate the inputs and call one marked operation.

Parameters:

Name Type Description Default
operation dict

{"id", "module", "function"} chosen by the CLI

required
inputs dict

the caller's input object

required
doc Document

the active document, or None

required

Returns:

Type Description
dict

{"value": ...}; a list result keeps its first

data:MAX_ITEMS items and adds total and truncated

Raises:

Type Description
OperationError

when the operation is not invocable

InputError

when the inputs do not match

Source code in pyrevitlib/pyrevit/agent/_operations.py
def invoke(operation, inputs, doc):
    """Validate the inputs and call one marked operation.

    Args:
        operation (dict): ``{"id", "module", "function"}`` chosen by the CLI
        inputs (dict): the caller's input object
        doc (DB.Document): the active document, or None

    Returns:
        (dict): ``{"value": ...}``; a list result keeps its first
        :data:`MAX_ITEMS` items and adds ``total`` and ``truncated``

    Raises:
        OperationError: when the operation is not invocable
        pyrevit_automation.InputError: when the inputs do not match
    """
    function, marker = _marked_function(operation)
    automation.validate_inputs(marker["inputs"], inputs)

    needs_document = marker.get("context") == "document"
    if needs_document and doc is None:
        raise OperationError("'{}' requires an active document.".format(marker["id"]))

    arguments = {}
    for spec in automation.parse_inputs(marker["inputs"]):
        if spec["name"] not in inputs:
            continue
        value = inputs[spec["name"]]
        if spec["type"] == "element":
            value = _element(doc, value, spec["name"])
        arguments[spec["name"]] = value
    if needs_document and "doc" in _parameter_names(function):
        arguments["doc"] = doc

    return _bounded(function(**arguments))