From a7dabd9124818da216c99c24a0ceea94f38e05b9 Mon Sep 17 00:00:00 2001 From: Edward Cormany Date: Thu, 15 Aug 2024 14:26:32 -0400 Subject: [PATCH] cleanup after docstrings move/conflict --- api/docs/v2/new_protocol_api.rst | 2 +- api/docs/v2/parameters/using_values.rst | 2 +- .../parameters/csv_parameter_interface.py | 24 +++++++++++++++---- 3 files changed, 21 insertions(+), 7 deletions(-) diff --git a/api/docs/v2/new_protocol_api.rst b/api/docs/v2/new_protocol_api.rst index d0501557b139..179cb3cba18c 100644 --- a/api/docs/v2/new_protocol_api.rst +++ b/api/docs/v2/new_protocol_api.rst @@ -91,7 +91,7 @@ Useful Types .. automodule:: opentrons.types :members: PipetteNotAttachedError, Point, Location, Mount -.. autoclass:: opentrons.protocols.parameters.types.CSVParameter +.. autoclass:: opentrons.protocol_api.CSVParameter :members: diff --git a/api/docs/v2/parameters/using_values.rst b/api/docs/v2/parameters/using_values.rst index 52a7aea2ab57..94b953714943 100644 --- a/api/docs/v2/parameters/using_values.rst +++ b/api/docs/v2/parameters/using_values.rst @@ -50,7 +50,7 @@ Also be careful with ``int`` types when performing calculations: dividing an ``i Manipulating CSV Data ===================== -CSV parameters have their own :py:class:`~opentrons.protocols.parameters.types.CSVParameter` type, since they don't correspond to a built-in Python type. This class has properties and methods that let you access the CSV data in one of three ways: as a file handler, as a string, or as nested lists. +CSV parameters have their own :py:class:`.CSVParameter` type, since they don't correspond to a built-in Python type. This class has properties and methods that let you access the CSV data in one of three ways: as a file handler, as a string, or as nested lists. The :py:obj:`.CSVParameter.file` parameter provides a `file handler object `_ that points to your CSV data. You can pass this object to functions of the built-in :py:obj:`csv` module, or to other modules you import, such as ``pandas``. diff --git a/api/src/opentrons/protocols/parameters/csv_parameter_interface.py b/api/src/opentrons/protocols/parameters/csv_parameter_interface.py index 20627322547a..2c48cbc3203f 100644 --- a/api/src/opentrons/protocols/parameters/csv_parameter_interface.py +++ b/api/src/opentrons/protocols/parameters/csv_parameter_interface.py @@ -16,7 +16,10 @@ def __init__(self, contents: Optional[bytes], api_version: APIVersion) -> 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: text = self.contents temporary_file = NamedTemporaryFile("r+") @@ -30,7 +33,7 @@ def file(self) -> TextIO: @property def file_opened(self) -> bool: - """Return if a file handler has been opened for the CSV parameter.""" + """Returns ``True`` if a file handler is open for the CSV parameter.""" return self._file is not None @property @@ -45,10 +48,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: