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

Jump to bottom
Merged
merged 3 commits into from
Jun 30, 2025
Merged

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

merged 3 commits into from
Jun 30, 2025
+26 −12

Conversation

serhiy-storchaka
Copy link
Member

@serhiy-storchaka serhiy-storchaka commented Apr 30, 2025 •
edited by github-actions bot
Loading

quotechar and new-line characters are always quoted or escaped. escapechar is always escaped.

📚 Documentation preview 📚: https://cpython-previews--133209.org.readthedocs.build/

@serhiy-storchaka
pythongh-132813: Fix the csv documentation for quoting and escaping
84e3b7b 
quotechar and new-line characters are always quoted or escaped.
escapechar is always escaped.
@serhiy-storchaka serhiy-storchaka added docs Documentation in the Doc dir skip news needs backport to 3.13 bugs and security fixes labels Apr 30, 2025
@bedevere-app bedevere-app bot mentioned this pull request Apr 30, 2025
Closed
@github-project-automation github-project-automation bot moved this to Todo in Docs PRs Apr 30, 2025
@vadimkantorov
Copy link

What can also be surprising is different behavior for quotechar="" and quotechar=None. I would make them behave the same (currently quotechar="" is not permitted), but it's very subjective indeed

@serhiy-storchaka
Copy link
Member Author

It was. In the past, "" and "\0" were interpreted as None for delimiter, quotechar and escapechar. But it was confusing, and it was impossible to use the null character as the delimiter or whatever.

@vadimkantorov
Copy link

@serhiy-storchaka IIUC, quote_char=None is accepted for QUOTE_NONE, but quote_char="" is not, because there is a check that if it's a str, it must be a 1-char str. For me the fact that quote_char=None is accepted, but quote_char="" is not is strange (not talking here about the null character "\0", just about empty string)

@serhiy-storchaka serhiy-storchaka added the needs backport to 3.14 bugs and security fixes label May 8, 2025
@serhiy-storchaka serhiy-storchaka requested a review from a team May 13, 2025 10:35
terryjreedy
terryjreedy reviewed May 13, 2025
View reviewed changes
Doc/library/csv.rst Outdated
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`,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I do not understand this part of the sentence in the original, nor the addition below.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How would you write it?

Different characters are escaped depending on different conditions:

  • if quoting is set to :const:QUOTE_NONE, it escapes delimiter, quotechar, etc.
  • if doublequote is False, it escapes quotechar.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps:

A one-character string for escaping. If quoting is set to :const:QUOTE_NONE, it escapes delimiter, quotechar,  ``'\r'``, ``'\n'`` and any of the characters in *lineterminator*. If doublequote is False, it escapes quotechar

terryjreedy
terryjreedy previously requested changes May 13, 2025
View reviewed changes
Copy link
Member

@terryjreedy terryjreedy left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am assuming that the fact changes are correct. I code not parse one sentence before and less so now. I am guessing that it needs to be split into 2 sentences.

@bedevere-app
Copy link

bedevere-app bot commented May 13, 2025

When you're done making the requested changes, leave the comment: I have made the requested changes; please review again.

serhiy-storchaka
serhiy-storchaka commented May 13, 2025
View reviewed changes
@vadimkantorov
Copy link

vadimkantorov commented May 13, 2025 •
edited
Loading

It would be nice if the docs mentioned explicitly that quotechar=None is also allowed. Currently:
image

which says that "empty" is not allowed, whatever that might be meaning (and many people would consider None to also qualify as "empty")

@serhiy-storchaka
Copy link
Member Author

This what this PR does.

vadimkantorov
vadimkantorov reviewed May 13, 2025
View reviewed changes
@serhiy-storchaka
Copy link
Member Author

I have made the requested changes; please review again.

@bedevere-app
Copy link

bedevere-app bot commented May 20, 2025

Thanks for making the requested changes!

@terryjreedy: please review the changes made to this pull request.

@bedevere-app bedevere-app bot requested a review from terryjreedy May 20, 2025 15:44
@terryjreedy terryjreedy dismissed their stale review June 30, 2025 02:46

Sentence changed and is now clearer.

@hugovk hugovk merged commit 536a5ff into python:main Jun 30, 2025
31 of 32 checks passed
@github-project-automation github-project-automation bot moved this from Todo to Done in Docs PRs Jun 30, 2025
@miss-islington-app
Copy link

Thanks @serhiy-storchaka for the PR, and @hugovk for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14.
🐍🍒⛏🤖 I'm not a witch! I'm not a witch!

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Jun 30, 2025
@serhiy-storchaka @miss-islington
pythongh-132813: Fix the csv documentation for quoting and escaping (p…
db6e12b 
…ythonGH-133209)

(cherry picked from commit 536a5ff)

Co-authored-by: Serhiy Storchaka <[email protected]>
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Jun 30, 2025
@serhiy-storchaka @miss-islington
pythongh-132813: Fix the csv documentation for quoting and escaping (p…
df09259 
…ythonGH-133209)

(cherry picked from commit 536a5ff)

Co-authored-by: Serhiy Storchaka <[email protected]>
@bedevere-app
Copy link

bedevere-app bot commented Jun 30, 2025

GH-136113 is a backport of this pull request to the 3.14 branch.

@bedevere-app bedevere-app bot removed the needs backport to 3.14 bugs and security fixes label Jun 30, 2025
@bedevere-app
Copy link

bedevere-app bot commented Jun 30, 2025

GH-136114 is a backport of this pull request to the 3.13 branch.

@bedevere-app bedevere-app bot removed the needs backport to 3.13 bugs and security fixes label Jun 30, 2025
hugovk pushed a commit that referenced this pull request Jun 30, 2025
@miss-islington @serhiy-storchaka
[3.14] gh-132813: Fix the csv documentation for quoting and escaping (G…
130d40a 
…H-133209) (#136113)

Co-authored-by: Serhiy Storchaka <[email protected]>
hugovk pushed a commit that referenced this pull request Jun 30, 2025
@miss-islington @serhiy-storchaka
[3.13] gh-132813: Fix the csv documentation for quoting and escaping (G…
008c8ca 
…H-133209) (#136114)

Co-authored-by: Serhiy Storchaka <[email protected]>
@serhiy-storchaka serhiy-storchaka deleted the docs-csv-quoting branch July 1, 2025 17:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@vadimkantorov vadimkantorov vadimkantorov left review comments

@aterrel aterrel aterrel approved these changes

@hugovk hugovk hugovk approved these changes

@terryjreedy terryjreedy terryjreedy approved these changes

Assignees
No one assigned
Labels
docs Documentation in the Doc dir skip news
Projects
Docs PRs
Status: Done
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
5 participants
@serhiy-storchaka @vadimkantorov @aterrel @hugovk @terryjreedy