ethyca-fides 2.64.1b0__py2.py3-none-any.whl → 2.64.1b2__py2.py3-none-any.whl

fides/api/schemas/manual_tasks/manual_task_status.py

@@ -1,6 +1,6 @@
 from datetime import datetime, timezone
 from enum import Enum as EnumType
-from typing import Optional
+from typing import Optional, Protocol
 
 from sqlalchemy.orm import Session
 
@@ -23,61 +23,133 @@ class StatusType(str, EnumType):
 
     @classmethod
     def get_valid_transitions(cls, current_status: "StatusType") -> list["StatusType"]:
-        """Get valid transitions from the current status.
+        """Get valid transitions from the current status."""
+        transitions = {
+            cls.pending: [cls.in_progress, cls.failed, cls.completed],
+            cls.in_progress: [cls.completed, cls.failed],
+            cls.completed: [],
+            cls.failed: [cls.pending, cls.in_progress],
+        }
+        return transitions.get(current_status, [])
+
+
+class StatusTransitionProtocol(Protocol):
+    """Protocol for objects that support status transitions.
+
+    This protocol defines the interface that any object supporting status transitions
+    must implement. It includes both the required attributes and methods.
+
+    Example:
+        ```python
+        # Any class that implements this protocol can be used interchangeably
+        def process_status_update(obj: StatusTransitionProtocol, db: Session) -> None:
+            if obj.is_pending:
+                obj.start_progress(db)
+            elif obj.is_in_progress:
+                obj.mark_completed(db, user_id="user123")
+
+        # This works with ManualTaskInstance or any other class implementing the protocol
+        instance = ManualTaskInstance(...)
+        process_status_update(instance, db)
+        ```
+    """
 
-        Args:
-            current_status: The current status
+    # Required attributes - using runtime types that work with SQLAlchemy
+    status: StatusType
+    completed_at: Optional[datetime]  # Can be None when resetting to pending
+    completed_by_id: Optional[str]  # Can be None when resetting to pending
 
-        Returns:
-            list[StatusType]: List of valid transitions
-        """
-        if current_status == cls.pending:
-            return [cls.in_progress, cls.failed, cls.completed]
-        if current_status == cls.in_progress:
-            return [cls.completed, cls.failed]
-        if current_status == cls.completed:
-            return []
-        if current_status == cls.failed:
-            return [cls.pending, cls.in_progress]
-        return []
+    # Required methods
+    # pylint does not understand the Protocol abstract syntax and will complain about the ellipsis
+    def update_status(
+        self, db: Session, new_status: StatusType, user_id: Optional[str] = None
+    ) -> None:
+        """Update the status with validation and completion handling."""
+        ...  # pylint: disable=unnecessary-ellipsis
+
+    def mark_completed(self, db: Session, user_id: str) -> None:
+        """Mark as completed."""
+        ...  # pylint: disable=unnecessary-ellipsis
+
+    def mark_failed(self, db: Session) -> None:
+        """Mark as failed."""
+        ...  # pylint: disable=unnecessary-ellipsis
+
+    def start_progress(self, db: Session) -> None:
+        """Mark as in progress."""
+        ...  # pylint: disable=unnecessary-ellipsis
+
+    def reset_to_pending(self, db: Session) -> None:
+        """Reset to pending status."""
+        ...  # pylint: disable=unnecessary-ellipsis
+
+    @property
+    def is_completed(self) -> bool:
+        """Check if completed."""
+        ...  # pylint: disable=unnecessary-ellipsis
+
+    @property
+    def is_failed(self) -> bool:
+        """Check if failed."""
+        ...  # pylint: disable=unnecessary-ellipsis
+
+    @property
+    def is_in_progress(self) -> bool:
+        """Check if in progress."""
+        ...  # pylint: disable=unnecessary-ellipsis
+
+    @property
+    def is_pending(self) -> bool:
+        """Check if pending."""
+        ...  # pylint: disable=unnecessary-ellipsis
+
+
+def validate_status_transition_object(obj: StatusTransitionProtocol) -> bool:
+    """Validate that an object properly implements the StatusTransitionProtocol.
+
+    This function demonstrates how the Protocol can be used for runtime validation
+    and type checking.
+    """
+    required_attrs = ["status", "completed_at", "completed_by_id"]
+    required_methods = [
+        "update_status",
+        "mark_completed",
+        "mark_failed",
+        "start_progress",
+        "reset_to_pending",
+    ]
+    required_properties = ["is_completed", "is_failed", "is_in_progress", "is_pending"]
+
+    # Check all required elements
+    all_required = required_attrs + required_methods + required_properties
+    return all(hasattr(obj, attr) for attr in all_required) and all(
+        callable(getattr(obj, method)) for method in required_methods
+    )
 
 
 class StatusTransitionMixin:
     """Mixin for handling status transitions.
 
     This mixin provides methods for managing status transitions and completion tracking.
-    It can be used by any model that needs status management.
+    It implements the StatusTransitionProtocol and can be used by any model that needs status management.
     """
 
