MAINT: Merge main

pandas-stubs/_typing.pyi

@@ -228,4 +228,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

@@ -1,20 +1,16 @@
-from __future__ import annotations
-
-from contextlib import contextmanager
-from pathlib import Path
-import tempfile
-from typing import (
-    IO,
-    Any,
-)
-import uuid
-
 import pandas as pd
-from pandas import DataFrame
+from pandas import (
+    DataFrame,
+    read_clipboard,
+)
+from pandas._testing import ensure_clean
+import pytest
 from typing_extensions import assert_type
 
 from tests import check
 
+from pandas.io.clipboard import PyperclipException
+from pandas.io.parsers import TextFileReader
 from pandas.io.stata import (
     StataReader,
     read_stata,
@@ -23,46 +19,6 @@
 DF = DataFrame({"a": [1, 2, 3], "b": [0.0, 0.0, 0.0]})
 
 
-@contextmanager
-def ensure_clean(filename=None, return_filelike: bool = False, **kwargs: Any):
-    """
-    Gets a temporary path and agrees to remove on close.
-    This implementation does not use tempfile.mkstemp to avoid having a file handle.
-    If the code using the returned path wants to delete the file itself, windows
-    requires that no program has a file handle to it.
-    Parameters
-    ----------
-    filename : str (optional)
-        suffix of the created file.
-    return_filelike : bool (default False)
-        if True, returns a file-like which is *always* cleaned. Necessary for
-        savefig and other functions which want to append extensions.
-    **kwargs
-        Additional keywords are passed to open().
-    """
-    folder = Path(tempfile.gettempdir())
-
-    if filename is None:
-        filename = ""
-    filename = str(uuid.uuid4()) + filename
-    path = folder / filename
-
-    path.touch()
-
-    handle_or_str: str | IO = str(path)
-    if return_filelike:
-        kwargs.setdefault("mode", "w+b")
-        handle_or_str = open(path, **kwargs)
-
-    try:
-        yield handle_or_str
-    finally:
-        if not isinstance(handle_or_str, str):
-            handle_or_str.close()
-        if path.is_file():
-            path.unlink()
-
-
 def test_read_stata_df():
     with ensure_clean() as path:
         DF.to_stata(path)
@@ -91,3 +47,30 @@ def test_read_stata_iterator():
         check(
             assert_type(read_stata(str_path, iterator=True), StataReader), StataReader
         )
+
+
+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,
+    )