Merge branch 'chore_release-8.0.0' of https://github.com/Opentrons/op…

…entrons into csv_param_improvements

api/docs/v2/versioning.rst

@@ -132,6 +132,11 @@ This table lists the correspondence between Protocol API versions and robot soft
 Changes in API Versions
 =======================
 
+Version 2.20
+------------
+
+- You can now call :py:obj:`.ProtocolContext.define_liquid()` without supplying a ``description`` or ``display_color``.
+
 Version 2.19
 ------------
 

api/src/opentrons/execute.py

@@ -142,23 +142,23 @@ def get_protocol_api(
     When this function is called, modules and instruments will be recached.
 
     :param version: The API version to use. This must be lower than
-                    ``opentrons.protocol_api.MAX_SUPPORTED_VERSION``.
-                    It may be specified either as a string (``'2.0'``) or
-                    as a ``protocols.types.APIVersion``
-                    (``APIVersion(2, 0)``).
+        ``opentrons.protocol_api.MAX_SUPPORTED_VERSION``.
+        It may be specified either as a string (``'2.0'``) or
+        as a ``protocols.types.APIVersion``
+        (``APIVersion(2, 0)``).
     :param bundled_labware: If specified, a mapping from labware names to
-                            labware definitions for labware to consider in the
-                            protocol. Note that if you specify this, _only_
-                            labware in this argument will be allowed in the
-                            protocol. This is preparation for a beta feature
-                            and is best not used.
+        labware definitions for labware to consider in the
+        protocol. Note that if you specify this, *only*
+        labware in this argument will be allowed in the
+        protocol. This is preparation for a beta feature
+        and is best not used.
     :param bundled_data: If specified, a mapping from filenames to contents
-                         for data to be available in the protocol from
-                         :py:obj:`opentrons.protocol_api.ProtocolContext.bundled_data`.
+        for data to be available in the protocol from
+        :py:obj:`opentrons.protocol_api.ProtocolContext.bundled_data`.
     :param extra_labware: A mapping from labware load names to custom labware definitions.
-                          If this is ``None`` (the default), and this function is called on a robot,
-                          it will look for labware in the ``labware`` subdirectory of the Jupyter
-                          data directory.
+        If this is ``None`` (the default), and this function is called on a robot,
+        it will look for labware in the ``labware`` subdirectory of the Jupyter
+        data directory.
     :return: The protocol context.
     """
     if isinstance(version, str):
@@ -313,18 +313,18 @@ def execute(
 
     :param protocol_file: The protocol file to execute
     :param protocol_name: The name of the protocol file. This is required
-                          internally, but it may not be a thing we can get
-                          from the protocol_file argument.
+        internally, but it may not be a thing we can get
+        from the ``protocol_file`` argument.
     :param propagate_logs: Whether this function should allow logs from the
-                           Opentrons stack to propagate up to the root handler.
-                           This can be useful if you're integrating this
-                           function in a larger application, but most logs that
-                           occur during protocol simulation are best associated
-                           with the actions in the protocol that cause them.
-                           Default: ``False``
+        Opentrons stack to propagate up to the root handler.
+        This can be useful if you're integrating this
+        function in a larger application, but most logs that
+        occur during protocol simulation are best associated
+        with the actions in the protocol that cause them.
+        Default: ``False``
     :param log_level: The level of logs to emit on the command line:
-                      ``"debug"``, ``"info"``, ``"warning"``, or ``"error"``.
-                      Defaults to ``"warning"``.
+        ``"debug"``, ``"info"``, ``"warning"``, or ``"error"``.
+        Defaults to ``"warning"``.
     :param emit_runlog: A callback for printing the run log. If specified, this
         will be called whenever a command adds an entry to the
         run log, which can be used for display and progress
@@ -353,17 +353,17 @@ def execute(
           ``KeyError``.
 
     :param custom_labware_paths: A list of directories to search for custom labware.
-                                 Loads valid labware from these paths and makes them available
-                                 to the protocol context. If this is ``None`` (the default), and
-                                 this function is called on a robot, it will look in the ``labware``
-                                 subdirectory of the Jupyter data directory.
+        Loads valid labware from these paths and makes them available
+        to the protocol context. If this is ``None`` (the default), and
+        this function is called on a robot, it will look in the ``labware``
+        subdirectory of the Jupyter data directory.
     :param custom_data_paths: A list of directories or files to load custom
-                              data files from. Ignored if the apiv2 feature
-                              flag if not set. Entries may be either files or
-                              directories. Specified files and the
-                              non-recursive contents of specified directories
-                              are presented by the protocol context in
-                              ``ProtocolContext.bundled_data``.
+        data files from. Ignored if the apiv2 feature
+        flag if not set. Entries may be either files or
+        directories. Specified files and the
+        non-recursive contents of specified directories
+        are presented by the protocol context in
+        ``ProtocolContext.bundled_data``.
     """
     stack_logger = logging.getLogger("opentrons")
     stack_logger.propagate = propagate_logs
@@ -457,10 +457,10 @@ def main() -> int:
     """Handler for command line invocation to run a protocol.
 
     :param argv: The arguments the program was invoked with; this is usually
-                 :py:obj:`sys.argv` but if you want to override that you can.
+        :py:obj:`sys.argv` but if you want to override that you can.
     :returns int: A success or failure value suitable for use as a shell
-                  return code passed to :py:obj:`sys.exit` (0 means success,
-                  anything else is a kind of failure).
+        return code passed to :py:obj:`sys.exit` (0 means success,
+        anything else is a kind of failure).
     """
     parser = argparse.ArgumentParser(
         prog="opentrons_execute", description="Run an OT-2 protocol"

api/src/opentrons/hardware_control/ot3api.py

@@ -2714,7 +2714,10 @@ async def liquid_probe(
 
         error: Optional[PipetteLiquidNotFoundError] = None
         pos = await self.gantry_position(checked_mount, refresh=True)
-        while (probe_start_pos.z - pos.z) < max_z_dist:
+        #  probe_start_pos.z + z_distance of pass - pos.z should be < max_z_dist
+        # due to rounding errors this can get caught in an infinite loop when the distance is almost equal
+        # so we check to see if they're within 0.01 which is 1/5th the minimum movement distance from move_utils.py
+        while (probe_start_pos.z - pos.z) < (max_z_dist + 0.01):
             # safe distance so we don't accidentally aspirate liquid if we're already close to liquid
             safe_plunger_pos = top_types.Point(
                 pos.x, pos.y, pos.z + probe_safe_reset_mm
@@ -2724,7 +2727,7 @@ async def liquid_probe(
                 pos.x, pos.y, pos.z + probe_pass_z_offset_mm
             )
             max_z_time = (
-                max_z_dist - (probe_start_pos.z - safe_plunger_pos.z)
+                max_z_dist - probe_start_pos.z + pass_start_pos.z
             ) / probe_settings.mount_speed
             p_travel_required_for_z = max_z_time * probe_settings.plunger_speed
             p_pass_travel = min(p_travel_required_for_z, p_working_mm)

api/src/opentrons/protocol_api/protocol_context.py

@@ -87,6 +87,16 @@
 ]
 
 
+class _Unset:
+    """A sentinel value for when no value has been supplied for an argument,
+    when `None` is already taken for some other meaning.
+
+    User code should never use this explicitly.
+    """
+
+    pass
+
+
 class ProtocolContext(CommandPublisher):
     """A context for the state of a protocol.
 
@@ -1197,17 +1207,54 @@ def set_rail_lights(self, on: bool) -> None:
 
     @requires_version(2, 14)
     def define_liquid(
-        self, name: str, description: Optional[str], display_color: Optional[str]
+        self,
+        name: str,
+        description: Union[str, None, _Unset] = _Unset(),
+        display_color: Union[str, None, _Unset] = _Unset(),
     ) -> Liquid:
+        # This first line of the docstring overrides the method signature in our public
+        # docs, which would otherwise have the `_Unset()`s expanded to a bunch of junk.
         """
+        define_liquid(self, name: str, description: Optional[str] = None, display_color: Optional[str] = None)
+
         Define a liquid within a protocol.
 
         :param str name: A human-readable name for the liquid.
-        :param str description: An optional description of the liquid.
-        :param str display_color: An optional hex color code, with hash included, to represent the specified liquid. Standard three-value, four-value, six-value, and eight-value syntax are all acceptable.
+        :param Optional[str] description: An optional description of the liquid.
+        :param Optional[str] display_color: An optional hex color code, with hash included,
+            to represent the specified liquid. For example, ``"#48B1FA"``.
+            Standard three-value, four-value, six-value, and eight-value syntax are all
+            acceptable.
 
         :return: A :py:class:`~opentrons.protocol_api.Liquid` object representing the specified liquid.
+
+        .. versionchanged:: 2.20
+            You can now omit the ``description`` and ``display_color`` arguments.
+            Formerly, when you didn't want to provide values, you had to supply
+            ``description=None`` and ``display_color=None`` explicitly.
         """
+        desc_and_display_color_omittable_since = APIVersion(2, 20)
+        if isinstance(description, _Unset):
+            if self._api_version < desc_and_display_color_omittable_since:
+                raise APIVersionError(
+                    api_element="Calling `define_liquid()` without a `description`",
+                    current_version=str(self._api_version),
+                    until_version=str(desc_and_display_color_omittable_since),
+                    message="Use a newer API version or explicitly supply `description=None`.",
+                )
+            else:
+                description = None
+        if isinstance(display_color, _Unset):
+            if self._api_version < desc_and_display_color_omittable_since:
+                raise APIVersionError(
+                    api_element="Calling `define_liquid()` without a `display_color`",
+                    current_version=str(self._api_version),
+                    until_version=str(desc_and_display_color_omittable_since),
+                    message="Use a newer API version or explicitly supply `display_color=None`.",
+                )
+            else:
+                display_color = None
+
         return self._core.define_liquid(
             name=name,
             description=description,

api/src/opentrons/protocol_api/validation.py

@@ -208,7 +208,7 @@ def ensure_and_convert_deck_slot(
                 api_element=f"Specifying a deck slot like '{deck_slot}'",
                 until_version=f"{_COORDINATE_DECK_LABEL_VERSION_GATE}",
                 current_version=f"{api_version}",
-                message=f" Increase your protocol's apiLevel, or use slot '{alternative}' instead.",
+                message=f"Increase your protocol's apiLevel, or use slot '{alternative}' instead.",
             )
 
         return parsed_slot.to_equivalent_for_robot_type(robot_type)

api/src/opentrons/protocol_runner/create_simulating_orchestrator.py

@@ -47,7 +47,11 @@ async def create_simulating_orchestrator(
         robot_type=robot_type
     )
 
-    # TODO(mc, 2021-08-25): move initial home to protocol engine
+    # TODO(mm, 2024-08-06): This home has theoretically been replaced by Protocol Engine
+    # `home` commands within the `RunOrchestrator` or `ProtocolRunner`. However, it turns
+    # out that this `HardwareControlAPI`-level home is accidentally load-bearing,
+    # working around Protocol Engine bugs where *both* layers need to be homed for
+    # certain commands to work. https://opentrons.atlassian.net/browse/EXEC-646
     await simulating_hardware_api.home()
 
     protocol_engine = await create_protocol_engine(