lamindb 0.77.2__py3-none-any.whl → 1.0rc1__py3-none-any.whl

lamindb/core/_context.py

@@ -2,35 +2,39 @@ from __future__ import annotations
 
 import builtins
 import hashlib
+import signal
+import sys
+import threading
+import traceback
 from datetime import datetime, timezone
-from pathlib import Path, PurePath
+from pathlib import Path
 from typing import TYPE_CHECKING
 
 import lamindb_setup as ln_setup
+from django.db.models import Func, IntegerField
 from lamin_utils import logger
 from lamindb_setup.core.hashing import hash_file
-from lnschema_core import Run, Transform, ids
-from lnschema_core.ids import base62_12
-from lnschema_core.models import format_field_value
+
+from lamindb.base import ids
+from lamindb.base.ids import base62_12
+from lamindb.models import Run, Transform, format_field_value
 
 from ._settings import settings
 from ._sync_git import get_transform_reference_from_git_repo
 from ._track_environment import track_environment
 from .exceptions import (
     InconsistentKey,
-    MissingContextUID,
     NotebookNotSaved,
-    NoTitleError,
     TrackNotCalled,
     UpdateContext,
 )
-from .subsettings._transform_settings import transform_settings
 from .versioning import bump_version as bump_version_function
 from .versioning import increment_base62, message_update_key_in_version_family
 
 if TYPE_CHECKING:
     from lamindb_setup.core.types import UPathStr
-    from lnschema_core.types import TransformType
+
+    from lamindb.base.types import TransformType
 
 is_run_from_ipython = getattr(builtins, "__IPYTHON__", False)
 
@@ -46,7 +50,7 @@ def get_uid_ext(version: str) -> str:
     return encodebytes(hashlib.md5(version.encode()).digest())[:4]  # noqa: S324
 
 
-def get_notebook_path():
+def get_notebook_path() -> Path:
     from nbproject.dev._jupyter_communicate import (
         notebook_path as get_notebook_path,
     )
@@ -58,50 +62,25 @@ def get_notebook_path():
         raise RuntimeError(msg_path_failed) from None
     if path is None:
         raise RuntimeError(msg_path_failed) from None
-    return path
+    return Path(path)
 
 
 # from https://stackoverflow.com/questions/61901628
-def get_notebook_name_colab() -> str:
+def get_notebook_key_colab() -> str:
     from socket import gethostbyname, gethostname  # type: ignore
 
     from requests import get  # type: ignore
 
     ip = gethostbyname(gethostname())  # 172.28.0.12
     try:
-        name = get(f"http://{ip}:9000/api/sessions").json()[0]["name"]  # noqa: S113
+        key = get(f"http://{ip}:9000/api/sessions").json()[0]["name"]  # noqa: S113
+        key = f"colab/{key}"
     except Exception:
         logger.warning(
-            "could not get notebook name from Google Colab, using: notebook.ipynb"
-        )
-        name = "notebook.ipynb"
-    return name.rstrip(".ipynb")
-
-
-def raise_missing_context(transform_type: str, key: str) -> bool:
-    transform = Transform.filter(key=key).latest_version().first()
-    if transform is None:
-        new_uid = f"{base62_12()}0000"
-        message = f'to track this {transform_type}, run: ln.track("{new_uid}")'
-    else:
-        uid = transform.uid
-        new_uid = f"{uid[:-4]}{increment_base62(uid[-4:])}"
-        message = (
-            f"you already have a transform with key '{key}': Transform('{transform.uid[:8]}')\n"
-            f'  (1) to make a revision, run: ln.track("{new_uid}")\n  (2) to create a new transform, rename your {transform_type} file and re-run: ln.track()'
+            "could not get notebook key from Google Colab, using: colab/notebook.ipynb"
         )
