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

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/cli/users.py

@@ -404,9 +404,12 @@ def add_user_option(parser, required=False):
 
 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
+            courses.process_course_option(canvas, args), args.user, roles=roles_list
         )
     )
     if not user_list:

canvaslms/grades/__init__.py

@@ -18,6 +18,20 @@ 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]`.
 
+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:
 

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/grades/conjunctavg.py

@@ -94,6 +94,37 @@ def int_to_grade(int_grade):
     return grade_map_inv[int_grade]
 
 
+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
+
+
+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,
+    )
+
+
 def summarize_group(assignments_list, users_list):
     """
     Summarizes a particular set of assignments (assignments_list) for all

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/grades/conjunctavgsurvey.py

@@ -77,6 +77,46 @@ def summarize(user, assignments_list):
     return (final_grade, final_date, graders)
 
 
+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
+
+
+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,
+    )
+
+
 def summarize_group(assignments_list, users_list):
     """
     Summarizes a particular set of assignments (assignments_list) for all

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/grades/disjunctmax.py

@@ -88,6 +88,44 @@ def int_to_grade(int_grade):
     return grade_map_inv[int_grade]
 
 
+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"
+
+
 def summarize_group(assignments_list, users_list):
     """Summarizes a particular set of assignments (assignments_list) for all
     users in users_list"""

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/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/grades/maxgradesurvey.py

@@ -60,6 +60,47 @@ def summarize(user, assignments_list):
     return (final_grade, final_date, graders)
 
 
+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"
+
+
 def summarize_group(assignments_list, users_list):
     """Summarizes a particular set of assignments (assignments_list) for all
     users in users_list"""

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/grades/participation.py

@@ -60,6 +60,24 @@ def summarize(user, assignments_list):
     return (final_grade, final_date, graders)
 
 
+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,
+    )
+
+
 def summarize_group(assignments_list, users_list):
     """
     Summarizes participation assignments using conjunctive P/F grading.