DEPR: flags

doc/source/user_guide/duplicates.rst

@@ -121,13 +121,15 @@ will be raised.
 
 .. ipython:: python
    :okexcept:
+   :okwarning:
 
    pd.Series([0, 1, 2], index=["a", "b", "b"]).set_flags(allows_duplicate_labels=False)
 
 This applies to both row and column labels for a :class:`DataFrame`
 
 .. ipython:: python
    :okexcept:
+   :okwarning:
 
    pd.DataFrame([[0, 1, 2], [3, 4, 5]], columns=["A", "B", "C"],).set_flags(
        allows_duplicate_labels=False
@@ -137,6 +139,7 @@ This attribute can be checked or set with :attr:`~DataFrame.flags.allows_duplica
 which indicates whether that object can have duplicate labels.
 
 .. ipython:: python
+   :okwarning:
 
    df = pd.DataFrame({"A": [0, 1, 2, 3]}, index=["x", "y", "X", "Y"]).set_flags(
        allows_duplicate_labels=False
@@ -148,6 +151,7 @@ which indicates whether that object can have duplicate labels.
 like ``allows_duplicate_labels`` set to some value
 
 .. ipython:: python
+   :okwarning:
 
    df2 = df.set_flags(allows_duplicate_labels=True)
    df2.flags.allows_duplicate_labels
@@ -157,6 +161,7 @@ Or the property can just be set directly on the same object
 
 
 .. ipython:: python
+   :okwarning:
 
    df2.flags.allows_duplicate_labels = False
    df2.flags.allows_duplicate_labels
@@ -193,6 +198,7 @@ operations.
 
 .. ipython:: python
    :okexcept:
+   :okwarning:
 
    s1 = pd.Series(0, index=["a", "b"]).set_flags(allows_duplicate_labels=False)
    s1

doc/source/whatsnew/v2.2.0.rst

@@ -597,6 +597,7 @@ Other Deprecations
 - Deprecated :func:`pd.core.internals.api.make_block`, use public APIs instead (:issue:`40226`)
 - Deprecated :func:`read_gbq` and :meth:`DataFrame.to_gbq`. Use ``pandas_gbq.read_gbq`` and ``pandas_gbq.to_gbq`` instead https://pandas-gbq.readthedocs.io/en/latest/api.html (:issue:`55525`)
 - Deprecated :meth:`.DataFrameGroupBy.fillna` and :meth:`.SeriesGroupBy.fillna`; use :meth:`.DataFrameGroupBy.ffill`, :meth:`.DataFrameGroupBy.bfill` for forward and backward filling or :meth:`.DataFrame.fillna` to fill with a single value (or the Series equivalents) (:issue:`55718`)
+- Deprecated :meth:`DataFrame.flags`, :meth:`DataFrame.set_flags`, :meth:`Series.flags`, :meth:`Series.set_flags` (:issue:`51280`)
 - Deprecated :meth:`DatetimeArray.__init__` and :meth:`TimedeltaArray.__init__`, use :func:`array` instead (:issue:`55623`)
 - Deprecated :meth:`Index.format`, use ``index.astype(str)`` or ``index.map(formatter)`` instead (:issue:`55413`)
 - Deprecated :meth:`Series.ravel`, the underlying array is already 1D, so ravel is not necessary (:issue:`52511`)

pandas/_testing/asserters.py

@@ -893,7 +893,9 @@ def assert_series_equal(
         raise_assert_detail(obj, "Series length are different", msg1, msg2)
 
     if check_flags:
-        assert left.flags == right.flags, f"{repr(left.flags)} != {repr(right.flags)}"
+        assert (
+            left._flags == right._flags
+        ), f"{repr(left._flags)} != {repr(right._flags)}"
 
     if check_index:
         # GH #38183
@@ -1166,7 +1168,9 @@ def assert_frame_equal(
         )
 
     if check_flags:
-        assert left.flags == right.flags, f"{repr(left.flags)} != {repr(right.flags)}"
+        assert (
+            left._flags == right._flags
+        ), f"{repr(left._flags)} != {repr(right._flags)}"
 
     # index comparison
     assert_index_equal(

pandas/conftest.py

@@ -168,6 +168,30 @@ def pytest_collection_modifyitems(items, config) -> None:
             "(Series|DataFrame).bool is now deprecated and will be removed "
             "in future version of pandas",
         ),
+        (
+            "Flags",
+            "DataFrame.flags is deprecated and will be removed in a future version",
+        ),
+        (
+            "flags",
+            "DataFrame.flags is deprecated and will be removed in a future version",
+        ),
+        (
+            "allows_duplicate_labels",
+            "DataFrame.flags is deprecated and will be removed in a future version",
+        ),
+        (
+            "set_flags",
+            "DataFrame.set_flags is deprecated and will be removed in a future version",
+        ),
+        (
+            "DuplicateLabelError",
+            "Series.set_flags is deprecated and will be removed in a future version",
+        ),
+        (
+            "DuplicateLabelError",
+            "Series.flags is deprecated and will be removed in a future version",
+        ),
         (
             "pandas.core.generic.NDFrame.first",
             "first is deprecated and will be removed in a future version. "

pandas/core/frame.py

@@ -5106,7 +5106,7 @@ def insert(
         """
         if allow_duplicates is lib.no_default:
             allow_duplicates = False
-        if allow_duplicates and not self.flags.allows_duplicate_labels:
+        if allow_duplicates and not self._flags.allows_duplicate_labels:
             raise ValueError(
                 "Cannot specify 'allow_duplicates=True' when "
                 "'self.flags.allows_duplicate_labels' is False."

pandas/core/generic.py

@@ -440,6 +440,12 @@ def flags(self) -> Flags:
         False
         >>> df.flags["allows_duplicate_labels"] = True
         """
+        warnings.warn(
+            f"{type(self).__name__}.flags is deprecated and will be removed "
+            "in a future version",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
         return self._flags
 
     @final
@@ -502,6 +508,13 @@ def set_flags(
         >>> df2.flags.allows_duplicate_labels
         False
         """
+        warnings.warn(
+            f"{type(self).__name__}.set_flags is deprecated and will be removed "
+            "in a future version",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+
         df = self.copy(deep=copy and not using_copy_on_write())
         if allows_duplicate_labels is not None:
             df.flags["allows_duplicate_labels"] = allows_duplicate_labels
@@ -2178,7 +2191,7 @@ def __getstate__(self) -> dict[str, Any]:
             "_typ": self._typ,
             "_metadata": self._metadata,
             "attrs": self.attrs,
-            "_flags": {k: self.flags[k] for k in self.flags._keys},
+            "_flags": {k: self._flags[k] for k in self._flags._keys},
             **meta,
         }
 
@@ -4511,7 +4524,7 @@ def __delitem__(self, key) -> None:
 
     @final
     def _check_inplace_and_allows_duplicate_labels(self, inplace: bool_t):
-        if inplace and not self.flags.allows_duplicate_labels:
+        if inplace and not self._flags.allows_duplicate_labels:
             raise ValueError(
                 "Cannot specify 'inplace=True' when "
                 "'self.flags.allows_duplicate_labels' is False."
@@ -6253,7 +6266,7 @@ def __finalize__(self, other, method: str | None = None, **kwargs) -> Self:
                 # of an empty dict is 50x more expensive than the empty check.
                 self.attrs = deepcopy(other.attrs)
 
-            self.flags.allows_duplicate_labels = other.flags.allows_duplicate_labels
+            self._flags.allows_duplicate_labels = other._flags.allows_duplicate_labels
             # For subclasses using _metadata.
             for name in set(self._metadata) & set(other._metadata):
                 assert isinstance(name, str)
@@ -6269,9 +6282,9 @@ def __finalize__(self, other, method: str | None = None, **kwargs) -> Self:
                     self.attrs = deepcopy(attrs)
 
             allows_duplicate_labels = all(
-                x.flags.allows_duplicate_labels for x in other.objs
+                x._flags.allows_duplicate_labels for x in other.objs
             )
-            self.flags.allows_duplicate_labels = allows_duplicate_labels
+            self._flags.allows_duplicate_labels = allows_duplicate_labels
 
         return self
 

pandas/tests/copy_view/test_methods.py

@@ -122,8 +122,12 @@ def test_copy_shallow(using_copy_on_write, warn_copy_on_write):
 def test_methods_copy_keyword(
     request, method, copy, using_copy_on_write, using_array_manager
 ):
+    warn = None
+    msg = "(DataFrame|Series).set_flags is deprecated"
     index = None
-    if "to_timestamp" in request.node.callspec.id:
+    if "set_flags" in request.node.callspec.id:
+        warn = FutureWarning
+    elif "to_timestamp" in request.node.callspec.id:
         index = period_range("2012-01-01", freq="D", periods=3)
     elif "to_period" in request.node.callspec.id:
         index = date_range("2012-01-01", freq="D", periods=3)
@@ -139,7 +143,8 @@ def test_methods_copy_keyword(
         with tm.assert_produces_warning(FutureWarning, match=msg):
             df2 = method(df, copy=copy)
     else:
-        df2 = method(df, copy=copy)
+        with tm.assert_produces_warning(warn, match=msg):
+            df2 = method(df, copy=copy)
 
     share_memory = using_copy_on_write or copy is False
 
@@ -197,8 +202,12 @@ def test_methods_copy_keyword(
     ],
 )
 def test_methods_series_copy_keyword(request, method, copy, using_copy_on_write):
+    warn = None
+    msg = "(DataFrame|Series).set_flags is deprecated"
     index = None
-    if "to_timestamp" in request.node.callspec.id:
+    if "set_flags" in request.node.callspec.id:
+        warn = FutureWarning
+    elif "to_timestamp" in request.node.callspec.id:
         index = period_range("2012-01-01", freq="D", periods=3)
     elif "to_period" in request.node.callspec.id:
         index = date_range("2012-01-01", freq="D", periods=3)
@@ -216,7 +225,8 @@ def test_methods_series_copy_keyword(request, method, copy, using_copy_on_write)
         with tm.assert_produces_warning(FutureWarning, match=msg):
             ser2 = method(ser, copy=copy)
     else:
-        ser2 = method(ser, copy=copy)
+        with tm.assert_produces_warning(warn, match=msg):
+            ser2 = method(ser, copy=copy)
 
     share_memory = using_copy_on_write or copy is False
 
@@ -1285,7 +1295,9 @@ def test_series_set_axis(using_copy_on_write):
 def test_set_flags(using_copy_on_write, warn_copy_on_write):
     ser = Series([1, 2, 3])
     ser_orig = ser.copy()
-    ser2 = ser.set_flags(allows_duplicate_labels=False)
+    msg = "Series.set_flags is deprecated"
+    with tm.assert_produces_warning(FutureWarning, match=msg):
+        ser2 = ser.set_flags(allows_duplicate_labels=False)
 
     assert np.shares_memory(ser, ser2)
 

pandas/tests/frame/methods/test_reset_index.py

@@ -441,7 +441,9 @@ def test_reset_index_duplicate_columns_allow(
     ):
         # GH#44755 reset_index with duplicate column labels
         df = multiindex_df.rename_axis("A")
-        df = df.set_flags(allows_duplicate_labels=flag)
+        msg = "DataFrame.set_flags is deprecated"
+        with tm.assert_produces_warning(FutureWarning, match=msg):
+            df = df.set_flags(allows_duplicate_labels=flag)
 
         if flag and allow_duplicates:
             result = df.reset_index(allow_duplicates=allow_duplicates)
@@ -464,7 +466,9 @@ def test_reset_index_duplicate_columns_allow(
     @pytest.mark.parametrize("flag", [False, True])
     def test_reset_index_duplicate_columns_default(self, multiindex_df, flag):
         df = multiindex_df.rename_axis("A")
-        df = df.set_flags(allows_duplicate_labels=flag)
+        msg = "DataFrame.set_flags is deprecated"
+        with tm.assert_produces_warning(FutureWarning, match=msg):
+            df = df.set_flags(allows_duplicate_labels=flag)
 
         msg = r"cannot insert \('A', ''\), already exists"
         with pytest.raises(ValueError, match=msg):

pandas/tests/frame/test_api.py

@@ -334,19 +334,25 @@ def test_set_flags(
             obj = obj["A"]
             key = 0
 
-        result = obj.set_flags(allows_duplicate_labels=allows_duplicate_labels)
+        set_msg = "(DataFrame|Series).set_flags is deprecated"
+        with tm.assert_produces_warning(FutureWarning, match=set_msg):
+            result = obj.set_flags(allows_duplicate_labels=allows_duplicate_labels)
 
+        get_msg = "(DataFrame|Series).flags is deprecated"
         if allows_duplicate_labels is None:
             # We don't update when it's not provided
-            assert result.flags.allows_duplicate_labels is True
+            with tm.assert_produces_warning(FutureWarning, match=get_msg):
+                assert result.flags.allows_duplicate_labels is True
         else:
-            assert result.flags.allows_duplicate_labels is allows_duplicate_labels
+            with tm.assert_produces_warning(FutureWarning, match=get_msg):
+                assert result.flags.allows_duplicate_labels is allows_duplicate_labels
 
         # We made a copy
         assert obj is not result
 
         # We didn't mutate obj
-        assert obj.flags.allows_duplicate_labels is True
+        with tm.assert_produces_warning(FutureWarning, match=get_msg):
+            assert obj.flags.allows_duplicate_labels is True
 
         # But we didn't copy data
         if frame_or_series is Series:
@@ -365,9 +371,10 @@ def test_set_flags(
                 result.iloc[key] = 1
 
         # Now we do copy.
-        result = obj.set_flags(
-            copy=True, allows_duplicate_labels=allows_duplicate_labels
-        )
+        with tm.assert_produces_warning(FutureWarning, match=set_msg):
+            result = obj.set_flags(
+                copy=True, allows_duplicate_labels=allows_duplicate_labels
+            )
         result.iloc[key] = 10
         assert obj.iloc[key] == 1
 
@@ -387,6 +394,9 @@ def test_inspect_getmembers(self):
         df = DataFrame()
         msg = "DataFrame._data is deprecated"
         with tm.assert_produces_warning(
-            DeprecationWarning, match=msg, check_stacklevel=False
+            # FutureWarning is for DataFrame.flags
+            (FutureWarning, DeprecationWarning),
+            match=msg,
+            check_stacklevel=False,
         ):
             inspect.getmembers(df)