CLN: annotations and docstrings in pd.io (pandas-dev#29605)

Author: jbrockmendel

pandas/io/clipboard/__init__.py

@@ -95,8 +95,8 @@ def _stringifyText(text):
     acceptedTypes = (str, int, float, bool)
     if not isinstance(text, acceptedTypes):
         raise PyperclipException(
-            "only str, int, float, and bool values"
-            "can be copied to the clipboard, not".format(text.__class__.__name__)
+            f"only str, int, float, and bool values"
+            f"can be copied to the clipboard, not {text.__class__.__name__}"
         )
     return str(text)
 

pandas/io/date_converters.py

@@ -57,8 +57,8 @@ def _check_columns(cols):
     for i, n in enumerate(map(len, tail)):
         if n != N:
             raise AssertionError(
-                "All columns must have the same length: {0}; "
-                "column {1} has length {2}".format(N, i, n)
+                f"All columns must have the same length: {N}; "
+                f"column {i} has length {n}"
             )
 
     return N

pandas/io/excel/_odfreader.py

@@ -61,7 +61,7 @@ def get_sheet_by_name(self, name: str):
             if table.getAttribute("name") == name:
                 return table
 
-        raise ValueError("sheet {} not found".format(name))
+        raise ValueError(f"sheet {name} not found")
 
     def get_sheet_data(self, sheet, convert_float: bool) -> List[List[Scalar]]:
         """Parse an ODF Table into a list of lists

pandas/io/excel/_openpyxl.py

@@ -46,7 +46,8 @@ def save(self):
     @classmethod
     def _convert_to_style(cls, style_dict):
         """
-        converts a style_dict to an openpyxl style object
+        Converts a style_dict to an openpyxl style object.
+
         Parameters
         ----------
         style_dict : style dictionary to convert
@@ -72,7 +73,8 @@ def _convert_to_style(cls, style_dict):
     def _convert_to_style_kwargs(cls, style_dict):
         """
         Convert a style_dict to a set of kwargs suitable for initializing
-        or updating-on-copy an openpyxl v2 style object
+        or updating-on-copy an openpyxl v2 style object.
+
         Parameters
         ----------
         style_dict : dict
@@ -83,6 +85,7 @@ def _convert_to_style_kwargs(cls, style_dict):
                 'alignment'
                 'number_format'
                 'protection'
+
         Returns
         -------
         style_kwargs : dict
@@ -107,7 +110,8 @@ def _convert_to_style_kwargs(cls, style_dict):
     @classmethod
     def _convert_to_color(cls, color_spec):
         """
-        Convert ``color_spec`` to an openpyxl v2 Color object
+        Convert ``color_spec`` to an openpyxl v2 Color object.
+
         Parameters
         ----------
         color_spec : str, dict
@@ -120,6 +124,7 @@ def _convert_to_color(cls, color_spec):
                 'tint'
                 'index'
                 'type'
+
         Returns
         -------
         color : openpyxl.styles.Color
@@ -135,7 +140,8 @@ def _convert_to_color(cls, color_spec):
     @classmethod
     def _convert_to_font(cls, font_dict):
         """
-        Convert ``font_dict`` to an openpyxl v2 Font object
+        Convert ``font_dict`` to an openpyxl v2 Font object.
+
         Parameters
         ----------
         font_dict : dict
@@ -154,6 +160,7 @@ def _convert_to_font(cls, font_dict):
                 'outline'
                 'shadow'
                 'condense'
+
         Returns
         -------
         font : openpyxl.styles.Font
@@ -185,11 +192,13 @@ def _convert_to_stop(cls, stop_seq):
         """
         Convert ``stop_seq`` to a list of openpyxl v2 Color objects,
         suitable for initializing the ``GradientFill`` ``stop`` parameter.
+
         Parameters
         ----------
         stop_seq : iterable
             An iterable that yields objects suitable for consumption by
             ``_convert_to_color``.
+
         Returns
         -------
         stop : list of openpyxl.styles.Color
@@ -200,7 +209,8 @@ def _convert_to_stop(cls, stop_seq):
     @classmethod
     def _convert_to_fill(cls, fill_dict):
         """
-        Convert ``fill_dict`` to an openpyxl v2 Fill object
+        Convert ``fill_dict`` to an openpyxl v2 Fill object.
+
         Parameters
         ----------
         fill_dict : dict
@@ -216,6 +226,7 @@ def _convert_to_fill(cls, fill_dict):
                 'top'
                 'bottom'
                 'stop'
+
         Returns
         -------
         fill : openpyxl.styles.Fill
@@ -262,14 +273,16 @@ def _convert_to_fill(cls, fill_dict):
     @classmethod
     def _convert_to_side(cls, side_spec):
         """
-        Convert ``side_spec`` to an openpyxl v2 Side object
+        Convert ``side_spec`` to an openpyxl v2 Side object.
+
         Parameters
         ----------
         side_spec : str, dict
             A string specifying the border style, or a dict with zero or more
             of the following keys (or their synonyms).
                 'style' ('border_style')
                 'color'
+
         Returns
         -------
         side : openpyxl.styles.Side
@@ -295,7 +308,8 @@ def _convert_to_side(cls, side_spec):
     @classmethod
     def _convert_to_border(cls, border_dict):
         """
-        Convert ``border_dict`` to an openpyxl v2 Border object
+        Convert ``border_dict`` to an openpyxl v2 Border object.
+
         Parameters
         ----------
         border_dict : dict
@@ -311,6 +325,7 @@ def _convert_to_border(cls, border_dict):
                 'diagonalUp' ('diagonalup')
                 'diagonalDown' ('diagonaldown')
                 'outline'
+
         Returns
         -------
         border : openpyxl.styles.Border
@@ -335,7 +350,8 @@ def _convert_to_border(cls, border_dict):
     @classmethod
     def _convert_to_alignment(cls, alignment_dict):
         """
-        Convert ``alignment_dict`` to an openpyxl v2 Alignment object
+        Convert ``alignment_dict`` to an openpyxl v2 Alignment object.
+
         Parameters
         ----------
         alignment_dict : dict

pandas/io/excel/_xlwt.py

@@ -77,7 +77,9 @@ def write_cells(
                 wks.write(startrow + cell.row, startcol + cell.col, val, style)
 
     @classmethod
-    def _style_to_xlwt(cls, item, firstlevel=True, field_sep=",", line_sep=";"):
+    def _style_to_xlwt(
+        cls, item, firstlevel: bool = True, field_sep=",", line_sep=";"
+    ) -> str:
         """helper which recursively generate an xlwt easy style string
         for example:
 
@@ -117,6 +119,7 @@ def _style_to_xlwt(cls, item, firstlevel=True, field_sep=",", line_sep=";"):
     def _convert_to_style(cls, style_dict, num_format_str=None):
         """
         converts a style_dict to an xlwt style object
+
         Parameters
         ----------
         style_dict : style dictionary to convert

pandas/io/feather_format.py

@@ -10,7 +10,7 @@
 from pandas.io.common import _stringify_path
 
 
-def to_feather(df, path):
+def to_feather(df: DataFrame, path):
     """
     Write a DataFrame to the feather-format
 

pandas/io/formats/csvs.py

@@ -327,7 +327,7 @@ def _save(self):
 
             self._save_chunk(start_i, end_i)
 
-    def _save_chunk(self, start_i, end_i):
+    def _save_chunk(self, start_i: int, end_i: int):
 
         data_index = self.data_index
 

pandas/io/formats/excel.py

@@ -63,8 +63,9 @@ def __init__(self, inherited=None):
 
     compute_css = CSSResolver()
 
-    def __call__(self, declarations_str):
-        """Convert CSS declarations to ExcelWriter style
+    def __call__(self, declarations_str: str):
+        """
+        Convert CSS declarations to ExcelWriter style.
 
         Parameters
         ----------
@@ -279,6 +280,7 @@ def build_font(self, props):
                 if "text-shadow" in props
                 else None
             ),
+            # FIXME: dont leave commented-out
             # 'vertAlign':,
             # 'charset': ,
             # 'scheme': ,
@@ -665,7 +667,7 @@ def _format_hierarchical_rows(self):
         for cell in self._generate_body(gcolidx):
             yield cell
 
-    def _generate_body(self, coloffset):
+    def _generate_body(self, coloffset: int):
         if self.styler is None:
             styles = None
         else:

pandas/io/formats/latex.py

@@ -11,8 +11,8 @@
 
 
 class LatexFormatter(TableFormatter):
-    """ Used to render a DataFrame to a LaTeX tabular/longtable environment
-    output.
+    """
+    Used to render a DataFrame to a LaTeX tabular/longtable environment output.
 
     Parameters
     ----------
@@ -106,18 +106,19 @@ def pad_empties(x):
             # Get rid of old multiindex column and add new ones
             strcols = out + strcols[1:]
 
-        column_format = self.column_format
-        if column_format is None:
+        if self.column_format is None:
             dtypes = self.frame.dtypes._values
             column_format = "".join(map(get_col_type, dtypes))
             if self.fmt.index:
                 index_format = "l" * self.frame.index.nlevels
                 column_format = index_format + column_format
-        elif not isinstance(column_format, str):  # pragma: no cover
+        elif not isinstance(self.column_format, str):  # pragma: no cover
             raise AssertionError(
                 "column_format must be str or unicode, "
                 "not {typ}".format(typ=type(column_format))
             )
+        else:
+            column_format = self.column_format
 
         if self.longtable:
             self._write_longtable_begin(buf, column_format)
@@ -265,15 +266,15 @@ def _format_multirow(
 
     def _print_cline(self, buf: IO[str], i: int, icol: int) -> None:
         """
-        Print clines after multirow-blocks are finished
+        Print clines after multirow-blocks are finished.
         """
         for cl in self.clinebuf:
             if cl[0] == i:
                 buf.write("\\cline{{{cl:d}-{icol:d}}}\n".format(cl=cl[1], icol=icol))
         # remove entries that have been written to buffer
         self.clinebuf = [x for x in self.clinebuf if x[0] != i]
 
-    def _write_tabular_begin(self, buf, column_format):
+    def _write_tabular_begin(self, buf, column_format: str):
         """
         Write the beginning of a tabular environment or
         nested table/tabular environments including caption and label.
@@ -283,11 +284,10 @@ def _write_tabular_begin(self, buf, column_format):
         buf : string or file handle
             File path or object. If not specified, the result is returned as
             a string.
-        column_format : str, default None
+        column_format : str
             The columns format as specified in `LaTeX table format
             <https://en.wikibooks.org/wiki/LaTeX/Tables>`__ e.g 'rcl'
             for 3 columns
-
         """
         if self.caption is not None or self.label is not None:
             # then write output in a nested table/tabular environment
@@ -327,7 +327,7 @@ def _write_tabular_end(self, buf):
         else:
             pass
 
-    def _write_longtable_begin(self, buf, column_format):
+    def _write_longtable_begin(self, buf, column_format: str):
         """
         Write the beginning of a longtable environment including caption and
         label if provided by user.
@@ -337,11 +337,10 @@ def _write_longtable_begin(self, buf, column_format):
         buf : string or file handle
             File path or object. If not specified, the result is returned as
             a string.
-        column_format : str, default None
+        column_format : str
             The columns format as specified in `LaTeX table format
             <https://en.wikibooks.org/wiki/LaTeX/Tables>`__ e.g 'rcl'
             for 3 columns
-
         """
         buf.write("\\begin{{longtable}}{{{fmt}}}\n".format(fmt=column_format))
 

pandas/io/html.py

@@ -57,16 +57,15 @@ def _importers():
 _RE_WHITESPACE = re.compile(r"[\r\n]+|\s{2,}")
 
 
-def _remove_whitespace(s, regex=_RE_WHITESPACE):
+def _remove_whitespace(s: str, regex=_RE_WHITESPACE) -> str:
     """
     Replace extra whitespace inside of a string with a single space.
 
     Parameters
     ----------
     s : str or unicode
         The string from which to remove extra whitespace.
-
-    regex : regex
+    regex : re.Pattern
         The regular expression to use to remove extra whitespace.
 
     Returns
@@ -253,7 +252,8 @@ def _text_getter(self, obj):
         raise AbstractMethodError(self)
 
     def _parse_td(self, obj):
-        """Return the td elements from a row element.
+        """
+        Return the td elements from a row element.
 
         Parameters
         ----------
@@ -600,7 +600,7 @@ def _build_doc(self):
         )
 
 
-def _build_xpath_expr(attrs):
+def _build_xpath_expr(attrs) -> str:
     """Build an xpath expression to simulate bs4's ability to pass in kwargs to
     search for attributes when using the lxml parser.
 
@@ -810,7 +810,8 @@ def _data_to_frame(**kwargs):
 
 
 def _parser_dispatch(flavor):
-    """Choose the parser based on the input flavor.
+    """
+    Choose the parser based on the input flavor.
 
     Parameters
     ----------
@@ -850,7 +851,7 @@ def _parser_dispatch(flavor):
     return _valid_parsers[flavor]
 
 
-def _print_as_set(s):
+def _print_as_set(s) -> str:
     return "{" + "{arg}".format(arg=", ".join(pprint_thing(el) for el in s)) + "}"