From 75cb41743af29876af768905947ee9990f4e53d2 Mon Sep 17 00:00:00 2001 From: Uttam Bhadauriya Date: Tue, 6 Oct 2026 18:37:25 +0530 Subject: [PATCH 1/2] gh-158837: Clarify csv.reader handling of iterables with stripped newlines Adds a warning and an example explaining that strings must retain their trailing newlines for quoted multiline values to be preserved. --- Doc/library/csv.rst | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/Doc/library/csv.rst b/Doc/library/csv.rst index 869c6a5f96a1f2a..da87d802cb1ea1f 100644 --- a/Doc/library/csv.rst +++ b/Doc/library/csv.rst @@ -67,6 +67,13 @@ The :mod:`!csv` module defines the following functions: dialect. For full details about the dialect and formatting parameters, see section :ref:`csv-fmt-params`. + .. note:: + If *csvfile* is an iterable of strings (such as a list) and the CSV format + contains quoted fields with embedded newlines, ensure that the strings + retain their newline characters. For example, using :meth:`~str.splitlines` + without ``keepends=True`` will strip these newlines, causing them to be + lost when the quoted fields are reconstructed. + Each row read from the csv file is returned as a list of strings. No automatic data type conversion is performed unless the :data:`QUOTE_NONNUMERIC` format option is specified (in which case unquoted fields are transformed into floats). @@ -711,6 +718,17 @@ done:: for row in csv.reader(['one,two,three']): print(row) +If the string contains quoted fields with embedded newlines, use +:meth:`~str.splitlines` with ``keepends=True`` to ensure the newlines +are preserved:: + + import csv + text = '''"Id (id)","Comments (comments)" + "195","This is a + multiline comment"''' + for row in csv.reader(text.splitlines(True)): + print(row) + .. rubric:: Footnotes From 1d0782fe9d3e786a575eb251826f35b7fdf0ffb2 Mon Sep 17 00:00:00 2001 From: Uttam Bhadauriya Date: Tue, 6 Oct 2026 18:51:43 +0530 Subject: [PATCH 2/2] Fix trailing whitespace --- Doc/library/csv.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/csv.rst b/Doc/library/csv.rst index da87d802cb1ea1f..8721a739313bf07 100644 --- a/Doc/library/csv.rst +++ b/Doc/library/csv.rst @@ -69,7 +69,7 @@ The :mod:`!csv` module defines the following functions: .. note:: If *csvfile* is an iterable of strings (such as a list) and the CSV format - contains quoted fields with embedded newlines, ensure that the strings + contains quoted fields with embedded newlines, ensure that the strings retain their newline characters. For example, using :meth:`~str.splitlines` without ``keepends=True`` will strip these newlines, causing them to be lost when the quoted fields are reconstructed.