uncountable.core.async_batch.AsyncBatchProcessor

class uncountable.core.async_batch.AsyncBatchProcessor(*, client)

Helper class that provides a standard way to create an ABC using inheritance.

Parameters:

client (Client)

associate_equipment_input(*, equipment_key, material_family_ids, depends_on=None, _request_options=None)

Create or return an input association for a piece of equipment within specified material families. The equipment is resolved via identifier key. Supports both direct invocation and async batch execution. Returns modification_made and result_id of the association.

Parameters:

  • equipment_key (IdentifierKey) – Identifier of the equipment to associate

  • material_family_ids (list[ObjectId]) – The list of material families to add the input to. This must be non-empty

  • depends_on (list[str] | None) – A list of batch reference keys to process before processing this request

  • _request_options (RequestOptions | None)

Return type:

QueuedAsyncBatchRequest

associate_recipe_as_input(*, recipe_key, input_key=None, show_in_listings=None, depends_on=None, _request_options=None)

Associates a recipe as an input (ingredient). When no existing input is specified, creates a new input or returns the existing association if one already exists. When an existing input is specified, associates it with the recipe; fails if that input is already associated with a different recipe. Use disassociate_recipe_as_input to remove an existing association first. Returns the input ID and whether a modification was made.

Parameters:

  • recipe_key (IdentifierKey) – Identifier for the recipe

  • input_key (IdentifierKey | None) – Identifier for an input to use for the association. Optionally supplied. If not supplied, one is created

  • show_in_listings (bool | None) – After associating the input should it be present in listings

  • depends_on (list[str] | None) – A list of batch reference keys to process before processing this request

  • _request_options (RequestOptions | None)

Return type:

QueuedAsyncBatchRequest

associate_recipe_as_lot(*, recipe_key, ingredient_key, depends_on=None, _request_options=None)

Creates a lot association between a recipe and an ingredient. The recipe becomes a lot for the specified ingredient. Returns whether a modification was made.

Parameters:

  • recipe_key (IdentifierKey) – Identifier for the recipe

  • ingredient_key (IdentifierKey) – Identifier for the ingredient

  • depends_on (list[str] | None) – A list of batch reference keys to process before processing this request

  • _request_options (RequestOptions | None)

Return type:

QueuedAsyncBatchRequest

clear_recipe_outputs(*, recipe_key, depends_on=None, _request_options=None)

Clears all output values and output metadata for a given recipe identified by key. Returns whether a modification was made.

Parameters:

  • recipe_key (IdentifierKey) – The identifier of the recipe

  • depends_on (list[str] | None) – A list of batch reference keys to process before processing this request

  • _request_options (RequestOptions | None)

Return type:

QueuedAsyncBatchRequest

complete_async_parse(*, async_job_key, upload_destination, parsed_file_data=None, file_id=None, depends_on=None, _request_options=None)

Completes the asynchronous parsing step of a file upload workflow. Accepts either inline parsed_file_data or a file_id referencing a JSON file containing the parsed data (exactly one must be provided). Resolves the async job by its identifier key and applies the parsed data to the upload destination. Updates the async job status to COMPLETED upon success. Supports async batch execution.

Parameters:

  • parsed_file_data (list[ParsedFileData] | None) – Inline parsed data. Provide either parsed_file_data or file_id, not both.

  • file_id (ObjectId | None) – File ID containing parsed data. Provide either file_id or parsed_file_data, not both.

  • depends_on (list[str] | None) – A list of batch reference keys to process before processing this request

  • async_job_key (IdentifierKey)

  • upload_destination (UploadDestinationRecipe)

  • _request_options (RequestOptions | None)

Return type:

QueuedAsyncBatchRequest

complete_async_upload(*, async_job_id, file_id, depends_on=None, _request_options=None)

Completes an asynchronous runsheet export by processing an uploaded file and placing it in the job owner’s export downloads folder. Sends an export-complete notification to the job owner on completion. Supports async batch execution.

Parameters:

  • depends_on (list[str] | None) – A list of batch reference keys to process before processing this request

  • async_job_id (ObjectId)

  • file_id (ObjectId)

  • _request_options (RequestOptions | None)

Return type:

QueuedAsyncBatchRequest

