cleaning up other references to output_dir

Author: tclose

docs/source/index.rst

@@ -170,6 +170,7 @@ See the full reference documentation for Pydra
    reference/api
    genindex
    modindex
+   reference/glossary
 
 .. _FSL: https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FSL
 .. _ANTs: http://stnava.github.io/ANTs/

docs/source/reference/glossary.rst

@@ -0,0 +1,28 @@
+Glossary
+========
+
+.. glossary::
+
+    Task
+      A unit of work within the system. It represents one complete processing step in a workflow.
+
+    Worker
+        Encapsulation of a task execution environment. It is responsible for executing
+        tasks and managing their lifecycle. Workers can be local (e.g., a thread or
+        process) or remote (e.g., high-performance cluster).
+
+    Job
+        A task that has been instantiated with resolved with concrete inputs.
+        (i.e. not lazy-values or state-arrays) and assigned to a worker.
+
+    Workflow
+      A series of tasks executed in a specific order.
+
+    Node
+        A single task within the context of a workflow, which is assigned a name and
+        references a state. Note this task can be nested workflow task.
+
+    State
+        The combination of all upstream splits and combines with any splitters and
+        combiners for a given node, it is used to track how many jobs, and their
+        parameterisations, need to be run for a given workflow node.

docs/source/tutorial/2-advanced-execution.ipynb

@@ -66,7 +66,7 @@
     "* `runtime`: information about the peak memory and CPU usage\n",
     "* `errored`: the error status of the task\n",
     "* `task`: the task object that generated the results\n",
-    "* `output_dir`: the output directory the results are stored in"
+    "* `cache_dir`: the output directory the results are stored in"
    ]
   },
   {

docs/source/tutorial/5-shell.ipynb

@@ -329,7 +329,7 @@
     "to it when it is called\n",
     "\n",
     "* field: the `Field` object to be provided a value, useful when writing generic callables\n",
-    "* output_dir: a `Path` object referencing the working directory the command was run within\n",
+    "* cache_dir: a `Path` object referencing the working directory the command was run within\n",
     "* inputs: a dictionary containing all the resolved inputs to the task\n",
     "* stdout: the standard output stream produced by the command\n",
     "* stderr: the standard error stream produced by the command\n",

pydra/compose/base/task.py

@@ -38,7 +38,7 @@ class Outputs:
 
     RESERVED_FIELD_NAMES = ("inputs",)
 
-    _output_dir: Path = attrs.field(default=None, init=False, repr=False)
+    _cache_dir: Path = attrs.field(default=None, init=False, repr=False)
 
     @property
     def inputs(self):
@@ -70,12 +70,12 @@ def _from_task(cls, job: "Job[TaskType]") -> Self:
                 default = output.default
             defaults[output.name] = default
         outputs = cls(**defaults)
-        outputs._output_dir = job.cache_dir
+        outputs._cache_dir = job.cache_dir
         return outputs
 
     @property
     def _results(self) -> "Result[Self]":
-        results_path = self._output_dir / "_job.pklz"
+        results_path = self._cache_dir / "_job.pklz"
         if not results_path.exists():
             raise FileNotFoundError(f"Job results file {results_path} not found")
         with open(results_path, "rb") as f:

pydra/compose/shell/field.py

@@ -107,7 +107,7 @@ class out(Out):
     callable : Callable, optional
         If provided the output file name (or list of file names) is created using the
         function. The function can take field (the specific output field will be passed
-        to the function), output_dir (task output_dir will be used), stdout, stderr
+        to the function), cache_dir (task cache_dir will be used), stdout, stderr
         (stdout and stderr of the task will be sent) inputs (entire inputs will be
         passed) or any input field name (a specific input field will be sent).
     """

pydra/compose/shell/task.py

@@ -64,7 +64,7 @@ def _from_task(cls, job: "Job[Task]") -> ty.Self:
         ----------
         inputs : Task
             The input task of the shell process.
-        output_dir : Path
+        cache_dir : Path
             The directory where the process was run.
         stdout : str
             The standard output of the process.
@@ -108,13 +108,13 @@ def _from_task(cls, job: "Job[Task]") -> ty.Self:
         return outputs
 
     @classmethod
-    def _resolve_default_value(cls, fld: field.out, output_dir: Path) -> ty.Any:
+    def _resolve_default_value(cls, fld: field.out, cache_dir: Path) -> ty.Any:
         """Resolve path and glob expr default values relative to the output dir"""
         default = fld.default
         if fld.type is Path:
             assert isinstance(default, Path)
             if not default.is_absolute():
-                default = output_dir.joinpath(default)
+                default = cache_dir.joinpath(default)
             if "*" not in str(default):
                 if default.exists():
                     return default
@@ -174,7 +174,7 @@ def _resolve_value(
             return template_update_single(
                 fld,
                 task=job.task,
-                output_dir=job.cache_dir,
+                cache_dir=job.cache_dir,
                 spec_type="output",
             )
         assert fld.callable, (
@@ -191,7 +191,7 @@ def _resolve_value(
         for argnm in call_args.args:
             if argnm == "field":
                 call_args_val[argnm] = fld
-            elif argnm == "output_dir":
+            elif argnm == "cache_dir":
                 call_args_val[argnm] = job.cache_dir
             elif argnm == "executable":
                 call_args_val[argnm] = job.task.executable
@@ -209,7 +209,7 @@ def _resolve_value(
                 except KeyError as e:
                     e.add_note(
                         f"arguments of the callable function from {fld.name!r} "
-                        f"has to be in inputs or be field or output_dir, "
+                        f"has to be in inputs or be field or cache_dir, "
                         f"but {argnm!r} is used"
                     )
                     raise
@@ -262,7 +262,7 @@ def cmdline(self) -> str:
         the current working directory."""
         # Skip the executable, which can be a multi-part command, e.g. 'docker run'.
         values = attrs_values(self)
