Clean up landing page examples

app/stardag-ui/src/code-examples/async-io/class-api.py

@@ -1,5 +1,6 @@
-"""Completion checks already happen concurrently via asyncio. Implement 
-`run_aio` for async concurrent task execution in build."""
+"""Completion checks already happen concurrently via asyncio. 
+Implement `run_aio` and use `_save_aio`/`load_aio` for async 
+concurrent task execution and saving output/loading inputs in build."""
 import httpx
 import stardag as sd
 
@@ -10,7 +11,7 @@ async def run_aio(self):
         async with httpx.AsyncClient() as client:
             response = await client.get(self.url)
             response.raise_for_status()
-            self._save(response.text)
+            await self._save_aio(response.text)
 
 urls = [f"https://www.example.com/{i}" for i in range(5)]
 tasks = [Download(url=url) for url in urls]

app/stardag-ui/src/code-examples/async-io/decorator-api.py

@@ -1,5 +1,6 @@
-"""Completion checks already happen concurrently via asyncio. Decorate 
-async functions to get async concurrent task execution in build."""
+"""Completion checks already happen concurrently via asyncio.
+Decorate async functions to get async concurrent task execution 
+and saving output/loading inputs in build."""
 import httpx
 import stardag as sd
 

app/stardag-ui/src/code-examples/compose/class-api.py

@@ -1,14 +1,18 @@
+"""Use the class API for further control."""
 import stardag as sd
 
+# Produces (a.k.a. "loads") list[int]
 class Range(sd.Task[list[int]]):
     limit: int
 
     def run(self):
         self._save(list(range(self.limit)))
 
-class Sum(sd.Task[int]):
+class Sum(sd.Task[int]):  # Produces ("loads") int
+    # Any task that produces ("loads") list[int]
     values: sd.TaskLoads[list[int]]
 
+    # Explicitly declare dependencies on other tasks
     def requires(self):
         return self.values
 

app/stardag-ui/src/code-examples/compose/decorator-api.py

@@ -1,9 +1,12 @@
+"""Use the decorator API to turn type-hinted 
+functions into tasks and compose them naturally."""
 import stardag as sd
 
 @sd.task
 def get_range(limit: int) -> list[int]:
     return list(range(limit))
 
+# Use `sd.Depends` to declare dependencies on other tasks' outputs
 @sd.task
 def get_sum(values: sd.Depends[list[int]]) -> int:
     return sum(values)

app/stardag-ui/src/code-examples/configure-env/env-vars.py

@@ -8,11 +8,11 @@
 import stardag as sd
 
 @sd.task(target_root_key="ingestion")
-def ingest(source: str) -> dict:
+def ingest(source: str) -> dict[str, str]:
     return {"result": source}
 
 @sd.task  # default target_root_key is "default"
-def process(data: sd.Depends[dict]) -> dict:
+def process(data: sd.Depends[dict[str, str]]) -> dict[str, str]:
     return {"result": data["result"] + " processed"}
 
 

app/stardag-ui/src/code-examples/configure-env/profile.py

@@ -20,11 +20,11 @@
 import stardag as sd
 
 @sd.task(target_root_key="ingestion")
-def ingest(source: str) -> dict:
+def ingest(source: str) -> dict[str, str]:
     return {"result": source}
 
 @sd.task  # default target_root_key is "default"
-def process(data: sd.Depends[dict]) -> dict:
+def process(data: sd.Depends[dict[str, str]]) -> dict[str, str]:
     return {"result": data["result"] + " processed"}
 
 

app/stardag-ui/src/code-examples/parameter-hashing/control.py

@@ -1,3 +1,4 @@
+"""Full control of parameter hashing with `StardagField`."""
 from typing import Annotated
 import stardag as sd
 

app/stardag-ui/src/code-examples/pydantic/class-api.py

@@ -1,11 +1,12 @@
-"""Stardag tasks *are* Pydantic models"""
+"""Stardag tasks *are* Pydantic models and serve as a
+declarative specification of the assets they produce."""
 from typing import Annotated
 from pydantic import Field
 
 import stardag as sd
 
 class Range(sd.Task[list[int]]):
-    # All Pydantic primitives such as validation out of the box
+    # Get all Pydantic primitives such as validation out of the box
     limit: Annotated[int, Field(gt=0)]
 
     def run(self):
@@ -24,7 +25,7 @@ def run(self):
 root_task = Sum(values=Range(limit=4))
 
 # Tasks are Pydantic models with all the familiar convenience methods
-assert root_task.model_dump() =={
+assert root_task.model_dump() == {
   "__namespace": "",
   "__name": "Sum",
   "version": "",

app/stardag-ui/src/code-examples/pydantic/decorator-api.py

@@ -1,12 +1,13 @@
-"""Stardag tasks *are* Pydantic models"""
+"""Stardag tasks *are* Pydantic models and serve as a
+declarative specification of the assets they produce."""
 from typing import Annotated
 from pydantic import Field
 
 import stardag as sd
 
 @sd.task
 def get_range(
-    # All Pydantic primitives such as validation out of the box
+    # Get all Pydantic primitives such as validation out of the box
     limit: Annotated[int, Field(gt=0)]
 ) -> list[int]:
     return list(range(limit))
@@ -19,7 +20,7 @@ def get_sum(values: sd.Depends[list[int]]) -> int:
 root_task = get_sum(values=get_range(limit=4))
 
 # Tasks are Pydantic models with all the familiar convenience methods
-assert root_task.model_dump() =={
+assert root_task.model_dump() == {
   "__namespace": "",
   "__name": "get_sum",
   "version": "",

app/stardag-ui/src/code-examples/serialization/load-from-registry.py

@@ -12,7 +12,7 @@ def get_num_rows(df: sd.Depends[pd.DataFrame]) -> int:
 # Get task id from registry UI
 df_task_id = UUID("359d8374-de0e-521b-84c1-1e9fd3b8b112")
 
-# We must (only) know data type used for serialization
+# We must (only) know data type used for (de)serialization
 df_task = sd.AliasTask[pd.DataFrame].from_registry(id=df_task_id)
 
 # AliasTask maintains the original task's ID, and can be composed as usual