lamindb 0.69.7__py3-none-any.whl → 0.69.9__py3-none-any.whl

lamindb/__init__.py

@@ -40,7 +40,7 @@ Modules & settings:
 
 """
 
-__version__ = "0.69.7"  # denote a release candidate for 0.1.0 with 0.1rc1
+__version__ = "0.69.9"  # denote a release candidate for 0.1.0 with 0.1rc1
 
 import os as _os
 

lamindb/_annotate.py

@@ -1,11 +1,15 @@
-from typing import Dict, Iterable, List, Optional, Tuple, Union
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Iterable
 
 import anndata as ad
 import lamindb_setup as ln_setup
 import pandas as pd
 from lamin_utils import colors, logger
 from lnschema_core import Artifact, Collection, Feature, Registry, Run, ULabel
-from lnschema_core.types import FieldAttr
+
+if TYPE_CHECKING:
+    from lnschema_core.types import FieldAttr
 
 
 class ValidationError(ValueError):
@@ -19,9 +23,9 @@ class AnnotateLookup:
 
     def __init__(
         self,
-        categorials: Dict[str, FieldAttr],
-        slots: Dict[str, FieldAttr] = None,
-        using: Optional[str] = None,
+        categorials: dict[str, FieldAttr],
+        slots: dict[str, FieldAttr] = None,
+        using: str | None = None,
     ) -> None:
         if slots is None:
             slots = {}
@@ -91,8 +95,8 @@ class DataFrameAnnotator:
         self,
         df: pd.DataFrame,
         columns: FieldAttr = Feature.name,
-        categoricals: Optional[Dict[str, FieldAttr]] = None,
-        using: Optional[str] = None,
+        categoricals: dict[str, FieldAttr] | None = None,
+        using: str | None = None,
         verbosity: str = "hint",
         **kwargs,
     ) -> None:
@@ -106,15 +110,15 @@ class DataFrameAnnotator:
         self._artifact = None
         self._collection = None
         self._validated = False
-        self._kwargs: Dict = kwargs
+        self._kwargs: dict = kwargs
         self._save_columns()
 
     @property
-    def fields(self) -> Dict:
+    def fields(self) -> dict:
         """Return the columns fields to validate against."""
         return self._fields
 
-    def lookup(self, using: Optional[str] = None) -> AnnotateLookup:
+    def lookup(self, using: str | None = None) -> AnnotateLookup:
         """Lookup features and labels.
 
         Args:
@@ -260,11 +264,11 @@ class DataFrameAnnotator:
 
     def save_collection(
         self,
-        artifact: Union[Artifact, Iterable[Artifact]],
+        artifact: Artifact | Iterable[Artifact],
         name: str,
-        description: Optional[str] = None,
-        reference: Optional[str] = None,
-        reference_type: Optional[str] = None,
+        description: str | None = None,
+        reference: str | None = None,
+        reference_type: str | None = None,
     ) -> Collection:
         """Save a collection from artifact/artifacts.
 
@@ -319,7 +323,7 @@ class AnnDataAnnotator(DataFrameAnnotator):
         self,
         adata: ad.AnnData,
         var_index: FieldAttr,
-        categoricals: Dict[str, FieldAttr],
+        categoricals: dict[str, FieldAttr],
         using: str = "default",
         verbosity: str = "hint",
         **kwargs,
@@ -342,11 +346,11 @@ class AnnDataAnnotator(DataFrameAnnotator):
         return self._var_field
 
     @property
-    def categoricals(self) -> Dict:
+    def categoricals(self) -> dict:
         """Return the obs fields to validate against."""
         return self._obs_fields
 
-    def lookup(self, using: Optional[str] = None) -> AnnotateLookup:
+    def lookup(self, using: str | None = None) -> AnnotateLookup:
         """Lookup features and labels."""
         return AnnotateLookup(
             categorials=self._obs_fields,
@@ -413,9 +417,9 @@ class Annotate:
     def from_df(
         cls,
         df: pd.DataFrame,
-        categoricals: Optional[Dict[str, FieldAttr]] = None,
+        categoricals: dict[str, FieldAttr] | None = None,
         columns: FieldAttr = Feature.name,
-        using: Optional[str] = None,
+        using: str | None = None,
         verbosity: str = "hint",
         **kwargs,
     ) -> DataFrameAnnotator:
@@ -433,7 +437,7 @@ class Annotate:
         cls,
         adata: ad.AnnData,
         var_index: FieldAttr,
-        categoricals: Dict[str, FieldAttr],
+        categoricals: dict[str, FieldAttr],
         using: str = "default",
         verbosity: str = "hint",
         **kwargs,
@@ -448,7 +452,7 @@ class Annotate:
         )
 
 
-def get_registry_instance(registry: Registry, using: Optional[str] = None) -> Registry:
+def get_registry_instance(registry: Registry, using: str | None = None) -> Registry:
     """Get a registry instance using a specific instance."""
     if using is not None and using != "default":
         return registry.using(using)
@@ -465,8 +469,8 @@ def standardize_and_inspect(
 
 
 def check_registry_organism(
-    registry: Registry, organism: Optional[str] = None
-) -> Optional[str]:
+    registry: Registry, organism: str | None = None
+) -> str | None:
     """Check if a registry needs an organism and return the organism name."""
     if hasattr(registry, "organism_id"):
         import bionty as bt
@@ -484,7 +488,7 @@ def validate_categories(
     values: Iterable[str],
     field: FieldAttr,
     key: str,
-    using: Optional[str] = None,
+    using: str | None = None,
     **kwargs,
 ) -> bool:
     """Validate ontology terms in a pandas series using LaminDB registries."""
@@ -560,8 +564,8 @@ def validate_categories(
 
 def validate_categories_in_df(
     df: pd.DataFrame,
-    fields: Dict[str, FieldAttr],
-    using: Optional[str] = None,
+    fields: dict[str, FieldAttr],
+    using: str | None = None,
     **kwargs,
 ) -> bool:
     """Validate categories in DataFrame columns using LaminDB registries."""
@@ -580,8 +584,8 @@ def validate_categories_in_df(
 def validate_anndata(
     adata: ad.AnnData,
     var_field: FieldAttr,
-    obs_fields: Dict[str, FieldAttr],
-    using: Optional[str] = None,
+    obs_fields: dict[str, FieldAttr],
+    using: str | None = None,
     **kwargs,
 ) -> bool:
     """Inspect metadata in an AnnData object using LaminDB registries."""
@@ -604,9 +608,9 @@ def validate_anndata(
 
 
 def save_artifact(
-    data: Union[pd.DataFrame, ad.AnnData],
+    data: pd.DataFrame | ad.AnnData,
     description: str,
-    fields: Dict[str, FieldAttr],
+    fields: dict[str, FieldAttr],
     columns_field: FieldAttr,
     **kwargs,
 ) -> Artifact:
@@ -631,7 +635,7 @@ def save_artifact(
         raise ValueError("data must be a DataFrame or AnnData object")
     artifact.save()
 
-    feature_kwargs: Dict = {}
+    feature_kwargs: dict = {}
     organism = check_registry_organism(
         columns_field.field.model, kwargs.pop("organism", None)
     )
@@ -662,14 +666,14 @@ def save_artifact(
 
 
 def update_registry(
-    values: List[str],
+    values: list[str],
     field: FieldAttr,
     key: str,
     save_function: str = "add_new_from",
-    using: Optional[str] = None,
+    using: str | None = None,
     validated_only: bool = True,
-    kwargs: Optional[Dict] = None,
-    df: Optional[pd.DataFrame] = None,
+    kwargs: dict | None = None,
+    df: pd.DataFrame | None = None,
 ) -> None:
     """Save features or labels records in the default instance from the using instance.
 
@@ -703,7 +707,7 @@ def update_registry(
             settings.verbosity = verbosity
             return
 
-        labels_saved: Dict = {"from public": [], "without reference": []}
+        labels_saved: dict = {"from public": [], "without reference": []}
 
         (
             labels_saved[f"from {using}"],
@@ -757,7 +761,7 @@ def update_registry(
 
 
 def log_saved_labels(
-    labels_saved: Dict,
+    labels_saved: dict,
     key: str,
     save_function: str,
     model_field: str,
@@ -795,7 +799,7 @@ def log_saved_labels(
             )
 
 
-def save_ulabels_with_parent(values: List[str], field: FieldAttr, key: str) -> None:
+def save_ulabels_with_parent(values: list[str], field: FieldAttr, key: str) -> None:
     """Save a parent label for the given labels."""
     registry = field.field.model
     assert registry == ULabel
@@ -808,11 +812,11 @@ def save_ulabels_with_parent(values: List[str], field: FieldAttr, key: str) -> N
 
 
 def update_registry_from_using_instance(
-    values: List[str],
+    values: list[str],
     field: FieldAttr,
-    using: Optional[str] = None,
-    kwargs: Optional[Dict] = None,
-) -> Tuple[List[str], List[str]]:
+    using: str | None = None,
+    kwargs: dict | None = None,
+) -> tuple[list[str], list[str]]:
     """Save features or labels records from the using instance.
 
     Args:

lamindb/_artifact.py

@@ -1,5 +1,7 @@
+from __future__ import annotations
+
 from pathlib import Path, PurePath, PurePosixPath
-from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple, Union
+from typing import TYPE_CHECKING, Any
 
 import fsspec
 import lamindb_setup as ln_setup
@@ -11,7 +13,6 @@ from lamindb_setup._init_instance import register_storage
 from lamindb_setup.core import StorageSettings
 from lamindb_setup.core._docs import doc_args
 from lamindb_setup.core.hashing import b16_to_b64, hash_file, hash_md5s_from_dir
-from lamindb_setup.core.types import UPathStr
 from lamindb_setup.core.upath import (
     create_path,
     extract_suffix_from_path,
@@ -21,7 +22,6 @@ from lamindb_setup.core.upath import (
 from lnschema_core import Artifact, Run, Storage
 from lnschema_core.models import IsTree
 from lnschema_core.types import (
-    DataLike,
     VisibilityChoice,
 )
 
@@ -53,15 +53,17 @@ from .core._data import (
 from .core.storage.file import AUTO_KEY_PREFIX
 
 if TYPE_CHECKING:
+    from lamindb_setup.core.types import UPathStr
+
     from lamindb.core.storage._backed_access import AnnDataAccessor, BackedAccessor
 
 
 def process_pathlike(
     filepath: UPath,
     default_storage: Storage,
-    using_key: Optional[str],
+    using_key: str | None,
     skip_existence_check: bool = False,
-) -> Tuple[Storage, bool]:
+) -> tuple[Storage, bool]:
     if not skip_existence_check:
         try:  # check if file exists
             if not filepath.exists():
@@ -111,13 +113,13 @@ def process_pathlike(
 
 def process_data(
     provisional_uid: str,
-    data: Union[UPathStr, DataLike],
-    format: Optional[str],
-    key: Optional[str],
+    data: UPathStr | pd.DataFrame | AnnData,
+    format: str | None,
+    key: str | None,
     default_storage: Storage,
-    using_key: Optional[str],
+    using_key: str | None,
     skip_existence_check: bool = False,
-) -> Tuple[Any, Union[Path, UPath], str, Storage, bool]:
+) -> tuple[Any, Path | UPath, str, Storage, bool]:
     """Serialize a data object that's provided as file or in memory."""
     # if not overwritten, data gets stored in default storage
     if isinstance(data, (str, Path, UPath)):  # UPathStr, spelled out
@@ -135,7 +137,7 @@ def process_data(
         )
         suffix = extract_suffix_from_path(path)
         memory_rep = None
-    elif isinstance(data, (pd.DataFrame, AnnData)):  # DataLike, spelled out
+    elif isinstance(data, (pd.DataFrame, AnnData)):
         storage = default_storage
         memory_rep = data
         if key is not None:
@@ -170,10 +172,10 @@ def process_data(
 def get_stat_or_artifact(
     path: UPath,
     suffix: str,
-    memory_rep: Optional[Any] = None,
+    memory_rep: Any | None = None,
     check_hash: bool = True,
-    using_key: Optional[str] = None,
-) -> Union[Tuple[int, Optional[str], Optional[str], Optional[int]], Artifact]:
+    using_key: str | None = None,
+) -> tuple[int, str | None, str | None, int | None] | Artifact:
     n_objects = None
     if settings.upon_file_create_skip_size_hash:
         return None, None, None, n_objects
@@ -245,8 +247,8 @@ def get_stat_or_artifact(
 
 
 def check_path_in_existing_storage(
-    path: Union[Path, UPath], using_key: Optional[str]
-) -> Union[Storage, bool]:
+    path: Path | UPath, using_key: str | None
+) -> Storage | bool:
     for storage in Storage.objects.using(using_key).filter().all():
         # if path is part of storage, return it
         if check_path_is_child_of_root(path, root=create_path(storage.root)):
@@ -254,9 +256,7 @@ def check_path_in_existing_storage(
     return False
 
 
-def check_path_is_child_of_root(
-    path: Union[Path, UPath], root: Optional[Union[Path, UPath]]
-) -> bool:
+def check_path_is_child_of_root(path: Path | UPath, root: Path | UPath | None) -> bool:
     path = UPath(str(path)) if not isinstance(path, UPath) else path
     root = UPath(str(root)) if not isinstance(root, UPath) else root
 
@@ -276,8 +276,8 @@ def check_path_is_child_of_root(
 
 
 def get_relative_path_to_directory(
-    path: Union[PurePath, Path, UPath], directory: Union[PurePath, Path, UPath]
-) -> Union[PurePath, Path]:
+    path: PurePath | Path | UPath, directory: PurePath | Path | UPath
+) -> PurePath | Path:
     if isinstance(directory, UPath) and not isinstance(directory, LocalPathClasses):
         # UPath.relative_to() is not behaving as it should (2023-04-07)
         # need to lstrip otherwise inconsistent behavior across trailing slashes
@@ -296,13 +296,13 @@ def get_relative_path_to_directory(
 
 def get_artifact_kwargs_from_data(
     *,
-    data: Union[Path, UPath, str, pd.DataFrame, AnnData],
-    key: Optional[str],
-    run: Optional[Run],
-    format: Optional[str],
+    data: Path | UPath | str | pd.DataFrame | AnnData,
+    key: str | None,
+    run: Run | None,
+    format: str | None,
     provisional_uid: str,
     default_storage: Storage,
-    using_key: Optional[str] = None,
+    using_key: str | None = None,
     skip_check_exists: bool = False,
 ):
     run = get_run(run)
@@ -399,8 +399,8 @@ def get_artifact_kwargs_from_data(
 def log_storage_hint(
     *,
     check_path_in_storage: bool,
-    storage: Optional[Storage],
-    key: Optional[str],
+    storage: Storage | None,
+    key: str | None,
     uid: str,
     suffix: str,
     is_dir: bool,
@@ -426,7 +426,7 @@ def log_storage_hint(
     logger.hint(hint)
 
 
-def data_is_anndata(data: DataLike):
+def data_is_anndata(data: AnnData | UPathStr):
     if isinstance(data, AnnData):
         return True
     if isinstance(data, (str, Path, UPath)):
@@ -434,7 +434,7 @@ def data_is_anndata(data: DataLike):
     return False  # pragma: no cover
 
 
-def data_is_mudata(data: DataLike):  # pragma: no cover
+def data_is_mudata(data: Any | UPathStr):  # pragma: no cover
     try:
         from mudata import MuData
     except ModuleNotFoundError:
@@ -447,7 +447,7 @@ def data_is_mudata(data: DataLike):  # pragma: no cover
     return False
 
 
-def _check_accessor_artifact(data: Any, accessor: Optional[str] = None):
+def _check_accessor_artifact(data: Any, accessor: str | None = None):
     if accessor is None and not isinstance(data, (str, Path, UPath)):
         if isinstance(data, pd.DataFrame):
             logger.warning("data is a DataFrame, please use .from_df()")
@@ -476,17 +476,17 @@ def __init__(artifact: Artifact, *args, **kwargs):
     if len(args) > 1:
         raise ValueError("Only one non-keyword arg allowed: data")
 
-    data: Union[str, Path] = kwargs.pop("data") if len(args) == 0 else args[0]
-    key: Optional[str] = kwargs.pop("key") if "key" in kwargs else None
-    run: Optional[Run] = kwargs.pop("run") if "run" in kwargs else None
-    description: Optional[str] = (
+    data: str | Path = kwargs.pop("data") if len(args) == 0 else args[0]
+    key: str | None = kwargs.pop("key") if "key" in kwargs else None
+    run: Run | None = kwargs.pop("run") if "run" in kwargs else None
+    description: str | None = (
         kwargs.pop("description") if "description" in kwargs else None
     )
-    is_new_version_of: Optional[Artifact] = (
+    is_new_version_of: Artifact | None = (
         kwargs.pop("is_new_version_of") if "is_new_version_of" in kwargs else None
     )
-    version: Optional[str] = kwargs.pop("version") if "version" in kwargs else None
-    visibility: Optional[int] = (
+    version: str | None = kwargs.pop("version") if "version" in kwargs else None
+    visibility: int | None = (
         kwargs.pop("visibility")
         if "visibility" in kwargs
         else VisibilityChoice.default.value
@@ -571,14 +571,14 @@ def __init__(artifact: Artifact, *args, **kwargs):
 @doc_args(Artifact.from_df.__doc__)
 def from_df(
     cls,
-    df: "pd.DataFrame",
-    key: Optional[str] = None,
-    description: Optional[str] = None,
-    run: Optional[Run] = None,
-    version: Optional[str] = None,
-    is_new_version_of: Optional["Artifact"] = None,
+    df: pd.DataFrame,
+    key: str | None = None,
+    description: str | None = None,
+    run: Run | None = None,
+    version: str | None = None,
+    is_new_version_of: Artifact | None = None,
     **kwargs,
-) -> "Artifact":
+) -> Artifact:
     """{}."""
     artifact = Artifact(
         data=df,
@@ -597,14 +597,14 @@ def from_df(
 @doc_args(Artifact.from_anndata.__doc__)
 def from_anndata(
     cls,
-    adata: "AnnData",
-    key: Optional[str] = None,
-    description: Optional[str] = None,
-    run: Optional[Run] = None,
-    version: Optional[str] = None,
-    is_new_version_of: Optional["Artifact"] = None,
+    adata: AnnData,
+    key: str | None = None,
+    description: str | None = None,
+    run: Run | None = None,
+    version: str | None = None,
+    is_new_version_of: Artifact | None = None,
     **kwargs,
-) -> "Artifact":
+) -> Artifact:
     """{}."""
     artifact = Artifact(
         data=adata,
@@ -624,10 +624,10 @@ def from_anndata(
 def from_dir(
     cls,
     path: UPathStr,
-    key: Optional[str] = None,
+    key: str | None = None,
     *,
-    run: Optional[Run] = None,
-) -> List["Artifact"]:
+    run: Run | None = None,
+) -> list[Artifact]:
     """{}."""
     logger.warning(
         "this creates one artifact per file in the directory - you might simply call"
@@ -639,7 +639,7 @@ def from_dir(
     storage, use_existing_storage = process_pathlike(
         folderpath, default_storage, using_key
     )
-    folder_key_path: Union[PurePath, Path]
+    folder_key_path: PurePath | Path
     if key is None:
         if not use_existing_storage:
             logger.warning(
@@ -724,9 +724,9 @@ def from_dir(
 # docstring handled through attach_func_to_class_method
 def replace(
     self,
-    data: Union[UPathStr, DataLike],
-    run: Optional[Run] = None,
-    format: Optional[str] = None,
+    data: UPathStr,
+    run: Run | None = None,
+    format: str | None = None,
 ) -> None:
     default_storage = settings._storage_settings.record
     kwargs, privates = get_artifact_kwargs_from_data(
@@ -784,9 +784,7 @@ def replace(
 
 
 # docstring handled through attach_func_to_class_method
-def backed(
-    self, is_run_input: Optional[bool] = None
-) -> Union["AnnDataAccessor", "BackedAccessor"]:
+def backed(self, is_run_input: bool | None = None) -> AnnDataAccessor | BackedAccessor:
     suffixes = (".h5", ".hdf5", ".h5ad", ".zrad", ".zarr")
     if self.suffix not in suffixes:
         raise ValueError(
@@ -809,9 +807,7 @@ def backed(
 
 
 # docstring handled through attach_func_to_class_method
-def load(
-    self, is_run_input: Optional[bool] = None, stream: bool = False, **kwargs
-) -> DataLike:
+def load(self, is_run_input: bool | None = None, stream: bool = False, **kwargs) -> Any:
     _track_run_input(self, is_run_input)
     if hasattr(self, "_memory_rep") and self._memory_rep is not None:
         return self._memory_rep
@@ -822,7 +818,7 @@ def load(
 
 
 # docstring handled through attach_func_to_class_method
-def stage(self, is_run_input: Optional[bool] = None) -> Path:
+def stage(self, is_run_input: bool | None = None) -> Path:
     _track_run_input(self, is_run_input)
 
     using_key = settings._using_key
@@ -833,9 +829,9 @@ def stage(self, is_run_input: Optional[bool] = None) -> Path:
 # docstring handled through attach_func_to_class_method
 def delete(
     self,
-    permanent: Optional[bool] = None,
-    storage: Optional[bool] = None,
-    using_key: Optional[str] = None,
+    permanent: bool | None = None,
+    storage: bool | None = None,
+    using_key: str | None = None,
 ) -> None:
     # by default, we only move artifacts into the trash (visibility = -1)
     trash_visibility = VisibilityChoice.trash.value
@@ -927,7 +923,7 @@ def _save_skip_storage(file, *args, **kwargs) -> None:
 
 @property  # type: ignore
 @doc_args(Artifact.path.__doc__)
-def path(self) -> Union[Path, UPath]:
+def path(self) -> Path | UPath:
     """{}."""
     using_key = settings._using_key
     return filepath_from_artifact(self, using_key)