https://github.com/python/cpython/commit/536a5ff15357a7d616c8226a642443e699f30244
commit: 536a5ff15357a7d616c8226a642443e699f30244
branch: main
author: Serhiy Storchaka <[email protected]>
committer: hugovk <[email protected]>
date: 2025-06-30T10:42:00+03:00
summary:
gh-132813: Fix the csv documentation for quoting and escaping (#133209)
files:
M Doc/library/csv.rst
diff --git a/Doc/library/csv.rst b/Doc/library/csv.rst
index 2e513bff651cd2..246999c64e4d68 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
@@ -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
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: [email protected]
