cornellGrading 2.20.1__tar.gz → 2.22.0__tar.gz

{cornellgrading-2.20.1/cornellGrading.egg-info → cornellgrading-2.22.0}/PKG-INFO

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

{cornellgrading-2.20.1 → cornellgrading-2.22.0}/cornellGrading/__init__.py

@@ -1,4 +1,4 @@
 name = "cornellGrading"
-__version__ = "2.20.1"
+__version__ = "2.22.0"
 from .cornellGrading import cornellGrading
 from .cornellQualtrics import cornellQualtrics

{cornellgrading-2.20.1 → cornellgrading-2.22.0}/cornellGrading/cornellGrading.py

@@ -284,9 +284,9 @@ class cornellGrading:
         """Locate folder by name
 
         Args:
-             folderName (str):
+            folderName (str):
                 Name of folder to return.  Must be exact match.
-                To see all assignments do:
+                To see all folders do:
                 >> for a in c.course.get_folders(): print(a.name)
 
         Returns:
@@ -2086,6 +2086,7 @@ class cornellGrading:
         preamble="",
         selfGradeDueDelta=7,
         selfGradeReleasedDelta=3,
+        extraQuestions=[],
     ):
         """Create a page with reference solutions and a New Quiz linking to the page for
         student self-assemssent.
@@ -2108,6 +2109,8 @@ class cornellGrading:
             selfGradeReleasedDelta (float):
                 Days after initial hw duedate that self-grading (and solutions) are
                 released.
+            extraQuestions (list(dict)):
+                List of dicts defining additional questions to ask
 
         Returns:
             None
@@ -2167,9 +2170,13 @@ class cornellGrading:
         for j in range(nprobs):
             tmp = item.copy()
             tmp["position"] = j + 1
-            tmp["entry"]["title"] = f"Problem {j+1} score"
+            tmp["entry"]["title"] = f"Problem {j + 1} score"
             self.addNewQuizItem(nq.id, tmp)
 
+        for j, q in enumerate(extraQuestions):
+            q["position"] = nprobs + j + 1
+            self.addNewQuizItem(nq.id, q)
+
         # publish quiz
         ass = self.getAssignment(nq.title)
         ass.edit(assignment={"published": True})
@@ -2288,7 +2295,7 @@ class cornellGrading:
 
         return submittedScoreNoAssignment, submittedAssignmentNoScore
 
-    def genNpointNewQuizItem(self, n, item_body=None, title=None,  position=0):
+    def genNpointNewQuizItem(self, n, item_body=None, title=None, position=0):
         """Generate a New Quiz multiple choice, variable point question with answers
         ranging from 0 to n and each answer worth the equivalent number of points.
 
@@ -2357,8 +2364,69 @@ class cornellGrading:
 
         return q
 
+    def genBinaryNewQuizItem(self, n, item_body, title, position=0):
+        """Generate a New Quiz multiple choice, variable point question with answers
+        'Yes' (earning n points) and 'No' (earning 0 points).
+
+        Args:
+            n (int):
+                Number of points possible.  Question will have n+1 options (from 0 to n)
+                with each response worth the equivalent number of points
+            item_body (str):
+                Question text (html formatted). This will automatically be wrapped in
+                <p>...</p>
+            title (str):
+                Question title
+            position (int):
+                Position of question in quiz.  Defaults to 0
+
+        Returns:
+            dict:
+                New Quiz Multiple choice question definition
+
+        """
+
+        # generate UUIDs
+        uuids = [uuid.uuid4() for _ in range(2)]
+
+        # create choices and values dict list
+        choices = []
+        values = []
+        for j, val in enumerate(["Yes", "No"]):
+            choices.append(
+                {"id": f"{uuids[j]}", "position": j + 1, "item_body": f"<p>{val}</p>"}
+            )
+            values.append({"value": f"{uuids[j]}", "points": int(val == "Yes") * n})
+
+        q = {
+            "position": position,
+            "points_possible": float(n),
+            "entry_type": "Item",
+            "status": "immutable",
+            "entry": {
+                "title": title,
+                "item_body": f"<p>{item_body}</p>",
+                "calculator_type": "none",
+                "interaction_data": {"choices": choices},
+                "properties": {
+                    "shuffle_rules": {"choices": {"to_lock": [], "shuffled": False}},
+                    "vary_points_by_answer": True,
+                },
+                "scoring_data": {
+                    "value": f"{uuids[0]}",
+                    "values": values,
+                },
+                "answer_feedback": {},
+                "scoring_algorithm": "VaryPointsByAnswer",
+                "interaction_type_slug": "choice",
+                "feedback": {},
+            },
+        }
+
+        return q
+
     def genNewQuizMultipleChoice(
-        self, question, options, correct_ind, points=1, position=0
+        self, question, options, correct_ind, points=1, position=0, fightml=None
     ):
         """Generate a new quiz-style multiple choice question dictionary
 
