📝 Add run=False description to from_dir

lnschema_core/_docs.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from textwrap import dedent
+
+
+def doc_args(*args):
+    """Pass arguments to docstrings."""
+
+    def dec(obj):
+        obj.__orig_doc__ = obj.__doc__
+        obj.__doc__ = dedent(obj.__doc__).format(*args)
+        return obj
+
+    return dec
+
+
+from_x_run_docs = """
+`Run` object or `False`. If :meth:`ln.track` was called, `False` prevents
+associating :class:`ln.Artifact` as :attr:`Run.output_artifacts`, allowing :attr:`Run.input_artifacts` instead.
+"""

lnschema_core/models.py

@@ -24,6 +24,7 @@
 from lamindb_setup import _check_instance_setup
 from lamindb_setup.core.hashing import HASH_LENGTH
 
+from lnschema_core._docs import doc_args, from_x_run_docs
 from lnschema_core.types import (
     ArtifactType,
     CharField,
@@ -2135,12 +2136,13 @@ def path(self) -> Path:
         pass
 
     @classmethod
+    @doc_args(from_x_run_docs)
     def from_df(
         cls,
         df: pd.DataFrame,
         key: str | None = None,
         description: str | None = None,
-        run: Run | None = None,
+        run: Run | bool | None = None,
         revises: Artifact | None = None,
         **kwargs,
     ) -> Artifact:
@@ -2154,7 +2156,7 @@ def from_df(
                 e.g., `"myfolder/myfile.parquet"`.
             description: A description.
             revises: An old version of the artifact.
-            run: The run that creates the artifact.
+            run: {0}
 
         See Also:
             :meth:`~lamindb.Collection`
@@ -2182,7 +2184,7 @@ def from_anndata(
         adata: AnnData | UPathStr,
         key: str | None = None,
         description: str | None = None,
-        run: Run | None = None,
+        run: Run | bool | None = None,
         revises: Artifact | None = None,
         **kwargs,
     ) -> Artifact:
@@ -2194,7 +2196,7 @@ def from_anndata(
                 e.g., `"myfolder/myfile.h5ad"`.
             description: A description.
             revises: An old version of the artifact.
-            run: The run that creates the artifact.
+            run: {0}
 
         See Also:
 
@@ -2213,12 +2215,13 @@ def from_anndata(
         pass
 
     @classmethod
+    @doc_args(from_x_run_docs)
     def from_mudata(
         cls,
         mdata: MuData,
         key: str | None = None,
         description: str | None = None,
-        run: Run | None = None,
+        run: Run | bool | None = None,
         revises: Artifact | None = None,
         **kwargs,
     ) -> Artifact:
@@ -2230,7 +2233,7 @@ def from_mudata(
                 e.g., `"myfolder/myfile.h5mu"`.
             description: A description.
             revises: An old version of the artifact.
-            run: The run that creates the artifact.
+            run: {0}
 
         See Also:
             :meth:`~lamindb.Collection`
@@ -2248,12 +2251,13 @@ def from_mudata(
         pass
 
     @classmethod
+    @doc_args(from_x_run_docs)
     def from_dir(
         cls,
         path: UPathStr,
         key: str | None = None,
         *,
-        run: Run | None = None,
+        run: Run | bool | None = None,
     ) -> list[Artifact]:
         """Create a list of artifact objects from a directory.
 
@@ -2264,11 +2268,11 @@ def from_dir(
 
         Args:
             path: Source path of folder.
-            key: Key for storage destination. If `None` and
+            key: Optional Key for storage destination. If `None` and
                 directory is in a registered location, the inferred `key` will
                 reflect the relative position. If `None` and directory is outside
                 of a registered storage location, the inferred key defaults to `path.name`.
-            run: A `Run` object.
+            run: {0}
 
         Examples:
             >>> dir_path = ln.core.datasets.generate_cell_ranger_files("sample_001", ln.settings.storage)