-    if is_run_from_ipython:
-        print(f"→ {message}")
-        response = input("→ Ready to re-run? (y/n)")
-        if response == "y":
-            logger.important(
-                "note: restart your notebook if you want consecutive cell execution"
-            )
-            return True
-        raise MissingContextUID("Please follow the instructions.")
-    else:
-        raise MissingContextUID(f"✗ {message}")
-    return False
+        key = "colab/notebook.ipynb"
+    return key
 
 
 def pretty_pypackages(dependencies: dict) -> str:
@@ -115,6 +94,83 @@ def pretty_pypackages(dependencies: dict) -> str:
     return " ".join(deps_list)
 
 
+class LogStreamHandler:
+    def __init__(self, log_stream, file):
+        self.log_stream = log_stream
+        self.file = file
+
+    def write(self, data):
+        self.log_stream.write(data)
+        self.file.write(data)
+        self.file.flush()
+
+    def flush(self):
+        self.log_stream.flush()
+        self.file.flush()
+
+
+class LogStreamTracker:
+    def __init__(self):
+        self.original_stdout = None
+        self.original_stderr = None
+        self.log_file = None
+        self.original_excepthook = sys.excepthook
+        self.is_cleaning_up = False
+
+    def start(self, run: Run):
+        self.original_stdout = sys.stdout
+        self.original_stderr = sys.stderr
+        self.run = run
+        self.log_file_path = (
+            ln_setup.settings.cache_dir / f"run_logs_{self.run.uid}.txt"
+        )
+        self.log_file = open(self.log_file_path, "w")
+        sys.stdout = LogStreamHandler(self.original_stdout, self.log_file)
+        sys.stderr = LogStreamHandler(self.original_stderr, self.log_file)
+        # handle signals
+        # signal should be used only in the main thread, otherwise
+        # ValueError: signal only works in main thread of the main interpreter
+        if threading.current_thread() == threading.main_thread():
+            signal.signal(signal.SIGTERM, self.cleanup)
+            signal.signal(signal.SIGINT, self.cleanup)
+        # handle exceptions
+        sys.excepthook = self.handle_exception
+
+    def finish(self):
+        if self.original_stdout:
+            sys.stdout = self.original_stdout
+            sys.stderr = self.original_stderr
+            self.log_file.close()
+
+    def cleanup(self, signo=None, frame=None):
+        from lamindb._finish import save_run_logs
+
+        if self.original_stdout and not self.is_cleaning_up:
+            self.is_cleaning_up = True
+            if signo is not None:
+                signal_msg = f"\nProcess terminated by signal {signo} ({signal.Signals(signo).name})\n"
+                if frame:
+                    signal_msg += (
+                        f"Frame info:\n{''.join(traceback.format_stack(frame))}"
+                    )
+                self.log_file.write(signal_msg)
+            sys.stdout = self.original_stdout
+            sys.stderr = self.original_stderr
+            self.log_file.flush()
+            self.log_file.close()
+            save_run_logs(self.run, save_run=True)
+
+    def handle_exception(self, exc_type, exc_value, exc_traceback):
+        if not self.is_cleaning_up:
+            error_msg = f"{''.join(traceback.format_exception(exc_type, exc_value, exc_traceback))}"
+            if self.log_file.closed:
+                self.log_file = open(self.log_file_path, "a")
+            self.log_file.write(error_msg)
+            self.log_file.flush()
+            self.cleanup()
+        self.original_excepthook(exc_type, exc_value, exc_traceback)
+
+
 class Context:
     """Run context.
 
@@ -136,7 +192,7 @@ class Context:
 
     def __init__(self):
         self._uid: str | None = None
-        self._name: str | None = None
+        self._description: str | None = None
         self._version: str | None = None
         self._transform: Transform | None = None
         self._run: Run | None = None
@@ -144,6 +200,7 @@ class Context:
         """A local path to the script that's running."""
         self._logging_message_track: str = ""
         self._logging_message_imports: str = ""
