[3.15] gh-80678: Document the preferred delimiters of csv.Sniffer (GH-154336) (#154589)

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

Author: 3 people

Doc/library/csv.rst

@@ -312,6 +312,11 @@ The :mod:`!csv` module defines the following classes:
       is given, it is interpreted as a string containing possible valid
       delimiter characters.
 
+      If several delimiters 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.
 
    .. method:: has_header(sample)
 

Lib/csv.py

@@ -241,6 +241,10 @@ def __init__(self):
     def sniff(self, sample, delimiters=None):
         """
         Returns a dialect (or None) corresponding to the sample
+
+        If several delimiters 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.
         """
 
         quotechar, doublequote, delimiter, skipinitialspace = \