ethyca-fides 2.68.1b0__py2.py3-none-any.whl → 2.68.1b1__py2.py3-none-any.whl

fides/api/task/conditional_dependencies/evaluator.py

@@ -1,15 +1,20 @@
-from typing import Any, Union
+from typing import Any, Optional, Union
 
 from loguru import logger
 from sqlalchemy.orm import Session
 
 from fides.api.graph.config import FieldPath
-from fides.api.task.conditional_dependencies.operators import operator_methods
+from fides.api.task.conditional_dependencies.operators import (
+    LOGICAL_OPERATORS,
+    OPERATOR_METHODS,
+)
 from fides.api.task.conditional_dependencies.schemas import (
     Condition,
+    ConditionEvaluationResult,
     ConditionGroup,
     ConditionLeaf,
-    GroupOperator,
+    EvaluationResult,
+    GroupEvaluationResult,
     Operator,
 )
 
@@ -19,84 +24,226 @@ class ConditionEvaluationError(Exception):
 
 
 class ConditionEvaluator:
-    """Evaluates nested conditions for manual task creation"""
+    """Evaluates nested conditions and returns a boolean result and a detailed evaluation report"""
 
     def __init__(self, db: Session):
         self.db = db
 
-    def evaluate_rule(self, rule: Condition, data: Union[dict, Any]) -> bool:
-        """Evaluate a nested condition rule against input data"""
+    def evaluate_rule(
+        self, rule: Condition, data: Union[dict, Any]
+    ) -> EvaluationResult:
+        """Evaluate a nested condition rule against input data and return detailed results
+
+        Args:
+            rule: The condition rule to evaluate
+            data: The data to evaluate the condition against
+
+        Returns:
+            evaluation report: A detailed report of the evaluation
+            - The field address of the condition
+            - The operator used in the condition
+            - The expected value of the condition
+            - The actual value of the condition
+            - The result of the condition evaluation
+            - A message describing the condition evaluation
+        """
         if isinstance(rule, ConditionLeaf):
-            return self._evaluate_leaf_condition(rule, data)
+            leaf_result = self._evaluate_leaf_condition(rule, data)
+            return leaf_result
         # ConditionGroup
-        return self._evaluate_group_condition(rule, data)
+        group_result = self._evaluate_group_condition(rule, data)
+        return group_result
 
     def _evaluate_leaf_condition(
         self, condition: ConditionLeaf, data: Union[dict, Any]
-    ) -> bool:
-        """Evaluate a leaf condition against input data"""
-        data_value = self._get_nested_value(data, condition.field_address.split("."))
-        # Apply operator and return result
-        return self._apply_operator(data_value, condition.operator, condition.value)
+    ) -> ConditionEvaluationResult:
+        """Evaluate a leaf condition against input data
+
+        Args:
+            condition: The leaf condition to evaluate
+            data: The data to evaluate the condition against
+
+        Returns:
+            A detailed evaluation report for the leaf condition
+
+        Raises:
+            ConditionEvaluationError: If there is an issue applying the operator or if an unexpected error occurs.
+        """
+        # Handle both colon-separated and dot-separated field addresses
+        if ":" in condition.field_address:
+            # Full field address like "dataset:collection:field" - split on colons
+            keys = condition.field_address.split(":")
+        else:
+            # Relative field path like "field.subfield" - split on dots
+            keys = condition.field_address.split(".")
+
+        data_value = self._get_nested_value(data, keys)
+
+        # Apply operator and get result
+        try:
+            result = self._apply_operator(
+                data_value, condition.operator, condition.value
+            )
+            message = f"Condition '{condition.field_address} {condition.operator} {condition.value}' evaluated to {result}"
+        except ConditionEvaluationError as e:
+            logger.error(
+                f"Unexpected error evaluating condition '{condition.field_address} {condition.operator} {condition.value}': {str(e)}"
+            )
+            raise
+
+        return ConditionEvaluationResult(
+            field_address=condition.field_address,
+            operator=condition.operator,
+            expected_value=condition.value,
+            actual_value=data_value,
+            result=result,
+            message=message,
+        )
 
     def _evaluate_group_condition(
         self, group: ConditionGroup, data: Union[dict, Any]
-    ) -> bool:
-        """Evaluate a group condition against input data"""
+    ) -> GroupEvaluationResult:
+        """Evaluate a group condition against input data
+
+        Args:
+            group: The group condition to evaluate
+            data: The data to evaluate the condition against
+
+        Returns:
+            A detailed evaluation report for the group condition
+
+        Raises:
+            ConditionEvaluationError: If there is an issue evaluating the group condition (e.g., from evaluate_rule calls)
+        """
+        try:
+            operator_func = LOGICAL_OPERATORS[group.logical_operator]
+        except KeyError as e:
+            raise ConditionEvaluationError(
+                f"Unknown logical operator: {group.logical_operator}"
+            ) from e
+
         results = [
             self.evaluate_rule(condition, data) for condition in group.conditions
         ]
