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

google_client/user_client.py

@@ -0,0 +1,208 @@
+"""
+User-centric Google API Client.
+
+This module provides a clean, user-focused API where each user gets their own
+client instance with easy access to all Google services.
+"""
+
+import os
+
+from google.auth.transport.requests import Request
+from google.oauth2.credentials import Credentials
+from google_auth_oauthlib.flow import InstalledAppFlow
+from googleapiclient.discovery import build
+
+from . services.gmail import GmailApiService
+from . services.calendar import CalendarApiService
+from . services.tasks import TasksApiService
+from . services.drive import DriveApiService
+
+
+# SCOPES = [
+#     'https://www.googleapis.com/auth/calendar',
+#     'https://mail.google.com/',
+#     'https://www.googleapis.com/auth/tasks',
+#     'https://www.googleapis.com/auth/drive'
+# ]
+
+
+class UserClient:
+    """
+    User-centric client that provides clean access to all Google APIs.
+    
+    Usage Examples:
+        # Single user from file
+        user = UserClient.from_file()
+        events = user.calendar.list_events(number_of_results=10)
+        emails = user.gmail.list_emails(max_results=20)
+        tasks = user.tasks.list_tasks()
+        files = user.drive.list(max_results=10)
+        
+        # Multi-user scenario
+        user_1 = UserClient.from_credentials_info(app_creds, user1_token)
+        user_2 = UserClient.from_credentials_info(app_creds, user2_token)
+        
+        user_1_events = user_1.calendar.list_events()
+        user_2_events = user_2.calendar.list_events()
+    """
+    
+    def __init__(self, credentials: Credentials):
+        """
+        Initialize user client with credentials.
+        
+        Args:
+            credentials: Google OAuth2 credentials for this user
+        """
+        self._credentials = credentials
+
+        self._gmail_service = None
+        self._calendar_service = None
+        self._tasks_service = None
+        self._drive_service = None
+
+        self._gmail = None
+        self._calendar = None
+        self._tasks = None
+        self._drive = None
+
+
+    @classmethod
+    def from_credentials_info(
+            cls,
+            app_credentials: dict,
+            user_token_data: dict = None,
+            scopes: list = None,
+            port: int = 8080
+    ) -> tuple["UserClient", dict]:
+        """
+        Create a UserClient from credential data.
+
+        Args:
+            app_credentials: OAuth client configuration dict
+            user_token_data: Previously stored user token data dict
+            scopes: List of OAuth scopes to request
+
+        Returns:
+            tuple: (UserClient instance, updated_token_data_to_store)
+        """
+        scopes = scopes
+        creds = None
+
+        # Try to load existing credentials from memory
+        if user_token_data:
+            creds = Credentials.from_authorized_user_info(user_token_data, scopes)
+
+        if not creds or not creds.valid:
+            if creds and creds.expired and creds.refresh_token:
+                creds.refresh(Request())
+            else:
+                flow = InstalledAppFlow.from_client_config(app_credentials, scopes)
+                creds = flow.run_local_server(port=port)
+
+        # Return credentials and token data to store
+        token_data_to_store = {
+            'token': creds.token,
+            'refresh_token': creds.refresh_token,
+            'token_uri': creds.token_uri,
+            'client_id': creds.client_id,
+            'client_secret': creds.client_secret,
+            'scopes': creds.scopes
+        }
+
+        return cls(creds), token_data_to_store
+
+    @classmethod
+    def from_file(
+            cls,
+            token_path: str = None,
+            credentials_path: str = None,
+            scopes: list = None,
+            port: int = 8080
+    ) -> "UserClient":
+        """
+        Create a UserClient from credential data.
+
+        Args:
+            token_path: Path to previously stored user's token file (contents of token.json)
+            credentials_path: Path to OAuth client's credential file (contents of credentials.json)
+            scopes: List of OAuth scopes to request
+
+        Returns:
+            A UserClient instance
+
+        """
+
+        credentials_path = credentials_path
+        scopes = scopes
+
+        creds = None
+
+        if os.path.exists(token_path):
+            creds = Credentials.from_authorized_user_file(token_path, scopes)
+
+        if not creds or not creds.valid:
+            if creds and creds.expired and creds.refresh_token:
+                creds.refresh(Request())
+            else:
+                flow = InstalledAppFlow.from_client_secrets_file(
+                    credentials_path, scopes
+                )
+                creds = flow.run_local_server(port=port)
+
+            with open(token_path, "w") as token:
+                token.write(creds.to_json())
+
+        return cls(creds)
+
+    def _get_gmail_service(self):
+        """Get or create Gmail API service for this user."""
+        if self._gmail_service is None:
+            self._gmail_service = build("gmail", "v1", credentials=self._credentials)
+        return self._gmail_service
+    
+    def _get_calendar_service(self):
+        """Get or create Calendar API service for this user."""
+        if self._calendar_service is None:
+            self._calendar_service = build("calendar", "v3", credentials=self._credentials)
+        return self._calendar_service
+    
+    def _get_tasks_service(self):
+        """Get or create Tasks API service for this user."""
+        if self._tasks_service is None:
+            self._tasks_service = build("tasks", "v1", credentials=self._credentials)
+        return self._tasks_service
+    
+    def _get_drive_service(self):
+        """Get or create Drive API service for this user."""
+        if self._drive_service is None:
+            self._drive_service = build("drive", "v3", credentials=self._credentials)
+        return self._drive_service
+
+    @property
+    def gmail(self):
+        """Gmail service layer for this user."""
+        if self._gmail is None:
+            self._gmail = GmailApiService(self._get_gmail_service())
+        return self._gmail
+
+    @property
+    def calendar(self):
+        """Calendar service layer for this user."""
+        if self._calendar is None:
+            self._calendar = CalendarApiService(self._get_calendar_service())
+        return self._calendar
+
+    @property
+    def tasks(self):
+        """Tasks service layer for this user."""
+        if self._tasks is None:
+            self._tasks = TasksApiService(self._get_tasks_service())
+        return self._tasks
+
+    @property
+    def drive(self):
+        """Drive service layer for this user."""
+        if self._drive is None:
+            self._drive = DriveApiService(self._get_drive_service())
+        return self._drive
+

google_client/utils/datetime.py

@@ -0,0 +1,144 @@
+from datetime import datetime, date, time, timedelta
+import tzlocal
+
+
+def current_datetime_local_timezone() -> datetime:
+    """
+    Returns the current date and time in the local timezone.
+
+    Returns:
+        A datetime object representing the current date and time.
+    """
+    return datetime.now(tzlocal.get_localzone())
+
+
+def convert_datetime_to_iso(date_time: datetime) -> str:
+    """
+    Converts a given datetime object to a string in ISO format, adjusted
+    to the local timezone.
+
+    Args:
+        date_time: The datetime object to be converted.
+
+    Returns:
+        The ISO formatted string of the datetime in the local timezone.
+    """
+    return date_time.astimezone(tzlocal.get_localzone()).isoformat()
+
+def convert_datetime_to_readable(start: datetime, end: datetime = None) -> str:
+    """
+    Converts one or two ISO datetime strings into a human-readable format.
+    This function accepts a mandatory `start` time and an optional `end` time.
+    Both inputs are expected to be in ISO format. The output will be a
+    formatted string where the time is displayed in a readable format with varying
+    detail based on the relationship between the provided `start` and `end`
+    timestamps. If only the `start` time is provided, the result will contain only
+    the formatted `start` time. If an `end` time is provided, the display will
+    depend on whether the two timestamps occur on the same day or on different days.
+
+    Args:
+        start: A datetime string in ISO format representing the starting
+            time of the event.
+        end: An optional datetime string in ISO format representing the
+            ending time of the event. Default is None.
+
+    Returns:
+        A formatted string combining `start` and `end` times in a
+            human-readable form.
+    """
+    start = start.strftime("%a, %b %d, %Y %I:%M%p")
+    
+    if end:
+        if end.day == datetime.strptime(start, "%a, %b %d, %Y %I:%M%p").day:
+            # If start and end are on the same day
+            end = end.strftime("%I:%M%p")
+        else:
+            end = end.strftime("%a, %b %d, %Y %I:%M%p")
+    return f"{start} - {end}" if end else f"{start}"
+
+def convert_datetime_to_local_timezone(date_time: datetime) -> datetime:
+    """
+    Converts a given datetime object to a local-timezone-aware timezone.
+    Args:
+        date_time: The datetime object to be converted.
+
+    Returns:
+        A datetime object representing the local-timezone-aware timezone.
+    """
+    return datetime.astimezone(date_time, tzlocal.get_localzone())
+
+
+def combine_with_timezone(date_obj: date, time_obj: time) -> datetime:
+    """
+    Combines a date and time into a timezone-aware datetime using the local timezone.
+    
+    Args:
+        date_obj: The date component
+        time_obj: The time component
+        
+    Returns:
+        A timezone-aware datetime object in the local timezone
+    """
+    naive_datetime = datetime.combine(date_obj, time_obj)
+    local_tz = tzlocal.get_localzone()
+    return naive_datetime.replace(tzinfo=local_tz)
+
+
+def today_start() -> datetime:
+    """
+    Returns the start of today (00:00:00) in the local timezone.
+    
+    Returns:
+        A timezone-aware datetime representing the start of today
+    """
+    return combine_with_timezone(date.today(), time.min)
+
+
+def today_end() -> datetime:
+    """
+    Returns the end of today (23:59:59.999999) in the local timezone.
+    
+    Returns:
+        A timezone-aware datetime representing the end of today
+    """
+    return combine_with_timezone(date.today(), time.max)
+
+
+def date_start(target_date: date) -> datetime:
+    """
+    Returns the start of the specified date (00:00:00) in the local timezone.
+    
+    Args:
+        target_date: The date to get the start of
+        
+    Returns:
+        A timezone-aware datetime representing the start of the specified date
+    """
+    return combine_with_timezone(target_date, time.min)
+
+
+def date_end(target_date: date) -> datetime:
+    """
+    Returns the end of the specified date (23:59:59.999999) in the local timezone.
+    
+    Args:
+        target_date: The date to get the end of
+        
+    Returns:
+        A timezone-aware datetime representing the end of the specified date
+    """
+    return combine_with_timezone(target_date, time.max)
+
+
+def days_from_today(days: int) -> datetime:
+    """
+    Returns the start of a date that is N days from today in the local timezone.
+    
+    Args:
+        days: Number of days from today (positive for future, negative for past)
+        
+    Returns:
+        A timezone-aware datetime representing the start of the target date
+    """
+    target_date = date.today() + timedelta(days=days)
+    return date_start(target_date)

