todo

pandas-dev · jreback · Sep 3, 2020 · Jun 7, 2020 · Jun 8, 2020 · Jun 8, 2020
commit 4ced35143cc8809b24ddb2594c424ad0397b9ce9
diff --git a/pandas/_testing.py b/pandas/_testing.py
@@ -1431,6 +1431,7 @@ def assert_frame_equal(
     check_categorical=True,
     check_like=False,
     check_freq=True,
+    check_flags=True,
     rtol=1.0e-5,
     atol=1.0e-8,
     obj="DataFrame",
@@ -1492,6 +1493,8 @@ def assert_frame_equal(
         (same as in columns) - same labels must be with the same data.
     check_freq : bool, default True
         Whether to check the `freq` attribute on a DatetimeIndex or TimedeltaIndex.
+    check_flags : bool, default True
+        Whether to check the `flags` attribute.
     rtol : float, default 1e-5
         Relative tolerance. Only used when check_exact is False.
 
@@ -1565,6 +1568,9 @@ def assert_frame_equal(
     if check_like:
         left, right = left.reindex_like(right), right
 
+    if check_flags:
+        assert left.flags == right.flags
+
     # index comparison
     assert_index_equal(
         left.index,

diff --git a/pandas/core/_flags.py b/pandas/core/_flags.py
@@ -0,0 +1,99 @@
+import weakref
+
+
+class Flags:
+    """
+    Flags that apply to pandas objects.
+
+    Parameters
+    ----------
+    obj : Series or DataFrame
+        The object these flags are associated with
+    allows_duplicate_labels : bool
+        Whether the object allows duplicate labels
+
+    Notes
+    -----
+    Attributes can be set in two ways
+
+    >>> df = pd.DataFrame()
+    >>> df.flags
+    <Flags(allows_duplicate_labels=True)>
+    >>> df.flags.allows_duplicate_labels = False
+    >>> df.flags
+    <Flags(allows_duplicate_labels=False)>
+
+    >>> df.flags['allows_duplicate_labels'] = True
+    >>> df.flags
+    <Flags(allows_duplicate_labels=True)>
+    """
+
+    _keys = {"allows_duplicate_labels"}
+
+    def __init__(self, obj, *, allows_duplicate_labels):
+        self._allows_duplicate_labels = allows_duplicate_labels
+        self._obj = weakref.ref(obj)
+
+    @property
+    def allows_duplicate_labels(self) -> bool:
+        """
+        Whether this object allows duplicate labels.
+
+        Setting ``allows_duplicate_labels=False`` ensures that the
+        index (and columns of a DataFrame) are unique. Most methods
+        that accept and return a Series or DataFrame will propagate
+        the value of ``allows_duplicate_labels``.
+
+        See :ref:`duplicates` for more.
+
+        See Also
+        --------
+        DataFrame.attrs : Set global metadata on this object.
+        DataFrame.set_flags : Set global flags on this object.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({"A": [1, 2]}, index=['a', 'a'])
+        >>> df.allows_duplicate_labels
+        True
+        >>> df.allows_duplicate_labels = False
+        Traceback (most recent call last):
+            ...
+        pandas.errors.DuplicateLabelError: Index has duplicates.
+              positions
+        label
+        a        [0, 1]
+        """
+        return self._allows_duplicate_labels
+
+    @allows_duplicate_labels.setter
+    def allows_duplicate_labels(self, value: bool):
+        value = bool(value)
+        obj = self._obj()
+        if obj is None:
+            raise ValueError("This flags object has been deleted.")
+
+        if not value:
+            for ax in obj.axes:
+                ax._maybe_check_unique()
+
+        self._allows_duplicate_labels = value
+
+    def __getitem__(self, key):
+        if key not in self._keys:
+            raise KeyError(key)
+
+        return getattr(self, key)
+
+    def __setitem__(self, key, value):
+        if key not in self._keys:
+            raise ValueError(f"Unknown flag {key}. Must be one of {self._keys}")
+        setattr(self, key, value)
+
+    def __repr__(self):
+        return f"<Flags(allows_duplicate_labels={self.allows_duplicate_labels})>"
+
+    def __eq__(self, other):
+        if isinstance(other, type(self)):
+            return self.allows_duplicate_labels == other.allows_duplicate_labels
+        return False
diff --git a/pandas/core/frame.py b/pandas/core/frame.py
@@ -461,7 +461,6 @@ def __init__(
         columns: Optional[Axes] = None,
         dtype: Optional[Dtype] = None,
         copy: bool = False,
-        allows_duplicate_labels=True,
     ):
         if data is None:
             data = {}
@@ -475,7 +474,7 @@ def __init__(
             if index is None and columns is None and dtype is None and copy is False:
                 # GH#33357 fastpath
                 NDFrame.__init__(
-                    self, data, allows_duplicate_labels=allows_duplicate_labels
+                    self, data,
                 )
                 return
 
@@ -580,7 +579,7 @@ def __init__(
                     values, index, columns, dtype=values.dtype, copy=False
                 )
 
-        NDFrame.__init__(self, mgr, allows_duplicate_labels=allows_duplicate_labels)
+        NDFrame.__init__(self, mgr)
 
     # ----------------------------------------------------------------------
 
@@ -3673,10 +3672,10 @@ def insert(self, loc, column, value, allow_duplicates=False) -> None:
         value : int, Series, or array-like
         allow_duplicates : bool, optional
         """
-        if allow_duplicates and not self.allows_duplicate_labels:
+        if allow_duplicates and not self.flags.allows_duplicate_labels:
             raise ValueError(
                 "Cannot specify 'allow_duplicates=True' when "
-                "'self.allows_duplicate_labels' is False."
+                "'self.flags.allows_duplicate_labels' is False."
             )
         self._ensure_valid_index(value)
         value = self._sanitize_column(column, value, broadcast=False)

diff --git a/pandas/core/generic.py b/pandas/core/generic.py
@@ -89,6 +89,7 @@
 
 import pandas as pd
 from pandas.core import missing, nanops
+from pandas.core._flags import Flags
 import pandas.core.algorithms as algos
 from pandas.core.base import PandasObject, SelectionMixin
 import pandas.core.common as com
@@ -199,7 +200,6 @@ def __init__(
         self,
         data: BlockManager,
         copy: bool = False,
-        allows_duplicate_labels: bool = True,
         attrs: Optional[Mapping[Optional[Hashable], Any]] = None,
     ):
         # copy kwarg is retained for mypy compat, is not used
@@ -212,7 +212,7 @@ def __init__(
         else:
             attrs = dict(attrs)
         object.__setattr__(self, "_attrs", attrs)
-        object.__setattr__(self, "allows_duplicate_labels", allows_duplicate_labels)
+        object.__setattr__(self, "_flags", Flags(self, allows_duplicate_labels=True))
 
     @classmethod
     def _init_mgr(cls, mgr, axes, dtype=None, copy: bool = False) -> BlockManager:
@@ -253,54 +253,17 @@ def attrs(self, value: Mapping[Optional[Hashable], Any]) -> None:
         self._attrs = dict(value)
 
     @property
-    def allows_duplicate_labels(self) -> bool:
-        """
-        Whether this object allows duplicate labels.
-
-        Setting ``allows_duplicate_labels=False`` ensures that the
-        index (and columns of a DataFrame) are unique. Most methods
-        that accept and return a Series or DataFrame will propagate
-        the value of ``allows_duplicate_labels``.
-
-        See :ref:`duplicates` for more.
-
-        See Also
-        --------
-        DataFrame.attrs : Set global metadata on this object.
-        DataFrame.set_flags : Set global flags on this object.
-
-        Examples
-        --------
-        >>> df = pd.DataFrame({"A": [1, 2]}, index=['a', 'a'])
-        >>> df.allows_duplicate_labels
-        True
-        >>> df.allows_duplicate_labels = False
-        Traceback (most recent call last):
-            ...
-        pandas.errors.DuplicateLabelError: Index has duplicates.
-              positions
-        label
-        a        [0, 1]
-        """
-        return self._allows_duplicate_labels
-
-    @allows_duplicate_labels.setter
-    def allows_duplicate_labels(self, value: bool):
-        value = bool(value)
-        if not value:
-            for ax in self.axes:
-                ax._maybe_check_unique()
-
-        # avoid `can_hold_identifiers` check.
-        object.__setattr__(self, "_allows_duplicate_labels", value)
+    def flags(self) -> Flags:
+        return self._flags
 
     def set_flags(
-        self: FrameOrSeries, *, allows_duplicate_labels: Optional[bool] = None
+        self: FrameOrSeries,
+        *,
+        copy: bool = False,
+        allows_duplicate_labels: Optional[bool] = None,
     ) -> FrameOrSeries:
         """
-        Set global attributes on a copy of this object.
-
-        This method is intended to be used in method chains.
+        Return a new object with updated flags.
 
         Parameters
         ----------
@@ -312,6 +275,18 @@ def set_flags(
         Series or DataFrame
             The same type as the caller.
 
+        Notes
+        -----
+        This method returns a new object that's a view on the same data
+        as the input. Mutating the input or the output will be reflected
+        in the other.
+
+        This method is intended to be used in method chains.
+
+        "Flags" differ from "metadata". Flags reflect properties of the
+        pandas object (the Series or DataFrame). Metadata refer to properties
+        of the dataset, and should be stored in :attr:`DataFrame.attrs`.
+
         See Also
         --------
         DataFrame.attrs : Set global metadata on this object.
@@ -326,9 +301,9 @@ def set_flags(
         >>> df2.allows_duplicate_labels
         False
         """
-        df = self.copy()
+        df = self.copy(deep=copy)
         if allows_duplicate_labels is not None:
-            df.allows_duplicate_labels = allows_duplicate_labels
+            df.flags["allows_duplicate_labels"] = allows_duplicate_labels
         return df
 
     @classmethod
@@ -3889,10 +3864,10 @@ def __delitem__(self, key) -> None:
     # Unsorted
 
     def _check_inplace_and_allows_duplicate_labels(self, inplace):
-        if inplace and not self.allows_duplicate_labels:
+        if inplace and not self.flags.allows_duplicate_labels:
             raise ValueError(
                 "Cannot specify 'inplace=True' when "
-                "'self.allows_duplicate_labels' is False."
+                "'self.flags.allows_duplicate_labels' is False."
             )
 
     def get(self, key, default=None):
@@ -5298,15 +5273,17 @@ def __finalize__(
             for name in other.attrs:
                 self.attrs[name] = other.attrs[name]
 
-            self.allows_duplicate_labels = other.allows_duplicate_labels
+            self.flags.allows_duplicate_labels = other.flags.allows_duplicate_labels
             # For subclasses using _metadata.
             for name in self._metadata:
                 assert isinstance(name, str)
                 object.__setattr__(self, name, getattr(other, name, None))
 
         if method == "concat":
-            allows_duplicate_labels = all(x.allows_duplicate_labels for x in other.objs)
-            self.allows_duplicate_labels = allows_duplicate_labels
+            allows_duplicate_labels = all(
+                x.flags.allows_duplicate_labels for x in other.objs
+            )
+            self.flags.allows_duplicate_labels = allows_duplicate_labels
 
         return self
 

diff --git a/pandas/core/series.py b/pandas/core/series.py
@@ -216,14 +216,7 @@ class Series(base.IndexOpsMixin, generic.NDFrame):
     # Constructors
 
     def __init__(
-        self,
-        data=None,
-        index=None,
-        dtype=None,
-        name=None,
-        copy=False,
-        allows_duplicate_labels=True,
-        fastpath=False,
+        self, data=None, index=None, dtype=None, name=None, copy=False, fastpath=False,
     ):
 
         if (
@@ -234,7 +227,7 @@ def __init__(
         ):
             # GH#33357 called wit
10670
h just the SingleBlockManager
             NDFrame.__init__(
-                self, data, allows_duplicate_labels=allows_duplicate_labels
+                self, data,
             )
             self.name = name
             return
@@ -355,7 +348,7 @@ def __init__(
                 data = SingleBlockManager.from_array(data, index)
 
         generic.NDFrame.__init__(
-            self, data, allows_duplicate_labels=allows_duplicate_labels
+            self, data,
         )
         self.name = name
         self._set_axis(0, index, fastpath=True)

diff --git a/pandas/errors/__init__.py b/pandas/errors/__init__.py
@@ -210,7 +210,9 @@ class DuplicateLabelError(ValueError):
 
     Examples
     --------
-    >>> s = pd.Series([0, 1, 2], index=['a', 'b', 'c'], allows_duplicate_labels=False)
+    >>> s = pd.Series([0, 1, 2], index=['a', 'b', 'c']).set_flags(
+    ...     allows_duplicate_labels=False
+    ... )
     >>> s.reindex(['a', 'a', 'b'])
     Traceback (most recent call last):
        ...

diff --git a/pandas/tests/frame/test_api.py b/pandas/tests/frame/test_api.py
@@ -557,15 +557,26 @@ def test_set_flags(self, allows_duplicate_labels):
         result = df.set_flags(allows_duplicate_labels=allows_duplicate_labels)
         if allows_duplicate_labels is None:
             # We don't update when it's not provided
-            assert result.allows_duplicate_labels is True
+            assert result.flags.allows_duplicate_labels is True
         else:
-            assert result.allows_duplicate_labels is allows_duplicate_labels
+            assert result.flags.allows_duplicate_labels is allows_duplicate_labels
 
         # We made a copy
         assert df is not result
+
         # We didn't mutate df
-        assert df.allows_duplicate_labels is True
-        tm.assert_frame_equal(result, df)
+        assert df.flags.allows_duplicate_labels is True
+
+        # But we didn't copy data
+        result.iloc[0, 0] = 0
+        assert df.iloc[0, 0] == 0
+
+        # Now we do copy.
+        result = df.set_flags(
+            copy=True, allows_duplicate_labels=allows_duplicate_labels
+        )
+        result.iloc[0, 0] = 10
+        assert df.iloc[0, 0] == 0
 
     def test_cache_on_copy(self):
         # GH 31784 _item_cache not cleared on copy causes incorrect reads after updates