lamindb 0.74.0__py3-none-any.whl → 0.74.2__py3-none-any.whl

lamindb/_parents.py

@@ -5,12 +5,12 @@ from typing import TYPE_CHECKING
 
 import lamindb_setup as ln_setup
 from lamin_utils import logger
-from lnschema_core import Artifact, Collection, Registry, Run, Transform
+from lnschema_core import Artifact, Collection, Record, Run, Transform
 from lnschema_core.models import HasParents, format_field_value
 
 from lamindb._utils import attach_func_to_class_method
 
-from ._registry import get_default_str_field
+from ._record import get_default_str_field
 
 if TYPE_CHECKING:
     from lnschema_core.types import StrField
@@ -137,7 +137,7 @@ def view_lineage(data: Artifact | Collection, with_children: bool = True) -> Non
 
 
 def _view_parents(
-    record: Registry, field: str, with_children: bool = False, distance: int = 100
+    record: Record, field: str, with_children: bool = False, distance: int = 100
 ):
     """Graph of parents."""
     if not hasattr(record, "parents"):
@@ -197,7 +197,7 @@ def _view_parents(
     _view(u)
 
 
-def _get_parents(record: Registry, field: str, distance: int, children: bool = False):
+def _get_parents(record: Record, field: str, distance: int, children: bool = False):
     """Recursively get parent records within a distance."""
     if children:
         key = "parents"
@@ -228,7 +228,7 @@ def _get_parents(record: Registry, field: str, distance: int, children: bool = F
 
 
 def _df_edges_from_parents(
-    record: Registry, field: str, distance: int, children: bool = False
+    record: Record, field: str, distance: int, children: bool = False
 ):
     """Construct a DataFrame of edges as the input of graphviz.Digraph."""
     key = "children" if children else "parents"
@@ -267,7 +267,7 @@ def _df_edges_from_parents(
     return df_edges
 
 
-def _record_label(record: Registry, field: str | None = None):
+def _record_label(record: Record, field: str | None = None):
     if isinstance(record, Artifact):
         if record.description is None:
             name = record.key
@@ -311,7 +311,7 @@ def _record_label(record: Registry, field: str | None = None):
         )
 
 
-def _add_emoji(record: Registry, label: str):
+def _add_emoji(record: Record, label: str):
     if record.__class__.__name__ == "Transform":
         emoji = TRANSFORM_EMOJIS.get(record.type, "💫")
     elif record.__class__.__name__ == "Run":

lamindb/_query_manager.py

@@ -5,7 +5,7 @@ from typing import TYPE_CHECKING, NamedTuple
 from django.db import models
 from lamin_utils import logger
 from lamindb_setup.core._docs import doc_args
-from lnschema_core.models import Registry
+from lnschema_core.models import Record
 
 from lamindb.core._settings import settings
 
@@ -45,7 +45,7 @@ class QueryManager(models.Manager):
 
                 if (
                     run_context.run is None
-                    and not settings.silence_file_run_transform_warning
+                    and not settings.creation.artifact_silence_missing_run_warning
                 ):
                     logger.warning(WARNING_RUN_TRANSFORM)
                 _track_run_input(self.instance)
@@ -84,17 +84,17 @@ class QueryManager(models.Manager):
         self._track_run_input_manager()
         return self._all_base_class()
 
-    @doc_args(Registry.search.__doc__)
+    @doc_args(Record.search.__doc__)
     def search(self, string: str, **kwargs):
-        """{}."""
-        from ._registry import _search
+        """{}"""  # noqa: D415
+        from ._record import _search
 
         return _search(cls=self.all(), string=string, **kwargs)
 
-    @doc_args(Registry.lookup.__doc__)
+    @doc_args(Record.lookup.__doc__)
     def lookup(self, field: StrField | None = None, **kwargs) -> NamedTuple:
-        """{}."""
-        from ._registry import _lookup
+        """{}"""  # noqa: D415
+        from ._record import _lookup
 
         return _lookup(cls=self.all(), field=field, **kwargs)
 

lamindb/_query_set.py

@@ -12,7 +12,7 @@ from lnschema_core.models import (
     CanValidate,
     Collection,
     IsVersioned,
-    Registry,
+    Record,
     Run,
     Transform,
 )
@@ -35,7 +35,7 @@ class MultipleResultsFound(Exception):
 #     return (series + timedelta).dt.strftime("%Y-%m-%d %H:%M:%S %Z")
 
 
-def get_keys_from_df(data: list, registry: Registry) -> list[str]:
+def get_keys_from_df(data: list, registry: Record) -> list[str]:
     if len(data) > 0:
         if isinstance(data[0], dict):
             keys = list(data[0].keys())
@@ -69,7 +69,7 @@ def one_helper(self):
 class RecordsList(UserList):
     """Is ordered, can't be queried, but has `.df()`."""
 
-    def __init__(self, records: Iterable[Registry]):
+    def __init__(self, records: Iterable[Record]):
         super().__init__(record for record in records)
 
     def df(self) -> pd.DataFrame:
@@ -77,7 +77,7 @@ class RecordsList(UserList):
         values = [record.__dict__ for record in self.data]
         return pd.DataFrame(values, columns=keys)
 
-    def one(self) -> Registry:
+    def one(self) -> Record:
         """Exactly one result. Throws error if there are more or none."""
         return one_helper(self)
 
@@ -96,9 +96,11 @@ class QuerySet(models.QuerySet, CanValidate):
         >>> queryset
     """
 
-    @doc_args(Registry.df.__doc__)
-    def df(self, include: str | list[str] | None = None) -> pd.DataFrame:
-        """{}."""
+    @doc_args(Record.df.__doc__)
+    def df(
+        self, include: str | list[str] | None = None, join: str = "inner"
+    ) -> pd.DataFrame:
+        """{}"""  # noqa: D415
         # re-order the columns
         exclude_field_names = ["created_at"]
         field_names = [
@@ -145,21 +147,21 @@ class QuerySet(models.QuerySet, CanValidate):
                     lookup_str = "__".join(split[1:])
                 else:
                     lookup_str = "id"
-                Registry = self.model
-                field = getattr(Registry, field_name)
+                Record = self.model
+                field = getattr(Record, field_name)
                 if isinstance(field.field, models.ManyToManyField):
                     related_ORM = (
                         field.field.model
-                        if field.field.model != Registry
+                        if field.field.model != Record
                         else field.field.related_model
                     )
-                    if Registry == related_ORM:
-                        left_side_link_model = f"from_{Registry.__name__.lower()}"
+                    if Record == related_ORM:
+                        left_side_link_model = f"from_{Record.__name__.lower()}"
                         values_expression = (
-                            f"to_{Registry.__name__.lower()}__{lookup_str}"
+                            f"to_{Record.__name__.lower()}__{lookup_str}"
                         )
                     else:
-                        left_side_link_model = f"{Registry.__name__.lower()}"
+                        left_side_link_model = f"{Record.__name__.lower()}"
                         values_expression = (
                             f"{related_ORM.__name__.lower()}__{lookup_str}"
                         )
@@ -173,7 +175,7 @@ class QuerySet(models.QuerySet, CanValidate):
                     link_groupby = link_df.groupby(left_side_link_model)[
                         values_expression
                     ].apply(list)
-                    df = pd.concat((link_groupby, df), axis=1, join="inner")
+                    df = pd.concat((link_groupby, df), axis=1, join=join)
                     df.rename(columns={values_expression: expression}, inplace=True)
                 else:
                     # the F() based implementation could also work for many-to-many,
@@ -185,7 +187,7 @@ class QuerySet(models.QuerySet, CanValidate):
                     )
                     df_anno = df_anno.set_index(pk_column_name)
                     df_anno.rename(columns={"expression": expression}, inplace=True)
-                    df = pd.concat((df_anno, df), axis=1, join="inner")
+                    df = pd.concat((df_anno, df), axis=1, join=join)
         return df
 
     def delete(self, *args, **kwargs):
@@ -197,7 +199,7 @@ class QuerySet(models.QuerySet, CanValidate):
         else:
             self._delete_base_class(*args, **kwargs)
 
-    def list(self, field: str | None = None) -> list[Registry]:
+    def list(self, field: str | None = None) -> list[Record]:
         """Populate a list with the results.
 
         Examples:
@@ -209,7 +211,7 @@ class QuerySet(models.QuerySet, CanValidate):
         else:
             return list(self.values_list(field, flat=True))
 
-    def first(self) -> Registry | None:
+    def first(self) -> Record | None:
         """If non-empty, the first result in the query set, otherwise ``None``.
 
         Examples:
@@ -219,7 +221,7 @@ class QuerySet(models.QuerySet, CanValidate):
             return None
         return self[0]
 
-    def one(self) -> Registry:
+    def one(self) -> Record:
         """Exactly one result. Raises error if there are more or none.
 
         Examples:
@@ -227,7 +229,7 @@ class QuerySet(models.QuerySet, CanValidate):
         """
         return one_helper(self)
 
-    def one_or_none(self) -> Registry | None:
+    def one_or_none(self) -> Record | None:
         """At most one result. Returns it if there is one, otherwise returns ``None``.
 
         Examples:
@@ -246,32 +248,32 @@ class QuerySet(models.QuerySet, CanValidate):
         if issubclass(self.model, IsVersioned):
             return filter_query_set_by_latest_version(self)
         else:
-            raise ValueError("Registry isn't subclass of `lamindb.core.IsVersioned`")
+            raise ValueError("Record isn't subclass of `lamindb.core.IsVersioned`")
 
-    @doc_args(Registry.search.__doc__)
+    @doc_args(Record.search.__doc__)
     def search(self, string: str, **kwargs):
-        """{}."""
-        from ._registry import _search
+        """{}"""  # noqa: D415
+        from ._record import _search
 
         return _search(cls=self, string=string, **kwargs)
 
-    @doc_args(Registry.lookup.__doc__)
+    @doc_args(Record.lookup.__doc__)
     def lookup(self, field: StrField | None = None, **kwargs) -> NamedTuple:
-        """{}."""
-        from ._registry import _lookup
+        """{}"""  # noqa: D415
+        from ._record import _lookup
 
         return _lookup(cls=self, field=field, **kwargs)
 
     @doc_args(CanValidate.validate.__doc__)
     def validate(self, values: ListLike, field: str | StrField | None = None, **kwargs):
-        """{}."""
+        """{}"""  # noqa: D415
         from ._can_validate import _validate
 
         return _validate(cls=self, values=values, field=field, **kwargs)
 
     @doc_args(CanValidate.inspect.__doc__)
     def inspect(self, values: ListLike, field: str | StrField | None = None, **kwargs):
-        """{}."""
+        """{}"""  # noqa: D415
         from ._can_validate import _inspect
 
         return _inspect(cls=self, values=values, field=field, **kwargs)
@@ -280,7 +282,7 @@ class QuerySet(models.QuerySet, CanValidate):
     def standardize(
         self, values: Iterable, field: str | StrField | None = None, **kwargs
     ):
-        """{}."""
+        """{}"""  # noqa: D415
         from ._can_validate import _standardize
 
         return _standardize(cls=self, values=values, field=field, **kwargs)

lamindb/{_registry.py → _record.py}

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import builtins
-from typing import TYPE_CHECKING, Iterable, List, NamedTuple
+from typing import TYPE_CHECKING, List, NamedTuple
 
 import dj_database_url
 import lamindb_setup as ln_setup
@@ -12,7 +12,7 @@ from lamin_utils._lookup import Lookup
 from lamindb_setup._connect_instance import get_owner_name_from_identifier
 from lamindb_setup.core._docs import doc_args
 from lamindb_setup.core._hub_core import connect_instance
-from lnschema_core import Registry
+from lnschema_core.models import IsVersioned, Record
 
 from lamindb._utils import attach_func_to_class_method
 from lamindb.core._settings import settings
@@ -20,12 +20,14 @@ from lamindb.core._settings import settings
 from ._from_values import get_or_create_records
 
 if TYPE_CHECKING:
+    import pandas as pd
     from lnschema_core.types import ListLike, StrField
 
+
 IPYTHON = getattr(builtins, "__IPYTHON__", False)
 
 
-def init_self_from_db(self: Registry, existing_record: Registry):
+def init_self_from_db(self: Record, existing_record: Record):
     new_args = [
         getattr(existing_record, field.attname) for field in self._meta.concrete_fields
     ]
@@ -34,7 +36,7 @@ def init_self_from_db(self: Registry, existing_record: Registry):
     self._state.db = "default"
 
 
-def validate_required_fields(orm: Registry, kwargs):
+def validate_required_fields(orm: Record, kwargs):
     required_fields = {
         k.name for k in orm._meta.fields if not k.null and k.default is None
     }
@@ -47,14 +49,16 @@ def validate_required_fields(orm: Registry, kwargs):
         raise TypeError(f"{missing_fields} are required.")
 
 
-def suggest_records_with_similar_names(record: Registry, kwargs) -> bool:
+def suggest_records_with_similar_names(record: Record, kwargs) -> bool:
     """Returns True if found exact match, otherwise False.
 
     Logs similar matches if found.
     """
     if kwargs.get("name") is None:
         return False
-    queryset = _search(record.__class__, kwargs["name"], truncate_words=True, limit=20)
+    queryset = _search(
+        record.__class__, kwargs["name"], field="name", truncate_words=True, limit=20
+    )
     if not queryset.exists():  # empty queryset
         return False
     for alternative_record in queryset:
@@ -73,7 +77,7 @@ def suggest_records_with_similar_names(record: Registry, kwargs) -> bool:
     return False
 
 
-def __init__(orm: Registry, *args, **kwargs):
+def __init__(orm: Record, *args, **kwargs):
     if not args:
         validate_required_fields(orm, kwargs)
 
@@ -82,17 +86,17 @@ def __init__(orm: Registry, *args, **kwargs):
         has_consciously_provided_uid = False
         if "_has_consciously_provided_uid" in kwargs:
             has_consciously_provided_uid = kwargs.pop("_has_consciously_provided_uid")
-        if settings.upon_create_search_names and not has_consciously_provided_uid:
+        if settings.creation.search_names and not has_consciously_provided_uid:
             match = suggest_records_with_similar_names(orm, kwargs)
             if match:
                 if "version" in kwargs:
                     version_comment = " and version"
-                    existing_record = orm.filter(
+                    existing_record = orm.__class__.filter(
                         name=kwargs["name"], version=kwargs["version"]
                     ).one_or_none()
                 else:
                     version_comment = ""
-                    existing_record = orm.filter(name=kwargs["name"]).one()
+                    existing_record = orm.__class__.filter(name=kwargs["name"]).one()
                 if existing_record is not None:
                     logger.important(
                         f"returning existing {orm.__class__.__name__} record with same"
@@ -100,27 +104,66 @@ def __init__(orm: Registry, *args, **kwargs):
                     )
                     init_self_from_db(orm, existing_record)
                     return None
-        super(Registry, orm).__init__(**kwargs)
+        super(Record, orm).__init__(**kwargs)
     elif len(args) != len(orm._meta.concrete_fields):
         raise ValueError("please provide keyword arguments, not plain arguments")
     else:
         # object is loaded from DB (**kwargs could be omitted below, I believe)
-        super(Registry, orm).__init__(*args, **kwargs)
+        super(Record, orm).__init__(*args, **kwargs)
+
+
+@classmethod  # type:ignore
+@doc_args(Record.filter.__doc__)
+def filter(cls, **expressions) -> QuerySet:
+    """{}"""  # noqa: D415
+    from lamindb._filter import filter
+
+    return filter(cls, **expressions)
+
+
+@classmethod  # type:ignore
+@doc_args(Record.get.__doc__)
+def get(cls, idlike: int | str) -> Record:
+    """{}"""  # noqa: D415
+    from lamindb._filter import filter
+
+    if isinstance(idlike, int):
+        return filter(cls, id=idlike).one()
+    else:
+        qs = filter(cls, uid__startswith=idlike)
+        if issubclass(cls, IsVersioned):
+            return qs.latest_version().one()
+        else:
+            return qs.one()
+
+
+@classmethod  # type:ignore
+@doc_args(Record.df.__doc__)
+def df(
+    cls, include: str | list[str] | None = None, join: str = "inner"
+) -> pd.DataFrame:
+    """{}"""  # noqa: D415
+    from lamindb._filter import filter
+
+    query_set = filter(cls)
+    if hasattr(cls, "updated_at"):
+        query_set = query_set.order_by("-updated_at")
+    return query_set.df(include=include, join=join)
 
 
 # from_values doesn't apply for QuerySet or Manager
 @classmethod  # type:ignore
-@doc_args(Registry.from_values.__doc__)
+@doc_args(Record.from_values.__doc__)
 def from_values(
     cls,
     values: ListLike,
     field: StrField | None = None,
     create: bool = False,
-    organism: Registry | str | None = None,
-    public_source: Registry | None = None,
+    organism: Record | str | None = None,
+    public_source: Record | None = None,
     mute: bool = False,
-) -> list[Registry]:
-    """{}."""
+) -> list[Record]:
+    """{}"""  # noqa: D415
     from_public = True if cls.__module__.startswith("lnschema_bionty.") else False
     field_str = get_default_str_field(cls, field=field)
     return get_or_create_records(
@@ -134,14 +177,6 @@ def from_values(
     )
 
 
-# From: https://stackoverflow.com/a/37648265
-def _order_queryset_by_ids(queryset: QuerySet, ids: Iterable):
-    from django.db.models import Case, When
-
-    preserved = Case(*[When(uid=pk, then=pos) for pos, pk in enumerate(ids)])
-    return queryset.filter(uid__in=ids).order_by(preserved)
-
-
 def _search(
     cls,
     string: str,
@@ -172,7 +207,7 @@ def _search(
                     fields.append(field.field.name)
                 except AttributeError as error:
                     raise TypeError(
-                        "Please pass a Registry string field, e.g., `CellType.name`!"
+                        "Please pass a Record string field, e.g., `CellType.name`!"
                     ) from error
             else:
                 fields.append(field)
@@ -187,7 +222,7 @@ def _search(
         else:
             return word
 
-    decomposed_string = string.split()
+    decomposed_string = str(string).split()
     # add the entire string back
     decomposed_string += [string]
     for word in decomposed_string:
@@ -222,7 +257,7 @@ def _search(
 
 
 @classmethod  # type: ignore
-@doc_args(Registry.search.__doc__)
+@doc_args(Record.search.__doc__)
 def search(
     cls,
     string: str,
@@ -231,7 +266,7 @@ def search(
     limit: int | None = 20,
     case_sensitive: bool = False,
 ) -> QuerySet:
-    """{}."""
+    """{}"""  # noqa: D415
     return _search(
         cls=cls,
         string=string,
@@ -247,7 +282,7 @@ def _lookup(
     return_field: StrField | None = None,
     using_key: str | None = None,
 ) -> NamedTuple:
-    """{}."""
+    """{}"""  # noqa: D415
     queryset = _queryset(cls, using_key=using_key)
     field = get_default_str_field(orm=queryset.model, field=field)
 
@@ -266,18 +301,18 @@ def _lookup(
 
 
 @classmethod  # type: ignore
-@doc_args(Registry.lookup.__doc__)
+@doc_args(Record.lookup.__doc__)
 def lookup(
     cls,
     field: StrField | None = None,
     return_field: StrField | None = None,
 ) -> NamedTuple:
-    """{}."""
+    """{}"""  # noqa: D415
     return _lookup(cls=cls, field=field, return_field=return_field)
 
 
 def get_default_str_field(
-    orm: Registry | QuerySet | Manager,
+    orm: Record | QuerySet | Manager,
     *,
     field: str | StrField | None = None,
 ) -> str:
@@ -307,7 +342,7 @@ def get_default_str_field(
         # no default field can be found
         if field is None:
             raise ValueError(
-                "please pass a Registry string field, e.g., `CellType.name`!"
+                "please pass a Record string field, e.g., `CellType.name`!"
             )
         else:
             field = field.name  # type:ignore
@@ -316,17 +351,20 @@ def get_default_str_field(
             field = field.field.name
         except AttributeError:
             raise TypeError(
-                "please pass a Registry string field, e.g., `CellType.name`!"
+                "please pass a Record string field, e.g., `CellType.name`!"
             ) from None
 
     return field
 
 
-def _queryset(cls: Registry | QuerySet | Manager, using_key: str) -> QuerySet:
-    queryset = (
-        cls.all() if isinstance(cls, QuerySet) else cls.objects.using(using_key).all()
-    )
-    return queryset
+def _queryset(cls: Record | QuerySet | Manager, using_key: str) -> QuerySet:
+    if isinstance(cls, (QuerySet, Manager)):
+        return cls.all()
+    elif using_key is None:
+        return cls.objects.all()
+    else:
+        # using must be called on cls, otherwise the connection isn't found
+        return cls.using(using_key).all()
 
 
 def add_db_connection(db: str, using: str):
@@ -340,12 +378,12 @@ def add_db_connection(db: str, using: str):
 
 
 @classmethod  # type: ignore
-@doc_args(Registry.using.__doc__)
+@doc_args(Record.using.__doc__)
 def using(
     cls,
     instance: str,
 ) -> QuerySet:
-    """{}."""
+    """{}"""  # noqa: D415
     from lamindb_setup._connect_instance import (
         load_instance_settings,
         update_db_using_local,
@@ -378,7 +416,7 @@ REGISTRY_UNIQUE_FIELD = {
 
 
 def update_fk_to_default_db(
-    records: Registry | list[Registry] | QuerySet,
+    records: Record | list[Record] | QuerySet,
     fk: str,
     using_key: str | None,
 ):
@@ -418,12 +456,12 @@ def transfer_fk_to_default_db_bulk(records: list | QuerySet, using_key: str | No
 
 
 def transfer_to_default_db(
-    record: Registry,
+    record: Record,
     using_key: str | None,
     save: bool = False,
     mute: bool = False,
     transfer_fk: bool = True,
-) -> Registry | None:
+) -> Record | None:
     db = record._state.db
     if db is not None and db != "default" and using_key is None:
         registry = record.__class__
@@ -447,7 +485,7 @@ def transfer_to_default_db(
             if run_context.run is not None:
                 record.run_id = run_context.run.id
             else:
-                if not settings.silence_file_run_transform_warning:
+                if not settings.creation.artifact_silence_missing_run_warning:
                     logger.warning(WARNING_RUN_TRANSFORM)
                 record.run_id = None
         if hasattr(record, "transform_id") and record._meta.model_name != "run":
@@ -476,7 +514,7 @@ def transfer_to_default_db(
 
 
 # docstring handled through attach_func_to_class_method
-def save(self, *args, **kwargs) -> Registry:
+def save(self, *args, **kwargs) -> Record:
     using_key = None
     if "using" in kwargs:
         using_key = kwargs["using"]
@@ -496,7 +534,7 @@ def save(self, *args, **kwargs) -> Registry:
         save_kwargs = kwargs.copy()
         if "parents" in save_kwargs:
             save_kwargs.pop("parents")
-        super(Registry, self).save(*args, **save_kwargs)
+        super(Record, self).save(*args, **save_kwargs)
     # perform transfer of many-to-many fields
     # only supported for Artifact and Collection records
     if db is not None and db != "default" and using_key is None:
@@ -531,6 +569,9 @@ def save(self, *args, **kwargs) -> Registry:
 
 METHOD_NAMES = [
     "__init__",
+    "filter",
+    "get",
+    "df",
     "search",
     "lookup",
     "save",
@@ -542,10 +583,10 @@ if ln_setup._TESTING:  # type: ignore
     from inspect import signature
 
     SIGS = {
-        name: signature(getattr(Registry, name))
+        name: signature(getattr(Record, name))
         for name in METHOD_NAMES
         if not name.startswith("__")
     }
 
 for name in METHOD_NAMES:
-    attach_func_to_class_method(name, Registry, globals())
+    attach_func_to_class_method(name, Record, globals())