mxcubecore.queuelib.serializer

QueueSerializer: turns the queue tree into the client JSON format, and turns client JSON back into calls on QueueBuilder.

Classes

QueueSerializer(builder)

Serializes the queue.

class mxcubecore.queuelib.serializer.QueueSerializer(builder)

Bases: object

Serializes the queue. Depends only on mxcubecore (HWR.beamline.*) and its sibling QueueBuilder - no self.app reference.

add_task(parent: int | str, item: dict) → int

Add a single task to an already-queued sample.

Unlike queue_add_item (which validates and adds a whole batch of samples/tasks at once), this adds exactly one task to a sample that must already be in the queue - it never creates a Sample node.

Parameters:

• parent (int | str) – the sample’s queueID, or its sampleID/loc_str

• item (dict) – task dict, e.g. {“type”: “DataCollection”, “parameters”: {…}}

Returns:

the new task’s queue id

Return type:

int

node_to_dict(node) → dict

Return a dict representing <node> itself

Return type:

dict

pretty_print_queue(msg: str | None = None) → None

Pretty print current queue state for debugging.

Parameters:

msg (str | None) –

Return type:

None

queue_add_item(item_list)

Add queue items to the queue.

Add the queue items in item_list to the queue. The items in the list can be either samples and or tasks. Samples are only added if they are not already in the queue and tasks are appended to the end of an (already existing) sample. A task is ignored if the sample is not already in the queue.

The items in item_list are dictionaries with the following structure:

{ “type”: “Sample | DataCollection | Characterisation”, “sampleID”: sid … task or sample specific data }

Each item (dictionary) describes either a sample or a task.

Validation (malformed input) is all-or-nothing: if any item fails schema validation, nothing is mutated and ValidationError propagates - the request never touched the queue. Once past validation, adding is best-effort per top-level item (see JSON_FORMAT.md known issue #8): items can depend on an earlier one in the same call (e.g. a task nested under a sample added earlier in the same list), so a failed item can’t simply roll back everything after it without also undoing work later items may already depend on. The returned dict’s “add_results” key reports which top-level items (by sampleID) succeeded or failed, so a client doesn’t have to guess from an all-or-nothing HTTP status and risk re-submitting (duplicating) items that already succeeded.

queue_to_dict() → dict

Return the whole queue: a dict keyed by sample ID, plus “sample_order” and “format_version” - see JSON_FORMAT.md.

Return type:

dict