gh-80678: Document the preferred delimiters of csv.Sniffer

[serhiy-storchaka]

The list of preferred delimiters exists since the module was added in 2003 and has never been documented, so it is only discoverable by reading the source. It decides the result whenever several candidates fit the sample equally well, no matter how many times each of them occurs — the case reported in the issue, a;b;c;d,e;f;g;h, is still detected as ,.

Document this in the Sniffer.sniff() documentation and docstring. The preferred attribute itself stays undocumented.

• Issue: Undocumented behavior in csv.Sniffer (preferred delimiters) #80678

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #33683469 | 📁 Comparing 9afd3ca against main (202c4c8)

  🔍 Preview build  

1 file changed

± library/csv.html

[serhiy-storchaka]

@smontanaro, you added this list of preferred delimiters in 2003, and you wrote in gh-75008 that you keep half an eye on the csv module. Could you please check that this describes the intended behavior? No obligation of course.

[smontanaro]

@smontanaro, you added this list of preferred delimiters in 2003....

I'm going to disclaim any involvement in this. It seems commit 04ae705 was the initial commit for csv.py. I was shepherding the general CSV module development, but wasn't involved with the Sniffer class. I would be more than happy if csv.Sniffer simply disappeared. I've never needed it. I can't imagine there are too many applications where the person manipulating even a large group of CSV files didn't know their basic properties. I have always believed the Sniffer class was a solution in search of a problem. Someone else wrote it, and it landed with everything else.

[serhiy-storchaka]

I understand you very well. But it seems that it is really used. It is used in Panda, there are also several third-party implementations. Half of csv issues are related to Sniffer (my rewrite in main fixes almost all of them).

[smontanaro]

@serhiy-storchaka It looks good to me. Is there a reason for not documenting the preferred attribute and noting that the described sequence of possible delimiters is its initial value?

[miss-islington-app]

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

[miss-islington-app]

Sorry, @serhiy-storchaka and @ambv, I could not cleanly backport this to 3.15 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker 79cdcee308c6612edd6d1ca972342e2a088b6b4e 3.15

[miss-islington-app]

Sorry, @serhiy-storchaka and @ambv, I could not cleanly backport this to 3.14 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker 79cdcee308c6612edd6d1ca972342e2a088b6b4e 3.14

[miss-islington-app]

Sorry, @serhiy-storchaka and @ambv, I could not cleanly backport this to 3.13 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker 79cdcee308c6612edd6d1ca972342e2a088b6b4e 3.13