benchling_sdk.apps.canvas.framework module

class CanvasBuilder

Bases: object

Canvas Builder.

This class provides methods to help developers effectively work with Canvas UI Blocks. Working with the underlying API models directly can be clunky, as there is no native way to easily find blocks based on their attributes, and then operate on them. Some blocks, like SectionUiBlock, have nested children blocks, further complicating the unassisted experience.

The goal of CanvasBuilder is to accept an existing Canvas, and easily change its contents (blocks), then send a resulting AppCanvasCreate or AppCanvasUpdate model to the API.

Some block operations include:

• Get by Id

• Filtering by predicate

• Remove

• Replace

• Insert After

• Insert Before

• Append

Sample usage:

``` canvas: Canvas = benchling.apps.get_canvas_by_id(“canvas_id”) builder = CanvasBuilder.from_canvas(canvas).blocks

.filter(lambda block: isinstance(block, TextInputUiBlock)) .remove()

updated_canvas = benchling.apps.update_canvas(“canvas_id”, builder.to_update()) ```

__init__(app_id: str, feature_id: str, resource_id: Optional[str] = None, enabled: bool = True, session_id: Optional[str] = None, blocks: Optional[List[Union[ButtonUiBlock, ChipUiBlock, DropdownMultiValueUiBlock, DropdownUiBlock, MarkdownUiBlock, SearchInputMultiValueUiBlock, SearchInputUiBlock, SectionUiBlock, SelectorInputMultiValueUiBlock, SelectorInputUiBlock, TableUiBlock, TextInputUiBlock, benchling_api_client.v2.extensions.UnknownType]]] = None, data: Optional[Union[Dict[str, Any], List[Any], str, int, float, bool]] = None)

Init AppCanvas.

Create a CanvasBuilder from scratch. Useful when a source AppCanvas is not already created.

property blocks: CanvasBuilderBlockStream

Blocks.

Return a stream of blocks which can be iterated and operated on to mutate the canvas stored by the builder.

data_to_json() → Optional[Union[Dict[str, Any], List[Any], str, int, float, bool]]

Convert Canvas data to JSON.

Return a JSON object parsed from the string of the canvas’s data, if present. Otherwise, return None.

classmethod from_canvas(canvas: AppCanvas) → CanvasBuilder

From Canvas.

Create a CanvasBuilder from an existing canvas. Preferred when a canvas already exists.

inputs_to_dict() → Dict[str, Union[str, List[str]]]

Read Inputs to dict.

Return a dictionary of {block_id: block_value} for all blocks on the canvas with input values. Includes blocks with a value that can be a str or multivalued. Excludes TableUiBlock. Blocks that only have read attributes are omitted.

List of included blocks:

DropdownMultiValueUiBlock DropdownUiBlock SearchInputMultiValueUiBlock SearchInputUiBlock SelectorInputMultiValueUiBlock SelectorInputUiBlock TextInputUiBlock

Raise DuplicateBlockIdError if multiple blocks with the same id are found.

inputs_to_dict_multi_value() → Dict[str, List[str]]

Read Inputs to dict, but only for multivalued blocks.

Return a dictionary of {block_id: block_value} for all blocks on the canvas with multivalued input values. Blocks that only have read attributes are omitted. Excludes TableUiBlock.

List of included blocks:

DropdownMultiValueUiBlock SearchInputMultiValueUiBlock SelectorInputMultiValueUiBlock

Raise DuplicateBlockIdError if multiple blocks with the same id are found.

inputs_to_dict_single_value() → Dict[str, str]

Read Inputs to dict, but only for single-valued blocks.

Return a dictionary of {block_id: block_value} for all blocks on the canvas with single input values. Blocks that only have read attributes are omitted. Excludes TableUiBlock.

List of included blocks:

DropdownUiBlock SearchInputUiBlock SelectorInputUiBlock TextInputUiBlock

Raise DuplicateBlockIdError if multiple blocks with the same id are found.

property resource_id

Returns the underlying resource_id of this CanvasBuilder.

to_create() → AppCanvasCreate

Return an AppCanvasCreate API model from the current state of the canvas managed by CanvasBuilder.

Raise MissingResourceIdError if the current state of the canvas managed by CanvasBuilder does not include a resource ID. Without a resource ID indicating the Benchling object on which to place the new canvas, canvas creation is underspecified and cannot be completed successfully.

to_update() → AppCanvasUpdate

Return an AppCanvasUpdate API model from the current state of the canvas managed by CanvasBuilder.

with_blocks(new_blocks: List[Union[ButtonUiBlock, ChipUiBlock, DropdownMultiValueUiBlock, DropdownUiBlock, MarkdownUiBlock, SearchInputMultiValueUiBlock, SearchInputUiBlock, SectionUiBlock, SelectorInputMultiValueUiBlock, SelectorInputUiBlock, TableUiBlock, TextInputUiBlock, benchling_api_client.v2.extensions.UnknownType]]) → CanvasBuilder

Return a new CanvasBuilder with the underlying blocks replaced.

This does not call the API, it only assigns state in the CanvasBuilder.

with_data(new_data: Optional[Union[Dict[str, Any], List[Any], str, int, float, bool]]) → CanvasBuilder

Return a new CanvasBuilder with the underlying data replaced.

