[3.12] docs: clarify csv.DictReader's treatment of the first data row (GH-118549...

(cherry picked from commit 9d67b72a4952766fdba803eb6eadd41dfee29dff)

Co-authored-by: Ned Batchelder <ned@nedbatchelder.com>

diff --git a/Doc/library/csv.rst b/Doc/library/csv.rst
index 4ee7820585d3a21098aa3a422e66d0d8f049e168..d17468023c6de1f28d796d8c660a8e69619efa54 100644 (file)
--- a/Doc/library/csv.rst
+++ b/Doc/library/csv.rst
@@ -156,8 +156,10 @@ The :mod:`csv` module defines the following classes:
 
    The *fieldnames* parameter is a :term:`sequence`.  If *fieldnames* is
    omitted, the values in the first row of file *f* will be used as the
-   fieldnames.  Regardless of how the fieldnames are determined, the
-   dictionary preserves their original ordering.
+   fieldnames and will be omitted from the results. If
+   *fieldnames* is provided, they will be used and the first row will be
+   included in the results.  Regardless of how the fieldnames are determined,
+   the dictionary preserves their original ordering.
 
    If a row has more fields than fieldnames, the remaining data is put in a
    list and stored with the fieldname specified by *restkey* (which defaults