create_mix_order(*, recipe_key, recipe_workflow_step_identifier, depends_on=None, _request_options=None)

Creates a mix order on a recipe workflow step. The recipe and workflow step are identified by their respective keys. Returns whether a modification was made.

Parameters:
Return type:

QueuedAsyncBatchRequest

create_or_update_entity(*, entity_type, definition_key, field_values, entity_key=None, on_create_init_field_values=None, depends_on=None, _request_options=None)

Creates a new entity or updates an existing one. If the entity already exists, updates its field values. Otherwise, creates a new entity under the specified definition. Returns the entity ID and whether a modification was made.

Parameters:

  • on_create_init_field_values (list[FieldArgumentValue] | None) – Field values set only when the entity is created (will be ignored if entity already exists)

  • depends_on (list[str] | None) – A list of batch reference keys to process before processing this request

  • entity_type (EntityType)

  • definition_key (IdentifierKey)

  • field_values (list[FieldArgumentValue])

  • entity_key (IdentifierKey | None)

  • _request_options (RequestOptions | None)

Return type:

QueuedAsyncBatchRequest

create_recipe(*, material_family_id, workflow_id, name=None, project_id=None, workflow_variant_id=None, recipe_metadata=None, identifiers=None, definition_key=None, recipe_key=None, depends_on=None, _request_options=None)

Creates a single recipe in the specified material family and workflow. If a matching recipe already exists, no new recipe is created and the existing recipe ID is returned. Returns the recipe ID.

Parameters:

  • name (str | None) – The name for the recipe

  • material_family_id (ObjectId) – The material family for the recipe

  • project_id (ObjectId | None) – The identifier of the project to create the recipe in

  • workflow_id (ObjectId) – The identifier of the workflow to create the recipe with

  • workflow_variant_id (ObjectId | None) – The identifier of the workflow variant to create the recipe with

  • recipe_metadata (list[MetadataValue] | None) – Metadata values to populate the recipe with

  • identifiers (RecipeIdentifiers | None) – [DEPRECATED] - use recipeKey. A recipe won’t be created if it matches the identifier. An identifier must be unique in the schema. An error will be raised if an argument is provided to both recipeKey and identifiers properties.

  • definition_key (IdentifierKey | None) – The entity definition identifier, default is used if not supplied

  • recipe_key (IdentifierKey | None) – If this identifier matches an existing recipe, the id of the existing recipe will be returned and no update will occur. Use the lookup_entity endpoint to match an existing recipe based on a set of field values.

  • depends_on (list[str] | None) – A list of batch reference keys to process before processing this request

  • _request_options (RequestOptions | None)

Return type:

QueuedAsyncBatchRequest

current_queue_size()
Return type:

int

edit_recipe_inputs(*, recipe_key, recipe_workflow_step_identifier, edits, depends_on=None, _request_options=None)

Applies a list of edits to inputs on a specific recipe workflow step. Supported edit types include clearing all inputs, upserting or adding inputs, updating annotations, setting lots, setting propagated percentages, changing basis, adding instructions, setting roles, and managing placeholders.

Parameters:
Return type:

QueuedAsyncBatchRequest

external_lock_entity(*, entity_key, entity_type, globally_removable=None, depends_on=None, _request_options=None)

Locks an entity to prevent modifications. Recipe entity types are not supported and must use the dedicated lock_recipes endpoint instead. Attempting to lock an already locked entity is a no-op.

Parameters:

  • entity_key (IdentifierKey) – Identifier for the entity

  • globally_removable (bool | None) – Should the lock be removable by any user or just admins

  • depends_on (list[str] | None) – A list of batch reference keys to process before processing this request

  • entity_type (EntityType)

  • _request_options (RequestOptions | None)

Return type:

QueuedAsyncBatchRequest

external_unlock_entity(*, entity_key, entity_type, depends_on=None, _request_options=None)

Removes the lock from an entity, allowing modifications again. Recipe entity types are not supported and must use the dedicated unlock_recipes endpoint instead. Attempting to unlock an already unlocked entity is a no-op.

Parameters:

  • entity_key (IdentifierKey) – Identifier for the entity

  • depends_on (list[str] | None) – A list of batch reference keys to process before processing this request

  • entity_type (EntityType)

  • _request_options (RequestOptions | None)

