feat: ✨ explain() errors

docs/design/interface.qmd

@@ -76,7 +76,7 @@ decide when and how failed checks should be enforced or handled. The
 output of this function is a list of `Issue` objects, which are
 described below.
 
-### {{< var planned >}} `explain()`
+### {{< var done >}} `explain()`
 
 The output of `check()` is a list of `Issue` objects, which are
 structured and machine-readable, but not very human-readable and

docs/guide/issues.qmd

@@ -12,9 +12,6 @@ properties. An `Issue` has attributes that provide information about the
 failed check, which are described in more detail in the
 [`Issue`](/docs/reference/Issue.qmd) documentation.
 
-<!-- TODO: Unhide this after it has been implemented. -->
-
-::: content-hidden
 ## The `explain()` function
 
 The `explain()` function provides a more verbose and user-friendly
@@ -40,4 +37,3 @@ cdp.explain(issues)
 
 When setting `error=True` in `check()`, error messages will be generated
 by the `explain()` function.
-:::

src/check_datapackage/__init__.py

@@ -1,6 +1,6 @@
 """Check functions and constants for the Frictionless Data Package standard."""
 
-from .check import DataPackageError, check
+from .check import DataPackageError, check, explain
 from .config import Config
 from .examples import (
     example_field_properties,
@@ -24,5 +24,6 @@
     "example_resource_properties",
     "example_field_properties",
     "check",
+    "explain",
     "read_json",
 ]

src/check_datapackage/check.py

@@ -48,17 +48,56 @@ def __init__(
         self,
         issues: list[Issue],
     ) -> None:
-        """Create the DataPackageError attributes from issues."""
-        # TODO: Switch to using `explain()` once implemented
-        errors: list[str] = _map(
-            issues,
-            lambda issue: f"- Property `{issue.jsonpath}`: {issue.message}\n",
-        )
-        message: str = (
-            "There were some issues found in your `datapackage.json`:\n\n"
-            + "\n".join(errors)
+        """Create the DataPackageError from issues."""
+        super().__init__(explain(issues))
+
+
+def explain(issues: list[Issue]) -> str:
+    """Explain the issues in a human-readable format.
+
+    Args:
+        issues: A list of `Issue` objects to explain.
+
+    Returns:
+        A human-readable explanation of the issues.
+
+    Examples:
+        ```{python}
+        import check_datapackage as cdp
+
+        issue = cdp.Issue(
+            jsonpath="$.resources[2].title",
+            type="required",
+            message="The `title` field is required but missing at the given JSON path.",
         )
-        super().__init__(message)
+
+        cdp.explain([issue])
+        ```
+    """
+    issue_explanations: list[str] = _map(
+        issues,
+        _create_explanation,
+    )
+    num_issues = len(issue_explanations)
+    singular_or_plural = " was" if num_issues == 1 else "s were"
+    return (
+        f"{num_issues} issue{singular_or_plural} found in your `datapackage.json`:\n\n"
+        + "\n".join(issue_explanations)
+    )
+
+
+def _create_explanation(issue: Issue) -> str:
+    """Create an informative explanation of what went wrong in each issue."""
+    # Remove suffix '$' to account for root path when `[]` is passed to `check()`
+    property_name = issue.jsonpath.removesuffix("$").split(".")[-1]
+    number_of_carets = len(str(issue.instance))
+    return (  # noqa: F401
+        f"At package{issue.jsonpath.removeprefix('$')}:\n"
+        "|\n"
+        f"| {property_name}{': ' if property_name else '  '}{issue.instance}\n"
+        f"| {' ' * len(property_name)}  {'^' * number_of_carets}\n"
+        f"{issue.message}\n"
+    )
 
 
 def check(
@@ -579,6 +618,7 @@ def _create_issue(error: SchemaError) -> Issue:
         message=error.message,
         jsonpath=error.jsonpath,
         type=error.type,
+        instance=error.instance,
     )
 
 

src/check_datapackage/issue.py

@@ -1,4 +1,5 @@
-from dataclasses import dataclass
+from dataclasses import dataclass, field
+from typing import Any
 
 
 @dataclass(order=True, frozen=True)
@@ -15,6 +16,8 @@ class Issue:
             as "required", "type", "pattern", or "format", or a custom type). Used to
             exclude specific types of issues.
         message (string): A description of what exactly the issue is.
+        instance (Any): The part of the object that failed the check. This field is not
+            considered when comparing or hashing `Issue` objects.
 
     Examples:
         ```{python}
@@ -31,3 +34,4 @@ class Issue:
     jsonpath: str
     type: str
     message: str
+    instance: Any = field(default=None, compare=False, hash=False)