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
 ~~~~~~~~~~~~~~~
 

pandas/conftest.py

@@ -137,6 +137,11 @@ 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",
+            "NDFrame.bool is now deprecated and will be removed in future releases "
+            "and cases that relied on it will raise in a future version",
+        ),
     ]
 
     for item in items:

pandas/core/generic.py

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

pandas/tests/generic/test_frame.py

@@ -47,18 +47,23 @@ def test_set_axis_name_mi(self, func):
 
     def test_nonzero_single_element(self):
         # allow single item via bool method
-        df = DataFrame([[True]])
-        assert df.bool()
-
-        df = DataFrame([[False]])
-        assert not df.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):
-            bool(df)
+        msg = (
+            "NDFrame.bool is now deprecated and will be removed in future releases "
+            "and cases that relied on it will raise in a future version"
+        )
+        with tm.assert_produces_warning(FutureWarning, match=msg):
+            df = DataFrame([[True]])
+            assert df.bool()
+
+            df = DataFrame([[False]])
+            assert not df.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):
+                bool(df)
 
     def test_metadata_propagation_indiv_groupby(self):
         # groupby

pandas/tests/generic/test_generic.py

@@ -441,3 +441,11 @@ 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 = (
+            "NDFrame.bool is now deprecated and will be removed in future releases "
+            "and cases that relied on it will raise in a future version"
+        )
+        with tm.assert_produces_warning(FutureWarning, match=msg):
+            DataFrame({"col": [False]}).bool()

pandas/tests/generic/test_series.py

@@ -41,11 +41,16 @@ def test_get_bool_data_preserve_dtype(self):
 
     def test_nonzero_single_element(self):
         # allow single item via bool method
-        ser = Series([True])
-        assert ser.bool()
+        msg = (
+            "NDFrame.bool is now deprecated and will be removed in future releases "
+            "and cases that relied on it will raise in a future version"
+        )
+        with tm.assert_produces_warning(FutureWarning, match=msg):
+            ser = Series([True])
+            assert ser.bool()
 
-        ser = Series([False])
-        assert not ser.bool()
+            ser = Series([False])
+            assert not ser.bool()
 
     @pytest.mark.parametrize("data", [np.nan, pd.NaT, True, False])
     def test_nonzero_single_element_raise_1(self, data):
@@ -58,35 +63,50 @@ 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):
-        series = Series([data])
+        msg = (
+            "NDFrame.bool is now deprecated and will be removed in future releases "
+            "and cases that relied on it will raise in a future version"
+        )
+        with tm.assert_produces_warning(FutureWarning, match=msg):
+            series = Series([data])
 
-        msg = "bool cannot act on a non-boolean single element Series"
-        with pytest.raises(ValueError, match=msg):
-            series.bool()
+            msg = "bool cannot act on a non-boolean single element Series"
+            with pytest.raises(ValueError, match=msg):
+                series.bool()
 
     @pytest.mark.parametrize("data", [(True, True), (False, False)])
     def test_nonzero_multiple_element_raise(self, data):
         # multiple bool are still an error
-        series = Series([data])
+        msg = (
+            "NDFrame.bool is now deprecated and will be removed in future releases "
+            "and cases that relied on it will raise in a future version"
+        )
+        with tm.assert_produces_warning(FutureWarning, match=msg):
+            series = Series([data])
 
-        msg = "The truth value of a Series is ambiguous"
-        with pytest.raises(ValueError, match=msg):
-            bool(series)
-        with pytest.raises(ValueError, match=msg):
-            series.bool()
+            msg = "The truth value of a Series is ambiguous"
+            with pytest.raises(ValueError, match=msg):
+                bool(series)
+            with pytest.raises(ValueError, match=msg):
+                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
-        series = Series([data])
+        msg = (
+            "NDFrame.bool is now deprecated and will be removed in future releases "
+            "and cases that relied on it will raise in a future version"
+        )
+        with tm.assert_produces_warning(FutureWarning, match=msg):
+            series = Series([data])
 
-        msg = "The truth value of a Series is ambiguous"
-        with pytest.raises(ValueError, match=msg):
-            bool(series)
+            msg = "The truth value of a Series is ambiguous"
+            with pytest.raises(ValueError, match=msg):
+                bool(series)
 
-        msg = "bool cannot act on a non-boolean single element Series"
-        with pytest.raises(ValueError, match=msg):
-            series.bool()
+            msg = "bool cannot act on a non-boolean single element Series"
+            with pytest.raises(ValueError, match=msg):
+                series.bool()
 
     def test_metadata_propagation_indiv_resample(self):
         # resample

pandas/tests/window/test_timeseries_window.py

@@ -506,13 +506,18 @@ 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().bool()
-
-        expected = dfp.rolling(200, min_periods=1).min()
-        result = dfp.rolling("200s").min()
-        assert ((result - expected) < 0.01).all().bool()
+        msg = (
+            "NDFrame.bool is now deprecated and will be removed in future releases "
+            "and cases that relied on it will raise in a future version"
+        )
+        with tm.assert_produces_warning(FutureWarning, match=msg):
+            expected = dfp.rolling(2, min_periods=1).min()
+            result = dfp.rolling("2s").min()
+            assert ((result - expected) < 0.01).all().bool()
+
+            expected = dfp.rolling(200, min_periods=1).min()
+            result = dfp.rolling("200s").min()
+            assert ((result - expected) < 0.01).all().bool()
 
     def test_ragged_max(self, ragged):
         df = ragged