diff --git a/lnschema_core/_docs.py b/lnschema_core/_docs.py new file mode 100644 index 00000000..5e588945 --- /dev/null +++ b/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. +""" diff --git a/lnschema_core/models.py b/lnschema_core/models.py index 3da0e58d..62b5f285 100644 --- a/lnschema_core/models.py +++ b/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)