STY: Use ruff to format docstrings

.pre-commit-config.yaml

@@ -19,7 +19,7 @@ ci:
     skip: [pylint, pyright, mypy]
 repos:
 -   repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.1.6
+    rev: v0.1.13
     hooks:
     -   id: ruff
         args: [--exit-non-zero-on-fix]
@@ -31,8 +31,6 @@ repos:
         exclude: ^pandas/tests
         args: [--select, "ANN001,ANN2", --fix-only, --exit-non-zero-on-fix]
     -   id: ruff-format
-        # TODO: "." not needed in ruff 0.1.8
-        args: ["."]
 -   repo: https://github.com/jendrikseipp/vulture
     rev: 'v2.10'
     hooks:

ci/code_checks.sh

@@ -69,67 +69,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
     $BASE_DIR/scripts/validate_docstrings.py --format=actions --errors=EX01,EX04,GL01,GL02,GL03,GL04,GL05,GL06,GL07,GL09,GL10,PR03,PR04,PR05,PR06,PR08,PR09,PR10,RT01,RT02,RT04,RT05,SA02,SA03,SA04,SS01,SS02,SS03,SS04,SS05,SS06
     RET=$(($RET + $?)) ; echo $MSG "DONE"
 
-    MSG='Partially validate docstrings (EX03)' ;  echo $MSG
-    $BASE_DIR/scripts/validate_docstrings.py --format=actions --errors=EX03 --ignore_functions \
-        pandas.Series.plot.line \
-        pandas.Series.to_sql \
-        pandas.errors.DatabaseError \
-        pandas.errors.IndexingError \
-        pandas.errors.InvalidColumnName \
-        pandas.errors.PossibleDataLossError \
-        pandas.errors.PossiblePrecisionLoss \
-        pandas.errors.SettingWithCopyError \
-        pandas.errors.SettingWithCopyWarning \
-        pandas.errors.SpecificationError \
-        pandas.errors.UndefinedVariableError \
-        pandas.errors.ValueLabelTypeMismatch \
-        pandas.Timestamp.ceil \
-        pandas.Timestamp.floor \
-        pandas.Timestamp.round \
-        pandas.ExcelWriter \
-        pandas.read_json \
-        pandas.io.json.build_table_schema \
-        pandas.io.formats.style.Styler.to_latex \
-        pandas.read_parquet \
-        pandas.DataFrame.to_sql \
-        pandas.read_stata \
-        pandas.core.resample.Resampler.interpolate \
-        pandas.plotting.scatter_matrix \
-        pandas.pivot \
-        pandas.merge_asof \
-        pandas.wide_to_long \
-        pandas.Index.rename \
-        pandas.Index.droplevel \
-        pandas.Index.isin \
-        pandas.MultiIndex.names \
-        pandas.MultiIndex.droplevel \
-        pandas.IndexSlice \
-        pandas.Grouper \
-        pandas.io.formats.style.Styler.map \
-        pandas.io.formats.style.Styler.apply_index \
-        pandas.io.formats.style.Styler.map_index \
-        pandas.io.formats.style.Styler.format \
-        pandas.io.formats.style.Styler.format_index \
-        pandas.io.formats.style.Styler.relabel_index \
-        pandas.io.formats.style.Styler.hide \
-        pandas.io.formats.style.Styler.set_td_classes \
-        pandas.io.formats.style.Styler.set_tooltips \
-        pandas.io.formats.style.Styler.set_uuid \
-        pandas.io.formats.style.Styler.pipe \
-        pandas.io.formats.style.Styler.highlight_between \
-        pandas.io.formats.style.Styler.highlight_quantile \
-        pandas.io.formats.style.Styler.background_gradient \
-        pandas.io.formats.style.Styler.text_gradient \
-        pandas.DataFrame.values \
-        pandas.DataFrame.groupby \
-        pandas.DataFrame.idxmax \
-        pandas.DataFrame.idxmin \
-        pandas.DataFrame.pivot \
-        pandas.DataFrame.sort_values \
-        pandas.DataFrame.plot.hexbin \
-        pandas.DataFrame.plot.line \
-    RET=$(($RET + $?)) ; echo $MSG "DONE"
-
 fi
 
 ### DOCUMENTATION NOTEBOOKS ###

doc/make.py

@@ -113,7 +113,7 @@ def _run_os(*args) -> None:
 
         Examples
         --------
-        >>> DocBuilder()._run_os('python', '--version')
+        >>> DocBuilder()._run_os("python", "--version")
         """
         subprocess.check_call(args, stdout=sys.stdout, stderr=sys.stderr)
 
@@ -129,7 +129,7 @@ def _sphinx_build(self, kind: str):
 
         Examples
         --------
-        >>> DocBuilder(num_jobs=4)._sphinx_build('html')
+        >>> DocBuilder(num_jobs=4)._sphinx_build("html")
         """
         if kind not in ("html", "latex", "linkcheck"):
             raise ValueError(f"kind must be html, latex or linkcheck, not {kind}")

