_csv.Reader and _csv.Writer (#13057)

stdlib/@tests/stubtest_allowlists/py310.txt

@@ -110,8 +110,6 @@ _collections_abc.Awaitable.__class_getitem__
 _collections_abc.Container.__class_getitem__
 _collections_abc.Iterable.__class_getitem__
 _collections_abc.MappingView.__class_getitem__
-_csv.Reader
-_csv.Writer
 bdb.Breakpoint.clearBreakpoints
 inspect.Signature.from_builtin  # Removed in 3.11, can add if someone needs this
 inspect.Signature.from_function  # Removed in 3.11, can add if someone needs this

stdlib/@tests/stubtest_allowlists/py311.txt

@@ -3,8 +3,6 @@ _collections_abc.Awaitable.__class_getitem__
 _collections_abc.Container.__class_getitem__
 _collections_abc.Iterable.__class_getitem__
 _collections_abc.MappingView.__class_getitem__
-_csv.Reader
-_csv.Writer
 _?bz2.BZ2Decompressor.__init__  # function does not accept parameters but C signature is set
 configparser.ParsingError.filename
 collections\.UserList\.index  # ignoring pos-or-keyword parameter

stdlib/@tests/stubtest_allowlists/py312.txt

@@ -7,8 +7,6 @@ _collections_abc.Awaitable.__class_getitem__
 _collections_abc.Container.__class_getitem__
 _collections_abc.Iterable.__class_getitem__
 _collections_abc.MappingView.__class_getitem__
-_csv.Reader
-_csv.Writer
 enum.Enum.__init__
 importlib._abc.Loader.exec_module  # See Lib/importlib/_abc.py. Might be defined for backwards compatibility
 lib2to3.pygram.pattern_symbols

stdlib/@tests/stubtest_allowlists/py313.txt

@@ -38,8 +38,6 @@ _collections_abc.Awaitable.__class_getitem__
 _collections_abc.Container.__class_getitem__
 _collections_abc.Iterable.__class_getitem__
 _collections_abc.MappingView.__class_getitem__
-_csv.Reader
-_csv.Writer
 enum.Enum.__init__
 importlib._abc.Loader.exec_module  # See Lib/importlib/_abc.py. Might be defined for backwards compatibility
 typing.NewType.__mro_entries__

stdlib/_csv.pyi

@@ -1,9 +1,9 @@
 import csv
 import sys
 from _typeshed import SupportsWrite
-from collections.abc import Iterable, Iterator
-from typing import Any, Final
-from typing_extensions import TypeAlias
+from collections.abc import Iterable
+from typing import Any, Final, type_check_only
+from typing_extensions import Self, TypeAlias
 
 __version__: Final[str]
 
@@ -45,17 +45,47 @@ class Dialect:
         strict: bool = False,
     ) -> None: ...
 
-class _reader(Iterator[list[str]]):
-    @property
-    def dialect(self) -> Dialect: ...
-    line_num: int
-    def __next__(self) -> list[str]: ...
+if sys.version_info >= (3, 10):
+    # This class calls itself _csv.reader.
+    class Reader:
+        @property
+        def dialect(self) -> Dialect: ...
+        line_num: int
+        def __iter__(self) -> Self: ...
+        def __next__(self) -> list[str]: ...
 
-class _writer:
-    @property
-    def dialect(self) -> Dialect: ...
-    def writerow(self, row: Iterable[Any]) -> Any: ...
-    def writerows(self, rows: Iterable[Iterable[Any]]) -> None: ...
+    # This class calls itself _csv.writer.
+    class Writer:
+        @property
+        def dialect(self) -> Dialect: ...
+        if sys.version_info >= (3, 13):
+            def writerow(self, row: Iterable[Any], /) -> Any: ...
+            def writerows(self, rows: Iterable[Iterable[Any]], /) -> None: ...
+        else:
+            def writerow(self, row: Iterable[Any]) -> Any: ...
+            def writerows(self, rows: Iterable[Iterable[Any]]) -> None: ...
+
+    # For the return types below.
+    # These aliases can be removed when typeshed drops support for 3.9.
+    _reader = Reader
+    _writer = Writer
+else:
+    # This class is not exposed. It calls itself _csv.reader.
+    @type_check_only
+    class _reader:
+        @property
+        def dialect(self) -> Dialect: ...
+        line_num: int
+        def __iter__(self) -> Self: ...
+        def __next__(self) -> list[str]: ...
+
+    # This class is not exposed. It calls itself _csv.writer.
+    @type_check_only
+    class _writer:
+        @property
+        def dialect(self) -> Dialect: ...
+        def writerow(self, row: Iterable[Any]) -> Any: ...
+        def writerows(self, rows: Iterable[Iterable[Any]]) -> None: ...
 
 def writer(
     csvfile: SupportsWrite[str],

stdlib/csv.pyi

@@ -8,8 +8,6 @@ from _csv import (
     __version__ as __version__,
     _DialectLike,
     _QuotingType,
-    _reader,
-    _writer,
     field_size_limit as field_size_limit,
     get_dialect as get_dialect,
     list_dialects as list_dialects,
@@ -21,6 +19,10 @@ from _csv import (
 
 if sys.version_info >= (3, 12):
     from _csv import QUOTE_NOTNULL as QUOTE_NOTNULL, QUOTE_STRINGS as QUOTE_STRINGS
+if sys.version_info >= (3, 10):
+    from _csv import Reader, Writer
+else:
+    from _csv import _reader as Reader, _writer as Writer
 
 from _typeshed import SupportsWrite
 from collections.abc import Collection, Iterable, Mapping, Sequence
@@ -77,7 +79,7 @@ class DictReader(Generic[_T]):
     fieldnames: Sequence[_T] | None
     restkey: _T | None
     restval: str | Any | None
-    reader: _reader
+    reader: Reader
     dialect: _DialectLike
     line_num: int
     @overload
@@ -125,7 +127,7 @@ class DictWriter(Generic[_T]):
     fieldnames: Collection[_T]
     restval: Any | None
     extrasaction: Literal["raise", "ignore"]
-    writer: _writer
+    writer: Writer
     def __init__(
         self,
         f: SupportsWrite[str],