bpo-43625: Enhance csv sniffer has_headers() to be more accurate (GH-26939) (GH-27494)

(cherry picked from commit ceea579ccc51791f3e115155d6f27905bc7544a9)

Co-authored-by: andrei kulakov <andrei.avk@gmail.com>

1 files changed, 14 insertions, 0 deletions

diff --git a/Doc/library/csv.rst b/Doc/library/csv.rst
index 7a72c26..cb03f8d 100644
--- a/Doc/library/csv.rst
+++ b/Doc/library/csv.rst
@@ -269,6 +269,20 @@ The :mod:`csv` module defines the following classes:
 
       Analyze the sample text (presumed to be in CSV format) and return
       :const:`True` if the first row appears to be a series of column headers.
+      Inspecting each column, one of two key criteria will be considered to
+      estimate if the sample contains a header:
+
+        - the second through n-th rows contain numeric values
+        - the second through n-th rows contain strings where at least one value's
+          length differs from that of the putative header of that column.
+
+      Twenty rows after the first row are sampled; if more than half of columns +
+      rows meet the criteria, :const:`True` is returned.
+
+   .. note::
+
+      This method is a rough heuristic and may produce both false positives and
+      negatives.
 
 An example for :class:`Sniffer` use::