canvaslms 5.9__tar.gz → 5.10__tar.gz

{canvaslms-5.9 → canvaslms-5.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: canvaslms
-Version: 5.9
+Version: 5.10
 Summary: Command-line interface to Canvas LMS
 License-Expression: MIT
 License-File: LICENSE

{canvaslms-5.9 → canvaslms-5.10}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "canvaslms"
-version = "5.9"
+version = "5.10"
 description = "Command-line interface to Canvas LMS"
 authors = [
   {name = "Daniel Bosk", email = "daniel@bosk.se"}

{canvaslms-5.9 → canvaslms-5.10}/src/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-5.9 → canvaslms-5.10}/src/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-5.9 → canvaslms-5.10}/src/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-5.9 → canvaslms-5.10}/src/canvaslms/cli/users.nw

@@ -746,6 +746,47 @@ def test_list_users_sets_course_attribute(
     assert result[0].course == mock_course
 @
 
+\subsubsection{Testing [[process_user_option]] with role filtering}
+
+This is a regression test for a bug where [[args.role]] (a string) was passed 
+directly to [[filter_users]], causing character-by-character iteration that 
+matched all enrollment types.
+
+We need to verify that [[process_user_option]] correctly converts the single 
+role string from argparse into a list before passing it to [[filter_users]].
+<<test functions>>=
+def test_process_user_option_filters_by_role(
+    mock_course, mock_student, mock_ta
+):
+    """Test that process_user_option correctly filters users by role"""
+    # Setup mock course and canvas
+    mock_course.get_users = Mock(return_value=[mock_student, mock_ta])
+    mock_canvas = Mock()
+    mock_canvas.get_courses = Mock(return_value=[mock_course])
+    
+    # Setup args with role="student" (as a string, like argparse provides)
+    mock_args = Mock()
+    mock_args.course = ".*"
+    mock_args.user = ".*"
+    mock_args.role = "student"  # Single string, not a list
+    
+    # Call process_user_option
+    result = users_module.process_user_option(mock_canvas, mock_args)
+    
+    # Verify only student is returned, not TA
+    assert len(result) == 1
+    assert result[0].id == 100  # Alice Student
+    
+    # Now test with TA role
+    mock_course.get_users = Mock(return_value=[mock_student, mock_ta])
+    mock_args.role = "ta"
+    result = users_module.process_user_option(mock_canvas, mock_args)
+    
+    # Verify only TA is returned
+    assert len(result) == 1
+    assert result[0].id == 200  # Bob TA
+@
+
 Second, we provide the most general function, [[filter_users]], which takes a
 list of courses, a list of Canvas roles and a regex as arguments.
 It returns the matching users.
@@ -934,13 +975,35 @@ When processing this option, we need to filter by course first, so we use the
 processing from the [[courses]] module to get the list of courses matching the 
 courses options.
 Then we simply filter all users.
+
+\subsubsection{Converting role string to list}
+
+The [[--role]] option (defined in [[add_user_roles_option]]) accepts a single 
+role string like [["student"]] or [["ta"]] via argparse.
+However, [[filter_users]] and [[list_users]] expect a list of role names, 
+since they need to iterate over roles when checking if any role matches a 
+user's enrollments.
+
+If we mistakenly pass a string directly to [[filter_users]], Python will 
+iterate over individual characters (for example, [["student"]] becomes 
+[['s']], [['t']], [['u']], [['d']], [['e']], [['n']], [['t']]) when checking 
+roles.
+This causes all enrollment types to match, since characters like [['t']], 
+[['a']], [['e']], [['n']] appear in [["StudentEnrollment"]], 
+[["TaEnrollment"]], [["TeacherEnrollment"]], and so on.
+
+Therefore, we must convert [[args.role]] to a single-element list before 
+passing it to [[filter_users]].
 <<functions>>=
 def process_user_option(canvas, args):
   """Processes the user option from command line, returns a list of users"""
+  # args.role is a single string (e.g., "student"), but filter_users expects
+  # a list of role names. Convert it to a single-element list.
+  roles_list = [args.role] if args.role else []
   user_list = list(filter_users(
     courses.process_course_option(canvas, args),
     args.user,
-    roles=args.role))
+    roles=roles_list))
   if not user_list:
     raise canvaslms.cli.EmptyListError("No users found matching the criteria")
   return user_list

