eng: Added docs for canvas code

examples/chem-sync-local-flask/local_app/benchling_app/canvas_interaction.py

@@ -28,16 +28,30 @@
 class UnsupportedButtonError(Exception):
     pass
 
+"""
+This file contains examples of how to handle a user clicking a button on a canvas
+For examples of initialization, check out canvas_initialize.py
+"""
 
 def route_interaction_webhook(app: App, canvas_interaction: CanvasInteractionWebhookV2) -> None:
     canvas_id = canvas_interaction.canvas_id
+
+    # Access the different actions by checking which button was clicked
     if canvas_interaction.button_id == SEARCH_BUTTON_ID:
         with app.create_session_context("Search Chemicals", timeout_seconds=20) as session:
             session.attach_canvas(canvas_id)
+
+            # Use a CanvasBuilder to update an existing canvas 
             canvas_builder = _canvas_builder_from_canvas_id(app, canvas_id)
             canvas_inputs = canvas_builder.inputs_to_dict_single_value()
+
+            # Validate and sanitize the user's search input
             sanitized_inputs = _validate_and_sanitize_inputs(canvas_inputs)
+
+            # Search for the chemical
             results = search(sanitized_inputs[SEARCH_TEXT_ID])
+
+            # Render the preview canvas
             render_preview_canvas(results, canvas_id, canvas_builder, session)
     elif canvas_interaction.button_id == CANCEL_BUTTON_ID:
         # Set session_id = None to detach and prior state or messages (essentially, reset)
@@ -46,12 +60,17 @@ def route_interaction_webhook(app: App, canvas_interaction: CanvasInteractionWeb
             .with_session_id(None)\
             .with_blocks(input_blocks())\
             .to_update()
+
+        # Update the canvas
         app.benchling.apps.update_canvas(canvas_id, canvas_update)
     elif canvas_interaction.button_id == CREATE_BUTTON_ID:
         with app.create_session_context("Create Molecules", timeout_seconds=20) as session:
             session.attach_canvas(canvas_id)
+
+            # Use a CanvasBuilder to create a new molecule
             canvas_builder = _canvas_builder_from_canvas_id(app, canvas_id)
             molecule = _create_molecule_from_canvas(app, canvas_builder)
+
             render_completed_canvas(molecule, canvas_id, canvas_builder, session)
     else:
         # Re-enable the Canvas, or it will stay disabled and the user will be stuck

examples/chem-sync-local-flask/local_app/benchling_app/handler.py

@@ -25,17 +25,25 @@ class UnsupportedWebhookError(Exception):
 
 def handle_webhook(webhook_dict: dict[str, Any]) -> None:
     logger.debug("Handling webhook with payload: %s", webhook_dict)
+
+    # Receive the webhook and initialize the app
     webhook = WebhookEnvelopeV0.from_dict(webhook_dict)
     app = init_app_from_webhook(webhook)
+
+    # Route the webhook to the appropriate handler
     # Could also choose to route on webhook.message.type
+
     # Note: if your manifest specifies more than one item in `features`,
     # then `webhook.message.feature_id` may also need to be part of your routing logic
     try:
         if isinstance(webhook.message, CanvasInitializeWebhookV2):
+            # This webhook is triggered when a canvas is initialized as a part of a run
             render_search_canvas(app, webhook.message)
         elif isinstance(webhook.message, CanvasInteractionWebhookV2):
+            # This webhook is triggered when a user clicks a button on the canvas
             route_interaction_webhook(app, webhook.message)
         elif isinstance(webhook.message, CanvasCreatedWebhookV2Beta):
+            # This webhook is triggered when a canvas is created in an entry
             render_search_canvas_for_created_canvas(app, webhook.message)
         else:
             # Should only happen if the app's manifest requests webhooks that aren't handled in its code paths

examples/chem-sync-local-flask/local_app/benchling_app/views/canvas_initialize.py

@@ -16,6 +16,17 @@
 
 from local_app.benchling_app.views.constants import SEARCH_BUTTON_ID, SEARCH_TEXT_ID
 
+"""
+This file contains examples of how create a canvas at initialization
+For examples of updates, check out canvas_interaction.py
+
+Use a CanvasBuilder to create or update a canvas associated with your app 
+This sdk tool can be used for easy creation and updates
+
+Check out https://benchling.com/sdk-docs/1.22.0/benchling_sdk.apps.canvas.framework.html
+for more details on the CanvasBuilder class
+"""
+
 
 def render_search_canvas(app: App, canvas_initialized: CanvasInitializeWebhookV2) -> None:
     with app.create_session_context("Show Sync Search", timeout_seconds=20):
@@ -24,7 +35,11 @@ def render_search_canvas(app: App, canvas_initialized: CanvasInitializeWebhookV2
             feature_id=canvas_initialized.feature_id,
             resource_id=canvas_initialized.resource_id,
         )
+
+        # Add the input blocks to the canvas 
         canvas_builder.blocks.append(input_blocks())
+
+        # Create the canvas
         app.benchling.apps.create_canvas(canvas_builder.to_create())
 
 
@@ -36,6 +51,13 @@ def render_search_canvas_for_created_canvas(app: App, canvas_created: CanvasCrea
 
 
 def input_blocks() -> list[UiBlock]:
+    """
+    Create 3 blocks to populate the canvas: 
+
+    Markdown block to display text 
+    TextInput block to capture user input 
+    Button block to trigger the search 
+    """
     return [
         MarkdownUiBlock(
             id="top_instructions",