opentrons 8.6.0__py3-none-any.whl

opentrons/protocol_api/_nozzle_layout.py

@@ -0,0 +1,31 @@
+from typing_extensions import Final
+import enum
+
+
+class NozzleLayout(enum.Enum):
+    COLUMN = "COLUMN"
+    PARTIAL_COLUMN = "PARTIAL_COLUMN"
+    SINGLE = "SINGLE"
+    ROW = "ROW"
+    QUADRANT = "QUADRANT"
+    ALL = "ALL"
+
+
+COLUMN: Final = NozzleLayout.COLUMN
+PARTIAL_COLUMN: Final = NozzleLayout.PARTIAL_COLUMN
+SINGLE: Final = NozzleLayout.SINGLE
+ROW: Final = NozzleLayout.ROW
+ALL: Final = NozzleLayout.ALL
+
+# Set __doc__ manually as a workaround. When this docstring is written the normal way, right after
+# the constant definition, Sphinx has trouble picking it up.
+COLUMN.__doc__ = """\
+A special nozzle configuration type indicating a full single column pick up. Predominantly meant for the 96 channel.
+
+See <ADD REFERENCE HERE> for details on using ``COLUMN`` with :py:obj:`InstrumentContext.configure_nozzle_layout()`.
+"""
+ALL.__doc__ = """\
+A special nozzle configuration type indicating a reset back to default where the pipette will pick up its max capacity of tips.
+
+See <ADD REFERENCE HERE> for details on using ``ALL`` with :py:obj:`InstrumentContext.configure_nozzle_layout()`.
+"""

opentrons/protocol_api/_parameter_context.py

@@ -0,0 +1,300 @@
+"""Parameter context for python protocols."""
+import uuid
+from typing import List, Optional, Union, Dict
+
+from opentrons.protocols.api_support.types import APIVersion
+from opentrons.protocols.api_support.util import requires_version
+from opentrons.protocols.parameters import (
+    parameter_definition,
+    csv_parameter_definition,
+    validation,
+)
+from opentrons.protocols.parameters.types import (
+    ParameterChoice,
+    UserFacingTypes,
+)
+from opentrons.protocols.parameters.exceptions import (
+    ParameterDefinitionError,
+    ParameterValueError,
+    IncompatibleParameterError,
+)
+from opentrons.protocol_engine.types import (
+    RunTimeParameter,
+    PrimitiveRunTimeParamValuesType,
+    CSVRuntimeParamPaths,
+    FileInfo,
+)
+
+from ._parameters import Parameters
+
+_ParameterDefinitionTypes = Union[
+    parameter_definition.ParameterDefinition,
+    csv_parameter_definition.CSVParameterDefinition,
+]
+
+
+class ParameterContext:
+    """Public context for adding parameters to a protocol."""
+
+    def __init__(self, api_version: APIVersion) -> None:
+        """Initializes a parameter context for user-set parameters."""
+        self._api_version = api_version
+        self._parameters: Dict[str, _ParameterDefinitionTypes] = {}
+
+    def add_int(
+        self,
+        display_name: str,
+        variable_name: str,
+        default: int,
+        minimum: Optional[int] = None,
+        maximum: Optional[int] = None,
+        choices: Optional[List[ParameterChoice]] = None,
+        description: Optional[str] = None,
+        unit: Optional[str] = None,
+    ) -> None:
+        """Creates an integer parameter, settable within a given range or list of choices.
+
+        Arguments:
+            display_name: The display name of the int parameter as it would show up on the frontend.
+            variable_name: The variable name the int parameter will be referred to in the run context.
+            default: The default value the int parameter will be set to. This will be used in initial analysis.
+            minimum: The minimum value the int parameter can be set to (inclusive). Mutually exclusive with choices.
+            maximum: The maximum value the int parameter can be set to (inclusive). Mutually exclusive with choices.
+            choices: A list of possible choices that this parameter can be set to.
+                Mutually exclusive with minimum and maximum.
+            description: A description of the parameter as it will show up on the frontend.
+            unit: An optional unit to be appended to the end of the integer as it shown on the frontend.
+        """
+        validation.validate_variable_name_unique(variable_name, set(self._parameters))
+        parameter = parameter_definition.create_int_parameter(
+            display_name=display_name,
+            variable_name=variable_name,
+            default=default,
+            minimum=minimum,
+            maximum=maximum,
+            choices=choices,
+            description=description,
+            unit=unit,
+        )
+        self._parameters[parameter.variable_name] = parameter
+
+    def add_float(
+        self,
+        display_name: str,
+        variable_name: str,
+        default: float,
+        minimum: Optional[float] = None,
+        maximum: Optional[float] = None,
+        choices: Optional[List[ParameterChoice]] = None,
+        description: Optional[str] = None,
+        unit: Optional[str] = None,
+    ) -> None:
+        """Creates a float parameter, settable within a given range or list of choices.
+
+        Arguments:
+            display_name: The display name of the float parameter as it would show up on the frontend.
+            variable_name: The variable name the float parameter will be referred to in the run context.
+            default: The default value the float parameter will be set to. This will be used in initial analysis.
+            minimum: The minimum value the float parameter can be set to (inclusive). Mutually exclusive with choices.
+            maximum: The maximum value the float parameter can be set to (inclusive). Mutually exclusive with choices.
+            choices: A list of possible choices that this parameter can be set to.
+                Mutually exclusive with minimum and maximum.
+            description: A description of the parameter as it will show up on the frontend.
+            unit: An optional unit to be appended to the end of the float as it shown on the frontend.
+        """
+        validation.validate_variable_name_unique(variable_name, set(self._parameters))
+        parameter = parameter_definition.create_float_parameter(
+            display_name=display_name,
+            variable_name=variable_name,
+            default=validation.ensure_float_value(default),
+            minimum=validation.ensure_optional_float_value(minimum),
+            maximum=validation.ensure_optional_float_value(maximum),
+            choices=validation.ensure_float_choices(choices),
+            description=description,
+            unit=unit,
+        )
+        self._parameters[parameter.variable_name] = parameter
+
+    def add_bool(
+        self,
+        display_name: str,
+        variable_name: str,
+        default: bool,
+        description: Optional[str] = None,
+    ) -> None:
+        """Creates a boolean parameter with allowable values of "On" (True) or "Off" (False).
+
+        Arguments:
+            display_name: The display name of the boolean parameter as it would show up on the frontend.
+            variable_name: The variable name the boolean parameter will be referred to in the run context.
+            default: The default value the boolean parameter will be set to. This will be used in initial analysis.
+            description: A description of the parameter as it will show up on the frontend.
+        """
+        validation.validate_variable_name_unique(variable_name, set(self._parameters))
+        parameter = parameter_definition.create_bool_parameter(
+            display_name=display_name,
+            variable_name=variable_name,
+            default=default,
+            choices=[
+                {"display_name": "On", "value": True},
+                {"display_name": "Off", "value": False},
+            ],
+            description=description,
+        )
+        self._parameters[parameter.variable_name] = parameter
+
+    def add_str(
+        self,
+        display_name: str,
+        variable_name: str,
+        default: str,
+        choices: Optional[List[ParameterChoice]] = None,
+        description: Optional[str] = None,
+    ) -> None:
+        """Creates a string parameter, settable among given choices.
+
+        Arguments:
+            display_name: The display name of the string parameter as it would show up on the frontend.
+            variable_name: The variable name the string parameter will be referred to in the run context.
+            default: The default value the string parameter will be set to. This will be used in initial analysis.
+            choices: A list of possible choices that this parameter can be set to.
+                Mutually exclusive with minimum and maximum.
+            description: A description of the parameter as it will show up on the frontend.
+        """
+        validation.validate_variable_name_unique(variable_name, set(self._parameters))
+        parameter = parameter_definition.create_str_parameter(
+            display_name=display_name,
+            variable_name=variable_name,
+            default=default,
+            choices=choices,
+            description=description,
+        )
+        self._parameters[parameter.variable_name] = parameter
+
+    @requires_version(2, 20)
+    def add_csv_file(
+        self,
+        display_name: str,
+        variable_name: str,
+        description: Optional[str] = None,
+    ) -> None:
+        """Creates a CSV parameter that can be set to any CSV file via the Flex ODD or a local computer.
+
+        Arguments:
+            display_name: The display name of the CSV parameter as it would show up on the frontend.
+            variable_name: The variable name the CSV parameter will be referred to in the run context.
+            description: A description of the parameter as it will show up on the frontend.
+        """
+        if any(
+            isinstance(parameter, csv_parameter_definition.CSVParameterDefinition)
+            for parameter in self._parameters.values()
+        ):
+            raise IncompatibleParameterError(
+                "Only one CSV File parameter can be defined per protocol."
+            )
+
+        validation.validate_variable_name_unique(variable_name, set(self._parameters))
+        parameter = csv_parameter_definition.create_csv_parameter(
+            display_name=display_name,
+            variable_name=variable_name,
+            description=description,
+        )
+        self._parameters[parameter.variable_name] = parameter
+
+    def set_parameters(
+        self, parameter_overrides: PrimitiveRunTimeParamValuesType
+    ) -> None:
+        """Sets parameters to values given by client, validating them as well.
+
+        :meta private:
+
+        This is intended for Opentrons internal use only and is not a guaranteed API.
+        """
+        for variable_name, override_value in parameter_overrides.items():
+            try:
+                parameter = self._parameters[variable_name]
+            except KeyError:
+                raise ParameterDefinitionError(
+                    f"Parameter {variable_name} is not defined as a parameter for this protocol."
+                )
+            if isinstance(parameter, csv_parameter_definition.CSVParameterDefinition):
+                raise ParameterValueError(
+                    f"A primitive param value was provided for the parameter '{variable_name}',"
+                    f" but '{variable_name}' is a CSV parameter that can only accept file IDs."
+                )
+            else:
+                validated_value = validation.ensure_value_type(
+                    override_value, parameter.parameter_type
+                )
+                parameter.value = validated_value
+
+    def initialize_csv_files(
+        self, run_time_param_file_overrides: CSVRuntimeParamPaths
+    ) -> None:
+        """Initializes the files for CSV parameters.
+
+        :meta private:
+
+        This is intended for Opentrons internal use only and is not a guaranteed API.
+        """
+        for variable_name, file_path in run_time_param_file_overrides.items():
+            try:
+                parameter = self._parameters[variable_name]
+            except KeyError:
+                raise ParameterDefinitionError(
+                    f"Parameter {variable_name} is not defined as a parameter for this protocol."
+                )
+            if not isinstance(
+                parameter, csv_parameter_definition.CSVParameterDefinition
+            ):
+                raise ParameterValueError(
+                    f"File Id was provided for the parameter '{variable_name}',"
+                    f" but '{variable_name}' is not a CSV parameter."
+                )
+
+            # TODO(jbl 2024-09-30) Refactor this so file ID is passed as its own argument and not assumed from the path
+            # If this is running on a robot, the parent folder in the path will be the file ID
+            # If it is running locally, most likely the parent folder will not be a UUID, so instead we will change
+            # this to be an empty string
+            file_id = file_path.parent.name
+            try:
+                uuid.UUID(file_id, version=4)
+            except ValueError:
+                file_id = ""
+
+            file_name = file_path.name
+
+            with file_path.open("rb") as fh:
+                contents = fh.read()
+
+            parameter.file_info = FileInfo(id=file_id, name=file_name)
+            parameter.value = contents
+
+    def export_parameters_for_analysis(self) -> List[RunTimeParameter]:
+        """Exports all parameters into a protocol engine models for reporting in analysis.
+
+        :meta private:
+
+        This is intended for Opentrons internal use only and is not a guaranteed API.
+        """
+        return [
+            parameter.as_protocol_engine_type()
+            for parameter in self._parameters.values()
+        ]
+
+    def export_parameters_for_protocol(self) -> Parameters:
+        """Exports all parameters into a protocol run usable parameters object.
+
+        :meta private:
+
+        This is intended for Opentrons internal use only and is not a guaranteed API.
+        """
+        parameters_for_protocol: Dict[str, UserFacingTypes] = {}
+        for parameter in self._parameters.values():
+            value: UserFacingTypes
+            if isinstance(parameter, csv_parameter_definition.CSVParameterDefinition):
+                value = parameter.as_csv_parameter_interface(self._api_version)
+            else:
+                value = parameter.value
+            parameters_for_protocol[parameter.variable_name] = value
+        return Parameters(parameters=parameters_for_protocol)

