Skip to content

gh-132813: Fix the csv documentation for quoting and escaping #133209

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+22 −12
Open

gh-132813: Fix the csv documentation for quoting and escaping #133209

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 22 additions & 12 deletions Doc/library/csv.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.

Expand Down Expand Up @@ -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
Expand All @@ -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.
Expand All @@ -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 <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
Expand Down
Loading