opentrons 8.7.0a9__py3-none-any.whl → 8.8.0a8__py3-none-any.whl

opentrons/protocol_engine/resources/file_provider.py

@@ -1,36 +1,91 @@
 """File interaction resource provider."""
 from datetime import datetime
+from io import StringIO
+import csv
 from typing import List, Optional, Callable, Awaitable, Dict
+from dataclasses import dataclass
 from pydantic import BaseModel
-from ..errors import StorageLimitReachedError
+from opentrons_shared_data.data_files import (
+    DataFileInfo,
+    MimeType,
+    RunFileNameMetadata,
+)
+
+SPECIAL_CHARACTERS = {
+    "#",
+    "%",
+    "&",
+    "{",
+    "}",
+    "\\",
+    "/",
+    "<",
+    ">",
+    "*",
+    "$",
+    "!",
+    "?",
+    ".",
+    "'",
+    '"',
+    ":",
+    ";",
+    "@",
+    "`",
+    "|",
+}
+
+
+@dataclass(frozen=True)
+class FileNameCmdMetadata:
+    """Command metadata associated with a specific data file."""
+
+    command_id: str
+    prev_command_id: str
+
+
+@dataclass(frozen=True)
+class ReadCmdFileNameMetadata(FileNameCmdMetadata):
+    """Data from a plate reader `read` command used to build the finalized file name."""
+
+    base_filename: str
+    wavelength: int
+
+
+@dataclass(frozen=True)
+class ImageCaptureCmdFileNameMetadata(FileNameCmdMetadata):
+    """Data from a camera capture command used to build the finalized file name."""
 
+    step_number: int
+    command_timestamp: datetime
+    base_filename: Optional[str]
 
-MAXIMUM_CSV_FILE_LIMIT = 400
 
+CommandFileNameMetadata = ReadCmdFileNameMetadata | ImageCaptureCmdFileNameMetadata
 
-class GenericCsvTransform:
-    """Generic CSV File Type data for rows of data to be seperated by a delimeter."""
 
-    filename: str
-    rows: List[List[str]]
-    delimiter: str = ","
+class FileData:
+    """File data container for writing to a file."""
+
+    data: bytes
+    mime_type: MimeType
+    run_metadata: RunFileNameMetadata
+    command_metadata: CommandFileNameMetadata
 
     @staticmethod
     def build(
-        filename: str, rows: List[List[str]], delimiter: str = ","
-    ) -> "GenericCsvTransform":
-        """Build a Generic CSV datatype class."""
-        if "." in filename and not filename.endswith(".csv"):
-            raise ValueError(
-                f"Provided filename {filename} invalid. Only CSV file format is accepted."
-            )
-        elif "." not in filename:
-            filename = f"{filename}.csv"
-        csv = GenericCsvTransform()
-        csv.filename = filename
-        csv.rows = rows
-        csv.delimiter = delimiter
-        return csv
+        data: bytes,
+        mime_type: MimeType,
+        run_metadata: RunFileNameMetadata,
+        command_metadata: CommandFileNameMetadata,
+    ) -> "FileData":
+        """Build a generic file data class."""
+        file_data = FileData()
+        file_data.data = data
+        file_data.mime_type = mime_type
+        file_data.run_metadata = run_metadata
+        file_data.command_metadata = command_metadata
+        return file_data
 
 
 class ReadData(BaseModel):
@@ -41,7 +96,7 @@ class ReadData(BaseModel):
 
 
 class PlateReaderData(BaseModel):
-    """Data from a Opentrons Plate Reader Read. Can be converted to CSV template format."""
+    """Data from an Opentrons Plate Reader Read. Can be converted to CSV format."""
 
     read_results: List[ReadData]
     reference_wavelength: Optional[int] = None
@@ -49,13 +104,8 @@ class PlateReaderData(BaseModel):
     finish_time: datetime
     serial_number: str
 
-    def build_generic_csv(  # noqa: C901
-        self, filename: str, measurement: ReadData
-    ) -> GenericCsvTransform:
-        """Builds a CSV compatible object containing Plate Reader Measurements.
-
-        This will also automatically reformat the provided filename to include the wavelength of those measurements.
-        """
+    def build_csv_bytes(self, measurement: ReadData) -> bytes:  # noqa: C901
+        """Builds CSV data as bytes containing Plate Reader Measurements."""
         plate_alpharows = ["A", "B", "C", "D", "E", "F", "G", "H"]
         rows = []
 
