ENH: Improve clipboard

pandas-stubs/_typing.pyi

@@ -211,4 +211,6 @@ MergeHow = Literal["left", "right", "outer", "inner"]
 JsonOrient = Literal["split", "records", "index", "columns", "values", "table"]
 TimestampConvention = Literal["start", "end", "s", "e"]
 
+CSVEngine = Literal["c", "python", "pyarrow", "python-fwf"]
+
 __all__ = ["npt", "type_t"]

pandas-stubs/io/clipboards.pyi

@@ -1,4 +1,225 @@
+import csv
+from typing import (
+    Any,
+    Callable,
+    Literal,
+    Sequence,
+    overload,
+)
+
+import numpy as np
 from pandas.core.frame import DataFrame
+from pandas.core.indexes.base import Index
+from pandas.core.series import Series
+
+from pandas._typing import (
+    CompressionOptions,
+    CSVEngine,
+    DtypeArg,
+    StorageOptions,
+    npt,
+)
+
+from pandas.io.parsers import TextFileReader
 
-def read_clipboard(sep: str = ..., **kwargs) -> DataFrame: ...
-def to_clipboard(obj, excel: bool = ..., sep=..., **kwargs) -> None: ...
+@overload
+def read_clipboard(
+    sep: str | None = ...,
+    *,
+    delimiter: str | None = ...,
+    header: int | Sequence[int] | Literal["infer"] | None = ...,
+    names: list[str] = ...,
+    index_col: int | str | Sequence[str | int] | Literal[False] | None = ...,
+    usecols: list[str]
+    | Sequence[int]
+    | Series
+    | Index
+    | npt.NDArray
+    | Callable[[str], bool]
+    | None = ...,
+    # squeeze: bool | None = ..., # deprecated: 1.4.0
+    # prefix: str | None = ..., # deprecated: 1.4.0
+    mangle_dupe_cols: bool = ...,  # deprecated: 1.5.0
+    dtype: DtypeArg | None = ...,
+    engine: CSVEngine | None = ...,
+    converters: dict[int | str, Callable[[str], Any]] = ...,
+    true_values: list[str] = ...,
+    false_values: list[str] = ...,
+    skipinitialspace: bool = ...,
+    skiprows: int | Sequence[int] | Callable[[int], bool] = ...,
+    skipfooter: int = ...,
+    nrows: int | None = ...,
+    na_values: Sequence[str] | dict[str, Sequence[str]] = ...,
+    keep_default_na: bool = ...,
+    na_filter: bool = ...,
+    verbose: bool = ...,
+    skip_blank_lines: bool = ...,
+    parse_dates: bool
+    | Sequence[int]
+    | list[str]
+    | Sequence[Sequence[int]]
+    | dict[str, Sequence[int]] = ...,
+    infer_datetime_format: bool = ...,
+    keep_date_col: bool = ...,
+    date_parser: Callable = ...,
+    dayfirst: bool = ...,
+    cache_dates: bool = ...,
+    iterator: Literal[True],
+    chunksize: int | None = ...,
+    compression: CompressionOptions = ...,
+    thousands: str | None = ...,
+    decimal: str = ...,
+    lineterminator: str | None = ...,
+    quotechar: str = ...,
+    quoting: int = ...,
+    doublequote: bool = ...,
+    escapechar: str | None = ...,
+    comment: str | None = ...,
+    encoding: str | None = ...,
+    encoding_errors: str | None = ...,
+    dialect: str | csv.Dialect = ...,
+    # error_bad_lines: bool | None = ...,  # Deprecated: 1.3.0
+    # warn_bad_lines: bool | None = ...,  # Deprecated: 1.3.0
+    on_bad_lines: Literal["error", "warn", "skip"]
+    | Callable[[list[str]], list[str] | None] = ...,
+    delim_whitespace: bool = ...,
+    low_memory: bool = ...,
+    memory_map: bool = ...,
+    float_precision: Literal["high", "legacy", "round_trip"] | None = ...,
+    storage_options: StorageOptions | None = ...,
+) -> TextFileReader: ...
+@overload
+def read_clipboard(
+    sep: str | None = ...,
+    *,
+    delimiter: str | None = ...,
+    header: int | Sequence[int] | Literal["infer"] | None = ...,
+    names: list[str] = ...,
+    index_col: int | str | Sequence[str | int] | Literal[False] | None = ...,
+    usecols: list[str]
+    | Sequence[int]
+    | Series
+    | Index
+    | npt.NDArray
+    | Callable[[str], bool]
+    | None = ...,
+    # squeeze: bool | None = ..., # deprecated: 1.4.0
+    # prefix: str | None = ..., # deprecated: 1.4.0
+    mangle_dupe_cols: bool = ...,  # deprecated: 1.5.0
+    dtype: DtypeArg | None = ...,
+    engine: CSVEngine | None = ...,
+    converters: dict[int | str, Callable[[str], Any]] = ...,
+    true_values: list[str] = ...,
+    false_values: list[str] = ...,
+    skipinitialspace: bool = ...,
+    skiprows: int | Sequence[int] | Callable[[int], bool] = ...,
+    skipfooter: int = ...,
+    nrows: int | None = ...,
+    na_values: Sequence[str] | dict[str, Sequence[str]] = ...,
+    keep_default_na: bool = ...,
+    na_filter: bool = ...,
+    verbose: bool = ...,
+    skip_blank_lines: bool = ...,
+    parse_dates: bool
+    | Sequence[int]
+    | list[str]
+    | Sequence[Sequence[int]]
+    | dict[str, Sequence[int]] = ...,
+    infer_datetime_format: bool = ...,
+    keep_date_col: bool = ...,
+    date_parser: Callable = ...,
+    dayfirst: bool = ...,
+    cache_dates: bool = ...,
+    iterator: bool = ...,
+    chunksize: int,
+    compression: CompressionOptions = ...,
+    thousands: str | None = ...,
+    decimal: str = ...,
+    lineterminator: str | None = ...,
+    quotechar: str = ...,
+    quoting: int = ...,
+    doublequote: bool = ...,
+    escapechar: str | None = ...,
+    comment: str | None = ...,
+    encoding: str | None = ...,
+    encoding_errors: str | None = ...,
+    dialect: str | csv.Dialect = ...,
+    # error_bad_lines: bool | None = ...,  # Deprecated: 1.3.0
+    # warn_bad_lines: bool | None = ...,  # Deprecated: 1.3.0
+    on_bad_lines: Literal["error", "warn", "skip"]
+    | Callable[[list[str]], list[str] | None] = ...,
+    delim_whitespace: bool = ...,
+    low_memory: bool = ...,
+    memory_map: bool = ...,
+    float_precision: Literal["high", "legacy", "round_trip"] | None = ...,
+    storage_options: StorageOptions | None = ...,
+) -> TextFileReader: ...
+@overload
+def read_clipboard(
+    sep: str | None = ...,
+    *,
+    delimiter: str | None = ...,
+    header: int | Sequence[int] | Literal["infer"] | None = ...,
+    names: list[str] = ...,
+    index_col: int | str | Sequence[str | int] | Literal[False] | None = ...,
+    usecols: list[str]
+    | Sequence[int]
+    | Series
+    | Index
+    | npt.NDArray
+    | Callable[[str], bool]
+    | None = ...,
+    # squeeze: bool | None = ..., # deprecated: 1.4.0
+    # prefix: str | None = ..., # deprecated: 1.4.0
+    mangle_dupe_cols: bool = ...,  # deprecated: 1.5.0
+    dtype: DtypeArg | None = ...,
+    engine: CSVEngine | None = ...,
+    converters: dict[int | str, Callable[[str], Any]] = ...,
+    true_values: list[str] = ...,
+    false_values: list[str] = ...,
+    skipinitialspace: bool = ...,
+    skiprows: int | Sequence[int] | Callable[[int], bool] = ...,
+    skipfooter: int = ...,
+    nrows: int | None = ...,
+    na_values: Sequence[str] | dict[str, Sequence[str]] = ...,
+    keep_default_na: bool = ...,
+    na_filter: bool = ...,
+    verbose: bool = ...,
+    skip_blank_lines: bool = ...,
+    parse_dates: bool
+    | Sequence[int]
+    | list[str]
+    | Sequence[Sequence[int]]
+    | dict[str, Sequence[int]] = ...,
+    infer_datetime_format: bool = ...,
+    keep_date_col: bool = ...,
+    date_parser: Callable = ...,
+    dayfirst: bool = ...,
+    cache_dates: bool = ...,
+    iterator: Literal[False] = ...,
+    chunksize: None = ...,
+    compression: CompressionOptions = ...,
+    thousands: str | None = ...,
+    decimal: str = ...,
+    lineterminator: str | None = ...,
+    quotechar: str = ...,
+    quoting: int = ...,
+    doublequote: bool = ...,
+    escapechar: str | None = ...,
+    comment: str | None = ...,
+    encoding: str | None = ...,
+    encoding_errors: str | None = ...,
+    dialect: str | csv.Dialect = ...,
+    # error_bad_lines: bool | None = ...,  # Deprecated: 1.3.0
+    # warn_bad_lines: bool | None = ...,  # Deprecated: 1.3.0
+    on_bad_lines: Literal["error", "warn", "skip"]
+    | Callable[[list[str]], list[str] | None] = ...,
+    delim_whitespace: bool = ...,
+    low_memory: bool = ...,
+    memory_map: bool = ...,
+    float_precision: Literal["high", "legacy", "round_trip"] | None = ...,
+    storage_options: StorageOptions | None = ...,
+) -> DataFrame: ...
+def to_clipboard(
+    obj, excel: bool = ..., sep: str | None = ..., **kwargs: Any
+) -> None: ...

