canvaslms 5.9__py3-none-any.whl → 5.10__py3-none-any.whl

canvaslms/cli/__init__.py

@@ -118,6 +118,11 @@ def main():
         default=0,
         help="Increase verbosity: -v=INFO, -vv=DEBUG, -vvv=all library debug",
     )
+    argp.add_argument(
+        "--no-cache",
+        action="store_true",
+        help="Do not read or write the persistent Canvas object cache",
+    )
     canvaslms.cli.login.add_command(subp)
     canvaslms.cli.courses.add_command(subp)
     canvaslms.cli.modules.add_command(subp)
@@ -177,7 +182,10 @@ def main():
         if "://" not in hostname:
             hostname = f"https://{hostname}"
 
-        canvas = canvaslms.cli.cache.load_canvas_cache(token, hostname)
+        if args.no_cache:
+            canvas = None
+        else:
+            canvas = canvaslms.cli.cache.load_canvas_cache(token, hostname)
 
         if not canvas:
             canvas = Canvas(hostname, token)
@@ -206,7 +214,7 @@ def main():
     if args.func:
         try:
             args.func(config, canvas, args)
-            if canvas:
+            if canvas and not args.no_cache:
                 canvaslms.cli.cache.save_canvas_cache(canvas, token, hostname)
         except EmptyListError as e:
             if args.quiet == 0:

canvaslms/cli/cli.nw