This does not call the API, it only assigns state in the CanvasBuilder.

with_enabled(enabled: bool = True) → CanvasBuilder

Return a new CanvasBuilder with the underlying canvas enabled set to the specified value.

Specify False to disable the canvas. This does not call the API, it only assigns state in the CanvasBuilder.

with_session_id(session_id: Optional[str]) → CanvasBuilder

Return a new CanvasBuilder with an optional session_id set.

This does not call the API, it only assigns state in the CanvasBuilder.

class CanvasBuilderBlockStream

Bases: benchling_sdk.apps.canvas.framework.FilteredCanvasBuilderBlockStream

Internal UI block list wrapper for CanvasBuilder.

Possesses some additional operations unavailable to filtered block streams.

__init__(builder: CanvasBuilder, blocks: List[CanvasBuilderUiBlock], selected_blocks: List[CanvasBuilderUiBlock], parent: Optional[CanvasBuilderUiBlock] = None)

Init CanvasBuilderBlockStream.

append(new_blocks: List[Union[ButtonUiBlock, ChipUiBlock, DropdownMultiValueUiBlock, DropdownUiBlock, MarkdownUiBlock, SearchInputMultiValueUiBlock, SearchInputUiBlock, SectionUiBlock, SelectorInputMultiValueUiBlock, SelectorInputUiBlock, TableUiBlock, TextInputUiBlock, benchling_api_client.v2.extensions.UnknownType]]) → None

Append new_blocks to the end of list of blocks.

Only operates on unfiltered block streams. This can be a list of blocks on a Canvas, or children on a block such as SectionUiBlock.

class CanvasBuilderFilter

Bases: Protocol

Callable protocol for specifying a predicate for filtering UiBlocks.

__init__(*args, **kwargs)

class CanvasBuilderUiBlock

Bases: Generic[benchling_sdk.apps.canvas.types.UiBlockType]

Internal UI block wrapper for CanvasBuilder.

__init__(block: benchling_sdk.apps.canvas.types.UiBlockType, builder: CanvasBuilder)

Init CanvasBuilderUiBlock.

children() → CanvasBuilderBlockStream

Return children for blocks when applicable, such as for section blocks.

If not applicable, returns an empty canvas block stream with no blocks.

classmethod from_api_model(block: benchling_sdk.apps.canvas.types.UiBlockType, builder: CanvasBuilder) → CanvasBuilderUiBlock[benchling_sdk.apps.canvas.types.UiBlockType]

Create a _CanvasBuilderUiBlock from an underlying API model.

insert_after(new_blocks: List[Union[ButtonUiBlock, ChipUiBlock, DropdownMultiValueUiBlock, DropdownUiBlock, MarkdownUiBlock, SearchInputMultiValueUiBlock, SearchInputUiBlock, SectionUiBlock, SelectorInputMultiValueUiBlock, SelectorInputUiBlock, TableUiBlock, TextInputUiBlock, benchling_api_client.v2.extensions.UnknownType]]) → None

Insert new_blocks after block.

insert_before(new_blocks: List[Union[ButtonUiBlock, ChipUiBlock, DropdownMultiValueUiBlock, DropdownUiBlock, MarkdownUiBlock, SearchInputMultiValueUiBlock, SearchInputUiBlock, SectionUiBlock, SelectorInputMultiValueUiBlock, SelectorInputUiBlock, TableUiBlock, TextInputUiBlock, benchling_api_client.v2.extensions.UnknownType]]) → None

Insert new_blocks before block.

remove() → None

Remove block.

replace(new_blocks: List[Union[ButtonUiBlock, ChipUiBlock, DropdownMultiValueUiBlock, DropdownUiBlock, MarkdownUiBlock, SearchInputMultiValueUiBlock, SearchInputUiBlock, SectionUiBlock, SelectorInputMultiValueUiBlock, SelectorInputUiBlock, TableUiBlock, TextInputUiBlock, benchling_api_client.v2.extensions.UnknownType]]) → None

Replace block with provided new_blocks.

to_api_model() → benchling_sdk.apps.canvas.types.UiBlockType

Convert to the underlying API model.

class FilteredCanvasBuilderBlockStream

Bases: object

Filtered UI block list wrapper for CanvasBuilder.

__init__(builder: CanvasBuilder, blocks: List[CanvasBuilderUiBlock], selected_blocks: List[CanvasBuilderUiBlock])

Init FilteredCanvasBuilderBlockStream.

count() → int

Return a count of the elements in the list of blocks.

filter(filter_function: CanvasBuilderFilter) → FilteredCanvasBuilderBlockStream

Filter.

Accept a predicate that evaluates if a UiBlock should be included in the result or not. Returns a new stream of blocks filtered to the predicate, which is further operable.

first() → CanvasBuilderUiBlock

Return the first block in the list.

classmethod from_builder(builder: CanvasBuilder) → benchling_sdk.apps.canvas.framework.S

From Builder.

Instantiate a new _FilteredCanvasBuilderBlockStream from a CanvasBuilder.

get_by_id(block_id: str) → CanvasBuilderUiBlock

Get a block by its id.

Raises NoMatchingBlocksError if the block is not found. To match an id as an optional, use filter().

last() → CanvasBuilderUiBlock

Return the last block in the list.

remove() → None

Remove blocks.