lamindb 1.3.1__py3-none-any.whl → 1.4.0__py3-none-any.whl

lamindb/__init__.py

@@ -72,7 +72,7 @@ Backward compatibility.
 
 # ruff: noqa: I001
 # denote a release candidate for 0.1.0 with 0.1rc1, 0.1a1, 0.1b1, etc.
-__version__ = "1.3.1"
+__version__ = "1.4.0"
 
 import warnings
 
@@ -123,8 +123,8 @@ if _check_instance_setup(from_module="lamindb"):
     from . import integrations
     from . import curators
 
-    track = context.track  # simple access
-    finish = context.finish  # simple access
+    track = context.track
+    finish = context.finish
     settings.__doc__ = """Global settings (:class:`~lamindb.core.Settings`)."""
     context.__doc__ = """Global run context (:class:`~lamindb.core.Context`).
 

lamindb/core/_context.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import builtins
 import hashlib
+import os
 import signal
 import sys
 import threading
@@ -22,7 +23,6 @@ from lamindb.models import Run, Transform, format_field_value
 
 from ..core._settings import settings
 from ..errors import (
-    InconsistentKey,
     InvalidArgument,
     TrackNotCalled,
     UpdateContext,
@@ -30,7 +30,6 @@ from ..errors import (
 from ..models._is_versioned import bump_version as bump_version_function
 from ..models._is_versioned import (
     increment_base62,
-    message_update_key_in_version_family,
 )
 from ._sync_git import get_transform_reference_from_git_repo
 from ._track_environment import track_environment
@@ -39,7 +38,7 @@ if TYPE_CHECKING:
     from lamindb_setup.core.types import UPathStr
 
     from lamindb.base.types import TransformType
-    from lamindb.models import Project
+    from lamindb.models import Project, Space
 
 is_run_from_ipython = getattr(builtins, "__IPYTHON__", False)
 
@@ -204,6 +203,7 @@ class Context:
         self._path: Path | None = None
         """A local path to the script that's running."""
         self._project: Project | None = None
+        self._space: Space | None = None
         self._logging_message_track: str = ""
         self._logging_message_imports: str = ""
         self._stream_tracker: LogStreamTracker = LogStreamTracker()
@@ -255,6 +255,11 @@ class Context:
         """Project to label entities created during the run."""
         return self._project
 
+    @property
+    def space(self) -> Space | None:
+        """The space in which entities are created during the run."""
+        return self._space
+
     @property
     def run(self) -> Run | None:
         """Managed run of context."""
@@ -265,23 +270,26 @@ class Context:
         transform: str | Transform | None = None,
         *,
         project: str | None = None,
+        space: str | None = None,
         params: dict | None = None,
         new_run: bool | None = None,
         path: str | None = None,
     ) -> None:
-        """Track a global run of your Python session.
+        """Track a global run in your compute session.
 
         - sets :attr:`~lamindb.core.Context.transform` &
           :attr:`~lamindb.core.Context.run` by creating or loading `Transform` &
           `Run` records
-        - saves Python environment as a `requirements.txt` file: `run.environment`
+        - writes compute environment to prepare populating: `run.environment`
+        - if :attr:`~lamindb.core.Settings.sync_git_repo` is set, checks whether a script-like
+          transform exists in a git repository and links it
 
-        If :attr:`~lamindb.core.Settings.sync_git_repo` is set, checks whether a
-        script-like transform exists in a git repository and links it.
+        Guide: :doc:`/track`
 
         Args:
-            transform: A transform `uid` or record. If `None`, creates a `uid`.
+            transform: A transform `uid` or record. If `None`, manages the `transform` based on the script or notebook that calls `ln.track()`.
             project: A project `name` or `uid` for labeling entities created during the run.
+            space: A space `name` or `uid` for creating entities during the run. This doesn't affect bionty entities given they should typically be commonly accessible.
             params: A dictionary of parameters to track for the run.
             new_run: If `False`, loads the latest run of transform
                 (default notebook), if `True`, creates new run (default non-notebook).
@@ -290,16 +298,16 @@ class Context:
 
         Examples:
 
-            To track the run of a notebook or script, call:
+            To track the run of a notebook or script, call::
 
-            >>> ln.track()
+                ln.track()
 