-    # These should be overridden by the implementing class
+    # Type annotations to match the Protocol
     status: StatusType
     completed_at: Optional[datetime]
     completed_by_id: Optional[str]
 
     def _get_valid_transitions(self) -> list[StatusType]:
-        """Get valid transitions from the current status.
-
-        Returns:
-            list[StatusType]: List of valid transitions
-        """
+        """Get valid transitions from the current status."""
         return StatusType.get_valid_transitions(self.status)
 
     def _validate_status_transition(self, new_status: StatusType) -> None:
-        """Validate that a status transition is allowed.
-
-        Args:
-            new_status: The new status to transition to
-
-        Raises:
-            StatusTransitionNotAllowed: If the transition is not allowed
-        """
-        # Don't allow transitions to the same status
+        """Validate that a status transition is allowed."""
         if new_status == self.status:
             raise StatusTransitionNotAllowed(
                 f"Invalid status transition: already in status {new_status}"
             )
 
-        # Get valid transitions for current status
         valid_transitions = self._get_valid_transitions()
         if new_status not in valid_transitions:
             raise StatusTransitionNotAllowed(
@@ -88,13 +160,7 @@ class StatusTransitionMixin:
     def update_status(
         self, db: Session, new_status: StatusType, user_id: Optional[str] = None
     ) -> None:
-        """Update the status with validation and completion handling.
-
-        Args:
-            db: Database session
-            new_status: New status to set
-            user_id: Optional user ID who is making the change
-        """
+        """Update the status with validation and completion handling."""
         self._validate_status_transition(new_status)
 
         if new_status == StatusType.completed:
@@ -110,12 +176,7 @@ class StatusTransitionMixin:
         db.commit()
 
     def mark_completed(self, db: Session, user_id: str) -> None:
-        """Mark as completed.
-
-        Args:
-            db: Database session
-            user_id: user ID who completed the task
-        """
+        """Mark as completed."""
         self.update_status(db, StatusType.completed, user_id)
 
     def mark_failed(self, db: Session) -> None:

fides/api/service/connectors/postgres_connector.py

@@ -37,7 +37,7 @@ class PostgreSQLConnector(SQLConnector):
         netloc = config.host
         port = f":{config.port}" if config.port else ""
         dbname = f"/{config.dbname}" if config.dbname else ""
-        query = f"?sslmode=${config.ssl_mode}" if config.ssl_mode else ""
+        query = f"?sslmode={config.ssl_mode}" if config.ssl_mode else ""
         return f"postgresql://{user_password}{netloc}{port}{dbname}{query}"
 
     def build_ssh_uri(self, local_address: tuple) -> str:
@@ -54,7 +54,7 @@ class PostgreSQLConnector(SQLConnector):
         netloc = local_host
         port = f":{local_port}" if local_port else ""
         dbname = f"/{config.dbname}" if config.dbname else ""
-        query = f"?sslmode=${config.ssl_mode}" if config.ssl_mode else ""
+        query = f"?sslmode={config.ssl_mode}" if config.ssl_mode else ""
         return f"postgresql://{user_password}{netloc}{port}{dbname}{query}"
 
     # Overrides SQLConnector.create_client

fides/common/api/v1/urn_registry.py

@@ -155,6 +155,10 @@ AUTHORIZE = "/connection/{connection_key}/authorize"
 ACCESS_MANUAL_WEBHOOKS = "/access_manual_webhook"
 ACCESS_MANUAL_WEBHOOK = CONNECTION_BY_KEY + "/access_manual_webhook"
 
+# Manual Tasks
+MANUAL_TASKS = "/manual-tasks"
+MANUAL_TASK = CONNECTION_BY_KEY + "/manual-task"
+
 # Collection URLs
 DATASETS = "/dataset"
 DATASET_CONFIG = "/datasetconfig"

fides/service/manual_tasks/manual_task_config_service.py

@@ -15,6 +15,14 @@ from fides.api.schemas.manual_tasks.manual_task_config import (
 from fides.service.manual_tasks.utils import validate_fields, with_task_logging
 
 
+class ManualTaskConfigError(Exception):
+    """Exception raised when a manual task config error occurs."""
+
+    def __init__(self, message: str):
+        self.message = message
+        super().__init__(self.message)
+
+
 class ManualTaskConfigService:
     def __init__(self, db: Session):
         self.db = db
@@ -51,8 +59,8 @@ class ManualTaskConfigService:
         """
         try:
             ManualTaskConfigurationType(config_type)
-        except ValueError:
-            raise ValueError(f"Invalid config type: {config_type}")
+        except ManualTaskConfigError:
+            raise ManualTaskConfigError(f"Invalid config type: {config_type}")
 
         # Set all existing versions to non-current
         if is_current:
@@ -96,7 +104,11 @@ class ManualTaskConfigService:
         modified_keys = set(fields_to_remove or [])
 
         if field_updates:
-            validate_fields(field_updates, is_submission=False)
+            try:
+                validate_fields(field_updates, is_submission=False)
+            except ValueError as e:
+                raise ManualTaskConfigError(f"Invalid field updates: {e}") from e
+
             fields_to_create = [
                 {
                     "task_id": config.task_id,
@@ -167,7 +179,7 @@ class ManualTaskConfigService:
         )
 
         if not config:
-            raise ValueError(
+            raise ManualTaskConfigError(
                 f"No current config found for task {task.id} and type {config_type}"
             )
         return config
@@ -355,7 +367,7 @@ class ManualTaskConfigService:
         """
         config = self.db.query(ManualTaskConfig).filter_by(id=config_id).first()
         if not config:
-            raise ValueError(f"Config with ID {config_id} not found")
+            raise ManualTaskConfigError(f"Config with ID {config_id} not found")
 
         log_data = self._create_log_data(
             task.id,

fides/service/manual_tasks/manual_task_instance_service.py

@@ -0,0 +1,285 @@
+from typing import Any, Optional
+
+from loguru import logger
+from sqlalchemy.orm import Session
+
+from fides.api.models.attachment import Attachment
+from fides.api.models.manual_tasks.manual_task_config import ManualTaskConfigField
+from fides.api.models.manual_tasks.manual_task_instance import (
+    ManualTaskInstance,
+    ManualTaskSubmission,
+)
+from fides.api.schemas.manual_tasks.manual_task_status import (
+    StatusTransitionNotAllowed,
+    StatusType,
+)
+from fides.service.manual_tasks.utils import validate_fields, with_task_logging
+
+
+class ManualTaskInstanceError(Exception):
+    """Exception raised when a manual task instance error occurs."""
+
+    def __init__(self, message: str):
+        self.message = message
+        super().__init__(self.message)
+
+
+class ManualTaskSubmissionError(Exception):
+    """Exception raised when a manual task submission error occurs."""
+
+    def __init__(self, message: str):
+        self.message = message
+        super().__init__(self.message)
+
+
+class ManualTaskInstanceService:
+    def __init__(self, db: Session):
+        self.db = db
+
+    def _create_log_data(
+        self,
+        task_id: str,
+        config_id: str,
+        instance_id: str,
+        details: dict[str, Any],
+    ) -> dict[str, Any]:
+        """Create standard log data structure."""
+        return {
+            "task_id": task_id,
+            "config_id": config_id,
+            "instance_id": instance_id,
+            "details": details,
+        }
+
+    def _get_instance(
+        self, instance_id: str, allow_completed: bool = False
+    ) -> ManualTaskInstance:
+        """Get and validate instance."""
+        instance = self.db.query(ManualTaskInstance).filter_by(id=instance_id).first()
+        if not instance:
+            raise ManualTaskInstanceError(f"Instance with ID {instance_id} not found")
+
+        if not allow_completed and instance.status == StatusType.completed:
+            raise StatusTransitionNotAllowed(
+                "Instance is already completed, no further changes allowed"
+            )
+
+        return instance
+
+    def _get_field(
+        self, field_id: str, validate_data: Optional[dict[str, Any]] = None
+    ) -> ManualTaskConfigField:
+        """Get and validate field."""
+        field = ManualTaskConfigField.get_by_key_or_id(
+            db=self.db, data={"id": field_id}
+        )
+        if not field:
+            raise ManualTaskInstanceError(f"Field with ID {field_id} not found")
+
+        if validate_data:
+            try:
+                validate_fields([validate_data], is_submission=True)
+            except ValueError as e:
+                raise ManualTaskInstanceError(f"Invalid field data: {e}") from e
+
+        return field
+
+    def _update_instance_status(
+        self,
+        instance: ManualTaskInstance,
+        new_status: Optional[StatusType] = None,
+        user_id: Optional[str] = None,
+        silent: bool = False,
+    ) -> None:
+        """Update instance status with optional error suppression."""
+        try:
+            if not new_status:
+                new_status = (
+                    StatusType.in_progress
+                    if instance.submissions
+                    else StatusType.pending
+                )
+            instance.update_status(self.db, new_status, user_id)
+        except StatusTransitionNotAllowed as e:
+            if not silent:
+                raise
+            logger.info(f"Status not transitioning: {e}")
+
+    @with_task_logging("Created task instance")
+    def create_instance(
+        self, task_id: str, config_id: str, entity_id: str, entity_type: str
+    ) -> tuple[ManualTaskInstance, dict[str, Any]]:
+        """Create a new instance for an entity."""
+        instance = ManualTaskInstance.create(
+            self.db,
+            data={
+                "task_id": task_id,
+                "config_id": config_id,
+                "entity_id": entity_id,
+                "entity_type": entity_type,
+            },
+        )
+        return instance, self._create_log_data(
+            task_id, config_id, instance.id, {"entity_type": entity_type}
+        )
+
+    def get_submission_for_field(
+        self, instance_id: str, field_id: str
+    ) -> Optional[ManualTaskSubmission]:
+        """Get the submission for a specific field."""
+        return self._get_instance(instance_id).get_submission_for_field(field_id)
+
+    @with_task_logging("Updated task instance status")
+    def update_status(
+        self,
+        instance_id: str,
+        new_status: Optional[StatusType] = None,
+        user_id: Optional[str] = None,
+    ) -> tuple[ManualTaskInstance, dict[str, Any]]:
+        """Update instance status with logging."""
+        instance = self._get_instance(instance_id)
+        previous_status = instance.status
+        self._update_instance_status(instance, new_status, user_id)
+
+        return instance, self._create_log_data(
+            instance.task_id,
+            instance.config_id,
+            instance.id,
+            {
+                "previous_status": previous_status,
+                "new_status": instance.status,
+                "user_id": user_id,
+            },
+        )
+
+    @with_task_logging("Created task submission")
+    def create_submission(
+        self,
+        instance_id: str,
+        field_id: str,
+        data: dict[str, Any],
+    ) -> tuple[ManualTaskSubmission, dict[str, Any]]:
+        """Create a new submission for a field."""
+        instance = self._get_instance(instance_id)
+        field = self._get_field(field_id, data)
+
+        if instance.get_submission_for_field(field_id):
+            raise ManualTaskInstanceError(
+                f"Submission for field {field.field_key} already exists for instance {instance.id}"
+            )
+
+        submission = ManualTaskSubmission.create(
+            self.db,
+            data={
+                "task_id": instance.task_id,
+                "config_id": instance.config_id,
+                "instance_id": instance.id,
+                "field_id": field.id,
+                "data": data,
+            },
+        )
+
+        # Update instance status to in_progress
+        self._update_instance_status(instance, StatusType.in_progress, silent=True)
+
+        return submission, self._create_log_data(
+            instance.task_id,
+            instance.config_id,
+            instance.id,
+            {
+                "field_key": field.field_key,
+                "field_type": field.field_type,
+            },
+        )
+
+    @with_task_logging("Updated task submission")
+    def update_submission(
+        self,
+        instance_id: str,
+        submission_id: str,
+        data: dict[str, Any],
+    ) -> tuple[ManualTaskSubmission, dict[str, Any]]:
+        """Update a submission for a field."""
+        instance = self._get_instance(instance_id)
+        submission = next(
+            (s for s in instance.submissions if s.id == submission_id),
+            None,
+        )
+        if not submission or not submission.field_id:
+            raise ManualTaskSubmissionError(
+                f"Valid submission with ID {submission_id} not found"
+            )
+
+        field = self._get_field(submission.field_id, data)
+        submission.update(self.db, data={"data": data})
+        self._update_instance_status(instance, silent=True)
+
+        return submission, self._create_log_data(
+            instance.task_id,
+            instance.config_id,
+            instance.id,
+            {
+                "field_key": field.field_key,
+                "field_type": field.field_type,
+            },
+        )
+
+    @with_task_logging("Delete task attachment")
+    def delete_attachment_by_id(
+        self,
+        submission_id: str,
+        attachment_id: str,
+    ) -> None:
+        """Delete an attachment for a field."""
+        submission = (
+            self.db.query(ManualTaskSubmission).filter_by(id=submission_id).first()
+        )
+        if not submission:
+            raise ManualTaskSubmissionError(
+                f"Submission with ID {submission_id} does not exist"
+            )
+
+        self._get_instance(
+            submission.instance_id
+        )  # Validates instance is not completed
+
+        attachment = self.db.query(Attachment).filter_by(id=attachment_id).first()
+        if not attachment or attachment not in submission.attachments:
+            raise ManualTaskSubmissionError(
+                f"Attachment {attachment_id} not found in submission {submission_id}"
+            )
+
+        # Delete attachment and optionally submission
+        if (
+            len(submission.attachments) == 1
+            and submission.field.field_type == "attachment"
+        ):
+            attachment.delete(self.db)
+            submission.delete(self.db)
+        else:
+            attachment.delete(self.db)
+
+    @with_task_logging("Completed task instance")
+    def complete_task_instance(
+        self, task_id: str, config_id: str, instance_id: str, user_id: str
+    ) -> tuple[ManualTaskInstance, dict[str, Any]]:
+        """Complete a task instance."""
+        instance = self._get_instance(instance_id)
+
+        missing_fields = [
+            field.field_key
+            for field in instance.required_fields
+            if not instance.get_submission_for_field(field.id)
+        ]
+        if missing_fields:
+            raise StatusTransitionNotAllowed(
+                f"Cannot complete task instance. Missing required fields: {', '.join(missing_fields)}"
+            )
+
+        instance.update_status(self.db, StatusType.completed, user_id)
+        instance.completed_by_id = user_id
+        instance.save(self.db)
+
+        return instance, self._create_log_data(
+            task_id, config_id, instance_id, {"completed_by": user_id}
+        )