Return type:

QueuedAsyncBatchRequest

get_submitted_job_ids()
Return type:

list[ObjectId]

grant_entity_permissions(*, entity_type, entity_key, permission_types, user_keys=None, user_group_keys=None, all_users=None, depends_on=None, _request_options=None)

Grants permissions on an entity. Only permissions that do not already exist are added. Returns whether any new permissions were granted.

Parameters:
Return type:

QueuedAsyncBatchRequest

invoke_uploader(*, uploader_key, destination, file_id=None, file_ids=None, depends_on=None, _request_options=None)

Processes one or more uploaded files through a configured uploader, parsing and writing the extracted data to a recipe destination. Resolves the uploader by its identifier key and requires READ_ALL permission on the uploader entity. The file_ids parameter is preferred; file_id is deprecated. Non-SDK users should use file_upload/external_create_file_record to upload files first. SDK users can use the client.upload_files() helper method. Supports async batch execution.

Parameters:
Return type:

QueuedAsyncBatchRequest

lock_recipes(*, type=lock_recipes_t.RecipeLockType.ALL, recipes, globally_removable, lock_samples=None, comments=None, depends_on=None, _request_options=None)

Locks experiments to prevent editing. Supports locking all data (inputs and measurements) or inputs only. Returns whether a modification was made.

param type:

The type of lock to set.

All = both inputs and measurements are locked. Inputs Only = only inputs are locked from editing.

param recipes:

The recipes to lock, a maximum of 100 can be sent

param globally_removable:

If true any user can unlock the experiment. If false the locking user is the only user that can unlock.

param lock_samples:

Should associated experiment test samples also be locked.

param comments:

Optional comment describing the purpose of locking

param depends_on:

A list of batch reference keys to process before processing this request

Parameters:
Return type:

QueuedAsyncBatchRequest

lookup_entity(*, entity_type, query, depends_on=None, _request_options=None)

Looks up an entity by matching field values. Only text and ID field types are supported for matching. Returns the matched entity ID, or null if no match is found. Fails if multiple entities match. Excludes archived entities from results.

Parameters:
Return type:

QueuedAsyncBatchRequest

push_notification(*, notification_targets, subject, message, display_notice=False, entity=None, notice_configuration=None, depends_on=None, _request_options=None)

Send a notification to one or more users or user groups. Supports specifying a subject, message body, and optional entity link. Can optionally display as an in-app notice with custom configuration. Supports both direct invocation and async batch execution.

Parameters:
Return type:

QueuedAsyncBatchRequest

run_trigger(*, trigger_ref_name, entity_identifier=None, entity=None, depends_on=None, _request_options=None)

Executes a trigger script identified by ref name, optionally on a specific entity, and returns only after the trigger has fully completed. Requires admin user access; non-admin users receive a 403 error. Accepts either entity_identifier (preferred) or entity (deprecated) to specify the target entity, but not both. Returns whether any entities were modified by the trigger execution.

Parameters:

  • entity_identifier (EntityIdentifier | None) – Identifier of the entity to run the trigger on.

  • entity (Entity | None) – [Deprecated: use entity_identifier] Entity to run the trigger on.

  • depends_on (list[str] | None) – A list of batch reference keys to process before processing this request

  • trigger_ref_name (str)

  • _request_options (RequestOptions | None)

Return type:

QueuedAsyncBatchRequest

send()
Return type:

ObjectId

set_barcode(*, entity_key, barcode_value, depends_on=None, _request_options=None)

Sets the barcode value for an entity. Returns whether the new barcode value was set.

Parameters:

  • depends_on (list[str] | None) – A list of batch reference keys to process before processing this request

  • entity_key (EntityIdentifier)

  • barcode_value (str)

  • _request_options (RequestOptions | None)

Return type:

QueuedAsyncBatchRequest

set_entity_field_values(*, entity_identifier, field_values, depends_on=None, _request_options=None)

Sets field values on an entity. Returns whether the field values were modified.

Parameters:

  • entity_identifier (EntityIdentifier) – Entity to update

  • field_values (list[FieldArgumentValue]) – Field values to set

  • depends_on (list[str] | None) – A list of batch reference keys to process before processing this request

  • _request_options (RequestOptions | None)

