matchlab 0.1.0.dev2__py3-none-any.whl → 0.1.0.dev4__py3-none-any.whl

matchlab/document.py

@@ -158,15 +158,19 @@ class PlanDocument(BaseModel):
         return {name for node in self.steps for name in node.resources.values()}
 
 
-def dump(root: Step) -> PlanDocument:
+def dump(root: Step, *, indent: int | None = None) -> str:
     """Describe `root` and everything it reads as a portable document.
 
+    JSON rather than an object, because a document exists to be put somewhere: a
+    column, an object store, a request body, a file.
+
     Args:
         root: The apex of the plan. Only what is reachable upstream of it is included,
             exactly as `collect()` would run.
+        indent: How the JSON is laid out. `None`, the default, is compact.
 
     Returns:
-        The document. It holds no resource, no credentials and no data.
+        The document, as JSON.
 
     Raises:
         ResourceError: If a resource was passed without a name, so there is nothing for
@@ -174,23 +178,9 @@ def dump(root: Step) -> PlanDocument:
             earlier, when the plan is built.
     """
     ordered = walk(root)
-    _check_resources(ordered)
-    position = {id(step): index for index, step in enumerate(ordered)}
-    return PlanDocument(
-        steps=tuple(
-            _node(step, tuple(position[id(parent)] for parent in step.parents))
-            for step in ordered
-        )
-    )
-
-
-def _check_resources(steps: list[Step]) -> None:
-    """Reject a plan whose resources have no names to record.
 
-    Raises:
-        ResourceError: If a resource is unnamed.
-    """
-    for position, step in enumerate(steps):
+    # Check resources
+    for position, step in enumerate(ordered):
         for field, resource in step._resources().items():
             if resource.name is None:
                 raise ResourceError(
@@ -199,6 +189,15 @@ def _check_resources(steps: list[Step]) -> None:
                     f'{field}=Resource("some_name", ...).'
                 )
 
+    position = {id(step): index for index, step in enumerate(ordered)}
+    document = PlanDocument(
+        steps=tuple(
+            _node(step, tuple(position[id(parent)] for parent in step.parents))
+            for step in ordered
+        )
+    )
+    return document.model_dump_json(indent=indent)
+
 
 def _node(step: Step, inputs: tuple[int, ...]) -> StepNode:
     """Describe one step, checking its spec is the one its kind implies."""
@@ -216,61 +215,68 @@ def _node(step: Step, inputs: tuple[int, ...]) -> StepNode:
     )
 
 
-def load(document: PlanDocument, resources: Mapping[str, Any]) -> Step:
+def load(document: str | bytes, resources: Mapping[str, Any]) -> Step:
     """Rebuild a plan from a document, returning its apex.
 
     Nothing is collected. This reconstructs the same lazy plan, so the returned step
     fingerprints identically to the one that was dumped, given the same data.
 
     Args:
-        document: A dumped plan.
+        document: The JSON `dump` produced.
         resources: Name to object, for every resource the document names.
-            `document.required_resources()` lists them.
 
     Returns:
         The plan's apex, the last step in the document.
 
     Raises:
+        ValidationError: If the JSON does not describe a plan document.
         ValueError: If the document is empty, names an unregistered location class, or
             wires a step to an input of the wrong kind.
         ResourceError: If a named resource was not supplied.
     """
-    if not document.steps:
+    parsed = PlanDocument.model_validate_json(document)
+    if not parsed.steps:
         raise ValueError("A plan document needs at least one step")
 
+    _check_supplied(parsed, resources)
+
     built: list[Step] = []
-    for position, node in enumerate(document.steps):
+    for position, node in enumerate(parsed.steps):
         built.append(
             _rebuild(node, position, [built[i] for i in node.inputs], resources)
         )
     return built[-1]
 
 