+        self._stream_tracker: LogStreamTracker = LogStreamTracker()
 
     @property
     def transform(self) -> Transform | None:
@@ -151,22 +208,31 @@ class Context:
         return self._transform
 
     @property
-    def uid(self) -> str | None:
-        """`uid` argument for `context.transform`."""
-        return self._uid
+    def description(self) -> str | None:
+        """`description` argument for `context.transform`."""
+        return self._description
 
-    @uid.setter
-    def uid(self, value: str | None):
-        self._uid = value
+    @description.setter
+    def description(self, value: str | None):
+        self._description = value
 
     @property
     def name(self) -> str | None:
-        """`name argument for `context.transform`."""
-        return self._name
+        """Deprecated. Populates `description` argument for `context.transform`."""
+        return self._description
 
     @name.setter
     def name(self, value: str | None):
-        self._name = value
+        self._description = value
+
+    @property
+    def uid(self) -> str | None:
+        """`uid` argument for `context.transform`."""
+        return self._uid
+
+    @uid.setter
+    def uid(self, value: str | None):
+        self._uid = value
 
     @property
     def version(self) -> str | None:
@@ -189,13 +255,14 @@ class Context:
         params: dict | None = None,
         new_run: bool | None = None,
         path: str | None = None,
+        log_to_file: bool | None = None,
     ) -> None:
         """Initiate a run with tracked data lineage.
 
         - sets :attr:`~lamindb.core.Context.transform` &
           :attr:`~lamindb.core.Context.run` by creating or loading `Transform` &
           `Run` records
-        - saves compute environment as a `requirements.txt` file: `run.environment`
+        - saves Python environment as a `requirements.txt` file: `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.
@@ -203,110 +270,49 @@ class Context:
         Args:
             transform: A transform `uid` or record. If `None`, creates a `uid`.
             params: A dictionary of parameters to track for the run.
-            new_run: If `False`, loads latest run of transform
-                (default notebook), if `True`, creates new run (default pipeline).
+            new_run: If `False`, loads the latest run of transform
+                (default notebook), if `True`, creates new run (default non-notebook).
             path: Filepath of notebook or script. Only needed if it can't be
                 automatically detected.
+            log_to_file: If `True`, logs stdout and stderr to a file and
+                saves the file within the current run (default non-notebook),
+                if `False`, does not log the output (default notebook).
 
         Examples:
 
-            To create a transform `uid` for tracking a script or notebook, call:
-
-            >>> ln.track()
-
             To track the run of a notebook or script, call:
 
-            >>> ln.track("FPnfDtJz8qbE0000")  # replace with your uid
+            >>> ln.track()
 
         """
         self._logging_message_track = ""
         self._logging_message_imports = ""
-        uid = None
         if transform is not None and isinstance(transform, str):
-            uid = transform
-            self.uid = uid
+            self.uid = transform
             transform = None
         self._path = None
         if transform is None:
-            is_tracked = False
-            transform_settings_are_set = (
-                transform_settings.stem_uid is not None
-                and transform_settings.version is not None
-            )
-            transform = None
-            stem_uid = None
-            # you can set ln.context.uid and then call ln.track() without passing anythin
-            # that has been the preferred syntax for a while; we'll likely
-            # deprecate it at some point
-            if uid is not None or self.uid is not None:
-                transform = Transform.filter(uid=self.uid).one_or_none()
-                if self.version is not None:
-                    # test inconsistent version passed
-                    if (
-                        transform is not None
-                        and transform.version is not None  # type: ignore
-                        and self.version != transform.version  # type: ignore
-                    ):
-                        raise SystemExit(
-                            f"Please pass consistent version: ln.context.version = '{transform.version}'"  # type: ignore
-                        )
-                    # test whether version was already used for another member of the family
-                    suid, vuid = (
-                        self.uid[: Transform._len_stem_uid],
-                        self.uid[Transform._len_stem_uid :],
-                    )
-                    transform = Transform.filter(
-                        uid__startswith=suid, version=self.version
-                    ).one_or_none()
-                    if (
-                        transform is not None
-                        and vuid != transform.uid[Transform._len_stem_uid :]
-                    ):
-                        better_version = bump_version_function(self.version)
-                        raise SystemExit(
-                            f"Version '{self.version}' is already taken by Transform(uid='{transform.uid}'); please set another version, e.g., ln.context.version = '{better_version}'"
-                        )
-            elif transform_settings_are_set:
-                stem_uid, self.version = (
-                    transform_settings.stem_uid,
-                    transform_settings.version,
-                )
-                transform = Transform.filter(
-                    uid__startswith=stem_uid, version=self.version
-                ).one_or_none()
+            description = None
             if is_run_from_ipython:
