flags

pandas-dev · jreback · Sep 3, 2020 · Jun 7, 2020 · Jun 8, 2020 · Jun 8, 2020
commit 4f7c350d9bda6b36ee476a4771f86e855a28d091
diff --git a/doc/source/reference/frame.rst b/doc/source/reference/frame.rst
@@ -37,7 +37,6 @@ Attributes and underlying data
    DataFrame.shape
    DataFrame.memory_usage
    DataFrame.empty
-   DataFrame.allows_duplicate_labels
    DataFrame.set_flags
 
 Conversion
@@ -278,6 +277,21 @@ Time Series-related
    DataFrame.tz_convert
    DataFrame.tz_localize
 
+.. _api.frame.flags:
+
+Flags
+~~~~~
+
+Flags refer to attributes of the pandas object. Properties of the dataset (like
+the date is was recorded, the URL it was accessed from, etc.) should be stored
+in :attr:`DataFrame.attrs`.
+
+.. autosummary::
+   :toctree: api/
+
+   Flags
+
+
 .. _api.frame.metadata:
 
 Metadata

diff --git a/doc/source/reference/series.rst b/doc/source/reference/series.rst
@@ -39,7 +39,7 @@ Attributes
    Series.empty
    Series.dtypes
    Series.name
-   Series.allows_duplicate_labels
+   Series.flags
    Series.set_flags
 
 Conversion
@@ -529,6 +529,19 @@ Sparse-dtype specific methods and attributes are provided under the
    Series.sparse.from_coo
    Series.sparse.to_coo
 
+.. _api.series.flags:
+
+Flags
+~~~~~
+
+Flags refer to attributes of the pandas object. Properties of the dataset (like
+the date is was recorded, the URL it was accessed from, etc.) should be stored
+in :attr:`Series.attrs`.
+
+.. autosummary::
+   :toctree: api/
+
+   Flags
 
 .. _api.series.metadata:
 

diff --git a/doc/source/user_guide/duplicates.rst b/doc/source/user_guide/duplicates.rst
@@ -121,42 +121,46 @@ an exception will be raised.
 .. ipython:: python
    :okexcept:
 
-   pd.Series([0, 1, 2], index=['a', 'b', 'b'], allows_duplicate_labels=False)
+   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:
 
-   pd.DataFrame([[0, 1, 2], [3, 4, 5]], columns=["A", "B", "C"],
-                allows_duplicate_labels=False)
+   pd.DataFrame(
+      [[0, 1, 2], [3, 4, 5]], columns=["A", "B", "C"],
+   ).set_flags(allows_duplicate_labels=False)
 
-This attribute can be checked or set with :attr:`~DataFrame.allows_duplicate_labels`,
+This attribute can be checked or set with :attr:`~DataFrame.flags.allows_duplicate_labels`,
 which indicates whether that object can have duplicate labels.
 
 .. ipython:: python
 
-   df = pd.DataFrame({"A": [0, 1, 2, 3]},
-                     index=['x', 'y', 'X', 'Y'],
-                     allows_duplicate_labels=False)
+   df = (
+      pd.DataFrame({"A": [0, 1, 2, 3]},
+                   index=['x', 'y', 'X', 'Y'])
+      .set_flags(allows_duplicate_labels=False)
+   )
    df
-   df.allows_duplicate_labels
+   df.flags.allows_duplicate_labels
 
 :meth:`DataFrame.set_flags` can be used to return a new ``DataFrame`` with attributes
 like ``allows_duplicate_labels`` set to some value
 
 .. ipython:: python
 
    df2 = df.set_flags(allows_duplicate_labels=True)
-   df2.allows_duplicate_labels
+   df2.flags.allows_duplicate_labels
 
+The new ``DataFrame`` returned is a view on the same data as the old ``DataFrame``.
 Or the property can just be set directly on the same object
 
 
 .. ipython:: python
 
-   df2.allows_duplicate_labels = False
-   df2.allows_duplicate_labels
+   df2.flags.allows_duplicate_labels = False
+   df2.flags.allows_duplicate_labels
 
 When processing raw, messy data you might initially read in the messy data
 (which potentially has duplicate labels), deduplicate, and then disallow duplicates
@@ -167,7 +171,7 @@ going forward, to ensure that your data pipeline doesn't introduce duplicates.
 
    >>> raw = pd.read_csv("...")
    >>> deduplicated = raw.groupby(level=0).first()  # remove duplicates
