canvaslms 5.7__tar.gz → 5.8__tar.gz

{canvaslms-5.7 → canvaslms-5.8}/PKG-INFO

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

{canvaslms-5.7 → canvaslms-5.8}/pyproject.toml

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

{canvaslms-5.7 → canvaslms-5.8}/src/canvaslms/cli/results.nw

@@ -39,6 +39,7 @@ import importlib.machinery
 import importlib.util
 import os
 import pathlib
+import pkgutil
 import re
 import sys
 
@@ -55,13 +56,27 @@ The command requires two arguments: course and assignment.
 We also want the option to filter on users.
 We can add these by using [[add_assignment_option]], however, we don't need the 
 ungraded flag as we want to export results (\ie graded material).
-Also, we can just add the [[add_user_or_group_option]] to be able to filter on 
+Also, we can just add the [[add_user_or_group_option]] to be able to filter on
 users or groups.
+
+The epilog contains a formatted list of available grading modules.
+We use [[RawDescriptionHelpFormatter]] to preserve the whitespace formatting in
+the epilog while still allowing argument help text to wrap normally.
+
+However, we must be careful about how we construct the epilog string.
+When [[black]] formats the generated Python, triple-quoted strings passed as
+arguments get indented on continuation lines.
+Since [[RawDescriptionHelpFormatter]] preserves this whitespace literally, we'd
+end up with oddly indented prose text in the help output.
+
+To avoid this, we build the epilog via the [[format_results_epilog]] function,
+which joins individual lines without introducing unwanted indentation.
 <<add results command to subp>>=
 results_parser = subp.add_parser("results",
     help="Lists results of a course",
     description="""<<results command description>>""",
-    epilog="""<<results command epilog>>""")
+    epilog=format_results_epilog(),
+    formatter_class=argparse.RawDescriptionHelpFormatter)
 results_parser.set_defaults(func=results_command)
 assignments.add_assignment_option(results_parser, ungraded=False)
 users.add_user_or_group_option(results_parser)
@@ -83,13 +98,10 @@ prevent the student from getting a grade. Output format, CSV:
   <course code> <component code> <student ID> <missing assignment> <reason>
 
 The reason can be "not submitted" or "not graded".
-<<results command epilog>>=
-If you specify an assignment group, the results of the assignments in that 
-group will be summarized. You can supply your own function for summarizing 
-grades through the -S option. See `pydoc3 canvaslms.grades` for different 
-options.
-@ We will cover the option for and loading of the custom summary module later, 
+@ We will cover the option for and loading of the custom summary module later,
 in \cref{custom-summary-modules}.
+We will also cover the [[format_grading_modules_help]] function, which
+dynamically discovers available modules in the [[canvaslms.grades]] package.
 
 Now, that [[results_command]] function must take three arguments: [[config]], 
 [[canvas]] and [[args]].
@@ -395,18 +407,120 @@ if grade is None or grade_date is None \
   continue
 @
 
+\subsection{Discovering available grading modules}
+\label{grading-module-discovery}
+
+When users install [[canvaslms]] via pipx, the package resides in an isolated
+virtual environment.
+This means the traditional approach of using [[pydoc3 canvaslms.grades]] to
+discover available modules no longer works---pydoc searches the system Python
+path, not pipx's isolated environment.
+
+To solve this, we dynamically discover available modules at runtime using
+[[pkgutil.iter_modules]].
+This works regardless of installation method because we introspect from within
+the package itself.
+If a module fails to import (for example, due to missing dependencies), we
+simply skip it rather than failing the entire discovery process.
+
+We provide two helper functions: one to list the modules with their
+descriptions, and one to format them for display in help text.
+<<functions>>=
+def list_grading_modules():
+  """
+  Discover available grading modules in canvaslms.grades package.
+  Returns a list of (module_name, description) tuples.
+  """
+  import canvaslms.grades
+
+  modules = []
+  # These are internal modules, not user-facing grading strategies
+  excluded = {"__init__", "grades"}
+
+  for importer, modname, ispkg in pkgutil.iter_modules(canvaslms.grades.__path__):
+    if modname in excluded:
+      continue
+    try:
+      module = importlib.import_module(f"canvaslms.grades.{modname}")
+      doc = module.__doc__
+      if doc:
+        # Take only the first line of the docstring
+        first_line = doc.strip().split('\n')[0]
+      else:
+        first_line = "(no description)"
+      modules.append((modname, first_line))
+    except ImportError:
+      continue
+
+  return sorted(modules)
+
+def format_grading_modules_help():
+  """Format the list of grading modules for help text display."""
+  modules = list_grading_modules()
+  if not modules:
+    return "  (no modules found)"
+
+  lines = []
+  for name, desc in modules:
+    lines.append(f"  canvaslms.grades.{name}: {desc}")
+  return "\n\n".join(lines)
+
+def format_results_epilog():
+  """
+  Build the epilog for results command help.
+
+  We construct the epilog by joining lines explicitly rather than using a
+  triple-quoted string. This avoids indentation issues when black formats
+  the generated Python code---triple-quoted strings in function arguments
+  get continuation-line indentation that RawDescriptionHelpFormatter
+  would preserve literally.
+  """
+  parts = [
+    "If you specify an assignment group, the results of the assignments in that",
+    "group will be summarized. You can supply your own function for summarizing",
+    "grades through the -S option.",
+    "",
+    "Available grading modules:",
+    format_grading_modules_help(),
+    "",
+    "You can also provide a path to your own Python file with a summarize_group",
+    "function."
+  ]
+  return "\n".join(parts)
+@
+
+The [[list_grading_modules]] function uses [[pkgutil.iter_modules]] to iterate
+over all submodules in the [[canvaslms.grades]] package.
+We exclude [[__init__]] (the package initializer) and [[grades]] (an internal
+module) since these are not user-facing grading strategies.
+
+For each module, we import it and extract the first line of its docstring as a
+brief description.
+This gives users immediate visibility into what each module does, right in the
+help output.
+
+The [[format_grading_modules_help]] function joins module entries with blank
+lines between them (double newline) for visual separation in the help output.
+This makes the list easier to scan when module descriptions vary in length.
+
+The [[format_results_epilog]] function builds the complete epilog by joining
+individual lines.
+This approach avoids the pitfall where [[black]] indents continuation lines in
+triple-quoted strings, which [[RawDescriptionHelpFormatter]] would preserve
+literally, resulting in oddly indented prose in the help output.
+
+
 \subsection{Loading a custom summary module}
 \label{custom-summary-modules}
 
-Different teachers have different policies for merging several assignments into 
+Different teachers have different policies for merging several assignments into
 one grade.
 We now want to provide a way to override the default function.
 <<summary module option doc>>=
-Name of Python module or file containing module to load with a custom 
-summarization function to summarize assignment groups. The default module is 
-part of the `canvaslms` package: `{default_summary_module}`. But it could be 
-any Python file in the file system or other built-in modules. See `pydoc3 
-canvaslms.grades` for alternative modules or how to build your own.
+Name of Python module or file to load with a custom summarization function.
+Default: `{default_summary_module}`. Available modules: """ + \
+", ".join(m[0] for m in list_grading_modules()) + """. \
+Or provide a path to your own Python file.
 <<add option for custom summary module>>=
 default_summary_module = "canvaslms.grades.conjunctavg"
 results_parser.add_argument("-S", "--summary-module",

{canvaslms-5.7 → canvaslms-5.8}/src/canvaslms/grades/Makefile

@@ -6,6 +6,7 @@ MODULES+=			disjunctmax.py
 MODULES+=			maxgradesurvey.py
 MODULES+=			conjunctavgsurvey.py
 MODULES+=			tilkryLAB1.py
+MODULES+=			participation.py
 
 .PHONY: all
 all: grades.tex
@@ -14,6 +15,7 @@ all: disjunctmax.tex
 all: maxgradesurvey.tex
 all: conjunctavgsurvey.tex
 all: tilkryLAB1.tex
+all: participation.tex
 all: ${MODULES}
 
 grades.tex: conjunctavg.tex
@@ -21,6 +23,7 @@ grades.tex: disjunctmax.tex
 grades.tex: maxgradesurvey.tex
 grades.tex: conjunctavgsurvey.tex
 grades.tex: tilkryLAB1.tex
+grades.tex: participation.tex
 
 __init__.py: init.py
 	${MV} $^ $@

{canvaslms-5.7 → canvaslms-5.8}/src/canvaslms/grades/grades.nw

@@ -135,3 +135,4 @@ We can also give the relative or absolute path to \texttt{mysum.py} instead.
 \input{../src/canvaslms/grades/disjunctmax.tex}
 \input{../src/canvaslms/grades/maxgradesurvey.tex}
 \input{../src/canvaslms/grades/tilkryLAB1.tex}
+\input{../src/canvaslms/grades/participation.tex}

canvaslms-5.8/src/canvaslms/grades/participation.nw

@@ -0,0 +1,218 @@
+\section{Conjunctive P/F grading, the \texttt{participation} module}
+
+This module implements conjunctive P/F grading for participation-based
+assignments.
+It's useful when students must complete \emph{all} assignments in a group to
+pass, where each assignment is graded as complete/incomplete or 100/0.
+
+As an example, consider a course where students pass by participating in
+seminars and completing reflections:
+\begin{minted}{text}
+$ canvaslms assignments list -c vetcyb25h -A "^Participation INL1" \
+  | cut -f 1-3
+DA2215 HT25 (vetcyb25h)	Participation INL1	Reflection on literature reviews
+DA2215 HT25 (vetcyb25h)	Participation INL1	Overview of Science in Security
+DA2215 HT25 (vetcyb25h)	Participation INL1	How to Design Computer Security Experiments
+DA2215 HT25 (vetcyb25h)	Participation INL1	How do you know it's secure? Passwords
+DA2215 HT25 (vetcyb25h)	Participation INL1	Comprehension, literature review: Of passwords and people
+DA2215 HT25 (vetcyb25h)	Participation INL1	Comprehension: Graphical Passwords: Learning from the First Twelve Years
+DA2215 HT25 (vetcyb25h)	Participation INL1	Achieving Rigor in Literature Reviews  Insights from Qualitative Data Analysis and Tool-Support
+DA2215 HT25 (vetcyb25h)	Participation INL1	Live seminar 13/11 at 13:15
+DA2215 HT25 (vetcyb25h)	Participation INL1	Comprehension: Of Passwords and People, Measuring the Effect of Password-Composition Policies
+DA2215 HT25 (vetcyb25h)	Participation INL1	Comprehension: Can long passwords be secure and usable?
+DA2215 HT25 (vetcyb25h)	Participation INL1	Comprehension: Why phishing works
+DA2215 HT25 (vetcyb25h)	Participation INL1	Live seminar 6/11 at 15:15
+DA2215 HT25 (vetcyb25h)	Participation INL1	The RSA and ElGamal cryptosystems
+DA2215 HT25 (vetcyb25h)	Participation INL1	On the Security of EIGamal Based Encryption
+DA2215 HT25 (vetcyb25h)	Participation INL1	Stealing Keys from PCs using a Radio: Cheap Electromagnetic Attacks on Windowed Exponentiation
+DA2215 HT25 (vetcyb25h)	Participation INL1	Timing Analysis of Keystrokes and Timing Attacks on SSH
+DA2215 HT25 (vetcyb25h)	Participation INL1	Reflection on the use of models, part I
+DA2215 HT25 (vetcyb25h)	Participation INL1	Theorem proving: 1. Introduction
+DA2215 HT25 (vetcyb25h)	Participation INL1	Theorem proving: 2. Formal methods and Interactive Theorem Proving
+DA2215 HT25 (vetcyb25h)	Participation INL1	Theorem proving: 4. Examples for what can be verified with Interactive Theorem Provers
+DA2215 HT25 (vetcyb25h)	Participation INL1	Theorem proving: 5. Limitations of Interactive Theorem Proving and Conclusion
+DA2215 HT25 (vetcyb25h)	Participation INL1	Model checking: algorithmic verification and debugging
+DA2215 HT25 (vetcyb25h)	Participation INL1	Reflection on the use of models, part II
+DA2215 HT25 (vetcyb25h)	Participation INL1	Live seminar 28/11  at 10:15
+DA2215 HT25 (vetcyb25h)	Participation INL1	Dos and Don'ts of Machine Learning in Computer Security
+DA2215 HT25 (vetcyb25h)	Participation INL1	Reflection on the use of statistics
+DA2215 HT25 (vetcyb25h)	Participation INL1	Comprehension: Why Johnny can't encrypt
+DA2215 HT25 (vetcyb25h)	Participation INL1	Comprehension: Comparing the Usability of Cryptographic APIs
+DA2215 HT25 (vetcyb25h)	Participation INL1	Reflection on qualitative methods
+DA2215 HT25 (vetcyb25h)	Participation INL1	SoK: Science, Security and the Elusive Goal of Security as a Scientific Pursuit
+DA2215 HT25 (vetcyb25h)	Participation INL1	Reflection on Science in Security
+DA2215 HT25 (vetcyb25h)	Participation INL1	Live seminar 12/12 at 12:15
+DA2215 HT25 (vetcyb25h)	Participation INL1	Tor: The Second-Generation Onion Router
+DA2215 HT25 (vetcyb25h)	Participation INL1	Comprehension: Users get routed: traffic correlation on tor by realistic adversaries
+DA2215 HT25 (vetcyb25h)	Participation INL1	Comprehension:  Shadow: Running Tor in a Box for Accurate and Efficient Experimentation
+DA2215 HT25 (vetcyb25h)	Participation INL1	Comprehension: Website Fingerprinting with Website Oracles
+DA2215 HT25 (vetcyb25h)	Participation INL1	Comprehension: Online Website Fingerprinting: Evaluating Website Fingerprinting Attacks on Tor in the Real World
+DA2215 HT25 (vetcyb25h)	Participation INL1	Reflection on the use of models, part III
+DA2215 HT25 (vetcyb25h)	Participation INL1	Live seminar 3/12 at 12:15
+DA2215 HT25 (vetcyb25h)	Participation INL1	Reflection on inferences, experiments and measurements
+\end{minted}
+The exact assignments and names might change though.
+But that's fine.
+The grading system remains the same, we have the following grades:
+\begin{minted}{text}
+$ canvaslms submissions list -c vetcyb25h -A "^Participation INL1" \
+  | cut -f 4 | sort -u
+
+100
+complete
+incomplete
+\end{minted}
+We want all assignments to have either complete or 100 to get a passing grade.
+Otherwise the student gets an F.
+
+\subsection{Grading logic: conjunctive P/F}
+
+This module implements what we call \emph{conjunctive P/F grading}.
+Let's contrast this with other approaches to understand what makes it unique:
+\begin{description}
+\item[conjunctavg] All assignments must pass, and A--E grades are averaged.
+  Here we have no A--E grades, only complete/incomplete or 100/empty.
+\item[disjunctmax] At least one assignment must pass (disjunctive), and we take
+  the best grade.
+  Here \emph{all} assignments must pass (conjunctive), and the only possible
+  grades are P or F.
+\end{description}
+
+The grading rule is simple: if \emph{all} participation assignments have a
+passing grade, the student passes.
+If \emph{any} assignment is missing or has an incomplete grade, the student
+fails.
+
+\subsection{Module structure}
+
+We follow the standard module structure: a [[summarize_group]] function that
+iterates over users and delegates to a [[summarize]] helper function.
+<<[[participation.py]]>>=
+"""
+<<module doc>>
+"""
+import datetime as dt
+from canvaslms.cli import results
+from canvasapi.exceptions import ResourceDoesNotExist
+
+<<helper functions>>
+
+def summarize_group(assignments_list, users_list):
+  """
+  Summarizes participation assignments using conjunctive P/F grading.
+  All assignments must have 'complete' or '100' for P, otherwise F.
+  """
+  for user in users_list:
+    grade, grade_date, graders = summarize(user, assignments_list)
+    yield [user, grade, grade_date, *graders]
+@
+
+<<module doc>>=
+Summarizes participation assignments using conjunctive P/F grading.
+All assignments must have 'complete' or '100' for P, otherwise F.
+@
+
+\subsection{What counts as passing?}
+
+A grade is considered passing if it is either:
+\begin{itemize}
+\item [[complete]] (case-insensitive, so [[Complete]] or [[COMPLETE]] also work)
+\item [[100]] (a numeric grade indicating full completion)
+\end{itemize}
+
+Anything else---including [[incomplete]], [[None]], or a missing
+submission---counts as not passing.
+<<helper functions>>=
+def is_passing_grade(grade):
+  """
+  Returns True if the grade indicates passing (complete or 100).
+  """
+  if grade is None:
+    return False
+  if isinstance(grade, str):
+    if grade.casefold() == "complete":
+      return True
+    if grade == "100":
+      return True
+  return False
+@
+
+\subsection{Summarizing a student's participation}
+
+The [[summarize]] function iterates through all assignments and checks whether
+each one has a passing grade.
+We collect dates and graders along the way.
+<<helper functions>>=
+def summarize(user, assignments_list):
+  """
+  Extracts user's submissions for all participation assignments.
+  Returns (grade, date, graders) where grade is P if all passed, F otherwise.
+  """
+  passed = []
+  dates = []
+  graders = []
+
+  for assignment in assignments_list:
+    <<get submission for assignment>>
+    <<check if grade is passing>>
+    <<add graders to [[graders]] list>>
+    <<add date to [[dates]] list>>
+
+  <<determine final grade>>
+
+  return (final_grade, final_date, graders)
+@
+
+For each assignment, we attempt to fetch the student's submission.
+If the submission doesn't exist (which can happen in rare cases), we treat it
+as not passing.
+<<get submission for assignment>>=
+try:
+  submission = assignment.get_submission(user,
+                                        include=["submission_history"])
+except ResourceDoesNotExist:
+  passed.append(False)
+  continue
+
+submission.assignment = assignment
+@
+
+We extract the grade from the submission and check whether it's passing.
+<<check if grade is passing>>=
+grade = submission.grade
+passed.append(is_passing_grade(grade))
+@
+
+We collect all graders from the submission history.
+This ensures we credit everyone who participated in the grading process, not
+just the last person to grade.
+<<add graders to [[graders]] list>>=
+graders += results.all_graders(submission)
+@
+
+For the date, we prefer the submission date but fall back to the grading date
+if no submission was made (for example, oral presentations where the student
+didn't submit anything).
+<<add date to [[dates]] list>>=
+grade_date = submission.submitted_at or submission.graded_at
+if grade_date:
+  grade_date = dt.date.fromisoformat(grade_date.split("T")[0])
+  dates.append(grade_date)
+@
+
+\subsection{Determining the final grade}
+
+The final grade is P if \emph{all} assignments passed, F otherwise.
+If there are no dates (meaning the student has no activity at all), we return
+[[None]] for both grade and date.
+<<determine final grade>>=
+if dates:
+  final_date = max(dates)
+  if all(passed):
+    final_grade = "P"
+  else:
+    final_grade = "F"
+else:
+  final_date = None
+  final_grade = None
+@