-                key, name = self._track_notebook(path=path)
+                self._path, description = self._track_notebook(path_str=path)
                 transform_type = "notebook"
                 transform_ref = None
                 transform_ref_type = None
             else:
-                # the below function is typically used for `.py` scripts
-                # it is also used for `.Rmd` and `.qmd` files, which we classify
-                # as "notebook" because they typically come with an .html run report
-                (name, key, transform_type, transform_ref, transform_ref_type) = (
-                    self._track_source_code(path=path)
-                )
-            if self.uid is not None or transform_settings_are_set:
-                # overwrite whatever is auto-detected in the notebook or script
-                if self.name is not None:
-                    name = self.name
-                self._create_or_load_transform(
-                    uid=self.uid,
-                    stem_uid=stem_uid,
-                    version=self.version,
-                    name=name,
-                    transform_ref=transform_ref,
-                    transform_ref_type=transform_ref_type,
-                    transform_type=transform_type,
-                    key=key,
-                    transform=transform,
-                )
-                # if no error is raised, the transform is tracked
-                is_tracked = True
-            if not is_tracked:
-                early_return = raise_missing_context(transform_type, key)
-                if early_return:
-                    return None
+                (
+                    self._path,
+                    transform_type,
+                    transform_ref,
+                    transform_ref_type,
+                ) = self._track_source_code(path=path)
+            if description is None:
+                description = self._description
+            self._create_or_load_transform(
+                description=description,
+                transform_ref=transform_ref,
+                transform_ref_type=transform_ref_type,
+                transform_type=transform_type,
+            )
         else:
             if transform.type in {"notebook", "script"}:
                 raise ValueError(
@@ -319,14 +325,10 @@ class Context:
                 transform_exists = Transform.filter(id=transform.id).first()
             if transform_exists is None:
                 transform.save()
-                self._logging_message_track += (
-                    f"created Transform('{transform.uid[:8]}')"
-                )
+                self._logging_message_track += f"created Transform('{transform.uid}')"
                 transform_exists = transform
             else:
-                self._logging_message_track += (
-                    f"loaded Transform('{transform.uid[:8]}')"
-                )
+                self._logging_message_track += f"loaded Transform('{transform.uid}')"
             self._transform = transform_exists
 
         if new_run is None:  # for notebooks, default to loading latest runs
@@ -343,7 +345,7 @@ class Context:
             )
             if run is not None:  # loaded latest run
                 run.started_at = datetime.now(timezone.utc)  # update run time
-                self._logging_message_track += f", re-started Run('{run.uid[:8]}') at {format_field_value(run.started_at)}"
+                self._logging_message_track += f", re-started Run('{run.uid[:8]}...') at {format_field_value(run.started_at)}"
 
         if run is None:  # create new run
             run = Run(
@@ -351,7 +353,7 @@ class Context:
                 params=params,
             )
             run.started_at = datetime.now(timezone.utc)