-        values.update(template_update(self, output_dir=Path.cwd()))
+        values.update(template_update(self, cache_dir=Path.cwd()))
         cmd_args = self._command_args(values=values)
         cmdline = cmd_args[0]
         for arg in cmd_args[1:]:

pydra/compose/shell/templating.py

@@ -15,7 +15,7 @@
 
 def template_update(
     task,
-    output_dir: Path | None = None,
+    cache_dir: Path | None = None,
     map_copyfiles: dict[str, Path] | None = None,
 ):
     """
@@ -45,7 +45,7 @@ def template_update(
             fld=fld,
             task=task,
             values=values,
-            output_dir=output_dir,
+            cache_dir=cache_dir,
         )
     # adding elements from map_copyfiles to fields with templates
     if map_copyfiles:
@@ -57,7 +57,7 @@ def template_update_single(
     fld: "field.outarg",
     task: "Task",
     values: dict[str, ty.Any] = None,
-    output_dir: Path | None = None,
+    cache_dir: Path | None = None,
     spec_type: str = "input",
 ) -> Path | list[Path | None] | None:
     """Update a single template from the input_spec or output_spec
@@ -96,13 +96,13 @@ def template_update_single(
             return None
     # inputs_dict[fld.name] is True or spec_type is output
     value = _template_formatting(fld, task, values)
-    if output_dir and value is not None:
-        # changing path so it is in the output_dir
+    if cache_dir and value is not None:
+        # changing path so it is in the cache_dir
         # should be converted to str, it is also used for input fields that should be str
         if type(value) is list:
-            value = [output_dir / val.name for val in value]
+            value = [cache_dir / val.name for val in value]
         else:
-            value = output_dir / value.name
+            value = cache_dir / value.name
     return value
 
 

pydra/compose/shell/tests/test_shell_run.py

@@ -1289,7 +1289,7 @@ class Outputs(shell.Outputs):
 def test_shell_cmd_inputspec_copyfile_1(worker, results_function, tmp_path):
     """shelltask changes a file in place,
     adding copy_mode="copy" to the file-input from input_spec
-    hardlink or copy in the output_dir should be created
+    hardlink or copy in the cache_dir should be created
     """
     file = tmp_path / "file_pydra.txt"
     with open(file, "w") as f:
@@ -1329,7 +1329,7 @@ class Outputs(shell.Outputs):
 def test_shell_cmd_inputspec_copyfile_1a(worker, results_function, tmp_path):
     """shelltask changes a file in place,
     adding copyfile=False to the File-input from input_spec
-    hardlink or softlink in the output_dir is created
+    hardlink or softlink in the cache_dir is created
     """
     file = tmp_path / "file_pydra.txt"
     with open(file, "w") as f:
@@ -2076,13 +2076,13 @@ def test_shell_cmd_outputspec_5(worker, results_function, tmp_path):
     """
     customised output_spec, adding files to the output,
     using a function to collect output, the function is saved in the field metadata
-    and uses output_dir and the glob function
+    and uses cache_dir and the glob function
     """
     cmd = ["touch", "newfile_tmp1.txt", "newfile_tmp2.txt"]
 
-    def gather_output(field, output_dir):
+    def gather_output(field, cache_dir):
         if field.name == "newfile":
-            return list(Path(output_dir).expanduser().glob("newfile*.txt"))
+            return list(Path(cache_dir).expanduser().glob("newfile*.txt"))
 
     @shell.define
     class Shelly(shell.Task["Shelly.Outputs"]):
@@ -2107,13 +2107,13 @@ def test_shell_cmd_outputspec_5a(worker, results_function, tmp_path):
     """
     customised output_spec, adding files to the output,
     using a function to collect output, the function is saved in the field metadata
-    and uses output_dir and inputs element
+    and uses cache_dir and inputs element
     """
     cmd = ["touch", "newfile_tmp1.txt", "newfile_tmp2.txt"]
 
-    def gather_output(executable, output_dir):
+    def gather_output(executable, cache_dir):
         files = executable[1:]
-        return [Path(output_dir) / file for file in files]
+        return [Path(cache_dir) / file for file in files]
 
     @shell.define
     class Shelly(shell.Task["Shelly.Outputs"]):
@@ -2141,9 +2141,9 @@ def test_shell_cmd_outputspec_5b_error(tmp_path):
     """
     cmd = ["touch", "newfile_tmp1.txt", "newfile_tmp2.txt"]
 
-    def gather_output(executable, output_dir, ble):
+    def gather_output(executable, cache_dir, ble):
         files = executable[1:]
-        return [Path(output_dir) / file for file in files]
+        return [Path(cache_dir) / file for file in files]
 
     @shell.define
     class Shelly(shell.Task["Shelly.Outputs"]):
@@ -2173,9 +2173,9 @@ class Shelly(shell.Task["Shelly.Outputs"]):
         class Outputs(shell.Outputs):
 
             @staticmethod
-            def gather_output(executable, output_dir):
+            def gather_output(executable, cache_dir):
                 files = executable[1:]
-                return [Path(output_dir) / file for file in files]
+                return [Path(cache_dir) / file for file in files]
 
             newfile: MultiOutputFile = shell.out(callable=gather_output)
 
@@ -2478,10 +2478,10 @@ class Outputs(shell.Outputs):
     assert get_output_names(shelly) == ["resultsDir", "return_code", "stderr", "stdout"]
     cache_root = tmp_path / "cache"
     outputs = results_function(shelly, worker=worker, cache_root=cache_root)
-    output_dir = next(p for p in cache_root.iterdir() if p.name.startswith("shell-"))
-    assert (output_dir / Path("test")).exists()
+    cache_dir = next(p for p in cache_root.iterdir() if p.name.startswith("shell-"))
+    assert (cache_dir / Path("test")).exists()
     assert get_lowest_directory(outputs.resultsDir) == get_lowest_directory(
-        output_dir / Path("test")
+        cache_dir / Path("test")
     )
 
 

pydra/compose/shell/tests/test_shell_templating.py

@@ -104,6 +104,6 @@ def test_template_formatting(tmp_path: Path):
         field,
         task,
         values=values,
-        output_dir=tmp_path,
+        cache_dir=tmp_path,
         spec_type="input",
     ) == [tmp_path / "file.bvec", tmp_path / "file.bval"]