🎨 Add path properties & storage field on Dataset (#303)

* 🎨 Add path properties

* ♻️ Fix

lnschema_core/migrations/0021_dataset_storage_alter_dataset_file.py

@@ -0,0 +1,23 @@
+# Generated by Django 4.2.2 on 2023-10-04 01:44
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("lnschema_core", "0020_run_report_transform_latest_report_and_more"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="dataset",
+            name="storage",
+            field=models.ForeignKey(null=True, on_delete=django.db.models.deletion.PROTECT, related_name="datasets", to="lnschema_core.storage"),
+        ),
+        migrations.AlterField(
+            model_name="dataset",
+            name="file",
+            field=models.OneToOneField(null=True, on_delete=django.db.models.deletion.PROTECT, related_name="dataset", to="lnschema_core.file"),
+        ),
+    ]

lnschema_core/models.py

@@ -652,6 +652,26 @@ def __init__(
     ):
         super(Storage, self).__init__(*args, **kwargs)
 
+    @property
+    def path(self) -> Union[Path, UPath]:
+        """Bucket or folder path (`Path`, `UPath`).
+
+        Examples:
+
+            Cloud storage bucket:
+
+            >>> ln.Storage("s3://my-bucket").save()
+
+            Directory/folder in cloud storage:
+
+            >>> ln.Storage("s3://my-bucket/my-directory").save()
+
+            Local directory/folder:
+
+            >>> ln.Storage("./my-directory").save()
+        """
+        pass
+
 
 class Transform(Registry, HasParents):
     """Transforms of files & datasets.
@@ -820,6 +840,8 @@ class Run(Registry):
     """Time of run execution."""
     created_by = models.ForeignKey(User, CASCADE, default=current_user_id, related_name="created_runs")
     """Creator of record, a :class:`~lamindb.User`."""
+    # we don't want to make below a OneToOne because there could be the same trivial report
+    # generated for many different runs
     report = models.ForeignKey("File", PROTECT, default=None, null=True, related_name="report_of")
     """Report of run, e.g., an html file."""
     is_consecutive = models.BooleanField(null=True, default=None)
@@ -1870,10 +1892,14 @@ class Dataset(Registry, Data):
     """:class:`~lamindb.Run` that created the `file`."""
     input_of = models.ManyToManyField(Run, related_name="input_datasets")
     """Runs that use this dataset as an input."""
-    file = models.ForeignKey("File", on_delete=PROTECT, null=True, unique=True, related_name="datasets")
+    file = models.OneToOneField("File", on_delete=PROTECT, null=True, unique=True, related_name="dataset")
     """Storage of dataset as a one file."""
     files = models.ManyToManyField("File", related_name="datasets")
     """Storage of dataset as multiple file."""
+    # below shouldn't be a OneToOne because different states of the same storage location might represent
+    # different datasets
+    storage = models.ForeignKey(Storage, on_delete=PROTECT, null=True, related_name="datasets")
+    """Storage of dataset as mere paths handled by a key value store or file system."""
     initial_version = models.ForeignKey("self", PROTECT, null=True, default=None)
     """Initial version of the dataset, a :class:`~lamindb.Dataset` object."""
     created_at = models.DateTimeField(auto_now_add=True, db_index=True)
@@ -1908,6 +1934,28 @@ def __init__(
     ):
         pass
 
+    @property
+    def path(self) -> Optional[Union[Path, UPath]]:
+        """None or bucket or folder path (`Path`, `UPath`).
+
+        Only relevant for datasets that merely reference to a bucket or folder.
+
+        Examples:
+
+            Cloud storage bucket:
+
+            >>> ln.Storage("s3://my-bucket").save()
+
+            Directory/folder in cloud storage:
+
+            >>> ln.Storage("s3://my-bucket/my-directory").save()
+
+            Local directory/folder:
+
+            >>> ln.Storage("./my-directory").save()
+        """
+        pass
+
     @classmethod
     def from_df(
         cls,