-            self._logging_message_track += f", started new Run('{run.uid[:8]}') at {format_field_value(run.started_at)}"
+            self._logging_message_track += f", started new Run('{run.uid[:8]}...') at {format_field_value(run.started_at)}"
         # can only determine at ln.finish() if run was consecutive in
         # interactive session, otherwise, is consecutive
         run.is_consecutive = True if is_run_from_ipython else None
@@ -359,11 +361,15 @@ class Context:
         run.save()
         if params is not None:
             run.params.add_values(params)
-            self._logging_message_track += "\n→ params: " + " ".join(
-                f"{key}='{value}'" for key, value in params.items()
+            self._logging_message_track += "\n→ params: " + ", ".join(
+                f"{key}={value}" for key, value in params.items()
             )
         self._run = run
         track_environment(run)
+        if log_to_file is None:
+            log_to_file = self.transform.type != "notebook"
+        if log_to_file:
+            self._stream_tracker.start(run)
         logger.important(self._logging_message_track)
         if self._logging_message_imports:
             logger.important(self._logging_message_imports)
@@ -372,61 +378,59 @@ class Context:
         self,
         *,
         path: UPathStr | None,
-    ) -> tuple[str, str, str, str, str]:
+    ) -> tuple[Path, str, str, str]:
+        # for `.py` files, classified as "script"
+        # for `.Rmd` and `.qmd` files, which we classify
+        # as "notebook" because they typically come with an .html run report
         if path is None:
             import inspect
 
             frame = inspect.stack()[2]
             module = inspect.getmodule(frame[0])
-            self._path = Path(module.__file__)
+            # None for interactive session
+            if module is None:
+                raise NotImplementedError(
+                    "Interactive sessions are not yet supported to be tracked."
+                )
+            path = Path(module.__file__)
         else:
-            self._path = Path(path)
-        transform_type = (
-            "notebook" if self._path.suffix in {".Rmd", ".qmd"} else "script"
-        )
-        name = self._path.name
-        key = name
+            path = Path(path)
+        transform_type = "notebook" if path.suffix in {".Rmd", ".qmd"} else "script"
         reference = None
         reference_type = None
         if settings.sync_git_repo is not None:
-            reference = get_transform_reference_from_git_repo(self._path)
+            reference = get_transform_reference_from_git_repo(path)
             reference_type = "url"
-        return name, key, transform_type, reference, reference_type
+        return path, transform_type, reference, reference_type
 
     def _track_notebook(
         self,
         *,
-        path: str | None,
-    ):
-        if path is None:
+        path_str: str | None,
+    ) -> tuple[Path, str | None]:
+        if path_str is None:
             path = get_notebook_path()
-        key = Path(path).name
-        if isinstance(path, (Path, PurePath)):
-            path_str = path.as_posix()  # type: ignore
         else:
-            path_str = str(path)
+            path = Path(path_str)
+        description = None
+        path_str = path.as_posix()
         if path_str.endswith("Untitled.ipynb"):
             raise RuntimeError("Please rename your notebook before tracking it")
         if path_str.startswith("/fileId="):
-            name = get_notebook_name_colab()
-            key = f"{name}.ipynb"
+            logger.warning("tracking on Google Colab is experimental")
+            path_str = get_notebook_key_colab()
+            path = Path(path_str)
         else:
             import nbproject
 
             try:
                 nbproject_title = nbproject.meta.live.title
             except IndexError:
-                raise NotebookNotSaved(
-                    "The notebook is not saved, please save the notebook and"
-                    " rerun ``"
-                ) from None
-            if nbproject_title is None:
-                raise NoTitleError(
-                    "Please add a title to your notebook in a markdown cell: # Title"
-                ) from None
-            name = nbproject_title
-        # log imported python packages
-        if not path_str.startswith("/fileId="):
+                # notebook is not saved
+                pass
+            if nbproject_title is not None:
+                description = nbproject_title
+            # log imported python packages
             try:
                 from nbproject.dev._pypackage import infer_pypackages
 
