diff --git a/api/docs/v2/new_protocol_api.rst b/api/docs/v2/new_protocol_api.rst index 0fd8deb4afb..d0501557b13 100644 --- a/api/docs/v2/new_protocol_api.rst +++ b/api/docs/v2/new_protocol_api.rst @@ -91,6 +91,10 @@ Useful Types .. automodule:: opentrons.types :members: PipetteNotAttachedError, Point, Location, Mount +.. autoclass:: opentrons.protocols.parameters.types.CSVParameter + :members: + + .. autodata:: opentrons.protocol_api.OFF_DECK :no-value: diff --git a/api/src/opentrons/protocols/parameters/types.py b/api/src/opentrons/protocols/parameters/types.py index a4b4e30e5c6..9553e1220ec 100644 --- a/api/src/opentrons/protocols/parameters/types.py +++ b/api/src/opentrons/protocols/parameters/types.py @@ -6,16 +6,25 @@ # TODO(jbl 2024-08-02) This is a public facing class and as such should be moved to the protocol_api folder class CSVParameter: + """ + An object representing a CSV file to be used as a runtime parameter. + + .. versionadded:: 2.20 + """ + def __init__(self, csv_file: Optional[TextIO]) -> None: self._file = csv_file self._contents: Optional[str] = None @property def file(self) -> TextIO: - """Returns the file handler for the CSV file.""" + """Returns the file handler for the CSV file. + + The file is treated as read-only, UTF-8-encoded text. + """ if self._file is None: raise RuntimeParameterRequired( - "CSV parameter needs to be set to a file for full analysis or run." + "CSV parameter needs to be set to a file for full analysis or protocol run." ) return self._file @@ -30,10 +39,21 @@ def contents(self) -> str: def parse_as_csv( self, detect_dialect: bool = True, **kwargs: Any ) -> List[List[str]]: - """Returns a list of rows with each row represented as a list of column elements. + """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, even if it is numeric in nature. + Cast these strings to integers or floating point numbers, as appropriate, to use + them as inputs to other API methods. - If there is a header for the CSV that will be the first row in the list (i.e. `.rows()[0]`). - All elements will be represented as strings, even if they are numeric in nature. + :param detect_dialect: If ``True``, examine the file and try to assign it a + :py:class:`csv.Dialect` to improve parsing behavior. + :param kwargs: For advanced CSV handling, you can pass any of the + `formatting parameters `_ + accepted by :py:func:`csv.reader` from the Python standard library. """ rows: List[List[str]] = [] if detect_dialect: