google-api-client-wrapper 1.0.0__py3-none-any.whl

google_client/services/tasks/query_builder.py

@@ -0,0 +1,324 @@
+from datetime import datetime, date, timedelta
+from typing import Optional, List, TYPE_CHECKING
+from .constants import MAX_RESULTS_LIMIT, DEFAULT_MAX_RESULTS, DEFAULT_TASK_LIST_ID
+
+if TYPE_CHECKING:
+    from .types import Task
+    from .api_service import TasksApiService
+
+
+class TaskQueryBuilder:
+    """
+    Builder pattern for constructing Google Tasks queries with a fluent API.
+    Provides a clean, readable way to build complex task queries.
+    
+    Example usage:
+        tasks = (Task.query()
+            .limit(50)
+            .due_before(end_date)
+            .completed_after(start_date)
+            .show_completed(True)
+            .execute())
+    """
+    
+    def __init__(self, api_service: "TasksApiService"):
+        self._api_service = api_service
+        self._max_results: Optional[int] = DEFAULT_MAX_RESULTS
+        self._completed_max: Optional[datetime] = None
+        self._completed_min: Optional[datetime] = None
+        self._due_max: Optional[datetime] = None
+        self._due_min: Optional[datetime] = None
+        self._show_completed: Optional[bool] = None
+        self._show_hidden: Optional[bool] = None
+        self._task_list_id: str = DEFAULT_TASK_LIST_ID
+        
+    def limit(self, count: int) -> "TaskQueryBuilder":
+        """
+        Set the maximum number of tasks to retrieve.
+        Args:
+            count: Maximum number of tasks (1-100)
+        Returns:
+            Self for method chaining
+        """
+        if count < 1 or count > MAX_RESULTS_LIMIT:
+            raise ValueError(f"Limit must be between 1 and {MAX_RESULTS_LIMIT}")
+        self._max_results = count
+        return self
+        
+    def completed_after(self, min_date: datetime) -> "TaskQueryBuilder":
+        """
+        Filter tasks completed after the specified date.
+        Args:
+            min_date: Minimum completion date (RFC 3339 timestamp)
+        Returns:
+            Self for method chaining
+        """
+        self._completed_min = min_date
+        return self
+        
+    def completed_before(self, max_date: datetime) -> "TaskQueryBuilder":
+        """
+        Filter tasks completed before the specified date.
+        Args:
+            max_date: Maximum completion date (RFC 3339 timestamp)
+        Returns:
+            Self for method chaining
+        """
+        self._completed_max = max_date
+        return self
+        
+    def completed_in_range(self, min_date: datetime, max_date: datetime) -> "TaskQueryBuilder":
+        """
+        Filter tasks completed within the specified date range.
+        Args:
+            min_date: Minimum completion date
+            max_date: Maximum completion date
+        Returns:
+            Self for method chaining
+        """
+        if min_date >= max_date:
+            raise ValueError("Start date must be before end date")
+        self._completed_min = min_date
+        self._completed_max = max_date
+        return self
+        
+    def due_after(self, min_date: datetime) -> "TaskQueryBuilder":
+        """
+        Filter tasks due after the specified date.
+        Args:
+            min_date: Minimum due date (RFC 3339 timestamp)
+        Returns:
+            Self for method chaining
+        """
+        self._due_min = min_date
+        return self
+        
+    def due_before(self, max_date: datetime) -> "TaskQueryBuilder":
+        """
+        Filter tasks due before the specified date.
+        Args:
+            max_date: Maximum due date (RFC 3339 timestamp)
+        Returns:
+            Self for method chaining
+        """
+        self._due_max = max_date
+        return self
+        
+    def due_in_range(self, min_date: datetime, max_date: datetime) -> "TaskQueryBuilder":
+        """
+        Filter tasks due within the specified date range.
+        Args:
+            min_date: Minimum due date
+            max_date: Maximum due date
+        Returns:
+            Self for method chaining
+        """
+        if min_date >= max_date:
+            raise ValueError("Start date must be before end date")
+        self._due_min = min_date
+        self._due_max = max_date
+        return self
+        
+    def show_completed(self, show: bool = True) -> "TaskQueryBuilder":
+        """
+        Include or exclude completed tasks in results.
+        Args:
+            show: Whether to include completed tasks
+        Returns:
+            Self for method chaining
+        """
+        self._show_completed = show
+        return self
+        
+    def show_hidden(self, show: bool = True) -> "TaskQueryBuilder":
+        """
+        Include or exclude hidden tasks in results.
+        Args:
+            show: Whether to include hidden tasks
+        Returns:
+            Self for method chaining
+        """
+        self._show_hidden = show
+        return self
+        
+    def in_task_list(self, task_list_id: str) -> "TaskQueryBuilder":
+        """
+        Specify which task list to query.
+        Args:
+            task_list_id: Task list identifier
+        Returns:
+            Self for method chaining
+        """
+        self._task_list_id = task_list_id
+        return self
+        
+    # Convenience date methods
+    def due_today(self) -> "TaskQueryBuilder":
+        """
+        Filter to tasks due today.
+        Returns:
+            Self for method chaining
+        """
+        today = date.today()
+        start_of_day = datetime.combine(today, datetime.min.time())
+        end_of_day = start_of_day + timedelta(days=1)
+        return self.due_in_range(start_of_day, end_of_day)
+        
+    def due_tomorrow(self) -> "TaskQueryBuilder":
+        """
+        Filter to tasks due tomorrow.
+        Returns:
+            Self for method chaining
+        """
+        tomorrow = date.today() + timedelta(days=1)
+        start_of_day = datetime.combine(tomorrow, datetime.min.time())
+        end_of_day = start_of_day + timedelta(days=1)
+        return self.due_in_range(start_of_day, end_of_day)
+        
+    def due_this_week(self) -> "TaskQueryBuilder":
+        """
+        Filter to tasks due this week (Monday to Sunday).
+        Returns:
+            Self for method chaining
+        """
+        today = date.today()
+        days_since_monday = today.weekday()
+        monday = today - timedelta(days=days_since_monday)
+        sunday = monday + timedelta(days=6)
+        
+        start_of_week = datetime.combine(monday, datetime.min.time())
+        end_of_week = datetime.combine(sunday, datetime.max.time())
+        return self.due_in_range(start_of_week, end_of_week)
+        
+    def due_next_week(self) -> "TaskQueryBuilder":
+        """
+        Filter to tasks due next week (Monday to Sunday).
+        Returns:
+            Self for method chaining
+        """
+        today = date.today()
+        days_since_monday = today.weekday()
+        next_monday = today + timedelta(days=(7 - days_since_monday))
+        next_sunday = next_monday + timedelta(days=6)
+        
+        start_of_week = datetime.combine(next_monday, datetime.min.time())
+        end_of_week = datetime.combine(next_sunday, datetime.max.time())
+        return self.due_in_range(start_of_week, end_of_week)
+        
+    def due_next_days(self, days: int) -> "TaskQueryBuilder":
+        """
+        Filter to tasks due in the next N days.
+        Args:
+            days: Number of days from today
+        Returns:
+            Self for method chaining
+        """
+        if days < 1:
+            raise ValueError("Days must be positive")
+            
+        today = date.today()
+        start = datetime.combine(today, datetime.min.time())
+        end = datetime.combine(today + timedelta(days=days + 1), datetime.min.time())
+        return self.due_in_range(start, end)
+        
+    def overdue(self) -> "TaskQueryBuilder":
+        """
+        Filter to tasks that are overdue (due date in the past and not completed).
+        Returns:
+            Self for method chaining
+        """
+        today = datetime.combine(date.today(), datetime.min.time())
+        return self.due_before(today).show_completed(False)
+        
+    def completed_today(self) -> "TaskQueryBuilder":
+        """
+        Filter to tasks completed today.
+        Returns:
+            Self for method chaining
+        """
+        today = date.today()
+        start_of_day = datetime.combine(today, datetime.min.time())
+        end_of_day = start_of_day + timedelta(days=1)
+        return self.completed_in_range(start_of_day, end_of_day)
+        
+    def completed_this_week(self) -> "TaskQueryBuilder":
+        """
+        Filter to tasks completed this week (Monday to Sunday).
+        Returns:
+            Self for method chaining
+        """
+        today = date.today()
+        days_since_monday = today.weekday()
+        monday = today - timedelta(days=days_since_monday)
+        sunday = monday + timedelta(days=6)
+        
+        start_of_week = datetime.combine(monday, datetime.min.time())
+        end_of_week = datetime.combine(sunday, datetime.max.time())
+        return self.completed_in_range(start_of_week, end_of_week)
+        
+    def completed_last_days(self, days: int) -> "TaskQueryBuilder":
+        """
+        Filter to tasks completed in the last N days.
+        Args:
+            days: Number of days back to search
+        Returns:
+            Self for method chaining
+        """
+        if days < 1:
+            raise ValueError("Days must be positive")
+            
+        today = date.today()
+        start = datetime.combine(today - timedelta(days=days), datetime.min.time())
+        end = datetime.combine(today, datetime.max.time())
+        return self.completed_in_range(start, end)
+        
+    def execute(self) -> List["Task"]:
+        """
+        Execute the query and return the results.
+        Returns:
+            List of Task objects matching the criteria
+        Raises:
+            ValueError: If query parameters are invalid
+        """
+        
+        # Use the service layer implementation
+        tasks = self._api_service.list_tasks(
+            task_list_id=self._task_list_id,
+            max_results=self._max_results,
+            completed_min=self._completed_min,
+            completed_max=self._completed_max,
+            due_min=self._due_min,
+            due_max=self._due_max,
+            show_completed=self._show_completed,
+            show_hidden=self._show_hidden
+        )
+        
+        return tasks
+        
+    def count(self) -> int:
+        """
+        Execute the query and return only the count of matching tasks.
+        Returns:
+            Number of tasks matching the criteria
+        """
+        return len(self.execute())
+        
+    def first(self) -> Optional["Task"]:
+        """
+        Execute the query and return only the first matching task.
+        Returns:
+            First Task or None if no matches
+        """
+        tasks = self.limit(1).execute()
+        return tasks[0] if tasks else None
+        
+    def exists(self) -> bool:
+        """
+        Check if any tasks match the criteria without retrieving them.
+        Returns:
+            True if at least one task matches, False otherwise
+        """
+        return self.limit(1).count() > 0
+        
+    def __repr__(self):
+        return f"TaskQueryBuilder(task_list_id='{self._task_list_id}', limit={self._max_results})"