opentrons/protocol_api/_parameters.py

@@ -0,0 +1,31 @@
+from typing import Dict, Optional, Any
+
+from opentrons.protocols.parameters.types import UserFacingTypes
+from opentrons.protocols.parameters.exceptions import ParameterNameError
+
+
+class Parameters:
+    def __init__(self, parameters: Optional[Dict[str, UserFacingTypes]] = None) -> None:
+        super().__setattr__("_values", {})
+        self._values: Dict[str, UserFacingTypes] = {}
+        if parameters is not None:
+            for name, value in parameters.items():
+                self._initialize_parameter(name, value)
+
+    def __setattr__(self, key: str, value: Any) -> None:
+        if key in self._values:
+            raise AttributeError(f"Cannot overwrite protocol defined parameter {key}")
+        super().__setattr__(key, value)
+
+    def _initialize_parameter(self, variable_name: str, value: UserFacingTypes) -> None:
+        if not hasattr(self, variable_name):
+            setattr(self, variable_name, value)
+            self._values[variable_name] = value
+        else:
+            raise ParameterNameError(
+                f"Cannot use {variable_name} as a variable name, either duplicates another"
+                f" parameter name, Opentrons reserved function, or Python built-in"
+            )
+
+    def get_all(self) -> Dict[str, UserFacingTypes]:
+        return self._values