Return type:

QueuedAsyncBatchRequest

set_recipe_metadata(*, recipe_key, recipe_metadata, depends_on=None, _request_options=None)

Sets metadata values on a recipe identified by key. Accepts a list of metadata field-value pairs to populate on the recipe. Fails if any of the metadata fields are read-only.

Parameters:

  • recipe_key (IdentifierKey) – Identifier for the recipe

  • recipe_metadata (list[MetadataValue]) – Metadata values to populate the recipe with

  • depends_on (list[str] | None) – A list of batch reference keys to process before processing this request

  • _request_options (RequestOptions | None)

Return type:

QueuedAsyncBatchRequest

swap_output_condition_parameters(*, scope, output_key, new_condition, old_condition_key=None, depends_on=None, _request_options=None)

Swap output condition parameters on recipes. Either specify recipe keys for targeted swaps or set swap_all to swap across all recipes in the project.

Parameters:

  • scope (SwapScope) – Which recipes to apply the swap to. See SwapScope variants for options.

  • output_key (IdentifierKey) – Identifier for the output on which to swap conditions.

  • old_condition_key (IdentifierKey | None) – Identifier for the old condition to replace. If omitted, recipes without a condition on the output are targeted.

  • new_condition (NewOutputCondition) – The new output condition to swap to. See NewOutputCondition variants for options.

  • depends_on (list[str] | None) – A list of batch reference keys to process before processing this request

  • _request_options (RequestOptions | None)

Return type:

QueuedAsyncBatchRequest

transition_entity_phase(*, transition, entity=None, entity_identifier=None, depends_on=None, _request_options=None)

Transitions an entity from one workflow phase to another. Fails if no valid transition exists between the specified phases, or if multiple transitions exist for the same phase pair.

Parameters:

  • entity (Entity | None) – Entity to transition. If entity_identifier is provided, this should be omitted.

  • entity_identifier (EntityIdentifier | None) – Identifier of the entity to transition. If entity is provided, this should be omitted.

  • transition (TransitionIdentifier) – Identifier of the transition to perform

  • depends_on (list[str] | None) – A list of batch reference keys to process before processing this request

  • _request_options (RequestOptions | None)

Return type:

QueuedAsyncBatchRequest

unlock_recipes(*, type=unlock_recipes_t.RecipeUnlockType.STANDARD, recipes, unlock_samples=None, depends_on=None, _request_options=None)

Unlocks previously locked experiments, making them editable again. Returns whether a modification was made.

Parameters:

  • type (RecipeUnlockType) – The method to unlock recipes. Default is standard.

  • recipes (list[IdentifierKey]) – The recipes to unlock, a maximum of 100 can be sent

  • unlock_samples (bool | None) – Should associated experiment test samples also be unlocked.

  • depends_on (list[str] | None) – A list of batch reference keys to process before processing this request

  • _request_options (RequestOptions | None)

Return type:

QueuedAsyncBatchRequest

upsert_condition_match(*, explicit_name=False, name=None, condition_parameters=None, output_conditions=None, existing_condition_match=None, depends_on=None, _request_options=None)

Creates or updates a condition match record. Condition matches are used to set goals on outputs. Each call creates a new condition match — there is no idempotent behavior, so the same inputs will produce a new condition match with each invocation. Returns modification_made and result_id of the created or updated condition match.

Parameters:

  • depends_on (list[str] | None) – A list of batch reference keys to process before processing this request

  • explicit_name (bool)

  • name (str | None)

  • condition_parameters (list[ConditionParameter] | None)

  • output_conditions (list[IdentifierKey] | None)

  • existing_condition_match (IdentifierKey | None)

  • _request_options (RequestOptions | None)

Return type:

QueuedAsyncBatchRequest

upsert_recipe_workflow_step(*, recipe_key, data_source, location, recipe_workflow_step_key=None, depends_on=None, _request_options=None)

Create or update a recipe workflow step on a recipe

Parameters:
Return type:

QueuedAsyncBatchRequest

upsert_step_relationships(*, recipe_key, edits, depends_on=None, _request_options=None)

Upsert step relationships on a recipe

Parameters:
Return type:

QueuedAsyncBatchRequest