feat: ✨ add check_properties()

ruff.toml

@@ -1,5 +1,5 @@
-# Support Python 3.10+
-target-version = "py310"
+# Support Python 3.12+
+target-version = "py312"
 
 # In addition to the default formatters/linters, add these as well.
 [lint]

seedcase_sprout/core/checks/__init__.py

@@ -0,0 +1,23 @@
+"""Check functions and constants for the Frictionless Data Package standard."""
+
+from .check_error import CheckError
+from .check_package_properties import check_package_properties
+from .check_properties import check_properties
+from .check_resource_properties import check_resource_properties
+from .required_fields import (
+    PACKAGE_RECOMMENDED_FIELDS,
+    PACKAGE_REQUIRED_FIELDS,
+    RESOURCE_REQUIRED_FIELDS,
+    RequiredFieldType,
+)
+
+__all__ = [
+    "CheckError",
+    "check_properties",
+    "check_package_properties",
+    "check_resource_properties",
+    "PACKAGE_RECOMMENDED_FIELDS",
+    "PACKAGE_REQUIRED_FIELDS",
+    "RESOURCE_REQUIRED_FIELDS",
+    "RequiredFieldType",
+]

seedcase_sprout/core/checks/add_package_recommendations.py

@@ -1,4 +1,7 @@
 from seedcase_sprout.core.checks.config import NAME_PATTERN, SEMVER_PATTERN
+from seedcase_sprout.core.checks.required_fields import (
+    PACKAGE_RECOMMENDED_FIELDS,
+)
 
 
 def add_package_recommendations(schema: dict) -> dict:
@@ -12,7 +15,7 @@ def add_package_recommendations(schema: dict) -> dict:
     Returns:
         The updated Data Package schema.
     """
-    schema["required"].extend(["name", "id", "licenses"])
+    schema["required"].extend(PACKAGE_RECOMMENDED_FIELDS.keys())
     schema["properties"]["name"]["pattern"] = NAME_PATTERN
     schema["properties"]["version"]["pattern"] = SEMVER_PATTERN
     schema["properties"]["contributors"]["items"]["required"] = ["title"]

seedcase_sprout/core/checks/check_error.py

@@ -0,0 +1,89 @@
+from functools import total_ordering
+
+
+@total_ordering
+class CheckError(Exception):
+    """Raised or returned when a properties object fails a single check."""
+
+    def __init__(
+        self,
+        message: str,
+        json_path: str,
+        validator: str,
+    ):
+        """Initialises CheckError.
+
+        Args:
+            message: The error message.
+            json_path: The path to the JSON field within the enclosing JSON object where
+                the error occurred.
+            validator: The name of the validator that failed.
+        """
+        self.message = message
+        self.json_path = json_path
+        self.validator = validator
+        super().__init__(self.__str__())
+
+    def __eq__(self, other: object) -> bool:
+        """Checks if this error is equal to an object.
+
+        Args:
+            other: The object to compare.
+
+        Returns:
+            If the objects are equal.
+        """
+        if not isinstance(other, CheckError):
+            return NotImplemented
+        return (
+            self.message == other.message
+            and self.json_path == other.json_path
+            and self.validator == other.validator
+        )
+
+    def __lt__(self, other: object) -> bool:
+        """Checks if this error is less than an object.
+
+        Args:
+            other: The object to compare.
+
+        Returns:
+            The result of the comparison.
+        """
+        if not isinstance(other, CheckError):
+            return NotImplemented
+        return (self.json_path, self.validator, self.message) < (
+            other.json_path,
+            other.validator,
+            other.message,
+        )
+
+    def __hash__(self) -> int:
+        """Returns a hash for this error.
+
+        Returns:
+            The hash.
+        """
+        return hash((self.message, self.json_path, self.validator))
+
+    def __str__(self) -> str:
+        """Returns a user-friendly string representation of the error.
+
+        Returns:
+            The string representation.
+        """
+        return (
+            f"Error at `{self.json_path}` caused by `{self.validator}`: {self.message}"
+        )
+
+    def __repr__(self) -> str:
+        """Returns a developer-friendly, unambiguous representation of the error.
+
+        Returns:
+            The developer-friendly representation.
+        """
+        return (
+            f"CheckError(message={self.message!r}, "
+            f"json_path={self.json_path!r}, "
+            f"validator={self.validator!r})"
+        )

seedcase_sprout/core/checks/check_object_against_json_schema.py

@@ -1,9 +1,14 @@
-from jsonschema import Draft7Validator, FormatChecker, ValidationError
+from jsonschema import Draft7Validator, FormatChecker
+
+from seedcase_sprout.core.checks.check_error import CheckError
+from seedcase_sprout.core.checks.validation_errors_to_check_errors import (
+    validation_errors_to_check_errors,
+)
 
 
 def check_object_against_json_schema(
     json_object: dict, schema: dict
-) -> list[ValidationError]:
+) -> list[CheckError]:
     """Checks that `json_object` matches the given JSON schema.
 
     Structural, type and format constraints are all checked. All schema violations are
