fw-gear-session-validator 0.2.2__py3-none-any.whl

fw_gear_session_validator/__init__.py

@@ -0,0 +1,8 @@
+"""The fw_gear_{{gear_package}} package."""
+
+from importlib.metadata import version
+
+try:
+    __version__ = version(__package__)
+except:  # noqa: E722
+    pass

fw_gear_session_validator/errors.py

@@ -0,0 +1,322 @@
+"""
+Simple JSONSchema Error Handler
+
+A lightweight approach that extracts key error information
+
+This approach:
+1. Extracts validator type
+2. Extracts schema path
+3. Extracts instance path
+4. Cleans error.message by removing instance representation
+5. Extracts description from schema by walking up schema path
+
+"""
+
+from typing import Any, Dict, Optional, Sequence, Tuple
+
+from jsonschema.exceptions import ValidationError
+
+
+def _resolve_path(root: Any, path: Sequence[Any]) -> Any:
+    """Resolve a path within a nested data structure.
+
+    Args:
+        root: The root data structure (dict/list)
+        path: Sequence of keys/indices to traverse
+
+    Returns:
+        The value at the specified path
+    """
+    node = root
+    for key in path:
+        node = node[key]
+    return node
+
+
+def nearest_description(
+    schema_root: dict, abs_schema_path: Sequence[Any]
+) -> Tuple[Optional[str], Optional[Sequence[Any]]]:
+    """Find the nearest description by walking up the schema path.
+
+    JSONSchema validators may fail at a node that doesn't have a description,
+    but a parent node (e.g., an allOf element) often does. This function
+    walks up from the failing node to find the nearest description.
+
+    Args:
+        schema_root: The root schema dictionary
+        abs_schema_path: The absolute schema path from the validation error
+
+    Returns:
+        Tuple of (description string or None, path where found or None)
+    """
+    # Start at the failing node and walk up to the root
+    for i in range(len(abs_schema_path), -1, -1):
+        sub_path = abs_schema_path[:i]
+        try:
+            node = _resolve_path(schema_root, sub_path)
+        except (KeyError, IndexError, TypeError):
+            continue
+
+        if isinstance(node, dict):
+            desc = node.get("description")
+            if isinstance(desc, str) and desc.strip():
+                return desc, sub_path
+
+    return None, None
+
+
+def create_simple_error_message(
+    error: ValidationError, schema_root: Optional[dict] = None
+) -> Dict[str, Any]:
+    """
+    Create a simple, clean error message from ValidationError.
+
+    This extracts the essential information and cleans the error message
+    by removing the instance representation that causes 1MB messages.
+
+    Args:
+        error: ValidationError from jsonschema
+        schema_root: The root schema dictionary (optional, for description extraction)
+
+    Returns:
+        Dict with keys:
+            - error_message: Cleaned error message without instance repr
+            - instance_path: Path in the data where error occurred
+            - label: Human-facing label (falls back to $ref)
+            - description: Human-readable description from schema (if found)
+            - schema_definition: Tail of validator_value[$ref] if present
+            - schema_path: Path in the schema where error occurred
+            - validator_type: Dict with 'type' and 'details' (details vary by type)
+            - validator_value: The constraint value from schema
+    """
+    # 1. Extract validator type
+    validator_type_str = error.validator
+
+    # 2. Extract schema path (where in schema the error is defined)
+    schema_path = list(error.absolute_schema_path)
+    schema_path_str = ".".join(str(p) for p in schema_path) if schema_path else "root"
+
+    # 3. Extract instance path (where in data the error occurred)
+    instance_path = list(error.absolute_path)
+    instance_path_str = (
+        ".".join(str(p) for p in instance_path) if instance_path else "root"
+    )
+
+    # 4. Get error message
+    original_message = error.message
+
+    # 5. Clean the message by removing instance representation
+    cleaned_message = clean_error_message(original_message, error.instance)
+
+    # 6. Extract validator value
+    validator_value = error.validator_value
+
+    # 7. Extract $ref and schema_definition if present
+    # NOTE: schema_definition is only populated when validator_value contains a $ref.
+    # For direct constraints (e.g., maximum: -9, pattern: "^[A-Z]+$"), schema_definition
+    # will remain None since they don't reference a definition.
+    schema_definition = None
+    label = None
+    if isinstance(validator_value, dict) and "$ref" in validator_value:
+        ref_value = validator_value["$ref"]
+        # Extract definition name from $ref path (e.g., "#/$defs/T1_acquisition" -> "T1_acquisition")
+        if "/" in ref_value:
+            schema_definition = ref_value.split("/")[-1]
+        else:
+            schema_definition = ref_value
+        label = schema_definition  # Use definition as label
+
+    # 8. Generate label if not already set
+    if label is None:
+        label = _generate_label(validator_type_str, validator_value, instance_path)
+
+    # 9. Build validator_type with details
+    validator_type_obj = {
+        "type": validator_type_str,
+        "details": _extract_validator_details(error),
+    }
+
+    # 10. Extract description from schema by walking up the schema path
+    description = None
+    if schema_root is not None:
+        description, _ = nearest_description(schema_root, schema_path)
+
+    # 11. Build result
+    result = {
+        "error_message": cleaned_message,
+        "instance_path": instance_path_str,
+        "label": label,
+        "schema_path": schema_path_str,
+        "validator_type": validator_type_obj,
+        "validator_value": validator_value,
+    }
+
+    # Add schema_definition if present
+    if schema_definition is not None:
+        result["schema_definition"] = schema_definition
+
+    # Add description if found
+    if description is not None:
+        result["description"] = description
+
+    return result
+
+
+def clean_error_message(message: str, instance: Any) -> str:
+    """
+    Clean error message by removing the instance representation.
+
+    JSONSchema error messages often follow patterns like:
+        "<instance repr> <description>"
+        "None of <instance repr> are valid under the given schema"
+
+    This function removes the instance repr part.
+
+    Args:
+        message: Original error message from jsonschema
+        instance: The instance value that failed validation
+
+    Returns:
+        Cleaned error message
+    """
+    # NEW SIMPLIFIED APPROACH: Remove instance repr from message
+    instance_repr = repr(instance)
+
+    # Check if instance repr is in the message
+    if instance_repr in message:
+        # Replace the instance repr with a placeholder
+        if isinstance(instance, list):
+            placeholder = f"[array of {len(instance)} items]"
+        elif isinstance(instance, dict):
+            placeholder = f"{{object with {len(instance)} keys}}"
+        else:
+            placeholder = f"<{type(instance).__name__}>"
+
+        message = message.replace(instance_repr, placeholder)
+
+    return message
+
+
+def _extract_validator_details(error: ValidationError) -> Dict[str, Any]:  # noqa: PLR0912
+    """
+    Extract validator-specific details using a hybrid approach:
+    - Custom logic for validators that need special handling
+    - Dynamic extraction of all constraint keywords from schema
+
+    Args:
+        error: ValidationError from jsonschema
+
+    Returns:
+        Dict with details extracted from error and schema
+    """
+    validator_type = error.validator
+    validator_value = error.validator_value
+    instance = error.instance
+    schema = error.schema
+
+    details = {}
+
+    # Step 1: Custom handling for validators that need special logic
+    if validator_type == "required":
+        # Calculate which specific fields are missing
+        if isinstance(validator_value, list) and isinstance(instance, dict):
+            missing = [field for field in validator_value if field not in instance]
+            details["missing"] = missing
+
+    elif validator_type == "type":
+        # Show expected vs found type
+        details["expected"] = validator_value
+        details["found"] = type(instance).__name__
+
+    elif validator_type == "pattern":
+        # Show pattern and preview of actual value
+        details["pattern"] = validator_value
+        if isinstance(instance, str):
+            details["preview"] = instance[:50]  # First 50 chars
+
+    elif validator_type in ("anyOf", "oneOf", "allOf"):
+        # Count number of alternatives
+        if isinstance(validator_value, list):
+            details["alternatives"] = len(validator_value)
+
+    elif validator_type == "enum":
+        # Show allowed values
+        details["allowed_values"] = validator_value
+        details["found"] = instance
+
+    elif validator_type == "const":
+        # Show expected constant value
+        details["expected"] = validator_value
+        details["found"] = instance
+
+    # Step 2: Add instance size/length if applicable
+    if isinstance(instance, (list, dict, str)):
+        if "found" not in details:  # Don't overwrite if already set
+            details["found"] = len(instance)
+
+    # Step 3: DYNAMIC EXTRACTION - Get all constraint keywords from schema
+    # Exclude structural/metadata keys that don't represent constraints
+    metadata_keys = {
+        "$schema",
+        "$id",
+        "$ref",
+        "$defs",
+        "definitions",
+        "title",
+        "description",
+        "examples",
+        "default",
+        "comment",
+        "type",
+        "properties",
+        "items",
+        "additionalProperties",
+        "patternProperties",
+        "additionalItems",
+        "required",
+    }
+
+    if isinstance(schema, dict):
+        for key, value in schema.items():
+            # Only add if:
+            # 1. Not a metadata/structural key
+            # 2. Not already in details (don't overwrite custom logic)
+            # 3. Not the current validator's keyword (avoid duplication with validator_value)
+            if (
+                key not in metadata_keys
+                and key not in details
+                and key != validator_type
+            ):
+                details[key] = value
+
+    return details
+
+
+def _generate_label(
+    validator_type: str, validator_value: Any, instance_path: list
+) -> str:
+    """
+    Generate a human-facing label for the error.
+
+    Args:
+        validator_type: Type of validator that failed
+        validator_value: The constraint value
+        instance_path: Path to the instance that failed
+
+    Returns:
+        Human-readable label string
+    """
+    # Use the last element of instance_path if available
+    if instance_path:
+        return str(instance_path[-1])
+
+    # Fallback to validator type
+    if validator_type == "required":
+        if isinstance(validator_value, list) and validator_value:
+            return f"missing_{validator_value[0]}"
+    elif validator_type == "type":
+        return "type_mismatch"
+    elif validator_type == "contains":
+        return "contains_validation"
+
+    return validator_type

fw_gear_session_validator/main.py

@@ -0,0 +1,104 @@
+"""Main module."""
+
+import json
+import logging
+from pathlib import Path
+from typing import Tuple
+
+import flywheel
+from flywheel import Client as FWClient
+
+from fw_gear_session_validator.parser import RunOptions
+from fw_gear_session_validator.pdf_report import generate_pdf_report
+from fw_gear_session_validator.session import build_session_dict
+from fw_gear_session_validator.utils import (
+    check_for_qc_tags,
+    handle_existing_qc_tags,
+    save_report,
+    tag_session_qc_result,
+)
+from fw_gear_session_validator.validation import validate_json, validate_schema
+
+log = logging.getLogger(__name__)
+
+
+def run(
+    destination: dict,
+    output_dir: Path,
+    schema_path: Path,
+    client: FWClient,
+    options: RunOptions,
+) -> Tuple[int, list[dict], flywheel.Session]:
+    """Run the session validation.
+
+    Args:
+        destination: The destination container information.
+        output_dir: The output directory for saving reports.
+        schema_path: Path to the validation schema file.
+        client: The Flywheel client to interact with the API.
+        options: RunOptions with configurations and optional PDF links.
+
+    Returns:
+        Tuple
+            e_code (int): Exit code of the run.
+            validation_report (list[dict]): The validation report.
+            session_ (flywheel.Session): The Flywheel session object.
+
+    """
+
+    # Grab the destination container and parent to make sure we are at the
+    # session level
+    run_level = destination.parent["type"]
+    if run_level != "session":
+        raise RuntimeError(
+            f"Cannot run at {run_level} level. Please run at session level."
+        )
+
+    session_id = destination.parent["id"]
+    session_ = client.get_session(session_id)
+    log.info(f"Checking if session {session_.label} needs validation.")
+
+    # Check for existing session-validator tags
+    qc_tags = check_for_qc_tags(session_)
+    # If session is already validated, log and exit
+    if not handle_existing_qc_tags(session_, qc_tags, options.force_rerun):
+        return None, None, None
+
+    # Check if schema is valid
+    log.debug(f"Loading schema from {schema_path}")
+    with open(schema_path, "r") as schema_file:
+        schema = json.load(schema_file)
+    log.info("Validating schema...")
+    if not validate_schema(schema):
+        raise ValueError("Invalid JSON schema. Please check the schema file.")
+
+    log.info(f"Validating session {session_.label}.")
+
+    # Build session dictionary for validation
+    log.debug("Building session dictionary.")
+    session_dict = build_session_dict(session_)
+
+    validation_report, validation_report_meta = validate_json(session_dict, schema)
+
+    if options.save_validation_report:
+        log.info("Validation complete. Saving JSON report.")
+        save_report(output_dir, validation_report)
+    else:
+        log.info("Validation complete. Not saving JSON report as per configuration.")
+
+    if options.save_pdf_report:
+        log.info("Generating PDF report.")
+        generate_pdf_report(
+            output_dir, session_.label, validation_report, options.pdf_links
+        )
+    else:
+        log.info("Not generating PDF report as per configuration.")
+
+    # Tag session as PASS or FAIL
+    log.info("Tagging session with QC result.")
+    tag_session_qc_result(session_, passed=not len(validation_report))
+
+    # Return error code
+    # Return validation_report and session container for creating
+    # qc metadata object in run.py
+    return 0, validation_report_meta, session_

fw_gear_session_validator/parser.py

@@ -0,0 +1,138 @@
+"""Parser module to parse gear config.json."""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional, Tuple
+
+from fw_gear import GearContext as GearToolkitContext
+
+
+@dataclass(frozen=True)
+class PdfLinks:
+    """PDF report link metadata."""
+
+    session_path: str
+    job_url: str
+    session_url: str
+    schema_url: str
+    schema_filename: str
+    schema_version: int
+
+
+@dataclass(frozen=True)
+class RunOptions:
+    """Configuration options."""
+
+    save_validation_report: bool = False
+    save_pdf_report: bool = False
+    force_rerun: bool = False
+    pdf_links: Optional[PdfLinks] = None
+
+    def validate(self) -> None:
+        """Validate options."""
+        if self.save_pdf_report and self.pdf_links is None:
+            raise ValueError("save_pdf_report=True requires pdf_links.")
+
+
+def build_pdf_links(gear_context: GearToolkitContext, destination: dict) -> PdfLinks:
+    """Build all PDF report link metadata.
+
+    Constructs session path, job URL, session URL, and schema info for PDF reports.
+
+    Args:
+        gear_context: The gear context containing client and config info.
+        destination: The destination analysis container.
+
+    Returns:
+        PdfLinks dataclass with all link metadata.
+    """
+    client = gear_context.client
+    session_id = destination.parent["id"]
+    session = client.get_session(session_id)
+
+    # Extract site URL (shared across all URL builders)
+    api_host = client._fw.api_client.configuration.host
+    site_url = api_host.rsplit("/api", 1)[0]
+
+    # Build session path: fw://group/project/subject/session
+    group = session.parents.group
+    project = client.get_project(session.parents.project)
+    subject = client.get_subject(session.parents.subject)
+    session_path = f"fw://{group}/{project.label}/{subject.label}/{session.label}"
+
+    # Build job URL
+    job_id = gear_context.config.job.get("id")
+    job_url = f"{site_url}/#/jobs/{job_id}" if job_id else ""
+
+    # Build session URL
+    session_url = (
+        f"{site_url}/#/projects/{session.parents.project}/sessions/{session_id}"
+    )
+
+    # Build schema info
+    schema_url, schema_filename, schema_version = "", "", 0
+    schema_input = gear_context.config.get_input("validation_schema")
+    if schema_input:
+        container_type = schema_input.get("hierarchy", {}).get("type", "")
+        container_id = schema_input.get("hierarchy", {}).get("id", "")
+        schema_filename = schema_input.get("location", {}).get("name", "")
+        file_id = schema_input.get("object", {}).get("file_id", "")
+
+        if file_id and container_id:
+            try:
+                file_info = client.get_file(file_id)
+                schema_version = getattr(file_info, "version", 0)
+            except Exception:
+                pass  # Version is optional
+
+        if container_type and container_id:
+            schema_url = f"{site_url}/#/{container_type}s/{container_id}"
+
+    return PdfLinks(
+        session_path=session_path,
+        job_url=job_url,
+        session_url=session_url,
+        schema_url=schema_url,
+        schema_filename=schema_filename,
+        schema_version=schema_version,
+    )
+
+
+def parse_config(
+    gear_context: GearToolkitContext,
+) -> Tuple[dict, Path, Path, RunOptions]:
+    """Parse context config.json object.
+
+    Args:
+        gear_context (GearToolkitContext): The gear context containing configuration.
+
+    Returns:
+        tuple:
+            destination: The destination container information.
+            output_dir: The output directory for saving reports.
+            schema_path: Path to the validation schema file.
+            options: RunOptions with flags and optional PDF links.
+    """
+    save_validation_report = gear_context.config.opts.get(
+        "save_validation_report", False
+    )
+    force_rerun = gear_context.config.opts.get("force_rerun", False)
+    save_pdf_report = gear_context.config.opts.get("save_pdf_report", False)
+    schema_path = gear_context.config.get_input_path("validation_schema")
+    if not schema_path:
+        raise ValueError("Validation schema is required.")
+
+    destination = gear_context.client.get_analysis(
+        gear_context.config.destination["id"]
+    )
+
+    pdf_links = build_pdf_links(gear_context, destination) if save_pdf_report else None
+
+    options = RunOptions(
+        save_validation_report=save_validation_report,
+        save_pdf_report=save_pdf_report,
+        force_rerun=force_rerun,
+        pdf_links=pdf_links,
+    )
+
+    return destination, Path(gear_context.output_dir), Path(schema_path), options