google_client/services/tasks/types.py

@@ -0,0 +1,156 @@
+from datetime import date, datetime, timedelta
+from typing import Optional
+from dataclasses import dataclass
+
+
+@dataclass
+class TaskList:
+    """
+    Represents a Google Task List.
+    Args:
+        task_list_id: Unique identifier for the task list.
+        title: The title of the task list.
+        updated: Last modification time.
+    """
+    task_list_id: Optional[str] = None
+    title: Optional[str] = None
+    updated: Optional[datetime] = None
+
+    def to_dict(self) -> dict:
+        """
+        Convert TaskList to dictionary format for Google Tasks API.
+        Returns:
+            Dictionary representation suitable for API calls.
+        """
+        task_list_dict = {}
+        if self.task_list_id:
+            task_list_dict['id'] = self.task_list_id
+        if self.title:
+            task_list_dict['title'] = self.title
+        if self.updated:
+            task_list_dict['updated'] = self.updated.isoformat() + 'Z'
+        return task_list_dict
+
+    def __repr__(self):
+        return f"TaskList(id={self.task_list_id!r}, title={self.title!r})"
+
+
+@dataclass
+class Task:
+    """
+    Represents a Google Task.
+    Args:
+        task_id: Unique identifier for the task.
+        title: The title of the task.
+        notes: Notes describing the task.
+        status: Status of the task ('needsAction' or 'completed').
+        due: Due date of the task.
+        completed: Completion date of the task.
+        updated: Last modification time.
+        parent: Parent task identifier.
+        position: Position in the task list.
+        task_list_id: ID of the task list this task belongs to.
+    """
+    task_id: Optional[str] = None
+    title: Optional[str] = None
+    notes: Optional[str] = None
+    status: Optional[str] = "needsAction"
+    due: Optional[date] = None
+    completed: Optional[date] = None
+    updated: Optional[date] = None
+    parent: Optional[str] = None
+    position: Optional[str] = None
+    task_list_id: Optional[str] = None
+
+    def is_completed(self) -> bool:
+        """
+        Check if the task is completed.
+        Returns:
+            True if the task is completed, False otherwise.
+        """
+        return self.status == 'completed'
+
+    def is_overdue(self) -> bool:
+        """
+        Check if the task is overdue.
+        Returns:
+            True if the task has a due date that has passed and is not completed.
+        """
+        if not self.due or self.is_completed():
+            return False
+        return self.due < date.today()
+
+    def is_due_today(self) -> bool:
+        """
+        Check if the task is due today.
+        Returns:
+            True if the task is due today, False otherwise.
+        """
+        if not self.due:
+            return False
+        return self.due == date.today()
+
+    def is_due_soon(self, days: int = 3) -> bool:
+        """
+        Check if the task is due within the next N days.
+        Args:
+            days: Number of days to check ahead (default: 3)
+        Returns:
+            True if the task is due within the specified days.
+        """
+        if not self.due or self.is_completed():
+            return False
+        today = date.today()
+        return today <= self.due <= (today + timedelta(days=days))
+
+    def has_parent(self) -> bool:
+        """
+        Check if the task has a parent task.
+        Returns:
+            True if the task has a parent, False otherwise.
+        """
+        return bool(self.parent)
+
+    def has_notes(self) -> bool:
+        """
+        Check if the task has notes.
+        Returns:
+            True if the task has notes, False otherwise.
+        """
+        return bool(self.notes and self.notes.strip())
+
+    def to_dict(self) -> dict:
+        """
+        Convert Task to dictionary format for Google Tasks API.
+        Returns:
+            Dictionary representation suitable for API calls.
+        """
+        task_dict = {}
+        if self.task_id:
+            task_dict['id'] = self.task_id
+        if self.title:
+            task_dict['title'] = self.title
+        if self.notes:
+            task_dict['notes'] = self.notes
+        if self.status:
+            task_dict['status'] = self.status
+        if self.due:
+            # Convert date to datetime for API compatibility
+            due_datetime = datetime.combine(self.due, datetime.min.time())
+            task_dict['due'] = due_datetime.isoformat() + 'Z'
+        if self.completed:
+            # Convert date to datetime for API compatibility
+            completed_datetime = datetime.combine(self.completed, datetime.min.time())
+            task_dict['completed'] = completed_datetime.isoformat() + 'Z'
+        if self.parent:
+            task_dict['parent'] = self.parent
+        if self.position:
+            task_dict['position'] = self.position
+        return task_dict
+
+    def __repr__(self):
+        due_str = self.due.strftime("%a %m-%d-%Y") if self.due else None
+        return (
+            f"Task(id={self.task_id!r}, title={self.title!r}, "
+            f"status={self.status!r}, due={due_str})"
+        )