@@ -2373,6 +2441,8 @@ class cornellGrading:
                 Number of points for correct answer (defaults to 1).
             position (int):
                 Position of question in quiz.  Defaults to 0
+            fightml (str, optional):
+                HTML string from figure upload. Defaults to None.
 
         Returns:
             dict:
@@ -2394,6 +2464,10 @@ class cornellGrading:
                 }
             )
 
+        qtxt = f"<p>{convalllatex(question)}</p>"
+        if fightml is not None:
+            qtxt = f"{qtxt}\n<p>{fightml}</p>"
+
         q = {
             "position": position,
             "points_possible": float(points),
@@ -2404,7 +2478,7 @@ class cornellGrading:
             "status": "mutable",
             "entry": {
                 "title": question,
-                "item_body": f"<p>{convalllatex(question)}</p>",
+                "item_body": qtxt,
                 "calculator_type": "none",
                 "interaction_data": {"choices": choices},
                 "properties": {
@@ -2422,7 +2496,7 @@ class cornellGrading:
         return q
 
     def genQuizMultipleChoice(
-        self, question, options, correct_ind, points=1, position=0
+        self, question, options, correct_ind, points=1, position=0, fightml=None
     ):
         """ "Generate a classic quiz-style multiple choice question dictionary
 
@@ -2437,6 +2511,8 @@ class cornellGrading:
                 Number of points for correct answer (defaults to 1).
             position (int):
                 Position of question in quiz.  Defaults to 0
+            fightml (str, optional):
+                HTML string from figure upload. Defaults to None.
 
         Returns:
             dict:
@@ -2454,9 +2530,13 @@ class cornellGrading:
                 }
             )
 
+        qtxt = f"<p>{convalllatex(question)}</p>"
+        if fightml is not None:
+            qtxt = f"{qtxt}\n<p>{fightml}</p>"
+
         q = {
             "question_name": question,
-            "question_text": f"<p>{convalllatex(question)}</p>",
+            "question_text": qtxt,
             "question_type": "multiple_choice_question",
             "position": 0,
             "points_possible": points,
@@ -2465,7 +2545,7 @@ class cornellGrading:
 
         return q
 
-    def genQuizFromPolev(self, allqs, quiz):
+    def genQuizFromPollEv(self, allqs, quiz, imagePath=None, imageFolder="QuizImages"):
         """Generate quiz items from a PollEv formatted CSV input file
 
         Args:
@@ -2473,6 +2553,11 @@ class cornellGrading:
                 Table of questions and answers, formatted in PolEV CSV upload style
             quiz (canvasapi.new_quiz.NewQuiz or canvasapi.quiz.Quiz):
                 Quiz object
+            imagePath (str, optional):
+                Full path to location on disk of any image files to use in questions.
+            imageFolder (str):
+                Name of Canvas folder to upload images to. Defaults to 'QuizImages'. If
+                folder does not exist, it will be created as a hidden folder.
 
         Returns:
             None
@@ -2480,6 +2565,10 @@ class cornellGrading:
         .. note::
             Poll Everywhere upload format documentation is available here:
             https://support.polleverywhere.com/hc/en-us/articles/1260801546530-Import-questions
+            The format is expanded by adding a 'Figure' column.  The contents of this
+            column should be the filename (without extension) of a figure associated
+            with the question.  If any figures are present, input `imagePath` must be
+            set. Images must be in png format with extension .png.
 
         """
 
@@ -2493,11 +2582,22 @@ class cornellGrading:
             if col.startswith("Option"):
                 optcols.append(col)
 
+        # check for any figures and make sure we have enough information to upload them
+        if np.any(~allqs["Figure"].isna()):
+            assert (
+                imagePath is not None
+            ), "imagePath must be set if questions include figures."
+            try:
+                figFolder = self.getFolder(imageFolder)
+            except AssertionError:
+                figFolder = self.createFolder(imageFolder, hidden=True)
+
         # iterate through rows, creating the questions
-        for j, row in allqs.iterrows():
+        for k, row in allqs.iterrows():
+            # process question and responses
             question = row.Title
             opts = row[optcols].values
-            opts = opts[~pandas.isna(opts)]
+            opts = opts[~pandas.isna(opts)].astype(str)
             correct_ind = [
                 j
                 for j, s in enumerate(opts)
@@ -2507,15 +2607,78 @@ class cornellGrading:
             correct_ind = correct_ind[0]
             opts[correct_ind] = opts[correct_ind].strip("***")
 
+            # process figure (if any)
+            if not (pandas.isna(row.Figure)):
+                impath = os.path.join(imagePath, f"{row.Figure}.png")
+                fightml = self.uploadFigure(impath, figFolder)
+            else:
+                fightml = None
+
             # create and add the question depending on quiz type
             if isinstance(quiz, canvasapi.new_quiz.NewQuiz):
                 q = self.genNewQuizMultipleChoice(
-                    question, opts.astype(str), correct_ind, position=j + 1
+                    question,
+                    opts.astype(str),
+                    correct_ind,
+                    position=k + 1,
+                    fightml=fightml,
                 )
 
                 self.addNewQuizItem(quiz.id, q)
             else:
                 q = self.genQuizMultipleChoice(
-                    question, opts.astype(str), correct_ind, position=j + 1
+                    question,
+                    opts.astype(str),
+                    correct_ind,
+                    position=k + 1,
+                    fightml=fightml,
                 )
                 quiz.create_question(question=q)
+
+    def uploadFigure(self, impath, figFolder):
+        """Upload a figure and generate an HTML string for embedding it. If filename
+        already exists in the folder, use that rather than overwriting.
+
+        Args:
+            impath (str):
+                Full path of disk to figure file
+            figFolder (canvasapi.folder.Folder):
+                Canvas folder to upload to
+
+        Returns:
+            str:
+                HTML string representing the figure
+        """
+
+        filename = os.path.split(impath)[-1]
+        haveFile = False
+        for file in figFolder.get_files():
+            if file.filename == filename:
+                haveFile = True
+                fig = {
+                    "id": file.id,
+                    "uuid": file.uuid,
+                    "display_name": file.display_name,
+                }
+                break
+
+        if not haveFile:
+            assert os.path.exists(impath), f"Can not locate {impath}."
+            status, fig = figFolder.upload(impath)
+            assert status, f"Failed to upload {impath}."
+
+        figsrc = (
+            f"{self.canvas._Canvas__requester.original_url}/courses/"
+            f"{self.course.id}/files/{fig['id']}/preview?verifier={fig['uuid']}"
+        )
+        apisrc = (
+            f"{self.canvas._Canvas__requester.base_url}courses/"
+            f"{self.course.id}/files/{fig['id']}"
+        )
+
+        fightml = (
+            f'<img id="{fig["id"]}" src="{figsrc}" alt="{fig["display_name"]}" '
+            f'width="600" data-api-endpoint="{apisrc}" data-api-returntype="File">'
+        )
+
+        return fightml

{cornellgrading-2.20.1 → cornellgrading-2.22.0}/cornellGrading/cornellQualtrics.py

@@ -690,6 +690,79 @@ class cornellQualtrics:
 
         return response.json()["result"]
 
+    def exportUploadedFiles(self, surveyId, DataExportTags, saveDir=None):
+        """Download all user uploaded files associated with specific questions from one
+        survey
+
+        Args:
+            surveyId (str):
+                Unique id string of survey.  Get either from web interface or via
+                getSurveyId
+            DataExportTags (list):
+                Data Export Tags for all questions with uploaded files
+            saveDir (str, optional):
+                Full path to save location.  If None (default) uses system tmp dir
+
+        Returns:
+            str:
+                Full path to directory where the survey results and all files are saved.
+                The survey results will be a CSV file with a filename that is the same
+                as the survey name, except with any colons replaced with underscores.
+                The files will be named as: ResponseId-FileId-fileName where ResponseId
+                and FileId match the entries in the survey results and fileName is the
+                original fileName of the upload.
+
+        Notes:
+            https://api.qualtrics.com/1071635f5a615-retrieve-a-user-uploaded-file
+
+        """
+
+        # get survey name from ID
+        if surveyId not in self.surveyIds:
+            self.listSurveys()
+            assert surveyId in self.surveyIds, f"Survey ID {surveyId} not found."
+
+        surveyname = self.surveyNames[self.surveyIds == surveyId][0]
+
+        # synthesize base URL
+        baseUrl = (
+            f"https://{self.dataCenter}{self.qualtricsapi}surveys/{surveyId}/responses/"
+        )
+
+        # export survey results and read output
+        tmpdir = self.exportSurvey(surveyId, saveDir=saveDir)
+        if ":" in surveyname:
+            surveyname = surveyname.replace(":", "_")
+        surveyfile = os.path.join(tmpdir, surveyname + ".csv")
+        assert os.path.isfile(surveyfile), "Survey results not where expected."
+        surveyres = pandas.read_csv(surveyfile, header=[0, 1, 2])
+
+        # get all response IDs
+        responseIds = surveyres["ResponseId"].values.flatten()
+
+        # loop through each data export tag and download the associated file for each
+        # response
+        for DataExportTag in DataExportTags:
+            # get all ids and filenames for current tag
+            fids = surveyres[f"{DataExportTag}_Id"].values.flatten()
+            fnames = surveyres[f"{DataExportTag}_Name"].values.flatten()
+
+            # loop through everything
+            for rid, fid, fname in zip(responseIds, fids, fnames):
+                durl = f"{baseUrl}{rid}/uploaded-files/{fid}"
+                requestDownload = requests.request(
+                    "GET", durl, headers=self.headers_post, stream=True
+                )
+                assert (
+                    requestDownload.status_code == 200
+                ), f"Download failed for file {fid} on response {rid}."
+
+                outname = os.path.join(tmpdir, f"{rid}-{fid}-{fname}")
+                with open(outname, "wb") as ff:
+                    ff.write(requestDownload.content)
+
+        return tmpdir
+
     def exportSurvey(self, surveyId, fileFormat="csv", useLabels="true", saveDir=None):
         """Download and extract survey results
 
@@ -701,7 +774,7 @@ class cornellQualtrics:
                 Format to download (must be csv, tsv, or spss)
             useLabels (str):
                 Use choice labels ("true" or "false", defaults "true")
-            saveDir (str):
+            saveDir (str, optional):
                 Full path to save location.  If None (default) uses system tmp dir
 
         Returns:

{cornellgrading-2.20.1 → cornellgrading-2.22.0/cornellGrading.egg-info}/PKG-INFO

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