TYP: more return annotations for io/* (#47524)

* TYP: more return annotations for io/*

* import future

Author: twoertwein

pandas/io/common.py

@@ -925,7 +925,7 @@ class _BufferedWriter(BytesIO, ABC):  # type: ignore[misc]
     """
 
     @abstractmethod
-    def write_to_buffer(self):
+    def write_to_buffer(self) -> None:
         ...
 
     def close(self) -> None:

pandas/io/date_converters.py

@@ -1,13 +1,16 @@
 """This module is designed for community supported date conversion functions"""
+from __future__ import annotations
+
 import warnings
 
 import numpy as np
 
 from pandas._libs.tslibs import parsing
+from pandas._typing import npt
 from pandas.util._exceptions import find_stack_level
 
 
-def parse_date_time(date_col, time_col):
+def parse_date_time(date_col, time_col) -> npt.NDArray[np.object_]:
     """
     Parse columns with dates and times into a single datetime column.
 
@@ -26,7 +29,7 @@ def parse_date_time(date_col, time_col):
     return parsing.try_parse_date_and_time(date_col, time_col)
 
 
-def parse_date_fields(year_col, month_col, day_col):
+def parse_date_fields(year_col, month_col, day_col) -> npt.NDArray[np.object_]:
     """
     Parse columns with years, months and days into a single date column.
 
@@ -48,7 +51,9 @@ def parse_date_fields(year_col, month_col, day_col):
     return parsing.try_parse_year_month_day(year_col, month_col, day_col)
 
 
-def parse_all_fields(year_col, month_col, day_col, hour_col, minute_col, second_col):
+def parse_all_fields(
+    year_col, month_col, day_col, hour_col, minute_col, second_col
+) -> npt.NDArray[np.object_]:
     """
     Parse columns with datetime information into a single datetime column.
 
@@ -78,7 +83,7 @@ def parse_all_fields(year_col, month_col, day_col, hour_col, minute_col, second_
     )
 
 
-def generic_parser(parse_func, *cols):
+def generic_parser(parse_func, *cols) -> np.ndarray:
     """
     Use dateparser to parse columns with data information into a single datetime column.
 

pandas/io/excel/_base.py

@@ -1069,7 +1069,7 @@ class ExcelWriter(metaclass=abc.ABCMeta):
     _supported_extensions: tuple[str, ...]
 
     def __new__(
-        cls,
+        cls: type[ExcelWriter],
         path: FilePath | WriteExcelBuffer | ExcelWriter,
         engine: str | None = None,
         date_format: str | None = None,
@@ -1079,7 +1079,7 @@ def __new__(
         if_sheet_exists: Literal["error", "new", "replace", "overlay"] | None = None,
         engine_kwargs: dict | None = None,
         **kwargs,
-    ):
+    ) -> ExcelWriter:
         if kwargs:
             if engine_kwargs is not None:
                 raise ValueError("Cannot use both engine_kwargs and **kwargs")
@@ -1325,7 +1325,7 @@ def cur_sheet(self):
         return self._cur_sheet
 
     @property
-    def handles(self):
+    def handles(self) -> IOHandles[bytes]:
         """
         Handles to Excel sheets.
 
@@ -1344,7 +1344,7 @@ def path(self):
         self._deprecate("path")
         return self._path
 
-    def __fspath__(self):
+    def __fspath__(self) -> str:
         return getattr(self._handles.handle, "name", "")
 
     def _get_sheet_name(self, sheet_name: str | None) -> str:
@@ -1402,10 +1402,10 @@ def check_extension(cls, ext: str) -> Literal[True]:
             return True
 
     # Allow use as a contextmanager
-    def __enter__(self):
+    def __enter__(self) -> ExcelWriter:
         return self
 
-    def __exit__(self, exc_type, exc_value, traceback):
+    def __exit__(self, exc_type, exc_value, traceback) -> None:
         self.close()
 
     def close(self) -> None:
@@ -1699,13 +1699,13 @@ def close(self) -> None:
         """close io if necessary"""
         self._reader.close()
 
-    def __enter__(self):
+    def __enter__(self) -> ExcelFile:
         return self
 
-    def __exit__(self, exc_type, exc_value, traceback):
+    def __exit__(self, exc_type, exc_value, traceback) -> None:
         self.close()
 
-    def __del__(self):
+    def __del__(self) -> None:
         # Ensure we don't leak file descriptors, but put in try/except in case
         # attributes are already deleted
         try:

pandas/io/excel/_openpyxl.py

@@ -33,6 +33,7 @@
 
 if TYPE_CHECKING:
     from openpyxl.descriptors.serialisable import Serialisable
+    from openpyxl.workbook import Workbook
 
 
 class OpenpyxlWriter(ExcelWriter):
@@ -79,7 +80,7 @@ def __init__(
                 self.book.remove(self.book.worksheets[0])
 
     @property
-    def book(self):
+    def book(self) -> Workbook:
         """
         Book instance of class openpyxl.workbook.Workbook.
 

pandas/io/feather_format.py

@@ -31,7 +31,7 @@ def to_feather(
     path: FilePath | WriteBuffer[bytes],
     storage_options: StorageOptions = None,
     **kwargs,
-):
+) -> None:
     """
     Write a DataFrame to the binary Feather format.
 

pandas/io/parsers/base_parser.py

@@ -220,7 +220,7 @@ def _validate_parse_dates_presence(self, columns: Sequence[Hashable]) -> Iterabl
             for col in cols_needed
         ]
 
-    def close(self):
+    def close(self) -> None:
         pass
 
     @final

pandas/io/parsers/python_parser.py

@@ -308,7 +308,11 @@ def _exclude_implicit_index(
         }, names
 
     # legacy
-    def get_chunk(self, size=None):
+    def get_chunk(
+        self, size: int | None = None
+    ) -> tuple[
+        Index | None, Sequence[Hashable] | MultiIndex, Mapping[Hashable, ArrayLike]
+    ]:
         if size is None:
             # error: "PythonParser" has no attribute "chunksize"
             size = self.chunksize  # type: ignore[attr-defined]

pandas/io/parsers/readers.py

@@ -493,7 +493,22 @@ class _DeprecationConfig(NamedTuple):
 }
 
 
-def validate_integer(name, val, min_val=0):
+@overload
+def validate_integer(name, val: None, min_val=...) -> None:
+    ...
+
+
+@overload
+def validate_integer(name, val: int | float, min_val=...) -> int:
+    ...
+
+
+@overload
+def validate_integer(name, val: int | None, min_val=...) -> int | None:
+    ...
+
+
+def validate_integer(name, val: int | float | None, min_val=0) -> int | None:
     """
     Checks whether the 'name' parameter for parsing is either
     an integer OR float that can SAFELY be cast to an integer
@@ -509,17 +524,18 @@ def validate_integer(name, val, min_val=0):
     min_val : int
         Minimum allowed value (val < min_val will result in a ValueError)
     """
-    msg = f"'{name:s}' must be an integer >={min_val:d}"
+    if val is None:
+        return val
 
-    if val is not None:
-        if is_float(val):
-            if int(val) != val:
-                raise ValueError(msg)
-            val = int(val)
-        elif not (is_integer(val) and val >= min_val):
+    msg = f"'{name:s}' must be an integer >={min_val:d}"
+    if is_float(val):
+        if int(val) != val:
             raise ValueError(msg)
+        val = int(val)
+    elif not (is_integer(val) and val >= min_val):
+        raise ValueError(msg)
 
-    return val
+    return int(val)
 
 
 def _validate_names(names: Sequence[Hashable] | None) -> None:
@@ -1784,7 +1800,7 @@ def __exit__(self, exc_type, exc_value, traceback) -> None:
         self.close()
 
 
-def TextParser(*args, **kwds):
+def TextParser(*args, **kwds) -> TextFileReader:
     """
     Converts lists of lists/tuples into DataFrames with proper type inference
     and optional (e.g. string to datetime) conversion. Also enables iterating

pandas/io/sas/sas_xport.py

@@ -396,7 +396,7 @@ def _read_header(self):
         dtype = np.dtype(dtypel)
         self._dtype = dtype
 
-    def __next__(self):
+    def __next__(self) -> pd.DataFrame:
         return self.read(nrows=self._chunksize or 1)
 
     def _record_count(self) -> int:
@@ -434,7 +434,7 @@ def _record_count(self) -> int:
 
         return (total_records_length - tail_pad) // self.record_length
 
-    def get_chunk(self, size=None):
+    def get_chunk(self, size=None) -> pd.DataFrame:
         """
         Reads lines from Xport file and returns as dataframe