{canvaslms-5.9 → canvaslms-5.10}/src/canvaslms/grades/conjunctavg.nw

@@ -133,7 +133,7 @@ graders += results.all_graders(submission)
 
 \subsection{Computing averages}
 
-To compute the average for the A--E grades; we will convert the grades into 
+To compute the average for the A--E grades; we will convert the grades into
 integers, compute the average, round the value to an integer and convert back.
 <<helper functions>>=
 def a2e_average(grades):
@@ -153,3 +153,52 @@ def int_to_grade(int_grade):
   return grade_map_inv[int_grade]
 @
 
+
+\subsection{Finding missing assignments}
+
+For conjunctive average grading, a student is \enquote{missing} any assignment
+that doesn't have a passing grade.
+Since ALL assignments must pass to get a grade, each individual failure
+prevents the student from completing the group.
+
+This is in contrast to disjunctive grading (see [[disjunctmax]]), where
+a student only needs ONE passing grade---there, we wouldn't report
+individual failing assignments as \enquote{missing} if the student already
+passed via another assignment.
+
+We define what counts as a passing grade for this module.
+A grade is passing if it's one of A--E, P, or \enquote{complete}.
+<<helper functions>>=
+def is_passing_grade(grade):
+  """
+  Returns True if grade is passing for conjunctive A-E grading.
+  """
+  if grade is None:
+    return False
+  if grade in ["A", "B", "C", "D", "E", "P"]:
+    return True
+  if isinstance(grade, str) and grade.casefold() == "complete":
+    return True
+  return False
+@
+
+We reuse the shared [[missing_assignments]] implementation from
+[[canvaslms.cli.results]], providing our module-specific [[is_passing_grade]]
+function as a callback.
+<<helper functions>>=
+def missing_assignments(assignments_list, users_list,
+                        passing_regex=None,
+                        optional_assignments=None):
+  """
+  Returns missing assignments for conjunctive average grading.
+
+  Any assignment without a passing grade (A-E, P, or complete) is missing.
+  """
+  from canvaslms.cli import results
+  return results.missing_assignments(
+    assignments_list, users_list,
+    optional_assignments=optional_assignments,
+    is_passing=is_passing_grade
+  )
+@
+

{canvaslms-5.9 → canvaslms-5.10}/src/canvaslms/grades/conjunctavgsurvey.nw

@@ -126,3 +126,53 @@ For who graded, we simply extract the list of graders from the submissions.
 graders += results.all_graders(submission)
 @
 
+
+\subsection{Finding missing assignments}
+
+For conjunctive average with surveys, the definition of \enquote{passing} is
+broader than plain [[conjunctavg]]: numeric grades (points, percentages) also
+count as passing.
+This accommodates mandatory surveys that aren't graded A--F but still need to
+be completed.
+
+We define [[is_passing_grade]] to accept A--E, P, complete, and any numeric
+value.
+<<helper functions>>=
+def is_passing_grade(grade):
+  """
+  Returns True if grade is passing (includes numeric grades).
+  """
+  if grade is None:
+    return False
+  if grade in ["A", "B", "C", "D", "E", "P"]:
+    return True
+  if isinstance(grade, str):
+    if grade.casefold() == "complete":
+      return True
+    # Numeric grades (points, percentages) count as passing
+    if (grade.isdigit()
+        or grade.replace('.', '', 1).isdigit()
+        or grade.replace('%', '', 1).isdigit()):
+      return True
+  return False
+@
+
+We reuse the shared implementation with our broader [[is_passing_grade]].
+<<helper functions>>=
+def missing_assignments(assignments_list, users_list,
+                        passing_regex=None,
+                        optional_assignments=None):
+  """
+  Returns missing assignments for conjunctive average with surveys.
+
+  Any assignment without a passing grade (A-E, P, complete, or numeric) is
+  missing.
+  """
+  from canvaslms.cli import results
+  return results.missing_assignments(
+    assignments_list, users_list,
+    optional_assignments=optional_assignments,
+    is_passing=is_passing_grade
+  )
+@
+

{canvaslms-5.9 → canvaslms-5.10}/src/canvaslms/grades/disjunctmax.nw

@@ -132,4 +132,63 @@ def int_to_grade(int_grade):
                    0: "P",
                    1: "E", 2: "D", 3: "C", 4: "B", 5: "A"}
   return grade_map_inv[int_grade]
