gh-80678: Document the preferred delimiters of csv.Sniffer (#154336)

The delimiters which win when several combinations fit the sample
equally well were not documented.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

diff --git a/Doc/library/csv.rst b/Doc/library/csv.rst
index 36db964a8bbfe44584a1ed3b4c80f078436e6eec..81949261c563d045c7b40ec70685c42d2383bb1a 100644 (file)
--- a/Doc/library/csv.rst
+++ b/Doc/library/csv.rst
@@ -322,6 +322,12 @@ The :mod:`!csv` module defines the following classes:
       in particular if it is a single column,
       so there is no delimiter to find.
 
+      If several combinations fit the sample equally well ---
+      for example if both ``','`` and ``';'`` split every row consistently ---
+      the delimiters ``','``, ``'\t'``, ``';'``, ``' '`` and ``':'``
+      are preferred, in this order,
+      no matter how many times each of them occurs.
+
       .. versionchanged:: next
          The dialect is now deduced by trial parsing
          and the results may differ from those of earlier Python versions.

diff --git a/Lib/csv.py b/Lib/csv.py
index 505e9e501e6772b2ef90a888e75bcdc29db21595..a84234f110dd70c742e5622537502ae95a161a3c 100644 (file)
--- a/Lib/csv.py
+++ b/Lib/csv.py
@@ -260,6 +260,10 @@ class Sniffer:
         beginning, then, after eliminating the combinations which are
         clearly worse than the leader, a several times larger part,
         and so on.
+
+        If several combinations fit the sample equally well, the
+        delimiters listed in the preferred attribute are preferred, in
+        that order, no matter how many times each of them occurs.
         """
         import re
         from collections import defaultdict