ladok3 4.19__tar.gz → 5.1__tar.gz

{ladok3-4.19 → ladok3-5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ladok3
-Version: 4.19
+Version: 5.1
 Summary: Python wrapper and CLI for the LADOK3 REST API.
 Home-page: https://github.com/dbosk/ladok3
 License: MIT

{ladok3-4.19 → ladok3-5.1}/doc/Makefile

@@ -24,6 +24,7 @@ ladok3.pdf: ../examples/example_LadokSession.py
 ladok3.pdf: ../examples/example_Student.py
 ladok3.pdf: ../examples/example_Course.py
 ladok3.pdf: ../examples/canvas2ladok.tex
+ladok3.pdf: ../src/ladok3/scripts.tex
 
 ladok3.pdf: didactic.sty
 

ladok3-5.1/doc/abstract.tex

@@ -0,0 +1,8 @@
+We provide a Python wrapper for the LADOK3 REST API\@.
+This wrapper provide a useful object-oriented framework for working with LADOK 
+and direct API calls that return the unprocessed JSON data directly from 
+LADOK\@.
+
+We also provide a command-line interface (CLI) for the library.
+We then construct some useful (shell) scripts using this CLI\@.
+These scripts automates the reporting of results from Canvas to LADOK\@.

{ladok3-4.19 → ladok3-5.1}/doc/ladok3.tex

@@ -46,10 +46,10 @@ higher education in Sweden.
 This is the documented source code of \texttt{ladok3}, a LADOK3 API wrapper for 
 Python.
 
-The \texttt{ladok3} library provides a non-GUI application that, similar to 
-access via a web browser, only provides the user with access to the LADOK data 
-and functionality that they would actually have based on their specific user 
-permissions in LADOK.
+The \texttt{ladok3} library provides a non-GUI application (a command-line 
+interface, CLI) that, similar to access via a web browser, only provides the 
+user with access to the LADOK data and functionality that they would actually 
+have based on their specific user permissions in LADOK.
 It can be seem as a very streamlined web browser just for LADOK's web 
 interface.
 While the library exploits caching to reduce the load on the LADOK server, this 
@@ -58,15 +58,27 @@ LADOK's web GUI export functions.
 
 You can install the \texttt{ladok3} package by running
 \begin{minted}{bash}
-pip3 install ladok3
+python3 -m pip install ladok3 # to use it in Python, or
+pipx install ladok3           # to just use the CLI
 \end{minted}
 in the terminal.
-You can find a quick reference by running
+
+Then you can use the CLI by running \mintinline{bash}{ladok} in the terminal.
+The command has built-in help, simply run \mintinline{bash}{ladok -h} to see 
+the available commands.
+However, the first thing you want to run after installing the package is
 \begin{minted}[firstnumber=last]{bash}
-pydoc ladok3
+ladok login
 \end{minted}
+This will set up your credentials for the CLI.
+However, if you want to use the library in a script, you can read
+\begin{minted}[firstnumber=last]{bash}
+ladok login -h
+\end{minted}
+for alternative ways of providing your credentials.
 
-We provide the main class \texttt{LadokSession} (\cref{LadokSession}).
+For use in Python scripts,
+we provide the main class \texttt{LadokSession} (\cref{LadokSession}).
 The \texttt{LadokSession} class acts like \enquote{factories} and will return 
 objects representing various LADOK data.
 These data objects' classes inherit the \texttt{LadokData} (\cref{LadokData}) 
@@ -83,27 +95,55 @@ We do this by caching all factory methods of any \texttt{LadokSession}.
 The \texttt{LadokSession} itself is also designed to be cacheable: if the session to 
 LADOK expires, it will automatically reauthenticate to establish a new session.
 
+You can find a quick reference by running
+\begin{minted}[firstnumber=last]{bash}
+pydoc ladok3 # doesn't work if installed with pipx
+\end{minted}
 
 
-\part{The library}
 
-\input{../src/ladok3/ladok3.tex}
+\part{Example applications}
 
+\chapter{Transfer results from Canvas to LADOK}\label{SomeScripts}
 
-\part{API calls}
+\input{../src/ladok3/scripts.tex}
 
-\input{../src/ladok3/api.tex}
-\input{../src/ladok3/undoc.tex}
+\chapter{Transfer results from Canvas to LADOK in Python}
+
+Here we provide an example program~\texttt{canvas2ladok.py} which exports 
+results from Canvas to LADOK for the introductory programming course~prgi 
+(DD1315).
+
+However, a better way to do this is by using the CLI
+(see \cref{SomeScripts} for an even better version):
+\begin{minted}{bash}
+#!/bin/bash
 
+. ${HOME}/.profile
 
+year=22
+courses="DD13(10HT${year}|17HT${year})"
+components="(LAB[123]|MAT1|KAL1)"
 
-\part{A command-line interface}
+canvaslms results -c "$courses" -A "$components" \
+| sed -E "s/ ?[HV]T[0-9]{2}( \(.*\))?//" \
+| ladok report -fv
+\end{minted}
+
+But now we'll have a look at how we can do this (well, a simpler version) in 
+Python.
+
+
+\input{../examples/canvas2ladok.tex}
+
+
+\part{The command-line interface}
 
 \chapter{The base interface}
 
 \input{../src/ladok3/cli.tex}
 
-\chapter{The \texttt{data} command}
+\chapter{The \texttt{course} command}
 
 \input{../src/ladok3/data.tex}
 
@@ -117,19 +157,16 @@ LADOK expires, it will automatically reauthenticate to establish a new session.
 
 
 
-\part{Other example applications}
+\part{The Python library}
+
+\input{../src/ladok3/ladok3.tex}
 
-\chapter{Transfer results from KTH Canvas to LADOK}
 
-Here we provide an example program~\texttt{canvas2ladok.py} which exports 
-results from KTH Canvas to LADOK for the introductory programming course~prgi 
-(DD1315).
-You can find an up-to-date version of this chapter at
-\begin{center}
-  \url{https://github.com/dbosk/intropy/tree/master/adm/reporting}.
-\end{center}
+\part{API calls}
+
+\input{../src/ladok3/api.tex}
+\input{../src/ladok3/undoc.tex}
 
-\input{../examples/canvas2ladok.tex}
 
 
 \backmatter

{ladok3-4.19 → ladok3-5.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "ladok3"
-version = "4.19"
+version = "5.1"
 description = "Python wrapper and CLI for the LADOK3 REST API."
 authors = [
   "Daniel Bosk <dbosk@kth.se>",

{ladok3-4.19 → ladok3-5.1}/src/ladok3/.gitignore

@@ -8,3 +8,4 @@ prgi.py
 prgi.tex
 ladok.bash
 test.bash
+ladok.sh

{ladok3-4.19 → ladok3-5.1}/src/ladok3/Makefile

@@ -1,9 +1,11 @@
 LIB=	ladok3.nw api.nw undoc.nw
 CLI=	cli.nw data.nw report.nw student.nw
+SCRIPTS=$(shell noroots scripts.nw | sed -E "s/(<<|>>)//g")
 
 .PHONY: all
 all: ${LIB:.nw=.tex} __init__.py
 all: ${CLI:.nw=.tex} ${CLI:.nw=.py} ladok.bash
+all: scripts.tex ${SCRIPTS}
 
 __init__.py: ladok3.py
 	mv $^ $@
@@ -13,6 +15,9 @@ ladok3.py: ${LIB}
 ladok.bash: __init__.py ${CLI:.nw=.py}
 	register-python-argcomplete ladok > $@
 
+${SCRIPTS}: scripts.nw
+	${NOTANGLE.sh}
+
 
 .PHONY: clean
 clean:
@@ -20,6 +25,7 @@ clean:
 	${RM} ${LIB:.nw=.tex}
 	${RM} ${CLI:.nw=.tex}
 	${RM} ${CLI:.nw=.py} ladok.bash
+	${RM} scripts.tex ${SCRIPTS}
 
 .PHONY: distclean
 distclean:

{ladok3-4.19 → ladok3-5.1}/src/ladok3/data.nw

@@ -16,7 +16,7 @@ from LADOK (\cref{DataCommand}).
 This is a subcommand for the [[ladok]] command-line interface.
 It can be used like this:
 \begin{minted}{bash}
-ladok data DD1315 > DD1315.csv
+ladok course DD1315 > DD1315.csv
 \end{minted}
 This program will produce CSV-formated data to answer the questions above.
 The data is formated like this:
@@ -26,11 +26,11 @@ The data is formated like this:
 \item component,
 \item student (pseudonym),
 \item grade,
-\item normalized time.
+\item either absolute date or normalized to the course start and finish.
 \end{itemize}
 
 
-\section{The [[data]] subcommand}\label{DataCommand}
+\section{The [[course]] subcommand}\label{DataCommand}
 
 This is a subcommand run as part of the [[ladok3.cli]] module.
 We provide a function [[add_command_options]] that adds the subcommand options 
@@ -59,7 +59,7 @@ def command(ladok, args):
 We add a subparser.
 We set it up to use the function [[command]].
 <<add data parser to parser>>=
-data_parser = parser.add_parser("data",
+data_parser = parser.add_parser("course",
   help="Returns course results data in CSV form",
   description="""
 Returns the results in CSV form for all first-time registered students.
@@ -79,9 +79,10 @@ course_rounds = filter_rounds(
   ladok.search_course_rounds(code=args.course_code),
   args.rounds)
 
-data_writer.writerow([
-  "Course", "Round", "Component", "Student", "Grade", "Time"
-])
+if args.header:
+  data_writer.writerow([
+    "Course", "Round", "Component", "Student", "Grade", "Time"
+  ])
 for course_round in course_rounds:
   data = extract_data_for_round(ladok, course_round, args)
 
@@ -91,6 +92,7 @@ for course_round in course_rounds:
         student, grade, time]
     )
 @ We must take a course code and a delimiter as arguments.
+We also want to know if we want a header or not.
 <<add data command arguments to data parser>>=
 data_parser.add_argument("course_code",
   help="The course code of the course for which to export data")
@@ -100,6 +102,9 @@ data_parser.add_argument("-d", "--delimiter",
   help="The delimiter for the CSV output; "
     "default is a tab character to be compatible with POSIX commands, "
     "use `-d,` or `-d ,` to get comma-separated values.")
+
+data_parser.add_argument("-H", "--header", action="store_true",
+                         help="Print a header line with the column names.")
 @
 
 We filter the rounds.
@@ -154,7 +159,20 @@ def extract_data_for_round(ladok, course_round, args):
       else:
         <<extract grade and normalized date from result data>>
 
-      yield student, component, grade, normalized_date
+      <<yield [[student, component, grade]] and date>>
+@
+
+We want to yield the data in CSV form, so we simply yield a tuple.
+The date is either the normalized date or the date from the result data.
+<<yield [[student, component, grade]] and date>>=
+if args.normalize_date:
+  yield student, component, grade, normalized_date
+elif result_data:
+  yield student, component, grade, result_data["Examinationsdatum"]
+<<add data command arguments to data parser>>=
+data_parser.add_argument("-n", "--normalize-date", action="store_true",
+                         help="Normalize the date to the start of the course, "
+                              "otherwise the date is printed as is.")
 @
 
 \subsection{Get round data}

{ladok3-4.19 → ladok3-5.1}/src/ladok3/report.nw

@@ -115,11 +115,24 @@ try:
   set_grade(ladok, args,
             student_id, course_code, component_code, grade, date, graders)
 except Exception as err:
-  print(f"{course_code} {component_code}={grade} ({date}) {student_id}: "
+  <<try to resolve [[student]] from [[ladok]] using [[student_id]]>>
+  print(f"{course_code} {component_code}={grade} ({date}) {student}: "
         f"{err}",
         file=sys.stderr)
 @
 
+The reason we want to resolve the student from LADOK is that the [[student_id]] 
+might be a personnummer or a LADOK ID---if the latter, it's not particularly 
+readable for a human and we can't use the LADOK ID in the LADOK web interface 
+when we want to deal with the errors manually.
+But if we resolve the student, then we get a readable name.
+<<try to resolve [[student]] from [[ladok]] using [[student_id]]>>=
+try:
+  student = ladok.get_student(student_id)
+except Exception:
+  student = student_id
+@
+
 When we set the grade, there are a few cases that should be handled.
 If the grade isn't attested, we try to change it.
 (This might still fail if the grade is finalized but not attested.)
@@ -254,8 +267,10 @@ try:
             args.student_id, args.course_code, args.component_code,
             args.grade, args.date, args.graders)
 except Exception as err:
+  student_id = args.student_id
+  <<try to resolve [[student]] from [[ladok]] using [[student_id]]>>
   print(f"{args.course_code} {args.component_code}={args.grade} ({args.date}) "
-        f"{args.student_id}: {err}",
+        f"{student}: {err}",
         file=sys.stderr)
 @
 

ladok3-5.1/src/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-4.19/doc/abstract.tex

@@ -1,3 +0,0 @@
-We provide a Python wrapper for the LADOK3 REST API\@.
-We provide a useful object-oriented framework and direct API calls that return 
-the unprocessed JSON data from LADOK.