lamindb 1.1.1__py3-none-any.whl → 1.2.0__py3-none-any.whl

lamindb/{core/versioning.py → models/_is_versioned.py}

@@ -1,15 +1,104 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Literal
+from typing import TYPE_CHECKING, Literal, overload
 
+from django.db import models
 from lamin_utils import logger
 from lamin_utils._base62 import increment_base62
 from lamindb_setup.core.upath import LocalPathClasses, UPath
 
 from lamindb.base import ids
+from lamindb.base.fields import (
+    BooleanField,
+    CharField,
+)
 
-if TYPE_CHECKING:
-    from lamindb.models import IsVersioned
+if TYPE_CHECKING:  # noqa
+    from lamindb.models.query_set import QuerySet
+
+
+class IsVersioned(models.Model):
+    """Base class for versioned models."""
+
+    class Meta:
+        abstract = True
+
+    _len_stem_uid: int
+
+    version: str | None = CharField(max_length=30, null=True, db_index=True)
+    """Version (default `None`).
+
+    Defines version of a family of records characterized by the same `stem_uid`.
+
+    Consider using `semantic versioning <https://semver.org>`__
+    with `Python versioning <https://peps.python.org/pep-0440/>`__.
+    """
+    is_latest: bool = BooleanField(default=True, db_index=True)
+    """Boolean flag that indicates whether a record is the latest in its version family."""
+
+    @overload
+    def __init__(self): ...
+
+    @overload
+    def __init__(
+        self,
+        *db_args,
+    ): ...
+
+    def __init__(
+        self,
+        *args,
+        **kwargs,
+    ):
+        self._revises = kwargs.pop("revises") if "revises" in kwargs else None
+        super().__init__(*args, **kwargs)
+
+    @property
+    def stem_uid(self) -> str:
+        """Universal id characterizing the version family.
+
+        The full uid of a record is obtained via concatenating the stem uid and version information::
+
+            stem_uid = random_base62(n_char)  # a random base62 sequence of length 12 (transform) or 16 (artifact, collection)
+            version_uid = "0000"  # an auto-incrementing 4-digit base62 number
+            uid = f"{stem_uid}{version_uid}"  # concatenate the stem_uid & version_uid
+
+        """
+        return self.uid[: self._len_stem_uid]  # type: ignore
+
+    @property
+    def versions(self) -> QuerySet:
+        """Lists all records of the same version family.
+
+        >>> new_artifact = ln.Artifact(df2, revises=artifact).save()
+        >>> new_artifact.versions()
+        """
+        db = self._state.db
+        if db is not None and db != "default":
+            return self.__class__.using(db).filter(uid__startswith=self.stem_uid)  # type: ignore
+        else:
+            return self.__class__.filter(uid__startswith=self.stem_uid)  # type: ignore
+
+    def _add_to_version_family(self, revises: IsVersioned, version: str | None = None):
+        """Add current record to a version family.
+
+        Args:
+            revises: a record that belongs to the version family.
+            version: semantic version of the record.
+        """
+        old_uid = self.uid  # type: ignore
+        new_uid, revises = create_uid(revises=revises, version=version)
+        if self.__class__.__name__ == "Artifact" and self._key_is_virtual:
+            old_path = self.path
+            new_path = get_new_path_from_uid(
+                old_path=old_path, old_uid=old_uid, new_uid=new_uid
+            )
+            new_path = UPath(old_path).rename(new_path)
+            logger.success(f"updated path from {old_path} to {new_path}!")
+        self.uid = new_uid
+        self.version = version
+        self.save()
+        logger.success(f"updated uid from {old_uid} to {new_uid}!")
 
 
 def message_update_key_in_version_family(
@@ -102,15 +191,14 @@ def create_uid(
                 f"didn't pass the latest version in `revises`, retrieved it: {revises}"
             )
         suid = revises.stem_uid
-        vuid = increment_base62(revises.uid[-4:])
+        vuid = increment_base62(revises.uid[-4:])  # type: ignore
     else:
         suid = ids.base62(n_full_id - 4)
         vuid = "0000"
     if version is not None:
         if not isinstance(version, str):
             raise ValueError(
-                "`version` parameter must be `None` or `str`, e.g., '0.1', '1', '2',"
-                " etc."
+                "`version` parameter must be `None` or `str`, e.g., '0.1', '1', '2', etc."
             )
         if revises is not None:
             if version == revises.version:

lamindb/{core → models}/_label_manager.py

@@ -1,6 +1,5 @@
 from __future__ import annotations
 
-import warnings
 from collections import defaultdict
 from typing import TYPE_CHECKING
 
@@ -10,15 +9,15 @@ from rich.table import Column, Table
 from rich.text import Text
 from rich.tree import Tree
 
-from lamindb._from_values import _format_values
-from lamindb._record import (
+from lamindb.models import CanCurate, Feature
+from lamindb.models._from_values import _format_values
+from lamindb.models.record import (
     REGISTRY_UNIQUE_FIELD,
     get_name_field,
     transfer_fk_to_default_db_bulk,
     transfer_to_default_db,
 )
-from lamindb._save import save
-from lamindb.models import CanCurate, Feature
+from lamindb.models.save import save
 
 from ._describe import (
     NAME_WIDTH,
@@ -28,12 +27,11 @@ from ._describe import (
     print_rich_tree,
 )
 from ._django import get_artifact_with_related, get_related_model
-from ._settings import settings
-from .relations import dict_related_model_to_related_name
+from ._relations import dict_related_model_to_related_name
 
 if TYPE_CHECKING:
-    from lamindb._query_set import QuerySet
     from lamindb.models import Artifact, Collection, Record
+    from lamindb.models.query_set import QuerySet
 
 EXCLUDE_LABELS = {"feature_sets"}
 
@@ -75,17 +73,10 @@ def _get_labels_postgres(
 def describe_labels(
     self: Artifact | Collection,
     labels_data: dict | None = None,
-    print_types: bool = False,  # deprecated
     tree: Tree | None = None,
     as_subtree: bool = False,
 ):
     """Describe labels associated with an artifact or collection."""
-    if print_types:
-        warnings.warn(
-            "`print_types` parameter is deprecated and will be removed in a future version. Types are now always printed.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
     if not self._state.adding and connections[self._state.db].vendor == "postgresql":
         labels_data = _get_labels_postgres(self, labels_data)
     if not labels_data:
@@ -205,7 +196,7 @@ class LabelManager:
             records: Label records to add.
             feature: Feature under which to group the labels.
         """
-        from ._data import add_labels
+        from .artifact import add_labels
 
         return add_labels(self._host, records=records, feature=feature)
 
@@ -222,7 +213,7 @@ class LabelManager:
             mute: Show no logging.
             flat_names: Flatten list to names rather than returning records.
         """
-        from ._data import get_labels
+        from .artifact import get_labels
 
         return get_labels(self._host, feature=feature, mute=mute, flat_names=flat_names)
 
@@ -240,6 +231,8 @@ class LabelManager:
         """
         if transfer_logs is None:
             transfer_logs = {"mapped": [], "transferred": [], "run": None}
+        from lamindb import settings
+
         using_key = settings._using_key
         for related_name, labels in _get_labels(data, instance=data._state.db).items():
             labels = labels.all()

lamindb/{core/relations.py → models/_relations.py}

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
 import lamindb_setup as ln_setup
 from django.db.models import ManyToManyField
 from lamindb_setup._connect_instance import (
@@ -8,7 +10,10 @@ from lamindb_setup._connect_instance import (
 )
 from lamindb_setup.core._settings_store import instance_settings_file
 
-from lamindb.models import LinkORM, Record, Registry, Schema
+from lamindb.models.record import LinkORM
+
+if TYPE_CHECKING:
+    from lamindb.models.record import Record, Registry
 
 
 def get_schema_modules(instance: str | None) -> set[str]:
@@ -84,6 +89,8 @@ def dict_related_model_to_related_name(
 
 
 def get_related_name(features_type: type[Record]) -> str:
+    from lamindb.models.schema import Schema
+
     candidates = [
         field.related_name
         for field in Schema._meta.related_objects