@@ -438,21 +442,15 @@ class Context:
             except Exception:
                 logger.debug("inferring imported packages failed")
                 pass
-        self._path = Path(path_str)
-        return key, name
+        return path, description
 
     def _create_or_load_transform(
         self,
         *,
-        uid: str | None,
-        stem_uid: str | None,
-        version: str | None,
-        name: str,
+        description: str,
         transform_ref: str | None = None,
         transform_ref_type: str | None = None,
-        key: str | None = None,
         transform_type: TransformType = None,
-        transform: Transform | None = None,
     ):
         def get_key_clashing_message(transform: Transform, key: str) -> str:
             update_key_note = message_update_key_in_version_family(
@@ -462,63 +460,139 @@ class Context:
                 registry="Transform",
             )
             return (
-                f'Filename "{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'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:
+
+            class SlashCount(Func):
+                template = "LENGTH(%(expressions)s) - LENGTH(REPLACE(%(expressions)s, '/', ''))"
+                output_field = IntegerField()
+
+            # we need to traverse from greater depth to shorter depth so that we match better matches first
+            transforms = (
+                Transform.filter(key__endswith=self._path.name, is_latest=True)
+                .annotate(slash_count=SlashCount("key"))
+                .order_by("-slash_count")
+            )
+            uid = f"{base62_12()}0000"
+            key = self._path.name
+            target_transform = None
+            hash, _ = hash_file(self._path)
+            if len(transforms) != 0:
+                message = ""
+                found_key = False
+                for aux_transform in transforms:
+                    if aux_transform.key in self._path.as_posix():
+                        key = aux_transform.key
+                        if (
+                            aux_transform.source_code is None
+                            or aux_transform.hash == hash
+                        ):
+                            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 transform with key '{aux_transform.key}', creating new version '{uid}'"
+                            revises = aux_transform
+                        found_key = True
+                        break
+                if not found_key:
+                    plural_s = "s" if len(transforms) > 1 else ""
+                    transforms_str = "\n".join(
+                        [
+                            f"    {transform.uid} → {transform.key}"
+                            for transform in transforms
+                        ]
+                    )
+                    message = f"ignoring transform{plural_s} with same filedescription:\n{transforms_str}"
+                if message != "":
+                    logger.important(message)
+            self.uid, transform = uid, target_transform
+        # the user did pass the uid
+        else:
+            transform = Transform.filter(uid=self.uid).one_or_none()
+            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
+            else:
+                key = self._path.name
+        if self.version is not None:
+            # test inconsistent version passed
+            if (
+                transform is not None
+                and transform.version is not None  # type: ignore
+                and self.version != transform.version  # type: ignore
+            ):
+                raise SystemExit(
+                    f"✗ please pass consistent version: ln.context.version = '{transform.version}'"  # type: ignore
+                )
+            # test whether version was already used for another member of the family
+            suid, vuid = (self.uid[:-4], self.uid[-4:])
+            transform = Transform.filter(
+                uid__startswith=suid, version=self.version
+            ).one_or_none()
+            if transform is not None and vuid != transform.uid[-4:]:
+                better_version = bump_version_function(self.version)
+                raise SystemExit(
+                    f"✗ version '{self.version}' is already taken by Transform('{transform.uid}'); please set another version, e.g., ln.context.version = '{better_version}'"
+                )
         # make a new transform record
         if transform is None:
-            if uid is None:
-                uid = f"{stem_uid}{get_uid_ext(version)}"
-            # let's query revises so that we can pass it to the constructor and use it for error handling
-            revises = (
-                Transform.filter(uid__startswith=uid[:-4], is_latest=True)
-                .order_by("-created_at")
-                .first()
-            )
-            # note that here we're not passing revises because we're not querying it
-            # hence, we need to do a revision family lookup based on key
-            # hence, we need key to be not None
             assert key is not None  # noqa: S101
             raise_update_context = False
             try:
                 transform = Transform(
-                    uid=uid,
-                    version=version,
-                    name=name,
+                    uid=self.uid,
+                    version=self.version,
+                    description=description,
                     key=key,
                     reference=transform_ref,
                     reference_type=transform_ref_type,
                     type=transform_type,
-                    revises=revises,
                 ).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))
