(chore): export read_elem and write_elem from the main package (#1598)

ilan-gold · flying-sheep · web-flow · commit dde809da186a · 2024-08-30T12:27:59.000Z
Co-authored-by: Philipp A. &lt;flying-sheep@web.de&gt;
diff --git a/benchmarks/benchmarks/sparse_dataset.py b/benchmarks/benchmarks/sparse_dataset.py
@@ -5,7 +5,8 @@
 from scipy import sparse
 
 from anndata import AnnData
-from anndata.experimental import sparse_dataset, write_elem
+from anndata._io.specs import write_elem
+from anndata.experimental import sparse_dataset
 
 
 def make_alternating_mask(n):
diff --git a/docs/api.md b/docs/api.md
@@ -52,6 +52,16 @@ Reading other file formats.
 
 ```
 
+Reading individual portions (`obs`, `varm` etc.) of the `AnnData` object.
+
+```{eval-rst}
+.. autosummary::
+   :toctree: generated/
+
+   read_elem
+
+```
+
 ## Writing
 
 Writing to anndata’s native file format `.h5ad`.
@@ -74,6 +84,16 @@ Writing to other formats.
    AnnData.write_zarr
 ```
 
+Writing individual portions (`obs`, `varm` etc.) of the `AnnData` object.
+
+```{eval-rst}
+.. autosummary::
+   :toctree: generated/
+
+   write_elem
+
+```
+
 (experimental-api)=
 
 ## Experimental API
@@ -100,8 +120,6 @@ Interface for accessing on-disk sparse data:
    :toctree: generated/
 
    experimental.sparse_dataset
-   experimental.CSRDataset
-   experimental.CSCDataset
 ```
 
 Out of core concatenation
@@ -119,8 +137,6 @@ Low level methods for reading and writing elements of an `AnnData` object to a s
 .. autosummary::
    :toctree: generated/
 
-   experimental.read_elem
-   experimental.write_elem
    experimental.read_elem_as_dask
 ```
 
@@ -141,8 +157,6 @@ Types used by the former:
    :toctree: generated/
 
    experimental.IOSpec
-   experimental.InMemoryElem
-   experimental.RWAble
    experimental.Read
    experimental.Write
    experimental.ReadCallback
@@ -168,3 +182,15 @@ Types used by the former:
    settings
    settings.override
 ```
+
+## Custom Types/Classes for Readable/Writeable Elements
+
+```{eval-rst}
+.. autosummary::
+   :toctree: generated/
+
+   CSRDataset
+   CSCDataset
+   RWAble
+   InMemoryElem
+```
diff --git a/docs/conf.py b/docs/conf.py
@@ -142,13 +142,13 @@ def setup(app: Sphinx):
     "anndata._types.WriteCallback": "anndata.experimental.WriteCallback",
     "anndata._types.Read": "anndata.experimental.Read",
     "anndata._types.Write": "anndata.experimental.Write",
-    "anndata._types.RWAble": "anndata.experimental.RWAble",
+    "anndata._types.RWAble": "anndata.RWAble",
 }
 autodoc_type_aliases = dict(
     NDArray=":data:`~numpy.typing.NDArray`",
-    RWAble=":data:`~anndata.experimental.RWAble`",
+    RWAble=":data:`~anndata.RWAble`",
     **{
-        f"{v}variantInMemoryType": ":data:`~anndata.experimental.InMemoryElem`"
+        f"{v}variantInMemoryType": ":data:`~anndata.InMemoryElem`"
         for v in ["In", "Co", "Contra"]
     },
 )
diff --git a/docs/fileformat-prose.md b/docs/fileformat-prose.md
@@ -476,7 +476,7 @@ That is, we store an indicator array (or mask) of null values alongside the arra
 :sync: hdf5
 
 ```python
->>> from anndata.experimental import write_elem
+>>> from anndata import write_elem
 >>> null_store = h5py.File("tmp.h5", mode="w")
 >>> int_array = pd.array([1, None, 3, 4])
 >>> int_array
@@ -498,7 +498,7 @@ nullable_integer/values <HDF5 dataset "values": shape (4,), type "<i8">
 :sync: zarr
 
 ```python
->>> from anndata.experimental import write_elem
+>>> from anndata import write_elem
 >>> null_store = zarr.open()
 >>> int_array = pd.array([1, None, 3, 4])
 >>> int_array
@@ -635,7 +635,7 @@ function:
 
 ```python
 >>> import awkward as ak
->>> from anndata.experimental import read_elem
+>>> from anndata import read_elem
 >>> awkward_group = store["varm/transcript"]
 >>> ak.from_buffers(
 ...     awkward_group.attrs["form"],
diff --git a/docs/release-notes/0.10.0.md b/docs/release-notes/0.10.0.md
@@ -13,7 +13,7 @@
 
 * Concatenate on-disk anndata objects with {func}`anndata.experimental.concat_on_disk` {pr}`955` {user}`selmanozleyen`
 * AnnData can now hold dask arrays with `scipy.sparse.spmatrix` chunks {pr}`1114` {user}`ivirshup`
-* Public API for interacting with on disk sparse arrays: {func}`~anndata.experimental.sparse_dataset`, {class}`~anndata.experimental.CSRDataset`, and {class}`~anndata.experimental.CSCDataset` {pr}`765` {user}`ilan-gold` {user}`ivirshup`
+* Public API for interacting with on disk sparse arrays: {func}`~anndata.experimental.sparse_dataset`, {class}`~anndata.CSRDataset`, and {class}`~anndata.CSCDataset` {pr}`765` {user}`ilan-gold` {user}`ivirshup`
 * Improved performance for simple slices of OOC sparse arrays {pr}`1131` {user}`ivirshup`
 
 **Improved errors and warnings**
diff --git a/docs/release-notes/0.10.2.md b/docs/release-notes/0.10.2.md
@@ -4,7 +4,7 @@
 #### Bug fixes
 
 * Added compatibility layer for packages relying on `anndata._core.sparse_dataset.SparseDataset`.
-  Note that this API is *deprecated* and new code should use {class}`~anndata.experimental.CSRDataset`, {class}`~anndata.experimental.CSCDataset`, and {func}`~anndata.experimental.sparse_dataset` instead.
+  Note that this API is *deprecated* and new code should use {class}`~anndata.CSRDataset`, {class}`~anndata.CSCDataset`, and {func}`~anndata.experimental.sparse_dataset` instead.
   {pr}`1185` {user}`ivirshup`
 * Handle deprecation warning from `pd.Categorical.map` thrown during `anndata.concat` {pr}`1189` {user}`flying-sheep` {user}`ivirshup`
 * Fixed extra steps being included in IO tracebacks {pr}`1193` {user}`flying-sheep`
diff --git a/docs/release-notes/0.8.0.md b/docs/release-notes/0.8.0.md
@@ -15,7 +15,7 @@ This should make it much easier to support new datatypes, use partial access, an
 
 - Each element should be tagged with an `encoding_type` and `encoding_version`. See updated docs on the {doc}`file format </fileformat-prose>`
 - Support for nullable integer and boolean data arrays. More data types to come!
-- Experimental support for low level access to the IO API via {func}`~anndata.experimental.read_elem` and {func}`~anndata.experimental.write_elem`
+- Experimental support for low level access to the IO API via {func}`~anndata.read_elem` and {func}`~anndata.write_elem`
 
 #### Features
 
diff --git a/docs/release-notes/1598.feature.md b/docs/release-notes/1598.feature.md
@@ -0,0 +1 @@
+Export {func}`~anndata.write_elem` and {func}`~anndata.read_elem` directly from the main package instead of `experimental` {user}`ilan-gold`
diff --git a/docs/release-notes/1616.doc.md b/docs/release-notes/1616.doc.md
@@ -1 +1 @@
-Correct {attr}`anndata.AnnData.X` type to include {class}`~anndata.experimental.CSRDataset` and {class}`~anndata.experimental.CSCDataset` as possible types {user}`ilan-gold`
+Correct {attr}`anndata.AnnData.X` type to include {class}`~anndata.CSRDataset` and {class}`~anndata.CSCDataset` as possible types and being deprecation process for non-csr/csc {class}`scipy.sparse.spmatrix` types in {attr}`anndata.AnnData.X` {user}`ilan-gold`
diff --git a/src/anndata/__init__.py b/src/anndata/__init__.py
@@ -24,6 +24,7 @@
 from ._core.anndata import AnnData
 from ._core.merge import concat
 from ._core.raw import Raw
+from ._core.sparse_dataset import CSCDataset, CSRDataset
 from ._io import (
     read_csv,
     read_excel,
@@ -35,19 +36,27 @@
     read_umi_tools,
     read_zarr,
 )
+from ._io.specs import read_elem, write_elem
 from ._settings import settings
+from ._types import InMemoryElem
+from ._types import RWAble as _RWAble
 from ._warnings import (
     ExperimentalFeatureWarning,
     ImplicitModificationWarning,
     OldFormatWarning,
     WriteWarning,
 )
 
+# Sphinx can’t find data docstrings when objects are re-exported
+RWAble = _RWAble
+"""A serializable object, excluding :class:`anndata.AnnData` objects i.e., something that can be stored in `uns` or `obsm`."""
+
+
 # Experimental needs to be imported last
-from . import experimental  # isort: skip
+from . import experimental  # noqa: E402 isort: skip
 
 # We use these in tests by attribute access
-from . import _io, logging  # noqa: F401 isort: skip
+from . import _io, logging  # noqa: F401, E402 isort: skip
 
 
 def read(*args, **kwargs):
@@ -75,6 +84,12 @@ def read(*args, **kwargs):
     "read_text",
     "read_mtx",
     "read_zarr",
+    "read_elem",
+    "write_elem",
+    "InMemoryElem",
+    "RWAble",
+    "CSRDataset",
+    "CSCDataset",
     "OldFormatWarning",
     "WriteWarning",
     "ImplicitModificationWarning",
diff --git a/src/anndata/_core/sparse_dataset.py b/src/anndata/_core/sparse_dataset.py
@@ -620,7 +620,8 @@ def sparse_dataset(group: GroupStorageType) -> CSRDataset | CSCDataset:
 
     >>> import scanpy as sc
     >>> import h5py
-    >>> from anndata.experimental import sparse_dataset, read_elem
+    >>> from anndata.experimental import sparse_dataset
+    >>> from anndata import read_elem
     >>> sc.datasets.pbmc68k_reduced().raw.to_adata().write_h5ad("pbmc.h5ad")
 
     Initialize a sparse dataset from storage
@@ -668,7 +669,7 @@ def subset_sparsedataset(d, subset_idx):
 _sparsedataset_depr_msg = """\
 SparseDataset is deprecated and will be removed in late 2024. It has been replaced by the public classes CSRDataset and CSCDataset.
 
-For instance checks, use `isinstance(X, (anndata.experimental.CSRDataset, anndata.experimental.CSCDataset))` instead.
+For instance checks, use `isinstance(X, (anndata.CSRDataset, anndata.CSCDataset))` instead.
 
 For creation, use `anndata.experimental.sparse_dataset(X)` instead.
 """
diff --git a/src/anndata/_types.py b/src/anndata/_types.py
@@ -161,7 +161,7 @@ def __call__(
         Params
         ------
         read_func
-            :func:`anndata.experimental.read_elem` function to call to read the current element given the ``iospec``.
+            :func:`anndata.read_elem` function to call to read the current element given the ``iospec``.
         elem_name
             The key to read in from the group.
         elem
@@ -194,7 +194,7 @@ def __call__(
         Params
         ------
         write_func
-            :func:`anndata.experimental.write_elem` function to call to read the current element given the ``iospec``.
+            :func:`anndata.write_elem` function to call to read the current element given the ``iospec``.
         store
             The store to which `elem` should be written.
         elem_name
diff --git a/src/anndata/experimental/__init__.py b/src/anndata/experimental/__init__.py
@@ -1,38 +1,44 @@
 from __future__ import annotations
 
-from anndata._core.sparse_dataset import CSCDataset, CSRDataset, sparse_dataset
-from anndata._io.specs import IOSpec, read_elem, read_elem_as_dask, write_elem
+import warnings
+from typing import TYPE_CHECKING
 
-from .._types import InMemoryElem as _InMemoryElem
+import anndata
+
+from .._core.sparse_dataset import sparse_dataset
+from .._io.specs import IOSpec, read_elem_as_dask
 from .._types import Read, ReadCallback, StorageType, Write, WriteCallback
-from .._types import RWAble as _RWAble
 from ._dispatch_io import read_dispatched, write_dispatched
 from .merge import concat_on_disk
 from .multi_files import AnnCollection
 from .pytorch import AnnLoader
 
-# Sphinx can’t find data docstrings when objects are re-exported
-InMemoryElem = _InMemoryElem
-"""An in-memory element that can be read and written, including an :class:`anndata.AnnData` objects."""
-RWAble = _RWAble
-"""A serializable object, excluding :class:`anndata.AnnData` objects i.e., something that can be stored in `uns` or `obsm`."""
+if TYPE_CHECKING:
+    from typing import Any
+
+
+_DEPRECATED = ["CSRDataset", "CSCDataset", "read_elem", "write_elem"]
+
+
+def __getattr__(key: str) -> Any:
+    if key in _DEPRECATED:
+        msg = f"Importing {key} from `anndata.experimental` is deprecated. Import from `anndata` directly."
+        warnings.warn(msg, FutureWarning)
+        return getattr(anndata, key)
+    msg = f"module {__name__!r} has no attribute {key!r}"
+    raise AttributeError(msg)
+
 
 __all__ = [
     "AnnCollection",
     "AnnLoader",
-    "read_elem",
-    "write_elem",
     "read_elem_as_dask",
     "read_dispatched",
     "write_dispatched",
     "IOSpec",
     "concat_on_disk",
     "sparse_dataset",
-    "CSRDataset",
-    "CSCDataset",
-    "InMemoryElem",
     "Read",
-    "RWAble",
     "Write",
     "ReadCallback",
     "WriteCallback",
diff --git a/tests/test_backed_sparse.py b/tests/test_backed_sparse.py
diff --git a/tests/test_concatenate_disk.py b/tests/test_concatenate_disk.py
diff --git a/tests/test_dask.py b/tests/test_dask.py
diff --git a/tests/test_deprecations.py b/tests/test_deprecations.py
diff --git a/tests/test_io_dispatched.py b/tests/test_io_dispatched.py
diff --git a/tests/test_io_utils.py b/tests/test_io_utils.py

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+Export {func}`~anndata.write_elem` and {func}`~anndata.read_elem` directly from the main package instead of `experimental` {user}`ilan-gold`
Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		-Correct {attr}`anndata.AnnData.X` type to include {class}`~anndata.experimental.CSRDataset` and {class}`~anndata.experimental.CSCDataset` as possible types {user}`ilan-gold`
	`1`	+Correct {attr}`anndata.AnnData.X` type to include {class}`~anndata.CSRDataset` and {class}`~anndata.CSCDataset` as possible types and being deprecation process for non-csr/csc {class}`scipy.sparse.spmatrix` types in {attr}`anndata.AnnData.X` {user}`ilan-gold`