+@
+
+
+\subsection{Finding missing assignments}
+
+For disjunctive maximum grading, the semantics of \enquote{missing} are
+fundamentally different from conjunctive modules.
+Since a student only needs ONE passing grade to pass the group:
+\begin{itemize}
+\item If the student has at least one passing grade, \emph{nothing} is missing.
+\item If the student has no passing grades, we report \emph{all} assignments
+  as options they could complete to pass.
+\end{itemize}
+
+This is in contrast to conjunctive modules (like [[conjunctavg]]), where each
+non-passing assignment is independently \enquote{missing}.
+
+We cannot reuse the shared implementation from [[canvaslms.cli.results]] because
+that iterates assignment-by-assignment.
+Disjunctive logic requires evaluating ALL assignments first, then deciding what
+to report.
+<<helper functions>>=
+def missing_assignments(assignments_list, users_list,
+                        passing_regex=None,
+                        optional_assignments=None):
+  """
+  Returns missing assignments for disjunctive maximum grading.
+
+  Only reports assignments if the student has NO passing grades.
+  If they have at least one passing grade, nothing is missing.
+  """
+  import re
+
+  for user in users_list:
+    grades_with_assignments = []
+
+    # First pass: collect all grades
+    for assignment in assignments_list:
+      # Skip optional assignments
+      if optional_assignments:
+        if any(re.search(opt, assignment.name) for opt in optional_assignments):
+          continue
+
+      try:
+        submission = assignment.get_submission(user)
+        grade = submission.grade or "F"
+      except ResourceDoesNotExist:
+        grade = "F"
+
+      grades_with_assignments.append((assignment, grade))
+
+    # Check if student has at least one passing grade (P or better)
+    has_passing = any(grade_to_int(g) >= 0 for _, g in grades_with_assignments)
+
+    if not has_passing:
+      # Report all assignments as options to complete
+      for assignment, grade in grades_with_assignments:
+        yield user, assignment, \
+              f"not a passing grade ({grade}) - complete any one to pass"
 

{canvaslms-5.9 → canvaslms-5.10}/src/canvaslms/grades/grades.nw

@@ -3,10 +3,10 @@
 
 This is the documentation for the \texttt{canvaslms.grades} package.
 <<module doc>>=
-This package contains modules to summarize assignment groups in different ways. 
+This package contains modules to summarize assignment groups in different ways.
 These modules are used with the `-S` option of the `results` command.
 
-For a module to be used with the `canvaslms results -S module` option, the 
+For a module to be used with the `canvaslms results -S module` option, the
 module must fulfil the following:
 
   1) It must contain a function named `summarize_group`.
@@ -22,7 +22,21 @@ module must fulfil the following:
   3) The return value should be a list of lists. Each list should have the
      form `[user, grade, grade date, grader 1, ..., grader N]`.
 
-For more details, see Chapter 11 of the `canvaslms.pdf` file found among the 
+OPTIONAL: A module may also provide a `missing_assignments` function for use
+with the `--missing` flag. If provided, it will be used instead of the default.
+
+  - `missing_assignments(assignments_list, users_list, passing_regex=...,
+    optional_assignments=...)` should yield `(user, assignment, reason)` tuples.
+
+  - What "missing" means depends on the grading policy:
+    * Conjunctive modules (all must pass): Any non-passing assignment is missing
+    * Disjunctive modules (at least one must pass): Only report if NO passing
+
+  - Modules can define `is_passing_grade(grade)` and call the shared default
+    implementation from `canvaslms.cli.results.missing_assignments()` with the
+    `is_passing` callback parameter.
+
+For more details, see Chapter 11 of the `canvaslms.pdf` file found among the
 release files at:
 
   https://github.com/dbosk/canvaslms/releases

{canvaslms-5.9 → canvaslms-5.10}/src/canvaslms/grades/maxgradesurvey.nw

@@ -101,4 +101,62 @@ def summarize(user, assignments_list):
     final_grade = None
 
   return (final_grade, final_date, graders)
