tallyfy 1.0.16__py3-none-any.whl

tallyfy/task_management/retrieval.py

@@ -0,0 +1,252 @@
+"""
+Task and process retrieval operations
+"""
+
+from typing import List, Optional
+from .base import TaskManagerBase
+from ..models import Task, Run, TasksList, RunsList, TallyfyError
+
+
+class TaskRetrieval(TaskManagerBase):
+    """Handles task and process retrieval operations"""
+
+    def get_my_tasks(self, org_id: str, page: int = 1, per_page: int = 100) -> TasksList:
+        """
+        Get all tasks assigned to the current user in the organization.
+
+        Args:
+            org_id: Organization ID
+            page: Page number (default: 1)
+            per_page: Number of results per page (default: 100)
+
+        Returns:
+            TasksList object containing tasks and pagination metadata (total count, etc.)
+
+        Raises:
+            TallyfyError: If the request fails
+        """
+        self._validate_org_id(org_id)
+
+        try:
+            endpoint = f"organizations/{org_id}/me/tasks"
+            params = self._build_query_params(page=page, per_page=per_page)
+            response_data = self.sdk._make_request('GET', endpoint, params=params)
+
+            # Return the structured response with pagination
+            return TasksList.from_dict(response_data)
+
+        except TallyfyError:
+            raise
+        except Exception as e:
+            self._handle_api_error(e, "get my tasks", org_id=org_id)
+
+    def get_user_tasks(self, org_id: str, user_id: int, page: int = 1, per_page: int = 100,
+                        sort_by: str = 'newest', status: str = 'all') -> TasksList:
+        """
+        Get all tasks assigned to the given user in the organization.
+
+        Args:
+            org_id: Organization ID
+            user_id: User ID
+            page: Page number (default: 1)
+            per_page: Number of results per page (default: 100)
+            sort_by: Sort order (default: 'newest')
+            status: Task status filter (default: 'all')
+
+        Returns:
+            TasksList object containing tasks and pagination metadata (total count, etc.)
+
+        Raises:
+            TallyfyError: If the request fails
+        """
+        self._validate_org_id(org_id)
+        self._validate_user_id(user_id)
+
+        try:
+            endpoint = f"organizations/{org_id}/users/{user_id}/tasks"
+            params = {
+                'page': str(page),
+                'per_page': str(per_page),
+                'sort_by': sort_by,
+                'status': status,
+                'with': 'run,threads_count,step,tags,folders,member_watchers.watcher'
+            }
+
+            response_data = self.sdk._make_request('GET', endpoint, params=params)
+
+            # Return the structured response with pagination
+            return TasksList.from_dict(response_data)
+
+        except TallyfyError:
+            raise
+        except Exception as e:
+            self._handle_api_error(e, "get user tasks", org_id=org_id, user_id=user_id)
+
+    def get_tasks_for_process(self, org_id: str, process_id: Optional[str] = None, process_name: Optional[str] = None,
+                           status: Optional[str] = None, sort: Optional[str] = None, with_: Optional[str] = None,
+                           owners: Optional[str] = None, groups: Optional[str] = None, guests: Optional[str] = None,
+                           page: int = 1, per_page: int = 100, current_task: Optional[str] = None,
+                           replace_page: Optional[int] = None, without_pagination: str = "false",
+                           deadline_start_range: Optional[str] = None, deadline_end_range: Optional[str] = None,
+                           unassigned: Optional[bool] = None) -> TasksList:
+        """
+        Get all tasks for a given process (run).
+
+        Args:
+            org_id: Organization ID
+            process_id: Process (run) ID to get tasks for
+            process_name: Process (run) name to get tasks for (alternative to process_id)
+            status: Filter by task status (complete, hasproblem, overdue, due_soon, active, active_visible, incomplete, inprogress, not-started)
+            sort: Sort by position or deadline (position, deadline, -position, -deadline)
+            with_: Additional data to retrieve (activities, run, run.checklist, step, form_fields, threads, comments, assets, summary)
+            owners: Search tasks assigned to specific members (comma-separated member IDs)
+            groups: Filter by Group ID
+            guests: Search tasks assigned to specific group (comma-separated group IDs)
+            page: Results page to retrieve (default: 1)
+            per_page: Tasks per page (default: 100)
+            current_task: Task ID
+            replace_page: Replace page
+            without_pagination: Results without pagination (true/false, default: false)
+            deadline_start_range: Deadline range starting date
+            deadline_end_range: Deadline range ending date
+            unassigned: Filter tasks with nobody assigned
+
+        Returns:
+            TasksList object containing tasks and pagination metadata (total count, etc.)
+
+        Raises:
+            TallyfyError: If the request fails
+            ValueError: If neither process_id nor process_name is provided
+        """
+        self._validate_org_id(org_id)
+
+        if not process_id and not process_name:
+            raise ValueError("Either process_id or process_name must be provided")
+
+        try:
+            # If process_name is provided but not process_id, search for the process first
+            if process_name and not process_id:
+                # We need to import TaskSearch here to avoid circular imports
+                from .search import TaskSearch
+                search = TaskSearch(self.sdk)
+                process_id = search.search_processes_by_name(org_id, process_name)
+
+            self._validate_process_id(process_id)
+
+            endpoint = f"organizations/{org_id}/runs/{process_id}/tasks"
+
+            # Build parameters using base class helper
+            params = self._build_query_params(
+                status=status,
+                sort=sort,
+                owners=owners,
+                groups=groups,
+                guests=guests,
+                page=page,
+                per_page=per_page,
+                currentTask=current_task,
+                replace_page=replace_page,
+                without_pagination=without_pagination,
+                deadline_start_range=deadline_start_range,
+                deadline_end_range=deadline_end_range,
+                unassigned=unassigned
+            )
+
+            # Handle the 'with' parameter specially due to Python keyword conflict
+            if with_:
+                params['with'] = with_
+
+            response_data = self.sdk._make_request('GET', endpoint, params=params)
+
+            # Return the structured response with pagination
+            return TasksList.from_dict(response_data)
+
+        except TallyfyError:
+            raise
+        except Exception as e:
+            self._handle_api_error(e, "get tasks for process", org_id=org_id, process_id=process_id, process_name=process_name)
+
+    def get_organization_runs(self, org_id: str, per_page: int = 100, page: int = 1, with_data: Optional[str] = None,
+                            form_fields_values: Optional[bool] = None,
+                            owners: Optional[str] = None, task_status: Optional[str] = None,
+                            groups: Optional[str] = None, status: Optional[str] = None,
+                            folder: Optional[str] = None, checklist_id: Optional[str] = None,
+                            starred: Optional[bool] = None, run_type: Optional[str] = None,
+                            tag: Optional[str] = None, sort: Optional[str] = None) -> RunsList:
+        """
+        Get all processes (runs) in the organization.
+
+        Args:
+            org_id: Organization ID
+            per_page: Results per page (default: 100)
+            page: Results page to retrieve (default: 1)
+            with_data: Comma-separated data to include (e.g., 'checklist,tasks,assets,tags')
+            form_fields_values: Include form field values
+            owners: Filter by specific member IDs
+            task_status: Filter by task status ('all', 'in-progress', 'completed')
+            groups: Filter by group IDs
+            status: Filter by process status ('active', 'problem', 'delayed', 'complete', 'archived')
+            folder: Filter by folder ID
+            checklist_id: Filter by template ID
+            starred: Filter by starred status
+            run_type: Filter by type ('procedure', 'form', 'document')
+            tag: Filter by tag ID
+            sort: Sort by creation date ('created_at', '-created_at')
+
+        Returns:
+            RunsList object containing runs and pagination metadata (total count, etc.)
+
+        Raises:
+            TallyfyError: If the request fails
+        """
+        self._validate_org_id(org_id)
+
+        try:
+            endpoint = f"organizations/{org_id}/runs"
+
+            # Build parameters using base class helper
+            params = self._build_query_params(
+                with_=with_data,  # Use with_ to avoid Python keyword conflict
+                form_fields_values=form_fields_values,
+                owners=owners,
+                task_status=task_status,
+                groups=groups,
+                status=status,
+                folder=folder,
+                checklist_id=checklist_id,
+                starred=starred,
+                type=run_type,  # API expects 'type' parameter
+                tag=tag,
+                sort=sort,
+                per_page=per_page,
+                page=page
+            )
+
+            # Handle the 'with' parameter specially due to Python keyword conflict
+            if with_data:
+                params['with'] = with_data
+                if 'with_' in params:
+                    del params['with_']
+
+            response_data = self.sdk._make_request('GET', endpoint, params=params)
+
+            # Return the structured response with pagination
+            return RunsList.from_dict(response_data)
+
+        except TallyfyError:
+            raise
+        except Exception as e:
+            self._handle_api_error(e, "get organization runs", org_id=org_id)
+
+    def get_organization_processes(self, org_id: str, **kwargs) -> RunsList:
+        """
+        Alias for get_organization_runs for better naming consistency.
+
+        Args:
+            org_id: Organization ID
+            **kwargs: Same parameters as get_organization_runs
+
+        Returns:
+            RunsList object containing runs and pagination metadata (total count, etc.)
+        """
+        return self.get_organization_runs(org_id, **kwargs)

tallyfy/task_management/search.py

@@ -0,0 +1,198 @@
+"""
+Task and process search operations
+"""
+
+from typing import List
+from .base import TaskManagerBase
+from ..models import SearchResult, SearchResultsList, TallyfyError
+
+
+class TaskSearch(TaskManagerBase):
+    """Handles task and process search operations"""
+
+    def search_processes_by_name(self, org_id: str, process_name: str) -> str:
+        """
+        Search for processes by name using the search endpoint.
+
+        Args:
+            org_id: Organization ID
+            process_name: Name or partial name of the process to search for
+
+        Returns:
+            Process ID of the found process
+
+        Raises:
+            TallyfyError: If no process found, multiple matches, or search fails
+        """
+        self._validate_org_id(org_id)
+        
+        if not process_name or not isinstance(process_name, str):
+            raise ValueError("Process name must be a non-empty string")
+        
+        try:
+            search_endpoint = f"organizations/{org_id}/search"
+            search_params = {
+                'on': 'process', 
+                'per_page': '20',
+                'search': process_name
+            }
+            
+            search_response = self.sdk._make_request('GET', search_endpoint, params=search_params)
+            
+            if isinstance(search_response, dict) and 'process' in search_response:
+                process_data = search_response['process']
+                if 'data' in process_data and process_data['data']:
+                    processes = process_data['data']
+                    
+                    # First try exact match (case-insensitive)
+                    exact_matches = [p for p in processes if p['name'].lower() == process_name.lower()]
+                    if exact_matches:
+                        return exact_matches[0]['id']
+                    elif len(processes) == 1:
+                        # Single search result, use it
+                        return processes[0]['id']
+                    else:
+                        # Multiple matches found, provide helpful error with options
+                        match_names = [f"'{p['name']}'" for p in processes[:5]]  # Show max 5
+                        raise TallyfyError(f"Multiple processes found matching '{process_name}': {', '.join(match_names)}. Please be more specific.")
+                else:
+                    raise TallyfyError(f"No process found matching name: {process_name}")
+            else:
+                raise TallyfyError(f"Search failed for process name: {process_name}")
+                
+        except TallyfyError:
+            raise
+        except Exception as e:
+            self._handle_api_error(e, "search processes by name", org_id=org_id, process_name=process_name)
+
+    def search(self, org_id: str, search_query: str, search_type: str = "process",
+                page: int = 1, per_page: int = 20) -> SearchResultsList:
+        """
+        Search for processes, templates, or tasks in the organization.
+
+        Args:
+            org_id: Organization ID
+            search_query: Text to search for
+            search_type: Type of search - 'process', 'blueprint', or 'task' (default: 'process'). blueprint equals template
+            page: Page number (default: 1)
+            per_page: Number of results per page (default: 20)
+
+        Returns:
+            SearchResultsList object containing results and pagination metadata (total count, etc.)
+
+        Raises:
+            TallyfyError: If the request fails
+            ValueError: If search_type is not valid
+        """
+        self._validate_org_id(org_id)
+
+        if not search_query or not isinstance(search_query, str):
+            raise ValueError("Search query must be a non-empty string")
+
+        # Validate search type
+        valid_types = ["process", "blueprint", "task"]
+        if search_type not in valid_types:
+            raise ValueError(f"Search type must be one of: {', '.join(valid_types)}")
+
+        if per_page <= 0 or per_page > 100:
+            raise ValueError("per_page must be between 1 and 100")
+
+        try:
+            endpoint = f"organizations/{org_id}/search"
+            params = {
+                'on': search_type,
+                'page': str(page),
+                'per_page': str(per_page),
+                'search': search_query
+            }
+
+            response_data = self.sdk._make_request('GET', endpoint, params=params)
+
+            # Return the structured response with pagination
+            return SearchResultsList.from_dict(response_data, search_type)
+
+        except TallyfyError:
+            raise
+        except Exception as e:
+            self._handle_api_error(e, "search", org_id=org_id, search_query=search_query, search_type=search_type)
+
+    def search_processes(self, org_id: str, search_query: str, page: int = 1, per_page: int = 20) -> SearchResultsList:
+        """
+        Search for processes in the organization.
+
+        Args:
+            org_id: Organization ID
+            search_query: Text to search for
+            page: Page number (default: 1)
+            per_page: Number of results per page (default: 20)
+
+        Returns:
+            SearchResultsList object containing results and pagination metadata (total count, etc.)
+
+        Raises:
+            TallyfyError: If the request fails
+        """
+        return self.search(org_id, search_query, "process", page, per_page)
+
+    def search_templates(self, org_id: str, search_query: str, page: int = 1, per_page: int = 20) -> SearchResultsList:
+        """
+        Search for templates (blueprints) in the organization.
+
+        Args:
+            org_id: Organization ID
+            search_query: Text to search for
+            page: Page number (default: 1)
+            per_page: Number of results per page (default: 20)
+
+        Returns:
+            SearchResultsList object containing results and pagination metadata (total count, etc.)
+
+        Raises:
+            TallyfyError: If the request fails
+        """
+        return self.search(org_id, search_query, "blueprint", page, per_page)
+
+    def search_tasks(self, org_id: str, search_query: str, page: int = 1, per_page: int = 20) -> SearchResultsList:
+        """
+        Search for tasks in the organization.
+
+        Args:
+            org_id: Organization ID
+            search_query: Text to search for
+            page: Page number (default: 1)
+            per_page: Number of results per page (default: 20)
+
+        Returns:
+            SearchResultsList object containing results and pagination metadata (total count, etc.)
+
+        Raises:
+            TallyfyError: If the request fails
+        """
+        return self.search(org_id, search_query, "task", page, per_page)
+
+    def find_process_by_name(self, org_id: str, process_name: str, exact_match: bool = True) -> List[SearchResult]:
+        """
+        Find processes by name with flexible matching options.
+
+        Args:
+            org_id: Organization ID
+            process_name: Name of the process to search for
+            exact_match: If True, only return exact matches (case-insensitive)
+
+        Returns:
+            List of SearchResult objects matching the criteria
+
+        Raises:
+            TallyfyError: If the request fails
+        """
+        results_list = self.search_processes(org_id, process_name)
+
+        if exact_match:
+            # Filter for exact matches (case-insensitive)
+            exact_results = []
+            for result in results_list.data:
+                if hasattr(result, 'name') and result.name.lower() == process_name.lower():
+                    exact_results.append(result)
+            return exact_results
+
+        return results_list.data

