ladok3 4.13__py3-none-any.whl → 5.4__py3-none-any.whl

ladok3/scripts.nw

@@ -0,0 +1,244 @@
+In this chapter we'll see some scripts for reporting results from Canvas to 
+LADOK.
+These scripts are run as cronjobs.
+This means that they run unattended and only produce output when they need 
+attention.
+
+We want to report results for courses that are titled \enquote{DD2520 VT25}, 
+\enquote{DD1310 HT24}, \enquote{DD1317 HT24}, and similar in Canvas.
+The advantage to using this command is that it will automatically report the 
+correct dates and everyone who has participated in the grading of each 
+student---as required by regulation.
+The official tools, like KTH Transfer to Ladok or SUNET's version of the same, 
+don't do this.
+They don't set the dates correctly, meaning that each individual should have a 
+separate date (date of submission).
+They also don't register the graders in LADOK.
+For each results, everyone who participated in the grading process should be 
+registered in LADOK.
+
+We'll have a script [[<<ladok.sh>>]] that is run by [[cron]].
+It's useful to load our profile, so that we have our normal environment.
+<<ladok.sh>>=
+#!/bin/bash
+. ${HOME}/.profile
+@
+
+We also want some helper functions and a main function that is only run when 
+the script is run.
+If the script is sourced, the main function is not run.
+This way we can use the helper functions in our terminal.
+<<ladok.sh>>=
+<<constants>>
+<<helper functions>>
+
+main() {
+  <<main script>>
+}
+
+# Only run if this is the main script
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+  main "$@"
+fi
+@
+
+We need to report more than once for a course.
+All students might not be done by the time of reporting.
+When they're done, we must report the results again\footnote{%
+  And students have a right to do this without having to reregister on a later 
+  course round.
+}.
+Sometimes a student finishes a course years after it ended.
+To speed up execution it's better to report results for a sliding window of 
+courses, instead of all courses.
+For those rare cases when a student finishes a course years after it ended, we 
+can report the results manually for that course again---by importing and 
+invoking the functions below in the terminal.
+
+We'll let [[YEARS]] be a regex for the years that we're interested in reporting 
+for.
+We'll use the current year and the previous year.
+The advantage of this window is that when we pass new year's eve, the autumn 
+courses are still current for a few weeks---but the year is the wrong one.
+As a side effect, during autumn we report results for any late results for the 
+previous year too.
+
+To construct the regex for years, we simply take a sequence of years
+([[24 25]]) and make a regex ([[(24|25)]]) out of it.
+<<constants>>=
+YEAR=$(date +%y)
+YEARS=$(echo -n "("; \
+        seq $((YEAR - 1)) $YEAR \
+        | sed -zE "s/\s/|/g" \
+        | sed "s/|$/)/")
+@
+
+\section{Reporting results on course components}
+
+We want a script that reports the results for all courses, including all 
+previous years, to LADOK.
+We want to do this for previous years as sometimes they finish assignments 
+years after the course ended.
+
+We'll add a function that takes a course regex and a component regex and 
+reports the results to LADOK.
+To report the modules, we sometimes need to override the default summary 
+function of [[canvaslms]]\footnote{\label{canvaslms-doc}%
+  For details on [[canvaslms results]], see Chapters 10 and 11 in its 
+  documentation, found on
+  \url{https://github.com/dbosk/canvaslms/releases/tag/v4.7}.
+  Particularly Chapter 11 discusses the summary modules.
+  You can also read [[pydoc canvaslms.grades]] for a more brief summary.
+}.
+We want something like this:
+<<main script>>=
+report_components "DD1301 HT${YEARS}" \
+                  LAB1
+report_components "DD131[057] HT${YEARS}" \
+                  "(LAB|MAT|KAL)[1-3]"
+report_components "DA2215 [HV]T${YEARS}" \
+                  INL1
+
+report_components "DD2520 VT${YEARS}" \
+                  INL1
+report_components "DD2520 VT${YEARS}" \
+                  LAB1 \
+                  canvaslms.grades.tilkryLAB1
+@ Note that the line reporting for DD1310 reports for \emph{all} instances as 
+well---that course is given five times in parallel.
+But the assessment should be the same so it is sufficient that one of the 
+examiners run this script to report all the results.
+
+To get the results out of Canvas we'll use the [[canvaslms results]] command.
+We must install the [[canvaslms]] tool.
+We can do this by running:
+\begin{minted}{bash}
+python3 -m pip install canvaslms # to use it with Python, or
+pipx install canvaslms           # to only use the CLI
+canvaslms login                  # or read `canvaslms login --help`
+\end{minted}
+For details on how to extract the results, read
+\mintinline{bash}{canvaslms results --help}
+(also read \cref{canvaslms-doc} on page~\pageref{canvaslms-doc}).
+<<helper functions>>=
+report_components() {
+  local course="$1"
+  local component="$2"
+  local summary_module="$3"
+
+  local summary_opt=""
+  if [[ -n "$summary_module" ]]; then
+    summary_opt="-S $summary_module"
+  fi
+
+  # Get the course results from Canvas.
+  canvaslms results -c "$course" -A "$component" $summary_opt \
+  | sed -E "s/ ?[HV]T[0-9]{2}( \(.*\))?//" \
+  | <<[[tee]] the component results to use for course grades>> \
+  | ladok report -fv # Report them to LADOK.
+}
+@
+
+
+\section{Reporting course grade}
+
+Now we can set the course grades based on the reported components.
+We'll have to report one course at a time since the course grade is based on 
+different components in different courses.
+<<main script>>=
+report_course "DD131[057] HT${YEARS}" \
+              LAB3
+report_course "DD2520 VT${YEARS}" \
+              LAB1
+@ We don't need to report the course grade for the other courses since they 
+have only one component.
+For courses with only one component, LADOK will automatically set the course 
+grade based on the grade of the single component.
+
+Setting the course grade can be done in several ways.
+The first option is to look at what results are already attested in LADOK.
+Unfortunately, this requires the round code---which we don't have access 
+to\footnote{%
+  For a brief period, IT included the round code in the course title in Canvas 
+  at KTH.
+  That was beneficial in many ways, but unfortunately it faced a backlash from 
+  teachers and it was undone.
+}.
+However, we can get this data from the [[canvaslms results]] line in 
+[[report_components]].
+That's why we want to [[tee]] that data out of that pipeline.
+
+When we [[tee]] the data out, we want to use the [[-a]] option to append if the 
+file already exists.
+The reason for this is that we want all results for the course in one file.
+But sometimes we might have to run the script several times---once for each 
+component.
+<<[[tee]] the component results to use for course grades>>=
+tee -a "${DATA_DIR}/${course}-results.csv"
+<<constants>>=
+DATA_DIR=`mktemp -d`
+@
+
+We'll provide a function that takes a course and a component and returns the 
+results for that course and component.
+If no component is given, we use all components.
+If we don't have results from before, we report those components to get the 
+data.
+<<helper functions>>=
+component_grades() {
+  local course="$1"
+  local component="${2:-[A-Z]{3}[0-9]+}"
+  local grades="${DATA_DIR}/${course}-results.csv"
+
+  if [[ ! -f "$grades" ]]; then
+    report_components "$course" "$component"
+  fi
+  cat "$grades" \
+  | grep -E "\s${component}\s" \
+  | sort -u
+}
+@ The data we get here has the following columns (tab separated):
+\begin{minted}{text}
+course    component   student   grade   date   graders
+\end{minted}
+
+Now we can use this file when reporting the course grades.
+If the file doesn't exist, we simply run [[report_components]].
+If the results are not yet attested (certified), the [[ladok report]] command 
+will simply give an error that all components of the course are not yet 
+attested.
+
+Now it's just to sort out the students and then for each student get the grade 
+of the component, get the latest grade date of all components and finally 
+report to LADOK.
+<<helper functions>>=
+report_course() {
+  local course="$1"
+  local component="$2"
+
+  for student in $(component_grades "$course" \
+                   | cut -f 3)
+  do
+    local grade=$(component_grades "$course" "$component" \
+                  | grep "$student" \
+                  | cut -f 4)
+    local grade_date=$(component_grades "$course" \
+                       | grep "$student" \
+                       | cut -f 5 \
+                       | sort \
+                       | tail -n 1)
+
+    if [ "$grade" = "" ]; then
+      continue
+    fi
+
+    local course_code=$(component_grades "$course" "$component" \
+                        | grep "$student" \
+                        | cut -f 1 \
+                        | sort -u)
+
+    # `component code = course code` yields final grade on course.
+    ladok report -fv "$course_code" "$course_code" \
+                     "$student" "$grade" "$grade_date"
+  done
+}

ladok3/student.nw

@@ -23,6 +23,14 @@ import ladok3.cli
 <<functions>>
 
 def add_command_options(parser):
+  """Add the 'student' subcommand options to the argument parser.
+  
+  Creates a subparser for displaying student information with options
+  for course filtering and result display.
+  
+  Args:
+      parser (ArgumentParser): The parent parser to add the subcommand to.
+  """
   student_parser = parser.add_parser("student",
     help="Shows a student's information in LADOK",
     description="""
@@ -34,6 +42,12 @@ def add_command_options(parser):
   <<add student command arguments to student parser>>
 
 def command(ladok, args):
+  """Execute the student information display command.
+  
+  Args:
+      ladok (LadokSession): The LADOK session for data access.
+      args: Parsed command line arguments containing student ID and display options.
+  """
   <<print info depending on args>>
 @
 
@@ -74,6 +88,17 @@ student_parser.add_argument("-r", "--results",
 )
 @
 
+\subsection{A contact information flag}
+
+We also want a flag for specifying whether or not to include the student's 
+contact information (email, phone, address).
+<<add student command arguments to student parser>>=
+student_parser.add_argument("--contact",
+  action="store_true", default=False,
+  help="Include contact information (email, phone, address)."
+)
+@
+
 \section{Print the student data}
 
 Now that we have the student identifier, we can simply use that to fetch the 
@@ -87,7 +112,7 @@ try:
 except Exception as err:
   ladok3.cli.err(-1, f"can't fetch student data for {args.id}: {err}")
 
-print_student_data(student)
+print_student_data(student, args)
 
 if args.course:
   print()
@@ -99,16 +124,56 @@ if args.course:
 To print the student's personal data, we simply print the most interesting 
 attributes.
 <<functions>>=
-def print_student_data(student):
-  """Prints the student data, all attributes, to stdout."""
+def print_student_data(student, args):
+  """Prints the student data, all attributes, to stdout.
+  
+  Args:
+    student: A Student object with the student's data
+    args: Command line arguments, including flags like --contact
+  """
   print(f"First name:   {student.first_name}")
   print(f"Last name:    {student.last_name}")
   print(f"Personnummer: {student.personnummer}")
   print(f"LADOK ID:     {student.ladok_id}")
   print(f"Alive:        {student.alive}")
-  print(f"Suspended:    {student.suspensions}")
+  <<print info about suspensions for [[student]]>>
+  <<print contact info if requested>>
 @
 
+We want to print whether the student is currently suspended or not.
+We want to make this really clear.
+<<print info about suspensions for [[student]]>>=
+print(f"Suspended:    ", end="")
+if any(map(lambda x: x.is_current, student.suspensions)):
+  print("YES")
+else:
+  print("no")
+@ Then we also want to print all the times the student has been suspended.
+We only want to print this if the student has been suspended at least once.
+<<print info about suspensions for [[student]]>>=
+if student.suspensions:
+  print(f"Suspenions:   ", end="")
+  for suspension in student.suspensions:
+    print(f"{suspension}", end="\n              ")
+  print()
+@
+
+Now we add the contact information display. 
+We only want to print this if the user has requested it using the [[--contact]] flag.
+<<print contact info if requested>>=
+if args.contact:
+  print("Contact information:")
+  if student.email:
+    print(f"Email:        {student.email}")
+  if student.phone:
+    print(f"Phone:        {student.phone}")
+  if student.address:
+    print(f"Address:      {student.address[0]}")
+    for line in student.address[1:]:
+      print(f"              {line}")
+@
+
+
 \subsection{Printing student's course data}
 
 To print the student's course data, we simply filter the courses on the option 

ladok3/student.py

@@ -1,54 +1,110 @@
 import csv
 import ladok3.cli
 
-def print_student_data(student):
-  """Prints the student data, all attributes, to stdout."""
-  print(f"First name:   {student.first_name}")
-  print(f"Last name:    {student.last_name}")
-  print(f"Personnummer: {student.personnummer}")
-  print(f"LADOK ID:     {student.ladok_id}")
-  print(f"Alive:        {student.alive}")
-  print(f"Suspended:    {student.suspensions}")
+
+def print_student_data(student, args):
+    """Prints the student data, all attributes, to stdout.
+
+    Args:
+      student: A Student object with the student's data
+      args: Command line arguments, including flags like --contact
+    """
+    print(f"First name:   {student.first_name}")
+    print(f"Last name:    {student.last_name}")
+    print(f"Personnummer: {student.personnummer}")
+    print(f"LADOK ID:     {student.ladok_id}")
+    print(f"Alive:        {student.alive}")
+    print(f"Suspended:    ", end="")
+    if any(map(lambda x: x.is_current, student.suspensions)):
+        print("YES")
+    else:
+        print("no")
+    if student.suspensions:
+        print(f"Suspenions:   ", end="")
+        for suspension in student.suspensions:
+            print(f"{suspension}", end="\n              ")
+        print()
+    if args.contact:
+        print("Contact information:")
+        if student.email:
+            print(f"Email:        {student.email}")
+        if student.phone:
+            print(f"Phone:        {student.phone}")
+        if student.address:
+            print(f"Address:      {student.address[0]}")
+            for line in student.address[1:]:
+                print(f"              {line}")
+
+
 def print_course_data(student, args):
-  """Prints the courses"""
-  print("Courses:")
-  for course in student.courses(code=args.course):
-    print(f"{course}")
-    if args.results:
-      for result in course.results():
-        print(f"  {result}")
+    """Prints the courses"""
+    print("Courses:")
+    for course in student.courses(code=args.course):
+        print(f"{course}")
+        if args.results:
+            for result in course.results():
+                print(f"  {result}")
+
 
 def add_command_options(parser):
-  student_parser = parser.add_parser("student",
-    help="Shows a student's information in LADOK",
-    description="""
+    """Add the 'student' subcommand options to the argument parser.
+
+    Creates a subparser for displaying student information with options
+    for course filtering and result display.
+
+    Args:
+        parser (ArgumentParser): The parent parser to add the subcommand to.
+    """
+    student_parser = parser.add_parser(
+        "student",
+        help="Shows a student's information in LADOK",
+        description="""
     Show a student's information in LADOK.
     Shows information like name, personnummer, contact information.
-    """
-  )
-  student_parser.set_defaults(func=command)
-  student_parser.add_argument("id",
-    help="The student's ID, either personnummer or LADOK ID"
-  )
-  student_parser.add_argument("-c", "--course",
-    nargs="?", const=".*",
-    help="A regular expression for which course codes to list, " \
-      "use no value for listing all courses."
-  )
-  student_parser.add_argument("-r", "--results",
-    action="store_true", default=False,
-    help="Set to include results for each course listed."
-  )
+    """,
+    )
+    student_parser.set_defaults(func=command)
+    student_parser.add_argument(
+        "id", help="The student's ID, either personnummer or LADOK ID"
+    )
+    student_parser.add_argument(
+        "-c",
+        "--course",
+        nargs="?",
+        const=".*",
+        help="A regular expression for which course codes to list, "
+        "use no value for listing all courses.",
+    )
+    student_parser.add_argument(
+        "-r",
+        "--results",
+        action="store_true",
+        default=False,
+        help="Set to include results for each course listed.",
+    )
+    student_parser.add_argument(
+        "--contact",
+        action="store_true",
+        default=False,
+        help="Include contact information (email, phone, address).",
+    )
+
 
 def command(ladok, args):
-  try:
-    student = ladok.get_student(args.id)
-    student.alive
-  except Exception as err:
-    ladok3.cli.err(-1, f"can't fetch student data for {args.id}: {err}")
+    """Execute the student information display command.
+
+    Args:
+        ladok (LadokSession): The LADOK session for data access.
+        args: Parsed command line arguments containing student ID and display options.
+    """
+    try:
+        student = ladok.get_student(args.id)
+        student.alive
+    except Exception as err:
+        ladok3.cli.err(-1, f"can't fetch student data for {args.id}: {err}")
 
-  print_student_data(student)
+    print_student_data(student, args)
 
-  if args.course:
-    print()
-    print_course_data(student, args)
+    if args.course:
+        print()
+        print_course_data(student, args)