🚚 Rename .stage() to .cache(), add .save(upload=None) (#369)

* 🚚 Rename stage to download

* ✨ Add a upload() method to Artifact

* 🚚 Rename download to cache

* ♻️ Replace new method with flag in save()

* ♻️ Fix

lnschema_core/models.py

@@ -1915,33 +1915,28 @@ def load(
 
             Load as an `AnnData`:
 
-            >>> ln.Artifact("s3://lamindb-ci/lndb-storage/pbmc68k.h5ad").save()
-            >>> artifact = ln.Artifact.filter(key="lndb-storage/pbmc68k.h5ad").one()
             >>> artifact.load()
             AnnData object with n_obs × n_vars = 70 × 765
 
-            Fall back to :meth:`~lamindb.Artifact.stage` if no in-memory representation is configured:
+            Fall back to :meth:`~lamindb.Artifact.cache` if no in-memory representation is configured:
 
-            >>> ln.Artifact(ln.core.datasets.file_jpg_paradisi05(), description="paradisi05").save()
-            >>> artifact = ln.Artifact.filter(description="paradisi05").one()
             >>> artifact.load()
             PosixPath('/home/runner/work/lamindb/lamindb/docs/guide/mydata/.lamindb/jb7BY5UJoQVGMUOKiLcn.jpg')
         """
         pass
 
-    def stage(self, is_run_input: bool | None = None) -> Path:
-        """Update cache from cloud storage if outdated.
+    def cache(self, is_run_input: bool | None = None) -> Path:
+        """Download cloud artifact to local cache.
+
+        Follows synching logic: only caches an artifact if it's outdated in the local cache.
 
         Returns a path to a locally cached on-disk object (say, a `.jpg` file).
 
         Examples:
 
             Sync file from cloud and return the local path of the cache:
 
-            >>> ln.settings.storage = "s3://lamindb-ci"
-            >>> ln.Artifact("s3://lamindb-ci/lndb-storage/pbmc68k.h5ad").save()
-            >>> artifact = ln.Artifact.filter(key="lndb-storage/pbmc68k.h5ad").one()
-            >>> artifact.stage()
+            >>> artifact.cache()
             PosixPath('/home/runner/work/Caches/lamindb/lamindb-ci/lndb-storage/pbmc68k.h5ad')
         """
         pass
@@ -1969,9 +1964,13 @@ def delete(
         """
         pass
 
-    def save(self, *args, **kwargs) -> None:
+    def save(self, upload: bool | None = None, **kwargs) -> None:
         """Save to database & storage.
 
+        Args:
+            upload: Trigger upload to cloud storage in instances with hybrid
+                storage mode.
+
         Examples:
             >>> artifact = ln.Artifact("./myfile.csv", description="myfile")
             >>> artifact.save()
@@ -2158,7 +2157,7 @@ def mapped(
         virtually concatenating `AnnData` arrays.
 
         If your `AnnData` collection is in the cloud, move them into a local
-        cache first via :meth:`~lamindb.Collection.stage`.
+        cache first via :meth:`~lamindb.Collection.cache`.
 
         `__getitem__` of the `MappedCollection` object takes a single integer index
         and returns a dictionary with the observation data sample for this index from
@@ -2199,10 +2198,12 @@ def mapped(
         """
         pass
 
-    def stage(self, is_run_input: bool | None = None) -> list[UPath]:
-        """Update cache from cloud storage if outdated.
+    def cache(self, is_run_input: bool | None = None) -> list[UPath]:
+        """Download cloud artifacts in collection to local cache.
+
+        Follows synching logic: only caches outdated artifacts.
 
-        Returns paths to locally cached on-disk objects in the collection.
+        Returns paths to locally cached on-disk artifacts.
 
         Args:
             is_run_input: Whether to track this collection as run input.