@@ -21,4 +26,4 @@ def check_object_against_json_schema(
     """
     Draft7Validator.check_schema(schema)
     validator = Draft7Validator(schema, format_checker=FormatChecker())
-    return list(validator.iter_errors(json_object))
+    return validation_errors_to_check_errors(validator.iter_errors(json_object))

seedcase_sprout/core/checks/check_package_properties.py

@@ -1,8 +1,7 @@
-from jsonschema import ValidationError
-
 from seedcase_sprout.core.checks.add_package_recommendations import (
     add_package_recommendations,
 )
+from seedcase_sprout.core.checks.check_error import CheckError
 from seedcase_sprout.core.checks.check_object_against_json_schema import (
     check_object_against_json_schema,
 )
@@ -14,7 +13,7 @@
 
 def check_package_properties(
     properties: dict, check_recommendations: bool = True
-) -> list[ValidationError]:
+) -> list[CheckError]:
     """Checks that `properties` matches the Data Package standard (v2.0).
 
     Only package properties are checked. Schema constraints for resource properties are

seedcase_sprout/core/checks/check_properties.py

@@ -1,11 +1,10 @@
-from jsonschema import ValidationError
-
 from seedcase_sprout.core.checks.add_package_recommendations import (
     add_package_recommendations,
 )
 from seedcase_sprout.core.checks.add_resource_recommendations import (
     add_resource_recommendations,
 )
+from seedcase_sprout.core.checks.check_error import CheckError
 from seedcase_sprout.core.checks.check_object_against_json_schema import (
     check_object_against_json_schema,
 )
@@ -15,7 +14,7 @@
 
 def check_properties(
     properties: dict, check_recommendations: bool = True
-) -> list[ValidationError]:
+) -> list[CheckError]:
     """Checks that `properties` matches the Data Package standard (v2.0).
 
     Both package and resource properties are checked. Structural, type and format

seedcase_sprout/core/checks/check_resource_properties.py

@@ -1,8 +1,7 @@
-from jsonschema import ValidationError
-
 from seedcase_sprout.core.checks.add_resource_recommendations import (
     add_resource_recommendations,
 )
+from seedcase_sprout.core.checks.check_error import CheckError
 from seedcase_sprout.core.checks.check_object_against_json_schema import (
     check_object_against_json_schema,
 )
@@ -12,7 +11,7 @@
 
 def check_resource_properties(
     properties: dict, check_recommendations: bool = True
-) -> list[ValidationError]:
+) -> list[CheckError]:
     """Checks that the resource `properties` matches the Data Resource standard (v2.0).
 
     This function expects an individual set of resource properties as input. Structural,

seedcase_sprout/core/checks/get_full_json_path_from_error.py

@@ -0,0 +1,21 @@
+import re
+
+from jsonschema import ValidationError
+
+
+def get_full_json_path_from_error(error: ValidationError) -> str:
+    """Returns the full `json_path` to the error.
+
+    For 'required' errors, the field name is extracted from the error message.
+
+    Args:
+        error: The error to get the full `json_path` for.
+
+    Returns:
+        The full`json_path` of the error.
+    """
+    if error.validator == "required":
+        match = re.search("'(.*)' is a required property", error.message)
+        if match:
+            return f"{error.json_path}.{match.group(1)}"
+    return error.json_path