opentrons/protocol_api/_transfer_liquid_validation.py

@@ -0,0 +1,108 @@
+from dataclasses import dataclass
+from typing import List, Union, Sequence, Optional
+
+from opentrons.types import Location, NozzleMapInterface
+from opentrons.protocols.api_support import instrument
+from opentrons.protocols.advanced_control.transfers import (
+    transfer_liquid_utils as tx_liquid_utils,
+)
+from opentrons.protocols.advanced_control.transfers.common import (
+    TransferTipPolicyV2,
+    TransferTipPolicyV2Type,
+)
+
+from .disposal_locations import TrashBin, WasteChute
+from .labware import Labware, Well
+from . import validation
+
+
+@dataclass
+class TransferInfo:
+
+    source: List[Well]
+    dest: Union[List[Well], TrashBin, WasteChute]
+    tip_policy: TransferTipPolicyV2
+    tip_racks: List[Labware]
+    trash_location: Union[Location, TrashBin, WasteChute]
+
+
+def verify_and_normalize_transfer_args(
+    source: Union[Well, Sequence[Well], Sequence[Sequence[Well]]],
+    dest: Union[Well, Sequence[Well], Sequence[Sequence[Well]], TrashBin, WasteChute],
+    tip_policy: TransferTipPolicyV2Type,
+    last_tip_well: Optional[Well],
+    tip_racks: List[Labware],
+    nozzle_map: NozzleMapInterface,
+    group_wells_for_multi_channel: bool,
+    current_volume: float,
+    trash_location: Union[Location, Well, Labware, TrashBin, WasteChute],
+) -> TransferInfo:
+    flat_sources_list = validation.ensure_valid_flat_wells_list_for_transfer_v2(source)
+    if not isinstance(dest, (TrashBin, WasteChute)):
+        flat_dests_list = validation.ensure_valid_flat_wells_list_for_transfer_v2(dest)
+    else:
+        # If trash bin or waste chute, set this to empty to have less isinstance checks after this
+        flat_dests_list = []
+    if group_wells_for_multi_channel and nozzle_map.tip_count > 1:
+        flat_sources_list = tx_liquid_utils.group_wells_for_multi_channel_transfer(
+            flat_sources_list, nozzle_map, "source"
+        )
+        flat_dests_list = tx_liquid_utils.group_wells_for_multi_channel_transfer(
+            flat_dests_list, nozzle_map, "destination"
+        )
+    for well in flat_sources_list + flat_dests_list:
+        instrument.validate_takes_liquid(
+            location=well.top(),
+            reject_module=True,
+            reject_adapter=True,
+        )
+
+    valid_new_tip = validation.ensure_new_tip_policy(tip_policy)
+    if valid_new_tip == TransferTipPolicyV2.NEVER:
+        if last_tip_well is None:
+            raise RuntimeError(
+                "Pipette has no tip attached to perform transfer."
+                " Either do a pick_up_tip beforehand or specify a new_tip parameter"
+                " of 'once' or 'always'."
+            )
+        else:
+            valid_tip_racks = [last_tip_well.parent]
+    else:
+        valid_tip_racks = tip_racks
+    if current_volume != 0:
+        raise RuntimeError(
+            "A transfer on a liquid class cannot start with liquid already in the tip."
+            " Ensure that all previously aspirated liquid is dispensed before starting"
+            " a new transfer."
+        )
+
+    _trash_location: Union[Location, Well, TrashBin, WasteChute]
+    if isinstance(trash_location, Labware):
+        _trash_location = trash_location.wells()[0]
+    else:
+        _trash_location = trash_location
+
+    valid_trash_location = validation.ensure_valid_trash_location_for_transfer_v2(
+        trash_location=_trash_location
+    )
+
+    return TransferInfo(
+        source=flat_sources_list,
+        dest=flat_dests_list if not isinstance(dest, (TrashBin, WasteChute)) else dest,
+        tip_policy=valid_new_tip,
+        tip_racks=valid_tip_racks,
+        trash_location=valid_trash_location,
+    )
+
+
+def resolve_keep_last_tip(
+    keep_last_tip: Optional[bool], tip_strategy: TransferTipPolicyV2
+) -> bool:
+    """Resolve the liquid class transfer argument `keep_last_tip`
+
+    If set to a boolean value, maintains that setting. Otherwise, default to
+    `True` if tip policy is `NEVER`, otherwise default to `False`
+    """
+    if keep_last_tip is not None:
+        return keep_last_tip
+    return tip_strategy == TransferTipPolicyV2.NEVER

opentrons/protocol_api/_types.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+from typing_extensions import Final
+import enum
+
+
+# TODO (tz, 5-18-23): think about a better name for it that would also work when we include staging area slots in the type.
+class OffDeckType(enum.Enum):
+    OFF_DECK = "off-deck"
+
+
+OFF_DECK: Final = OffDeckType.OFF_DECK
+
+# Set __doc__ manually as a workaround. When this docstring is written the normal way, right after
+# the constant definition, Sphinx has trouble picking it up.
+OFF_DECK.__doc__ = """\
+A special location value, indicating that a labware is not currently on the robot's deck.
+
+See :ref:`off-deck-location` for details on using ``OFF_DECK`` with :py:obj:`ProtocolContext.move_labware()`.
+"""
+
+
+class PlungerPositionTypes(enum.Enum):
+    PLUNGER_TOP = "top"
+    PLUNGER_BOTTOM = "bottom"
+    PLUNGER_BLOWOUT = "blow_out"
+    PLUNGER_DROPTIP = "drop_tip"
+
+
+PLUNGER_TOP: Final = PlungerPositionTypes.PLUNGER_TOP
+PLUNGER_BOTTOM: Final = PlungerPositionTypes.PLUNGER_BOTTOM
+PLUNGER_BLOWOUT: Final = PlungerPositionTypes.PLUNGER_BLOWOUT
+PLUNGER_DROPTIP: Final = PlungerPositionTypes.PLUNGER_DROPTIP
+
+
+class PipetteActionTypes(enum.Enum):
+    ASPIRATE_ACTION = "aspirate"
+    DISPENSE_ACTION = "dispense"
+    BLOWOUT_ACTION = "blowout"
+
+
+ASPIRATE_ACTION: Final = PipetteActionTypes.ASPIRATE_ACTION
+DISPENSE_ACTION: Final = PipetteActionTypes.DISPENSE_ACTION
+BLOWOUT_ACTION: Final = PipetteActionTypes.BLOWOUT_ACTION

opentrons/protocol_api/config.py

@@ -0,0 +1,23 @@
+"""Contains configuration related classes for Protocol API."""
+
+
+class Clearances:
+    def __init__(self, default_aspirate: float, default_dispense: float) -> None:
+        self._aspirate = default_aspirate
+        self._dispense = default_dispense
+
+    @property
+    def aspirate(self) -> float:
+        return self._aspirate
+
+    @aspirate.setter
+    def aspirate(self, new_val: float) -> None:
+        self._aspirate = float(new_val)
+
+    @property
+    def dispense(self) -> float:
+        return self._dispense
+
+    @dispense.setter
+    def dispense(self, new_val: float) -> None:
+        self._dispense = float(new_val)

opentrons/protocol_api/core/__init__.py

@@ -0,0 +1,23 @@
+"""Core protocol logic interfaces and implementations.
+
+This module provide facades to different protocol execution cores,
+and is an internal implementation detail of the Python Protocol API.
+
+Nothing defined in `opentrons.protocol_api.core` may be considered public.
+"""
+# TODO(mc, 2022-08-22): uncomment when import cycles can be resolved
+# from .protocol import AbstractProtocol
+# from .labware_offset_provider import (
+#     AbstractLabwareOffsetProvider,
+#     LabwareOffsetProvider,
+#     NullLabwareOffsetProvider,
+#     ProvidedLabwareOffset,
+# )
+
+# __all__ = [
+#     "AbstractProtocol",
+#     "AbstractLabwareOffsetProvider",
+#     "LabwareOffsetProvider",
+#     "NullLabwareOffsetProvider",
+#     "ProvidedLabwareOffset",
+# ]

opentrons/protocol_api/core/common.py

@@ -0,0 +1,33 @@
+"""Common APIs for protocol core interfaces."""
+
+# TODO(mc, 2022-08-22): move to __init__ when dependency cycles are resolved
+from .instrument import AbstractInstrument
+from .labware import AbstractLabware
+from .module import (
+    AbstractModuleCore,
+    AbstractTemperatureModuleCore,
+    AbstractMagneticModuleCore,
+    AbstractThermocyclerCore,
+    AbstractHeaterShakerCore,
+    AbstractMagneticBlockCore,
+    AbstractAbsorbanceReaderCore,
+    AbstractFlexStackerCore,
+)
+from .protocol import AbstractProtocol
+from .well import AbstractWellCore
+from .robot import AbstractRobot
+
+
+WellCore = AbstractWellCore
+LabwareCore = AbstractLabware[WellCore]
+InstrumentCore = AbstractInstrument[WellCore, LabwareCore]
+ModuleCore = AbstractModuleCore[LabwareCore]
+TemperatureModuleCore = AbstractTemperatureModuleCore[LabwareCore]
+MagneticModuleCore = AbstractMagneticModuleCore[LabwareCore]
+ThermocyclerCore = AbstractThermocyclerCore[LabwareCore]
+HeaterShakerCore = AbstractHeaterShakerCore[LabwareCore]
+MagneticBlockCore = AbstractMagneticBlockCore[LabwareCore]
+AbsorbanceReaderCore = AbstractAbsorbanceReaderCore[LabwareCore]
+FlexStackerCore = AbstractFlexStackerCore[LabwareCore]
+RobotCore = AbstractRobot
+ProtocolCore = AbstractProtocol[InstrumentCore, LabwareCore, ModuleCore]

opentrons/protocol_api/core/core_map.py

@@ -0,0 +1,74 @@
+"""Map equipment cores to public PAPI objects."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Dict, Union
+from typing import overload, Callable
+
+from .common import ModuleCore, LabwareCore
+
+if TYPE_CHECKING:
+    from ..labware import Labware
+    from ..protocol_context import ModuleTypes
+
+
+class LoadedCoreMap:
+    """A map of equipment (labware, modules) cores to public PAPI instances.
+
+    This object keeps track of every core instance that has been created
+    so that later, those cores can be used to look up the public PAPI objects
+    they represent.
+
+    This linkage creates a circular dependency, but keeps it contained to this instance.
+    """
+
+    def __init__(self) -> None:
+        self._contexts_by_core: Dict[
+            Union[LabwareCore, ModuleCore],
+            Union[Labware, ModuleTypes],
+        ] = {}
+
+    @overload
+    def add(self, core: LabwareCore, context: Labware) -> None:
+        ...
+
+    @overload
+    def add(self, core: ModuleCore, context: ModuleTypes) -> None:
+        ...
+
+    def add(
+        self,
+        core: Union[LabwareCore, ModuleCore],
+        context: Union[Labware, ModuleTypes],
+    ) -> None:
+        """Add a core and its associated public PAPI object."""
+        self._contexts_by_core[core] = context
+
+    @overload
+    def get(self, core: LabwareCore) -> Labware:
+        ...
+
+    @overload
+    def get(self, core: ModuleCore) -> ModuleTypes:
+        ...
+
+    @overload
+    def get(self, core: None) -> None:
+        ...
+
+    def get(
+        self, core: Union[LabwareCore, ModuleCore, None]
+    ) -> Union[Labware, ModuleTypes, None]:
+        """Given a core, get the public PAPI object it represents."""
+        return self._contexts_by_core[core] if core is not None else None
+
+    def get_or_add(
+        self, core: LabwareCore, context_builder: Callable[[LabwareCore], Labware]
+    ) -> Labware:
+        try:
+            return self.get(core)
+        except KeyError:
+            pass
+        context = context_builder(core)
+        self.add(core, context)
+        return context