bluesky_queueserver_api.http.REManagerAPI

class bluesky_queueserver_api.http.REManagerAPI(*, http_server_uri=None, http_auth_provider=None, timeout=5.0, timeout_login=60.0, console_monitor_poll_period=0.5, console_monitor_max_msgs=10000, console_monitor_max_lines=1000, request_fail_exceptions=True, status_expiration_period=0.5, status_polling_period=1.0)

API for communication with RE Manager using HTTP (RESTful API) protocol.

Parameters:

http_server_uri: str or None

URI of Bluesky HTTP Server. If None, then the default URI “http://localhost:60610”` is used.

http_auth_provider: str or None, optional

Name of the endpoint of authentication provider (such as '/toy/token') or None if authentication provider is not needed (e.g. if authorization using API keys is used). The provider may also be passed as a parameter of login API if needed. Default: None.

timeout: float, optional

Request timeout. Positive value sets timeout in seconds, 0 (zero) disables timeouts, None sets timeout to the default value. Default value is 5.0 seconds.

timeout_login: float, optional

Request timeout used for login requests. Login requests may take substantial time to process at the server, especially in case of 2FA. See the description for the parameter timeout for more information. Default value is 60.0 seconds.

console_monitor_poll_period: float

Polling period defines interval between consecutive HTTP requests to the server. Default: 0.5 s.

console_monitor_max_msgs: int

Maximum number of messages in the internal message buffer. Default: 10000.

console_monitor_max_lines: int

Maximum number of lines in the internal text buffer. Default: 1000.

request_fail_exceptions: boolean

If True (default) then API functions that communicate with RE Manager are raising the RequestFailError exception if the request is rejected (the response contains "success": False, e.g. if a submitted plan is rejected). If False, then API functions are always returning the response and user code is responsible for checking and processing the success flag.

status_expiration_period: float

Expiration period for cached RE Manager status, default value: 0.5 seconds

status_polling_period: float

Polling period for RE Manager status used by ‘wait’ operations, default value: 1 second

Examples

Synchronous API:

from bluesky_queueserver_api.http import REManagerAPI
RM = REManagerAPI()
# < some useful code >
RE.close()

Asynchronous API:

from bluesky_queueserver_api.http.aio import REManagerAPI

async def testing():
    RM = REManagerAPI()
    # < some useful code >
    await RE.close()

asyncio.run(testing())

__init__(*, http_server_uri=None, http_auth_provider=None, timeout=5.0, timeout_login=60.0, console_monitor_poll_period=0.5, console_monitor_max_msgs=10000, console_monitor_max_lines=1000, request_fail_exceptions=True, status_expiration_period=0.5, status_polling_period=1.0)

Methods

__init__(*[, http_server_uri, ...])
api_scopes(*[, token, api_key])	Returns API scopes for an authorized user.
apikey_delete(*, first_eight[, token, api_key])	Delete an API key for the authorized principal. The API key is identified by first eight characters. For example, an API key ::.
apikey_info(*[, api_key])	Get information about an API key.
apikey_new(*, expires_in[, scopes, note, ...])	Generate a new API key for authorized user.
close()	Close RE Manager client.
config_get()	Returns config info for RE Manager.
devices_allowed(*[, reload, user_group])	Returns the list (dictionary) of allowed devices.
devices_existing(*[, reload])	Returns the list (dictionary) of existing devices.
environment_close(*[, lock_key])	Close RE Worker environment.
environment_destroy(*[, lock_key])	Destroy RE Worker environment.
environment_open(*[, lock_key])	Open RE Worker environment.
environment_update(*[, run_in_background, ...])	Update RE Worker environment cache.
function_execute(item, *[, ...])	Start execution of a function in RE Worker namespace.
get_default_lock_key([new_key])	Returns the default lock key.
history_clear(*[, lock_key])	Remove all items from the history.
history_get(*[, reload])	Returns the list of plans in the history.
item_add(item, *[, pos, before_uid, ...])	Add item to the queue.
item_add_batch(items, *[, pos, before_uid, ...])	Add a batch of items to the queue.
item_execute(item, *[, user, user_group, ...])	Immediately execute the submitted item.
item_get(*[, pos, uid])	Load an existing queue item.
item_move(*[, pos, uid, pos_dest, ...])	Move an item to a different position in the queue.
item_move_batch(*[, uids, pos_dest, ...])	Move a batch of items to a different position in the queue.
item_remove(*[, pos, uid, lock_key])	Remove an item from the queue.
item_remove_batch(*, uids[, ignore_missing, ...])	Remove a batch of items from the queue.
item_update(item, *[, replace, user, ...])	Update an existing item in the queue.
kernel_interrupt(*[, interrupt_task, ...])	Send interrupt request (Ctrl-C) to the running IPython kernel.
lock([lock_key, environment, queue, note, user])	Lock RE Manager with a lock key.
lock_all([lock_key, note, user])	Locks the environment and the queue in RE Manager.
lock_environment([lock_key, note, user])	Locks the environment in RE Manager.
lock_info([lock_key, reload])	Returns status information of the current lock.
lock_queue([lock_key, note, user])	Locks the queue in RE Manager.
login([username, password, provider])	Parameters:
logout()	Log out.
permissions_get()	Download the dictionary of user group permissions currently used by RE Manager.
permissions_reload(*[, ...])	Generate the new lists of allowed plans and devices based on current user group permissions and the lists of existing plans and devices.
permissions_set(user_group_permissions, *[, ...])	Uploads the dictionary of user group permissions.
ping(*[, reload])	Current implementation of the API loads status of RE Manager, but this may change in future releases.
plans_allowed(*[, reload, user_group])	Returns the list (dictionary) of allowed plans.
plans_existing(*[, reload])	Returns the list (dictionary) of existing plans.
principal_info(*[, principal_uid])	Returns full information on all principals or one principal.
queue_autostart(enable, *[, lock_key])	Enable/disable autostart mode.
queue_clear(*[, lock_key])	Remove all items from the plan queue.
queue_get(*[, reload])	Returns the list of items (plans and instructions) in the plan queue and currently running plan.
queue_mode_set(**kwargs)	Set parameters that define the mode of plan queue execution.
queue_start(*[, lock_key])	Start execution of the queue.
queue_stop(*[, lock_key])	Request RE Manager to stop execution of the queue after completion of the currently running plan.
queue_stop_cancel(*[, lock_key])	Cancel the pending request to stop execution of the queue after the currently running plan.
re_abort(*[, lock_key])	Request Run Engine to abort paused plan.
re_halt(*[, lock_key])	Request Run Engine to halt paused plan.
re_pause([option, lock_key])	Request Run Engine to pause currently running plan.
re_resume(*[, lock_key])	Request Run Engine to resume paused plan.
re_runs([option, reload])	Request the list of active runs generated by the currently executed plans.
re_stop(*[, lock_key])	Request Run Engine to stop paused plan.
script_upload(script, *[, update_lists, ...])	Upload and execute script in RE Worker namespace.
send_request(*, method[, params, ...])	Send request to RE Manager and receive the response.
session_refresh(*[, refresh_token])	Refresh session using valid refresh token.
session_revoke(*, session_uid[, token, api_key])	Revoke session for an authorized user.
set_authorization_key(*[, api_key, token, ...])	Set default authorization key(s) for HTTP requests.
set_default_lock_key(lock_key)	Set the default lock key.
set_user_name_to_login_name()	Set the default user name to 'login name'.
status(*[, reload])	Load status of RE Manager.
task_result(task_uid)	Get the status and results of task execution.
task_status(task_uid)	Returns the status of one or more tasks executed by the worker process.
unlock([lock_key])	Unlock RE Manager.
wait_for_completed_task(task_uid, *[, ...])	Wait for one or multiple tasks to be completed.
wait_for_condition(condition, *[, timeout, ...])	The function periodically checks RE Manager status and blocks until the condition callable returns True and can be used to wait for arbitrary conditions based on RE Manager status and/or user-provided data.
wait_for_idle(*[, timeout, monitor])	Wait for RE Manager to return to "idle" state.
wait_for_idle_or_paused(*[, timeout, monitor])	Wait for RE Manager to switch to idle or paused state.
wait_for_idle_or_running(*[, timeout, monitor])	Wait for RE Manager to switch to idle or executing_queue state.
whoami(*[, token, api_key])	Returns full information about the principal.

Attributes

auth_key	Returns authorization key.
auth_method	Returns authorization method (API key, token or none).
console_monitor	Reference to a console_monitor.
default_lock_key_path	Get/set path of the file with the default lock key.
enable_locked_api	Enable/disable access to locked API.
lock_key	Get/set current lock key.
protocol	Indicates the protocol used for communication (ZMQ or HTTP).
request_fail_exceptions_enabled	Enable or disable RequestFailedError exceptions (boolean).
user	Get and set the default user name.
user_group	Get and set the default user group name.