Separate the example section from _interval_shared_docs

Author: makbigc

pandas/core/arrays/interval.py

@@ -222,7 +222,7 @@ def _from_factorized(cls, values, original):
             values = values.astype(original.dtype.subtype)
         return cls(values, closed=original.closed)
 
-    _interval_shared_docs['from_breaks'] = """
+    _interval_shared_docs['from_breaks'] = textwrap.dedent("""\
     Construct an %(klass)s from an array of splits.
 
     Parameters
@@ -249,23 +249,28 @@ def _from_factorized(cls, values, original):
     %(klass)s.from_arrays : Construct from a left and right array.
     %(klass)s.from_tuples : Construct from a sequence of tuples.
 
-    Examples
-    --------
-    >>> pd.%(qualname)s.from_breaks([0, 1, 2, 3])
-    %(klass)s([(0, 1], (1, 2], (2, 3]],
-                  closed='right',
-                  dtype='interval[int64]')
-    """
+    %(examples)s\
+    """)
 
     @classmethod
-    @Appender(_interval_shared_docs['from_breaks'] % _shared_docs_kwargs)
+    @Appender(_interval_shared_docs['from_breaks'] % dict(
+        klass='IntervalArray',
+        examples=textwrap.dedent("""\
+        Examples
+        --------
+        >>> pd.arrays.IntervalArray.from_breaks([0, 1, 2, 3])
+        <IntervalArray>
+        [(0, 1], (1, 2], (2, 3]]
+        Length: 3, closed: right, dtype: interval[int64]
+        """),
+    ))
     def from_breaks(cls, breaks, closed='right', copy=False, dtype=None):
         breaks = maybe_convert_platform_interval(breaks)
 
         return cls.from_arrays(breaks[:-1], breaks[1:], closed, copy=copy,
                                dtype=dtype)
 
-    _interval_shared_docs['from_arrays'] = """
+    _interval_shared_docs['from_arrays'] = textwrap.dedent("""
         Construct from two arrays defining the left and right bounds.
 
         Parameters
@@ -311,16 +316,19 @@ def from_breaks(cls, breaks, closed='right', copy=False, dtype=None):
         using an unsupported type for `left` or `right`. At the moment,
         'category', 'object', and 'string' subtypes are not supported.
 
-        Examples
-        --------
-        >>> %(klass)s.from_arrays([0, 1, 2], [1, 2, 3])
-        %(klass)s([(0, 1], (1, 2], (2, 3]],
-                     closed='right',
-                     dtype='interval[int64]')
-        """
+        %(examples)s\
+        """)
 
     @classmethod
-    @Appender(_interval_shared_docs['from_arrays'] % _shared_docs_kwargs)
+    @Appender(_interval_shared_docs['from_arrays'] % dict(
+        klass='IntervalArray',
+        examples=textwrap.dedent("""\
+        >>> pd.arrays.IntervalArray.from_arrays([0, 1, 2], [1, 2, 3])
+        <IntervalArray>
+        [(0, 1], (1, 2], (2, 3]]
+        Length: 3, closed: right, dtype: interval[int64]
+        """),
+    ))
     def from_arrays(cls, left, right, closed='right', copy=False, dtype=None):
         left = maybe_convert_platform_interval(left)
         right = maybe_convert_platform_interval(right)
