hpde-analytics-cli 2.0.0__tar.gz → 6.0.1__tar.gz

{hpde_analytics_cli-2.0.0 → hpde_analytics_cli-6.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hpde-analytics-cli
-Version: 2.0.0
+Version: 6.0.1
 Summary: Data analysis and reporting tool for HPDE and Time Trials programs
 Author-email: Kevin Homan <homan13@gmail.com>
 License: MIT
@@ -30,6 +30,8 @@ Requires-Dist: requests-oauthlib>=1.3.0
 Requires-Dist: python-dotenv>=1.0.0
 Requires-Dist: openpyxl>=3.1.0
 Requires-Dist: keyring>=24.0.0
+Requires-Dist: gspread>=6.0.0
+Requires-Dist: google-auth>=2.22.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0.0; extra == "dev"

{hpde_analytics_cli-2.0.0 → hpde_analytics_cli-6.0.1}/hpde_analytics_cli/api/client.py

@@ -11,6 +11,10 @@ from requests_oauthlib import OAuth1Session
 
 from hpde_analytics_cli.auth.oauth import MSROAuth
 
+# Error message constants
+ERR_EVENT_ID_REQUIRED = "Event ID is required"
+ERR_ORG_ID_REQUIRED = "Organization ID is required"
+
 
 class APIError(Exception):
     """Exception raised for API errors."""
@@ -46,6 +50,121 @@ class MSRClient:
         """Get an authenticated OAuth session."""
         return self.oauth.get_oauth_session()
 
+    def _execute_http_request(
+        self,
+        method: str,
+        session: OAuth1Session,
+        url: str,
+        params: Optional[Dict[str, Any]],
+        headers: Dict[str, str],
+    ):
+        """Execute HTTP request based on method type."""
+        if method.upper() == "GET":
+            return session.get(url, params=params, headers=headers)
+        elif method.upper() == "POST":
+            return session.post(url, data=params, headers=headers)
+        else:
+            raise APIError(f"Unsupported HTTP method: {method}")
+
+    def _handle_response_status(self, response, endpoint: str) -> Optional[Dict[str, Any]]:
+        """
+        Handle HTTP response status codes.
+
+        Returns:
+            Parsed response data if successful, None if should retry
+
+        Raises:
+            APIError: For non-retryable errors
+        """
+        if response.status_code == 200:
+            data = response.json()
+            # MSR wraps responses in {"response": {...}}
+            if isinstance(data, dict) and "response" in data:
+                data = data["response"]
+            return data
+
+        if response.status_code == 401:
+            raise APIError(
+                "Authentication failed - tokens may be invalid or expired",
+                status_code=401,
+                response_body=response.text,
+            )
+
+        if response.status_code == 403:
+            raise APIError(
+                "Access forbidden - insufficient permissions",
+                status_code=403,
+                response_body=response.text,
+            )
+
+        if response.status_code == 404:
+            raise APIError(
+                f"Resource not found: {endpoint}",
+                status_code=404,
+                response_body=response.text,
+            )
+
+        if response.status_code >= 500:
+            # Server error - signal retry
+            return None
+
+        raise APIError(
+            f"Request failed with status {response.status_code}",
+            status_code=response.status_code,
+            response_body=response.text,
+        )
+
+    def _should_retry_on_server_error(
+        self, response, endpoint: str, attempt: int, retries: int
+    ) -> APIError:
+        """
+        Handle server error response and determine if retry should occur.
+
+        Args:
+            response: HTTP response object
+            endpoint: API endpoint path
+            attempt: Current attempt number
+            retries: Maximum number of retries
+
+        Returns:
+            APIError to raise if no more retries
+
+        Raises:
+            APIError: If no more retries remain
+        """
+        error = APIError(
+            f"Server error: {response.status_code}",
+            status_code=response.status_code,
+            response_body=response.text,
+        )
+        if attempt < retries:
+            time.sleep(self.retry_delay * (attempt + 1))
+        else:
+            raise error
+        return error
+
+    def _should_retry_on_exception(self, e: Exception, attempt: int, retries: int) -> APIError:
+        """
+        Handle request exception and determine if retry should occur.
+
+        Args:
+            e: Exception that occurred
+            attempt: Current attempt number
+            retries: Maximum number of retries
+
+        Returns:
+            APIError to raise if no more retries
+
+        Raises:
+            APIError: If no more retries remain
+        """
+        error = APIError(f"Request failed: {str(e)}")
+        if attempt < retries:
+            time.sleep(self.retry_delay * (attempt + 1))
+        else:
+            raise error
+        return error
+
     def _request(
         self,
         method: str,
@@ -89,64 +208,21 @@ class MSRClient:
 
         for attempt in range(retries + 1):
             try:
-                if method.upper() == "GET":
-                    response = session.get(url, params=params, headers=headers)
-                elif method.upper() == "POST":
-                    response = session.post(url, data=params, headers=headers)
-                else:
-                    raise APIError(f"Unsupported HTTP method: {method}")
-
-                # Handle response
-                if response.status_code == 200:
-                    data = response.json()
-                    # MSR wraps responses in {"response": {...}}
-                    if isinstance(data, dict) and "response" in data:
-                        data = data["response"]
-                    return data
-                elif response.status_code == 401:
-                    raise APIError(
-                        "Authentication failed - tokens may be invalid or expired",
-                        status_code=401,
-                        response_body=response.text,
-                    )
-                elif response.status_code == 403:
-                    raise APIError(
-                        "Access forbidden - insufficient permissions",
-                        status_code=403,
-                        response_body=response.text,
-                    )
-                elif response.status_code == 404:
-                    raise APIError(
-                        f"Resource not found: {endpoint}",
-                        status_code=404,
-                        response_body=response.text,
-                    )
-                elif response.status_code >= 500:
-                    # Server error - retry
-                    last_error = APIError(
-                        f"Server error: {response.status_code}",
-                        status_code=response.status_code,
-                        response_body=response.text,
-                    )
-                    if attempt < retries:
-                        time.sleep(self.retry_delay * (attempt + 1))
-                        continue
-                    raise last_error
-                else:
-                    raise APIError(
-                        f"Request failed with status {response.status_code}",
-                        status_code=response.status_code,
-                        response_body=response.text,
-                    )
+                response = self._execute_http_request(method, session, url, params, headers)
+                result = self._handle_response_status(response, endpoint)
+
+                if result is not None:
+                    return result
+
+                # Server error - retry
+                last_error = self._should_retry_on_server_error(
+                    response, endpoint, attempt, retries
+                )
 
             except APIError:
                 raise
             except Exception as e:
-                last_error = APIError(f"Request failed: {str(e)}")
-                if attempt < retries:
-                    time.sleep(self.retry_delay * (attempt + 1))
-                    continue
-                raise last_error
+                last_error = self._should_retry_on_exception(e, attempt, retries)
 
         raise last_error
 
@@ -173,7 +249,7 @@ class MSRClient:
         """
         org_id = organization_id or self.organization_id
         if not org_id:
-            raise ValueError("Organization ID is required")
+            raise ValueError(ERR_ORG_ID_REQUIRED)
 
         return self._request("GET", f"/rest/calendars/organization/{org_id}")
 
@@ -190,7 +266,7 @@ class MSRClient:
         Endpoint: GET /rest/events/{event_id}/entrylist
         """
         if not event_id:
-            raise ValueError("Event ID is required")
+            raise ValueError(ERR_EVENT_ID_REQUIRED)
 
         return self._request("GET", f"/rest/events/{event_id}/entrylist")
 
@@ -207,7 +283,7 @@ class MSRClient:
         Endpoint: GET /rest/events/{event_id}/attendees
         """
         if not event_id:
-            raise ValueError("Event ID is required")
+            raise ValueError(ERR_EVENT_ID_REQUIRED)
 
         return self._request("GET", f"/rest/events/{event_id}/attendees")
 
@@ -224,7 +300,7 @@ class MSRClient:
         Endpoint: GET /rest/events/{event_id}/assignments
         """
         if not event_id:
-            raise ValueError("Event ID is required")
+            raise ValueError(ERR_EVENT_ID_REQUIRED)
 
         return self._request("GET", f"/rest/events/{event_id}/assignments")
 
@@ -241,10 +317,61 @@ class MSRClient:
         Endpoint: GET /rest/events/{event_id}/feeds/timing
         """
         if not event_id:
-            raise ValueError("Event ID is required")
+            raise ValueError(ERR_EVENT_ID_REQUIRED)
 
         return self._request("GET", f"/rest/events/{event_id}/feeds/timing")
 
+    def _fetch_user_profile(self, results: Dict[str, Any]) -> None:
+        """Fetch and store user profile data."""
+        print("  Fetching /rest/me...")
+        try:
+            results["me"] = self.get_me()
+            print("    [OK] User profile retrieved")
+        except APIError as e:
+            print(f"    [ERROR] {e}")
+            results["me"] = {"error": str(e)}
+
+    def _fetch_organization_calendar(
+        self, results: Dict[str, Any], event_id: Optional[str]
+    ) -> Optional[str]:
+        """
+        Fetch and store organization calendar data.
+
+        Returns:
+            Event ID if found in calendar, otherwise the input event_id
+        """
+        if not self.organization_id:
+            return event_id
+
+        print(f"  Fetching organization calendar (org: {self.organization_id})...")
+        try:
+            results["calendar"] = self.get_organization_calendar()
+            print("    [OK] Calendar retrieved")
+
+            # Get first event ID if not provided
+            if not event_id:
+                events = results["calendar"].get("events", [])
+                if events:
+                    event_id = events[0].get("id")
+                    print(f"    Using first event from calendar: {event_id}")
+        except APIError as e:
+            print(f"    [ERROR] {e}")
+            results["calendar"] = {"error": str(e)}
+
+        return event_id
+
+    def _fetch_event_endpoint(
+        self, results: Dict[str, Any], key: str, method, description: str, event_id: str
+    ) -> None:
+        """Fetch data from a single event endpoint."""
+        print(f"  Fetching {description} (event: {event_id})...")
+        try:
+            results[key] = method(event_id)
+            print(f"    [OK] {description} retrieved")
+        except APIError as e:
+            print(f"    [ERROR] {e}")
+            results[key] = {"error": str(e)}
+
     def get_all_endpoint_data(self, event_id: Optional[str] = None) -> Dict[str, Any]:
         """
         Fetch data from all available endpoints for field discovery.
@@ -255,33 +382,13 @@ class MSRClient:
         Returns:
             Dict with data from each endpoint, keyed by endpoint name
         """
-        results = {}
+        results: Dict[str, Any] = {}
 
-        # Always fetch user profile
-        print("  Fetching /rest/me...")
-        try:
-            results["me"] = self.get_me()
-            print("    [OK] User profile retrieved")
-        except APIError as e:
-            print(f"    [ERROR] {e}")
-            results["me"] = {"error": str(e)}
+        # Fetch user profile
+        self._fetch_user_profile(results)
 
-        # Fetch organization calendar
-        if self.organization_id:
-            print(f"  Fetching organization calendar (org: {self.organization_id})...")
-            try:
-                results["calendar"] = self.get_organization_calendar()
-                print("    [OK] Calendar retrieved")
-
-                # Get first event ID if not provided
-                if not event_id:
-                    events = results["calendar"].get("events", [])
-                    if events:
-                        event_id = events[0].get("id")
-                        print(f"    Using first event from calendar: {event_id}")
-            except APIError as e:
-                print(f"    [ERROR] {e}")
-                results["calendar"] = {"error": str(e)}
+        # Fetch organization calendar and potentially get event_id
+        event_id = self._fetch_organization_calendar(results, event_id)
 
         # Event-specific endpoints (require event_id)
         if event_id:
@@ -293,13 +400,7 @@ class MSRClient:
             ]
 
             for key, method, description in event_endpoints:
-                print(f"  Fetching {description} (event: {event_id})...")
-                try:
-                    results[key] = method(event_id)
-                    print(f"    [OK] {description} retrieved")
-                except APIError as e:
-                    print(f"    [ERROR] {e}")
-                    results[key] = {"error": str(e)}
+                self._fetch_event_endpoint(results, key, method, description, event_id)
         else:
             print("  [SKIP] No event ID available - skipping event-specific endpoints")
             print("         Use --event-id to specify an event, or ensure calendar has events")

{hpde_analytics_cli-2.0.0 → hpde_analytics_cli-6.0.1}/hpde_analytics_cli/auth/oauth.py

@@ -448,16 +448,20 @@ class MSROAuth:
             # Step 2: Get authorization URL
             auth_url = self.get_authorization_url()
 
+            # Always print the URL so the user can copy/paste it if needed
+            print(f"\nAuthorization URL:\n\n  {auth_url}\n")
+
             # Open browser automatically if requested
             if auto_open_browser:
-                print("\nAttempting to open browser automatically...")
+                print("Attempting to open browser automatically...")
                 try:
                     webbrowser.open(auth_url)
+                    print("  Browser opened. If nothing appeared, copy the URL above.")
                 except Exception as e:
                     print(f"  Could not open browser automatically: {e}")
-                print("\nIf the browser does not open, check your default browser settings.")
+                    print("  Copy the URL above and open it in your browser manually.")
             else:
-                print("\nPlease complete authorization in your browser.")
+                print("Copy the URL above and open it in your browser.")
 
             # Step 3: Wait for callback with verifier
             verifier = self._wait_for_callback(server)

hpde_analytics_cli-6.0.1/hpde_analytics_cli/integrations/__init__.py

@@ -0,0 +1 @@
+"""Google Sheets integration module."""

hpde_analytics_cli-6.0.1/hpde_analytics_cli/integrations/email_populator.py

@@ -0,0 +1,247 @@
+"""
+Email Populator Module
+
+Matches student names from Google Form responses to MSR event data
+and populates email addresses in the Google Sheet.
+"""
+
+import csv
+import os
+from typing import Any, Dict, List, Optional, Tuple
+
+
+class NameMatcher:
+    """Handles name normalization and matching between MSR and Sheet data."""
+
+    @staticmethod
+    def normalize(name: str) -> str:
+        """Normalize a name for comparison: lowercase, strip, collapse spaces."""
+        return " ".join(name.lower().split())
+
+    @staticmethod
+    def build_email_lookup(
+        entrylist: List[Dict],
+        attendees: List[Dict],
+        group_filter: str,
+    ) -> Dict[str, str]:
+        """
+        Build a lookup dict: normalized full name -> email.
+
+        Filters entrylist by group substring, then enriches with email from attendees.
+
+        Args:
+            entrylist: List of entrylist records (with firstName, lastName, group)
+            attendees: List of attendee records (with firstName, lastName, email)
+            group_filter: Case-insensitive substring to match against group field
+
+        Returns:
+            Dict mapping normalized "firstname lastname" -> email
+        """
+        # Build attendee email lookup by driver key (first|last)
+        attendee_emails: Dict[str, str] = {}
+        for att in attendees:
+            first = (att.get("firstName") or "").strip()
+            last = (att.get("lastName") or "").strip()
+            email = (att.get("email") or "").strip()
+            if first and last and email:
+                key = f"{first.lower()}|{last.lower()}"
+                attendee_emails[key] = email
+
+        # Filter entrylist by group and build name -> email lookup
+        email_lookup: Dict[str, str] = {}
+        group_filter_lower = group_filter.lower()
+
+        for entry in entrylist:
+            group = (entry.get("group") or "").lower()
+            if group_filter_lower not in group:
+                continue
+
+            first = (entry.get("firstName") or "").strip()
+            last = (entry.get("lastName") or "").strip()
+            if not first or not last:
+                continue
+
+            driver_key = f"{first.lower()}|{last.lower()}"
+            email = attendee_emails.get(driver_key, "")
+
+            if email:
+                full_name = NameMatcher.normalize(f"{first} {last}")
+                email_lookup[full_name] = email
+
+        return email_lookup
+
+    @staticmethod
+    def match_name(sheet_name: str, email_lookup: Dict[str, str]) -> Optional[str]:
+        """
+        Match a name from the Sheet against the MSR email lookup.
+
+        Args:
+            sheet_name: Name string from the Google Sheet
+            email_lookup: Dict of normalized name -> email
+
+        Returns:
+            Email address if matched, None otherwise
+        """
+        normalized = NameMatcher.normalize(sheet_name)
+        return email_lookup.get(normalized)
+
+
+class EmailPopulator:
+    """Orchestrates the email population workflow."""
+
+    def __init__(self, verbose: bool = False):
+        self.verbose = verbose
+
+    def _log(self, message: str) -> None:
+        """Print message if verbose mode is on."""
+        if self.verbose:
+            print(message)
+
+    def _read_csv(self, filepath: str) -> List[Dict]:
+        """Read a CSV file into a list of dictionaries."""
+        rows = []
+        with open(filepath, "r", encoding="utf-8") as f:
+            reader = csv.DictReader(f)
+            for row in reader:
+                rows.append(row)
+        return rows
+
+    def load_msr_data_from_export(self, export_dir: str) -> Tuple[List[Dict], List[Dict]]:
+        """
+        Load entrylist and attendees from export CSV files.
+
+        Args:
+            export_dir: Directory containing entrylist.csv and attendees.csv
+
+        Returns:
+            Tuple of (entrylist records, attendee records)
+        """
+        entrylist_path = os.path.join(export_dir, "entrylist.csv")
+        attendees_path = os.path.join(export_dir, "attendees.csv")
+
+        if not os.path.exists(entrylist_path):
+            raise FileNotFoundError(f"entrylist.csv not found in {export_dir}")
+        if not os.path.exists(attendees_path):
+            raise FileNotFoundError(f"attendees.csv not found in {export_dir}")
+
+        entrylist = self._read_csv(entrylist_path)
+        attendees = self._read_csv(attendees_path)
+
+        self._log(
+            f"  Loaded {len(entrylist)} entrylist records " f"and {len(attendees)} attendee records"
+        )
+
+        return entrylist, attendees
+
+    def load_msr_data_from_api(self, client: Any, event_id: str) -> Tuple[List[Dict], List[Dict]]:
+        """
+        Fetch entrylist and attendees from MSR API.
+
+        Args:
+            client: Authenticated MSRClient instance
+            event_id: MSR event ID
+
+        Returns:
+            Tuple of (entrylist records, attendee records)
+        """
+        self._log("  Fetching entrylist from MSR API...")
+        entrylist_data = client.get_event_entrylist(event_id)
+        entrylist = entrylist_data.get("assignments", [])
+
+        self._log("  Fetching attendees from MSR API...")
+        attendees_data = client.get_event_attendees(event_id)
+        attendees = attendees_data.get("attendees", [])
+
+        self._log(
+            f"  Fetched {len(entrylist)} entrylist records "
+            f"and {len(attendees)} attendee records"
+        )
+
+        return entrylist, attendees
+
+    def populate_emails(
+        self,
+        sheets_client: Any,
+        sheet_id: str,
+        worksheet_name: Optional[str],
+        name_column: str,
+        email_column: str,
+        email_lookup: Dict[str, str],
+    ) -> Dict[str, Any]:
+        """
+        Read names from Sheet, match to emails, write results.
+
+        Skips rows where the email column is already populated.
+
+        Args:
+            sheets_client: Authenticated GoogleSheetsClient instance
+            sheet_id: Google Sheet ID
+            worksheet_name: Optional worksheet/tab name (default: first sheet)
+            name_column: Column letter or header text for student names
+            email_column: Column letter or header text for email addresses
+            email_lookup: Dict of normalized name -> email from MSR data
+
+        Returns:
+            Dict with keys: matched, unmatched, skipped, already_filled, total_rows
+        """
+        self._log("\n  Connecting to Google Sheets...")
+        sheets_client.connect()
+
+        worksheet = sheets_client.open_sheet(sheet_id, worksheet_name)
+        self._log(f"  Opened worksheet: {worksheet.title}")
+
+        name_col_idx = sheets_client.find_column_index(worksheet, name_column)
+        email_col_idx = sheets_client.find_column_index(worksheet, email_column)
+        self._log(f"  Name column index: {name_col_idx}, Email column index: {email_col_idx}")
+
+        # Read all data at once to minimize API calls
+        all_records = worksheet.get_all_values()
+        if len(all_records) <= 1:
+            self._log("  Sheet has no data rows (only header or empty).")
+            return {
+                "matched": 0,
+                "unmatched": [],
+                "skipped": 0,
+                "already_filled": 0,
+                "total_rows": 0,
+            }
+
+        # Process rows (skip header row at index 0; Sheet rows start at 2)
+        updates = []
+        matched = 0
+        unmatched = []
+        skipped = 0
+        already_filled = 0
+
+        for row_idx, row in enumerate(all_records[1:], start=2):
+            name_value = row[name_col_idx - 1].strip() if len(row) >= name_col_idx else ""
+            email_value = row[email_col_idx - 1].strip() if len(row) >= email_col_idx else ""
+
+            if not name_value:
+                skipped += 1
+                continue
+
+            if email_value:
+                already_filled += 1
+                continue
+
+            email = NameMatcher.match_name(name_value, email_lookup)
+            if email:
+                updates.append((row_idx, email_col_idx, email))
+                matched += 1
+                self._log(f"    [MATCH] Row {row_idx}: {name_value} -> {email}")
+            else:
+                unmatched.append({"row": row_idx, "name": name_value})
+                self._log(f"    [NO MATCH] Row {row_idx}: {name_value}")
+
+        if updates:
+            self._log(f"\n  Writing {len(updates)} email addresses to Sheet...")
+            sheets_client.batch_update_cells(worksheet, updates)
+
+        return {
+            "matched": matched,
+            "unmatched": unmatched,
+            "skipped": skipped,
+            "already_filled": already_filled,
+            "total_rows": len(all_records) - 1,
+        }