From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
Date: Sat, 16 Dec 2023 08:18:45 +0000 (+0100)
Subject: [3.11] gh-113046: Revise csv.reader doc (GH-113207) (#113211)
X-Git-Tag: v3.11.8~256
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=2be7a7296f5b31a4f674fa98ff8338690a093d91;p=thirdparty%2FPython%2Fcpython.git

[3.11] gh-113046: Revise csv.reader doc (GH-113207) (#113211)

Clarify nature of csvfile.
(cherry picked from commit 84df3172efe8767ddf5c28bdb6696b3f216bcaa6)

Co-authored-by: Terry Jan Reedy <tjreedy@udel.edu>
---

diff --git a/Doc/library/csv.rst b/Doc/library/csv.rst
index 3983d7f9b6a4..b55212630555 100644
--- a/Doc/library/csv.rst
+++ b/Doc/library/csv.rst
@@ -55,10 +55,11 @@ The :mod:`csv` module defines the following functions:
 
 .. function:: reader(csvfile, dialect='excel', **fmtparams)
 
-   Return a reader object which will iterate over lines in the given *csvfile*.
-   *csvfile* can be any object which supports the :term:`iterator` protocol and returns a
-   string each time its :meth:`!__next__` method is called --- :term:`file objects
-   <file object>` and list objects are both suitable.   If *csvfile* is a file object,
+   Return a :ref:`reader object <reader-objects>` that will process
+   lines from the given *csvfile*.  A csvfile must be an iterable of
+   strings, each in the reader's defined csv format.
+   A csvfile is most commonly a file-like object or list.
+   If *csvfile* is a file object,
    it should be opened with ``newline=''``. [1]_  An optional
    *dialect* parameter can be given which is used to define a set of parameters
    specific to a particular CSV dialect.  It may be an instance of a subclass of
@@ -427,6 +428,8 @@ Dialects support the following attributes:
    When ``True``, raise exception :exc:`Error` on bad CSV input.
    The default is ``False``.
 
+.. _reader-objects:
+
 Reader Objects
 --------------