@@ -370,7 +378,7 @@ def from_arrays(cls, left, right, closed='right', copy=False, dtype=None):
                   closed='right', dtype='interval[int64]')
     """
 
-    _interval_shared_docs['from_tuples'] = """
+    _interval_shared_docs['from_tuples'] = textwrap.dedent("""\
     Construct an %(klass)s from an array-like of tuples
 
     Parameters
@@ -399,15 +407,21 @@ def from_arrays(cls, left, right, closed='right', copy=False, dtype=None):
     %(klass)s.from_breaks : Construct an %(klass)s from an array of
                                 splits.
 
-    Examples
-    --------
-    >>> pd.%(qualname)s.from_tuples([(0, 1), (1, 2)])
-    %(klass)s([(0, 1], (1, 2]],
-                closed='right', dtype='interval[int64]')
-    """
+    %(examples)s\
+    """)
 
     @classmethod
-    @Appender(_interval_shared_docs['from_tuples'] % _shared_docs_kwargs)
+    @Appender(_interval_shared_docs['from_tuples'] % dict(
+        klass='IntervalArray',
+        examples=textwrap.dedent("""\
+        Examples
+        --------
+        >>> pd.arrays.IntervalArray.from_tuples([(0, 1), (1, 2)])
+        <IntervalArray>
+        [(0, 1], (1, 2]]
+        Length: 2, closed: right, dtype: interval[int64]
+        """),
+    ))
     def from_tuples(cls, data, closed='right', copy=False, dtype=None):
         if len(data):
             left, right = [], []
@@ -886,7 +900,7 @@ def closed(self):
         """
         return self._closed
 
-    _interval_shared_docs['set_closed'] = """
+    _interval_shared_docs['set_closed'] = textwrap.dedent("""\
         Return an %(klass)s identical to the current one, but closed on the
         specified side
 
@@ -902,20 +916,25 @@ def closed(self):
         -------
         new_index : %(klass)s
 
+        %(examples)s\
+        """)
+
+    @Appender(_interval_shared_docs['set_closed'] % dict(
+        klass='IntervalArray',
+        examples=textwrap.dedent("""\
         Examples
         --------
-        >>> index = pd.interval_range(0, 3)
+        >>> index = pd.arrays.IntervalArray.from_breaks(range(4))
         >>> index
-        IntervalIndex([(0, 1], (1, 2], (2, 3]],
-              closed='right',
-              dtype='interval[int64]')
+        <IntervalArray>
+        [(0, 1], (1, 2], (2, 3]]
+        Length: 3, closed: right, dtype: interval[int64]
         >>> index.set_closed('both')
-        IntervalIndex([[0, 1], [1, 2], [2, 3]],
-              closed='both',
-              dtype='interval[int64]')
-        """
-
-    @Appender(_interval_shared_docs['set_closed'] % _shared_docs_kwargs)
+        <IntervalArray>
+        [[0, 1], [1, 2], [2, 3]]
+        Length: 3, closed: both, dtype: interval[int64]
+        """),
+    ))
     def set_closed(self, closed):
         if closed not in _VALID_CLOSED:
             msg = "invalid option for 'closed': {closed}"
@@ -1028,7 +1047,7 @@ def repeat(self, repeats, axis=None):
         right_repeat = self.right.repeat(repeats)
         return self._shallow_copy(left=left_repeat, right=right_repeat)
 
-    _interval_shared_docs['overlaps'] = """
+    _interval_shared_docs['overlaps'] = textwrap.dedent("""
         Check elementwise if an Interval overlaps the values in the %(klass)s.
 
         Two intervals overlap if they share a common point, including closed
@@ -1039,7 +1058,7 @@ def repeat(self, repeats, axis=None):
 
         Parameters
         ----------
-        other : Interval
+        other : %(klass)s
             Interval to check against for an overlap.
 
         Returns
@@ -1053,11 +1072,7 @@ def repeat(self, repeats, axis=None):
 
         Examples
         --------
-        >>> intervals = pd.%(qualname)s.from_tuples([(0, 1), (1, 3), (2, 4)])
-        >>> intervals
-        <%(klass)s>
-        [(0, 1], (1, 3], (2, 4]]
-        Length: 3, closed: right, dtype: interval[int64]
+        %(examples)s
 
         >>> intervals.overlaps(pd.Interval(0.5, 1.5))
         array([ True,  True, False])
@@ -1071,9 +1086,20 @@ def repeat(self, repeats, axis=None):
 
         >>> intervals.overlaps(pd.Interval(1, 2, closed='right'))
         array([False,  True, False])
-    """
 
-    @Appender(_interval_shared_docs['overlaps'] % _shared_docs_kwargs)
+        """)
+
+    @Appender(_interval_shared_docs['overlaps'] % dict(
+        klass='IntervalArray',
+        examples=textwrap.dedent("""\
+        >>> intervals = pd.arrays.IntervalArray.from_tuples([(0, 1), (1, 3),\
+                                                             (2, 4)])
+        >>> intervals
+        <IntervalArray>
+        [(0, 1], (1, 3], (2, 4]]
+        Length: 3, closed: right, dtype: interval[int64]
+        """),
+    ))
     def overlaps(self, other):
         if isinstance(other, (IntervalArray, ABCIntervalIndex)):
             raise NotImplementedError

pandas/core/indexes/interval.py

@@ -206,7 +206,17 @@ def _simple_new(cls, array, name, closed=None):
         return result
 
     @classmethod
-    @Appender(_interval_shared_docs['from_breaks'] % _index_doc_kwargs)
+    @Appender(_interval_shared_docs['from_breaks'] % dict(
+        klass='IntervalIndex',
+        examples=textwrap.dedent("""\
+        Examples
+        --------
+        >>> pd.IntervalIndex.from_breaks([0, 1, 2, 3])
+        IntervalIndex([(0, 1], (1, 2], (2, 3]],
+                      closed='right',
+                      dtype='interval[int64]')
+        """),
+    ))
     def from_breaks(cls, breaks, closed='right', name=None, copy=False,
                     dtype=None):
         with rewrite_exception("IntervalArray", cls.__name__):