+        group_result = operator_func([r.result for r in results])
+
+        return GroupEvaluationResult(
+            logical_operator=group.logical_operator,
+            condition_results=results,
+            result=group_result,
+        )
 
-        logical_operators = {GroupOperator.and_: all, GroupOperator.or_: any}
-        operator_func = logical_operators.get(group.logical_operator)
+    def _get_nested_value_from_fides_reference_structure(
+        self, data: Any, keys: list[str]
+    ) -> Optional[Any]:
+        """Get nested value from Fides reference structure
 
-        if operator_func is None:
-            logger.warning(f"Unknown logical operator: {group.logical_operator}")
-            return False
+        Args:
+            data: The Fides reference structure to get the nested value from
+            keys: The keys to for the specific nested value in the data
 
-        return operator_func(results)
+        Returns:
+            The nested value from the data or None if not a Fides reference structure
+
+        Raises:
+            AttributeError: If the data does not have a get_field_value method
+            ValueError: If the keys are not valid for the Fides reference structure
+        """
+        if hasattr(data, "get_field_value"):
+            try:
+                field_path = FieldPath(*keys) if len(keys) > 1 else FieldPath(keys[0])
+                return data.get_field_value(field_path)
+            except (AttributeError, ValueError):
+                logger.debug(
+                    f"Fides reference structure does not have a get_field_value method: {data}"
+                )
+                raise
+        raise ConditionEvaluationError(
+            f"Data does not have a get_field_value method: {data}"
+        )
+
+    def _get_nested_value_from_dict(self, data: dict, keys: list[str]) -> Optional[Any]:
+        """Get nested value from dictionary. This is the fallback and will return None if the key is not found.
+        When the data is missing the None value will work with exists/not_exists operations and correctly evaluate to False
+        for other operations like eq, not_eq, etc.
+
+        Args:
+            data: The dictionary to get the nested value from
+            keys: The keys to for the specific nested value in the data
+
+        Returns:
+            The nested value from the data
+
+        Raises:
+            KeyError: If the keys are not valid for the dictionary
+        """
+        current: Any = data
+        for key in keys:
+            if not isinstance(current, dict):
+                return None
+            current = current.get(key)
+            if current is None:
+                return None
+        return current
 
     def _get_nested_value(self, data: Union[dict, Any], keys: list[str]) -> Any:
-        """Get nested value from data using dot notation
+        """Get nested value from data using dot notation or colon notation
 
         Supports both simple dictionary access and Fides reference structures:
         - Simple dict: data["user"]["name"]
         - Fides FieldAddress: data.get_field_value(FieldAddress("dataset", "collection", "field_address"))
         - Fides Collection: data.get_field_value(FieldPath("field_address", "subfield"))
+
+        Also supports full field addresses with dataset:collection:field format
+
+        Args:
+            data: The data to get the nested value from
+            keys: The keys to for the specific nested value in the data
+
+        Returns:
+            The nested value from the data
+
+        Raises:
+            KeyError: If the keys are not valid for the dictionary
         """
         if not keys:
             return data
 
-        current = data
-
         # Try Fides reference structures first
-        if hasattr(current, "get_field_value"):
-            try:
-                field_path = FieldPath(*keys) if len(keys) > 1 else FieldPath(keys[0])
-                return current.get_field_value(field_path)
-            except (AttributeError, ValueError):
-                pass
-
-        # Fall back to dictionary access
-        for key in keys:
-            if not isinstance(current, dict):
-                current = current.get(key, {}) if hasattr(current, "get") else None
-            else:
-                current = current.get(key, {})
+        try:
+            return self._get_nested_value_from_fides_reference_structure(data, keys)
+        except (AttributeError, ValueError, ConditionEvaluationError):
+            pass
 
-        return current if current != {} else None
+        # Fall back to dictionary access for all path types
+        return self._get_nested_value_from_dict(data, keys)
 
     def _apply_operator(
         self, data_value: Any, operator: Operator, user_input_value: Any
     ) -> bool:
-        """Apply operator to actual and expected values"""
+        """Apply operator to actual and expected values
+        The operator is validated in the ConditionLeaf and ConditionGroup schemas,
+        so we don't need to validate it here.
 
