DEPR: added deprecation warning for NDFrame.bool

doc/source/user_guide/basics.rst

@@ -329,16 +329,6 @@ You can test if a pandas object is empty, via the :attr:`~DataFrame.empty` prope
  df.empty
  pd.DataFrame(columns=list("ABC")).empty
 
-To evaluate single-element pandas objects in a boolean context, use the method
-:meth:`~DataFrame.bool`:
-
-.. ipython:: python
-
- pd.Series([True]).bool()
- pd.Series([False]).bool()
- pd.DataFrame([[True]]).bool()
- pd.DataFrame([[False]]).bool()
-
 .. warning::
 
  You might be tempted to do the following:

doc/source/user_guide/gotchas.rst

@@ -121,16 +121,6 @@ Below is how to check if any of the values are ``True``:
  if pd.Series([False, True, False]).any():
  print("I am any")
 
-To evaluate single-element pandas objects in a boolean context, use the method
-:meth:`~DataFrame.bool`:
-
-.. ipython:: python
-
- pd.Series([True]).bool()
- pd.Series([False]).bool()
- pd.DataFrame([[True]]).bool()
- pd.DataFrame([[False]]).bool()
-
 Bitwise boolean
 ~~~~~~~~~~~~~~~
 

doc/source/whatsnew/v0.13.0.rst

@@ -154,6 +154,7 @@ API changes
  Added the ``.bool()`` method to ``NDFrame`` objects to facilitate evaluating of single-element boolean Series:
 
  .. ipython:: python
+ :okwarning:
 
  pd.Series([True]).bool()
  pd.Series([False]).bool()

doc/source/whatsnew/v2.1.0.rst

@@ -110,6 +110,7 @@ Deprecations
 - Deprecated the ``axis`` keyword in :meth:`DataFrame.ewm`, :meth:`Series.ewm`, :meth:`DataFrame.rolling`, :meth:`Series.rolling`, :meth:`DataFrame.expanding`, :meth:`Series.expanding` (:issue:`51778`)
 - Deprecated 'method', 'limit', and 'fill_axis' keywords in :meth:`DataFrame.align` and :meth:`Series.align`, explicitly call ``fillna`` on the alignment results instead (:issue:`51856`)
 - Deprecated the 'axis' keyword in :meth:`.GroupBy.idxmax`, :meth:`.GroupBy.idxmin`, :meth:`.GroupBy.fillna`, :meth:`.GroupBy.take`, :meth:`.GroupBy.skew`, :meth:`.GroupBy.rank`, :meth:`.GroupBy.cumprod`, :meth:`.GroupBy.cumsum`, :meth:`.GroupBy.cummax`, :meth:`.GroupBy.cummin`, :meth:`.GroupBy.pct_change`, :meth:`GroupBy.diff`, :meth:`.GroupBy.shift`, and :meth:`DataFrameGroupBy.corrwith`; for ``axis=1`` operate on the underlying :class:`DataFrame` instead (:issue:`50405`, :issue:`51046`)
+- Deprecated '.bool' in :meth:`NDFrame.bool` (:issue:`51749`)
 -
 
 .. ---------------------------------------------------------------------------

pandas/conftest.py

@@ -137,6 +137,12 @@ def pytest_collection_modifyitems(items, config) -> None:
  ignored_doctest_warnings = [
  # Docstring divides by zero to show behavior difference
  ("missing.mask_zero_div_zero", "divide by zero encountered"),
+ (
+ "pandas.core.generic.NDFrame.bool",
+ "(Series|DataFrame).bool is now deprecated and will be removed "
+ "in future version of pandas and cases that relied on it will raise "
+ "a future warning",
+ ),
  ]
 
  for item in items:

pandas/core/generic.py

