Pending Actions (Server Jobs)

A Pending Action is the record of a background process running on the server. Endpoints that start long-running work, such as imports, exports and texture generation, return one of these instead of making you wait, and it is the handle you use to follow that work to completion.

See Pending Actions in the API reference for the underlying endpoints.

Waiting for completion

Rather than polling yourself, hand the ID to on_completion. It blocks until the action reaches a terminal state and returns both the final record and every progress message it saw along the way.

import bruce_models as BM

result = BM.PendingAction.on_completion(bruce, action_id)

action = result.get("action")
print(action.get("Status"))
print(action.get("Result"))

for message in result.get("messages"):
    print(message.get("Message"))

A failed or cancelled action returns normally rather than raising, because the messages are usually what you need in order to find out why. Check Status to tell the outcomes apart.

import bruce_models as BM

result = BM.PendingAction.on_completion(bruce, action_id)
action = result.get("action")

if action.get("Status") == BM.EStatus.COMPLETE:
    print("Done:", action.get("Result"))
elif action.get("Status") == BM.EStatus.FAILED:
    print("Failed. Messages:")
    for message in result.get("messages"):
        print(" ", message.get("Message.Type"), message.get("Message"))

You can follow progress as it happens, and give up after a while instead of waiting indefinitely.

import bruce_models as BM

result = BM.PendingAction.on_completion(
    bruce,
    action_id,
    # Seconds between status checks. Defaults to 3.
    interval=5,
    # Raises a TimeoutError once exceeded. Waits indefinitely when omitted.
    timeout=600,
    on_progress=lambda a: print(f"{a.get('Progress')}%"),
    on_message=lambda m: print(m.get("Message"))
)

Reading records directly

The Result property is always a dictionary. The API returns it as a string by default, which is usually but not always stringified JSON, so this library requests the parsed form and saves you guessing. A result that was not JSON arrives as { "Output": "..." }.

import bruce_models as BM

# A single record.
action = BM.PendingAction.get(bruce, action_id)
print(action.get("Progress"), action.get("Status"))
print(action.get("Result"))

# Recent records, optionally filtered by status.
actions = BM.PendingAction.get_list(bruce, start_index=0, amount=20).get("Items")
in_progress = BM.PendingAction.get_list(
    bruce,
    status=BM.EStatus.IN_PROGRESS
).get("Items")

# Progress messages, newest first.
messages = BM.PendingAction.get_messages(bruce, action_id, amount=30)

# Ask the server to stop the work.
BM.PendingAction.cancel(bruce, action_id)

Statuses

BM.EStatus holds the available statuses, and BM.EStatus.FINISHED is the set of terminal ones so you do not have to list them yourself.

import bruce_models as BM

BM.EStatus.IN_PROGRESS
BM.EStatus.COMPLETE
BM.EStatus.FAILED
BM.EStatus.CANCELLED

# Every status other than IN_PROGRESS.
if action.get("Status") in BM.EStatus.FINISHED:
    print("Nothing more to wait for.")

# Message types, useful for hiding debug output from end users.
BM.EMessageType.INFO
BM.EMessageType.STATUS
BM.EMessageType.WARNING
BM.EMessageType.ERROR