@@ -63,7 +113,7 @@ class PlateReaderData(BaseModel):
         for i in range(8):
             row = [plate_alpharows[i]]
             for j in range(12):
-                row.append(str(measurement.data[f"{plate_alpharows[i]}{j+1}"]))
+                row.append(str(measurement.data[f"{plate_alpharows[i]}{j + 1}"]))
             rows.append(row)
         for i in range(3):
             rows.append([])
@@ -116,16 +166,12 @@ class PlateReaderData(BaseModel):
             ["Measurement finished at", self.finish_time.strftime("%m %d %H:%M:%S %Y")]
         )
 
-        # Ensure the filename adheres to ruleset contains the wavelength for a given measurement
-        if filename.endswith(".csv"):
-            filename = filename[:-4]
-        filename = filename + str(measurement.wavelength) + "nm.csv"
+        output = StringIO()
+        writer = csv.writer(output, delimiter=",")
+        writer.writerows(rows)
+        csv_bytes = output.getvalue().encode("utf-8")
 
-        return GenericCsvTransform.build(
-            filename=filename,
-            rows=rows,
-            delimiter=",",
-        )
+        return csv_bytes
 
 
 class FileProvider:
@@ -133,29 +179,58 @@ class FileProvider:
 
     def __init__(
         self,
-        data_files_write_csv_callback: Optional[
-            Callable[[GenericCsvTransform], Awaitable[str]]
+        data_files_write_file_cb: Optional[
+            Callable[[FileData], Awaitable[DataFileInfo]]
         ] = None,
-        data_files_filecount: Optional[Callable[[], Awaitable[int]]] = None,
     ) -> None:
         """Initialize the interface callbacks of the File Provider for data file handling within the Protocol Engine.
 
         Params:
-            data_files_write_csv_callback: Callback to write a CSV file to the data files directory and add it to the database.
+            data_files_write_file_callback: Callback to write a file to the data files directory and add it to the database.
             data_files_filecount: Callback to check the amount of data files already present in the data files directory.
         """
-        self._data_files_write_csv_callback = data_files_write_csv_callback
-        self._data_files_filecount = data_files_filecount
-
-    async def write_csv(self, write_data: GenericCsvTransform) -> str:
-        """Writes the provided CSV object to a file in the Data Files directory. Returns the File ID of the file created."""
-        if self._data_files_filecount is not None:
-            file_count = await self._data_files_filecount()
-            if file_count >= MAXIMUM_CSV_FILE_LIMIT:
-                raise StorageLimitReachedError(
-                    f"Not enough space to store file {write_data.filename}."
-                )
-            if self._data_files_write_csv_callback is not None:
-                return await self._data_files_write_csv_callback(write_data)
-        # If we are in an analysis or simulation state, return an empty file ID
-        return ""
+        self._data_files_write_file_cb = data_files_write_file_cb
+        self._run_metadata: RunFileNameMetadata | None = None
+
+    async def write_file(
+        self,
+        data: bytes,
+        mime_type: MimeType,
+        command_metadata: CommandFileNameMetadata,
+    ) -> DataFileInfo:
+        """Writes arbitrary data to a file in the Data Files directory.
+
+        Returns the `DataFileInfo` of the file created.
+
+        Raises:
+            Note that the callback may raise a StorageLimitReachedError.
+        """
+        if self._data_files_write_file_cb is not None:
+            assert self._run_metadata is not None
+            file_data = FileData.build(
+                data=data,
+                mime_type=mime_type,
+                command_metadata=command_metadata,
+                run_metadata=self._run_metadata,
+            )
+
+            return await self._data_files_write_file_cb(file_data)
+        # If we are in an analysis or simulation state, return an empty `DataFileInfo`
+        return DataFileInfo(
+            id="",
+            name="",
+            file_hash="",
+            created_at=datetime.now(),
+            generated=True,
+            stored=False,
+            path="",
+            mime_type=mime_type,
+        )
+
+    def set_run_metadata(self, metadata: RunFileNameMetadata) -> None:
+        """Sets metadata specific to the run."""
+        self._run_metadata = metadata
+
+    def clear_run_metadata(self) -> None:
+        """Clears metadata specific to the run."""
+        self._run_metadata = None

opentrons/protocol_engine/resources/labware_validation.py

@@ -2,6 +2,7 @@
 
 from opentrons_shared_data.labware.labware_definition import (
     LabwareDefinition,
+    LabwareDefinition2,
     LabwareRole,
 )
 
@@ -44,15 +45,18 @@ def validate_definition_is_system(definition: LabwareDefinition) -> bool:
     return LabwareRole.system in definition.allowedRoles
 
 
-def validate_labware_can_be_stacked(
-    top_labware_definition: LabwareDefinition, below_labware_load_name: str
+def validate_legacy_labware_can_be_stacked(
+    child_labware_definition: LabwareDefinition2, parent_labware_load_name: str
 ) -> bool:
-    """Validate that the labware being loaded onto is in the above labware's stackingOffsetWithLabware definition."""
+    """Validate that the parent labware is in the child labware's stackingOffsetWithLabware definition.
+
+    Schema 3 Labware stacking validation is handled in locating features.
+    """
     return (
-        below_labware_load_name in top_labware_definition.stackingOffsetWithLabware
+        parent_labware_load_name in child_labware_definition.stackingOffsetWithLabware
         or (
-            "default" in top_labware_definition.stackingOffsetWithLabware
-            and top_labware_definition.compatibleParentLabware is None
+            "default" in child_labware_definition.stackingOffsetWithLabware
+            and child_labware_definition.compatibleParentLabware is None
         )
     )
 

opentrons/protocol_engine/slot_standardization.py

@@ -27,6 +27,7 @@ from .types import (
     AddressableAreaLocation,
     ModuleLocation,
     OnLabwareLocation,
+    WASTE_CHUTE_LOCATION,
 )
 
 
@@ -116,6 +117,7 @@ def _standardize_labware_location(
         )
         or original == OFF_DECK_LOCATION
         or original == SYSTEM_LOCATION
+        or original == WASTE_CHUTE_LOCATION
     ):
         return original
 

opentrons/protocol_engine/state/_well_math.py

@@ -17,13 +17,47 @@ def wells_covered_by_pipette_configuration(
     """Compute the wells covered by a pipette nozzle configuration."""
     if len(labware_wells_by_column) >= 12 and len(labware_wells_by_column[0]) >= 8:
         yield from wells_covered_dense(
-            nozzle_map,
+            nozzle_map.columns,
+            nozzle_map.rows,
+            nozzle_map.starting_nozzle,
             target_well,
             labware_wells_by_column,
         )
     elif len(labware_wells_by_column) < 12 and len(labware_wells_by_column[0]) < 8:
         yield from wells_covered_sparse(
-            nozzle_map, target_well, labware_wells_by_column
+            nozzle_map.columns,
+            nozzle_map.rows,
+            nozzle_map.starting_nozzle,
+            target_well,
+            labware_wells_by_column,
+        )
+    else:
+        raise InvalidStoredData(
+            "Labware of non-SBS and non-reservoir format cannot be handled"
+        )
+
+
+def wells_covered_by_physical_pipette(
+    nozzle_map: NozzleMap,
+    target_well: str,
+    labware_wells_by_column: list[list[str]],
+) -> Iterator[str]:
+    """Compute the wells covered by a pipette nozzle configuration."""
+    if len(labware_wells_by_column) >= 12 and len(labware_wells_by_column[0]) >= 8:
+        yield from wells_covered_dense(
+            nozzle_map.full_instrument_columns,
+            nozzle_map.full_instrument_rows,
+            nozzle_map.starting_nozzle,
+            target_well,
+            labware_wells_by_column,
+        )
+    elif len(labware_wells_by_column) < 12 and len(labware_wells_by_column[0]) < 8:
+        yield from wells_covered_sparse(
+            nozzle_map.full_instrument_columns,
+            nozzle_map.full_instrument_rows,
+            nozzle_map.starting_nozzle,
+            target_well,
+            labware_wells_by_column,
         )
     else:
         raise InvalidStoredData(
@@ -42,7 +76,11 @@ def row_col_ordinals_from_column_major_map(
 
 
 def wells_covered_dense(  # noqa: C901
-    nozzle_map: NozzleMap, target_well: str, target_wells_by_column: list[list[str]]
+    columns: dict[str, list[str]],
+    rows: dict[str, list[str]],
+    starting_nozzle: str,
+    target_well: str,
+    target_wells_by_column: list[list[str]],
 ) -> Iterator[str]:
     """Get the list of wells covered by a nozzle map on an SBS format labware with a specified multiplier of 96 into the number of wells.
 
@@ -66,11 +104,11 @@ def wells_covered_dense(  # noqa: C901
             "This labware cannot be used with wells_covered_dense() because it is less dense than an SBS 96 standard"
         )
 
-    for nozzle_column in range(len(nozzle_map.columns)):
+    for nozzle_column in range(len(columns)):
         target_column_offset = nozzle_column * column_downsample
-        for nozzle_row in range(len(nozzle_map.rows)):
+        for nozzle_row in range(len(rows)):
             target_row_offset = nozzle_row * row_downsample
-            if nozzle_map.starting_nozzle == "A1":
+            if starting_nozzle == "A1":
                 if (
                     target_column_index + target_column_offset
                     < len(target_wells_by_column)
@@ -81,7 +119,7 @@ def wells_covered_dense(  # noqa: C901
                     yield target_wells_by_column[
                         target_column_index + target_column_offset
                     ][target_row_index + target_row_offset]
-            elif nozzle_map.starting_nozzle == "A12":
+            elif starting_nozzle == "A12":
                 if (target_column_index - target_column_offset >= 0) and (
                     target_row_index + target_row_offset
                     < len(target_wells_by_column[target_column_index])
@@ -89,7 +127,7 @@ def wells_covered_dense(  # noqa: C901
                     yield target_wells_by_column[
                         target_column_index - target_column_offset
                     ][target_row_index + target_row_offset]
-            elif nozzle_map.starting_nozzle == "H1":
+            elif starting_nozzle == "H1":
                 if (
                     target_column_index + target_column_offset
                     < len(target_wells_by_column)
@@ -97,7 +135,7 @@ def wells_covered_dense(  # noqa: C901
                     yield target_wells_by_column[
                         target_column_index + target_column_offset
                     ][target_row_index - target_row_offset]
-            elif nozzle_map.starting_nozzle == "H12":
+            elif starting_nozzle == "H12":
                 if (target_column_index - target_column_offset >= 0) and (
                     target_row_index - target_row_offset >= 0
                 ):
@@ -106,12 +144,16 @@ def wells_covered_dense(  # noqa: C901
                     ][target_row_index - target_row_offset]
             else:
                 raise InvalidProtocolData(
-                    f"A pipette nozzle configuration may not having a starting nozzle of {nozzle_map.starting_nozzle}"
+                    f"A pipette nozzle configuration may not having a starting nozzle of {starting_nozzle}"
                 )
 
 
 def wells_covered_sparse(  # noqa: C901
-    nozzle_map: NozzleMap, target_well: str, target_wells_by_column: list[list[str]]
+    columns: dict[str, list[str]],
+    rows: dict[str, list[str]],
+    starting_nozzle: str,
+    target_well: str,
+    target_wells_by_column: list[list[str]],
 ) -> Iterator[str]:
     """Get the list of wells covered by a nozzle map on a column-oriented reservoir.
 
@@ -128,9 +170,9 @@ def wells_covered_sparse(  # noqa: C901
         raise InvalidStoredData(
             "This labware cannot be used with wells_covered_sparse() because it is more dense than an SBS 96 standard."
         )
-    for nozzle_column in range(max(1, len(nozzle_map.columns) // column_upsample)):
-        for nozzle_row in range(max(1, len(nozzle_map.rows) // row_upsample)):
-            if nozzle_map.starting_nozzle == "A1":
+    for nozzle_column in range(max(1, len(columns) // column_upsample)):
+        for nozzle_row in range(max(1, len(rows) // row_upsample)):
+            if starting_nozzle == "A1":
                 if (
                     target_column_index + nozzle_column < len(target_wells_by_column)
                 ) and (
@@ -140,7 +182,7 @@ def wells_covered_sparse(  # noqa: C901
                     yield target_wells_by_column[target_column_index + nozzle_column][
                         target_row_index + nozzle_row
                     ]
-            elif nozzle_map.starting_nozzle == "A12":
+            elif starting_nozzle == "A12":
                 if (target_column_index - nozzle_column >= 0) and (
                     target_row_index + nozzle_row
                     < len(target_wells_by_column[target_column_index])
@@ -148,7 +190,7 @@ def wells_covered_sparse(  # noqa: C901
                     yield target_wells_by_column[target_column_index - nozzle_column][
                         target_row_index + nozzle_row
                     ]
-            elif nozzle_map.starting_nozzle == "H1":
+            elif starting_nozzle == "H1":
                 if (
                     target_column_index + nozzle_column
                     < len(target_wells_by_column[target_column_index])
@@ -156,7 +198,7 @@ def wells_covered_sparse(  # noqa: C901
                     yield target_wells_by_column[target_column_index + nozzle_column][
                         target_row_index - nozzle_row
                     ]
-            elif nozzle_map.starting_nozzle == "H12":
+            elif starting_nozzle == "H12":
                 if (target_column_index - nozzle_column >= 0) and (
                     target_row_index - nozzle_row >= 0
                 ):
@@ -165,7 +207,7 @@ def wells_covered_sparse(  # noqa: C901
                     ]
             else:
                 raise InvalidProtocolData(
-                    f"A pipette nozzle configuration may not having a starting nozzle of {nozzle_map.starting_nozzle}"
+                    f"A pipette nozzle configuration may not having a starting nozzle of {starting_nozzle}"
                 )
 
 

opentrons/protocol_engine/state/addressable_areas.py

@@ -5,6 +5,7 @@ from functools import cached_property
 from typing import Dict, List, Optional, Set
 
 from opentrons_shared_data.robot.types import RobotType, RobotDefinition
+from opentrons_shared_data.module.types import ModuleOrientation
 from opentrons_shared_data.deck.types import (
     DeckDefinitionV5,
     SlotDefV3,
@@ -614,6 +615,7 @@ class AddressableAreaView:
             "displayName": addressable_area.display_name,
             "compatibleModuleTypes": addressable_area.compatible_module_types,
             "features": addressable_area.features,
+            "orientation": ModuleOrientation.NOT_APPLICABLE,
         }
 
     def get_deck_slot_definitions(self) -> Dict[str, SlotDefV3]:

opentrons/protocol_engine/state/camera.py

@@ -0,0 +1,54 @@
+"""Camera related state and store resource.
+
+Camera settings, particularly for enablement, can be quieried from via the Camera Provider callback.
+However, here Camera settings may also be provided to override or supercede those provided by the callbacks.
+"""
+from dataclasses import dataclass
+from typing import Optional
+from opentrons.protocol_engine.actions import AddCameraSettingsAction
+from opentrons.protocol_engine.resources.camera_provider import CameraSettings
+
+from ._abstract_store import HasState, HandlesActions
+from ..actions import Action
+
+
+@dataclass
+class CameraState:
+    """State of Engine Camera override settings."""
+
+    enablement_settings: Optional[CameraSettings]
+    # todo(chb, 2025-10-28): Eventually we will want to extend this to include the camera configurations overrides (contrast, zoom, etc)
+
+
+class CameraStore(HasState[CameraState], HandlesActions):
+    """Camera container."""
+
+    _state: CameraState
+
+    def __init__(self) -> None:
+        """Initialize a Camera store and its state."""
+        self._state = CameraState(enablement_settings=None)
+
+    def handle_action(self, action: Action) -> None:
+        """Modify state in reaction to an action."""
+        if isinstance(action, AddCameraSettingsAction):
+            # Update the Camera Enablement settings to the newest override settings
+            self._state.enablement_settings = action.enablement_settings
+
+
+class CameraView:
+    """Read-only engine created Camera state view."""
+
+    _state: CameraState
+
+    def __init__(self, state: CameraState) -> None:
+        """Initialize the view of Camera state.
+
+        Arguments:
+            state: Camera dataclass used for tracking override settings for the camera.
+        """
+        self._state = state
+
+    def get_enablement_settings(self) -> CameraSettings | None:
+        """Get the enablement settings override currently in use. This will take priority over Camera Provider callback provided settings."""
+        return self._state.enablement_settings

opentrons/protocol_engine/state/commands.py

@@ -238,8 +238,11 @@ class CommandState:
     has_entered_error_recovery: bool
     """Whether the run has entered error recovery."""
 
-    stopped_by_estop: bool
-    """If this is set to True, the engine was stopped by an estop event."""
+    stopped_by_async_error: bool
+    """If this is set to True, the engine was stopped by an async event."""
+
+    is_stopping_because_of_async_error: bool
+    """If this is set to True, the engine was stopped by an asynch event and hasn't finished stopping."""
 
     error_recovery_policy: ErrorRecoveryPolicy
     """See `CommandView.get_error_recovery_policy()`."""
@@ -272,7 +275,8 @@ class CommandStore(HasState[CommandState], HandlesActions):
             run_completed_at=None,
             run_started_at=None,
             latest_protocol_command_hash=None,
-            stopped_by_estop=False,
+            stopped_by_async_error=False,
+            is_stopping_because_of_async_error=False,
             error_recovery_policy=error_recovery_policy,
             has_entered_error_recovery=False,
         )
@@ -472,8 +476,9 @@ class CommandStore(HasState[CommandState], HandlesActions):
             self._state.recovery_target = None
             self._state.queue_status = QueueStatus.PAUSED
 
-            if action.from_estop:
-                self._state.stopped_by_estop = True
+            if action.from_asynchronous_error:
+                self._state.stopped_by_async_error = True
+                self._state.is_stopping_because_of_async_error = True
                 self._state.run_result = RunResult.FAILED
             else:
                 self._state.run_result = RunResult.STOPPED
@@ -499,14 +504,29 @@ class CommandStore(HasState[CommandState], HandlesActions):
                     action.error_details.error,
                 )
         else:
-            # HACK(sf): There needs to be a better way to set
-            # an estop error than this else clause
-            if self._state.stopped_by_estop and action.error_details:
+            # HACK(sf): There needs to be a better way to handle async errors than this logic
+            # which is way too nonlocal. The idea here is that
+            # (1) there's an async error that calls one of the engine async error handlers,
+            # which emits a stop action and then tells the orchestrator to call finish
+            # (2) calling stop normally would lock out the run error field (since the idea is that
+            # stop happens in the handler of the error that stops the run, and thus the failed
+            # command has already set the run error), but here either the command didn't fail or
+            # the command failed with an error that isn't relevant or is duplicative, so we want
+            # to override that
+            # (3) but we don't want to override it twice, because some other error handler might
+            # tell us to finish with the cancelled error that happens because a command was cancelled
+            # in reaction to (2)
+            # So we set and clear this stopped_by_async_error and it's awful. Let's figure out a better
+            # way.
+
+            if self._state.is_stopping_because_of_async_error and action.error_details:
                 self._state.run_error = self._map_run_exception_to_error_occurrence(
                     action.error_details.error_id,
                     action.error_details.created_at,
                     action.error_details.error,
                 )
+                self._state.is_stopping_because_of_async_error = False
+                self._state.stopped_by_async_error = True
 
     def _handle_hardware_stopped_action(self, action: HardwareStoppedAction) -> None:
         self._state.queue_status = QueueStatus.PAUSED
@@ -516,10 +536,13 @@ class CommandStore(HasState[CommandState], HandlesActions):
         )
 
         if action.finish_error_details:
-            self._state.finish_error = self._map_finish_exception_to_error_occurrence(
-                action.finish_error_details.error_id,
-                action.finish_error_details.created_at,
-                action.finish_error_details.error,
+            self._state.finish_error = (
+                self._state.finish_error
+                or self._map_finish_exception_to_error_occurrence(
+                    action.finish_error_details.error_id,
+                    action.finish_error_details.created_at,
+                    action.finish_error_details.error,
+                )
             )
 
     def _handle_door_change_action(self, action: DoorChangeAction) -> None:
@@ -952,9 +975,9 @@ class CommandView:
         """Get whether an engine stop has completed."""
         return self._state.run_completed_at is not None
 
-    def get_is_stopped_by_estop(self) -> bool:
+    def get_is_stopped_by_async_error(self) -> bool:
         """Return whether the engine was stopped specifically by an E-stop."""
-        return self._state.stopped_by_estop
+        return self._state.stopped_by_async_error
 
     def has_been_played(self) -> bool:
         """Get whether engine has started."""