-def _bind(
-    node: StepNode, position: int, supplied: Mapping[str, Any]
-) -> dict[str, Resource]:
-    """Turn a node's `field -> resource name` map into bound resources.
+def _check_supplied(document: PlanDocument, supplied: Mapping[str, Any]) -> None:
+    """Reject a load missing any resource the document names, naming them all.
 
     Raises:
         ResourceError: If the document names a resource `supplied` does not have.
     """
-    bound: dict[str, Resource] = {}
-    for field, name in node.resources.items():
-        if name not in supplied:
-            raise ResourceError(
-                f"Step {position} ({node.kind}) needs resource '{name}' for '{field}', "
-                f"which was not supplied. Pass it when loading: "
-                f"resources={{'{name}': ...}}."
-            )
-        bound[field] = Resource(name, supplied[name])
-    return bound
+    missing: dict[str, str] = {}
+    for position, node in enumerate(document.steps):
+        for field, name in node.resources.items():
+            if name not in supplied and name not in missing:
+                missing[name] = f"step {position} ({node.kind}) reads it as '{field}'"
+    if not missing:
+        return
+
+    wanted = "\n".join(f"  '{name}' — {where}" for name, where in missing.items())
+    example = ", ".join(f"'{name}': ..." for name in missing)
+    raise ResourceError(
+        f"This plan needs resources that were not supplied:\n{wanted}\n"
+        f"Pass them when loading: resources={{{example}}}."
+    )
 
 
 def _rebuild(
     node: StepNode, position: int, inputs: list[Step], supplied: Mapping[str, Any]
 ) -> Step:
     """Rebuild one step from its node and its already-rebuilt inputs."""
-    resources = _bind(node, position, supplied)
+    resources = {
+        field: Resource(name, supplied[name]) for field, name in node.resources.items()
+    }
     match node.kind:
         case StepKind.SOURCE:
             spec = _expect(node, position, SourceSpec)

matchlab/models/linkers/splinklinker.py

@@ -174,21 +174,52 @@ class SplinkLinker(Linker):
     _id_dtype_l: pl.DataType
     _id_dtype_r: pl.DataType
 
+    @staticmethod
+    def _schema_summary(data: pl.DataFrame) -> str:
+        """Render a compact column-to-dtype summary for diagnostics."""
+        return (
+            ", ".join(f"{column}={dtype}" for column, dtype in data.schema.items())
+            or "<empty>"
+        )
+
+    @classmethod
+    def _conformancy_error(cls, left: pl.DataFrame, right: pl.DataFrame) -> ValueError:
+        """Build a detailed error describing how the two inputs differ."""
+        left_only = [column for column in left.columns if column not in right.columns]
+        right_only = [column for column in right.columns if column not in left.columns]
+        shared = [column for column in left.columns if column in right.columns]
+        differing_dtypes = [
+            f"{column}: left={left.schema[column]}, right={right.schema[column]}"
+            for column in shared
+            if left.schema[column] != right.schema[column]
+        ]
+
+        details = [
+            "SplinkLinker requires input data to be conformant, meaning they "
+            "share the same column names and data formats.",
+            f"Left schema: {cls._schema_summary(left)}",
+            f"Right schema: {cls._schema_summary(right)}",
+        ]
+        if left_only:
+            details.append(f"Columns only on left: {left_only}")
+        if right_only:
+            details.append(f"Columns only on right: {right_only}")
+        if differing_dtypes:
+            details.append("Differing dtypes: " + "; ".join(differing_dtypes))
+        return ValueError("\n".join(details))
+
     def prepare(self, left: pl.DataFrame, right: pl.DataFrame) -> None:
         """Build the Splink linker over left and right, and run its training functions.
 
         Runs each function in `settings.linker_training_functions`, in order, against
         the built linker. `link()` then just predicts against the trained state.
         """
-        if (set(left.columns) != set(right.columns)) or not left.dtypes == right.dtypes:
-            raise ValueError(
-                "SplinkLinker requires input data to be conformant, meaning they "
-                "share the same column names and data formats."
-            )
-
         self._id_dtype_l = left[self.left_id].dtype
         self._id_dtype_r = right[self.right_id].dtype
 
+        if (set(left.columns) != set(right.columns)) or not left.dtypes == right.dtypes:
+            raise self._conformancy_error(left, right)
+
         # Convert to pandas for Splink compatibility
         left_pd = left.with_columns(pl.col(self.left_id).cast(pl.String)).to_pandas()
         right_pd = right.with_columns(pl.col(self.right_id).cast(pl.String)).to_pandas()

{matchlab-0.1.0.dev2.dist-info → matchlab-0.1.0.dev4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matchlab
-Version: 0.1.0.dev2
+Version: 0.1.0.dev4
 Summary: A local-first library for building, running and evaluating entity resolution pipelines.
 Author: Department for Business and Trade
 Project-URL: Documentation, https://uktrade.github.io/matchlab/

{matchlab-0.1.0.dev2.dist-info → matchlab-0.1.0.dev4.dist-info}/RECORD

@@ -1,6 +1,6 @@
 matchlab/__init__.py,sha256=vjjzGMDlKk1D7GPHp5Yk8LqFs7yhQw8VANVtJh9HK_U,2419
 matchlab/cli.py,sha256=Ka-clRCiPnxI5jmehjGCgdNyADcPFcnl3cuPI1rynYg,6209
-matchlab/document.py,sha256=M6A8N353c-7vIi3NrXPM2yGoHOGCinrH65_5yJmaYFc,14503
+matchlab/document.py,sha256=rCnGJxdu83Mqbf5PnIjda2mVM7StW3IXdMFb9MPx6nE,14927
 matchlab/lineage.py,sha256=C2y2gclA-ehh2Yh45aLLaAwMgBZOK6tZmLgxjvycl-I,8865
 matchlab/progress.py,sha256=t2PAj0YG2vAHguMFn9J0NL07R2K6wEnAkGELQpFNYNM,21330
 matchlab/recordstep.py,sha256=E1-JkXsqcPmrlQw7AM-eDfHPcznLX0e_SzlVrTsADEA,7637
@@ -41,7 +41,7 @@ matchlab/models/dedupers/naive.py,sha256=fP8PFKXDDvNmCMhWPLZQO9KWJoagMIDBq-qYVdU
 matchlab/models/linkers/__init__.py,sha256=qbj6hITLFBuONO0_fn3yPknTUAWjzWcFSQzIyi75Rmc,339
 matchlab/models/linkers/base.py,sha256=Wp4Eym5ZyDy3nBeaFVLaHDgB4rC2CSV7VFclPD5PkAI,1488
 matchlab/models/linkers/deterministic.py,sha256=TQmwy9tPL0F7BStpoQaET6xTbyt1znujebzV7IB3CG0,8735
-matchlab/models/linkers/splinklinker.py,sha256=O2Ds0dhnozPAOOi2-CoyM8_ED9Wxtl5B6Kqt415WEl8,10103
+matchlab/models/linkers/splinklinker.py,sha256=iB3h6jSGCzo4HsF3P0mOKt0YqTvq3deukz6VaFb6a6A,11513
 matchlab/models/linkers/weighteddeterministic.py,sha256=sD2QosF4IJMQwUwmuWzDKCr6Cta7RZyjS43I15WMtTI,4050
 matchlab/resolvers/__init__.py,sha256=QuWZ6zt2QK7tWn9lr83iYUTkNQxwtAM9PITaoJOOpPs,210
 matchlab/resolvers/base.py,sha256=s8u3uDZEln9FadCLEc6nxZZICu3KgIP4ShSe-PxruZM,2281
@@ -68,9 +68,9 @@ matchlab/transformers/explode.py,sha256=k8Q__0aFdntyGxkffu2KWSJmCVCu7ImvJtRt-32Q
 matchlab/transformers/group.py,sha256=oPswcSUdj_2W2WCb0gJ51YSWU3qI3MVfZ3aYw5EXDl0,2374
 matchlab/transformers/select.py,sha256=s3NmMgL5IS7ifeIhj5ABQJ46XULW6s_kQKASOq7G0sQ,1125
 matchlab/transformers/transform.py,sha256=KlzKlbEvA5tF6wBSK9RuXkHLd6gckfhDsT6SJQa3atQ,7007
-matchlab-0.1.0.dev2.dist-info/licenses/LICENSE,sha256=7fhYMrjTXiy7Sf-9lBtZHNc4IjHTcfqmGW0AcjFMJJo,1090
-matchlab-0.1.0.dev2.dist-info/METADATA,sha256=ajzBLXJWFDhpXmJaOSLnqGlBacwzUQV6MjghGFoccP8,3268
-matchlab-0.1.0.dev2.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-matchlab-0.1.0.dev2.dist-info/entry_points.txt,sha256=giDdKIeNDxGNWrvoVuLA5mtQjwStupSwxDYmrRjM9Rs,47
-matchlab-0.1.0.dev2.dist-info/top_level.txt,sha256=1ZVLg12gZgkOUbN5CfX-KmLTbHGRbZqFEZPqrfRVN-Y,9
-matchlab-0.1.0.dev2.dist-info/RECORD,,
+matchlab-0.1.0.dev4.dist-info/licenses/LICENSE,sha256=7fhYMrjTXiy7Sf-9lBtZHNc4IjHTcfqmGW0AcjFMJJo,1090
+matchlab-0.1.0.dev4.dist-info/METADATA,sha256=lbnW3f0uznFSzADcZkaA4AJ7H3p7TnxCR8Vn_PuX0qA,3268
+matchlab-0.1.0.dev4.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+matchlab-0.1.0.dev4.dist-info/entry_points.txt,sha256=giDdKIeNDxGNWrvoVuLA5mtQjwStupSwxDYmrRjM9Rs,47
+matchlab-0.1.0.dev4.dist-info/top_level.txt,sha256=1ZVLg12gZgkOUbN5CfX-KmLTbHGRbZqFEZPqrfRVN-Y,9
+matchlab-0.1.0.dev4.dist-info/RECORD,,