TYP: pandas/io annotations from pandas-stubs (#47831)

Author: twoertwein

pandas/errors/__init__.py

@@ -189,7 +189,7 @@ class AbstractMethodError(NotImplementedError):
     while keeping compatibility with Python 2 and Python 3.
     """
 
-    def __init__(self, class_instance, methodtype="method") -> None:
+    def __init__(self, class_instance, methodtype: str = "method") -> None:
         types = {"method", "classmethod", "staticmethod", "property"}
         if methodtype not in types:
             raise ValueError(

pandas/io/excel/_base.py

@@ -359,13 +359,18 @@ def read_excel(
     # sheet name is str or int -> DataFrame
     sheet_name: str | int,
     header: int | Sequence[int] | None = ...,
-    names=...,
+    names: list[str] | None = ...,
     index_col: int | Sequence[int] | None = ...,
-    usecols=...,
+    usecols: int
+    | str
+    | Sequence[int]
+    | Sequence[str]
+    | Callable[[str], bool]
+    | None = ...,
     squeeze: bool | None = ...,
     dtype: DtypeArg | None = ...,
     engine: Literal["xlrd", "openpyxl", "odf", "pyxlsb"] | None = ...,
-    converters=...,
+    converters: dict[str, Callable] | dict[int, Callable] | None = ...,
     true_values: Iterable[Hashable] | None = ...,
     false_values: Iterable[Hashable] | None = ...,
     skiprows: Sequence[int] | int | Callable[[int], object] | None = ...,
@@ -374,8 +379,8 @@ def read_excel(
     keep_default_na: bool = ...,
     na_filter: bool = ...,
     verbose: bool = ...,
-    parse_dates=...,
-    date_parser=...,
+    parse_dates: list | dict | bool = ...,
+    date_parser: Callable | None = ...,
     thousands: str | None = ...,
     decimal: str = ...,
     comment: str | None = ...,
@@ -393,13 +398,18 @@ def read_excel(
     # sheet name is list or None -> dict[IntStrT, DataFrame]
     sheet_name: list[IntStrT] | None,
     header: int | Sequence[int] | None = ...,
-    names=...,
+    names: list[str] | None = ...,
     index_col: int | Sequence[int] | None = ...,
-    usecols=...,
+    usecols: int
+    | str
+    | Sequence[int]
+    | Sequence[str]
+    | Callable[[str], bool]
+    | None = ...,
     squeeze: bool | None = ...,
     dtype: DtypeArg | None = ...,
     engine: Literal["xlrd", "openpyxl", "odf", "pyxlsb"] | None = ...,
-    converters=...,
+    converters: dict[str, Callable] | dict[int, Callable] | None = ...,
     true_values: Iterable[Hashable] | None = ...,
     false_values: Iterable[Hashable] | None = ...,
     skiprows: Sequence[int] | int | Callable[[int], object] | None = ...,
@@ -408,8 +418,8 @@ def read_excel(
     keep_default_na: bool = ...,
     na_filter: bool = ...,
     verbose: bool = ...,
-    parse_dates=...,
-    date_parser=...,
+    parse_dates: list | dict | bool = ...,
+    date_parser: Callable | None = ...,
     thousands: str | None = ...,
     decimal: str = ...,
     comment: str | None = ...,
@@ -428,13 +438,18 @@ def read_excel(
     io,
     sheet_name: str | int | list[IntStrT] | None = 0,
     header: int | Sequence[int] | None = 0,
-    names=None,
+    names: list[str] | None = None,
     index_col: int | Sequence[int] | None = None,
-    usecols=None,
+    usecols: int
+    | str
+    | Sequence[int]
+    | Sequence[str]
+    | Callable[[str], bool]
+    | None = None,
     squeeze: bool | None = None,
     dtype: DtypeArg | None = None,
     engine: Literal["xlrd", "openpyxl", "odf", "pyxlsb"] | None = None,
-    converters=None,
+    converters: dict[str, Callable] | dict[int, Callable] | None = None,
     true_values: Iterable[Hashable] | None = None,
     false_values: Iterable[Hashable] | None = None,
     skiprows: Sequence[int] | int | Callable[[int], object] | None = None,
@@ -443,8 +458,8 @@ def read_excel(
     keep_default_na: bool = True,
     na_filter: bool = True,
     verbose: bool = False,
-    parse_dates=False,
-    date_parser=None,
+    parse_dates: list | dict | bool = False,
+    date_parser: Callable | None = None,
     thousands: str | None = None,
     decimal: str = ".",
     comment: str | None = None,
@@ -687,8 +702,8 @@ def parse(
         nrows: int | None = None,
         na_values=None,
         verbose: bool = False,
-        parse_dates=False,
-        date_parser=None,
+        parse_dates: list | dict | bool = False,
+        date_parser: Callable | None = None,
         thousands: str | None = None,
         decimal: str = ".",
         comment: str | None = None,
@@ -1665,8 +1680,8 @@ def parse(
         skiprows: Sequence[int] | int | Callable[[int], object] | None = None,
         nrows: int | None = None,
         na_values=None,
-        parse_dates=False,
-        date_parser=None,
+        parse_dates: list | dict | bool = False,
+        date_parser: Callable | None = None,
         thousands: str | None = None,
         comment: str | None = None,
         skipfooter: int = 0,

pandas/io/formats/excel.py

@@ -853,9 +853,9 @@ def get_formatted_cells(self) -> Iterable[ExcelCell]:
     def write(
         self,
         writer,
-        sheet_name="Sheet1",
-        startrow=0,
-        startcol=0,
+        sheet_name: str = "Sheet1",
+        startrow: int = 0,
+        startcol: int = 0,
         freeze_panes=None,
         engine=None,
         storage_options: StorageOptions = None,

pandas/io/formats/format.py

@@ -20,6 +20,7 @@
     TYPE_CHECKING,
     Any,
     Callable,
+    Final,
     Hashable,
     Iterable,
     Iterator,
@@ -117,7 +118,7 @@
     )
 
 
-common_docstring = """
+common_docstring: Final = """
         Parameters
         ----------
         buf : str, Path or StringIO-like, optional, default None
@@ -190,7 +191,7 @@
     "unset",
 )
 
-return_docstring = """
+return_docstring: Final = """
         Returns
         -------
         str or None

pandas/io/formats/html.py

@@ -6,6 +6,7 @@
 from textwrap import dedent
 from typing import (
     Any,
+    Final,
     Hashable,
     Iterable,
     Mapping,
@@ -39,7 +40,7 @@ class HTMLFormatter:
     and this class responsible for only producing html markup.
     """
 
-    indent_delta = 2
+    indent_delta: Final = 2
 
     def __init__(
         self,

pandas/io/formats/style.py

@@ -3332,7 +3332,7 @@ def highlight_null(
         color: str | None = None,
         subset: Subset | None = None,
         props: str | None = None,
-        null_color=lib.no_default,
+        null_color: str | lib.NoDefault = lib.no_default,
     ) -> Styler:
         """
         Highlight missing values with a style.

pandas/io/html.py

@@ -10,6 +10,7 @@
 import numbers
 import re
 from typing import (
+    Iterable,
     Pattern,
     Sequence,
     cast,
@@ -971,7 +972,7 @@ def read_html(
     encoding: str | None = None,
     decimal: str = ".",
     converters: dict | None = None,
-    na_values=None,
+    na_values: Iterable[object] | None = None,
     keep_default_na: bool = True,
     displayed_only: bool = True,
 ) -> list[DataFrame]:

pandas/io/json/_json.py

@@ -365,16 +365,16 @@ def obj_to_write(self) -> NDFrame | Mapping[IndexLabel, Any]:
 def read_json(
     path_or_buf: FilePath | ReadBuffer[str] | ReadBuffer[bytes],
     *,
-    orient=...,
+    orient: str | None = ...,
     typ: Literal["frame"] = ...,
     dtype: DtypeArg | None = ...,
     convert_axes=...,
-    convert_dates=...,
+    convert_dates: bool | list[str] = ...,
     keep_default_dates: bool = ...,
     numpy: bool = ...,
     precise_float: bool = ...,
-    date_unit=...,
-    encoding=...,
+    date_unit: str | None = ...,
+    encoding: str | None = ...,
     encoding_errors: str | None = ...,
     lines: bool = ...,
     chunksize: int,
@@ -389,16 +389,16 @@ def read_json(
 def read_json(
     path_or_buf: FilePath | ReadBuffer[str] | ReadBuffer[bytes],
     *,
-    orient=...,
+    orient: str | None = ...,
     typ: Literal["series"],
     dtype: DtypeArg | None = ...,
     convert_axes=...,
-    convert_dates=...,
+    convert_dates: bool | list[str] = ...,
     keep_default_dates: bool = ...,
     numpy: bool = ...,
     precise_float: bool = ...,
-    date_unit=...,
-    encoding=...,
+    date_unit: str | None = ...,
+    encoding: str | None = ...,
     encoding_errors: str | None = ...,
     lines: bool = ...,
     chunksize: int,
@@ -413,16 +413,16 @@ def read_json(
 def read_json(
     path_or_buf: FilePath | ReadBuffer[str] | ReadBuffer[bytes],
     *,
-    orient=...,
+    orient: str | None = ...,
     typ: Literal["series"],
     dtype: DtypeArg | None = ...,
     convert_axes=...,
-    convert_dates=...,
+    convert_dates: bool | list[str] = ...,
     keep_default_dates: bool = ...,
     numpy: bool = ...,
     precise_float: bool = ...,
-    date_unit=...,
-    encoding=...,
+    date_unit: str | None = ...,
+    encoding: str | None = ...,
     encoding_errors: str | None = ...,
     lines: bool = ...,
     chunksize: None = ...,
@@ -436,16 +436,16 @@ def read_json(
 @overload
 def read_json(
     path_or_buf: FilePath | ReadBuffer[str] | ReadBuffer[bytes],
-    orient=...,
+    orient: str | None = ...,
     typ: Literal["frame"] = ...,
     dtype: DtypeArg | None = ...,
     convert_axes=...,
-    convert_dates=...,
+    convert_dates: bool | list[str] = ...,
     keep_default_dates: bool = ...,
     numpy: bool = ...,
     precise_float: bool = ...,
-    date_unit=...,
-    encoding=...,
+    date_unit: str | None = ...,
+    encoding: str | None = ...,
     encoding_errors: str | None = ...,
     lines: bool = ...,
     chunksize: None = ...,
@@ -464,16 +464,16 @@ def read_json(
 @deprecate_nonkeyword_arguments(version="2.0", allowed_args=["path_or_buf"])
 def read_json(
     path_or_buf: FilePath | ReadBuffer[str] | ReadBuffer[bytes],
-    orient=None,
+    orient: str | None = None,
     typ: Literal["frame", "series"] = "frame",
     dtype: DtypeArg | None = None,
     convert_axes=None,
-    convert_dates=True,
+    convert_dates: bool | list[str] = True,
     keep_default_dates: bool = True,
     numpy: bool = False,
     precise_float: bool = False,
-    date_unit=None,
-    encoding=None,
+    date_unit: str | None = None,
+    encoding: str | None = None,
     encoding_errors: str | None = "strict",
     lines: bool = False,
     chunksize: int | None = None,
@@ -1009,11 +1009,11 @@ def __init__(
         json,
         orient,
         dtype: DtypeArg | None = None,
-        convert_axes=True,
-        convert_dates=True,
-        keep_default_dates=False,
-        numpy=False,
-        precise_float=False,
+        convert_axes: bool = True,
+        convert_dates: bool | list[str] = True,
+        keep_default_dates: bool = False,
+        numpy: bool = False,
+        precise_float: bool = False,
         date_unit=None,
     ) -> None:
         self.json = json
@@ -1093,7 +1093,11 @@ def _try_convert_types(self):
         raise AbstractMethodError(self)
 
     def _try_convert_data(
-        self, name, data, use_dtypes: bool = True, convert_dates: bool = True
+        self,
+        name,
+        data,
+        use_dtypes: bool = True,
+        convert_dates: bool | list[str] = True,
     ):
         """
         Try to parse a ndarray like into a column by inferring dtype.
@@ -1375,10 +1379,10 @@ def _try_convert_dates(self):
             return
 
         # our columns to parse
-        convert_dates = self.convert_dates
-        if convert_dates is True:
-            convert_dates = []
-        convert_dates = set(convert_dates)
+        convert_dates_list_bool = self.convert_dates
+        if isinstance(convert_dates_list_bool, bool):
+            convert_dates_list_bool = []
+        convert_dates = set(convert_dates_list_bool)
 
         def is_ok(col) -> bool:
             """

pandas/io/parquet.py

@@ -444,9 +444,9 @@ def to_parquet(
 
 @doc(storage_options=_shared_docs["storage_options"])
 def read_parquet(
-    path,
+    path: FilePath | ReadBuffer[bytes],
     engine: str = "auto",
-    columns=None,
+    columns: list[str] | None = None,
     storage_options: StorageOptions = None,
     use_nullable_dtypes: bool = False,
     **kwargs,