google_client/services/tasks/utils.py

@@ -0,0 +1,224 @@
+import re
+from datetime import datetime, date, time
+from typing import Optional, Dict, Any
+
+from .types import Task, TaskList
+from .constants import (
+    MAX_TITLE_LENGTH, MAX_NOTES_LENGTH, VALID_TASK_STATUSES,
+    RFC3339_FORMAT
+)
+from ...utils.datetime import convert_datetime_to_local_timezone
+
+
+# Import from shared utilities
+from ...utils.validation import validate_text_field, sanitize_header_value
+
+
+def validate_task_status(status: Optional[str]) -> None:
+    """Validates task status."""
+    if status and status not in VALID_TASK_STATUSES:
+        raise ValueError(f"Invalid task status: {status}. Must be one of: {', '.join(VALID_TASK_STATUSES)}")
+
+
+def parse_datetime_field(field_value: Optional[str]) -> Optional[date]:
+    """
+    Parse datetime field from Google Tasks API response to date.
+    
+    Args:
+        field_value: ISO datetime string from API
+        
+    Returns:
+        Parsed date object or None if parsing fails
+    """
+    if not field_value:
+        return None
+        
+    try:
+        # Handle different formats from Tasks API
+        if field_value.endswith('Z'):
+            dt = datetime.fromisoformat(field_value.replace('Z', '+00:00'))
+        else:
+            dt = datetime.fromisoformat(field_value)
+            
+        # Convert to local timezone and return date
+        dt = convert_datetime_to_local_timezone(dt)
+        return dt.date()
+    except (ValueError, TypeError):
+        return None
+
+
+def parse_update_datetime_field(field_value: Optional[str]) -> Optional[datetime]:
+    """
+    Parse update datetime field from Google Tasks API response.
+    
+    Args:
+        field_value: ISO datetime string from API
+        
+    Returns:
+        Parsed datetime object or None if parsing fails
+    """
+    if not field_value:
+        return None
+        
+    try:
+        # Handle different formats from Tasks API
+        if field_value.endswith('Z'):
+            dt = datetime.fromisoformat(field_value.replace('Z', '+00:00'))
+        else:
+            dt = datetime.fromisoformat(field_value)
+            
+        # Convert to local timezone
+        return convert_datetime_to_local_timezone(dt)
+    except (ValueError, TypeError):
+        return None
+
+
+def from_google_task(google_task: Dict[str, Any], task_list_id: Optional[str] = None) -> Task:
+    """
+    Create a Task instance from a Google Tasks API response.
+    
+    Args:
+        google_task: Dictionary containing task data from Google Tasks API
+        task_list_id: The ID of the task list this task belongs to
+        
+    Returns:
+        Task instance populated with the data from the dictionary
+    """
+    try:
+        task_id = google_task.get('id')
+        title = google_task.get('title', '').strip() if google_task.get('title') else None
+        notes = google_task.get('notes', '').strip() if google_task.get('notes') else None
+        status = google_task.get('status', 'needsAction')
+        
+        # Validate status
+        if status not in VALID_TASK_STATUSES:
+            status = 'needsAction'
+        
+        # Parse dates
+        due = parse_datetime_field(google_task.get('due'))
+        completed = parse_datetime_field(google_task.get('completed'))
+        updated = parse_datetime_field(google_task.get('updated'))
+        
+        # Parse hierarchy
+        parent = google_task.get('parent')
+        position = google_task.get('position')
+        
+        return Task(
+            task_id=task_id,
+            title=title,
+            notes=notes,
+            status=status,
+            due=due,
+            completed=completed,
+            updated=updated,
+            parent=parent,
+            position=position,
+            task_list_id=task_list_id
+        )
+        
+    except Exception as e:
+        raise ValueError("Invalid task data - failed to parse Google task")
+
+
+def from_google_task_list(google_task_list: Dict[str, Any]) -> TaskList:
+    """
+    Create a TaskList instance from a Google Tasks API response.
+    
+    Args:
+        google_task_list: Dictionary containing task list data from Google Tasks API
+        
+    Returns:
+        TaskList instance populated with the data from the dictionary
+    """
+    try:
+        task_list_id = google_task_list.get('id')
+        title = google_task_list.get('title', '').strip() if google_task_list.get('title') else None
+        updated = parse_update_datetime_field(google_task_list.get('updated'))
+        
+        return TaskList(
+            task_list_id=task_list_id,
+            title=title,
+            updated=updated
+        )
+        
+    except Exception as e:
+        raise ValueError("Invalid task list data - failed to parse Google task list")
+
+
+def create_task_body(
+    title: str,
+    notes: Optional[str] = None,
+    due: Optional[date] = None,
+    parent: Optional[str] = None,
+    position: Optional[str] = None,
+    status: Optional[str] = None
+) -> Dict[str, Any]:
+    """
+    Create task body dictionary for Google Tasks API.
+    
+    Args:
+        title: Task title
+        notes: Task notes
+        due: Due date
+        parent: Parent task ID
+        position: Position in task list
+        status: Task status
+        
+    Returns:
+        Dictionary suitable for Tasks API requests
+        
+    Raises:
+        ValueError: If required fields are invalid
+    """
+    if not title or not title.strip():
+        raise ValueError("Task title cannot be empty")
+    
+    # Validate text fields
+    validate_text_field(title, MAX_TITLE_LENGTH, "title")
+    validate_text_field(notes, MAX_NOTES_LENGTH, "notes")
+    validate_task_status(status)
+    
+    # Build task body
+    task_body = {
+        'title': sanitize_header_value(title)
+    }
+    
+    # Add optional fields
+    if notes:
+        task_body['notes'] = sanitize_header_value(notes)
+    if due:
+        # Convert date to datetime for API compatibility
+        due_datetime = datetime.combine(due, time.min)
+        task_body['due'] = due_datetime.isoformat() + 'Z'
+    if parent:
+        task_body['parent'] = parent
+    if position:
+        task_body['position'] = position
+    if status:
+        task_body['status'] = status
+        
+    return task_body
+
+
+def create_task_list_body(title: str) -> Dict[str, Any]:
+    """
+    Create task list body dictionary for Google Tasks API.
+    
+    Args:
+        title: Task list title
+        
+    Returns:
+        Dictionary suitable for Tasks API requests
+        
+    Raises:
+        ValueError: If required fields are invalid
+    """
+    if not title or not title.strip():
+        raise ValueError("Task list title cannot be empty")
+    
+    # Validate title length
+    validate_text_field(title, MAX_TITLE_LENGTH, "title")
+    
+    return {
+        'title': sanitize_header_value(title)
+    }