opentrons 8.6.0__py3-none-any.whl

opentrons/protocols/parameters/csv_parameter_definition.py

@@ -0,0 +1,77 @@
+"""CSV Parameter definition and associated classes/functions."""
+from typing import Optional
+
+from opentrons.protocol_engine.types import (
+    RunTimeParameter,
+    CSVParameter as ProtocolEngineCSVParameter,
+    FileInfo,
+)
+from opentrons.protocols.api_support.types import APIVersion
+
+from . import validation
+from .parameter_definition import AbstractParameterDefinition
+from .csv_parameter_interface import CSVParameter
+
+
+class CSVParameterDefinition(AbstractParameterDefinition[Optional[bytes]]):
+    """The definition for a user defined CSV file parameter."""
+
+    def __init__(
+        self, display_name: str, variable_name: str, description: Optional[str]
+    ) -> None:
+        """Initializes a CSV file parameter.
+
+        Arguments:
+            display_name: The display name of the parameter as it would show up on the frontend.
+            variable_name: The variable name the parameter will be referred to in the run context.
+            description: An optional description for the parameter.
+        """
+        self._display_name = validation.ensure_display_name(display_name)
+        self._variable_name = validation.ensure_variable_name(variable_name)
+        self._description = validation.ensure_description(description)
+        self._value: Optional[bytes] = None
+        self._file_info: Optional[FileInfo] = None
+
+    @property
+    def variable_name(self) -> str:
+        """The in-protocol variable name of the parameter."""
+        return self._variable_name
+
+    @property
+    def value(self) -> Optional[bytes]:
+        """The current set file for the CSV parameter. Defaults to None on definition creation."""
+        return self._value
+
+    @value.setter
+    def value(self, contents: bytes) -> None:
+        self._value = contents
+
+    @property
+    def file_info(self) -> Optional[FileInfo]:
+        return self._file_info
+
+    @file_info.setter
+    def file_info(self, file_info: FileInfo) -> None:
+        self._file_info = file_info
+
+    def as_csv_parameter_interface(self, api_version: APIVersion) -> CSVParameter:
+        return CSVParameter(contents=self._value, api_version=api_version)
+
+    def as_protocol_engine_type(self) -> RunTimeParameter:
+        """Returns CSV parameter as a Protocol Engine type to send to client."""
+        return ProtocolEngineCSVParameter(
+            displayName=self._display_name,
+            variableName=self._variable_name,
+            description=self._description,
+            file=self._file_info,
+        )
+
+
+def create_csv_parameter(
+    display_name: str,
+    variable_name: str,
+    description: Optional[str] = None,
+) -> CSVParameterDefinition:
+    return CSVParameterDefinition(
+        display_name=display_name, variable_name=variable_name, description=description
+    )

opentrons/protocols/parameters/csv_parameter_interface.py

