favour using task_help method instead of pprint(fields_dict(...))

Author: tclose

docs/source/tutorial/4-python.ipynb

@@ -25,7 +25,7 @@
     "\n",
     "# Note that we use PascalCase because the object returned by the decorator is actually a class\n",
     "@python.define\n",
-    "def MyFirstTaskDef(a, b):\n",
+    "def MyFirstTask(a, b):\n",
     "    \"\"\"Sample function for testing\"\"\"\n",
     "    return a + b"
    ]
@@ -45,7 +45,7 @@
    "outputs": [],
    "source": [
     "# Instantiate the task, setting all parameters\n",
-    "my_first_task = MyFirstTaskDef(a=1, b=2.0)\n",
+    "my_first_task = MyFirstTask(a=1, b=2.0)\n",
     "\n",
     "# Execute the task\n",
     "outputs = my_first_task()\n",
@@ -69,12 +69,12 @@
    "outputs": [],
    "source": [
     "@python.define(outputs=[\"c\", \"d\"])\n",
-    "def NamedOutputTaskDef(a, b):\n",
+    "def NamedOutputTask(a, b):\n",
     "    \"\"\"Sample function for testing\"\"\"\n",
     "    return a + b, a - b\n",
     "\n",
     "\n",
-    "named_output_task = NamedOutputTaskDef(a=2, b=1)\n",
+    "named_output_task = NamedOutputTask(a=2, b=1)\n",
     "\n",
     "outputs = named_output_task()\n",
     "\n",
@@ -102,7 +102,7 @@
     "        \"d\": python.out(type=float, help=\"the difference of the inputs\"),\n",
     "    },\n",
     ")\n",
-    "def AugmentedTaskDef(a, b):\n",
+    "def AugmentedTask(a, b):\n",
     "    \"\"\"Sample function for testing\"\"\"\n",
     "    return a + b, a - b"
    ]
@@ -163,13 +163,12 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from pprint import pprint\n",
-    "from pydra.utils import fields_dict\n",
+    "from pydra.utils import task_help\n",
     "\n",
     "\n",
     "@python.define(outputs=[\"c\", \"d\"])\n",
-    "def DocStrDef(a: int, b: float) -> tuple[float, float]:\n",
-    "    \"\"\"Sample function for testing\n",
+    "def DocStrExample(a: int, b: float) -> tuple[float, float]:\n",
+    "    \"\"\"Example python task with help strings pulled from doc-string\n",
     "\n",
     "    Args:\n",
     "        a: First input\n",
@@ -183,8 +182,7 @@
     "    return a + b, a * b\n",
     "\n",
     "\n",
-    "pprint(fields_dict(DocStrDef))\n",
-    "pprint(fields_dict(DocStrDef.Outputs))"
+    "task_help(DocStrExample)"
    ]
   },
   {

docs/source/tutorial/5-shell.ipynb

@@ -134,8 +134,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from pprint import pprint\n",
-    "from pydra.utils import fields_dict\n",
+    "from pydra.utils import task_help\n",
     "\n",
     "Cp = shell.define(\n",
     "    \"cp <in_fs_objects:fs-object+> <out|out_dir:directory> \"\n",
@@ -145,8 +144,7 @@
     "    \"--tuple-arg <tuple_arg:int,str*> \"\n",
     ")\n",
     "\n",
-    "pprint(fields_dict(Cp))\n",
-    "pprint(fields_dict(Cp.Outputs))"
+    "task_help(Cp)"
    ]
   },
   {
@@ -164,6 +162,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "from pydra.utils import fields_dict\n",
+    "\n",
     "Cp = shell.define(\n",
     "    \"cp <in_fs_objects:fs-object+> <out|out_dir:directory> \"\n",
     "    \"-R<recursive=True> \"\n",
@@ -275,8 +275,7 @@
     ")\n",
     "\n",
     "\n",
-    "pprint(fields_dict(Cp))\n",
-    "pprint(fields_dict(Cp.Outputs))"
+    "task_help(Cp)"
    ]
   },
   {
@@ -390,7 +389,7 @@
    "outputs": [],
    "source": [
     "from fileformats.generic import File\n",
-    "from pydra.utils import task_fields\n",
+    "from pydra.utils import task_help\n",
     "\n",
     "ACommand = shell.define(\n",
     "    \"a-command\",\n",
@@ -407,9 +406,7 @@
     "    },\n",
     ")\n",
     "\n",
-    "\n",
-    "print(f\"ACommand input fields: {task_fields(ACommand)}\")\n",
-    "print(f\"ACommand input fields: {task_fields(ACommand.Outputs)}\")"
+    "task_help(ACommand)"
    ]
   },
   {

docs/source/tutorial/7-canonical-form.ipynb

@@ -46,8 +46,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from pprint import pprint\n",
-    "from pydra.utils import fields_dict\n",
+    "from pydra.utils import task_help\n",
     "from pydra.compose import python\n",
     "\n",
     "\n",
@@ -79,8 +78,7 @@
     "        return a + b, a / b\n",
     "\n",
     "\n",
-    "pprint(fields_dict(CanonicalPythonTask))\n",
-    "pprint(fields_dict(CanonicalPythonTask.Outputs))"
+    "task_help(CanonicalPythonTask)"
    ]
   },
   {
@@ -128,8 +126,7 @@
     "        return a + b, a / b\n",
     "\n",
     "\n",
-    "pprint(fields_dict(CanonicalPythonTask))\n",
-    "pprint(fields_dict(CanonicalPythonTask.Outputs))"
+    "task_help(CanonicalPythonTask)"
    ]
   },
   {
@@ -178,8 +175,7 @@
     "        out_file_size: int = shell.out(callable=get_file_size)\n",
     "\n",
     "\n",
-    "pprint(fields_dict(CpWithSize))\n",
-    "pprint(fields_dict(CpWithSize.Outputs))"
+    "task_help(CpWithSize)"
    ]
   },
   {

pydra/engine/tests/test_task.py

@@ -13,7 +13,7 @@
 from pydra.utils.messenger import FileMessenger, PrintMessenger, collect_messages
 from pydra.engine.audit import AuditFlag
 from pydra.engine.hooks import TaskHooks
-from pydra.utils.general import task_fields, print_help
+from pydra.utils.general import task_fields, task_help
 from pydra.engine.submitter import Submitter
 from pydra.engine.job import Job
 from pydra.utils.general import default_run_cache_dir
@@ -90,7 +90,7 @@ def TestFunc(a: int, b: float = 0.1) -> float:
     outputs = funky()
     assert outputs.out_out == 2.1
 
-    help = print_help(funky)
+    help = task_help(funky)
     assert help == [
         "Help for TestFunc",
         "Input Parameters:",
@@ -148,7 +148,7 @@ def TestFunc(
     assert hasattr(outputs, "integer")
     assert outputs.integer == 3
 
-    help = print_help(funky)
+    help = task_help(funky)
     assert help == [
         "Help for TestFunc",
         "Input Parameters:",
@@ -450,7 +450,7 @@ def TestFunc(a, b) -> int:
     assert not Path(cache_dir / f"python-{funky._hash}").exists()
     outputs = funky(cache_dir=cache_dir)
     assert outputs.out == 31
-    help = print_help(funky)
+    help = task_help(funky)
 
     assert help == [
         "Help for TestFunc",
@@ -491,7 +491,7 @@ def TestFunc(a, b) -> tuple[int, int]:
     assert not Path(cache_dir / f"python-{funky._hash}" / "_result.pklz").exists()
     outputs = funky(cache_dir=cache_dir)
     assert outputs.out1 == 12
-    help = print_help(funky)
+    help = task_help(funky)
 
     assert help == [
         "Help for TestFunc",

pydra/utils/__init__.py

@@ -2,8 +2,8 @@
     task_fields,
     fields_dict,
     plot_workflow,
-    print_help,
+    task_help,
 )
 from ._version import __version__
 
-__all__ = ["__version__", "task_fields", "plot_workflow", "print_help", "fields_dict"]
+__all__ = ["__version__", "task_fields", "plot_workflow", "task_help", "fields_dict"]

pydra/utils/general.py

@@ -297,7 +297,7 @@ def from_list_if_single(obj: ty.Any) -> ty.Any:
     return obj
 
 
-def print_help(defn: "Task[TaskType]") -> list[str]:
+def task_help(defn: "Task[TaskType]", to_list: bool = False) -> list[str] | None:
     """Visit a job object and print its input/output interface."""
     from pydra.compose.base import NO_DEFAULT
 
@@ -326,8 +326,9 @@ def print_help(defn: "Task[TaskType]") -> list[str]:
         except AttributeError:
             name = str(f.type)
         lines += [f"- {f.name}: {name}"]
+    if to_list:
+        return lines
     print("\n".join(lines))
-    return lines
 
 
 def position_sort(args):