tests/test_io.py

@@ -0,0 +1,40 @@
+from pandas import (
+    DataFrame,
+    read_clipboard,
+)
+import pytest
+from typing_extensions import assert_type
+
+from tests import check
+
+from pandas.io.clipboard import PyperclipException
+from pandas.io.parsers import TextFileReader
+
+DF = DataFrame({"a": [1, 2, 3], "b": [0.0, 0.0, 0.0]})
+
+
+def test_clipboard():
+    try:
+        DF.to_clipboard()
+    except PyperclipException:
+        pytest.skip("clipboard not available for testing")
+    check(assert_type(read_clipboard(), DataFrame), DataFrame)
+    check(assert_type(read_clipboard(iterator=False), DataFrame), DataFrame)
+    check(assert_type(read_clipboard(chunksize=None), DataFrame), DataFrame)
+
+
+def test_clipboard_iterator():
+    try:
+        DF.to_clipboard()
+    except PyperclipException:
+        pytest.skip("clipboard not available for testing")
+    check(assert_type(read_clipboard(iterator=True), TextFileReader), TextFileReader)
+    check(
+        assert_type(read_clipboard(iterator=True, chunksize=None), TextFileReader),
+        TextFileReader,
+    )
+    check(assert_type(read_clipboard(chunksize=1), TextFileReader), TextFileReader)
+    check(
+        assert_type(read_clipboard(iterator=False, chunksize=1), TextFileReader),
+        TextFileReader,
+    )