Docstring improvements & enable lints (#4161)

py-polars/.flake8

@@ -5,8 +5,10 @@ extend-ignore =
     # Satisfy black: https://black.readthedocs.io/en/stable/guides/using_black_with_other_tools.html#flake8
     E203,
     # pydocstyle: http://www.pydocstyle.org/en/stable/error_codes.html
-    # numpy convention with D413 (Missing blank line after last section)
-    D107, D203, D212, D402, D415, D416
+    # numpy convention with a few additional lints
+    D107, D203, D212, D402, D415, D416,
+    # TODO: Remove errors below to further improve docstring linting
+    D1, D400, D205,
 
 per-file-ignores =
     __init__.py:F401

py-polars/build.requirements.txt

@@ -21,6 +21,7 @@ mypy==0.961
 ghp-import==2.1.0
 flake8==4.0.1
 flake8-bugbear==22.7.1
+flake8-docstrings==1.6.0
 sphinx==4.2.0
 pydata-sphinx-theme==0.6.3
 sphinx-panels==0.6.0

py-polars/polars/_html.py

@@ -1,6 +1,4 @@
-"""
-Module for formatting output data in HTML.
-"""
+"""Module for formatting output data in HTML."""
 from __future__ import annotations
 
 import os
@@ -12,6 +10,8 @@
 
 
 class Tag:
+    """Class for representing an HTML tag."""
+
     def __init__(
         self,
         elements: list[str],
@@ -72,9 +72,7 @@ def __init__(
             self.col_idx = range(0, df.width)
 
     def write_header(self) -> None:
-        """
-        Writes the header of an HTML table.
-        """
+        """Write the header of an HTML table."""
         self.elements.append(f"<small>shape: {self.df.shape}</small>")
         with Tag(self.elements, "thead"):
             with Tag(self.elements, "tr"):
@@ -95,9 +93,7 @@ def write_header(self) -> None:
                             self.elements.append(dtypes[c])
 
     def write_body(self) -> None:
-        """
-        Writes the body of an HTML table.
-        """
+        """Write the body of an HTML table."""
         str_lengths = int(os.environ.get("POLARS_FMT_STR_LEN", "15"))
         with Tag(self.elements, "tbody"):
             for r in self.row_idx:
@@ -129,9 +125,11 @@ def render(self) -> list[str]:
 
 class NotebookFormatter(HTMLFormatter):
     """
-    Internal class for formatting output data in html for display in Jupyter
-    Notebooks. This class is intended for functionality specific to
-    DataFrame._repr_html_() and DataFrame.to_html(notebook=True)
+    Class for formatting output data in HTML for display in Jupyter Notebooks.
+
+    This class is intended for functionality specific to DataFrame._repr_html_()
+    and DataFrame.to_html(notebook=True).
+
     """
 
     def write_style(self) -> None:
@@ -166,9 +164,7 @@ def write_style(self) -> None:
         self.write(template)
 
     def render(self) -> list[str]:
-        """
-        Return the lines needed to render a HTML table.
-        """
+        """Return the lines needed to render a HTML table."""
         with Tag(self.elements, "div"):
             self.write_style()
             super().render()

py-polars/polars/cfg.py

@@ -6,19 +6,15 @@
 
 
 class Config:
-    """
-    Configure polars
-    """
+    """Configure polars."""
 
     # class-local boolean flags can be used for options that don't have
     # a Rust component (so no need to register environment variables).
     with_columns_kwargs: bool = False
 
     @classmethod
     def set_utf8_tables(cls) -> type[Config]:
-        """
-        Use utf8 characters to print tables
-        """
+        """Use utf8 characters to print tables."""
         # os.unsetenv is automatically called if we remove a key from os.environ,
         # see https://docs.python.org/3/library/os.html#os.environ. However, we cannot
         # call os.unsetenv directly, as that fails on Windows
@@ -27,42 +23,42 @@ def set_utf8_tables(cls) -> type[Config]:
 
     @classmethod
     def set_ascii_tables(cls) -> type[Config]:
-        """
-        Use ascii characters to print tables
-        """
+        """Use ascii characters to print tables."""
         os.environ["POLARS_FMT_NO_UTF8"] = "1"
         return cls
 
     @classmethod
     def set_tbl_width_chars(cls, width: int) -> type[Config]:
         """
-        Set the number of character used to draw the table
+        Set the number of character used to draw the table.
 
         Parameters
         ----------
         width
             number of chars
+
         """
         os.environ["POLARS_TABLE_WIDTH"] = str(width)
         return cls
 
     @classmethod
     def set_tbl_rows(cls, n: int) -> type[Config]:
         """
-        Set the number of rows used to print tables
+        Set the number of rows used to print tables.
 
         Parameters
         ----------
         n
             number of rows to print
+
         """
         os.environ["POLARS_FMT_MAX_ROWS"] = str(n)
         return cls
 
     @classmethod
     def set_tbl_cols(cls, n: int) -> type[Config]:
         """
-        Set the number of columns used to print tables
+        Set the number of columns used to print tables.
 
         Parameters
         ----------
@@ -100,30 +96,26 @@ def set_tbl_cols(cls, n: int) -> type[Config]:
 
     @classmethod
     def set_global_string_cache(cls) -> type[Config]:
-        """
-        Turn on the global string cache
-        """
+        """Turn on the global string cache."""
         toggle_string_cache(True)
         return cls
 
     @classmethod
     def unset_global_string_cache(cls) -> type[Config]:
-        """
-        Turn off the global string cache
-        """
+        """Turn off the global string cache."""
         toggle_string_cache(False)
         return cls
 
     @classmethod
     def set_fmt_str_lengths(cls, n: int) -> type[Config]:
         """
-        Set the number of characters used to print string values
+        Set the number of characters used to print string values.
 
         Parameters
         ----------
         n
             number of characters to print
-        """
 
+        """
         os.environ["POLARS_FMT_STR_LEN"] = str(n)
         return cls