google_client/utils/validation.py

@@ -0,0 +1,71 @@
+"""
+Shared validation utilities for Google API client.
+
+This module provides common validation functions used across all services
+to maintain consistency and reduce code duplication.
+"""
+
+import re
+from typing import Optional
+
+
+def is_valid_email(email: str) -> bool:
+    """
+    Validate email format using regex.
+    
+    Args:
+        email: Email address to validate
+        
+    Returns:
+        True if email format is valid, False otherwise
+    """
+    pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
+    return re.match(pattern, email) is not None
+
+
+def validate_text_field(value: Optional[str], max_length: int, field_name: str, service_prefix: str = "") -> None:
+    """
+    Validates text field length and content.
+    
+    Args:
+        value: Text value to validate
+        max_length: Maximum allowed length
+        field_name: Name of the field for error messages
+        service_prefix: Service prefix for error message (e.g., "Email", "Event")
+        
+    Raises:
+        ValueError: If value exceeds maximum length
+    """
+    if value and len(value) > max_length:
+        prefix = f"{service_prefix} " if service_prefix else ""
+        raise ValueError(f"{prefix}{field_name} cannot exceed {max_length} characters")
+
+
+def sanitize_header_value(value: str) -> str:
+    """
+    Sanitize a string value for safe use in HTTP headers.
+
+    Prevents header injection by removing control characters that could
+    be used to inject additional headers or corrupt the MIME structure.
+
+    Args:
+        value: The string to sanitize
+
+    Returns:
+        Sanitized string safe for use in headers
+    """
+    if not value:
+        return ""
+
+    # Remove control characters that could cause header injection
+    # This includes \r, \n, \0, and other control characters
+    sanitized = re.sub(r'[\r\n\x00-\x1f\x7f-\x9f]', '', value)
+
+    # Remove any quotes that could break the header structure
+    sanitized = sanitized.replace('"', '')
+
+    # Limit length to prevent overly long headers
+    if len(sanitized) > 255:
+        sanitized = sanitized[:255]
+
+    return sanitized.strip()