lamin_cli 1.5.4__tar.gz → 1.6.0__tar.gz

{lamin_cli-1.5.4 → lamin_cli-1.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: lamin_cli
-Version: 1.5.4
+Version: 1.6.0
 Summary: Lamin CLI.
 Author-email: Lamin Labs <open-source@lamin.ai>
 Description-Content-Type: text/markdown

lamin_cli-1.6.0/lamin_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Lamin CLI."""
+
+__version__ = "1.6.0"

{lamin_cli-1.5.4 → lamin_cli-1.6.0}/lamin_cli/__main__.py

@@ -22,6 +22,34 @@ from lamindb_setup._init_instance import (
 if TYPE_CHECKING:
     from collections.abc import Mapping
 
+COMMAND_GROUPS = {
+    "lamin": [
+        {
+            "name": "Manage connections",
+            "commands": ["connect", "info", "init", "disconnect"],
+        },
+        {
+            "name": "Load, save, create & delete data",
+            "commands": ["load", "save", "create", "delete"],
+        },
+        {
+            "name": "Describe, annotate & list data",
+            "commands": ["describe", "annotate", "list"],
+        },
+        {
+            "name": "Configure",
+            "commands": ["checkout", "switch", "cache", "settings", "migrate"],
+        },
+        {
+            "name": "Auth",
+            "commands": [
+                "login",
+                "logout",
+            ],
+        },
+    ]
+}
+
 # https://github.com/ewels/rich-click/issues/19
 # Otherwise rich-click takes over the formatting.
 if os.environ.get("NO_RICH"):
@@ -47,30 +75,6 @@ if os.environ.get("NO_RICH"):
 else:
     import rich_click as click
 
-    COMMAND_GROUPS = {
-        "lamin": [
-            {
-                "name": "Connect to an instance",
-                "commands": ["connect", "disconnect", "info", "init", "run"],
-            },
-            {
-                "name": "Read & write data",
-                "commands": ["load", "save", "get", "delete", "create", "list"],
-            },
-            {
-                "name": "Configure",
-                "commands": ["checkout", "switch", "cache", "settings", "migrate"],
-            },
-            {
-                "name": "Auth",
-                "commands": [
-                    "login",
-                    "logout",
-                ],
-            },
-        ]
-    }
-
     def lamin_group_decorator(f):
         @click.rich_config(
             help_config=click.RichHelpConfiguration(
@@ -104,7 +108,7 @@ except PackageNotFoundError:
 @lamin_group_decorator
 @click.version_option(version=lamindb_version, prog_name="lamindb")
 def main():
-    """Configure LaminDB and perform simple actions."""
+    """Manage data with LaminDB instances."""
     silence_loggers()
 
 
@@ -190,13 +194,10 @@ def connect(instance: str):
     {attr}`~lamindb.setup.core.SetupSettings.auto_connect` to `True` so that you
     auto-connect in a Python session upon importing `lamindb`.
 
-    For manually connecting in a Python session, use {func}`~lamindb.connect`.
+    Alternatively, you can connect in a Python session via {func}`~lamindb.connect`.
     """
-    from lamindb_setup import connect as connect_
-    from lamindb_setup import settings as settings_
-
-    settings_.auto_connect = True
-    return connect_(instance, _reload_lamindb=False, _write_settings=True)
+    from lamindb_setup._connect_instance import _connect_cli
+    return _connect_cli(instance)
 
 
 @main.command()
@@ -263,7 +264,10 @@ def list_(entity: Literal["branch"], name: str | None = None):
 def switch(branch: str | None = None, space: str | None = None):
     """Switch between branches or spaces.
 
-    Currently only supports creating a branch.
+    ```
+    lamin switch --branch my_branch
+    lamin switch --space our_space
+    ```
     """
     from lamindb.setup import switch as switch_
 
@@ -273,7 +277,7 @@ def switch(branch: str | None = None, space: str | None = None):
 @main.command()
 @click.option("--schema", is_flag=True, help="View database schema.")
 def info(schema: bool):
-    """Show info about current instance."""
+    """Show info about the environment, instance, branch, space, and user."""
     if schema:
         from lamindb_setup._schema import view
 
@@ -289,13 +293,14 @@ def info(schema: bool):
 @main.command()
 @click.argument("entity", type=str)
 @click.option("--name", type=str, default=None)
+@click.option("--uid", type=str, default=None)
 @click.option("--slug", type=str, default=None)
 @click.option("--force", is_flag=True, default=False, help="Do not ask for confirmation (only relevant for instance).")
 # fmt: on
-def delete(entity: str, name: str | None = None, slug: str | None = None, force: bool = False):
+def delete(entity: str, name: str | None = None, uid: str | None = None, slug: str | None = None, force: bool = False):
     """Delete an entity.
 
-    Currently supported: `branch` and `instance`.
+    Currently supported: `branch`, `artifact`, and `instance`.
 
     ```
     lamin delete instance --slug account/name
@@ -305,9 +310,15 @@ def delete(entity: str, name: str | None = None, slug: str | None = None, force:
     from lamindb_setup._delete import delete
 
     if entity == "branch":
+        assert name is not None, "You have to pass a name for deleting a branch."
         from lamindb import Branch
 
         Branch.get(name=name).delete()
+    elif entity == "artifact":
+        assert uid is not None, "You have to pass a uid for deleting an artifact."
+        from lamindb import Artifact
+
+        Artifact.get(uid).delete()
     elif entity == "instance":
         return delete(slug, force=force)
     else:  # backwars compatibility
@@ -322,7 +333,7 @@ def delete(entity: str, name: str | None = None, slug: str | None = None, force:
     "--with-env", is_flag=True, help="Also return the environment for a tranform."
 )
 def load(entity: str, uid: str | None = None, key: str | None = None, with_env: bool = False):
-    """Load a file or folder.
+    """Load a file or folder into the cache or working directory.
 
     Pass a URL, `artifact`, or `transform`. For example:
 
@@ -337,30 +348,16 @@ def load(entity: str, uid: str | None = None, key: str | None = None, with_env:
     """
     is_slug = entity.count("/") == 1
     if is_slug:
-        from lamindb_setup import connect
-        from lamindb_setup import settings as settings_
-
-        # can decide whether we want to actually deprecate
-        # click.echo(
-        #     f"! please use: lamin connect {entity}"
-        # )
-        settings_.auto_connect = True
-        return connect(entity, _reload_lamindb=False, _write_settings=True)
+        from lamindb_setup._connect_instance import _connect_cli
+        # for backward compat and convenience, connect to the instance
+        return _connect_cli(entity)
     else:
         from lamin_cli._load import load as load_
 
         return load_(entity, uid=uid, key=key, with_env=with_env)
 
 
-@main.command()
-@click.argument("entity", type=str)
-@click.option("--uid", help="The uid for the entity.")
-@click.option("--key", help="The key for the entity.")
-def get(entity: str, uid: str | None = None, key: str | None = None):
-    """Query metadata about an entity.
-
-    Currently only works for artifact.
-    """
+def _describe(entity: str = "artifact", uid: str | None = None, key: str | None = None):
     import lamindb_setup as ln_setup
 
     from ._load import decompose_url
@@ -383,6 +380,34 @@ def get(entity: str, uid: str | None = None, key: str | None = None):
     artifact.describe()
 
 
+@main.command()
+@click.argument("entity", type=str, default="artifact")
+@click.option("--uid", help="The uid for the entity.")
+@click.option("--key", help="The key for the entity.")
+def describe(entity: str = "artifact", uid: str | None = None, key: str | None = None):
+    """Describe an artifact.
+
+    ```
+    lamin describe --key example_datasets/mini_immuno/dataset1.h5ad
+    lamin describe https://lamin.ai/laminlabs/lamin-site-assets/artifact/6sofuDVvTANB0f48
+    ```
+    """
+    _describe(entity=entity, uid=uid, key=key)
+
+
+@main.command()
+@click.argument("entity", type=str, default="artifact")
+@click.option("--uid", help="The uid for the entity.")
+@click.option("--key", help="The key for the entity.")
+def get(entity: str = "artifact", uid: str | None = None, key: str | None = None):
+    """Query metadata about an entity.
+
+    Currently still equivalent to `lamin describe`.
+    """
+    logger.warning("please use `lamin describe` instead of `lamin get` to describe")
+    _describe(entity=entity, uid=uid, key=key)
+
+
 @main.command()
 @click.argument("path", type=str)
 @click.option("--key", type=str, default=None, help="The key of the artifact or transform.")
@@ -414,6 +439,66 @@ def save(path: str, key: str, description: str, stem_uid: str, project: str, spa
         sys.exit(1)
 
 
+@main.command()
+@click.option("--key", type=str, default=None, help="The key of an artifact or transform.")
+@click.option("--uid", type=str, default=None, help="The uid of an artifact or transform.")
+@click.option("--project", type=str, default=None, help="A valid project name or uid.")
+@click.option("--features", multiple=True, help="Feature annotations. Supports: feature=value, feature=val1,val2, or feature=\"val1\",\"val2\"")
+@click.option("--registry", type=str, default=None, help="Either 'artifact' or 'transform'. If not passed, chooses based on key suffix.")
+def annotate(key: str, uid: str, project: str, registry: str, features: tuple):
+    """Annotate an artifact or a transform.
+
+    You can annotate with projects and valid features & values.
+
+    ```
+    lamin annotate --key raw/sample.fastq --project "My Project"
+    lamin annotate --key raw/sample.fastq --features perturbation=IFNG,DMSO cell_line=HEK297
+    lamin annotate --key my-notebook.ipynb --project "My Project"
+    ```
+    """
+    import lamindb as ln
+
+    from lamin_cli._annotate import _parse_features_list
+    from lamin_cli._save import infer_registry_from_path
+
+    if registry is None:
+        if key is not None:
+            registry = infer_registry_from_path(key)
+        else:
+            registry = "artifact"
+    if registry == "artifact":
+        model = ln.Artifact
+    else:
+        model = ln.Transform
+
+    # Get the artifact
+    if key is not None:
+        artifact = model.get(key=key)
+    elif uid is not None:
+        artifact = model.get(uid=uid)
+    else:
+        raise ln.errors.InvalidArgument("Either --key or --uid must be provided")
+
+    # Handle project annotation
+    if project is not None:
+        project_record = ln.Project.filter(
+            ln.Q(name=project) | ln.Q(uid=project)
+        ).one_or_none()
+        if project_record is None:
+            raise ln.errors.InvalidArgument(
+                f"Project '{project}' not found, either create it with `ln.Project(name='...').save()` or fix typos."
+            )
+        artifact.projects.add(project_record)
+
+    # Handle feature annotations
+    if features:
+        feature_dict = _parse_features_list(features)
+        artifact.features.add_values(feature_dict)
+
+    artifact_rep = artifact.key if artifact.key else artifact.description if artifact.description else artifact.uid
+    logger.important(f"annotated {registry}: {artifact_rep}")
+
+
 @main.command()
 @click.argument("filepath", type=str)
 @click.option("--project", type=str, default=None, help="A valid project name or uid. When running on Modal, creates an app with the same name.", required=True)

lamin_cli-1.6.0/lamin_cli/_annotate.py

@@ -0,0 +1,47 @@
+def _parse_features_list(features_list: tuple) -> dict:
+    """Parse feature list into a dictionary.
+
+    Supports multiple formats:
+    - Quoted values: 'perturbation="DMSO","IFNG"' → {"perturbation": ["DMSO", "IFNG"]}
+    - Unquoted values: 'perturbation=IFNG,DMSO' → {"perturbation": ["IFNG", "DMSO"]}
+    - Single values: 'cell_line=HEK297' → {"cell_line": "HEK297"}
+    - Mixed: ('perturbation="DMSO","IFNG"', 'cell_line=HEK297', 'genes=TP53,BRCA1')
+    """
+    import re
+
+    import lamindb as ln
+
+    feature_dict = {}
+
+    for feature_assignment in features_list:
+        if "=" not in feature_assignment:
+            raise ln.errors.InvalidArgument(
+                f"Invalid feature assignment: '{feature_assignment}'. Expected format: 'feature=value' or 'feature=\"value1\",\"value2\"'"
+            )
+
+        feature_name, values_str = feature_assignment.split("=", 1)
+        feature_name = feature_name.strip()
+
+        # Parse quoted values using regex
+        # This will match quoted strings like "DMSO","IFNG" or single values like HEK297
+        quoted_values = re.findall(r'"([^"]*)"', values_str)
+
+        if quoted_values:
+            # If we found quoted values, use them
+            if len(quoted_values) == 1:
+                feature_dict[feature_name] = quoted_values[0]
+            else:
+                feature_dict[feature_name] = quoted_values
+        else:
+            # If no quoted values, treat as single unquoted value
+            # Remove any surrounding whitespace
+            value = values_str.strip()
+
+            # Handle comma-separated unquoted values
+            if "," in value:
+                values = [v.strip() for v in value.split(",")]
+                feature_dict[feature_name] = values
+            else:
+                feature_dict[feature_name] = value
+
+    return feature_dict

{lamin_cli-1.5.4 → lamin_cli-1.6.0}/lamin_cli/_save.py

@@ -1,15 +1,29 @@
 from __future__ import annotations
 
+import os
 import re
 import sys
+from pathlib import Path
 from typing import TYPE_CHECKING
 
 import click
 from lamin_utils import logger
 from lamindb_setup.core.hashing import hash_file
 
-if TYPE_CHECKING:
-    from pathlib import Path
+
+def infer_registry_from_path(path: Path | str) -> str:
+    suffixes_transform = {
+        "py": {".py", ".ipynb"},
+        "R": {".R", ".qmd", ".Rmd"},
+    }
+    if isinstance(path, str):
+        path = Path(path)
+    registry = (
+        "transform"
+        if path.suffix in suffixes_transform["py"].union(suffixes_transform["R"])
+        else "artifact"
+    )
+    return registry
 
 
 def parse_uid_from_code(content: str, suffix: str) -> str | None:
@@ -82,15 +96,7 @@ def save_from_path_cli(
         raise click.BadParameter(f"Path {path} does not exist", param_hint="path")
 
     if registry is None:
-        suffixes_transform = {
-            "py": {".py", ".ipynb"},
-            "R": {".R", ".qmd", ".Rmd"},
-        }
-        registry = (
-            "transform"
-            if path.suffix in suffixes_transform["py"].union(suffixes_transform["R"])
-            else "artifact"
-        )
+        registry = infer_registry_from_path(path)
 
     if project is not None:
         project_record = ln.Project.filter(
@@ -145,7 +151,7 @@ def save_from_path_cli(
         artifact.save()
         logger.important(f"saved: {artifact}")
         logger.important(f"storage path: {artifact.path}")
-        if ln_setup.settings.storage.type == "s3":
+        if artifact.storage.type == "s3":
             logger.important(f"storage url: {artifact.path.to_url()}")
         if project is not None:
             artifact.projects.add(project_record)
@@ -256,11 +262,14 @@ def save_from_path_cli(
         # latest run of this transform by user
         run = ln.Run.filter(transform=transform).order_by("-started_at").first()
         if run is not None and run.created_by.id != ln_setup.settings.user.id:
-            response = input(
-                "You are trying to save a transform created by another user: Source"
-                " and report files will be tagged with *your* user id. Proceed?"
-                " (y/n)"
-            )
+            if os.environ.get("LAMIN_TESTING") == "true":
+                response = "y"
+            else:
+                response = input(
+                    "You are trying to save a transform created by another user: Source"
+                    " and report files will be tagged with *your* user id. Proceed?"
+                    " (y/n)"
+                )
             if response != "y":
                 return "aborted-save-notebook-created-by-different-user"
         if run is None and transform.key.endswith(".ipynb"):

lamin_cli-1.5.4/tests/core/test_save_files.py → lamin_cli-1.6.0/tests/core/test_save_annotate_files.py

@@ -1,3 +1,4 @@
+import re
 import subprocess
 from pathlib import Path
 
@@ -7,7 +8,7 @@ import lamindb_setup as ln_setup
 test_file = Path(__file__).parent.parent.parent.resolve() / ".gitignore"
 
 
-def test_save_local_file():
+def test_save_and_annotate_local_file():
     filepath = test_file
 
     # neither key nor description
@@ -71,6 +72,46 @@ def test_save_local_file():
     )
     assert result.returncode == 1
 
+    result = subprocess.run(
+        f"lamin save {filepath} --key mytest --registry artifact",
+        shell=True,
+        capture_output=True,
+    )
+    print(result.stdout.decode())
+    print(result.stderr.decode())
+    assert "returning existing artifact with same hash" in result.stdout.decode()
+    assert "key='mytest'" in result.stdout.decode()
+    assert "storage path:" in result.stdout.decode()
+    assert result.returncode == 0
+
+    artifact.projects.remove(project)
+
+    ml_split_type = ln.ULabel(name="Perturbation", is_type=True).save()
+    ln.ULabel(name="DMSO", type=ml_split_type).save()
+    ln.ULabel(name="IFNG", type=ml_split_type).save()
+    ln.Feature(name="perturbation", dtype=ml_split_type).save()
+
+    result = subprocess.run(
+        "lamin annotate --key mytest --project test_project --features perturbation=DMSO,IFNG",
+        shell=True,
+        capture_output=True,
+    )
+    print(result.stdout.decode())
+    print(result.stderr.decode())
+    assert result.returncode == 0
+
+    artifact = ln.Artifact.get(key="mytest")
+    features = artifact.features.get_values()
+    assert features["perturbation"] == {"DMSO", "IFNG"}
+    assert project in artifact.projects.all()
+
+    result = subprocess.run(
+        "lamin describe --key mytest",
+        shell=True,
+        capture_output=True,
+    )
+    assert result.returncode == 0
+
 
 def test_save_cloud_file():
     # should be no key for cloud paths

lamin_cli-1.5.4/tests/core/test_save_scripts.py → lamin_cli-1.6.0/tests/core/test_save_annotate_scripts.py

@@ -1,4 +1,5 @@
 import os
+import re
 import subprocess
 from pathlib import Path
 
@@ -29,7 +30,7 @@ def test_save_resave_script_no_uids():
     assert ln.Transform.filter(key=filepath.name).count() == 2
 
 
-def test_save_without_uid():
+def test_save_and_annotate_without_uid():
     env = os.environ
     env["LAMIN_TESTING"] = "true"
     filepath = scripts_dir / "run-track-and-finish.py"
@@ -47,6 +48,15 @@ def test_save_without_uid():
     assert "created Transform" in result.stdout.decode()
     assert "labeled with project: test_project" in result.stdout.decode()
 
+    result = subprocess.run(
+        "lamin annotate --key run-track-and-finish.py --project test_project",
+        shell=True,
+        capture_output=True,
+    )
+    print(result.stdout.decode())
+    print(result.stderr.decode())
+    assert result.returncode == 0
+
 
 def test_run_save_cache_with_git_and_uid():
     env = os.environ

{lamin_cli-1.5.4 → lamin_cli-1.6.0}/tests/core/test_save_notebooks.py

@@ -35,7 +35,7 @@ def test_save_non_consecutive():
     transform = ln.Transform(
         uid="HDMGkxN9rgFA0000",
         version="1",
-        name="My test notebook (non-consecutive)",
+        key="My test notebook (non-consecutive)",
         type="notebook",
     ).save()
     ln.Run(transform=transform).save()

{lamin_cli-1.5.4 → lamin_cli-1.6.0}/tests/core/test_save_r_code.py

@@ -13,7 +13,7 @@ def test_run_save_cache():
     filepath = scripts_dir / "run-track.R"
 
     transform = ln.Transform(
-        uid="EPnfDtJz8qbE0000", name="run-track.R", key="run-track.R", type="script"
+        uid="EPnfDtJz8qbE0000", key="run-track.R", type="script"
     ).save()
     ln.Run(transform=transform).save()
 
@@ -38,7 +38,6 @@ def test_run_save_cache():
 
     transform = ln.Transform(
         uid="HPnfDtJz8qbE0000",
-        name="run-track.qmd",
         key="run-track.qmd",
         type="notebook",
     ).save()

lamin_cli-1.5.4/lamin_cli/__init__.py

@@ -1,3 +0,0 @@
-"""Lamin CLI."""
-
-__version__ = "1.5.4"