@@ -0,0 +1,96 @@
+import csv
+from tempfile import NamedTemporaryFile
+from typing import Optional, TextIO, Any, List
+
+from opentrons.protocols.api_support.types import APIVersion
+
+from .exceptions import ParameterValueError, RuntimeParameterRequired
+
+
+# TODO(jbl 2024-08-02) This is a public facing class and as such should be moved to the protocol_api folder
+class CSVParameter:
+    def __init__(self, contents: Optional[bytes], api_version: APIVersion) -> None:
+        self._contents = contents
+        self._api_version = api_version
+        self._file: Optional[TextIO] = None
+
+    @property
+    def file(self) -> TextIO:
+        """Returns the file handler for the CSV file.
+
+        The file is treated as read-only, UTF-8-encoded text.
+        """
+        if self._file is None:
+            text = self.contents
+            temporary_file = NamedTemporaryFile("r+")
+            temporary_file.write(text)
+            temporary_file.flush()
+
+            # Open a new file handler for the temporary file with read-only permissions and close the other
+            self._file = open(temporary_file.name, "r")
+            temporary_file.close()
+        return self._file
+
+    @property
+    def file_opened(self) -> bool:
+        """Returns ``True`` if a file handler is open for the CSV parameter."""
+        return self._file is not None
+
+    @property
+    def contents(self) -> str:
+        """Returns the full contents of the CSV file as a single string."""
+        if self._contents is None:
+            raise RuntimeParameterRequired(
+                "CSV parameter needs to be set to a file for full analysis or run."
+            )
+        return self._contents.decode("utf-8")
+
+    def parse_as_csv(
+        self, detect_dialect: bool = True, **kwargs: Any
+    ) -> List[List[str]]:
+        """Parses the CSV data and returns a list of lists.
+
+        Each item in the parent list corresponds to a row in the CSV file.
+        If the CSV has a header, that will be the first row in the list: ``.parse_as_csv()[0]``.
+
+        Each item in the child lists corresponds to a single cell within its row.
+        The data for each cell is represented as a string. You may need to trim whitespace
+        or otherwise validate string contents before passing them as inputs to other API methods.
+        For numeric data, cast these strings to integers or floating point numbers,
+        as appropriate.
+
+        :param detect_dialect: If ``True``, examine the file and try to assign it a
+            :py:class:`csv.Dialect` to improve parsing behavior. Set this to ``False``
+            when using the file output of :py:meth:`.AbsorbanceReaderContext.read` as
+            a runtime parameter.
+        :param kwargs: For advanced CSV handling, you can pass any of the
+            `formatting parameters <https://docs.python.org/3/library/csv.html#csv-fmt-params>`_
+            accepted by :py:func:`csv.reader` from the Python standard library.
+        """
+        rows: List[List[str]] = []
+        if detect_dialect:
+            try:
+                dialect = csv.Sniffer().sniff(self.contents[:1024])
+                reader = csv.reader(self.contents.split("\n"), dialect, **kwargs)
+            except (UnicodeDecodeError, csv.Error):
+                raise ParameterValueError(
+                    "Cannot parse dialect or contents from provided CSV contents."
+                )
+        else:
+            try:
+                reader = csv.reader(self.contents.split("\n"), **kwargs)
+            except (UnicodeDecodeError, csv.Error):
+                raise ParameterValueError("Cannot parse provided CSV contents.")
+        try:
+            for row in reader:
+                rows.append(row)
+        except (UnicodeDecodeError, csv.Error):
+            raise ParameterValueError("Cannot parse provided CSV contents.")
+        return self._remove_trailing_empty_rows(rows)
+
+    @staticmethod
+    def _remove_trailing_empty_rows(rows: List[List[str]]) -> List[List[str]]:
+        """Removes any trailing empty rows."""
+        while rows and rows[-1] == []:
+            rows.pop()
+        return rows

opentrons/protocols/parameters/exceptions.py

@@ -0,0 +1,34 @@
+from typing import Optional, Dict, Sequence
+
+from opentrons_shared_data.errors import GeneralError, EnumeratedError, ErrorCodes
+
+
+class RuntimeParameterRequired(GeneralError):
+    """An error raised when a parameter is required to be set for full analysis."""
+
+    def __init__(
+        self,
+        message: Optional[str] = None,
+        detail: Optional[Dict[str, str]] = None,
+        wrapping: Optional[Sequence[EnumeratedError]] = None,
+    ) -> None:
+        """Build an RuntimeParameterRequired."""
+        super().__init__(
+            ErrorCodes.RUNTIME_PARAMETER_VALUE_REQUIRED, message, detail, wrapping
+        )
+
+
+class ParameterValueError(ValueError):
+    """An error raised when a parameter value is not valid."""
+
+
+class ParameterDefinitionError(ValueError):
+    """An error raised when a parameter definition value is not valid."""
+
+
+class ParameterNameError(ValueError):
+    """An error raised when a parameter name or description is not valid."""
+
+
+class IncompatibleParameterError(ValueError):
+    """An error raised when a parameter conflicts with another parameter."""

opentrons/protocols/parameters/parameter_definition.py

