tallyfy 1.0.16__py3-none-any.whl

tallyfy/organization_management/__init__.py

@@ -0,0 +1,26 @@
+"""
+Organization management module for Tallyfy SDK
+"""
+
+from .base import OrganizationManagerBase
+from .retrieval import OrganizationRetrieval
+
+class OrganizationManager(OrganizationRetrieval):
+    """
+    Complete organization management interface combining all functionality.
+    
+    This class provides access to:
+    - Organization retrieval operations
+    
+    Example:
+        >>> from tallyfy import TallyfySDK
+        >>> sdk = TallyfySDK(api_key="your_api_key")
+        >>> orgs = sdk.organizations.get_current_user_organizations()
+        >>> print(f"User belongs to {len(orgs.data)} organizations")
+    """
+    pass
+
+# Maintain backward compatibility
+OrganizationManagement = OrganizationManager
+
+__all__ = ['OrganizationManager', 'OrganizationManagement', 'OrganizationRetrieval', 'OrganizationManagerBase']

tallyfy/organization_management/base.py

@@ -0,0 +1,76 @@
+"""
+Base class for organization management operations
+"""
+
+import logging
+from typing import Dict, Any, List, Optional
+from ..models import TallyfyError
+
+
+class OrganizationManagerBase:
+    """Base class providing common functionality for organization management operations"""
+
+    def __init__(self, sdk):
+        """
+        Initialize the organization manager base.
+        
+        Args:
+            sdk: The main Tallyfy SDK instance
+        """
+        self.sdk = sdk
+        self.logger = logging.getLogger(f"{__name__}.{self.__class__.__name__}")
+
+    def _extract_data(self, response_data: Dict[str, Any], default_empty: bool = True) -> Any:
+        """
+        Extract data from API response.
+        
+        Args:
+            response_data: Raw API response
+            default_empty: Return empty list if no data found
+            
+        Returns:
+            Extracted data
+        """
+        if not response_data:
+            return [] if default_empty else None
+            
+        # Handle direct data responses
+        if 'data' in response_data:
+            return response_data['data']
+        
+        # Handle responses where the main content is directly available
+        # This is common for single item responses
+        return response_data if not default_empty else []
+
+    def _handle_api_error(self, error: Exception, operation: str, **context) -> None:
+        """
+        Handle and log API errors consistently.
+        
+        Args:
+            error: The exception that occurred
+            operation: Description of the operation that failed
+            **context: Additional context for debugging
+        """
+        context_str = ", ".join([f"{k}={v}" for k, v in context.items()])
+        error_message = f"Failed to {operation}"
+        if context_str:
+            error_message += f" ({context_str})"
+        
+        self.logger.error(f"{error_message}: {str(error)}")
+        
+        if isinstance(error, TallyfyError):
+            raise error
+        else:
+            raise TallyfyError(f"{error_message}: {str(error)}")
+
+    def _build_query_params(self, **kwargs) -> Dict[str, Any]:
+        """
+        Build query parameters for API requests.
+        
+        Args:
+            **kwargs: Parameters to include in the query string
+            
+        Returns:
+            Dictionary of query parameters with None values filtered out
+        """
+        return {key: value for key, value in kwargs.items() if value is not None}

tallyfy/organization_management/retrieval.py

@@ -0,0 +1,39 @@
+"""
+Organization retrieval operations
+"""
+
+from typing import List, Optional
+from .base import OrganizationManagerBase
+from ..models import Organization, OrganizationsList, TallyfyError
+
+
+class OrganizationRetrieval(OrganizationManagerBase):
+    """Handles organization retrieval operations"""
+
+    def get_current_user_organizations(self, page: int = 1, per_page: int = 10) -> OrganizationsList:
+        """
+        Get all organizations the current member is a part of.
+
+        Args:
+            page: Page number (default: 1)
+            per_page: Number of results per page (default: 10, max: 100)
+
+        Returns:
+            OrganizationsList object containing organizations and pagination metadata
+
+        Raises:
+            TallyfyError: If the request fails
+        """
+        try:
+            endpoint = "me/organizations"
+            params = self._build_query_params(page=page, per_page=min(per_page, 100))
+            
+            response_data = self.sdk._make_request('GET', endpoint, params=params)
+
+            # Return the structured response with pagination
+            return OrganizationsList.from_dict(response_data)
+
+        except TallyfyError:
+            raise
+        except Exception as e:
+            self._handle_api_error(e, "get my organizations", page=page, per_page=per_page)

tallyfy/task_management/__init__.py

@@ -0,0 +1,81 @@
+"""
+Task Management Package
+
+This package provides a refactored, modular approach to task management
+functionality, breaking down the monolithic TaskManagement class into
+specialized components for better maintainability and separation of concerns.
+
+Classes:
+    TaskRetrieval: Task and process retrieval operations
+    TaskSearch: Search operations for tasks, processes, and templates  
+    TaskCreation: Task creation operations
+    TaskManager: Unified interface combining all functionality
+"""
+
+from .base import TaskManagerBase
+from .retrieval import TaskRetrieval
+from .search import TaskSearch
+from .creation import TaskCreation
+
+
+class TaskManager:
+    """
+    Unified interface for task management functionality.
+    
+    This class provides access to all task management capabilities
+    through a single interface while maintaining the modular structure
+    underneath.
+    """
+    
+    def __init__(self, sdk):
+        """
+        Initialize task manager with SDK instance.
+        
+        Args:
+            sdk: Main SDK instance
+        """
+        self.retrieval = TaskRetrieval(sdk)
+        self._search_service = TaskSearch(sdk)  # Use private name to avoid conflict
+        self.creation = TaskCreation(sdk)
+        
+        # For backward compatibility, expose common methods at the top level
+        
+        # Retrieval methods
+        self.get_my_tasks = self.retrieval.get_my_tasks
+        self.get_user_tasks = self.retrieval.get_user_tasks
+        self.get_tasks_for_process = self.retrieval.get_tasks_for_process
+        self.get_organization_runs = self.retrieval.get_organization_runs
+        self.get_organization_processes = self.retrieval.get_organization_processes
+        
+        # Search methods
+        self.search_processes_by_name = self._search_service.search_processes_by_name
+        self.search = self._search_service.search  # Main search method for backward compatibility
+        self.search_processes = self._search_service.search_processes
+        self.search_templates = self._search_service.search_templates
+        self.search_tasks = self._search_service.search_tasks
+        self.find_process_by_name = self._search_service.find_process_by_name
+        
+        # Creation methods
+        self.create_task = self.creation.create_task
+        self.create_simple_task = self.creation.create_simple_task
+        self.create_user_task = self.creation.create_user_task
+        self.create_guest_task = self.creation.create_guest_task
+        self.create_group_task = self.creation.create_group_task
+    
+    @property
+    def search_service(self):
+        """Access to the TaskSearch service object for advanced search operations."""
+        return self._search_service
+
+
+# For backward compatibility, create an alias
+TaskManagement = TaskManager
+
+__all__ = [
+    'TaskManagerBase',
+    'TaskRetrieval', 
+    'TaskSearch',
+    'TaskCreation',
+    'TaskManager',
+    'TaskManagement'  # Backward compatibility alias
+]

tallyfy/task_management/base.py

@@ -0,0 +1,125 @@
+"""
+Base class for task management operations
+"""
+
+from typing import Optional, List, Dict, Any
+from ..models import TallyfyError
+
+
+class TaskManagerBase:
+    """Base class providing common functionality for task management"""
+    
+    def __init__(self, sdk):
+        """
+        Initialize base task manager.
+        
+        Args:
+            sdk: Main SDK instance
+        """
+        self.sdk = sdk
+    
+    def _validate_org_id(self, org_id: str) -> None:
+        """
+        Validate organization ID parameter.
+        
+        Args:
+            org_id: Organization ID to validate
+            
+        Raises:
+            ValueError: If org_id is invalid
+        """
+        if not org_id or not isinstance(org_id, str):
+            raise ValueError("Organization ID must be a non-empty string")
+    
+    def _validate_user_id(self, user_id: int) -> None:
+        """
+        Validate user ID parameter.
+        
+        Args:
+            user_id: User ID to validate
+            
+        Raises:
+            ValueError: If user_id is invalid
+        """
+        if not isinstance(user_id, int) or user_id <= 0:
+            raise ValueError("User ID must be a positive integer")
+    
+    def _validate_process_id(self, process_id: str) -> None:
+        """
+        Validate process ID parameter.
+        
+        Args:
+            process_id: Process ID to validate
+            
+        Raises:
+            ValueError: If process_id is invalid
+        """
+        if not process_id or not isinstance(process_id, str):
+            raise ValueError("Process ID must be a non-empty string")
+    
+    def _extract_data(self, response_data, data_key: Optional[str] = None) -> List[Dict[str, Any]]:
+        """
+        Extract data from API response.
+        
+        Args:
+            response_data: Raw response from API
+            data_key: Optional key to extract from response (e.g., 'process', 'blueprint')
+            
+        Returns:
+            Extracted data list or empty list
+        """
+        if isinstance(response_data, dict):
+            if data_key and data_key in response_data:
+                # Handle search responses with specific keys
+                nested_data = response_data[data_key]
+                if isinstance(nested_data, dict) and 'data' in nested_data:
+                    return nested_data['data']
+                elif isinstance(nested_data, list):
+                    return nested_data
+            elif 'data' in response_data:
+                return response_data['data']
+            return []
+        elif isinstance(response_data, list):
+            return response_data
+        return []
+    
+    def _handle_api_error(self, error: Exception, operation: str, **context) -> None:
+        """
+        Handle API errors with context.
+        
+        Args:
+            error: The exception that occurred
+            operation: Description of the operation that failed
+            **context: Additional context for error logging
+        """
+        context_str = ", ".join([f"{k}={v}" for k, v in context.items()])
+        error_msg = f"Failed to {operation}"
+        if context_str:
+            error_msg += f" ({context_str})"
+        error_msg += f": {error}"
+        
+        self.sdk.logger.error(error_msg)
+        
+        if isinstance(error, TallyfyError):
+            raise error
+        else:
+            raise TallyfyError(error_msg)
+    
+    def _build_query_params(self, **kwargs) -> Dict[str, Any]:
+        """
+        Build query parameters from keyword arguments, filtering out None values.
+        
+        Args:
+            **kwargs: Keyword arguments to convert to query parameters
+            
+        Returns:
+            Dictionary of non-None parameters
+        """
+        params = {}
+        for key, value in kwargs.items():
+            if value is not None:
+                if isinstance(value, bool):
+                    params[key] = 'true' if value else 'false'
+                else:
+                    params[key] = str(value)
+        return params