-            self._logging_message_track += f"created Transform('{transform.uid[:8]}')"
+            self._logging_message_track += f"created Transform('{transform.uid}')"
         else:
             uid = transform.uid
             # transform was already saved via `finish()`
-            transform_was_saved = (
-                transform._source_code_artifact_id is not None
-                or transform.source_code is not None
-            )
+            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))
-            elif transform.name != name:
-                transform.name = name
+            elif transform.description != description:
+                transform.description = description
                 transform.save()
                 self._logging_message_track += (
-                    "updated transform name, "  # white space on purpose
+                    "updated transform description, "  # white space on purpose
                 )
             elif (
                 transform.created_by_id != ln_setup.settings.user.id
                 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* filename and `ln.track("{ids.base62_12()}0000")`.'
+                    f'{transform.created_by.description} ({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")`.'
                 )
             # check whether transform source code was already saved
             if transform_was_saved:
@@ -527,30 +601,23 @@ class Context:
                     bump_revision = True
                 else:
                     hash, _ = hash_file(self._path)  # ignore hash_type for now
-                    if transform.hash is not None:
-                        condition = hash != transform.hash
-                    else:
-                        condition = hash != transform._source_code_artifact.hash
-                    if condition:
+                    if hash != transform.hash:
                         bump_revision = True
                     else:
                         self._logging_message_track += (
-                            f"loaded Transform('{transform.uid[:8]}')"
+                            f"loaded Transform('{transform.uid}')"
                         )
                 if bump_revision:
                     change_type = (
-                        "Re-running saved notebook"
+                        "re-running saved notebook"
                         if is_run_from_ipython
-                        else "Source code changed"
+                        else "source code changed"
                     )
                     raise UpdateContext(
-                        f"{change_type}, bump revision by setting:\n\n"
-                        f'ln.track("{uid[:-4]}{increment_base62(uid[-4:])}")'
+                        f'✗ {change_type}, run: ln.track("{uid[:-4]}{increment_base62(uid[-4:])}")'
                     )
             else:
-                self._logging_message_track += (
-                    f"loaded Transform('{transform.uid[:8]}')"
-                )
+                self._logging_message_track += f"loaded Transform('{transform.uid}')"
         self._transform = transform
 
     def finish(self, ignore_non_consecutive: None | bool = None) -> None:
@@ -580,8 +647,8 @@ class Context:
 
         """
         from lamindb._finish import (
+            get_save_notebook_message,
             get_seconds_since_modified,
-            get_shortcut,
             save_context_core,
         )
 
@@ -600,13 +667,13 @@ class Context:
             import nbproject
 
             # it might be that the user modifies the title just before ln.finish()
-            if (nbproject_title := nbproject.meta.live.title) != self.transform.name:
-                self.transform.name = nbproject_title
+            if (
+                nbproject_title := nbproject.meta.live.title
+            ) != self.transform.description:
+                self.transform.description = nbproject_title
                 self.transform.save()
             if get_seconds_since_modified(self._path) > 2 and not ln_setup._TESTING:
-                raise NotebookNotSaved(
-                    f"Please save the notebook in your editor (shortcut `{get_shortcut()}`) within 2 sec before calling `ln.finish()`"
-                )
+                raise NotebookNotSaved(get_save_notebook_message())
         save_context_core(
             run=self.run,
             transform=self.run.transform,
@@ -614,6 +681,8 @@ class Context:
             finished_at=True,
             ignore_non_consecutive=ignore_non_consecutive,
         )
+        if self.transform.type != "notebook":
+            self._stream_tracker.finish()
 
 
 context = Context()