@@ -1504,6 +1504,14 @@ def bool(self) -> bool_t:
  >>> pd.DataFrame({'col': [False]}).bool()
  False
  """
+
+ warnings.warn(
+ f"{type(self).__name__}.bool is now deprecated and will be removed "
+ "in future version of pandas and cases that relied on it will raise "
+ "a future warning",
+ FutureWarning,
+ stacklevel=find_stack_level(),
+ )
  v = self.squeeze()
  if isinstance(v, (bool, np.bool_)):
  return bool(v)

pandas/tests/generic/test_frame.py

@@ -47,19 +47,28 @@ def test_set_axis_name_mi(self, func):
 
  def test_nonzero_single_element(self):
  # allow single item via bool method
+ msg = (
+ "DataFrame.bool is now deprecated and will be removed "
+ "in future version of pandas and cases that relied on it will raise "
+ "a future warning"
+ )
  df = DataFrame([[True]])
- assert df.bool()
+ df1 = DataFrame([[False]])
+ with tm.assert_produces_warning(FutureWarning, match=msg):
+ assert df.bool()
 
- df = DataFrame([[False]])
- assert not df.bool()
+ with tm.assert_produces_warning(FutureWarning, match=msg):
+  assert not df1.bool()
 
  df = DataFrame([[False, False]])
- msg = "The truth value of a DataFrame is ambiguous"
- with pytest.raises(ValueError, match=msg):
- df.bool()
- with pytest.raises(ValueError, match=msg):
+ msg1 = "The truth value of a DataFrame is ambiguous"
+ with pytest.raises(ValueError, match=msg1):
  bool(df)
 
+ with tm.assert_produces_warning(FutureWarning, match=msg):
+ with pytest.raises(ValueError, match=msg1):
+ df.bool()
+
  def test_metadata_propagation_indiv_groupby(self):
  # groupby
  df = DataFrame(

pandas/tests/generic/test_generic.py

@@ -448,3 +448,12 @@ def test_flags_identity(self, frame_or_series):
  assert obj.flags is obj.flags
  obj2 = obj.copy()
  assert obj2.flags is not obj.flags
+
+ def test_bool_dep(self) -> None:
+ msg = (
+ "DataFrame.bool is now deprecated and will be removed "
+ "in future version of pandas and cases that relied on it will raise "
+ "a future warning"
+ )
+ with tm.assert_produces_warning(FutureWarning, match=msg):
+ DataFrame({"col": [False]}).bool()

pandas/tests/generic/test_series.py

@@ -41,11 +41,17 @@ def test_get_bool_data_preserve_dtype(self):
 
  def test_nonzero_single_element(self):
  # allow single item via bool method
+ msg = (
+ "Series.bool is now deprecated and will be removed "
+ "in future version of pandas and cases that relied on it will raise "
+ "a future warning"
+ )
  ser = Series([True])
- assert ser.bool()
-
- ser = Series([False])
- assert not ser.bool()
+ ser1 = Series([False])
+ with tm.assert_produces_warning(FutureWarning, match=msg):
+ assert ser.bool()
+ with tm.assert_produces_warning(FutureWarning, match=msg):
+ assert not ser1.bool()
 
  @pytest.mark.parametrize("data", [np.nan, pd.NaT, True, False])
  def test_nonzero_single_element_raise_1(self, data):
@@ -58,35 +64,49 @@ def test_nonzero_single_element_raise_1(self, data):
 
  @pytest.mark.parametrize("data", [np.nan, pd.NaT])
  def test_nonzero_single_element_raise_2(self, data):
+ msg = (
+ "Series.bool is now deprecated and will be removed "
+ "in future version of pandas and cases that relied on it will raise "
+ "a future warning"
+ )
+ msg1 = "bool cannot act on a non-boolean single element Series"
  series = Series([data])
-
- msg = "bool cannot act on a non-boolean single element Series"
- with pytest.raises(ValueError, match=msg):
- series.bool()
+ with tm.assert_produces_warning(FutureWarning, match=msg):
+ with pytest.raises(ValueError, match=msg1):
+ series.bool()
 
  @pytest.mark.parametrize("data", [(True, True), (False, False)])
  def test_nonzero_multiple_element_raise(self, data):
  # multiple bool are still an error
+ msg = (
+ "Series.bool is now deprecated and will be removed "
+ "in future version of pandas and cases that relied on it will raise "
+ "a future warning"
+ )
+ msg1 = "The truth value of a Series is ambiguous"
  series = Series([data])
-
- msg = "The truth value of a Series is ambiguous"
- with pytest.raises(ValueError, match=msg):
+ with pytest.raises(ValueError, match=msg1):
  bool(series)
- with pytest.raises(ValueError, match=msg):
- series.bool()
+ with tm.assert_produces_warning(FutureWarning, match=msg):
+ with pytest.raises(ValueError, match=msg1):
+ series.bool()
 
  @pytest.mark.parametrize("data", [1, 0, "a", 0.0])
  def test_nonbool_single_element_raise(self, data):
  # single non-bool are an error
+ msg = (
+ "Series.bool is now deprecated and will be removed "
+ "in future version of pandas and cases that relied on it will raise "
+ "a future warning"
+ )
+ msg1 = "The truth value of a Series is ambiguous"
+ msg2 = "bool cannot act on a non-boolean single element Series"
  series = Series([data])
-
- msg = "The truth value of a Series is ambiguous"
- with pytest.raises(ValueError, match=msg):
+ with pytest.raises(ValueError, match=msg1):
  bool(series)
-
- msg = "bool cannot act on a non-boolean single element Series"
- with pytest.raises(ValueError, match=msg):
- series.bool()
+ with tm.assert_produces_warning(FutureWarning, match=msg):
+ with pytest.raises(ValueError, match=msg2):
+ series.bool()
 
  def test_metadata_propagation_indiv_resample(self):
  # resample

pandas/tests/window/test_timeseries_window.py

@@ -506,6 +506,7 @@ def test_perf_min(self):
  dfp = DataFrame(
  {"B": np.random.randn(N)}, index=date_range("20130101", periods=N, freq="s")
  )
+
  expected = dfp.rolling(2, min_periods=1).min()
  result = dfp.rolling("2s").min()
  assert ((result - expected) < 0.01).all().all()