seedcase_sprout/core/checks/required_fields.py

@@ -0,0 +1,28 @@
+from enum import Enum
+
+# Data Package standard required fields and their types
+
+
+class RequiredFieldType(str, Enum):
+    """A class enumerating allowed types for required fields."""
+
+    str = "str"
+    list = "list"
+    any = "any"
+
+
+PACKAGE_REQUIRED_FIELDS = {
+    "resources": RequiredFieldType.list,
+}
+
+PACKAGE_RECOMMENDED_FIELDS = {
+    "name": RequiredFieldType.str,
+    "id": RequiredFieldType.str,
+    "licenses": RequiredFieldType.list,
+}
+
+RESOURCE_REQUIRED_FIELDS = {
+    "name": RequiredFieldType.str,
+    "path": RequiredFieldType.str,
+    "data": RequiredFieldType.any,
+}

seedcase_sprout/core/checks/unwrap_errors.py

@@ -0,0 +1,18 @@
+from jsonschema import ValidationError
+
+
+def unwrap_errors(errors: list[ValidationError]) -> list[ValidationError]:
+    """Recursively extracts all errors into a flat list of errors.
+
+    Args:
+        errors: A nested list of errors.
+
+    Returns:
+        A flat list of errors.
+    """
+    unwrapped = []
+    for error in errors:
+        unwrapped.append(error)
+        if error.context:
+            unwrapped.extend(unwrap_errors(error.context))
+    return unwrapped

seedcase_sprout/core/checks/validation_errors_to_check_errors.py

@@ -0,0 +1,41 @@
+from typing import Iterator
+
+from jsonschema import ValidationError
+
+from seedcase_sprout.core.checks.check_error import CheckError
+from seedcase_sprout.core.checks.get_full_json_path_from_error import (
+    get_full_json_path_from_error,
+)
+from seedcase_sprout.core.checks.unwrap_errors import unwrap_errors
+
+COMPLEX_VALIDATORS = {"allOf", "anyOf", "oneOf"}
+
+
+def validation_errors_to_check_errors(
+    validation_errors: Iterator[ValidationError],
+) -> list[CheckError]:
+    """Transforms `jsonschema.ValidationError`s to more compact `CheckError`s.
+
+    The list of errors is:
+
+      - flattened
+      - filtered for summary-type errors
+      - filtered for duplicates
+      - sorted by error location
+
+    Args:
+        validation_errors: The `jsonschema.ValidationError`s to transform.
+
+    Returns:
+        A list of `CheckError`s.
+    """
+    check_errors = [
+        CheckError(
+            message=error.message,
+            json_path=get_full_json_path_from_error(error),
+            validator=error.validator,
+        )
+        for error in unwrap_errors(list(validation_errors))
+        if error.validator not in COMPLEX_VALIDATORS
+    ]
+    return sorted(set(check_errors))

seedcase_sprout/core/sprout_checks/check_data_path_string.py

@@ -0,0 +1,29 @@
+from seedcase_sprout.core.checks.check_error import CheckError
+from seedcase_sprout.core.sprout_checks.get_json_path_to_resource_field import (
+    get_json_path_to_resource_field,
+)
+
+
+def check_data_path_string(
+    properties: dict, index: int | None = None
+) -> list[CheckError]:
+    """Checks that the `path` field of a set of resource properties is of type string.
+
+    Args:
+        properties: The resource properties.
+        index: The index of the resource properties. Defaults to None.
+
+    Returns:
+        A list of errors. An empty list if no error was found.
+    """
+    path = properties.get("path", "")
+    if isinstance(path, str):
+        return []
+
+    return [
+        CheckError(
+            message=f"{path} is not of type 'string'",
+            json_path=get_json_path_to_resource_field("path", index),
+            validator="type",
+        )
+    ]