+        Args:
+            data_value: The actual value to evaluate
+            operator: The operator to apply
+            user_input_value: The expected value to evaluate against
+
+        Returns:
+            The result of the operator applied to the actual and expected values
+        """
         # Get the method for the operator and execute it
-        operator_method = operator_methods.get(operator)
-        if operator_method is None:
-            logger.warning(f"Unknown operator: {operator}")
-            raise ConditionEvaluationError(f"Unknown operator: {operator}")
         try:
+            operator_method = OPERATOR_METHODS[operator]
             return operator_method(data_value, user_input_value)
-        except (TypeError, ValueError) as e:
-            raise ConditionEvaluationError(f"Error evaluating condition: {e}") from e
+        except KeyError as e:
+            # Unknown operator
+            logger.error(f"Unknown operator: {operator}")
+            raise ConditionEvaluationError(f"Unknown operator: {operator}") from e
+        except Exception as e:
+            # Log unexpected errors but still raise them
+            logger.error(f"Unexpected error in operator {operator}: {e}")
+            raise ConditionEvaluationError(
+                f"Unexpected error evaluating condition: {e}"
+            ) from e

fides/api/task/conditional_dependencies/logging_utils.py

@@ -0,0 +1,196 @@
+from typing import Optional, cast
+
+from fides.api.task.conditional_dependencies.schemas import (
+    ConditionEvaluationResult,
+    EvaluationResult,
+    GroupEvaluationResult,
+)
+
+MAX_DEPTH = 100
+
+
+def format_evaluation_success_message(
+    evaluation_result: Optional[EvaluationResult],
+) -> str:
+    """Format a detailed message about which conditions succeeded
+
+    Args:
+        evaluation_result: The evaluation result to create a string from
+
+    Returns:
+        A string describing the evaluation result
+
+    """
+    if not evaluation_result:
+        return "No conditional dependencies to evaluate."
+
+    return _format_evaluation_message(evaluation_result, success=True, depth=0)
+
+
+def format_evaluation_failure_message(
+    evaluation_result: Optional[EvaluationResult],
+) -> str:
+    """Format a detailed message about which conditions failed
+
+    Args:
+        evaluation_result: The evaluation result to create a string from
+
+    Returns:
+        A string describing the evaluation result
+    """
+    if not evaluation_result:
+        return "No conditional dependencies to evaluate."
+
+    return _format_evaluation_message(evaluation_result, success=False, depth=0)
+
+
+def _format_leaf_condition(evaluation_result: ConditionEvaluationResult) -> str:
+    """Format a single leaf condition into a readable string
+
+    Args:
+        evaluation_result: The conditionevaluation result to create a string from
+
+    Returns:
+        A string describing the evaluation result
+    """
+    condition_desc = f"{evaluation_result.field_address} {evaluation_result.operator}"
+    if evaluation_result.expected_value is not None:
+        condition_desc += f" {evaluation_result.expected_value}"
+    return condition_desc
+
+
+def _format_condition_list(
+    results: list[EvaluationResult], success: bool, depth: int
+) -> list[str]:
+    """Format a list of conditions (either leaf or group) into readable strings
+
+    Args:
+        results: The list of conditions to format
+        success: Whether the conditions were successful
+        depth: The depth of the conditions
+
+    Returns:
+        A list of strings describing the conditions
+    """
+    condition_descriptions = []
+    for sub_result in results:
+        if _is_leaf_condition(sub_result):
+            # Cast to the specific type after verification
+            leaf_result = cast(ConditionEvaluationResult, sub_result)
+            condition_descriptions.append(_format_leaf_condition(leaf_result))
+        elif _is_group_condition(sub_result):
+            # Cast to the specific type after verification
+            group_result = cast(GroupEvaluationResult, sub_result)
+            condition_descriptions.append(
+                _format_evaluation_message(group_result, success, depth + 1)
+            )
+    return condition_descriptions
+
+
+def _format_evaluation_message(
+    evaluation_result: EvaluationResult, success: bool, depth: int = 0
+) -> str:
+    """Format evaluation results into a readable message
+
+    Args:
+        evaluation_result: The evaluation result to format
+        success: Whether the conditions were successful
+        depth: The depth of the conditions
+
+    Returns:
+        A string describing the evaluation result
+    """
+    # Prevent infinite recursion
+    if depth > MAX_DEPTH:
+        return "Condition evaluation too deeply nested"
+
+    # Try to format as group condition first
+    if _is_group_condition(evaluation_result):
+        # Cast to the specific type after verification
+        group_result = cast(GroupEvaluationResult, evaluation_result)
+        return _format_group_condition(group_result, success, depth)
+
+    # Try to format as leaf condition
+    if _is_leaf_condition(evaluation_result):
+        # Cast to the specific type after verification
+        leaf_result = cast(ConditionEvaluationResult, evaluation_result)
+        return _format_leaf_condition_message(leaf_result, success)
+
+    # Unknown condition type
+    return "Evaluation result details unavailable"
+
+
+def _is_group_condition(evaluation_result: EvaluationResult) -> bool:
+    """Check if evaluation_result is a group condition by checking for group-specific attributes
+
+    Args:
+        evaluation_result: The evaluation result to check
+
+    Returns:
+        True if the evaluation result is a group condition, False otherwise
+    """
+    # Check for attributes that are unique to GroupEvaluationResult
+    return hasattr(evaluation_result, "logical_operator") and hasattr(
+        evaluation_result, "condition_results"
+    )
+
+
+def _is_leaf_condition(evaluation_result: EvaluationResult) -> bool:
+    """Check if evaluation_result is a leaf condition by checking for leaf-specific attributes
+
+    Args:
+        evaluation_result: The evaluation result to check
+
+    Returns:
+        True if the evaluation result is a leaf condition, False otherwise
+    """
+    # Check for attributes that are unique to ConditionEvaluationResult
+    return hasattr(evaluation_result, "field_address") and hasattr(
+        evaluation_result, "operator"
+    )
+
+
+def _format_group_condition(
+    evaluation_result: GroupEvaluationResult, success: bool, depth: int
+) -> str:
+    """Format a group condition evaluation result
+
+    Args:
+        evaluation_result: The group evaluation result to format
+        success: Whether the conditions were successful
+        depth: The depth of the conditions
+
+    Returns:
+        A string describing the evaluation result
+    """
+    logical_operator = evaluation_result.logical_operator
+    results = evaluation_result.condition_results
+    condition_descriptions = _format_condition_list(results, success, depth)
+
+    if success:
+        return f"All conditions in {logical_operator.upper()} group were met: {'; '.join(condition_descriptions)}"
+
+    if condition_descriptions:
+        return f"Failed conditions in {logical_operator.upper()} group: {'; '.join(condition_descriptions)}"
+
+    return f"Group condition with {logical_operator.upper()} operator failed"
+
+
+def _format_leaf_condition_message(
+    evaluation_result: ConditionEvaluationResult, success: bool
+) -> str:
+    """Format a leaf condition evaluation result
+
+    Args:
+        evaluation_result: The leaf evaluation result to format
+        success: Whether the conditions were successful
+
+    Returns:
+        A string describing the evaluation result
+    """
+    condition_desc = _format_leaf_condition(evaluation_result)
+
+    if success:
+        return f"Condition '{condition_desc}' was met"
+
+    return f"Condition '{condition_desc}' was not met"

fides/api/task/conditional_dependencies/operators.py

@@ -1,7 +1,7 @@
 import numbers
 import operator as py_operator
 
-from fides.api.task.conditional_dependencies.schemas import Operator
+from fides.api.task.conditional_dependencies.schemas import GroupOperator, Operator
 
 # Define operator methods for validation
 #
@@ -17,7 +17,7 @@ from fides.api.task.conditional_dependencies.schemas import Operator
 #   * None in [] returns False
 #   * None not in [] returns True
 #   * This allows None to be a valid list element for membership testing
-operator_methods = {
+OPERATOR_METHODS = {
     # Basic operators - handle None naturally using Python's built-in behavior
     Operator.exists: lambda a, _: a is not None,
     Operator.not_exists: lambda a, _: a is None,
@@ -103,6 +103,12 @@ operator_methods = {
     ),
 }
 
+# Define logical operators for group conditions
+LOGICAL_OPERATORS = {
+    GroupOperator.and_: all,
+    GroupOperator.or_: any,
+}
+
 # Common operators that work with most data types
 COMMON_OPERATORS = {
     Operator.eq,

fides/api/task/conditional_dependencies/schemas.py

@@ -1,5 +1,5 @@
 from enum import Enum
-from typing import List, Optional, Union
+from typing import Any, List, Optional, Union
 
 from pydantic import BaseModel, Field, model_validator
 
@@ -100,6 +100,30 @@ class ConditionGroup(BaseModel):
         return self
 
 
+# Evaluation result for a single condition
+class ConditionEvaluationResult(BaseModel):
+    field_address: str
+    operator: Operator
+    expected_value: Optional[
+        Union[str, int, float, bool, List[Union[str, int, float, bool]]]
+    ]
+    actual_value: Any
+    result: bool
+    message: str
+
+
+# Evaluation result for a group of conditions
+class GroupEvaluationResult(BaseModel):
+    logical_operator: GroupOperator
+    condition_results: list["EvaluationResult"]
+    result: bool
+
+
+# Union type for evaluation results
+EvaluationResult = Union[ConditionEvaluationResult, GroupEvaluationResult]
+
+
 # Use model_rebuild to allow recursive nesting
 Condition = Union[ConditionLeaf, ConditionGroup]
 ConditionGroup.model_rebuild()
+GroupEvaluationResult.model_rebuild()

fides/api/task/graph_task.py

@@ -437,13 +437,20 @@ class GraphTask(ABC):  # pylint: disable=too-many-instance-attributes
         self.update_status("retrying", [], action_type, ExecutionLogStatus.retrying)
 
     def log_awaiting_processing(
-        self, action_type: ActionType, ex: Optional[BaseException]
+        self,
+        action_type: ActionType,
+        ex: Optional[BaseException],
+        extra_message: Optional[str] = None,
     ) -> None:
         """On paused activities"""
         logger.info("Pausing node {}", self.key)
 
+        message = str(ex)
+        if extra_message:
+            message = f"{message}. {extra_message}"
+
         self.update_status(
-            str(ex), [], action_type, ExecutionLogStatus.awaiting_processing
+            message, [], action_type, ExecutionLogStatus.awaiting_processing
         )
 
     def log_skipped(self, action_type: ActionType, ex: str) -> None: