bluesky_queueserver_api.zmq.REManagerAPI.item_add

REManagerAPI.item_add(item, *, pos=None, before_uid=None, after_uid=None, user=None, user_group=None, lock_key=None)

Add item to the queue. The item may be a plan or an instruction represented as a dictionary of parameters or an instance of BItem, BPlan or BInst classes. The item is added to the back of the queue by default. Alternatively, the item may be placed at the desired position in the queue or inserted before or after one of the existing items. The parameters pos, before_uid and after_uid are mutually exclusive, i.e. only one of the parameters may have a value different from None.

Parameters:
item: dict, BItem, BPlan or BInst

Dictionary or an instance of BItem, BPlan or BInst representing a plan or an instruction.

pos: str, int or None

Position of the item in the queue. RE Manager will attempt to insert the item at the specified position. The position may be positive or negative integer. If the value is negative, the position is counted from the back of the queue, so "pos": -1 inserts the item to the back of the queue, "pos": -2 - to the position previous to last ect. If pos has a string value "front" or "back", then the item is inserted at the front or the back of the queue. If the value is None (default), then the position is not specified.

before_uid, after_uid: str or None

Insert the item before or after the item with the given item UID. If None (default), then the parameters are not specified.

user, user_group: str or None (optional)

User name and user group name used in the API request. The parameter values override the default user and user group names (accessible using user and user_group properties). The default user or user group name is used if the respective parameter is not specified or None. The parameters are ignored by the HTTP version of the API.

lock_key: str or None (optional)

The lock key enables access to the API when RE Manager queue 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.

  • qsize: int or None - new size of the queue or None if operation failed,

  • item: dict or None - a dictionary with parameters of the inserted item, including the assigned UID. If the request is rejected, the dictionary is a copy of the submitted item (with assigned UID) or None.

Raises:
RequestTimeoutError, RequestFailedError, HTTPRequestError, HTTPClientError, HTTPServerError

All exceptions raised by send_request API.

Examples

# Synchronous code (0MQ, HTTP)
# Add an item to the back of the queue
RM.item_add({"item_type": "plan", "name": "count", "args": [["det1"]]})
# Add an item to the front of the queue
RM.item_add(BItem("plan", "count", ["det1"], num=10, delay=1), pos="front")
RM.item_add(BItem("plan", "count", ["det1"], num=10, delay=1), pos=0)
# Insert an item to the position #5 (numbers start from 0)
RM.item_add(BPlan("count", ["det1"], num=10, delay=1), pos=5)
# Insert an item before the last item
RM.item_add(BPlan("count", ["det1"], num=10, delay=1), pos=-1)

try:
    response = RM.item_add(BPlan("count", ["det1"], num=10, delay=1))
    # No exception was raised, so the request was successful
    assert response["success"] == True
    assert response["msg"] == ""
    # Print some parameters
    print(f"qsize = {response['qsize']}")
    print(f"item = {response['item']}")

    # Insert another plan before the plan that was just inserted
    item_uid = response["item"]["item_uid"]
    RM.item_add(BPlan("count", ["det1"], num=10, delay=1), before_uid=item_uid)
except RM.RequestFailedError as ex:
    print(f"Request was rejected: {ex}")
    # < code that processes the error >

# Asynchronous code (0MQ, HTTP)
# Add an item to the back of the queue
await RM.item_add({"item_type": "plan", "name": "count", "args": [["det1"]]})
# Add an item to the front of the queue
await RM.item_add(BItem("plan", "count", ["det1"], num=10, delay=1), pos="front")
await RM.item_add(BItem("plan", "count", ["det1"], num=10, delay=1), pos=0)
# Insert an item to the position #5 (numbers start from 0)
await RM.item_add(BPlan("count", ["det1"], num=10, delay=1), pos=5)
# Insert an item before the last item
await RM.item_add(BPlan("count", ["det1"], num=10, delay=1), pos=-1)