CLN: D213: Multi-line docstring summary should start at the second line (#31893)

Author: simonjayhawkins

pandas/_config/config.py

@@ -82,7 +82,8 @@
 
 
 class OptionError(AttributeError, KeyError):
-    """Exception for pandas.options, backwards compatible with KeyError
+    """
+    Exception for pandas.options, backwards compatible with KeyError
     checks
     """
 
@@ -545,7 +546,8 @@ def deprecate_option(
 
 
 def _select_options(pat: str) -> List[str]:
-    """returns a list of keys matching `pat`
+    """
+    returns a list of keys matching `pat`
 
     if pat=="all", returns all registered options
     """
@@ -708,7 +710,8 @@ def pp(name: str, ks: Iterable[str]) -> List[str]:
 
 @contextmanager
 def config_prefix(prefix):
-    """contextmanager for multiple invocations of API with a common prefix
+    """
+    contextmanager for multiple invocations of API with a common prefix
 
     supported API functions: (register / get / set )__option
 

pandas/_testing.py

@@ -743,7 +743,8 @@ def repr_class(x):
 
 
 def assert_attr_equal(attr, left, right, obj="Attributes"):
-    """checks attributes are equal. Both objects must have attribute.
+    """
+    checks attributes are equal. Both objects must have attribute.
 
     Parameters
     ----------
@@ -820,7 +821,8 @@ def assert_is_sorted(seq):
 def assert_categorical_equal(
     left, right, check_dtype=True, check_category_order=True, obj="Categorical"
 ):
-    """Test that Categoricals are equivalent.
+    """
+    Test that Categoricals are equivalent.
 
     Parameters
     ----------
@@ -860,7 +862,8 @@ def assert_categorical_equal(
 
 
 def assert_interval_array_equal(left, right, exact="equiv", obj="IntervalArray"):
-    """Test that two IntervalArrays are equivalent.
+    """
+    Test that two IntervalArrays are equivalent.
 
     Parameters
     ----------
@@ -1009,7 +1012,8 @@ def _raise(left, right, err_msg):
 def assert_extension_array_equal(
     left, right, check_dtype=True, check_less_precise=False, check_exact=False
 ):
-    """Check that left and right ExtensionArrays are equal.
+    """
+    Check that left and right ExtensionArrays are equal.
 
     Parameters
     ----------
@@ -1489,7 +1493,8 @@ def assert_sp_array_equal(
     check_fill_value=True,
     consolidate_block_indices=False,
 ):
-    """Check that the left and right SparseArray are equal.
+    """
+    Check that the left and right SparseArray are equal.
 
     Parameters
     ----------
@@ -1724,7 +1729,8 @@ def _make_timeseries(start="2000-01-01", end="2000-12-31", freq="1D", seed=None)
 
 
 def all_index_generator(k=10):
-    """Generator which can be iterated over to get instances of all the various
+    """
+    Generator which can be iterated over to get instances of all the various
     index classes.
 
     Parameters
@@ -1763,7 +1769,8 @@ def index_subclass_makers_generator():
 
 
 def all_timeseries_index_generator(k=10):
-    """Generator which can be iterated over to get instances of all the classes
+    """
+    Generator which can be iterated over to get instances of all the classes
     which represent time-series.
 
     Parameters
@@ -1854,7 +1861,8 @@ def makePeriodFrame(nper=None):
 def makeCustomIndex(
     nentries, nlevels, prefix="#", names=False, ndupe_l=None, idx_type=None
 ):
-    """Create an index/multindex with given dimensions, levels, names, etc'
+    """
+    Create an index/multindex with given dimensions, levels, names, etc'
 
     nentries - number of entries in index
     nlevels - number of levels (> 1 produces multindex)
@@ -2144,7 +2152,8 @@ def makeMissingDataframe(density=0.9, random_state=None):
 
 
 def optional_args(decorator):
-    """allows a decorator to take optional positional and keyword arguments.
+    """
+    allows a decorator to take optional positional and keyword arguments.
     Assumes that taking a single, callable, positional argument means that
     it is decorating a function, i.e. something like this::
 
@@ -2216,7 +2225,8 @@ def _get_default_network_errors():
 
 
 def can_connect(url, error_classes=None):
-    """Try to connect to the given url. True if succeeds, False if IOError
+    """
+    Try to connect to the given url. True if succeeds, False if IOError
     raised
 
     Parameters
@@ -2584,7 +2594,8 @@ def use_numexpr(use, min_elements=None):
 
 
 def test_parallel(num_threads=2, kwargs_list=None):
-    """Decorator to run the same function multiple times in parallel.
+    """
+    Decorator to run the same function multiple times in parallel.
 
     Parameters
     ----------

pandas/compat/chainmap.py

@@ -5,7 +5,8 @@
 
 
 class DeepChainMap(ChainMap[_KT, _VT]):
-    """Variant of ChainMap that allows direct updates to inner scopes.
+    """
+    Variant of ChainMap that allows direct updates to inner scopes.
 
     Only works when all passed mapping are mutable.
     """

pandas/core/aggregation.py

@@ -98,7 +98,8 @@ def normalize_keyword_aggregation(kwargs: dict) -> Tuple[dict, List[str], List[i
 def _make_unique_kwarg_list(
     seq: Sequence[Tuple[Any, Any]]
 ) -> Sequence[Tuple[Any, Any]]:
-    """Uniquify aggfunc name of the pairs in the order list
+    """
+    Uniquify aggfunc name of the pairs in the order list
 
     Examples:
     --------

pandas/core/arrays/base.py

@@ -1,4 +1,5 @@
-"""An interface for extending pandas with custom arrays.
+"""
+An interface for extending pandas with custom arrays.
 
 .. warning::
 
@@ -213,7 +214,8 @@ def _from_sequence(cls, scalars, dtype=None, copy=False):
 
     @classmethod
     def _from_sequence_of_strings(cls, strings, dtype=None, copy=False):
-        """Construct a new ExtensionArray from a sequence of strings.
+        """
+        Construct a new ExtensionArray from a sequence of strings.
 
         .. versionadded:: 0.24.0
 
@@ -961,7 +963,8 @@ def __repr__(self) -> str:
         return f"{class_name}{data}\nLength: {len(self)}, dtype: {self.dtype}"
 
     def _formatter(self, boxed: bool = False) -> Callable[[Any], Optional[str]]:
-        """Formatting function for scalar values.
+        """
+        Formatting function for scalar values.
 
         This is used in the default '__repr__'. The returned formatting
         function receives instances of your scalar type.

pandas/core/arrays/categorical.py

@@ -1891,7 +1891,8 @@ def __contains__(self, key) -> bool:
         return contains(self, key, container=self._codes)
 
     def _tidy_repr(self, max_vals=10, footer=True) -> str:
-        """ a short repr displaying only max_vals and an optional (but default
+        """
+        a short repr displaying only max_vals and an optional (but default
         footer)
         """
         num = max_vals // 2

pandas/core/arrays/datetimelike.py

@@ -134,7 +134,8 @@ def _simple_new(cls, values, **kwargs):
 
     @property
     def _scalar_type(self) -> Type[DatetimeLikeScalar]:
-        """The scalar associated with this datelike
+        """
+        The scalar associated with this datelike
 
         * PeriodArray : Period
         * DatetimeArray : Timestamp

pandas/core/arrays/integer.py

@@ -477,7 +477,8 @@ def astype(self, dtype, copy: bool = True) -> ArrayLike:
 
     @property
     def _ndarray_values(self) -> np.ndarray:
-        """Internal pandas method for lossy conversion to a NumPy ndarray.
+        """
+        Internal pandas method for lossy conversion to a NumPy ndarray.
 
         This method is not part of the pandas interface.
 
@@ -492,7 +493,8 @@ def _values_for_factorize(self) -> Tuple[np.ndarray, float]:
         return self.to_numpy(na_value=np.nan), np.nan
 
     def _values_for_argsort(self) -> np.ndarray:
-        """Return values for sorting.
+        """
+        Return values for sorting.
 
         Returns
         -------

pandas/core/arrays/interval.py

@@ -460,7 +460,8 @@ def from_tuples(cls, data, closed="right", copy=False, dtype=None):
         return cls.from_arrays(left, right, closed, copy=False, dtype=dtype)
 
     def _validate(self):
-        """Verify that the IntervalArray is valid.
+        """
+        Verify that the IntervalArray is valid.
 
         Checks that
 

pandas/core/arrays/sparse/scipy_sparse.py

@@ -17,7 +17,8 @@ def _check_is_partition(parts, whole):
 
 
 def _to_ijv(ss, row_levels=(0,), column_levels=(1,), sort_labels=False):
-    """ For arbitrary (MultiIndexed) sparse Series return
+    """
+    For arbitrary (MultiIndexed) sparse Series return
     (v, i, j, ilabels, jlabels) where (v, (i, j)) is suitable for
     passing to scipy.sparse.coo constructor.
     """
@@ -44,7 +45,8 @@ def get_indexers(levels):
         # labels_to_i[:] = np.arange(labels_to_i.shape[0])
 
         def _get_label_to_i_dict(labels, sort_labels=False):
-            """ Return dict of unique labels to number.
+            """
+            Return dict of unique labels to number.
             Optionally sort by label.
             """
             labels = Index(map(tuple, labels)).unique().tolist()  # squish

pandas/core/computation/ops.py

@@ -1,4 +1,5 @@
-"""Operator classes for eval.
+"""
+Operator classes for eval.
 """
 
 from datetime import datetime
@@ -248,7 +249,8 @@ def is_datetime(self) -> bool:
 
 
 def _in(x, y):
-    """Compute the vectorized membership of ``x in y`` if possible, otherwise
+    """
+    Compute the vectorized membership of ``x in y`` if possible, otherwise
     use Python.
     """
     try:
@@ -263,7 +265,8 @@ def _in(x, y):
 
 
 def _not_in(x, y):
-    """Compute the vectorized membership of ``x not in y`` if possible,
+    """
+    Compute the vectorized membership of ``x not in y`` if possible,
     otherwise use Python.
     """
     try:
@@ -445,7 +448,8 @@ def evaluate(self, env, engine: str, parser, term_type, eval_in_python):
         return term_type(name, env=env)
 
     def convert_values(self):
-        """Convert datetimes to a comparable value in an expression.
+        """
+        Convert datetimes to a comparable value in an expression.
         """
 
         def stringify(value):

pandas/core/computation/parsing.py

@@ -1,4 +1,5 @@
-""":func:`~pandas.eval` source string parsing functions
+"""
+:func:`~pandas.eval` source string parsing functions
 """
 
 from io import StringIO

pandas/core/computation/pytables.py

@@ -149,7 +149,8 @@ def is_valid(self) -> bool:
 
     @property
     def is_in_table(self) -> bool:
-        """ return True if this is a valid column name for generation (e.g. an
+        """
+        return True if this is a valid column name for generation (e.g. an
         actual column in the table)
         """
         return self.queryables.get(self.lhs) is not None
@@ -175,7 +176,8 @@ def generate(self, v) -> str:
         return f"({self.lhs} {self.op} {val})"
 
     def convert_value(self, v) -> "TermValue":
-        """ convert the expression that is in the term to something that is
+        """
+        convert the expression that is in the term to something that is
         accepted by pytables
         """
 

pandas/core/computation/scope.py

@@ -31,7 +31,8 @@ def ensure_scope(
 
 
 def _replacer(x) -> str:
-    """Replace a number with its hexadecimal representation. Used to tag
+    """
+    Replace a number with its hexadecimal representation. Used to tag
     temporary variables with their calling scope's id.
     """
     # get the hex repr of the binary char and remove 0x and pad by pad_size

pandas/core/dtypes/cast.py

@@ -105,7 +105,8 @@ def is_nested_object(obj) -> bool:
 
 
 def maybe_downcast_to_dtype(result, dtype):
-    """ try to cast to the specified dtype (e.g. convert back to bool/int
+    """
+    try to cast to the specified dtype (e.g. convert back to bool/int
     or could be an astype of float64->float32
     """
     do_round = False
@@ -750,7 +751,8 @@ def maybe_upcast(values, fill_value=np.nan, dtype=None, copy: bool = False):
 
 
 def invalidate_string_dtypes(dtype_set):
-    """Change string like dtypes to object for
+    """
+    Change string like dtypes to object for
     ``DataFrame.select_dtypes()``.
     """
     non_string_dtypes = dtype_set - {np.dtype("S").type, np.dtype("<U").type}
@@ -1216,7 +1218,8 @@ def try_timedelta(v):
 
 
 def maybe_cast_to_datetime(value, dtype, errors: str = "raise"):
-    """ try to cast the array/value to a datetimelike dtype, converting float
+    """
+    try to cast the array/value to a datetimelike dtype, converting float
     nan to iNaT
     """
     from pandas.core.tools.timedeltas import to_timedelta

pandas/core/dtypes/concat.py

@@ -136,7 +136,8 @@ def is_nonempty(x) -> bool:
 
 
 def concat_categorical(to_concat, axis: int = 0):
-    """Concatenate an object/categorical array of arrays, each of which is a
+    """
+    Concatenate an object/categorical array of arrays, each of which is a
     single dtype
 
     Parameters