ENH: New boundary inputs

doc/source/whatsnew/v1.3.0.rst

@@ -270,6 +270,7 @@ Other enhancements
 - Add keyword ``dropna`` to :meth:`DataFrame.value_counts` to allow counting rows that include ``NA`` values (:issue:`41325`)
 - :meth:`Series.replace` will now cast results to ``PeriodDtype`` where possible instead of ``object`` dtype (:issue:`41526`)
 - Improved error message in ``corr`` and ``cov`` methods on :class:`.Rolling`, :class:`.Expanding`, and :class:`.ExponentialMovingWindow` when ``other`` is not a :class:`DataFrame` or :class:`Series` (:issue:`41741`)
+- :meth:`Series.between` can now accept ``left`` or ``right`` as arguments to ``inclusive`` to include only the left or right boundary
 
 .. ---------------------------------------------------------------------------
 
@@ -715,6 +716,7 @@ Deprecations
 - Deprecated the ``level`` keyword for :class:`DataFrame` and :class:`Series` aggregations; use groupby instead (:issue:`39983`)
 - Deprecated the ``inplace`` parameter of :meth:`Categorical.remove_categories`, :meth:`Categorical.add_categories`, :meth:`Categorical.reorder_categories`, :meth:`Categorical.rename_categories`, :meth:`Categorical.set_categories` and will be removed in a future version (:issue:`37643`)
 - Deprecated :func:`merge` producing duplicated columns through the ``suffixes`` keyword  and already existing columns (:issue:`22818`)
+- Deprecated boolean arguments of ``inclusive`` in :meth:`Series.between` to have ``{"left", "right", "neither", "both"}`` as standard argument values (:issue:`40628`)
 - Deprecated setting :attr:`Categorical._codes`, create a new :class:`Categorical` with the desired codes instead (:issue:`40606`)
 - Deprecated the ``convert_float`` optional argument in :func:`read_excel` and :meth:`ExcelFile.parse` (:issue:`41127`)
 - Deprecated behavior of :meth:`DatetimeIndex.union` with mixed timezones; in a future version both will be cast to UTC instead of object dtype (:issue:`39328`)

pandas/core/series.py

@@ -4969,7 +4969,7 @@ def isin(self, values) -> Series:
             self, method="isin"
         )
 
-    def between(self, left, right, inclusive=True) -> Series:
+    def between(self, left, right, inclusive="both") -> Series:
         """
         Return boolean Series equivalent to left <= series <= right.
 
@@ -4983,8 +4983,11 @@ def between(self, left, right, inclusive=True) -> Series:
             Left boundary.
         right : scalar or list-like
             Right boundary.
-        inclusive : bool, default True
-            Include boundaries.
+        inclusive : {"both", "neither", "left", "right"}
+            Include boundaries. Whether to set each bound as closed or open.
+
+            .. versionchanged:: 1.3.0
+
 
         Returns
         -------
@@ -5035,12 +5038,34 @@ def between(self, left, right, inclusive=True) -> Series:
         3    False
         dtype: bool
         """
-        if inclusive:
+        if inclusive is True or inclusive is False:
+            warnings.warn(
+                "Boolean inputs to the `inclusive` argument are deprecated in"
+                "favour of `both` or `neither`.",
+                FutureWarning,
+                stacklevel=2,
+            )
+            if inclusive:
+                inclusive = "both"
+            else:
+                inclusive = "neither"
+        if inclusive == "both":
             lmask = self >= left
             rmask = self <= right
-        else:
+        elif inclusive == "left":
+            lmask = self >= left
+            rmask = self < right
+        elif inclusive == "right":
+            lmask = self > left
+            rmask = self <= right
+        elif inclusive == "neither":
             lmask = self > left
             rmask = self < right
+        else:
+            raise ValueError(
+                "Inclusive has to be either string of 'both',"
+                "'left', 'right', or 'neither'."
+            )
 
         return lmask & rmask
 

pandas/tests/series/methods/test_between.py

@@ -1,4 +1,5 @@
 import numpy as np
+import pytest
 
 from pandas import (
     Series,
@@ -38,3 +39,48 @@ def test_between_period_values(self):
         result = ser.between(left, right)
         expected = (ser >= left) & (ser <= right)
         tm.assert_series_equal(result, expected)
+
+    def test_between_inclusive_string(self):  # :issue:`40628`
+        series = Series(date_range("1/1/2000", periods=10))
+        left, right = series[[2, 7]]
+
+        result = series.between(left, right, inclusive="both")
+        expected = (series >= left) & (series <= right)
+        tm.assert_series_equal(result, expected)
+
+        result = series.between(left, right, inclusive="left")
+        expected = (series >= left) & (series < right)
+        tm.assert_series_equal(result, expected)
+
+        result = series.between(left, right, inclusive="right")
+        expected = (series > left) & (series <= right)
+        tm.assert_series_equal(result, expected)
+
+        result = series.between(left, right, inclusive="neither")
+        expected = (series > left) & (series < right)
+        tm.assert_series_equal(result, expected)
+
+    def test_between_error_args(self):  # :issue:`40628`
+        series = Series(date_range("1/1/2000", periods=10))
+        left, right = series[[2, 7]]
+
+        value_error_msg = (
+            "Inclusive has to be either string of 'both',"
+            "'left', 'right', or 'neither'."
+        )
+
+        with pytest.raises(ValueError, match=value_error_msg):
+            series = Series(date_range("1/1/2000", periods=10))
+            series.between(left, right, inclusive="yes")
+
+    def test_between_inclusive_warning(self):
+        series = Series(date_range("1/1/2000", periods=10))
+        left, right = series[[2, 7]]
+        with tm.assert_produces_warning(FutureWarning):
+            result = series.between(left, right, inclusive=False)
+            expected = (series > left) & (series < right)
+            tm.assert_series_equal(result, expected)
+        with tm.assert_produces_warning(FutureWarning):
+            result = series.between(left, right, inclusive=True)
+            expected = (series >= left) & (series <= right)
+            tm.assert_series_equal(result, expected)