cornellGrading 2.25.0__tar.gz → 2.27.0__tar.gz

{cornellgrading-2.25.0/cornellGrading.egg-info → cornellgrading-2.27.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cornellGrading
-Version: 2.25.0
+Version: 2.27.0
 Summary: Routines for interacting with Cornell installations of Canvas and Qualtrics
 Home-page: https://github.com/dsavransky/grading
 Author: Dmitry Savransky

{cornellgrading-2.25.0 → cornellgrading-2.27.0}/cornellGrading/__init__.py

@@ -1,4 +1,5 @@
 name = "cornellGrading"
-__version__ = "2.25.0"
+__version__ = "2.27.0"
 from .cornellGrading import cornellGrading
 from .cornellQualtrics import cornellQualtrics
+from .simplelists import simplelists

{cornellgrading-2.25.0 → cornellgrading-2.27.0}/cornellGrading/cornellGrading.py

@@ -803,7 +803,7 @@ class cornellGrading:
         # check that this one doesn't already exist
         res = self.qualtrics.getMailingLists()
         assert self.coursename not in [
-            el["name"] for el in res.json()["result"]["elements"]
+            el["name"] for el in res
         ], "Mailing list already exists for this course."
 
         names = np.array([n.split(", ") for n in self.names])
@@ -1011,9 +1011,7 @@ class cornellGrading:
                   <p><a class="survey-link ng-binding" href="{0}" target="_blank">{0}
                   </a></p>
                   <p>Be sure to enter your correct netid or you will not receive
-                  credit.</p>""".format(
-            link
-        )
+                  credit.</p>""".format(link)
 
         _ = self.createAssignment(
             assname,
@@ -1611,9 +1609,7 @@ class cornellGrading:
                 """data-api-endpoint="{2}" data-api-returntype="File">{0}</a></p>
                     <p>Grade yourself against the rubric in the syllabus and enter your
                     scores for each problem by following the link in the comments on
-                    your original submission.</p>""".format(
-                    solfname, solurl, solepoint
-                )
+                    your original submission.</p>""".format(solfname, solurl, solepoint)
             )
 
             if injectText:

{cornellgrading-2.25.0 → cornellgrading-2.27.0}/cornellGrading/cornellQualtrics.py

@@ -80,6 +80,10 @@ class cornellQualtrics:
             self.listSurveys()
             print("Connected to Qualtrics.")
 
+        # set directoryId and userId
+        self.directoryId = self.getDirectoryId()
+        self.whoami()
+
     def setupHeaders(self):
         """Generate standard headers
 
@@ -105,6 +109,37 @@ class cornellQualtrics:
             "x-api-token": self.apiToken,
         }
 
+    def whoami(self):
+        """Populate userId attribute"""
+
+        baseUrl = f"https://{self.dataCenter}{self.qualtricsapi}whoami"
+        response = requests.get(baseUrl, headers=self.headers_tokenOnly)
+
+        self.userId = response.json()["result"]["userId"]
+
+    def expandResponse(self, response):
+        """
+
+        Args:
+            response (requests.models.Response):
+                Requests response from any relevant endpoint accessed with GET request
+
+        Returns:
+            list:
+                list of all result elements
+
+        """
+
+        out = response.json()["result"]["elements"]
+
+        while response.json()["result"]["nextPage"] is not None:
+            response = requests.get(
+                response.json()["result"]["nextPage"], headers=self.headers_tokenOnly
+            )
+            out += response.json()["result"]["elements"]
+
+        return out
+
     def listSurveys(self, baseUrl=None):
         """Grab and store all available Qualtrics surveys
 
@@ -214,25 +249,34 @@ class cornellQualtrics:
 
         return response
 
-    def getMailingLists(self):
+    def getMailingLists(self, includeShared=False):
         """Grab all available Qualtrics mailing lists
 
         Args:
-            None
+            includeShared (bool):
+                If True, include all mailing lists accessible to user.  If False
+                (defualt) include only those owned by user.
 
         Returns:
-            requests.models.Response:
-                response object with all mailing lists
+            list:
+                all mailing list definitions
 
         """
 
-        baseUrl = "https://{0}{1}mailinglists".format(
-            self.dataCenter,
-            self.qualtricsapi,
+        baseUrl = (
+            f"https://{self.dataCenter}{self.qualtricsapi}directories/"
+            f"{self.directoryId}/mailinglists"
         )
-        response = requests.get(baseUrl, headers=self.headers_tokenOnly)
+        if includeShared:
+            response = requests.get(baseUrl, headers=self.headers_tokenOnly)
+        else:
+            response = requests.get(
+                baseUrl, headers=self.headers_tokenOnly, params={"ownerId": self.userId}
+            )
 
-        return response
+        out = self.expandResponse(response)
+
+        return out
 
     def getMailingListId(self, listName):
         """Find qualtrics mailinglist id by name.  Matching is exact.
@@ -249,9 +293,9 @@ class cornellQualtrics:
 
         res = self.getMailingLists()
         mailinglistid = None
-        for el in res.json()["result"]["elements"]:
+        for el in res:
             if el["name"] == listName:
-                mailinglistid = el["id"]
+                mailinglistid = el["mailingListId"]
                 break
         assert mailinglistid, "Couldn't find this mailing list."
 
@@ -263,8 +307,8 @@ class cornellQualtrics:
         Args:
             listName (str):
                 List name
-            libraryId (str, optional):
-                Library ID. If None, will attempt to identify it automatically
+            libraryId (str, deprecated):
+                DEPRECATED and ignored.  Left only for backwards compatibility.
 
         Returns:
             str:
@@ -272,23 +316,13 @@ class cornellQualtrics:
 
         """
 
-        # first we need to figure out what our personal library id is
-        tmp = requests.get(
-            "https://{0}{1}libraries".format(self.dataCenter, self.qualtricsapi),
-            headers=self.headers_tokenOnly,
+        data = {"name": listName}
+        baseUrl = (
+            f"https://{self.dataCenter}{self.qualtricsapi}directories/"
+            f"{self.directoryId}/mailinglists"
         )
-
-        if libraryId is None:
-            for el in tmp.json()["result"]["elements"]:
-                if "UR_" in el["libraryId"] or "URH_" in el["libraryId"]:
-                    libraryId = el["libraryId"]
-                    break
-            assert libraryId is not None, "Could not identify library id."
-
-        data = {"libraryId": libraryId, "name": listName}
-
         response = requests.post(
-            "https://{0}{1}mailinglists".format(self.dataCenter, self.qualtricsapi),
+            baseUrl,
             headers=self.headers_post,
             json=data,
         )
@@ -304,8 +338,8 @@ class cornellQualtrics:
                 Mailing list name
             contacts (pandas.DataFrame):
                 DataFrame containing the columns: 'First Name', 'Last Name', and 'Email'
-            libraryId (str, optional):
-                Library ID. If None, will attempt to identify it automatically
+            libraryId (str, dprecated):
+                DEPRECATED and ignored.  Left only for backwards compatibility.
 
 
         Returns:
@@ -367,26 +401,18 @@ class cornellQualtrics:
 
 
         """
-        response = requests.get(
-            "https://{0}{2}mailinglists/{1}/contacts".format(
-                self.dataCenter,
-                mailingListId,
-                self.qualtricsapi,
-            ),
-            headers=self.headers_tokenOnly,
+        baseUrl = (
+            f"https://{self.dataCenter}{self.qualtricsapi}directories/"
+            f"{self.directoryId}/mailinglists/{mailingListId}/contacts"
         )
 
+        response = requests.get(baseUrl, headers=self.headers_tokenOnly)
+
         assert (
             response.status_code == 200
         ), "Could not get contacts for list {}.".format(mailingListId)
 
-        out = response.json()["result"]["elements"]
-
-        while response.json()["result"]["nextPage"] is not None:
-            response = requests.get(
-                response.json()["result"]["nextPage"], headers=self.headers_tokenOnly
-            )
-            out += response.json()["result"]["elements"]
+        out = self.expandResponse(response)
 
         return out
 
@@ -417,7 +443,7 @@ class cornellQualtrics:
         for el in contacts:
             fn.append(el["firstName"])
             ln.append(el["lastName"])
-            cid.append(el["id"])
+            cid.append(el["contactLookupId"])
             email.append(el["email"])
 
         contacts = pandas.DataFrame(
@@ -453,8 +479,9 @@ class cornellQualtrics:
 
         """
 
-        baseUrl = "https://{0}{2}mailinglists/{1}/contacts".format(
-            self.dataCenter, mailingListId, self.qualtricsapi
+        baseUrl = (
+            f"https://{self.dataCenter}{self.qualtricsapi}directories/"
+            f"{self.directoryId}/mailinglists/{mailingListId}/contacts"
         )
 
         data = {
@@ -484,15 +511,12 @@ class cornellQualtrics:
 
         """
 
-        response = requests.delete(
-            "https://{0}{3}mailinglists/{1}/contacts/{2}".format(
-                self.dataCenter,
-                mailingListId,
-                contactId,
-                self.qualtricsapi,
-            ),
-            headers=self.headers_post,
+        baseUrl = (
+            f"https://{self.dataCenter}{self.qualtricsapi}directories/"
+            f"{self.directoryId}/mailinglists/{mailingListId}/contacts/{contactId}"
         )
+
+        response = requests.delete(baseUrl, headers=self.headers_post)
         assert response.status_code == 200, "Could not remove contact from list."
 
     def genDistribution(self, surveyId, mailingListId):

cornellgrading-2.27.0/cornellGrading/simplelists.py

@@ -0,0 +1,242 @@
+"""Wrapper class for interacting with the SimpleLists v2 REST API.
+
+Provides authentication against per-list API keys stored in a local JSON
+credentials file, plus basic contact operations (retrieve, create, delete)
+against SimpleLists mailing lists"""
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import requests
+
+
+class simplelists:
+    """Class for io methods for the SimpleLists v2 API."""
+
+    def __init__(self, server: str = "https://lists.cornell.edu/api/2/") -> None:
+        """Load per-list API keys and validate them against the live API.
+
+        Args:
+            server (str):
+                Base URL of the SimpleLists API, including trailing slash
+                and version path. Defaults to
+                'https://lists.cornell.edu/api/2/'.
+        """
+
+        self.baseurl = server
+
+        cdir = "simplelists"
+
+        if os.name == "nt":
+            config_dir = Path(os.environ["APPDATA"], cdir)
+        else:
+            config_dir = Path(Path.home(), ".config", cdir)
+
+        credfile = config_dir / "credentials.json"
+
+        assert credfile.exists(), f"Cannot locate credentials file at {credfile}."
+        assert os.access(credfile, os.R_OK), (
+            f"Credentials file at {credfile} exists but is not readable."
+        )
+
+        self.keys: Dict[str, str] = json.loads(credfile.read_text())
+
+        for account, apikey in self.keys.items():
+            server_response = requests.get(
+                f"{self.baseurl}contacts/", params={"limit": 1}, auth=(apikey, "")
+            )
+            assert server_response.status_code == 200, (
+                f"Could not authenticate SimpleLists API key for '{account}'."
+            )
+
+    def _get_api_key(self, list_name: str) -> str:
+        """Look up the API key associated with a mailing list name.
+
+        Args:
+            list_name (str):
+                Name of the list (e.g. 'MAEFIELDFACULTY-L'), matching the
+                list-name portion of a '<list_name>-account' key in the
+                loaded credentials file.
+
+        Returns:
+            str:
+                API key for the requested list.
+        """
+
+        account = f"{list_name}-account"
+        assert account in self.keys, (
+            f"No API key found for list '{list_name}' "
+            f"(expected key '{account}' in credentials.json)."
+        )
+
+        return self.keys[account]
+
+    def get_contacts(self, list_name: str, limit: int = 1000) -> List[Dict[str, Any]]:
+        """Retrieve all contacts belonging to a mailing list.
+
+        Args:
+            list_name (str):
+                Name of the list to query (e.g. 'MAEFIELDFACULTY-L').
+            limit (int):
+                Maximum number of records to request per page (SimpleLists
+                API allows up to 1000). Defaults to 1000.
+
+        Returns:
+            list:
+                Raw contact objects (as returned by the API, one dict per
+                contact) for every contact on the list.
+        """
+
+        apikey = self._get_api_key(list_name)
+        url = f"{self.baseurl}contacts/"
+
+        records: List[Dict[str, Any]] = []
+        page = 1
+        while True:
+            server_response = requests.get(
+                url,
+                params={"list": list_name, "page": page, "limit": limit},
+                auth=(apikey, ""),
+            )
+            assert server_response.status_code == 200, (
+                f"Could not retrieve contacts for list '{list_name}' (page {page})."
+            )
+            payload = server_response.json()
+            records.extend(payload["data"])
+
+            if not payload["data"] or page * limit >= payload["count"]:
+                break
+            page += 1
+
+        return records
+
+    def create_contact(
+        self,
+        list_name: str,
+        email: str,
+        firstname: Optional[str] = None,
+        surname: Optional[str] = None,
+        notes: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Create a new contact and add them to a mailing list.
+
+        Args:
+            list_name (str):
+                Name of the list to add the new contact to.
+            email (str):
+                Primary email address for the new contact.
+            firstname (str, optional):
+                Contact's first name. Defaults to None (omitted).
+            surname (str, optional):
+                Contact's surname. Defaults to None (omitted).
+            notes (str, optional):
+                Free-text notes for the contact. Defaults to None (omitted).
+
+        Returns:
+            dict:
+                Parsed JSON response describing the created contact.
+        """
+
+        apikey = self._get_api_key(list_name)
+        url = f"{self.baseurl}contacts/"
+
+        payload: Dict[str, Any] = {
+            "emails": email,
+            "lists": list_name,
+        }
+        if firstname is not None:
+            payload["firstname"] = firstname
+        if surname is not None:
+            payload["surname"] = surname
+        if notes is not None:
+            payload["notes"] = notes
+
+        server_response = requests.post(url, data=payload, auth=(apikey, ""))
+        assert server_response.status_code == 200, (
+            f"Could not create contact '{email}' on list '{list_name}'."
+        )
+
+        return server_response.json()
+
+    def update_contact(
+        self,
+        list_name: str,
+        contact_id: int,
+        firstname: Optional[str] = None,
+        surname: Optional[str] = None,
+        notes: Optional[str] = None,
+        email: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Update an existing contact.
+
+        Args:
+            list_name (str):
+                Name of the list the API key belongs to (used only to
+                resolve the API key; SimpleLists contact ids are global,
+                not scoped to a single list).
+            contact_id (int):
+                SimpleLists internal id of the contact to update.
+            firstname (str, optional):
+                New first name. Defaults to None (left unchanged).
+            surname (str, optional):
+                New surname. Defaults to None (left unchanged).
+            notes (str, optional):
+                New free-text notes. Defaults to None (left unchanged).
+            email (str, optional):
+                New list of email addresses. Defaults to None (left
+                unchanged).
+
+        Returns:
+            dict:
+                Parsed JSON response describing the updated contact.
+        """
+
+        apikey = self._get_api_key(list_name)
+        url = f"{self.baseurl}contacts/{contact_id}/"
+
+        payload: Dict[str, Any] = {}
+        if firstname is not None:
+            payload["firstname"] = firstname
+        if surname is not None:
+            payload["surname"] = surname
+        if notes is not None:
+            payload["notes"] = notes
+        if email is not None:
+            payload["emails"] = email
+
+        assert payload, "At least one contact property must be provided to update."
+
+        server_response = requests.put(url, data=payload, auth=(apikey, ""))
+        assert server_response.status_code == 200, (
+            f"Could not update contact id {contact_id} (list '{list_name}')."
+        )
+
+        return server_response.json()
+
+    def delete_contact(self, list_name: str, contact_id: int) -> bool:
+        """Delete a contact from SimpleLists.
+
+        Args:
+            list_name (str):
+                Name of the list the API key belongs to (used only to
+                resolve the API key; SimpleLists contact ids are global,
+                not scoped to a single list).
+            contact_id (int):
+                SimpleLists internal id of the contact to delete.
+
+        Returns:
+            bool:
+                True if the API reported successful deletion.
+        """
+
+        apikey = self._get_api_key(list_name)
+        url = f"{self.baseurl}contacts/{contact_id}/"
+
+        server_response = requests.delete(url, auth=(apikey, ""))
+        assert server_response.status_code == 200, (
+            f"Could not delete contact id {contact_id} (list '{list_name}')."
+        )
+
+        return server_response.json().get("success", False)

{cornellgrading-2.25.0 → cornellgrading-2.27.0/cornellGrading.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cornellGrading
-Version: 2.25.0
+Version: 2.27.0
 Summary: Routines for interacting with Cornell installations of Canvas and Qualtrics
 Home-page: https://github.com/dsavransky/grading
 Author: Dmitry Savransky

{cornellgrading-2.25.0 → cornellgrading-2.27.0}/cornellGrading.egg-info/SOURCES.txt

@@ -11,6 +11,7 @@ cornellGrading/cornellQualtrics.py
 cornellGrading/dueDatesFromCSV.py
 cornellGrading/pandocHTMLParser.py
 cornellGrading/quizQuestionBank.py
+cornellGrading/simplelists.py
 cornellGrading/uploadPollEvScores.py
 cornellGrading/upload_MC_questions.py
 cornellGrading/utils.py