From 4e9ac5efbe040c6509d39580ec8a6c7f95c2c43b Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 30 Mar 2026 22:13:15 +0000
Subject: [PATCH 1/2] Initial plan


From 9a1423138cf13f0067c42de63570fdbdac3d712a Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 30 Mar 2026 22:18:07 +0000
Subject: [PATCH 2/2] Add docstrings to pipeweld objects and functions

Agent-Logs-Url: https://github.com/usethis-python/usethis-python/sessions/77c2b8c8-97e2-4dbf-ab7b-19f4d090df64

Co-authored-by: nathanjmcdougall <18602289+nathanjmcdougall@users.noreply.github.com>
---
 src/usethis/_pipeweld/containers.py |  6 ++++++
 src/usethis/_pipeweld/func.py       | 14 ++++++++++++++
 src/usethis/_pipeweld/ops.py        |  6 ++++++
 src/usethis/_pipeweld/result.py     |  2 ++
 4 files changed, 28 insertions(+)

diff --git a/src/usethis/_pipeweld/containers.py b/src/usethis/_pipeweld/containers.py
index 99bb1179..20f205c4 100644
--- a/src/usethis/_pipeweld/containers.py
+++ b/src/usethis/_pipeweld/containers.py
@@ -9,6 +9,8 @@
 
 
 class Series(RootModel[list["Series | Parallel | DepGroup | str"]]):
+    """An ordered sequence of pipeline components executed one after another."""
+
     @override
     def __hash__(self):
         return hash((_HASH_SALT, tuple(self.root)))
@@ -30,6 +32,8 @@ def __len__(self):
 
 
 class Parallel(RootModel[frozenset["Series | Parallel | DepGroup | str"]]):
+    """An unordered set of pipeline components executed in parallel."""
+
     @override
     def __hash__(self):
         return hash((_HASH_SALT, frozenset(self)))
@@ -51,6 +55,8 @@ def __len__(self):
 
 
 class DepGroup(BaseModel):
+    """A pipeline component tied to a named dependency configuration group."""
+
     series: Series
     config_group: str
 
diff --git a/src/usethis/_pipeweld/func.py b/src/usethis/_pipeweld/func.py
index 00cdf6cd..47eb0f85 100644
--- a/src/usethis/_pipeweld/func.py
+++ b/src/usethis/_pipeweld/func.py
@@ -25,6 +25,13 @@
 
 
 class Partition(BaseModel):
+    """A three-way partition of a pipeline component relative to a new step's dependencies.
+
+    The three parts are: steps that must run before the new step (prerequisite),
+    steps independent of the new step (nondependent), and steps that must run after
+    the new step (postrequisite).
+    """
+
     prerequisite_component: str | Series | DepGroup | Parallel | None = None
     nondependent_component: str | Series | DepGroup | Parallel | None = None
     postrequisite_component: str | Series | DepGroup | Parallel | None = None
@@ -32,6 +39,8 @@ class Partition(BaseModel):
 
 
 class Adder(BaseModel):
+    """Add a new step into an existing pipeline, respecting dependency ordering."""
+
     pipeline: Series
     step: str
     prerequisites: set[str] = set()
@@ -39,6 +48,7 @@ class Adder(BaseModel):
     compatible_config_groups: set[str] = set()
 
     def add(self) -> WeldResult:
+        """Add the step to the pipeline and return the modified pipeline with instructions."""
         if len(self.pipeline) == 0:
             # Empty pipeline
             return WeldResult(
@@ -68,6 +78,10 @@ def add(self) -> WeldResult:
     def partition_component(
         self, component: str | Series | Parallel | DepGroup, *, predecessor: str | None
     ) -> tuple[Partition, list[Instruction]]:
+        """Partition a component into prerequisite, nondependent, and postrequisite parts.
+
+        Returns the partition and any insertion instructions needed to perform the split.
+        """
         if isinstance(component, str):
             if component in self.prerequisites:
                 return Partition(
diff --git a/src/usethis/_pipeweld/ops.py b/src/usethis/_pipeweld/ops.py
index ded241d7..56ab7a2a 100644
--- a/src/usethis/_pipeweld/ops.py
+++ b/src/usethis/_pipeweld/ops.py
@@ -8,15 +8,21 @@
 
 
 class BaseOperation(BaseModel):
+    """Base class for pipeline insertion operations."""
+
     after: str | None  # None represents the source node
     step: str
 
 
 class InsertParallel(BaseOperation):
+    """Insert a step in parallel with the step after the given predecessor."""
+
     pass
 
 
 class InsertSuccessor(BaseOperation):
+    """Insert a step as the immediate successor of the given predecessor."""
+
     pass
 
 
diff --git a/src/usethis/_pipeweld/result.py b/src/usethis/_pipeweld/result.py
index cc80f0fd..701e1ef0 100644
--- a/src/usethis/_pipeweld/result.py
+++ b/src/usethis/_pipeweld/result.py
@@ -9,5 +9,7 @@
 
 
 class WeldResult(BaseModel):
+    """The result of a pipeline welding operation."""
+
     solution: Series
     instructions: list[Instruction]