ENH: Improve to_string typing

pandas-stubs/_typing.pyi

@@ -39,6 +39,8 @@ from pandas._libs.tslibs import (
 
 from pandas.core.dtypes.dtypes import ExtensionDtype
 
+from pandas.io.formats.format import EngFormatter
+
 ArrayLike = Union[ExtensionArray, np.ndarray]
 AnyArrayLike = Union[Index, Series, np.ndarray]
 PythonScalar = Union[str, bool, complex]
@@ -188,7 +190,10 @@ CompressionDict = dict[str, Any]
 CompressionOptions = Optional[
     Union[Literal["infer", "gzip", "bz2", "zip", "xz", "zstd"], CompressionDict]
 ]
-
+FormattersType = Union[
+    list[Callable], tuple[Callable, ...], Mapping[Union[str, int], Callable]
+]
+FloatFormatType = str | Callable | EngFormatter
 # converters
 ConvertersArg = dict[Hashable, Callable[[Dtype], Dtype]]
 

pandas-stubs/core/frame.pyi

@@ -57,6 +57,8 @@ from pandas._typing import (
     FilePath,
     FilePathOrBuffer,
     FillnaOptions,
+    FloatFormatType,
+    FormattersType,
     GroupByObjectNonScalar,
     HashableT,
     IgnoreRaise,
@@ -347,7 +349,7 @@ class DataFrame(NDFrame, OpsMixin):
     def to_html(
         self,
         buf: FilePath | WriteBuffer[str],
-        columns: list[HashableT] | None = ...,
+        columns: list[HashableT] | Index | Series | None = ...,
         col_space: ColspaceArgType | None = ...,
         header: _bool = ...,
         index: _bool = ...,
@@ -1928,7 +1930,7 @@ class DataFrame(NDFrame, OpsMixin):
         mode: _str = ...,
         encoding: _str | None = ...,
         compression: _str | Mapping[_str, _str] = ...,
-        quoting: int | None = ...,
+        quoting: Literal[0, 1, 2, 3] | None = ...,
         quotechar: _str = ...,
         line_terminator: _str | None = ...,
         chunksize: int | None = ...,
@@ -1952,7 +1954,7 @@ class DataFrame(NDFrame, OpsMixin):
         mode: _str = ...,
         encoding: _str | None = ...,
         compression: _str | Mapping[_str, _str] = ...,
-        quoting: int | None = ...,
+        quoting: Literal[0, 1, 2, 3] | None = ...,
         quotechar: _str = ...,
         line_terminator: _str | None = ...,
         chunksize: int | None = ...,
@@ -2003,45 +2005,46 @@ class DataFrame(NDFrame, OpsMixin):
     @overload
     def to_string(
         self,
-        buf: FilePathOrBuffer | None,
-        columns: Sequence[_str] | None = ...,
-        col_space: int | list[int] | dict[_str | int, int] | None = ...,
-        header: _bool | Sequence[_str] = ...,
+        buf: FilePath | WriteBuffer[str],
+        columns: list[HashableT] | Index | Series | None = ...,
+        col_space: int | list[int] | dict[HashableT, int] | None = ...,
+        header: _bool | list[_str] | tuple[str, ...] = ...,
         index: _bool = ...,
         na_rep: _str = ...,
-        formatters=...,
-        float_format=...,
+        formatters: FormattersType | None = ...,
+        float_format: FloatFormatType | None = ...,
         sparsify: _bool | None = ...,
         index_names: _bool = ...,
         justify: _str | None = ...,
         max_rows: int | None = ...,
-        min_rows: int | None = ...,
         max_cols: int | None = ...,
         show_dimensions: _bool = ...,
         decimal: _str = ...,
         line_width: int | None = ...,
+        min_rows: int | None = ...,
         max_colwidth: int | None = ...,
         encoding: _str | None = ...,
     ) -> None: ...
     @overload
     def to_string(
         self,
-        columns: Sequence[_str] | None = ...,
-        col_space: int | list[int] | dict[_str | int, int] | None = ...,
+        buf: None = ...,
+        columns: list[HashableT] | Index | Series | None = ...,
+        col_space: int | list[int] | dict[Hashable, int] | None = ...,
         header: _bool | Sequence[_str] = ...,
         index: _bool = ...,
         na_rep: _str = ...,
-        formatters=...,
-        float_format=...,
+        formatters: FormattersType | None = ...,
+        float_format: FloatFormatType | None = ...,
         sparsify: _bool | None = ...,
         index_names: _bool = ...,
         justify: _str | None = ...,
         max_rows: int | None = ...,
-        min_rows: int | None = ...,
         max_cols: int | None = ...,
         show_dimensions: _bool = ...,
         decimal: _str = ...,
         line_width: int | None = ...,
+        min_rows: int | None = ...,
         max_colwidth: int | None = ...,
         encoding: _str | None = ...,
     ) -> _str: ...

pandas-stubs/core/generic.pyi

@@ -242,7 +242,7 @@ class NDFrame(PandasObject, indexing.IndexingMixin):
         mode: _str = ...,
         encoding: _str | None = ...,
         compression: _str | Mapping[_str, _str] = ...,
-        quoting: int | None = ...,
+        quoting: Literal[0, 1, 2, 3] | None = ...,
         quotechar: _str = ...,
         line_terminator: _str | None = ...,
         chunksize: int | None = ...,
@@ -266,7 +266,7 @@ class NDFrame(PandasObject, indexing.IndexingMixin):
         mode: _str = ...,
         encoding: _str | None = ...,
         compression: _str | Mapping[_str, _str] = ...,
-        quoting: int | None = ...,
+        quoting: Literal[0, 1, 2, 3] | None = ...,
         quotechar: _str = ...,
         line_terminator: _str | None = ...,
         chunksize: int | None = ...,

pandas-stubs/io/clipboards.pyi

@@ -71,7 +71,7 @@ def read_clipboard(
     decimal: str = ...,
     lineterminator: str | None = ...,
     quotechar: str = ...,
-    quoting: int = ...,
+    quoting: Literal[0, 1, 2, 3] | None = ...,
     doublequote: bool = ...,
     escapechar: str | None = ...,
     comment: str | None = ...,
@@ -137,7 +137,7 @@ def read_clipboard(
     decimal: str = ...,
     lineterminator: str | None = ...,
     quotechar: str = ...,
-    quoting: int = ...,
+    quoting: Literal[0, 1, 2, 3] | None = ...,
     doublequote: bool = ...,
     escapechar: str | None = ...,
     comment: str | None = ...,
@@ -203,7 +203,7 @@ def read_clipboard(
     decimal: str = ...,
     lineterminator: str | None = ...,
     quotechar: str = ...,
-    quoting: int = ...,
+    quoting: Literal[0, 1, 2, 3] | None = ...,
     doublequote: bool = ...,
     escapechar: str | None = ...,
     comment: str | None = ...,

tests/test_frame.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from collections import defaultdict
+import csv
 import datetime
 import io
 from pathlib import Path
@@ -114,6 +115,9 @@ def test_types_to_csv() -> None:
     # Testing support for binary file handles, added in 1.2.0 https://pandas.pydata.org/docs/whatsnew/v1.2.0.html
     df.to_csv(io.BytesIO(), encoding="utf-8", compression="gzip")
 
+    # Testing support for binary file handles, added in 1.2.0 https://pandas.pydata.org/docs/whatsnew/v1.2.0.html
+    df.to_csv(io.BytesIO(), quoting=csv.QUOTE_ALL, encoding="utf-8", compression="gzip")
+
 
 def test_types_to_csv_when_path_passed() -> None:
     df = pd.DataFrame(data={"col1": [1, 2], "col2": [3, 4]})

tests/test_io.py

@@ -353,6 +353,17 @@ def test_feather():
     check(assert_type(read_feather(bio), DataFrame), DataFrame)
 
 
+def test_to_string():
+    check(assert_type(DF.to_string(), str), str)
+    with ensure_clean() as path:
+        check(assert_type(DF.to_string(path), None), type(None))
+        check(assert_type(DF.to_string(pathlib.Path(path)), None), type(None))
+        with open(path, "wt") as df_string:
+            check(assert_type(DF.to_string(df_string), None), type(None))
+        sio = io.StringIO()
+        check(assert_type(DF.to_string(sio), None), type(None))
+
+
 def test_read_sql():
     with ensure_clean() as path:
         con = sqlite3.connect(path)