[3.14] gh-132813: Fix the csv documentation for quoting and escaping (GH-133209)...

Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>

diff --git a/Doc/library/csv.rst b/Doc/library/csv.rst
index 2e513bff651cd22bf34a9ceb07ff2ea0d33bf021..246999c64e4d68da54a50f27f9f3f23784cdd95c 100644 (file)
--- 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
@@ -342,10 +342,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.
 
@@ -414,9 +417,16 @@ 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 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.
 
    .. versionchanged:: 3.11
@@ -436,9 +446,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.
@@ -447,7 +460,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 <csv-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