@@ -215,7 +225,17 @@ def from_breaks(cls, breaks, closed='right', name=None, copy=False,
         return cls._simple_new(array, name=name)
 
     @classmethod
-    @Appender(_interval_shared_docs['from_arrays'] % _index_doc_kwargs)
+    @Appender(_interval_shared_docs['from_arrays'] % dict(
+        klass='IntervalIndex',
+        examples=textwrap.dedent("""\
+        Examples
+        --------
+        >>> pd.IntervalIndex.from_arrays([0, 1, 2], [1, 2, 3])
+        IntervalIndex([(0, 1], (1, 2], (2, 3]],
+                      closed='right',
+                      dtype='interval[int64]')
+        """),
+    ))
     def from_arrays(cls, left, right, closed='right', name=None, copy=False,
                     dtype=None):
         with rewrite_exception("IntervalArray", cls.__name__):
@@ -239,7 +259,17 @@ def from_intervals(cls, data, closed=None, name=None, copy=False,
         return cls._simple_new(array, name=name)
 
     @classmethod
-    @Appender(_interval_shared_docs['from_tuples'] % _index_doc_kwargs)
+    @Appender(_interval_shared_docs['from_tuples'] % dict(
+        klass='IntervalIndex',
+        examples=textwrap.dedent("""\
+        Examples
+        --------
+        >>> pd.IntervalIndex.from_tuples([(0, 1), (1, 2)])
+        IntervalIndex([(0, 1], (1, 2]],
+                       closed='right',
+                       dtype='interval[int64]')
+        """),
+    ))
     def from_tuples(cls, data, closed='right', name=None, copy=False,
                     dtype=None):
         with rewrite_exception("IntervalArray", cls.__name__):
@@ -356,7 +386,22 @@ def closed(self):
         """
         return self._data._closed
 
-    @Appender(_interval_shared_docs['set_closed'] % _index_doc_kwargs)
+    @Appender(_interval_shared_docs['set_closed'] % dict(
+        klass='IntervalIndex',
+        examples=textwrap.dedent("""\
+        Examples
+        --------
+        >>> index = pd.interval_range(0, 3)
+        >>> index
+        IntervalIndex([(0, 1], (1, 2], (2, 3]],
+                      closed='right',
+                      dtype='interval[int64]')
+        >>> index.set_closed('both')
+        IntervalIndex([[0, 1], [1, 2], [2, 3]],
+                      closed='both',
+                      dtype='interval[int64]')
+        """),
+    ))
     def set_closed(self, closed):
         if closed not in _VALID_CLOSED:
             msg = "invalid option for 'closed': {closed}"
@@ -1134,52 +1179,17 @@ def equals(self, other):
                 self.right.equals(other.right) and
                 self.closed == other.closed)
 
-    def overlaps(self, other):
-        """
-        Check elementwise if an Interval overlaps the values in the
-        IntervalIndex.
-
-        Two intervals overlap if they share a common point, including closed
-        endpoints. Intervals that only have an open endpoint in common do not
-        overlap.
-
-        .. versionadded:: 0.24.0
-
-        Parameters
-        ----------
-        other : Interval
-            Interval to check against for an overlap.
-
-        Returns
-        -------
-        ndarray
-            Boolean array positionally indicating where an overlap occurs.
-
-        See Also
-        --------
-        Interval.overlaps : Check whether two Interval objects overlap.
-
-        Examples
-        --------
+    @Appender(_interval_shared_docs['overlaps'] % dict(
+        klass='IntervalIndex',
+        examples=textwrap.dedent("""\
         >>> intervals = pd.IntervalIndex.from_tuples([(0, 1), (1, 3), (2, 4)])
         >>> intervals
         IntervalIndex([(0, 1], (1, 3], (2, 4]],
               closed='right',
               dtype='interval[int64]')
-
-        >>> intervals.overlaps(pd.Interval(0.5, 1.5))
-        array([ True,  True, False])
-
-        Intervals that share closed endpoints overlap:
-
-        >>> intervals.overlaps(pd.Interval(1, 3, closed='left'))
-        array([ True,  True, True])
-
-        Intervals that only have an open endpoint in common do not overlap:
-
-        >>> intervals.overlaps(pd.Interval(1, 2, closed='right'))
-        array([False,  True, False])
-        """
+        """),
+    ))
+    def overlaps(self, other):
         return self._data.overlaps(other)
 
     @Appender(_index_shared_docs['intersection'])