+@
+
+
+\subsection{Finding missing assignments}
+
+Like [[disjunctmax]], this module uses disjunctive grading: a student only needs
+ONE passing grade.
+The semantics of \enquote{missing} are the same:
+\begin{itemize}
+\item If the student has at least one passing grade, nothing is missing.
+\item If the student has no passing grades, all assignments are reported as
+  options.
+\end{itemize}
+
+The key difference from [[disjunctmax]] is that unknown grades (grades not in
+A--F or P) are treated as F.
+This accommodates surveys where numeric scores don't count as grades.
+<<helper functions>>=
+def missing_assignments(assignments_list, users_list,
+                        passing_regex=None,
+                        optional_assignments=None):
+  """
+  Returns missing assignments for disjunctive maximum grading with surveys.
+
+  Only reports assignments if the student has NO passing grades.
+  Unknown grades (not A-F or P) are treated as F.
+  """
+  import re
+
+  for user in users_list:
+    grades_with_assignments = []
+
+    # First pass: collect all grades
+    for assignment in assignments_list:
+      # Skip optional assignments
+      if optional_assignments:
+        if any(re.search(opt, assignment.name) for opt in optional_assignments):
+          continue
+
+      try:
+        submission = assignment.get_submission(user)
+        grade = submission.grade
+        # Unknown grades are treated as F
+        if grade is None or grade not in "ABCDEPF":
+          grade = "F"
+      except ResourceDoesNotExist:
+        grade = "F"
+
+      grades_with_assignments.append((assignment, grade))
+
+    # Check if student has at least one passing grade (P or better)
+    has_passing = any(grade_max([g]) != "F" for _, g in grades_with_assignments)
+
+    if not has_passing:
+      # Report all assignments as options to complete
+      for assignment, grade in grades_with_assignments:
+        yield user, assignment, \
+              f"not a passing grade ({grade}) - complete any one to pass"
 

{canvaslms-5.9 → canvaslms-5.10}/src/canvaslms/grades/participation.nw

@@ -216,3 +216,30 @@ else:
   final_date = None
   final_grade = None
 @
+
+
+\subsection{Finding missing assignments}
+
+For participation grading, a student is \enquote{missing} any assignment that
+doesn't have a passing grade ([[complete]] or [[100]]).
+Since this is conjunctive grading (all must pass), each incomplete assignment
+prevents the student from passing the group.
+
+We already have [[is_passing_grade]] defined above, so we simply reuse the
+shared implementation from [[canvaslms.cli.results]] with our callback.
+<<helper functions>>=
+def missing_assignments(assignments_list, users_list,
+                        passing_regex=None,
+                        optional_assignments=None):
+  """
+  Returns missing assignments for participation grading.
+
+  Any assignment without 'complete' or '100' is missing.
+  """
+  from canvaslms.cli import results
+  return results.missing_assignments(
+    assignments_list, users_list,
+    optional_assignments=optional_assignments,
+    is_passing=is_passing_grade
+  )
+@

{canvaslms-5.9 → canvaslms-5.10}/src/canvaslms/grades/tilkryLAB1.nw

@@ -304,6 +304,53 @@ else:
   final_grade = "E"
 @
 
+\subsection{Finding missing assignments}
+
+For the tilkry LAB1 grading system, \enquote{missing} has a specific meaning:
+only \emph{mandatory} assignments that aren't passed are reported.
+Optional assignments are never reported as missing since they're, well, optional.
+
+A mandatory assignment is missing if it doesn't have a P or P+ grade.
+We use the existing [[is_optional]] helper to distinguish mandatory from
+optional assignments.
+<<helper functions>>=
+def missing_assignments(assignments_list, users_list,
+                        passing_regex=None,
+                        optional_assignments=None):
+  """
+  Returns missing mandatory assignments for tilkry LAB1.
+
+  Only mandatory assignments (those not prefixed with "Optional:") are
+  reported. Optional assignments are never reported as missing.
+  """
+  for user in users_list:
+    for assignment in assignments_list:
+      # Skip optional assignments entirely - they're never "missing"
+      if is_optional(assignment):
+        continue
+
+      try:
+        submission = assignment.get_submission(user)
+      except ResourceDoesNotExist:
+        yield user, assignment, "no submission exists"
+        continue
+
+      grade = submission.grade
+
+      # Check if mandatory assignment is passed
+      if grade is None:
+        yield user, assignment, "not done"
+      elif grade == "P+" or grade == "P":
+        # Passed, not missing
+        pass
+      elif grade == "F":
+        yield user, assignment, "not passed (F)"
+      else:
+        # Unexpected grade for mandatory assignment
+        yield user, assignment, f"unexpected grade ({grade})"
+@
+
+
 \subsection{The complete module}
 
 All in all, the module looks like this.