tallyfy/template_management/__init__.py

@@ -0,0 +1,85 @@
+"""
+Template Management Package
+
+This package provides a refactored, modular approach to template management
+functionality, breaking down the monolithic TemplateManagement class into
+specialized components for better maintainability and separation of concerns.
+
+Classes:
+    TemplateBasicOperations: CRUD operations for templates
+    TemplateAnalysis: Analysis and insights for templates
+    TemplateAutomation: Automation rule management
+    TemplateHealthAssessment: Comprehensive template health checks
+    TemplateManager: Unified interface combining all functionality
+"""
+
+from .base import TemplateManagerBase
+from .basic_operations import TemplateBasicOperations
+from .analysis import TemplateAnalysis
+from .automation import TemplateAutomation
+from .health_assessment import TemplateHealthAssessment
+
+
+class TemplateManager:
+    """
+    Unified interface for template management functionality.
+    
+    This class provides access to all template management capabilities
+    through a single interface while maintaining the modular structure
+    underneath.
+    """
+    
+    def __init__(self, sdk):
+        """
+        Initialize template manager with SDK instance.
+        
+        Args:
+            sdk: Main SDK instance
+        """
+        self.basic_operations = TemplateBasicOperations(sdk)
+        self.analysis = TemplateAnalysis(sdk)
+        self.automation = TemplateAutomation(sdk)
+        self.health_assessment = TemplateHealthAssessment(sdk)
+        
+        # For backward compatibility, expose common methods at the top level
+        self.search_templates_by_name = self.basic_operations.search_templates_by_name
+        self.get_template = self.basic_operations.get_template
+        self.get_all_templates = self.basic_operations.get_all_templates
+        self.update_template_metadata = self.basic_operations.update_template_metadata
+        self.get_template_with_steps = self.basic_operations.get_template_with_steps
+        self.duplicate_template = self.basic_operations.duplicate_template
+        self.get_template_steps = self.basic_operations.get_template_steps
+        self.edit_description_on_step = self.basic_operations.edit_description_on_step
+        self.add_step_to_template = self.basic_operations.add_step_to_template
+        
+        # Analysis methods
+        self.get_step_dependencies = self.analysis.get_step_dependencies
+        self.suggest_step_deadline = self.analysis.suggest_step_deadline
+        self.get_step_visibility_conditions = self.analysis.get_step_visibility_conditions
+        self.suggest_kickoff_fields = self.analysis.suggest_kickoff_fields
+        self.suggest_automation_consolidation = self.analysis.suggest_automation_consolidation
+        
+        # Automation methods
+        self.create_automation_rule = self.automation.create_automation_rule
+        self.update_automation_rule = self.automation.update_automation_rule
+        self.delete_automation_rule = self.automation.delete_automation_rule
+        self.consolidate_automation_rules = self.automation.consolidate_automation_rules
+        self.add_assignees_to_step = self.automation.add_assignees_to_step
+        self.analyze_template_automations = self.automation.analyze_template_automations
+        
+        # Health assessment method
+        self.assess_template_health = self.health_assessment.assess_template_health
+
+
+# For backward compatibility, create an alias
+TemplateManagement = TemplateManager
+
+__all__ = [
+    'TemplateManagerBase',
+    'TemplateBasicOperations', 
+    'TemplateAnalysis',
+    'TemplateAutomation',
+    'TemplateHealthAssessment',
+    'TemplateManager',
+    'TemplateManagement'  # Backward compatibility alias
+]