@@ -0,0 +1,272 @@
+"""Parameter definition and associated validators."""
+from abc import abstractmethod, ABC
+from typing import Generic, Optional, List, Set, Union
+
+from opentrons.protocols.parameters.types import (
+    ParamType,
+    ParameterChoice,
+    PrimitiveAllowedTypes,
+)
+from opentrons.protocols.parameters.exceptions import (
+    ParameterValueError,
+    ParameterDefinitionError,
+)
+from opentrons.protocols.parameters import validation
+from opentrons.protocol_engine.types import (
+    RunTimeParameter,
+    NumberParameter,
+    BooleanParameter,
+    EnumParameter,
+    EnumChoice,
+)
+from opentrons.util.get_union_elements import get_union_elements
+
+
+class AbstractParameterDefinition(ABC, Generic[ParamType]):
+    @property
+    @abstractmethod
+    def variable_name(self) -> str:
+        ...
+
+    @property
+    @abstractmethod
+    def value(self) -> ParamType:
+        ...
+
+    @value.setter
+    @abstractmethod
+    def value(self, new_value: ParamType) -> None:
+        ...
+
+    @abstractmethod
+    def as_protocol_engine_type(self) -> RunTimeParameter:
+        ...
+
+
+class ParameterDefinition(AbstractParameterDefinition[PrimitiveAllowedTypes]):
+    """The definition for a user defined parameter."""
+
+    def __init__(
+        self,
+        display_name: str,
+        variable_name: str,
+        parameter_type: type,
+        default: PrimitiveAllowedTypes,
+        minimum: Optional[PrimitiveAllowedTypes] = None,
+        maximum: Optional[PrimitiveAllowedTypes] = None,
+        choices: Optional[List[ParameterChoice]] = None,
+        description: Optional[str] = None,
+        unit: Optional[str] = None,
+    ) -> None:
+        """Initializes a parameter.
+
+        This stores the type, default values, range or list of possible values, and other information
+        that is defined when a parameter is created for a protocol, as well as validators for setting
+        a non-default value for the parameter.
+
+        Arguments:
+            display_name: The display name of the parameter as it would show up on the frontend.
+            variable_name: The variable name the parameter will be referred to in the run context.
+            parameter_type: Can be bool, int, float or str. Must match the type of default and all choices or
+                min and max values
+            default: The default value the parameter is set to. This will be used in initial analysis.
+            minimum: The minimum value the parameter can be set to (inclusive). Mutually exclusive with choices.
+            maximum: The maximum value the parameter can be set to (inclusive). Mutually exclusive with choices.
+            choices: A sequence of possible choices that this parameter can be set to.
+                Mutually exclusive with minimum and maximum.
+            description: An optional description for the parameter.
+            unit: An optional suffix for float and int type parameters.
+        """
+        self._display_name = validation.ensure_display_name(display_name)
+        self._variable_name = validation.ensure_variable_name(variable_name)
+        self._description = validation.ensure_description(description)
+        self._unit = validation.ensure_unit_string_length(unit)
+
+        if parameter_type not in get_union_elements(PrimitiveAllowedTypes):
+            raise ParameterDefinitionError(
+                "Parameters can only be of type int, float, str, or bool."
+            )
+        self._type = parameter_type
+
+        self._choices: Optional[List[ParameterChoice]] = choices
+        self._allowed_values: Optional[Set[PrimitiveAllowedTypes]] = None
+
+        self._minimum: Optional[Union[int, float]] = None
+        self._maximum: Optional[Union[int, float]] = None
+
+        validation.validate_options(default, minimum, maximum, choices, parameter_type)
+        if choices is not None:
+            self._allowed_values = {choice["value"] for choice in choices}
+        else:
+            assert isinstance(minimum, (int, float)) and isinstance(
+                maximum, (int, float)
+            )
+            self._minimum = minimum
+            self._maximum = maximum
+
+        self._default: PrimitiveAllowedTypes = default
+        self.value: PrimitiveAllowedTypes = default
+
+    @property
+    def value(self) -> PrimitiveAllowedTypes:
+        """The current value of the parameter."""
+        return self._value
+
+    @value.setter
+    def value(self, new_value: PrimitiveAllowedTypes) -> None:
+        validation.validate_type(new_value, self._type)
+        if self._allowed_values is not None and new_value not in self._allowed_values:
+            raise ParameterValueError(
+                f"Parameter must be set to one of the allowed values of {sorted(self._allowed_values)}."
+            )
+        elif (
+            isinstance(self._minimum, (int, float))
+            and isinstance(self._maximum, (int, float))
+            and isinstance(new_value, (int, float))
+            and not (self._minimum <= new_value <= self._maximum)
+        ):
+            raise ParameterValueError(
+                f"Parameter must be between {self._minimum} and {self._maximum} inclusive."
+            )
+        self._value = new_value
+
+    @property
+    def variable_name(self) -> str:
+        """The in-protocol variable name of the parameter."""
+        return self._variable_name
+
+    @property
+    def parameter_type(self) -> type:
+        """The python type of the parameter."""
+        return self._type
+
+    def as_protocol_engine_type(self) -> RunTimeParameter:
+        """Returns parameter as a Protocol Engine type to send to client."""
+        parameter: RunTimeParameter
+        if self._type is bool:
+            parameter = BooleanParameter(
+                displayName=self._display_name,
+                variableName=self._variable_name,
+                description=self._description,
+                value=bool(self._value),
+                default=bool(self._default),
+            )
+        elif self._choices is not None:
+            choices = [
+                EnumChoice(
+                    displayName=str(choice["display_name"]),
+                    value=choice["value"],
+                )
+                for choice in self._choices
+            ]
+            parameter = EnumParameter(
+                type=validation.convert_type_string_for_enum(self._type),
+                displayName=self._display_name,
+                variableName=self._variable_name,
+                description=self._description,
+                choices=choices,
+                value=self._value,
+                default=self._default,
+            )
+        elif self._minimum is not None and self._maximum is not None:
+            parameter = NumberParameter(
+                type=validation.convert_type_string_for_num_param(self._type),
+                displayName=self._display_name,
+                variableName=self._variable_name,
+                description=self._description,
+                suffix=self._unit,
+                min=float(self._minimum),
+                max=float(self._maximum),
+                value=float(self._value),
+                default=float(self._default),
+            )
+        else:
+            raise ParameterDefinitionError(
+                f"Cannot resolve parameter {self._display_name} to protocol engine type."
+            )
+
+        return parameter
+
+
+def create_int_parameter(
+    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,
+) -> ParameterDefinition:
+    """Creates an integer parameter."""
+    return ParameterDefinition(
+        parameter_type=int,
+        display_name=display_name,
+        variable_name=variable_name,
+        default=default,
+        minimum=minimum,
+        maximum=maximum,
+        choices=choices,
+        description=description,
+        unit=unit,
+    )
+
+
+def create_float_parameter(
+    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,
+) -> ParameterDefinition:
+    """Creates a float parameter."""
+    return ParameterDefinition(
+        parameter_type=float,
+        display_name=display_name,
+        variable_name=variable_name,
+        default=default,
+        minimum=minimum,
+        maximum=maximum,
+        choices=choices,
+        description=description,
+        unit=unit,
+    )
+
+
+def create_bool_parameter(
+    display_name: str,
+    variable_name: str,
+    default: bool,
+    choices: List[ParameterChoice],
+    description: Optional[str] = None,
+) -> ParameterDefinition:
+    """Creates a boolean parameter."""
+    return ParameterDefinition(
+        parameter_type=bool,
+        display_name=display_name,
+        variable_name=variable_name,
+        default=default,
+        choices=choices,
+        description=description,
+    )
+
+
+def create_str_parameter(
+    display_name: str,
+    variable_name: str,
+    default: str,
+    choices: Optional[List[ParameterChoice]] = None,
+    description: Optional[str] = None,
+) -> ParameterDefinition:
+    """Creates a string parameter."""
+    return ParameterDefinition(
+        parameter_type=str,
+        display_name=display_name,
+        variable_name=variable_name,
+        default=default,
+        choices=choices,
+        description=description,
+    )

opentrons/protocols/parameters/types.py

@@ -0,0 +1,17 @@
+from typing import TypeVar, Union, TypedDict
+
+from .csv_parameter_interface import CSVParameter
+
+
+PrimitiveAllowedTypes = Union[str, int, float, bool]
+AllAllowedTypes = Union[str, int, float, bool, bytes, None]
+UserFacingTypes = Union[str, int, float, bool, CSVParameter]
+
+ParamType = TypeVar("ParamType", bound=AllAllowedTypes)
+
+
+class ParameterChoice(TypedDict):
+    """A parameter choice containing the display name and value."""
+
+    display_name: str
+    value: PrimitiveAllowedTypes