tallyfy/task_management/creation.py

@@ -0,0 +1,221 @@
+"""
+Task creation operations
+"""
+
+from typing import Optional
+from .base import TaskManagerBase
+from ..models import Task, TaskOwners, TallyfyError
+from email_validator import validate_email, EmailNotValidError
+
+
+class TaskCreation(TaskManagerBase):
+    """Handles task creation operations"""
+
+    def create_task(self, org_id: str, title: str, deadline: str,
+                   owners: TaskOwners, description: Optional[str] = None,
+                   max_assignable: Optional[int] = None, prevent_guest_comment: Optional[bool] = None) -> Optional[Task]:
+        """
+        Create a standalone task in the organization.
+
+        Args:
+            org_id: Organization ID
+            title: Task name (required)
+            deadline: Task deadline in "YYYY-mm-dd HH:ii:ss" format
+            owners: TaskOwners object with users, guests, and groups
+            description: Task description (optional)
+            max_assignable: Maximum number of assignees (optional)
+            prevent_guest_comment: Prevent guests from commenting (optional)
+
+        Returns:
+            Task object for the created task
+
+        Raises:
+            TallyfyError: If the request fails
+            ValueError: If required parameters are missing or invalid
+        """
+        self._validate_org_id(org_id)
+        
+        if not title or not isinstance(title, str):
+            raise ValueError("Task title must be a non-empty string")
+
+        if not deadline or not isinstance(deadline, str):
+            raise ValueError("Task deadline must be a non-empty string in 'YYYY-mm-dd HH:ii:ss' format")
+
+        # Validate that at least one assignee is provided
+        if not owners or not isinstance(owners, TaskOwners):
+            raise ValueError("TaskOwners object is required")
+            
+        if not owners.users and not owners.guests and not owners.groups:
+            raise ValueError("At least one assignee is required (users, guests, or groups)")
+
+        # Validate max_assignable if provided
+        if max_assignable is not None and (not isinstance(max_assignable, int) or max_assignable <= 0):
+            raise ValueError("max_assignable must be a positive integer")
+
+        try:
+            endpoint = f"organizations/{org_id}/tasks"
+
+            task_data = {
+                "title": title,
+                "deadline": deadline,
+                "owners": {
+                    "users": owners.users or [],
+                    "guests": owners.guests or [],
+                    "groups": owners.groups or []
+                },
+                "task_type": "task",
+                "separate_task_for_each_assignee": True,
+                "status": "not-started",
+                "everyone_must_complete": False,
+                "is_soft_start_date": True
+            }
+
+            # Add optional fields
+            if description:
+                task_data["description"] = description
+            if max_assignable is not None:
+                task_data["max_assignable"] = max_assignable
+            if prevent_guest_comment is not None:
+                task_data["prevent_guest_comment"] = prevent_guest_comment
+
+            response_data = self.sdk._make_request('POST', endpoint, data=task_data)
+
+            task_response_data = self._extract_data(response_data)
+            if task_response_data:
+                # Handle both single task and list responses
+                if isinstance(task_response_data, list) and task_response_data:
+                    return Task.from_dict(task_response_data[0])
+                elif isinstance(task_response_data, dict):
+                    return Task.from_dict(task_response_data)
+            
+            # Check if response_data itself is the task data
+            if isinstance(response_data, dict) and 'data' in response_data:
+                task_data_response = response_data['data']
+                if isinstance(task_data_response, dict):
+                    return Task.from_dict(task_data_response)
+            
+            self.sdk.logger.warning("Unexpected response format for task creation")
+            return None
+
+        except TallyfyError:
+            raise
+        except Exception as e:
+            self._handle_api_error(e, "create task", org_id=org_id, title=title)
+
+    def create_simple_task(self, org_id: str, title: str, deadline: str, user_ids: Optional[list] = None, 
+                          guest_emails: Optional[list] = None, group_ids: Optional[list] = None,
+                          description: Optional[str] = None) -> Optional[Task]:
+        """
+        Create a simple task with basic assignee information.
+        
+        This is a convenience method that creates TaskOwners internally.
+
+        Args:
+            org_id: Organization ID
+            title: Task name (required)
+            deadline: Task deadline in "YYYY-mm-dd HH:ii:ss" format
+            user_ids: List of user IDs to assign (optional)
+            guest_emails: List of guest email addresses to assign (optional)
+            group_ids: List of group IDs to assign (optional)
+            description: Task description (optional)
+
+        Returns:
+            Task object for the created task
+
+        Raises:
+            TallyfyError: If the request fails
+            ValueError: If required parameters are missing or no assignees provided
+        """
+        # Validate that at least one assignee type is provided
+        if not user_ids and not guest_emails and not group_ids:
+            raise ValueError("At least one assignee is required (user_ids, guest_emails, or group_ids)")
+
+        # Create TaskOwners object
+        owners = TaskOwners(
+            users=user_ids or [],
+            guests=guest_emails or [],
+            groups=group_ids or []
+        )
+
+        return self.create_task(org_id, title, deadline, owners, description)
+
+    def create_user_task(self, org_id: str, title: str, deadline: str, user_ids: list, 
+                        description: Optional[str] = None) -> Optional[Task]:
+        """
+        Create a task assigned to specific users only.
+
+        Args:
+            org_id: Organization ID
+            title: Task name (required)
+            deadline: Task deadline in "YYYY-mm-dd HH:ii:ss" format
+            user_ids: List of user IDs to assign (required)
+            description: Task description (optional)
+
+        Returns:
+            Task object for the created task
+
+        Raises:
+            TallyfyError: If the request fails
+            ValueError: If required parameters are missing
+        """
+        if not user_ids or not isinstance(user_ids, list):
+            raise ValueError("user_ids must be a non-empty list")
+
+        return self.create_simple_task(org_id, title, deadline, user_ids=user_ids, description=description)
+
+    def create_guest_task(self, org_id: str, title: str, deadline: str, guest_emails: list, 
+                         description: Optional[str] = None) -> Optional[Task]:
+        """
+        Create a task assigned to guests only.
+
+        Args:
+            org_id: Organization ID
+            title: Task name (required)
+            deadline: Task deadline in "YYYY-mm-dd HH:ii:ss" format
+            guest_emails: List of guest email addresses to assign (required)
+            description: Task description (optional)
+
+        Returns:
+            Task object for the created task
+
+        Raises:
+            TallyfyError: If the request fails
+            ValueError: If required parameters are missing
+        """
+        if not guest_emails or not isinstance(guest_emails, list):
+            raise ValueError("guest_emails must be a non-empty list")
+
+        # Basic email validation
+        for email in guest_emails:
+            try:
+                validation = validate_email(email)
+                # The validated email address
+                email = validation.normalized
+            except EmailNotValidError as e:
+                raise ValueError(f"Invalid email address: {str(e)}")
+
+        return self.create_simple_task(org_id, title, deadline, guest_emails=guest_emails, description=description)
+
+    def create_group_task(self, org_id: str, title: str, deadline: str, group_ids: list, 
+                         description: Optional[str] = None) -> Optional[Task]:
+        """
+        Create a task assigned to groups only.
+
+        Args:
+            org_id: Organization ID
+            title: Task name (required)
+            deadline: Task deadline in "YYYY-mm-dd HH:ii:ss" format
+            group_ids: List of group IDs to assign (required)
+            description: Task description (optional)
+
+        Returns:
+            Task object for the created task
+
+        Raises:
+            TallyfyError: If the request fails
+            ValueError: If required parameters are missing
+        """
+        if not group_ids or not isinstance(group_ids, list):
+            raise ValueError("group_ids must be a non-empty list")
+
+        return self.create_simple_task(org_id, title, deadline, group_ids=group_ids, description=description)