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