bluesky_queueserver_api.zmq.REManagerAPI.script_upload

REManagerAPI.script_upload(script, *, update_lists=None, update_re=None, run_in_background=None, lock_key=None)

Upload and execute script in RE Worker namespace. The script may add, modify or replace objects defined in the namespace, including plans and devices. Dynamic modification of the worker namespace may be used to implement more flexible workflows. The API call updates the lists of existing and allowed plans and devices if new plans or devices are added, modified or deleted by the script. Use task_result API to check if the script was loaded correctly. Note, that if the task fails, the script is still executed to the point where the exception is raised and the respective changes to the environment are applied.

Parameters:
script: str

The string that contains the Python script. The script should satisfy the same requirements as Bluesky startup scripts. The script can use objects already existing in the RE Worker namespace.

update_lists: boolean (optional, default True)

Update lists of existing and available plans and devices after execution of the script. It is required to update the lists if the script adds or modifies plans and/or devices in RE Worker namespace, otherwise it is more efficient to disable the update. For example, the update could be disabled for the remotely executed scripts that print or modify variables from the namespace during iteractive debug session.

update_re: boolean (optional, default False)

The uploaded scripts may replace Run Engine (RE) and Data Broker (db) instances in the namespace. In most cases this operation should not be allowed, therefore it is disabled by default, i.e. if the script creates new RE and db objects, those objects are discarded. Set this parameter True to allow the server to replace RE and db objects. This parameter has no effect if the script is not creating new instances of RE and/or db.

run_in_background: boolean (optional, default False)

Set this parameter True to upload and execute the script in the background (while a plan or another foreground task is running). Generally, it is not recommended to update RE Worker namespace in the background. Background tasks are executed in separate threads and only thread-safe scripts should be uploaded in the background. Developers of data acquisition workflows and/or user specific code are responsible for thread safety.

lock_key: str or None (optional)

The lock key enables access to the API when RE Manager environment is locked. If the parameter is not None, the key overrides the current lock key set by REManagerAPI.lock_key. See documentation on REMangerAPI.lock() for more information. Default: None.

Returns:
response: dict

Dictionary keys:

  • success: boolean - success of the request.

  • msg: str - error message in case the request is rejected by RE Manager or operation failed.

  • task_uid - UID of the started task.

Raises:
RequestTimeoutError, RequestFailedError, HTTPRequestError, HTTPClientError, HTTPServerError

All exceptions raised by send_request API.

Examples

script = "def test_sleep():\n    yield from bps.sleep(5)\n"

# Synchronous code (0MQ, HTTP)
RM.script_upload(script)

# Asynchronous code (0MQ, HTTP)
await RM.script_upload(script)