CLN: Make repeat method consistent (pandas-dev#24395)

Author: jschendel

pandas/core/arrays/base.py

@@ -12,6 +12,7 @@
 from pandas.compat import PY3, set_function_name
 from pandas.compat.numpy import function as nv
 from pandas.errors import AbstractMethodError
+from pandas.util._decorators import Appender, Substitution
 
 from pandas.core.dtypes.common import is_list_like
 from pandas.core.dtypes.generic import ABCIndexClass, ABCSeries
@@ -20,6 +21,8 @@
 
 _not_implemented_message = "{} does not implement {}."
 
+_extension_array_shared_docs = dict()
+
 
 class ExtensionArray(object):
     """
@@ -580,32 +583,55 @@ def factorize(self, na_sentinel=-1):
         uniques = self._from_factorized(uniques, self)
         return labels, uniques
 
-    def repeat(self, repeats, axis=None):
-        """
-        Repeat elements of an array.
+    _extension_array_shared_docs['repeat'] = """
+        Repeat elements of a %(klass)s.
 
-        .. versionadded:: 0.24.0
+        Returns a new %(klass)s where each element of the current %(klass)s
+        is repeated consecutively a given number of times.
 
         Parameters
         ----------
-        repeats : int
-            This should be a non-negative integer. Repeating 0 times
-            will return an empty array.
+        repeats : int or array of ints
+            The number of repetitions for each element. This should be a
+            non-negative integer. Repeating 0 times will return an empty
+            %(klass)s.
+        *args
+            Additional arguments have no effect but might be accepted for
+            compatibility with numpy.
+        **kwargs
+            Additional keywords have no effect but might be accepted for
+            compatibility with numpy.
 
         Returns
         -------
-        repeated_array : ExtensionArray
-            Same type as the input, with elements repeated `repeats` times.
+        repeated_array : %(klass)s
+            Newly created %(klass)s with repeated elements.
 
         See Also
         --------
+        Series.repeat : Equivalent function for Series.
+        Index.repeat : Equivalent function for Index.
         numpy.repeat : Similar method for :class:`numpy.ndarray`.
         ExtensionArray.take : Take arbitrary positions.
+
+        Examples
+        --------
+        >>> cat = pd.Categorical(['a', 'b', 'c'])
+        >>> cat
+        [a, b, c]
+        Categories (3, object): [a, b, c]
+        >>> cat.repeat(2)
+        [a, a, b, b, c, c]
+        Categories (3, object): [a, b, c]
+        >>> cat.repeat([1, 2, 3])
+        [a, b, b, c, c, c]
+        Categories (3, object): [a, b, c]
         """
-        if axis is not None:
-            raise ValueError("'axis' must be None.")
-        if repeats < 0:
-            raise ValueError("negative repeats are not allowed.")
+
+    @Substitution(klass='ExtensionArray')
+    @Appender(_extension_array_shared_docs['repeat'])
+    def repeat(self, repeats, *args, **kwargs):
+        nv.validate_repeat(args, kwargs)
         ind = np.arange(len(self)).repeat(repeats)
         return self.take(ind)
 

pandas/core/arrays/categorical.py

@@ -39,7 +39,7 @@
 from pandas.io.formats import console
 from pandas.io.formats.terminal import get_terminal_size
 
-from .base import ExtensionArray
+from .base import ExtensionArray, _extension_array_shared_docs
 
 _take_msg = textwrap.dedent("""\
     Interpreting negative values in 'indexer' as missing values.
@@ -2394,15 +2394,9 @@ def describe(self):
 
         return result
 
+    @Substitution(klass='Categorical')
+    @Appender(_extension_array_shared_docs['repeat'])
     def repeat(self, repeats, *args, **kwargs):
-        """
-        Repeat elements of a Categorical.
-
-        See Also
-        --------
-        numpy.ndarray.repeat
-
-        """
         nv.validate_repeat(args, kwargs)
         codes = self._codes.repeat(repeats)
         return self._constructor(values=codes, dtype=self.dtype, fastpath=True)

pandas/core/arrays/interval.py

@@ -20,12 +20,13 @@
     ABCDatetimeIndex, ABCInterval, ABCIntervalIndex, ABCPeriodIndex, ABCSeries)
 from pandas.core.dtypes.missing import isna, notna
 
+from pandas.core.arrays.base import (
+    ExtensionArray, _extension_array_shared_docs)
+from pandas.core.arrays.categorical import Categorical
 import pandas.core.common as com
 from pandas.core.config import get_option
 from pandas.core.indexes.base import Index, ensure_index
 
-from . import Categorical, ExtensionArray
-
 _VALID_CLOSED = {'left', 'right', 'both', 'neither'}
 _interval_shared_docs = {}
 
@@ -1000,35 +1001,11 @@ def to_tuples(self, na_tuple=True):
             tuples = np.where(~self.isna(), tuples, np.nan)
         return tuples
 
-    def repeat(self, repeats, **kwargs):
-        """
-        Repeat elements of an IntervalArray.
-
-        Returns a new IntervalArray where each element of the current
-        IntervalArray is repeated consecutively a given number of times.
-
-        Parameters
-        ----------
-        repeats : int
-            The number of repetitions for each element.
-
-        **kwargs
-            Additional keywords have no effect but might be accepted for
-            compatibility with numpy.
-
-        Returns
-        -------
-        IntervalArray
-            Newly created IntervalArray with repeated elements.
-
-        See Also
-        --------
-        Index.repeat : Equivalent function for Index.
-        Series.repeat : Equivalent function for Series.
-        numpy.repeat : Underlying implementation.
-        """
-        left_repeat = self.left.repeat(repeats, **kwargs)
-        right_repeat = self.right.repeat(repeats, **kwargs)
+    @Appender(_extension_array_shared_docs['repeat'] % _shared_docs_kwargs)
+    def repeat(self, repeats, *args, **kwargs):
+        nv.validate_repeat(args, kwargs)
+        left_repeat = self.left.repeat(repeats)
+        right_repeat = self.right.repeat(repeats)
         return self._shallow_copy(left=left_repeat, right=right_repeat)
 
     _interval_shared_docs['overlaps'] = """

pandas/core/arrays/period.py

@@ -11,7 +11,6 @@
     period_asfreq_arr)
 from pandas._libs.tslibs.timedeltas import Timedelta, delta_to_nanoseconds
 import pandas.compat as compat
-from pandas.compat.numpy import function as nv
 from pandas.util._decorators import Appender, cache_readonly
 from pandas.util._validators import validate_fillna_kwargs
 
@@ -593,19 +592,6 @@ def _format_native_types(self, na_rep=u'NaT', date_format=None, **kwargs):
 
     # ------------------------------------------------------------------
 
-    def repeat(self, repeats, *args, **kwargs):
-        """
-        Repeat elements of a PeriodArray.
-
-        See Also
-        --------
-        numpy.ndarray.repeat
-        """
-        # TODO(DatetimeArray): remove
-        nv.validate_repeat(args, kwargs)
-        values = self._data.repeat(repeats)
-        return type(self)(values, self.freq)
-
     def astype(self, dtype, copy=True):
         # TODO: Figure out something better here...
         # We have DatetimeLikeArrayMixin ->

pandas/core/indexes/base.py

@@ -834,41 +834,48 @@ def _assert_take_fillable(self, values, indices, allow_fill=True,
             taken = values.take(indices)
         return taken
 
-    def repeat(self, repeats, *args, **kwargs):
-        """
-        Repeat elements of an Index.
+    _index_shared_docs['repeat'] = """
+        Repeat elements of a %(klass)s.
 
-        Returns a new index where each element of the current index
+        Returns a new %(klass)s where each element of the current %(klass)s
         is repeated consecutively a given number of times.
 
         Parameters
         ----------
-        repeats : int
-            The number of repetitions for each element.
+        repeats : int or array of ints
+            The number of repetitions for each element. This should be a
+            non-negative integer. Repeating 0 times will return an empty
+            %(klass)s.
+        *args
+            Additional arguments have no effect but might be accepted for
+            compatibility with numpy.
         **kwargs
             Additional keywords have no effect but might be accepted for
             compatibility with numpy.
 
         Returns
         -------
-        pandas.Index
-            Newly created Index with repeated elements.
+        repeated_index : %(klass)s
+            Newly created %(klass)s with repeated elements.
 
         See Also
         --------
         Series.repeat : Equivalent function for Series.
-        numpy.repeat : Underlying implementation.
+        numpy.repeat : Similar method for :class:`numpy.ndarray`.
 
         Examples
         --------
-        >>> idx = pd.Index([1, 2, 3])
+        >>> idx = pd.Index(['a', 'b', 'c'])
         >>> idx
-        Int64Index([1, 2, 3], dtype='int64')
+        Index(['a', 'b', 'c'], dtype='object')
         >>> idx.repeat(2)
-        Int64Index([1, 1, 2, 2, 3, 3], dtype='int64')
-        >>> idx.repeat(3)
-        Int64Index([1, 1, 1, 2, 2, 2, 3, 3, 3], dtype='int64')
+        Index(['a', 'a', 'b', 'b', 'c', 'c'], dtype='object')
+        >>> idx.repeat([1, 2, 3])
+        Index(['a', 'b', 'b', 'c', 'c', 'c'], dtype='object')
         """
+
+    @Appender(_index_shared_docs['repeat'] % _index_doc_kwargs)
+    def repeat(self, repeats, *args, **kwargs):
         nv.validate_repeat(args, kwargs)
         return self._shallow_copy(self._values.repeat(repeats))
 

pandas/core/indexes/datetimelike.py

@@ -450,17 +450,11 @@ def isin(self, values):
 
         return algorithms.isin(self.asi8, values.asi8)
 
+    @Appender(_index_shared_docs['repeat'] % _index_doc_kwargs)
     def repeat(self, repeats, *args, **kwargs):
-        """
-        Analogous to ndarray.repeat.
-        """
         nv.validate_repeat(args, kwargs)
-        if is_period_dtype(self):
-            freq = self.freq
-        else:
-            freq = None
-        return self._shallow_copy(self.asi8.repeat(repeats),
-                                  freq=freq)
+        freq = self.freq if is_period_dtype(self) else None
+        return self._shallow_copy(self.asi8.repeat(repeats), freq=freq)
 
     @Appender(_index_shared_docs['where'] % _index_doc_kwargs)
     def where(self, cond, other=None):

pandas/core/indexes/multi.py

@@ -1857,6 +1857,7 @@ def append(self, other):
     def argsort(self, *args, **kwargs):
         return self.values.argsort(*args, **kwargs)
 
+    @Appender(_index_shared_docs['repeat'] % _index_doc_kwargs)
     def repeat(self, repeats, *args, **kwargs):
         nv.validate_repeat(args, kwargs)
         return MultiIndex(levels=self.levels,

pandas/core/indexes/period.py

@@ -924,10 +924,6 @@ def wrapper(self, other):
         wrapper.__name__ = '__{}__'.format(op.__name__)
         return wrapper
 
-    def repeat(self, repeats, *args, **kwargs):
-        # TODO(DatetimeArray): Just use Index.repeat
-        return Index.repeat(self, repeats, *args, **kwargs)
-
     def view(self, dtype=None, type=None):
         # TODO(DatetimeArray): remove
         if dtype is None or dtype is __builtins__['type'](self):

pandas/core/series.py

@@ -1038,12 +1038,58 @@ def _set_values(self, key, value):
 
     def repeat(self, repeats, *args, **kwargs):
         """
-        Repeat elements of an Series. Refer to `numpy.ndarray.repeat`
-        for more information about the `repeats` argument.
+        Repeat elements of a Series.
+
+        Returns a new Series where each element of the current Series
+        is repeated consecutively a given number of times.
+
+        Parameters
+        ----------
+        repeats : int or array of ints
+            The number of repetitions for each element. This should be a
+            non-negative integer. Repeating 0 times will return an empty
+            Series.
+        *args
+            Additional arguments have no effect but might be accepted for
+            compatibility with numpy.
+        **kwargs
+            Additional keywords have no effect but might be accepted for
+            compatibility with numpy.
+
+        Returns
+        -------
+        repeated_series : Series
+            Newly created Series with repeated elements.
 
         See Also
         --------
-        numpy.ndarray.repeat
+        Index.repeat : Equivalent function for Index.
+        numpy.repeat : Similar method for :class:`numpy.ndarray`.
+
+        Examples
+        --------
+        >>> s = pd.Series(['a', 'b', 'c'])
+        >>> s
+        0    a
+        1    b
+        2    c
+        dtype: object
+        >>> s.repeat(2)
+        0    a
+        0    a
+        1    b
+        1    b
+        2    c
+        2    c
+        dtype: object
+        >>> s.repeat([1, 2, 3])
+        0    a
+        1    b
+        1    b
+        2    c
+        2    c
+        2    c
+        dtype: object
         """
         nv.validate_repeat(args, kwargs)
         new_index = self.index.repeat(repeats)

pandas/tests/arrays/categorical/test_analytics.py

@@ -295,22 +295,6 @@ def test_validate_inplace(self):
             with pytest.raises(ValueError):
                 cat.sort_values(inplace=value)
 
-    def test_repeat(self):
-        # GH10183
-        cat = Categorical(["a", "b"], categories=["a", "b"])
-        exp = Categorical(["a", "a", "b", "b"], categories=["a", "b"])
-        res = cat.repeat(2)
-        tm.assert_categorical_equal(res, exp)
-
-    def test_numpy_repeat(self):
-        cat = Categorical(["a", "b"], categories=["a", "b"])
-        exp = Categorical(["a", "a", "b", "b"], categories=["a", "b"])
-        tm.assert_categorical_equal(np.repeat(cat, 2), exp)
-
-        msg = "the 'axis' parameter is not supported"
-        with pytest.raises(ValueError, match=msg):
-            np.repeat(cat, 2, axis=1)
-
     def test_isna(self):
         exp = np.array([False, False, True])
         c = Categorical(["a", "b", np.nan])