API: Store name outside attrs (#30798)

* API: Store name outside attrs

This aligns with xarray and h5py:
#29062 (comment)

Author: TomAugspurger

doc/source/reference/frame.rst

@@ -273,6 +273,8 @@ Metadata
 
 :attr:`DataFrame.attrs` is a dictionary for storing global metadata for this DataFrame.
 
+.. warning:: ``DataFrame.attrs`` is considered experimental and may change without warning.
+
 .. autosummary::
    :toctree: api/
 

doc/source/reference/series.rst

@@ -525,6 +525,8 @@ Metadata
 
 :attr:`Series.attrs` is a dictionary for storing global metadata for this Series.
 
+.. warning:: ``Series.attrs`` is considered experimental and may change without warning.
+
 .. autosummary::
    :toctree: api/
 

doc/source/whatsnew/v1.0.0.rst

@@ -218,6 +218,7 @@ Other enhancements
 - Added new writer for exporting Stata dta files in version 118, ``StataWriter118``.  This format supports exporting strings containing Unicode characters (:issue:`23573`)
 - :meth:`Series.map` now accepts ``collections.abc.Mapping`` subclasses as a mapper (:issue:`29733`)
 - The ``pandas.datetime`` class is now deprecated. Import from ``datetime`` instead (:issue:`30296`)
+- Added an experimental :attr:`~DataFrame.attrs` for storing global metadata about a dataset (:issue:`29062`)
 - :meth:`Timestamp.fromisocalendar` is now compatible with python 3.8 and above (:issue:`28115`)
 
 

pandas/core/generic.py

@@ -231,6 +231,10 @@ def _init_mgr(self, mgr, axes=None, dtype=None, copy=False):
     def attrs(self) -> Dict[Optional[Hashable], Any]:
         """
         Dictionary of global attributes on this object.
+
+        .. warning::
+
+           attrs is experimental and may change without warning.
         """
         if self._attrs is None:
             self._attrs = {}

pandas/core/series.py

@@ -159,7 +159,8 @@ class Series(base.IndexOpsMixin, generic.NDFrame):
 
     _typ = "series"
 
-    _metadata: List[str] = []
+    _name: Optional[Hashable]
+    _metadata: List[str] = ["name"]
     _accessors = {"dt", "cat", "str", "sparse"}
     _deprecations = (
         base.IndexOpsMixin._deprecations
@@ -425,13 +426,13 @@ def dtypes(self):
 
     @property
     def name(self) -> Optional[Hashable]:
-        return self.attrs.get("name", None)
+        return self._name
 
     @name.setter
     def name(self, value: Optional[Hashable]) -> None:
         if not is_hashable(value):
             raise TypeError("Series.name must be a hashable type")
-        self.attrs["name"] = value
+        object.__setattr__(self, "_name", value)
 
     @property
     def values(self):

pandas/tests/frame/test_api.py

@@ -551,3 +551,11 @@ async def test_tab_complete_warning(self, ip):
         with tm.assert_produces_warning(None):
             with provisionalcompleter("ignore"):
                 list(ip.Completer.completions("df.", 1))
+
+    def test_attrs(self):
+        df = pd.DataFrame({"A": [2, 3]})
+        assert df.attrs == {}
+        df.attrs["version"] = 1
+
+        result = df.rename(columns=str)
+        assert result.attrs == {"version": 1}

pandas/tests/series/test_api.py

@@ -512,6 +512,13 @@ def test_integer_series_size(self):
         s = Series(range(9), dtype="Int64")
         assert s.size == 9
 
+    def test_attrs(self):
+        s = pd.Series([0, 1], name="abc")
+        assert s.attrs == {}
+        s.attrs["version"] = 1
+        result = s + 1
+        assert result.attrs == {"version": 1}
+
 
 class TestCategoricalSeries:
     @pytest.mark.parametrize(