environment.yml

@@ -75,7 +75,6 @@ dependencies:
   - cxx-compiler
 
   # code checks
-  - flake8=6.1.0  # run in subprocess over docstring examples
   - mypy=1.8.0  # pre-commit uses locally installed mypy
   - tokenize-rt  # scripts/check_for_inconsistent_pandas_namespace.py
   - pre-commit>=3.6.0

pandas/_config/config.py

@@ -465,7 +465,7 @@ class option_context(ContextDecorator):
     Examples
     --------
     >>> from pandas import option_context
-    >>> with option_context('display.max_rows', 10, 'display.max_columns', 5):
+    >>> with option_context("display.max_rows", 10, "display.max_columns", 5):
     ...     pass
     """
 

pandas/_testing/_warnings.py

@@ -76,10 +76,8 @@ class for all warnings. To raise multiple types of exceptions,
     >>> import warnings
     >>> with assert_produces_warning():
     ...     warnings.warn(UserWarning())
-    ...
     >>> with assert_produces_warning(False):
     ...     warnings.warn(RuntimeWarning())
-    ...
     Traceback (most recent call last):
         ...
     AssertionError: Caused unexpected warning(s): ['RuntimeWarning'].

pandas/_testing/asserters.py

@@ -1178,8 +1178,8 @@ def assert_frame_equal(
     but with columns of differing dtypes.
 
     >>> from pandas.testing import assert_frame_equal
-    >>> df1 = pd.DataFrame({'a': [1, 2], 'b': [3, 4]})
-    >>> df2 = pd.DataFrame({'a': [1, 2], 'b': [3.0, 4.0]})
+    >>> df1 = pd.DataFrame({"a": [1, 2], "b": [3, 4]})
+    >>> df2 = pd.DataFrame({"a": [1, 2], "b": [3.0, 4.0]})
 
     df1 equals itself.
 

pandas/_testing/contexts.py

@@ -70,9 +70,8 @@ def set_timezone(tz: str) -> Generator[None, None, None]:
     >>> tzlocal().tzname(datetime(2021, 1, 1))  # doctest: +SKIP
     'IST'
 
-    >>> with set_timezone('US/Eastern'):
+    >>> with set_timezone("US/Eastern"):
     ...     tzlocal().tzname(datetime(2021, 1, 1))
-    ...
     'EST'
     """
     import time

pandas/core/accessor.py

@@ -265,7 +265,7 @@ def __init__(self, pandas_object):  # noqa: E999
     For consistency with pandas methods, you should raise an ``AttributeError``
     if the data passed to your accessor has an incorrect dtype.
 
-    >>> pd.Series(['a', 'b']).dt
+    >>> pd.Series(["a", "b"]).dt
     Traceback (most recent call last):
     ...
     AttributeError: Can only use .dt accessor with datetimelike values
@@ -274,8 +274,6 @@ def __init__(self, pandas_object):  # noqa: E999
     --------
     In your library code::
 
-        import pandas as pd
-
         @pd.api.extensions.register_dataframe_accessor("geo")
         class GeoAccessor:
             def __init__(self, pandas_obj):

pandas/core/algorithms.py