-   >>> deduplicated.allows_duplicate_labels = False  # disallow going forward
+   >>> deduplicated.flags.allows_duplicate_labels = False  # disallow going forward
 
 Setting ``allows_duplicate_labels=True`` on a ``Series`` or ``DataFrame`` with duplicate
 labels or performing an operation that introduces duplicate labels on a ``Series`` or
@@ -191,7 +195,7 @@ operations.
 .. ipython:: python
    :okexcept:
 
-   s1 = pd.Series(0, index=['a', 'b'], allows_duplicate_labels=False)
+   s1 = pd.Series(0, index=['a', 'b']).set_flags(allows_duplicate_labels=False)
    s1
    s1.head().rename({"a": "b"})
 

diff --git a/doc/source/whatsnew/v1.2.0.rst b/doc/source/whatsnew/v1.2.0.rst
@@ -31,14 +31,14 @@ By default, duplicates continue to be allowed
 .. ipython:: python
    :okexcept:
 
-   pd.Series([1, 2], index=['a', 'a'], allows_duplicate_labels=False)
+   pd.Series([1, 2], index=['a', 'a']).set_flags(allows_duplicate_labels=False)
 
 Pandas will propagate the ``allows_duplicate_labels`` property through many operations.
 
 .. ipython:: python
    :okexcept:
 
-   a = pd.Series([1, 2], index=['a', 'b'], allows_duplicate_labels=False)
+   a = pd.Series([1, 2], index=['a', 'b']).set_flags(allows_duplicate_labels=False)
    a
    # An operation introducing duplicates
    a.reindex(['a', 'b', 'a'])
@@ -52,6 +52,11 @@ Pandas will propagate the ``allows_duplicate_labels`` property through many oper
 
 See :ref:`duplicates` for more.
 
+The ``allows_duplicate_labels`` flag is stored in the new :attr:`DataFrame.flags`
+attribute. This stores global attributes that apply to the *pandas object*. This
+differs from :attr:`DataFrame.attrs`, which stores information that applies to
+the dataset.
+
 Passing arguments to fsspec backends
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

diff --git a/pandas/__init__.py b/pandas/__init__.py
@@ -100,6 +100,7 @@
     to_datetime,
     to_timedelta,
     # misc
+    Flags,
     Grouper,
     factorize,
     unique,

diff --git a/pandas/core/_flags.py b/pandas/core/_flags.py
@@ -5,12 +5,26 @@ class Flags:
     """
     Flags that apply to pandas objects.
 
+    .. versionadded:: 1.2.0
+
     Parameters
     ----------
     obj : Series or DataFrame
         The object these flags are associated with
-    allows_duplicate_labels : bool
-        Whether the object allows duplicate labels
+    allows_duplicate_labels : bool, default True
+        Whether to allow duplicate labels in this object. By default,
+        duplicate labels are permitted. Setting this to ``False`` will
+        cause an :class:`errors.DuplicateLabelError` to be raised when
+        `index` (or columns for DataFrame) is not unique, or any
+        subsequent operation on introduces duplicates.
+        See :ref:`duplicates.disallow` for more.
+
+        .. warning::
+
+           This is an experimental feature. Currently, many methods fail to
+           propagate the ``allows_duplicate_labels`` value. In future versions
+           it is expected that every method taking or returning one or more
+           DataFrame or Series objects will propagate ``allows_duplicate_labels``.
 
     Notes
     -----

diff --git a/pandas/core/api.py b/pandas/core/api.py
@@ -26,6 +26,7 @@
 )
 from pandas.core.arrays.string_ import StringDtype
 from pandas.core.construction import array
+from pandas.core.flags import Flags
 from pandas.core.groupby import Grouper, NamedAgg
 from pandas.core.indexes.api import (
     CategoricalIndex,

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
@@ -369,22 +369,6 @@ class DataFrame(NDFrame):
         Data type to force. Only a single dtype is allowed. If None, infer.
     copy : bool, default False
         Copy data from inputs. Only affects DataFrame / 2d ndarray input.
-    allows_duplicate_labels : bool, default True
-        Whether to allow duplicate row or column labels in this DataFrame.
-        By default, duplicate labels are permitted. Setting this to ``False``
-        will cause an :class:`errors.DuplicateLabelError` to be raised when
-        `index` or `columns` are not unique, or when any subsequent operation
-        on this DataFrame introduces duplicates. See :ref:`duplicates.disallow`
-        for more.
-
-        .. versionadded:: 1.1.0
-
-        .. warning::
-
-           This is an experimental feature. Currently, many methods fail to
-           propagate the ``allows_duplicate_labels`` value. In future versions
-           it is expected that every method taking or returning one or more
-           DataFrame or Series objects will propagate ``allows_duplicate_labels``.
 
     See Also
     --------