From 84e3b7b6496868e93ac51d6161ffb65db375f6a3 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Wed, 30 Apr 2025 18:06:40 +0300 Subject: [PATCH 1/2] gh-132813: Fix the csv documentation for quoting and escaping quotechar and new-line characters are always quoted or escaped. escapechar is always escaped. --- Doc/library/csv.rst | 34 ++++++++++++++++++++++------------ 1 file changed, 22 insertions(+), 12 deletions(-) diff --git a/Doc/library/csv.rst b/Doc/library/csv.rst index 533cdf13974be6..86ae111b1be7e1 100644 --- a/Doc/library/csv.rst +++ b/Doc/library/csv.rst @@ -323,8 +323,8 @@ The :mod:`csv` module defines the following constants: .. data:: QUOTE_MINIMAL Instructs :class:`writer` objects to only quote those fields which contain - special characters such as *delimiter*, *quotechar* or any of the characters in - *lineterminator*. + special characters such as *delimiter*, *quotechar*, ``'\r'``, ``'\n'`` + or any of the characters in *lineterminator*. .. data:: QUOTE_NONNUMERIC @@ -336,10 +336,13 @@ The :mod:`csv` module defines the following constants: .. data:: QUOTE_NONE - Instructs :class:`writer` objects to never quote fields. When the current - *delimiter* occurs in output data it is preceded by the current *escapechar* - character. If *escapechar* is not set, the writer will raise :exc:`Error` if + Instructs :class:`writer` objects to never quote fields. + When the current *delimiter*, *quotechar*, *escapechar*, ``'\r'``, ``'\n'`` + or any of the characters in *lineterminator* occurs in output data + it is preceded by the current *escapechar* character. + If *escapechar* is not set, the writer will raise :exc:`Error` if any characters that require escaping are encountered. + Set *quotechar* to ``None`` to prevent its escaping. Instructs :class:`reader` objects to perform no special processing of quote characters. @@ -408,9 +411,12 @@ Dialects support the following attributes: .. attribute:: Dialect.escapechar - A one-character string used by the writer to escape the *delimiter* if *quoting* - is set to :const:`QUOTE_NONE` and the *quotechar* if *doublequote* is - :const:`False`. On reading, the *escapechar* removes any special meaning from + A one-character string used by the writer to escape the *delimiter*, + the *quotechar*, ``'\r'``, ``'\n'`` and any of the characters in + *lineterminator* if *quoting* is set to :const:`QUOTE_NONE`, + the *quotechar* if *doublequote* is :const:`False`, + and the *escapechar* itself. + On reading, the *escapechar* removes any special meaning from the following character. It defaults to :const:`None`, which disables escaping. .. versionchanged:: 3.11 @@ -430,9 +436,12 @@ Dialects support the following attributes: .. attribute:: Dialect.quotechar - A one-character string used to quote fields containing special characters, such - as the *delimiter* or *quotechar*, or which contain new-line characters. It - defaults to ``'"'``. + A one-character string used to quote fields containing special characters, + such as the *delimiter* or the *quotechar*, or which contain new-line + characters (``'\r'``, ``'\n'`` or any of the characters in *lineterminator*). + It defaults to ``'"'``. + Can be set to ``None`` to prevent escaping ``'"'`` if *quoting* is set + to :const:`QUOTE_NONE`. .. versionchanged:: 3.11 An empty *quotechar* is not allowed. @@ -441,7 +450,8 @@ Dialects support the following attributes: Controls when quotes should be generated by the writer and recognised by the reader. It can take on any of the :ref:`QUOTE_\* constants ` - and defaults to :const:`QUOTE_MINIMAL`. + and defaults to :const:`QUOTE_MINIMAL` if *quotechar* is not ``None``, + and :const:`QUOTE_NONE` otherwise. .. attribute:: Dialect.skipinitialspace From cec7884fa7212ea992a78b072f70521b60cc3373 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Tue, 20 May 2025 18:32:11 +0300 Subject: [PATCH 2/2] Update Doc/library/csv.rst --- Doc/library/csv.rst | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/Doc/library/csv.rst b/Doc/library/csv.rst index 86ae111b1be7e1..5306e448916852 100644 --- a/Doc/library/csv.rst +++ b/Doc/library/csv.rst @@ -411,11 +411,15 @@ Dialects support the following attributes: .. attribute:: Dialect.escapechar - A one-character string used by the writer to escape the *delimiter*, - the *quotechar*, ``'\r'``, ``'\n'`` and any of the characters in - *lineterminator* if *quoting* is set to :const:`QUOTE_NONE`, - the *quotechar* if *doublequote* is :const:`False`, - and the *escapechar* itself. + A one-character string used by the writer to escape characters that + require escaping: + + * the *delimiter*, the *quotechar*, ``'\r'``, ``'\n'`` and any of the + characters in *lineterminator* are escaped if *quoting* is set to + :const:`QUOTE_NONE`; + * the *quotechar* is escaped if *doublequote* is :const:`False`; + * the *escapechar* itself. + On reading, the *escapechar* removes any special meaning from the following character. It defaults to :const:`None`, which disables escaping.