@@ -1215,8 +1215,9 @@ def take(
     >>> pd.api.extensions.take(np.array([10, 20, 30]), [0, 0, -1], allow_fill=True)
     array([10., 10., nan])
 
-    >>> pd.api.extensions.take(np.array([10, 20, 30]), [0, 0, -1], allow_fill=True,
-    ...      fill_value=-10)
+    >>> pd.api.extensions.take(
+    ...     np.array([10, 20, 30]), [0, 0, -1], allow_fill=True, fill_value=-10
+    ... )
     array([ 10,  10, -10])
     """
     if not isinstance(arr, (np.ndarray, ABCExtensionArray, ABCIndex, ABCSeries)):

pandas/core/apply.py

@@ -1798,14 +1798,14 @@ def normalize_keyword_aggregation(
 
 
 def _make_unique_kwarg_list(
-    seq: Sequence[tuple[Any, Any]]
+    seq: Sequence[tuple[Any, Any]],
 ) -> Sequence[tuple[Any, Any]]:
     """
     Uniquify aggfunc name of the pairs in the order list
 
     Examples:
     --------
-    >>> kwarg_list = [('a', '<lambda>'), ('a', '<lambda>'), ('b', '<lambda>')]
+    >>> kwarg_list = [("a", "<lambda>"), ("a", "<lambda>"), ("b", "<lambda>")]
     >>> _make_unique_kwarg_list(kwarg_list)
     [('a', '<lambda>_0'), ('a', '<lambda>_1'), ('b', '<lambda>')]
     """
@@ -1837,7 +1837,7 @@ def relabel_result(
     >>> from pandas.core.apply import relabel_result
     >>> result = pd.DataFrame(
     ...     {"A": [np.nan, 2, np.nan], "C": [6, np.nan, np.nan], "B": [np.nan, 4, 2.5]},
-    ...     index=["max", "mean", "min"]
+    ...     index=["max", "mean", "min"],
     ... )
     >>> funcs = {"A": ["max"], "C": ["max"], "B": ["mean", "min"]}
     >>> columns = ("foo", "aab", "bar", "dat")
@@ -1976,7 +1976,7 @@ def maybe_mangle_lambdas(agg_spec: Any) -> Any:
 
     Examples
     --------
-    >>> maybe_mangle_lambdas('sum')
+    >>> maybe_mangle_lambdas("sum")
     'sum'
     >>> maybe_mangle_lambdas([lambda: 1, lambda: 2])  # doctest: +SKIP
     [<function __main__.<lambda_0>,
@@ -2021,7 +2021,7 @@ def validate_func_kwargs(
 
     Examples
     --------
-    >>> validate_func_kwargs({'one': 'min', 'two': 'max'})
+    >>> validate_func_kwargs({"one": "min", "two": "max"})
     (['one', 'two'], ['min', 'max'])
     """
     tuple_given_message = "func is expected but received {} in **kwargs."

pandas/core/arraylike.py

@@ -119,40 +119,41 @@ def __add__(self, other):
 
         Examples
         --------
-        >>> df = pd.DataFrame({'height': [1.5, 2.6], 'weight': [500, 800]},
-        ...                   index=['elk', 'moose'])
+        >>> df = pd.DataFrame(
+        ...     {"height": [1.5, 2.6], "weight": [500, 800]}, index=["elk", "moose"]
+        ... )
         >>> df
                height  weight
         elk       1.5     500
         moose     2.6     800
 
         Adding a scalar affects all rows and columns.
 
-        >>> df[['height', 'weight']] + 1.5
+        >>> df[["height", "weight"]] + 1.5
                height  weight
         elk       3.0   501.5
         moose     4.1   801.5
 
         Each element of a list is added to a column of the DataFrame, in order.
 
-        >>> df[['height', 'weight']] + [0.5, 1.5]
+        >>> df[["height", "weight"]] + [0.5, 1.5]
                height  weight
         elk       2.0   501.5
         moose     3.1   801.5
 
         Keys of a dictionary are aligned to the DataFrame, based on column names;
         each value in the dictionary is added to the corresponding column.
 
-        >>> df[['height', 'weight']] + {'height': 0.5, 'weight': 1.5}
+        >>> df[["height", "weight"]] + {"height": 0.5, "weight": 1.5}
                height  weight
         elk       2.0   501.5
         moose     3.1   801.5
 
         When `other` is a :class:`Series`, the index of `other` is aligned with the
         columns of the DataFrame.
 
-        >>> s1 = pd.Series([0.5, 1.5], index=['weight', 'height'])
-        >>> df[['height', 'weight']] + s1
+        >>> s1 = pd.Series([0.5, 1.5], index=["weight", "height"])
+        >>> df[["height", "weight"]] + s1
                height  weight
         elk       3.0   500.5
         moose     4.1   800.5
@@ -161,23 +162,24 @@ def __add__(self, other):
         the :class:`Series` will not be reoriented. If index-wise alignment is desired,
         :meth:`DataFrame.add` should be used with `axis='index'`.
 
-        >>> s2 = pd.Series([0.5, 1.5], index=['elk', 'moose'])
-        >>> df[['height', 'weight']] + s2
+        >>> s2 = pd.Series([0.5, 1.5], index=["elk", "moose"])
+        >>> df[["height", "weight"]] + s2
                elk  height  moose  weight
         elk    NaN     NaN    NaN     NaN
         moose  NaN     NaN    NaN     NaN
 
-        >>> df[['height', 'weight']].add(s2, axis='index')
+        >>> df[["height", "weight"]].add(s2, axis="index")
                height  weight
         elk       2.0   500.5
         moose     4.1   801.5
 
         When `other` is a :class:`DataFrame`, both columns names and the
         index are aligned.
 
-        >>> other = pd.DataFrame({'height': [0.2, 0.4, 0.6]},
-        ...                      index=['elk', 'moose', 'deer'])
-        >>> df[['height', 'weight']] + other
+        >>> other = pd.DataFrame(
+        ...     {"height": [0.2, 0.4, 0.6]}, index=["elk", "moose", "deer"]
+        ... )
+        >>> df[["height", "weight"]] + other
                height  weight
         deer      NaN     NaN
         elk       1.7     NaN