-            If you want to ensure a single version history across renames of the notebook or script, pass the auto-generated `uid` that you'll find in the logs:
+            If you want to ensure a single version history across renames of the notebook or script, pass the auto-generated `uid` that you'll find in the logs::
 
-            >>> ln.track("Onv04I53OgtT0000")  # example uid, the last four characters encode the version of the transform
+                ln.track("Onv04I53OgtT0000")  # example uid, the last four characters encode the version of the transform
 
         """
-        from lamindb.models import Project
+        from lamindb.models import Project, Space
 
         instance_settings = ln_setup.settings.instance
         # similar logic here: https://github.com/laminlabs/lamindb/pull/2527
@@ -307,6 +315,8 @@ class Context:
         if instance_settings.dialect == "postgresql" and "read" in instance_settings.db:
             logger.warning("skipping track(), connected in read-only mode")
             return None
+        if project is None:
+            project = os.environ.get("LAMIN_CURRENT_PROJECT")
         if project is not None:
             project_record = Project.filter(
                 Q(name=project) | Q(uid=project)
@@ -316,6 +326,13 @@ class Context:
                     f"Project '{project}' not found, either create it with `ln.Project(name='...').save()` or fix typos."
                 )
             self._project = project_record
+        if space is not None:
+            space_record = Space.filter(Q(name=space) | Q(uid=space)).one_or_none()
+            if space_record is None:
+                raise InvalidArgument(
+                    f"Space '{space}', please check on the hub UI whether you have the correct `uid` or `name`."
+                )
+            self._space = space_record
         self._logging_message_track = ""
         self._logging_message_imports = ""
         if transform is not None and isinstance(transform, str):
@@ -495,19 +512,6 @@ class Context:
         transform_ref_type: str | None = None,
         transform_type: TransformType = None,
     ):
-        def get_key_clashing_message(transform: Transform, key: str) -> str:
-            update_key_note = message_update_key_in_version_family(
-                suid=transform.stem_uid,
-                existing_key=transform.key,
-                new_key=key,
-                registry="Transform",
-            )
-            return (
-                f'Filepath "{key}" clashes with the existing key "{transform.key}" for uid "{transform.uid[:-4]}...."\n\nEither init a new transform with a new uid:\n\n'
-                f'ln.track("{ids.base62_12()}0000")\n\n{update_key_note}'
-            )
-
-        revises = None
         # the user did not pass the uid
         if self.uid is None:
 
@@ -531,27 +535,28 @@ class Context:
                 for aux_transform in transforms:
                     if aux_transform.key in self._path.as_posix():
                         key = aux_transform.key
+                        # first part of the if condition: no version bump, second part: version bump
                         if (
-                            # has to be the same user
-                            aux_transform.created_by_id == ln_setup.settings.user.id
-                            and (
-                                # if the transform source code wasn't yet saved
+                            # if a user hasn't yet saved the transform source code, needs to be same user
+                            (
                                 aux_transform.source_code is None
-                                # if the transform source code is unchanged
-                                # if aux_transform.type == "notebook", we anticipate the user makes changes to the notebook source code
-                                # in an interactive session, hence we *pro-actively bump* the version number by setting `revises`
-                                # in the second part of the if condition even though the source code is unchanged at point of running track()
-                                or (
-                                    aux_transform.hash == hash
-                                    and aux_transform.type != "notebook"
-                                )
+                                and aux_transform.created_by_id
+                                == ln_setup.settings.user.id
+                            )
+                            # if the transform source code is unchanged
+                            # if aux_transform.type == "notebook", we anticipate the user makes changes to the notebook source code
+                            # in an interactive session, hence we *pro-actively bump* the version number by setting `revises`
+                            # in the second part of the if condition even though the source code is unchanged at point of running track()
+                            or (
+                                aux_transform.hash == hash
+                                and aux_transform.type != "notebook"
                             )
                         ):
                             uid = aux_transform.uid
                             target_transform = aux_transform
                         else:
                             uid = f"{aux_transform.uid[:-4]}{increment_base62(aux_transform.uid[-4:])}"
-                            message = f"there already is a {aux_transform.type} with `key` '{aux_transform.key}'"
+                            message = f"there already is a {aux_transform.type} with key '{aux_transform.key}'"
                             if (
                                 aux_transform.hash == hash
                                 and aux_transform.type == "notebook"
@@ -564,7 +569,6 @@ class Context:
                             ):
                                 message += f" -- {aux_transform.created_by.handle} already works on this draft"
                             message += f", creating new version '{uid}'"
-                            revises = aux_transform
                         found_key = True
                         break
                 if not found_key:
@@ -585,15 +589,14 @@ class Context:
             if transform is not None:
                 if transform.key not in self._path.as_posix():
                     n_parts = len(Path(transform.key).parts)
-                    last_path_elements = (
+                    (
                         Path(*self._path.parts[-n_parts:]).as_posix()
                         if n_parts > 0
                         else ""
                     )
-                    raise UpdateContext(
-                        get_key_clashing_message(transform, last_path_elements)
-                    )
-                key = transform.key  # type: ignore
+                    key = self._path.name
+                else:
+                    key = transform.key  # type: ignore
             else:
                 key = self._path.name
         if self.version is not None:
@@ -619,27 +622,15 @@ class Context:
         # make a new transform record
         if transform is None:
             assert key is not None  # noqa: S101
-            raise_update_context = False
-            try:
-                transform = Transform(  # type: ignore
-                    uid=self.uid,
-                    version=self.version,
-                    description=description,
-                    key=key,
-                    reference=transform_ref,
-                    reference_type=transform_ref_type,
-                    type=transform_type,
-                ).save()
-            except InconsistentKey:
-                raise_update_context = True
-            if raise_update_context:
-                if revises is None:
-                    revises = (
-                        Transform.filter(uid__startswith=self.uid[:-4], is_latest=True)
-                        .order_by("-created_at")
-                        .first()
-                    )
-                raise UpdateContext(get_key_clashing_message(revises, key))
+            transform = Transform(  # type: ignore
+                uid=self.uid,
+                version=self.version,
+                description=description,
+                key=key,
+                reference=transform_ref,
+                reference_type=transform_ref_type,
+                type=transform_type,
+            ).save()
             self._logging_message_track += f"created Transform('{transform.uid}')"
         else:
             uid = transform.uid
@@ -647,7 +638,11 @@ class Context:
             transform_was_saved = transform.source_code is not None
             # check whether the transform.key is consistent
             if transform.key != key:
-                raise UpdateContext(get_key_clashing_message(transform, key))
+                self._logging_message_track += (
+                    f"renaming transform {transform.key} to {key}"
+                )
+                transform.key = key
+                transform.save()
             elif transform.description != description and description is not None:
                 transform.description = description
                 transform.save()
@@ -659,7 +654,7 @@ class Context:
                 and not transform_was_saved
             ):
                 raise UpdateContext(
-                    f'{transform.created_by.name} ({transform.created_by.handle}) already works on this draft {transform.type}.\n\nPlease create a revision via `ln.track("{uid[:-4]}{increment_base62(uid[-4:])}")` or a new transform with a *different* filedescription and `ln.track("{ids.base62_12()}0000")`.'
+                    f'{transform.created_by.name} ({transform.created_by.handle}) already works on this draft {transform.type}.\n\nPlease create a revision via `ln.track("{uid[:-4]}{increment_base62(uid[-4:])}")` or a new transform with a *different* key and `ln.track("{ids.base62_12()}0000")`.'
                 )
             # check whether transform source code was already saved
             if transform_was_saved:
@@ -752,4 +747,4 @@ class Context:
         self._description = None
 
 
-context = Context()
+context: Context = Context()

lamindb/core/datasets/_small.py

@@ -44,7 +44,7 @@ def small_dataset1(
     # define the dataset-level metadata
     metadata = {
         "temperature": 21.6,
-        "study": "Candidate marker study 1",
+        "experiment": "Experiment 1",
         "date_of_study": "2024-12-01",
         "study_note": "We had a great time performing this study and the results look compelling.",
     }
@@ -78,7 +78,7 @@ def small_dataset2(
     }
     metadata = {
         "temperature": 22.6,
-        "study": "Candidate marker study 2",
+        "experiment": "Experiment 2",
         "date_of_study": "2025-02-13",
     }
     dataset_df = pd.DataFrame(