chore: deprecate AnnData.*_keys methods

docs/release-notes/2102.chore.md

@@ -0,0 +1 @@
+Deprecate `AnnData.*_keys()` methods. {user}`flying-sheep`

src/anndata/_core/anndata.py

@@ -936,22 +936,27 @@ def uns(self):
     Is sliced with `data` and `var` but behaves otherwise like a :term:`mapping`.
     """
 
+    @deprecated("obs (e.g. `k in adata.obs` or `str(adata.obs.columns.tolist())`)")
     def obs_keys(self) -> list[str]:
         """List keys of observation annotation :attr:`obs`."""
         return self._obs.keys().tolist()
 
+    @deprecated("var (e.g. `k in adata.var` or `str(adata.var.columns.tolist())`)")
     def var_keys(self) -> list[str]:
         """List keys of variable annotation :attr:`var`."""
         return self._var.keys().tolist()
 
+    @deprecated("obsm (e.g. `k in adata.obsm` or `adata.obsm.keys() | {'u'}`)")
     def obsm_keys(self) -> list[str]:
         """List keys of observation annotation :attr:`obsm`."""
         return list(self.obsm.keys())
 
+    @deprecated("varm (e.g. `k in adata.varm` or `adata.varm.keys() | {'u'}`)")
     def varm_keys(self) -> list[str]:
         """List keys of variable annotation :attr:`varm`."""
         return list(self.varm.keys())
 
+    @deprecated("uns (e.g. `k in adata.uns` or `sorted(adata.uns)`)")
     def uns_keys(self) -> list[str]:
         """List keys of unstructured annotation."""
         return sorted(self._uns.keys())

tests/test_base.py

@@ -515,10 +515,10 @@ def test_append_col():
 
 def test_delete_col():
     adata = AnnData(np.array([[1, 2, 3], [4, 5, 6]]), dict(o1=[1, 2], o2=[3, 4]))
-    assert adata.obs_keys() == ["o1", "o2"]
+    assert adata.obs.columns.tolist() == ["o1", "o2"]
 
     del adata.obs["o1"]
-    assert adata.obs_keys() == ["o2"]
+    assert adata.obs.columns.tolist() == ["o2"]
     assert adata.obs["o2"].tolist() == [3, 4]
 
 
@@ -536,7 +536,7 @@ def test_multicol():
     adata = AnnData(np.array([[1, 2, 3], [4, 5, 6]]))
     # 'c' keeps the columns as should be
     adata.obsm["c"] = np.array([[0.0, 1.0], [2, 3]])
-    assert adata.obsm_keys() == ["c"]
+    assert adata.obsm.keys() == {"c"}
     assert adata.obsm["c"].tolist() == [[0.0, 1.0], [2, 3]]
 
 

tests/test_concatenate.py

@@ -315,15 +315,15 @@ def test_concatenate_dense():
     X_combined = [[2, 3], [5, 6], [3, 2], [6, 5], [3, 2], [6, 5]]
     assert adata.X.astype(int).tolist() == X_combined
     assert adata.layers["Xs"].astype(int).tolist() == X_combined
-    assert adata.obs_keys() == ["anno1", "anno2", "batch"]
-    assert adata.var_keys() == ["annoA-0", "annoA-1", "annoB-2"]
+    assert adata.obs.columns.tolist() == ["anno1", "anno2", "batch"]
+    assert adata.var.columns.tolist() == ["annoA-0", "annoA-1", "annoB-2"]
     assert adata.var.values.tolist() == [[1, 2, 2], [2, 1, 1]]
-    assert adata.obsm_keys() == ["X_1", "X_2"]
+    assert adata.obsm.keys() == {"X_1", "X_2"}
     assert adata.obsm["X_1"].tolist() == np.concatenate([X1, X1, X1]).tolist()
 
     # with batch_key and batch_categories
     adata = adata1.concatenate(adata2, adata3, batch_key="batch1")
-    assert adata.obs_keys() == ["anno1", "anno2", "batch1"]
+    assert adata.obs.columns.tolist() == ["anno1", "anno2", "batch1"]
     adata = adata1.concatenate(adata2, adata3, batch_categories=["a1", "a2", "a3"])
     assert adata.obs["batch"].cat.categories.tolist() == ["a1", "a2", "a3"]
     assert adata.var_names.tolist() == ["b", "c"]
@@ -644,7 +644,7 @@ def test_concatenate_dense_duplicates():
     )
 
     adata = adata1.concatenate(adata2, adata3)
-    assert adata.var_keys() == [
+    assert adata.var.columns.tolist() == [
         "annoA",
         "annoB",
         "annoC-0",

tests/test_deprecations.py

@@ -134,3 +134,9 @@ def test_warn_on_deprecated__io_module():
         FutureWarning, match=r"Importing read_h5ad from `anndata._io` is deprecated"
     ):
         from anndata._io import read_h5ad  # noqa
+
+
+@pytest.mark.parametrize("name", ["obs", "var", "obsm", "varm", "uns"])
+def test_keys_function_warns(adata: AnnData, name) -> None:
+    with pytest.warns(FutureWarning, match=rf"{name}_keys is deprecated"):
+        getattr(adata, f"{name}_keys")()

tests/test_readwrite.py

@@ -494,18 +494,18 @@ def test_readwrite_loom(typ, obsm_mapping, varm_mapping, tmp_path):
     else:
         # TODO: this should not be necessary
         assert np.allclose(adata.X.toarray(), X.toarray())
-    assert "X_a" in adata.obsm_keys()
+    assert "X_a" in adata.obsm
     assert adata.obsm["X_a"].shape[1] == 2
-    assert "X_b" in adata.varm_keys()
+    assert "X_b" in adata.varm
     assert adata.varm["X_b"].shape[1] == 3
     # as we called with `cleanup=True`
     assert "oanno1b" in adata.uns["loom-obs"]
     assert "vanno2" in adata.uns["loom-var"]
     for k, v in obsm_mapping.items():
-        assert k in adata.obsm_keys()
+        assert k in adata.obsm
         assert adata.obsm[k].shape[1] == len(v)
     for k, v in varm_mapping.items():
-        assert k in adata.varm_keys()
+        assert k in adata.varm
         assert adata.varm[k].shape[1] == len(v)
     assert adata.obs_names.name == obs_dim
     assert adata.var_names.name == var_dim