@@ -356,6 +356,19 @@ argp.add_argument("-v", "--verbose",
 @
 
 
+\subsection{Cache control}
+
+Most commands speed up by caching the Canvas API object between runs.
+Occasionally you want to bypass the cache for a single command,
+for example right after creating or updating objects.
+
+<<add global options to argp>>=
+argp.add_argument("--no-cache",
+  action="store_true",
+  help="Do not read or write the persistent Canvas object cache")
+@
+
+
 \subsection{Logging in and setting up Canvas}
 
 Each subcommand will have its own module in the package.
@@ -445,15 +458,25 @@ Before creating a new Canvas object from scratch, we try to load it from the
 persistent cache.
 This can significantly speed up commands by reusing previously fetched course
 data, assignments, users, and submissions.
+If the cached object becomes stale (for example, right after creating a quiz),
+you can bypass the cache with [[--no-cache]].
+
+For example:
+\begin{verbatim}
+canvaslms --no-cache quizzes export -c "My Course" -a "My Quiz"
+\end{verbatim}
 <<try to load canvas from cache>>=
-canvas = canvaslms.cli.cache.load_canvas_cache(token, hostname)
+if args.no_cache:
+  canvas = None
+else:
+  canvas = canvaslms.cli.cache.load_canvas_cache(token, hostname)
 @
 
 After successfully executing a command, we save the Canvas object to the cache
 for future use.
 We only save if the canvas object was actually used (not [[None]]).
 <<save canvas to cache after command>>=
-if canvas:
+if canvas and not args.no_cache:
   canvaslms.cli.cache.save_canvas_cache(canvas, token, hostname)
 @
 

canvaslms/cli/quizzes.nw

@@ -95,8 +95,13 @@ Here, [[attempt_limit]] of [[null]] means unlimited attempts.  The
 [[score_to_keep]] can be [[highest]] (default) or [[latest]].  Setting
 [[cooling_period]] to [[true]] requires [[cooling_period_seconds]] to specify
 the wait time (3600 seconds = 1 hour).  Using [[latest]] with a cooling period
-lets students ``build on their last result''---they see which questions they
-got wrong and can retry without losing progress.
+supports a workflow where students can keep trying and learn from their
+previous attempt.
+
+Note that some New Quizzes settings are not reliably settable via the API.
+In particular, in our testing (KTH Canvas, February 2026),
+[[multiple_attempts.build_on_last_attempt]] appears to be ignored on quiz
+creation/import via the New Quizzes API.
 
 \paragraph{Controlling what students see after submission.}
 To show students their score but hide the correct answers:
@@ -2574,6 +2579,9 @@ def create_command(config, canvas, args):
   if args.title:
     quiz_params['title'] = args.title
 
+  if quiz_type == "new":
+    <<warn about ignored New Quiz settings>>
+
   if 'title' not in quiz_params:
     canvaslms.cli.err(1, "Quiz title is required (use --title or include in JSON)")
 
@@ -2622,6 +2630,41 @@ to flatten these into the format the API expects:
 quiz[quiz_settings][multiple_attempts][cooling_period_seconds]=3600
 \end{verbatim}
 
+\paragraph{Some settings cannot be set via the API.}
+Canvas does not reliably apply every [[quiz_settings]] field during quiz
+creation.
+
+In our testing (KTH Canvas, February 2026),
+[[multiple_attempts.build_on_last_attempt]] appears to be \emph{read-only via the
+New Quizzes API}: it shows up in exports when set in the Canvas web UI, but both
+[[POST]] (create) and [[PATCH]] (update) silently drop the field.
+
+The official New Quizzes API documentation does not list
+[[multiple_attempts.build_on_last_attempt]] as a supported field.
+
+This means the export/create workflow cannot round-trip that setting purely via
+API calls.  We keep the schema and examples so the exported JSON is faithful,
+but users should expect that field to be ignored on import unless they set it
+manually in the UI.
+
+When [[quizzes create]] sees this field in input JSON, we emit a warning to make
+the limitation explicit.
+
+<<warn about ignored New Quiz settings>>=
+try:
+  build_on_last_attempt = (quiz_params
+    .get('quiz_settings', {})
+    .get('multiple_attempts', {})
+    .get('build_on_last_attempt', None))
+except Exception:
+  build_on_last_attempt = None
+
+if build_on_last_attempt is not None:
+  canvaslms.cli.warn(
+    "New Quizzes: quiz_settings.multiple_attempts.build_on_last_attempt "
+    "is ignored by the API on some Canvas instances; set it in the web UI")
+@
+
 <<functions>>=
 def create_new_quiz(course, requester, quiz_params):
   """Creates a New Quiz via the New Quizzes API
@@ -2646,7 +2689,9 @@ def create_new_quiz(course, requester, quiz_params):
       _url="new_quizzes",
       **params
     )
-    return response.json()
+    data = response.json()
+
+    return data
   except Exception as e:
     canvaslms.cli.warn(f"Failed to create New Quiz: {e}")
     return None
@@ -2918,6 +2963,10 @@ NEW_QUIZ_MULTIPLE_ATTEMPTS_SCHEMA = {
         'default': 'highest',
         'description': 'Which score to keep: average, first, highest, or latest'
     },
+    'build_on_last_attempt': {
+        'default': False,
+        'description': 'Whether students continue from their previous attempt (may be ignored by the API on import)'
+    },
     'cooling_period': {
         'default': False,
         'description': 'Whether to require a waiting period between attempts'
@@ -6277,6 +6326,11 @@ The [[quiz_settings]] object within [[settings]] controls advanced quiz behavior
 \item[[[session_time_limit_in_seconds]]] Time limit in seconds
 \end{description}
 
+Some fields may be present in exports but ignored when creating a quiz via the
+API.
+In particular, see the note in \cref{sec:advanced-quiz-settings} about
+[[multiple_attempts.build_on_last_attempt]].
+
 <<constants>>=
 EXAMPLE_FULL_NEW_QUIZ_JSON = {
   "quiz_type": "new",
@@ -6320,6 +6374,7 @@ EXAMPLE_FULL_NEW_QUIZ_JSON = {
         "attempt_limit": False,
         "max_attempts": None,
         "score_to_keep": "latest",
+        "build_on_last_attempt": True,
         "cooling_period": True,
         "cooling_period_seconds": 3600
       },
@@ -7899,4 +7954,3 @@ def get_bank_items(requester, bank_id):
     # Item Banks API often isn't accessible - this is expected
     return []
 @
-

canvaslms/cli/quizzes.py

@@ -143,6 +143,10 @@ NEW_QUIZ_MULTIPLE_ATTEMPTS_SCHEMA = {
         "default": "highest",
         "description": "Which score to keep: average, first, highest, or latest",
     },
+    "build_on_last_attempt": {
+        "default": False,
+        "description": "Whether students continue from their previous attempt (may be ignored by the API on import)",
+    },
     "cooling_period": {
         "default": False,
         "description": "Whether to require a waiting period between attempts",
@@ -645,6 +649,7 @@ EXAMPLE_FULL_NEW_QUIZ_JSON = {
                 "attempt_limit": False,
                 "max_attempts": None,
                 "score_to_keep": "latest",
+                "build_on_last_attempt": True,
                 "cooling_period": True,
                 "cooling_period_seconds": 3600,
             },
@@ -2105,6 +2110,22 @@ def create_command(config, canvas, args):
     if args.title:
         quiz_params["title"] = args.title
 
+    if quiz_type == "new":
+        try:
+            build_on_last_attempt = (
+                quiz_params.get("quiz_settings", {})
+                .get("multiple_attempts", {})
+                .get("build_on_last_attempt", None)
+            )
+        except Exception:
+            build_on_last_attempt = None
+
+        if build_on_last_attempt is not None:
+            canvaslms.cli.warn(
+                "New Quizzes: quiz_settings.multiple_attempts.build_on_last_attempt "
+                "is ignored by the API on some Canvas instances; set it in the web UI"
+            )
+
     if "title" not in quiz_params:
         canvaslms.cli.err(1, "Quiz title is required (use --title or include in JSON)")
 
@@ -2160,7 +2181,9 @@ def create_new_quiz(course, requester, quiz_params):
         response = requester.request(
             method="POST", endpoint=endpoint, _url="new_quizzes", **params
         )
-        return response.json()
+        data = response.json()
+
+        return data
     except Exception as e:
         canvaslms.cli.warn(f"Failed to create New Quiz: {e}")
         return None

canvaslms/cli/results.nw

@@ -569,33 +569,46 @@ The available summary functions and the default one can be found in
 \subsection{Producing a list of missing assignments}
 
 Now we want to look at the missing option.
-If the user supplies this option, we want to produce a list of missing 
-assignments.
-Similarly to summarizing a group, we also want to use different modules to 
-produce the missing assignments.
-We'll use an option missing which takes an optional name of such a module.
+If the user supplies this option, we want to produce a list of missing
+assignments instead of grades.
+
+Previously, this option could take an optional module name, creating a confusing
+interface where both [[--missing module]] and [[-S module]] could specify
+modules.
+We simplify this: [[--missing]] is now a simple flag, and the module specified
+via [[-S]] provides the [[missing_assignments]] function if it has one.
+If the [[-S]] module doesn't provide [[missing_assignments]], we fall back to
+the default implementation in this module.
+
+This design follows the principle that each grading module knows best what
+\enquote{missing} means for its grading policy:
+\begin{description}
+\item[Conjunctive modules] (all must pass): Any assignment without a passing
+  grade is missing.
+\item[Disjunctive modules] (at least one must pass): Assignments are only
+  \enquote{missing} if the student has NO passing grades at all.
+\end{description}
 <<add option for missing assignments>>=
-<<define [[default_missing_module]]>>
 results_parser.add_argument("--missing",
-  required=False, nargs="?",
-  const=default_missing_module, default=None,
+  action="store_true",
   help="Produce a list of missing assignments instead of grades. "
-       "You can supply a custom module to this option, the module must "
-       "contain a "
-       "function `missing_assignments(assignments_list, users_list). "
+       "Uses the summary module's missing_assignments() if available, "
+       "otherwise uses the default implementation. "
        <<missing module behaviour>>
        "This option only has effect when working with assignment groups.")
 @
 
-This lets us load the module and use it to produce the missing assignments, in 
-a similar fashion as above.
+Since [[--missing]] is now a simple flag, we use the summary module (specified
+via [[-S]]) to provide the [[missing_assignments]] function.
+If the summary module doesn't have one, we fall back to this module's default.
 <<load the correct missing module as [[missing]]>>=
 if args.missing:
-  try:
-    missing = load_module(args.missing)
-  except Exception as err:
-    canvaslms.cli.err(1, f"Error loading missing module "
-      f"'{args.missing}': {err}")
+  <<load the correct summary module as [[summary]]>>
+  if hasattr(summary, 'missing_assignments'):
+    missing = summary
+  else:
+    import canvaslms.cli.results
+    missing = canvaslms.cli.results
 @
 
 Now, to the main part of the problem.
@@ -624,8 +637,18 @@ for user, assignment, reason in missing_results:
 \subsubsection{The default missing module}
 
 We'll now cover a default function for the missing assignments.
-We'll put it in the same module as the [[results]] CLI command, not in a 
+We'll put it in the same module as the [[results]] CLI command, not in a
 separate module.
+
+The function accepts an optional [[is_passing]] callback that determines whether
+a grade counts as passing.
+This allows grading modules to reuse this shared implementation while providing
+their own definition of what \enquote{passing} means.
+For example, [[conjunctavg]] considers only A--E and P as passing, while
+[[conjunctavgsurvey]] also accepts numeric grades.
+
+If no [[is_passing]] callback is provided, we fall back to regex matching
+against [[passing_regex]].
 <<functions>>=
 def missing_assignments(assignments_list, users_list,
                         <<optional [[missing_assignments]] args>>):
@@ -638,8 +661,6 @@ def missing_assignments(assignments_list, users_list,
     for assignment in assignments_list:
       <<skip if [[assignment]] is optional>>
       <<if [[assignment]] is missing for [[user]], yield it>>
-<<define [[default_missing_module]]>>=
-default_missing_module = "canvaslms.cli.results"
 @
 
 We'll add [[<<optional [[missing_assignments]] args>>]] to the function to make 
@@ -663,10 +684,13 @@ We don't want to make it sound like an optional assignment is mandatory.
 @
 
 This gives us something like this.
+We check if the grade passes using either the [[is_passing]] callback (if
+provided) or the [[passing_regex]].
 <<if [[assignment]] is missing for [[user]], yield it>>=
 try:
   submission = assignment.get_submission(user)
 except canvasapi.exceptions.ResourceDoesNotExist:
+  yield user, assignment, "no submission exists"
   continue
 
 if submission is None:
@@ -677,45 +701,61 @@ elif submission.grade is None:
           f"submitted on {canvaslms.cli.utils.format_local_time(submission.submitted_at)}, but not graded"
   else:
     yield user, assignment, "not done"
-elif not filter_grade(submission.grade, passing_regex):
-  if hasattr(submission, 'submitted_at') and submission.submitted_at and \
-        hasattr(submission, 'graded_at') and submission.graded_at and \
-        submission.submitted_at > submission.graded_at:
-    yield user, assignment, \
-          f"not a passing grade ({submission.grade}), resubmission not graded"
-  else:
-    yield user, assignment, \
-          f"not a passing grade ({submission.grade})"
+else:
+  <<check if grade passes using callback or regex>>
+  if not grade_passes:
+    if hasattr(submission, 'submitted_at') and submission.submitted_at and \
+          hasattr(submission, 'graded_at') and submission.graded_at and \
+          submission.submitted_at > submission.graded_at:
+      yield user, assignment, \
+            f"not a passing grade ({submission.grade}), resubmission not graded"
+    else:
+      yield user, assignment, \
+            f"not a passing grade ({submission.grade})"
+<<check if grade passes using callback or regex>>=
+if is_passing is not None:
+  grade_passes = is_passing(submission.grade)
+else:
+  grade_passes = filter_grade(submission.grade, passing_regex)
 @
 
-Now, we need that [[passing_regex]], so we can add it to the optional 
+Now, we need that [[passing_regex]], so we can add it to the optional
 arguments, with a default value (same as above).
 We add the most common grading scales.
-But we also add number scores, which can be used for mandatory surveys and the 
+But we also add number scores, which can be used for mandatory surveys and the
 like.
 <<optional [[missing_assignments]] args>>=
 passing_regex=PASSING_REGEX,
 @
 
-Next, if we want to be able to skip optional assignments, we can add an 
+Next, if we want to be able to skip optional assignments, we can add an
 optional argument for that.
 <<optional [[missing_assignments]] args>>=
-optional_assignments = None,
+optional_assignments=None,
+@
+
+Finally, we add the [[is_passing]] callback.
+If provided, this function takes a grade and returns [[True]] if it's passing.
+This lets grading modules define their own semantics for what constitutes a
+passing grade.
+<<optional [[missing_assignments]] args>>=
+is_passing=None,
 @
 
 This allows us to make the call to the function as follows.
-We check if it's the default function or not, if it is we can pass additional 
-arguments from the CLI arguments.
+We check if it's the default function or not.
+If it is, we pass additional arguments from the CLI.
+If not, the module provides its own implementation with module-specific
+semantics (which may or may not use these arguments).
+
+We always pass [[passing_regex]] and [[optional_assignments]] since these are
+CLI-level concerns that any module might want to honor.
 <<let [[missing_results]] be the result of [[missing.missing_assignments]]>>=
-if missing.missing_assignments == missing_assignments:
-  missing_results = missing.missing_assignments(
-                                  assignments_list, users_list,
-                                  passing_regex=args.filter_grades,
-                                  optional_assignments=args.optional_assignments
-                                )
-else:
-  missing_results = missing.missing_assignments(
-    assignments_list, users_list)
+missing_results = missing.missing_assignments(
+  assignments_list, users_list,
+  passing_regex=args.filter_grades,
+  optional_assignments=args.optional_assignments
+)
 @
 
 All that is missing now is the optional assignments argument for the parser.

canvaslms/cli/results.py

@@ -124,23 +124,25 @@ def summarize_assignment_groups(canvas, args):
             if args.missing:
                 if args.missing:
                     try:
-                        missing = load_module(args.missing)
+                        summary = load_module(args.summary_module)
                     except Exception as err:
                         canvaslms.cli.err(
                             1,
-                            f"Error loading missing module " f"'{args.missing}': {err}",
+                            f"Error loading summary module "
+                            f"'{args.summary_module}': {err}",
                         )
-                if missing.missing_assignments == missing_assignments:
-                    missing_results = missing.missing_assignments(
-                        assignments_list,
-                        users_list,
-                        passing_regex=args.filter_grades,
-                        optional_assignments=args.optional_assignments,
-                    )
-                else:
-                    missing_results = missing.missing_assignments(
-                        assignments_list, users_list
-                    )
+                    if hasattr(summary, "missing_assignments"):
+                        missing = summary
+                    else:
+                        import canvaslms.cli.results
+
+                        missing = canvaslms.cli.results
+                missing_results = missing.missing_assignments(
+                    assignments_list,
+                    users_list,
+                    passing_regex=args.filter_grades,
+                    optional_assignments=args.optional_assignments,
+                )
                 for user, assignment, reason in missing_results:
                     yield [
                         course.course_code,
@@ -198,23 +200,25 @@ def summarize_modules(canvas, args):
             if args.missing:
                 if args.missing:
                     try:
-                        missing = load_module(args.missing)
+                        summary = load_module(args.summary_module)
                     except Exception as err:
                         canvaslms.cli.err(
                             1,
-                            f"Error loading missing module " f"'{args.missing}': {err}",
+                            f"Error loading summary module "
+                            f"'{args.summary_module}': {err}",
                         )
-                if missing.missing_assignments == missing_assignments:
-                    missing_results = missing.missing_assignments(
-                        assignments_list,
-                        users_list,
-                        passing_regex=args.filter_grades,
-                        optional_assignments=args.optional_assignments,
-                    )
-                else:
-                    missing_results = missing.missing_assignments(
-                        assignments_list, users_list
-                    )
+                    if hasattr(summary, "missing_assignments"):
+                        missing = summary
+                    else:
+                        import canvaslms.cli.results
+
+                        missing = canvaslms.cli.results
+                missing_results = missing.missing_assignments(
+                    assignments_list,
+                    users_list,
+                    passing_regex=args.filter_grades,
+                    optional_assignments=args.optional_assignments,
+                )
                 for user, assignment, reason in missing_results:
                     yield [
                         course.course_code,
@@ -338,6 +342,7 @@ def missing_assignments(
     users_list,
     passing_regex=PASSING_REGEX,
     optional_assignments=None,
+    is_passing=None,
 ):
     """
     Returns tuples of missing assignments.
@@ -362,6 +367,7 @@ def missing_assignments(
             try:
                 submission = assignment.get_submission(user)
             except canvasapi.exceptions.ResourceDoesNotExist:
+                yield user, assignment, "no submission exists"
                 continue
 
             if submission is None:
@@ -371,17 +377,22 @@ def missing_assignments(
                     yield user, assignment, f"submitted on {canvaslms.cli.utils.format_local_time(submission.submitted_at)}, but not graded"
                 else:
                     yield user, assignment, "not done"
-            elif not filter_grade(submission.grade, passing_regex):
-                if (
-                    hasattr(submission, "submitted_at")
-                    and submission.submitted_at
-                    and hasattr(submission, "graded_at")
-                    and submission.graded_at
-                    and submission.submitted_at > submission.graded_at
-                ):
-                    yield user, assignment, f"not a passing grade ({submission.grade}), resubmission not graded"
+            else:
+                if is_passing is not None:
+                    grade_passes = is_passing(submission.grade)
                 else:
-                    yield user, assignment, f"not a passing grade ({submission.grade})"
+                    grade_passes = filter_grade(submission.grade, passing_regex)
+                if not grade_passes:
+                    if (
+                        hasattr(submission, "submitted_at")
+                        and submission.submitted_at
+                        and hasattr(submission, "graded_at")
+                        and submission.graded_at
+                        and submission.submitted_at > submission.graded_at
+                    ):
+                        yield user, assignment, f"not a passing grade ({submission.grade}), resubmission not graded"
+                    else:
+                        yield user, assignment, f"not a passing grade ({submission.grade})"
 
 
 def add_command(subp):
@@ -432,17 +443,12 @@ def add_command(subp):
         + """. \
              Or provide a path to your own Python file.""",
     )
-    default_missing_module = "canvaslms.cli.results"
     results_parser.add_argument(
         "--missing",
-        required=False,
-        nargs="?",
-        const=default_missing_module,
-        default=None,
+        action="store_true",
         help="Produce a list of missing assignments instead of grades. "
-        "You can supply a custom module to this option, the module must "
-        "contain a "
-        "function `missing_assignments(assignments_list, users_list). "
+        "Uses the summary module's missing_assignments() if available, "
+        "otherwise uses the default implementation. "
         "The default module checks if all things are graded or submitted. "
         "This option only has effect when working with assignment groups.",
     )