ENH: consistency of input args for boundaries - Interval (#46522)

Author: Khor Chean Wei

asv_bench/benchmarks/reshape.py

@@ -268,7 +268,9 @@ def setup(self, bins):
         self.datetime_series = pd.Series(
             np.random.randint(N, size=N), dtype="datetime64[ns]"
         )
-        self.interval_bins = pd.IntervalIndex.from_breaks(np.linspace(0, N, bins))
+        self.interval_bins = pd.IntervalIndex.from_breaks(
+            np.linspace(0, N, bins), "right"
+        )
 
     def time_cut_int(self, bins):
         pd.cut(self.int_series, bins)

doc/redirects.csv

@@ -741,11 +741,11 @@ generated/pandas.Index.values,../reference/api/pandas.Index.values
 generated/pandas.Index.view,../reference/api/pandas.Index.view
 generated/pandas.Index.where,../reference/api/pandas.Index.where
 generated/pandas.infer_freq,../reference/api/pandas.infer_freq
-generated/pandas.Interval.closed,../reference/api/pandas.Interval.closed
+generated/pandas.Interval.inclusive,../reference/api/pandas.Interval.inclusive
 generated/pandas.Interval.closed_left,../reference/api/pandas.Interval.closed_left
 generated/pandas.Interval.closed_right,../reference/api/pandas.Interval.closed_right
 generated/pandas.Interval,../reference/api/pandas.Interval
-generated/pandas.IntervalIndex.closed,../reference/api/pandas.IntervalIndex.closed
+generated/pandas.IntervalIndex.inclusive,../reference/api/pandas.IntervalIndex.inclusive
 generated/pandas.IntervalIndex.contains,../reference/api/pandas.IntervalIndex.contains
 generated/pandas.IntervalIndex.from_arrays,../reference/api/pandas.IntervalIndex.from_arrays
 generated/pandas.IntervalIndex.from_breaks,../reference/api/pandas.IntervalIndex.from_breaks

doc/source/reference/arrays.rst

@@ -303,7 +303,7 @@ Properties
 .. autosummary::
    :toctree: api/
 
-   Interval.closed
+   Interval.inclusive
    Interval.closed_left
    Interval.closed_right
    Interval.is_empty
@@ -340,7 +340,7 @@ A collection of intervals may be stored in an :class:`arrays.IntervalArray`.
 
       arrays.IntervalArray.left
       arrays.IntervalArray.right
-      arrays.IntervalArray.closed
+      arrays.IntervalArray.inclusive
       arrays.IntervalArray.mid
       arrays.IntervalArray.length
       arrays.IntervalArray.is_empty

doc/source/reference/indexing.rst

@@ -242,7 +242,7 @@ IntervalIndex components
    IntervalIndex.left
    IntervalIndex.right
    IntervalIndex.mid
-   IntervalIndex.closed
+   IntervalIndex.inclusive
    IntervalIndex.length
    IntervalIndex.values
    IntervalIndex.is_empty

doc/source/user_guide/advanced.rst

@@ -1020,7 +1020,7 @@ Trying to select an ``Interval`` that is not exactly contained in the ``Interval
 
    In [7]: df.loc[pd.Interval(0.5, 2.5)]
    ---------------------------------------------------------------------------
-   KeyError: Interval(0.5, 2.5, closed='right')
+   KeyError: Interval(0.5, 2.5, inclusive='right')
 
 Selecting all ``Intervals`` that overlap a given ``Interval`` can be performed using the
 :meth:`~IntervalIndex.overlaps` method to create a boolean indexer.

doc/source/whatsnew/v0.20.0.rst

@@ -448,7 +448,7 @@ Selecting via a specific interval:
 
 .. ipython:: python
 
-   df.loc[pd.Interval(1.5, 3.0)]
+   df.loc[pd.Interval(1.5, 3.0, "right")]
 
 Selecting via a scalar value that is contained *in* the intervals.
 

doc/source/whatsnew/v0.25.0.rst

@@ -584,18 +584,18 @@ this would previously return ``True`` for any ``Interval`` overlapping an ``Inte
 
 .. code-block:: python
 
-   In [4]: pd.Interval(1, 2, closed='neither') in ii
+   In [4]: pd.Interval(1, 2, inclusive='neither') in ii
    Out[4]: True
 
-   In [5]: pd.Interval(-10, 10, closed='both') in ii
+   In [5]: pd.Interval(-10, 10, inclusive='both') in ii
    Out[5]: True
 
 *New behavior*:
 
 .. ipython:: python
 
-   pd.Interval(1, 2, closed='neither') in ii
-   pd.Interval(-10, 10, closed='both') in ii
+   pd.Interval(1, 2, inclusive='neither') in ii
+   pd.Interval(-10, 10, inclusive='both') in ii
 
 The :meth:`~IntervalIndex.get_loc` method now only returns locations for exact matches to ``Interval`` queries, as opposed to the previous behavior of
 returning locations for overlapping matches.  A ``KeyError`` will be raised if an exact match is not found.
@@ -619,7 +619,7 @@ returning locations for overlapping matches.  A ``KeyError`` will be raised if a
 
    In [7]: ii.get_loc(pd.Interval(2, 6))
    ---------------------------------------------------------------------------
-   KeyError: Interval(2, 6, closed='right')
+   KeyError: Interval(2, 6, inclusive='right')
 
 Likewise, :meth:`~IntervalIndex.get_indexer` and :meth:`~IntervalIndex.get_indexer_non_unique` will also only return locations for exact matches
 to ``Interval`` queries, with ``-1`` denoting that an exact match was not found.
@@ -680,11 +680,11 @@ Similarly, a ``KeyError`` will be raised for non-exact matches instead of return
 
    In [6]: s[pd.Interval(2, 3)]
    ---------------------------------------------------------------------------
-   KeyError: Interval(2, 3, closed='right')
+   KeyError: Interval(2, 3, inclusive='right')
 
    In [7]: s.loc[pd.Interval(2, 3)]
    ---------------------------------------------------------------------------
-   KeyError: Interval(2, 3, closed='right')
+   KeyError: Interval(2, 3, inclusive='right')
 
 The :meth:`~IntervalIndex.overlaps` method can be used to create a boolean indexer that replicates the
 previous behavior of returning overlapping matches.

doc/source/whatsnew/v1.5.0.rst

@@ -669,7 +669,12 @@ Other Deprecations
 - Deprecated the methods :meth:`DataFrame.mad`, :meth:`Series.mad`, and the corresponding groupby methods (:issue:`11787`)
 - Deprecated positional arguments to :meth:`Index.join` except for ``other``, use keyword-only arguments instead of positional arguments (:issue:`46518`)
 - Deprecated indexing on a timezone-naive :class:`DatetimeIndex` using a string representing a timezone-aware datetime (:issue:`46903`, :issue:`36148`)
--
+- Deprecated the ``closed`` argument in :class:`Interval` in favor of ``inclusive`` argument; In a future version passing ``closed`` will raise (:issue:`40245`)
+- Deprecated the ``closed`` argument in :class:`IntervalIndex` in favor of ``inclusive`` argument; In a future version passing ``closed`` will raise (:issue:`40245`)
+- Deprecated the ``closed`` argument in :class:`IntervalDtype` in favor of ``inclusive`` argument; In a future version passing ``closed`` will raise (:issue:`40245`)
+- Deprecated the ``closed`` argument in :class:`IntervalArray` in favor of ``inclusive`` argument; In a future version passing ``closed`` will raise (:issue:`40245`)
+- Deprecated the ``closed`` argument in :class:`intervaltree` in favor of ``inclusive`` argument; In a future version passing ``closed`` will raise (:issue:`40245`)
+- Deprecated the ``closed`` argument in :class:`ArrowInterval` in favor of ``inclusive`` argument; In a future version passing ``closed`` will raise (:issue:`40245`)
 
 .. ---------------------------------------------------------------------------
 .. _whatsnew_150.performance:

pandas/_libs/interval.pyi

@@ -11,6 +11,7 @@ from typing import (
 import numpy as np
 import numpy.typing as npt
 
+from pandas._libs import lib
 from pandas._typing import (
     IntervalClosedType,
     Timedelta,
@@ -54,19 +55,24 @@ class IntervalMixin:
     def is_empty(self) -> bool: ...
     def _check_closed_matches(self, other: IntervalMixin, name: str = ...) -> None: ...
 
+def _warning_interval(
+    inclusive, closed
+) -> tuple[IntervalClosedType, lib.NoDefault]: ...
+
 class Interval(IntervalMixin, Generic[_OrderableT]):
     @property
     def left(self: Interval[_OrderableT]) -> _OrderableT: ...
     @property
     def right(self: Interval[_OrderableT]) -> _OrderableT: ...
     @property
-    def closed(self) -> IntervalClosedType: ...
+    def inclusive(self) -> IntervalClosedType: ...
     mid: _MidDescriptor
     length: _LengthDescriptor
     def __init__(
         self,
         left: _OrderableT,
         right: _OrderableT,
+        inclusive: IntervalClosedType = ...,
         closed: IntervalClosedType = ...,
     ) -> None: ...
     def __hash__(self) -> int: ...
@@ -157,7 +163,7 @@ class IntervalTree(IntervalMixin):
         self,
         left: np.ndarray,
         right: np.ndarray,
-        closed: IntervalClosedType = ...,
+        inclusive: IntervalClosedType = ...,
         leaf_size: int = ...,
     ) -> None: ...
     @property